@telnyx/agent-harness 0.1.0-beta.0

package/README.md

@@ -0,0 +1,179 @@
+# Telnyx Agent Harness
+
+`@telnyx/agent-harness` is a beta package for composing bounded AI SDK turns with
+portable host ports in a Node-hosted actor runtime. It does not support browser
+execution. The Node-only test adapter is intentionally isolated to a subpath.
+
+## Beta and release gate
+
+This source change does not publish a package. The planned initial release is
+`0.1.0-beta.0` under the `beta` tag. The package remains `UNLICENSED`; an owner
+must approve npm organization/package ownership, distribution terms, and trusted
+publisher bootstrap before the main-only publication workflow is dispatched. A
+registry-installed `@telnyx/edge-runtime@0.15.2` is required: the runtime
+adapter uses its `./internal` `getAgentHarnessHost` and
+`getAgentHarnessAuthorizationProvider` seams. Source validation is not evidence
+that the beta is published or live; see `docs/agent-harness/beta-release.md` for
+fresh preflight, publication, and rollback gates.
+
+## Installation
+
+```bash
+npm install @telnyx/agent-harness@beta @telnyx/edge-runtime@^0.15.2
+```
+
+The package requires Node 22.13 or newer.
+
+## Exports
+
+```ts
+import { createHarness } from "@telnyx/agent-harness";
+import { createNodeAgentHarnessPorts } from "@telnyx/agent-harness/node";
+import {
+  AGENT_HARNESS_PORTS_VERSION,
+  defineAgentHarnessPortsContract,
+} from "@telnyx/agent-harness/contract";
+```
+
+- `@telnyx/agent-harness` exports portable ports, `createHarness`, and the
+  trusted runtime adapter. It does not export the Node adapter.
+- `@telnyx/agent-harness/node` exports `createNodeAgentHarnessPorts()` for
+  deterministic Node tests. Its in-memory state is available across
+  `reopen()` only within the current process; it is not a production durability
+  host.
+- `@telnyx/agent-harness/contract` exports the executable Vitest host-adapter
+  contract and `AGENT_HARNESS_PORTS_VERSION` (`2`). Root-only consumers do not
+  install Vitest. Contract consumers must add Vitest to their own test
+  environment.
+
+## Bounded turn example
+
+```ts
+import { createHarness } from "@telnyx/agent-harness";
+
+const harness = createHarness({
+  ports,
+  model,
+  limits: { steps: 4 },
+  tools: {},
+});
+
+const result = await harness.turn("Summarize this input");
+console.log(result.text);
+```
+
+A harness captures its ports, model, instructions, and tool map at construction.
+Each completed model step is committed before callbacks run. This beta does not
+claim exactly-once external effects or crash recovery; production durability,
+concurrency ownership, and provider configuration remain responsibilities of
+the selected host.
+
+## Scheduling dispatch and recovery lifecycle
+
+`createHarnessWithScheduling` constructs a durable harness with bounded
+scheduling tools (`schedule`, `list_schedules`, `cancel_schedule`) and a unified
+`dispatch` + `recover` surface that handles both scheduler and harness tasks.
+
+### Construction
+
+```ts
+import { createHarnessWithScheduling } from "@telnyx/agent-harness";
+
+const { harness, scheduling } = createHarnessWithScheduling({
+  ports,
+  model,
+  limits: { steps: 8 },
+  tools: {},
+});
+
+// harness extends Harness: accept, get, cancel, recover, run, dispatch, turn,
+//   approvals, list, status — all the durable run-ledger surfaces.
+// scheduling exposes: schedule, listSchedules, cancelSchedule, dispatch, recover.
+```
+
+The returned `harness.dispatch` and `harness.recover` are **unified** entry
+points that route both scheduler and harness tasks through the same durable
+ownership checks. Call them from the host task handler.
+
+### Task delivery (dispatch)
+
+The host receives tasks from the durable task queue and must route them through
+`harness.dispatch(task)`. Dispatch validates the private harness envelope and
+routes:
+
+1. Scheduler tasks (`__telnyx_agent_harness_schedule`) → scheduling admission
+   (creates a run occurrence for the scheduled prompt).
+2. Harness run tasks (`__telnyx_agent_harness_run`) → `harness.run(runId)`.
+3. Approval resume tasks (`__telnyx_agent_harness_approval_resume`) →
+   `harness.run(runId, batch)` with a deterministic batch fence.
+
+Required ordering: the host must call `harness.dispatch(task)` for every task it
+receives. Dispatch is idempotent for already-completed or already-admitted runs.
+
+### Recovery after restart (recover)
+
+On actor restart, the host must call `harness.recover()` **before** processing
+new tasks. Recovery:
+
+1. Marks uncertain interrupted runs (effect started but not committed) as
+   `outcome_unknown` — at-least-once delivery, never exactly-once.
+2. Re-enqueues accepted and `resume_pending` runs for re-execution.
+3. Expires approvals whose `expiresAt` has passed.
+4. Reconciles schedule occurrences with committed run admissions (repairs the
+   occurrence → run correlation for runs that committed before the occurrence
+   was updated).
+5. Re-arms active interval schedules and cancels stale scheduled tasks.
+
+```ts
+// On actor startup:
+await harness.recover();
+// Then process queued tasks:
+for (const task of await ports.tasks.list()) {
+  await harness.dispatch(task);
+}
+```
+
+### Fresh actor
+
+A fresh actor with no prior state starts empty. `accept(input, { key })`
+admits a run with an idempotency key. The first call queues a task; a second
+call with the same key returns the existing run (duplicate: true) without
+re-queuing.
+
+### Restart behavior
+
+After a process restart, `recover()` re-enqueues all non-terminal runs. A run
+that was `running` when the process stopped is reset to `accepted` and
+re-queued. A run that was `awaiting_approval` or `resume_pending` is
+re-evaluated: if its approvals are still valid, it is re-queued for resumption;
+if an approval expired, the run fails with `HARNESS_APPROVAL_EXPIRED`.
+
+### Duplicate delivery
+
+Duplicate task delivery is safe: `dispatch` checks the durable run status
+before claiming. An already-completed or already-canceled run is returned
+without re-execution. A run that is already `running` (claimed by the current
+activation) is returned without re-claiming.
+
+### Failed run behavior
+
+A run that fails with a safe failure code (`HARNESS_PROVIDER_ERROR`,
+`HARNESS_STEP_LIMIT`, `HARNESS_CANCELLED`, etc.) is marked `failed` with that
+code. A run whose failure left an effect in an uncertain state (effect started
+but not committed) is marked `outcome_unknown`. The host can retry or inspect
+these runs; recovery does not automatically retry `outcome_unknown` runs.
+
+### Idempotency and occurrence bookkeeping
+
+Schedule occurrences are tracked per `(schedule_id, scheduled_for)` pair. An
+occurrence starts as `pending`, transitions to `admitted` when a run is
+accepted, and records the run's journal sequence after completion. This
+makes the occurrence → run → journal relationship recoverable without
+inferring from actor-global history.
+
+## Validation
+
+Package development and release preparation are validated with the repository's
+lint, test, build, clean-consumer, and registry-SDK preflight gates. The
+clean-consumer gate installs the packed package outside the monorepo and checks
+the root, `./node`, and `./contract` exports without private workspace masking.

package/dist/approvals.d.ts

@@ -0,0 +1,140 @@
+import type { JSONValue } from "ai";
+import type { AgentHarnessAuthorizationIdentity, AgentHarnessPorts } from "./ports.js";
+export declare const HARNESS_APPROVAL_STATUSES: readonly ["pending", "granted", "denied", "expired", "consumed"];
+export type HarnessApprovalStatus = (typeof HARNESS_APPROVAL_STATUSES)[number];
+export declare class HarnessAuthorizationError extends Error {
+    readonly code: "identity_unavailable" | "unauthenticated" | "forbidden" | "policy_unavailable";
+    constructor(code: "identity_unavailable" | "unauthenticated" | "forbidden" | "policy_unavailable");
+}
+export declare class HarnessApprovalError extends Error {
+    readonly code: "expired" | "replayed" | "conflicting" | "consumed" | "missing";
+    constructor(code: "expired" | "replayed" | "conflicting" | "consumed" | "missing");
+}
+export interface HarnessApprovalRequest {
+    /** Pinned AI SDK approval id when the request originated from a native approval part. */
+    readonly id?: string;
+    readonly runId: string;
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly arguments: unknown;
+    readonly requiredAction: string;
+    readonly expiresAt: number;
+}
+export interface HarnessApproval {
+    readonly id: string;
+    readonly runId: string;
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly arguments: JSONValue;
+    readonly requiredAction: string;
+    readonly authorization: AgentHarnessAuthorizationIdentity;
+    readonly status: HarnessApprovalStatus;
+    readonly expiresAt: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+export interface HarnessApprovalAudit {
+    readonly event: string;
+    /** Fixed operation class; excludes approval inputs and credentials. */
+    readonly action: string;
+    /** Fixed outcome class; excludes provider and policy response bodies. */
+    readonly outcome: string;
+    readonly at: number;
+}
+export interface HarnessApprovalLedger {
+    inspect(id: string): Promise<HarnessApproval>;
+    grant(id: string): Promise<HarnessApproval>;
+    deny(id: string): Promise<HarnessApproval>;
+}
+interface HarnessApprovalExecutionLedger extends HarnessApprovalLedger {
+    /** Private execution seam; never exposed through createHarness().approvals. */
+    request(request: HarnessApprovalRequest): Promise<Readonly<{
+        id: string;
+        status: "pending";
+    }>>;
+    /** Private audit seam; host callers receive no raw journal/audit surface. */
+    audit(id: string): Promise<readonly HarnessApprovalAudit[]>;
+    /** Private deterministic recovery seam; never exposed to host callers. */
+    inspectUnchecked(id: string): Promise<HarnessApproval | undefined>;
+    /** Private harness seam: reauthorizes one granted effect without consuming it. */
+    reauthorizeEffect(runId: string, toolCallId: string | undefined, toolName: string, input: unknown): Promise<Readonly<{
+        id: string;
+        input: JSONValue;
+    }> | undefined>;
+    /** Private synchronous seam: consumes a reauthorized grant inside the effect-start transaction. */
+    consumeAuthorizedEffect(runId: string, approvalId: string | undefined): void;
+    /** Runs the approval record and private continuation callback in one SQL transaction. */
+    requestWithPause(request: HarnessApprovalRequest, pause: () => void): Promise<Readonly<{
+        id: string;
+        status: "pending";
+    }>>;
+    /** Persists a validated step-wide approval batch and one continuation transition atomically. */
+    requestBatchWithPause(requests: readonly HarnessApprovalRequest[], pause: (created: readonly Readonly<{
+        id: string;
+        status: "pending";
+    }>[]) => void): Promise<readonly Readonly<{
+        id: string;
+        status: "pending";
+    }>[]>;
+    /** Records a grant and resumes only after the whole batch has durable granted responses. */
+    grantWithResume(id: string, decide: (approval: HarnessApproval) => void, resume: (approval: HarnessApproval) => void): Promise<HarnessApproval>;
+    /** Runs the denied decision and private terminalization callback in one SQL transaction. */
+    denyWithCancel(id: string, cancel: (approval: HarnessApproval) => void): Promise<HarnessApproval>;
+}
+export declare function createHarnessApprovalLedger(ports: AgentHarnessPorts): HarnessApprovalLedger;
+export declare function createHarnessApprovalExecutionLedger(ports: AgentHarnessPorts): HarnessApprovalExecutionLedger;
+export interface HarnessApprovalMessageRequest {
+    readonly runId: string;
+    readonly approvalId: string;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly journalSeq: number;
+    /** Durable message sequence immediately preceding this private envelope. */
+    readonly afterMessageSeq: number;
+    /** Durable approval batch identifier. Legacy callers default to epoch zero. */
+    readonly approvalEpoch?: number;
+    readonly signature?: string;
+    /** Private canonical execution input; never projected into AgentMessage storage. */
+    readonly canonicalToolCall: Readonly<{
+        toolCallId: string;
+        toolName: string;
+        input: unknown;
+    }>;
+}
+export interface HarnessApprovalMessageDecision {
+    readonly approvalId: string;
+    readonly approved: boolean;
+    readonly reason?: string;
+}
+interface HarnessApprovalMessageJournal {
+    /** Allocates a private per-run envelope sequence; it is unrelated to AgentMessage sequence. */
+    nextRunSequence(runId: string): number;
+    request(request: HarnessApprovalMessageRequest): Promise<void>;
+    decide(decision: HarnessApprovalMessageDecision): Promise<void>;
+    restore(runId: string, toolCallId: string, journalSeq: number): Promise<readonly unknown[]>;
+    /** Restores only completed private envelopes for one durable continuation. */
+    restoreRun(runId: string): Promise<readonly Readonly<{
+        afterMessageSeq: number;
+        journalSeq: number;
+        approvalId: string;
+        toolCall: CanonicalToolCall;
+        messages: readonly unknown[];
+    }>[]>;
+}
+interface HarnessApprovalMessageJournalExecution extends HarnessApprovalMessageJournal {
+    /** Allocates a durable per-run approval batch identifier. */
+    nextRunApprovalEpoch(runId: string): number;
+    /** Private continuation seam; runs inside the enclosing approval transaction. */
+    requestInTransaction(request: HarnessApprovalMessageRequest): void;
+    /** Private continuation seam; runs inside the enclosing approval transaction. */
+    decideInTransaction(decision: HarnessApprovalMessageDecision): void;
+}
+type CanonicalToolCall = Readonly<{
+    toolCallId: string;
+    toolName: string;
+    input: JSONValue;
+}>;
+/** Private SQL codec for the pinned AI SDK approval-message subset only. */
+export declare function createHarnessApprovalMessageJournal(ports: AgentHarnessPorts): HarnessApprovalMessageJournalExecution;
+export {};
+//# sourceMappingURL=approvals.d.ts.map