createHarnessRunLedger()

createHarnessRunLedger(ports, execute, options?): HarnessRunLedger

​

On the Agent Runtime

// 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.
• 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_.

// 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().
• 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(). The class overrides onTask() to hand it to dispatch().

​

HarnessRunLedger

accept(input, options): Promise<HarnessRunAcceptance>

cancel(runId): Promise<HarnessRun | undefined>

dispatch(task): Promise<HarnessRun | undefined>

get(runId): Promise<HarnessRun | undefined>

list(options?): Promise<readonly HarnessRun[]>

recover(): Promise<number>

run(runId): Promise<HarnessRun | undefined>

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

​

HarnessRunLedgerOptions

readonly optional checkpoints?: HarnessCheckpoint

readonly optional requireApprovalIdentity?: boolean

​

HarnessCheckpoint

HarnessCheckpoint = (point) => void

​

ensureHarnessDurabilitySchema()

ensureHarnessDurabilitySchema(ports): void

​

HarnessInjectedCrash

new HarnessInjectedCrash(cause): HarnessInjectedCrash

optional cause?: unknown

message: string

name: string

optional stack?: string

static stackTraceLimit: number

static captureStackTrace(targetObject, constructorOpt?): void

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

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();

static prepareStackTrace(err, stackTraces): any

​

HarnessApprovalPause

new HarnessApprovalPause(): HarnessApprovalPause

optional cause?: unknown

message: string

name: string

optional stack?: string

static stackTraceLimit: number

static captureStackTrace(targetObject, constructorOpt?): void

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

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();

static prepareStackTrace(err, stackTraces): any