> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript runs

> Use the current run-model resources and legacy validation helpers with the TypeScript SDK

## Canonical resources

For new integrations, prefer `client.testRuns`, `client.tests`, `client.sandboxRuns`, and `client.twinRuns`.

## Create an ad hoc test run

```typescript theme={null}
const run = await client.testRuns.create({
  prompt: 'Test the checkout flow',
  startUrl: 'https://staging.myapp.com',
  twins: ['stripe', 'slack'],   // optional
  repo: 'myorg/myrepo',         // optional
  branch: 'feature/checkout',   // optional
});

const detail = await client.testRuns.wait(run.id, { timeout: 300000 });
console.log(detail.status);
```

List, inspect, or rerun test runs:

```typescript theme={null}
const runs = await client.testRuns.list();
const detail = await client.testRuns.get('run-id');
const rerun = await client.testRuns.rerun('run-id');
```

## Create a sandbox run

```typescript theme={null}
const sandbox = await client.sandboxRuns.create({
  repo: 'myorg/myrepo',
  branch: 'feature/checkout',
  twins: ['stripe', 'slack'],
  ttlMinutes: 60,
});

const detail = await client.sandboxRuns.get(sandbox.sandboxId);
const logs = await client.sandboxRuns.logs(sandbox.sandboxId);
```

## Create a twin run

```typescript theme={null}
const result = await client.twinRuns.create({
  twins: ['stripe', 'slack'],
  ttlMinutes: 60,
  scenarioId: 'scenario-id',  // optional
});

const status = await client.twinRuns.get(result.runId);
await client.twinRuns.extend(result.runId, { ttlMinutes: 30 });
await client.twinRuns.lock(result.runId);
await client.twinRuns.teardown(result.runId);
```

## Run a saved test

```typescript theme={null}
const tests = await client.tests.list({ repoFullName: 'myorg/myrepo' });
const test = await client.tests.get('test-id');
const run = await client.tests.run('test-id', { startUrl: 'https://staging.myapp.com' });
```

## Legacy validation runs

Test a live URL with browser validation and optional digital twins.

```typescript theme={null}
const run = await client.runs.createUrlRun({
  url: 'https://staging.myapp.com',
  prompt: 'Test the checkout flow',                          // optional
  twins: ['stripe', 'slack'],                                // optional
  credentials: { email: 'test@example.com', password: 'pass' },  // optional
  runnerMode: 'visual',                                      // optional
  sessionId: 'abc-123',                                      // optional
});
// run.runId, run.status, run.sessionId
```

## Create a PR run

Validate code changes from a branch or pull request.

```typescript theme={null}
const run = await client.runs.createPrRun({
  repo: 'myorg/myrepo',
  branch: 'feature/checkout',                                // optional
  prUrl: 'https://github.com/org/repo/pull/42',              // optional
  twins: ['stripe'],                                         // optional
  contextNotes: 'Changed the payment flow',                  // optional
  scenarioPrompt: 'Customer with active subscription',       // optional
});
```

## Agent run migration

<Warning>
  The current package still exposes `client.runs.createAgentRun(...)`, but it targets the removed `/validate/agent-run` endpoint.
  Use `client.runs.createUrlRun(...)` for deployed URLs, `client.runs.createPrRun(...)` for normal PR validation, or call `POST /validate/pr-run` with `run_type: "agent_run"` when you need a sandbox-style branch run.
</Warning>

## Get run details

```typescript theme={null}
const detail = await client.runs.get('run-id');
console.log(detail.status);         // "completed", "running", "failed", etc.
console.log(detail.resultsJson);    // step results array
console.log(detail.stepSummaries);  // grouped summaries
console.log(detail.eventLogJson);   // timeline events
```

## Stream results

Stream live results via server-sent events:

```typescript theme={null}
for await (const event of client.runs.streamResults('run-id')) {
  console.log(event);
}
```

## Wait for completion

Block until the run reaches a terminal status (`completed`, `failed`, or `cancelled`):

```typescript theme={null}
const detail = await client.runs.wait('run-id', {
  pollInterval: 2500,  // ms between polls (default 2500)
  timeout: 600000,     // max ms to wait (default 600000)
});
```

## Cancel a run

```typescript theme={null}
await client.runs.cancel('run-id');
```

<Note>
  `client.runs` is the legacy namespace over `/validate/...` and `/runs/...`. New work should prefer `client.testRuns`, `client.tests`, `client.sandboxRuns`, and `client.twinRuns`.
</Note>