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

# createHarnessRunLedger()

> **createHarnessRunLedger**(`ports`, `execute`, `options?`): [`HarnessRunLedger`](/docs/agent-sdk/harness-sdk/persistence/run-ledger#harnessrunledger)

**Parameters**

| Parameter | Type |
| - | - |
| `ports` | [`AgentHarnessPorts`](/docs/agent-sdk/harness-sdk/ports) |
| `execute` | (`input`, `signal`, `steps`) => `Promise`\<`unknown`> |
| `options?` | [`HarnessRunLedgerOptions`](/docs/agent-sdk/harness-sdk/persistence/run-ledger#harnessrunledgeroptions) |

**Returns**
[`HarnessRunLedger`](/docs/agent-sdk/harness-sdk/persistence/run-ledger#harnessrunledger)

## On the Agent Runtime

The ledger records each run in the SQL port. It executes each run in a task of the tasks port.

```ts theme={null}
// run ledger (@telnyx/agent-harness)
export function ensureHarnessDurabilitySchema(ports) {
  ports.sql.transactionSync(() => {
    ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_schema (version INTEGER PRIMARY KEY)");
    // …
  });
}
```

* `ports.sql.exec()` runs on the instance's own SQLite database, [`this.ctx.storage.sql`](/docs/agent-sdk/interface/ctx).
* `ports.sql.transactionSync()` is `this.ctx.storage.transactionSync()`. The schema is created and migrated in one such transaction. A migration that throws is rolled back whole.
* The ledger's tables share the database with any table the class creates. Their names begin with `__telnyx_agent_harness_`.

```ts theme={null}
// run ledger (@telnyx/agent-harness)
const TASK_METHOD = "__telnyx_agent_harness_run";
// …
const enqueue = async (run) => {
  if (run.status !== "accepted")
    return;
  await ports.tasks.queue(TASK_METHOD, { runId: run.id }, { id: run.task_id, maxRetries: 5 });
};
// …
const admission = ports.sql.transactionSync(() => {
  // …
});
// This is intentionally outside the SQL transaction: a queue failure leaves an accepted record for recover().
await enqueue(admission.run);
```

* `accept()` queues the run's task after the run's row commits, through the class's [`queue()`](/docs/agent-sdk/interface/queue).
* The task's `id` is the run's `task_id`. Queueing the run again, as `recover()` does, leaves one pending task for it.
* `__telnyx_agent_harness_run` names no method of the class, so the task reaches [`onTask()`](/docs/agent-sdk/interface/onTask). The class overrides `onTask()` to hand it to [`dispatch()`](/docs/agent-sdk/harness-sdk/harness/dispatch).

## HarnessRunLedger

**Methods**
**accept()**

> **accept**(`input`, `options`): `Promise`\<[`HarnessRunAcceptance`](/docs/agent-sdk/harness-sdk/harness/accept#harnessrunacceptance)>

**Parameters**

| Parameter | Type |
| - | - |
| `input` | `string` |
| `options` | [`HarnessRunAcceptanceOptions`](/docs/agent-sdk/harness-sdk/harness/accept#harnessrunacceptanceoptions) |

**Returns**
`Promise`\<[`HarnessRunAcceptance`](/docs/agent-sdk/harness-sdk/harness/accept#harnessrunacceptance)>

**cancel()**

> **cancel**(`runId`): `Promise`\<[`HarnessRun`](/docs/agent-sdk/harness-sdk/harness/get#harnessrun) | `undefined`>

**Parameters**

| Parameter | Type |
| - | - |
| `runId` | `string` |

**Returns**
`Promise`\<[`HarnessRun`](/docs/agent-sdk/harness-sdk/harness/get#harnessrun) | `undefined`>

**dispatch()**

> **dispatch**(`task`): `Promise`\<[`HarnessRun`](/docs/agent-sdk/harness-sdk/harness/get#harnessrun) | `undefined`>

Execute one task emitted by `accept()` after validating its private harness envelope.

**Parameters**

| Parameter | Type |
| - | - |
| `task` | `Readonly`\<`Pick`\<`TaskRecord`, `"name"` \| `"payload"`>> |

**Returns**
`Promise`\<[`HarnessRun`](/docs/agent-sdk/harness-sdk/harness/get#harnessrun) | `undefined`>

**get()**

> **get**(`runId`): `Promise`\<[`HarnessRun`](/docs/agent-sdk/harness-sdk/harness/get#harnessrun) | `undefined`>

**Parameters**

| Parameter | Type |
| - | - |
| `runId` | `string` |

**Returns**
`Promise`\<[`HarnessRun`](/docs/agent-sdk/harness-sdk/harness/get#harnessrun) | `undefined`>

**list()**

> **list**(`options?`): `Promise`\<readonly [`HarnessRun`](/docs/agent-sdk/harness-sdk/harness/get#harnessrun)\[]>

**Parameters**

| Parameter | Type |
| - | - |
| `options?` | [`HarnessRunListOptions`](/docs/agent-sdk/harness-sdk/harness/list#harnessrunlistoptions) |

**Returns**
`Promise`\<readonly [`HarnessRun`](/docs/agent-sdk/harness-sdk/harness/get#harnessrun)\[]>

**recover()**

> **recover**(): `Promise`\<`number`>

Re-enqueue accepted and interrupted runs. Recovery is at-least-once, never exactly-once.

**Returns**
`Promise`\<`number`>

**run()**

> **run**(`runId`): `Promise`\<[`HarnessRun`](/docs/agent-sdk/harness-sdk/harness/get#harnessrun) | `undefined`>

Claim and execute an admitted run; host task handlers call this with their persistent run id.

**Parameters**

| Parameter | Type |
| - | - |
| `runId` | `string` |

**Returns**
`Promise`\<[`HarnessRun`](/docs/agent-sdk/harness-sdk/harness/get#harnessrun) | `undefined`>

**status()**

> **status**(`runId`): `Promise`\<`"accepted"` | `"running"` | `"awaiting_approval"` | `"resume_pending"` | `"completed"` | `"failed"` | `"canceled"` | `"outcome_unknown"` | `undefined`>

**Parameters**

| Parameter | Type |
| - | - |
| `runId` | `string` |

**Returns**
`Promise`\<`"accepted"` | `"running"` | `"awaiting_approval"` | `"resume_pending"` | `"completed"` | `"failed"` | `"canceled"` | `"outcome_unknown"` | `undefined`>

## HarnessRunLedgerOptions

**Properties**
**checkpoints?**

> `readonly` `optional` **checkpoints?**: [`HarnessCheckpoint`](/docs/agent-sdk/harness-sdk/persistence/run-ledger#harnesscheckpoint)

Deterministic test seam for crash-window recovery coverage.

**requireApprovalIdentity?**

> `readonly` `optional` **requireApprovalIdentity?**: `boolean`

Approval-capable harnesses bind admission to a host-attested subject.

## HarnessCheckpoint

> **HarnessCheckpoint** = (`point`) => `void`

**Parameters**

| Parameter | Type |
| - | - |
| `point` | `"before_effect"` \| `"after_effect_before_memo"` \| `"after_memo"` \| `"before_final_run_commit"` |

**Returns**
`void`

## ensureHarnessDurabilitySchema()

> **ensureHarnessDurabilitySchema**(`ports`): `void`

**Parameters**

| Parameter | Type |
| - | - |
| `ports` | [`AgentHarnessPorts`](/docs/agent-sdk/harness-sdk/ports) |

**Returns**
`void`

## HarnessInjectedCrash

Internal deterministic crash signal. It intentionally leaves persistent state at the interrupted boundary.

**Constructors**
**Constructor**

> **new HarnessInjectedCrash**(`cause`): `HarnessInjectedCrash`

**Parameters**

| Parameter | Type |
| - | - |
| `cause` | `unknown` |

**Returns**
`HarnessInjectedCrash`

**Properties**
**cause?**

> `optional` **cause?**: `unknown`

**message**

> **message**: `string`

**name**

> **name**: `string`

**stack?**

> `optional` **stack?**: `string`

**stackTraceLimit**

> `static` **stackTraceLimit**: `number`

The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).

The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured *after* the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.

**Methods**
**captureStackTrace()**

> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js theme={null}
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js theme={null}
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

**Parameters**

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |

**Returns**
`void`

**prepareStackTrace()**

> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`

**Parameters**

| Parameter | Type |
| - | - |
| `err` | `Error` |
| `stackTraces` | `CallSite`\[] |

**Returns**
`any`

**See**
[https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces)

## HarnessApprovalPause

Internal control signal: approval state was persistently recorded before pausing.

**Constructors**
**Constructor**

> **new HarnessApprovalPause**(): `HarnessApprovalPause`

**Returns**
`HarnessApprovalPause`

**Properties**
**cause?**

> `optional` **cause?**: `unknown`

**message**

> **message**: `string`

**name**

> **name**: `string`

**stack?**

> `optional` **stack?**: `string`

**stackTraceLimit**

> `static` **stackTraceLimit**: `number`

The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).

The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured *after* the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.

**Methods**
**captureStackTrace()**

> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js theme={null}
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js theme={null}
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

**Parameters**

| Parameter | Type |
| - | - |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |

**Returns**
`void`

**prepareStackTrace()**

> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`

**Parameters**

| Parameter | Type |
| - | - |
| `err` | `Error` |
| `stackTraces` | `CallSite`\[] |

**Returns**
`any`

**See**
[https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces)