@telnyx/agent-harness 0.1.0-beta.0

package/dist/channel.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Generic discrete-message channel contract.
+ *
+ * The harness never accepts provider payloads or provider-specific addressing
+ * fields. A reference adapter owns those transformations before this boundary.
+ */
+export type ChannelContent = Readonly<Record<string, unknown>>;
+export interface NormalizedChannelInbound {
+    readonly channel: string;
+    readonly externalMessageId: string;
+    readonly conversationId: string;
+    readonly receivedAt: number;
+    readonly content: ChannelContent;
+}
+export interface ChannelAcceptance {
+    readonly channel: string;
+    readonly conversationId: string;
+    readonly externalMessageId: string;
+    readonly receivedAt: number;
+    readonly content: ChannelContent;
+}
+export interface ChannelSendRequest {
+    readonly conversationId: string;
+    readonly content: ChannelContent;
+    /** Stable retry token supplied for replies that require delivery correlation. */
+    readonly idempotencyKey?: string;
+}
+export interface ChannelAdapter {
+    readonly channel: string;
+    send(request: ChannelSendRequest): Promise<{
+        providerRequestId: string;
+    }>;
+}
+export interface ChannelLedger {
+    /**
+     * Atomically claims an inbound provider message and persists its run mapping
+     * as one recovery unit. Durable implementations must share this claim across
+     * router processes and must not release a claim after `accept` succeeds.
+     */
+    acceptInbound(channel: string, externalMessageId: string, conversationId: string, accept: () => Promise<string>): Promise<Readonly<{
+        runId: string;
+        duplicate: boolean;
+    }>>;
+    findRun(runId: string): Promise<Readonly<{
+        channel: string;
+        conversationId: string;
+    }> | undefined>;
+    /**
+     * Reserves and completes one correlated outbound attempt. Implementations
+     * must retain the stable idempotency key through retries/recovery so a
+     * provider never observes an unkeyed resend after persistence uncertainty.
+     */
+    sendOutbound(channel: string, runId: string, idempotencyKey: string, send: (idempotencyKey: string) => Promise<{
+        providerRequestId: string;
+    }>): Promise<{
+        providerRequestId: string;
+    }>;
+    /** Reconciles a previous provider success without authorizing or sending again. */
+    recoverOutbound(channel: string, runId: string, idempotencyKey: string): Promise<{
+        providerRequestId: string;
+    } | undefined>;
+    findOutbound(channel: string, providerRequestId: string): Promise<string | undefined>;
+}
+export interface OutboundChannelPolicy {
+    authorize(request: Readonly<{
+        channel: string;
+        serviceAccountId: string | undefined;
+    }>): Promise<boolean>;
+}
+export declare class ChannelAuthorizationError extends Error {
+    constructor();
+}
+export interface ChannelRouterOptions {
+    readonly adapters: readonly ChannelAdapter[];
+    readonly ledger: ChannelLedger;
+    readonly policy: OutboundChannelPolicy;
+    readonly accept: (request: ChannelAcceptance) => Promise<{
+        runId: string;
+    }>;
+}
+export interface ChannelReplyRequest {
+    readonly runId: string;
+    readonly serviceAccountId?: string;
+    /** Caller-supplied stable key for this retryable reply. */
+    readonly idempotencyKey: string;
+    readonly content: ChannelContent;
+}
+export interface ChannelOutboundRequest {
+    readonly channel: string;
+    readonly conversationId: string;
+    readonly serviceAccountId?: string;
+    /** Exact harness run to correlate this out-of-band send with delivery events. */
+    readonly runId: string;
+    /** Caller-supplied stable key for this retryable out-of-band send. */
+    readonly idempotencyKey: string;
+    readonly content: ChannelContent;
+}
+export interface ChannelDeliveryEvent {
+    readonly channel: string;
+    readonly providerRequestId: string;
+    readonly status: string;
+    readonly occurredAt: number;
+}
+export declare function createChannelRouter(options: ChannelRouterOptions): Readonly<{
+    receive(inbound: NormalizedChannelInbound): Promise<{
+        runId: string;
+        duplicate: boolean;
+    }>;
+    reply(request: ChannelReplyRequest): Promise<{
+        providerRequestId: string;
+    }>;
+    send(request: ChannelOutboundRequest): Promise<{
+        providerRequestId: string;
+    }>;
+    delivery(event: ChannelDeliveryEvent): Promise<{
+        runId: string;
+    } | undefined>;
+}>;
+export interface InMemoryChannelLedgerOptions {
+    /** Test-only fault injection for recovery-path verification. */
+    readonly failAfterInboundAcceptOnce?: boolean;
+    /** Test-only fault injection for recovery-path verification. */
+    readonly failAfterOutboundSendOnce?: boolean;
+}
+/** Deterministic ledger test double; production wiring must provide durable storage. */
+export declare class InMemoryChannelLedger implements ChannelLedger {
+    private readonly inbound;
+    private readonly inboundClaims;
+    private readonly pendingInbound;
+    private readonly runs;
+    private readonly outbound;
+    private readonly outboundAttempts;
+    private readonly pendingOutbound;
+    private failAfterInboundAcceptOnce;
+    private failAfterOutboundSendOnce;
+    constructor(options?: InMemoryChannelLedgerOptions);
+    acceptInbound(channel: string, externalMessageId: string, conversationId: string, accept: () => Promise<string>): Promise<Readonly<{
+        runId: string;
+        duplicate: boolean;
+    }>>;
+    findRun(runId: string): Promise<Readonly<{
+        channel: string;
+        conversationId: string;
+    }> | undefined>;
+    sendOutbound(channel: string, runId: string, idempotencyKey: string, send: (idempotencyKey: string) => Promise<{
+        providerRequestId: string;
+    }>): Promise<{
+        providerRequestId: string;
+    }>;
+    recoverOutbound(channel: string, runId: string, idempotencyKey: string): Promise<{
+        providerRequestId: string;
+    } | undefined>;
+    findOutbound(channel: string, providerRequestId: string): Promise<string | undefined>;
+}
+export interface SmsReferenceAdapterOptions {
+    readonly send: (request: ChannelSendRequest) => Promise<{
+        providerRequestId: string;
+    }>;
+}
+/**
+ * Hermetic reference adapter for SMS-shaped webhooks. It does not call a live
+ * provider; transport wiring is deliberately injected by the caller.
+ */
+export declare class SmsReferenceAdapter implements ChannelAdapter {
+    private readonly options;
+    readonly channel = "sms";
+    constructor(options: SmsReferenceAdapterOptions);
+    normalizeWebhook(webhook: Readonly<{
+        messageId: string;
+        conversationId: string;
+        text: string;
+        receivedAt: number;
+    }>): NormalizedChannelInbound;
+    send(request: ChannelSendRequest): Promise<{
+        providerRequestId: string;
+    }>;
+}
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.js

@@ -0,0 +1,184 @@
+export class ChannelAuthorizationError extends Error {
+    constructor() {
+        super("outbound channel send requires an authorized Service Account");
+        this.name = "ChannelAuthorizationError";
+    }
+}
+function adapterByChannel(adapters, channel) {
+    const adapter = adapters.get(channel);
+    if (!adapter)
+        throw new Error(`unsupported channel: ${channel}`);
+    return adapter;
+}
+function ledgerKey(...values) {
+    return JSON.stringify(values);
+}
+function requireIdempotencyKey(idempotencyKey) {
+    if (!idempotencyKey.trim())
+        throw new Error("idempotency key must not be blank");
+}
+export function createChannelRouter(options) {
+    const adapters = new Map(options.adapters.map((adapter) => [adapter.channel, adapter]));
+    const send = async (request, runId, idempotencyKey) => {
+        requireIdempotencyKey(idempotencyKey);
+        const recovered = await options.ledger.recoverOutbound(request.channel, runId, idempotencyKey);
+        if (recovered)
+            return recovered;
+        if (!request.serviceAccountId?.trim()) {
+            throw new ChannelAuthorizationError();
+        }
+        if (!(await options.policy.authorize({
+            channel: request.channel,
+            serviceAccountId: request.serviceAccountId,
+        }))) {
+            throw new ChannelAuthorizationError();
+        }
+        const adapter = adapterByChannel(adapters, request.channel);
+        return options.ledger.sendOutbound(request.channel, runId, idempotencyKey, (stableKey) => adapter.send({
+            conversationId: request.conversationId,
+            content: request.content,
+            idempotencyKey: stableKey,
+        }));
+    };
+    return Object.freeze({
+        receive: async (inbound) => {
+            adapterByChannel(adapters, inbound.channel);
+            return options.ledger.acceptInbound(inbound.channel, inbound.externalMessageId, inbound.conversationId, async () => {
+                const result = await options.accept({
+                    channel: inbound.channel,
+                    conversationId: inbound.conversationId,
+                    externalMessageId: inbound.externalMessageId,
+                    receivedAt: inbound.receivedAt,
+                    content: inbound.content,
+                });
+                return result.runId;
+            });
+        },
+        reply: async (request) => {
+            const run = await options.ledger.findRun(request.runId);
+            if (!run)
+                throw new Error(`unknown channel run: ${request.runId}`);
+            return send({ ...run, serviceAccountId: request.serviceAccountId, runId: request.runId, idempotencyKey: request.idempotencyKey, content: request.content }, request.runId, request.idempotencyKey);
+        },
+        send: async (request) => send(request, request.runId, request.idempotencyKey),
+        delivery: async (event) => {
+            adapterByChannel(adapters, event.channel);
+            const runId = await options.ledger.findOutbound(event.channel, event.providerRequestId);
+            return runId === undefined ? undefined : { runId };
+        },
+    });
+}
+/** Deterministic ledger test double; production wiring must provide durable storage. */
+export class InMemoryChannelLedger {
+    inbound = new Map();
+    inboundClaims = new Map();
+    pendingInbound = new Map();
+    runs = new Map();
+    outbound = new Map();
+    outboundAttempts = new Map();
+    pendingOutbound = new Map();
+    failAfterInboundAcceptOnce;
+    failAfterOutboundSendOnce;
+    constructor(options = {}) {
+        this.failAfterInboundAcceptOnce = options.failAfterInboundAcceptOnce ?? false;
+        this.failAfterOutboundSendOnce = options.failAfterOutboundSendOnce ?? false;
+    }
+    async acceptInbound(channel, externalMessageId, conversationId, accept) {
+        const key = ledgerKey(channel, conversationId, externalMessageId);
+        const existing = this.inbound.get(key);
+        if (existing)
+            return { runId: existing, duplicate: true };
+        const pending = this.pendingInbound.get(key);
+        if (pending) {
+            this.pendingInbound.delete(key);
+            this.inbound.set(key, pending.runId);
+            this.runs.set(pending.runId, { channel: pending.channel, conversationId: pending.conversationId });
+            return { runId: pending.runId, duplicate: true };
+        }
+        const inFlight = this.inboundClaims.get(key);
+        if (inFlight)
+            return { runId: await inFlight, duplicate: true };
+        const claimed = (async () => {
+            const runId = await accept();
+            if (this.failAfterInboundAcceptOnce) {
+                this.failAfterInboundAcceptOnce = false;
+                this.pendingInbound.set(key, { runId, channel, conversationId });
+                throw new Error("inbound run mapping failed");
+            }
+            this.inbound.set(key, runId);
+            this.runs.set(runId, { channel, conversationId });
+            return runId;
+        })();
+        this.inboundClaims.set(key, claimed);
+        try {
+            return { runId: await claimed, duplicate: false };
+        }
+        finally {
+            this.inboundClaims.delete(key);
+        }
+    }
+    async findRun(runId) {
+        return this.runs.get(runId);
+    }
+    async sendOutbound(channel, runId, idempotencyKey, send) {
+        const attemptKey = ledgerKey(channel, runId, idempotencyKey);
+        const existing = this.outboundAttempts.get(attemptKey);
+        if (existing)
+            return existing;
+        const attempt = (async () => {
+            const result = await send(attemptKey);
+            if (this.failAfterOutboundSendOnce) {
+                this.failAfterOutboundSendOnce = false;
+                this.pendingOutbound.set(attemptKey, { channel, runId, result });
+                throw new Error("outbound persistence failed");
+            }
+            this.outbound.set(ledgerKey(channel, result.providerRequestId), runId);
+            return result;
+        })();
+        this.outboundAttempts.set(attemptKey, attempt);
+        try {
+            return await attempt;
+        }
+        catch (error) {
+            this.outboundAttempts.delete(attemptKey);
+            throw error;
+        }
+    }
+    async recoverOutbound(channel, runId, idempotencyKey) {
+        const attemptKey = ledgerKey(channel, runId, idempotencyKey);
+        const pending = this.pendingOutbound.get(attemptKey);
+        if (!pending)
+            return undefined;
+        this.pendingOutbound.delete(attemptKey);
+        this.outbound.set(ledgerKey(channel, pending.result.providerRequestId), runId);
+        this.outboundAttempts.set(attemptKey, Promise.resolve(pending.result));
+        return pending.result;
+    }
+    async findOutbound(channel, providerRequestId) {
+        return this.outbound.get(ledgerKey(channel, providerRequestId));
+    }
+}
+/**
+ * Hermetic reference adapter for SMS-shaped webhooks. It does not call a live
+ * provider; transport wiring is deliberately injected by the caller.
+ */
+export class SmsReferenceAdapter {
+    options;
+    channel = "sms";
+    constructor(options) {
+        this.options = options;
+    }
+    normalizeWebhook(webhook) {
+        return {
+            channel: this.channel,
+            externalMessageId: webhook.messageId,
+            conversationId: webhook.conversationId,
+            receivedAt: webhook.receivedAt,
+            content: { text: webhook.text },
+        };
+    }
+    send(request) {
+        return this.options.send(request);
+    }
+}
+//# sourceMappingURL=channel.js.map

package/dist/contract.d.ts

@@ -0,0 +1,50 @@
+import { type AgentHarnessPorts } from "./ports.js";
+export { AGENT_HARNESS_PORTS_VERSION } from "./ports.js";
+/** A fresh adapter fixture consumed by the shared ports contract suite. */
+export interface AgentHarnessPortsContractFixture {
+    /** Adapter under test. */
+    ports: AgentHarnessPorts<TestState>;
+    /** Test-host control for exercising current due-task delivery and retry. */
+    delivery: {
+        failNext(count?: number): void;
+        advanceBy(milliseconds: number): void;
+        drainDue(): Promise<number>;
+        /** Exercise a task handler that cancels its own recurring id, then throws. */
+        selfCancelAndThrow(): Promise<number>;
+        /** Exercise a task handler that re-arms its own id, then throws. */
+        selfReplaceAndThrow(): Promise<number>;
+        calls(): readonly string[];
+    };
+    /** Test-host control for exercising post-commit state-hook failures. */
+    stateHook: {
+        failNext(count?: number): void;
+        calls(): readonly Readonly<{
+            next: TestState;
+            prev: TestState;
+        }>[];
+    };
+    /** Reconstruct an adapter over the same durable backing. */
+    reopen(): Promise<AgentHarnessPorts<TestState>> | AgentHarnessPorts<TestState>;
+    /** Construct a distinct wrapper for the current live activation. */
+    rewrapLive(): AgentHarnessPorts<TestState>;
+    /** Release fixture-owned resources. */
+    close(): Promise<void> | void;
+}
+/** Factory used by {@link defineAgentHarnessPortsContract}. */
+export type AgentHarnessPortsContractFactory = () => Promise<AgentHarnessPortsContractFixture> | AgentHarnessPortsContractFixture;
+interface TestState extends Record<string, unknown> {
+    nested: {
+        keep?: boolean;
+        added?: string;
+    };
+    remove?: string;
+    replacement?: boolean;
+}
+/**
+ * Register the executable v2 ports contract against an adapter factory.
+ *
+ * Runtime and plain-Node adapters call this same function; adapter-specific
+ * tests may add stricter checks, but may not weaken these shared semantics.
+ */
+export declare function defineAgentHarnessPortsContract(label: string, factory: AgentHarnessPortsContractFactory): void;
+//# sourceMappingURL=contract.d.ts.map