@telnyx/agent-harness 0.1.0-beta.0

package/dist/ports.d.ts

@@ -0,0 +1,99 @@
+import type { AgentMessage, MergePatch, ScheduleOptions, SqlBindValue, SqlCursor, SqlValue, StoredEvent, StoredMessage, TaskRecord } from "@telnyx/edge-runtime/internal";
+/** Exact major contract implemented by every COMPUTE-705 adapter. */
+export declare const AGENT_HARNESS_PORTS_VERSION: 2;
+/** Stable identity asserted by the host, never accepted from a harness input. */
+export interface AgentHarnessIdentity {
+    readonly id: string;
+}
+/** Host clock used by queue and schedule operations. */
+export interface AgentHarnessClock {
+    now(): number;
+}
+/** Gateway-attested Service Account identity. It is never caller or tool supplied. */
+export interface AgentHarnessAuthorizationIdentity {
+    readonly serviceAccountId: string;
+    readonly organizationId: string;
+}
+/** Versioned private authorization capability required for approval decisions. */
+export interface HarnessAuthorizationPort {
+    identity(): AgentHarnessAuthorizationIdentity | undefined;
+    authorize(request: Readonly<{
+        identity: AgentHarnessAuthorizationIdentity;
+        action: string;
+        resource: string;
+        runId: string;
+        approvalId: string;
+    }>): Promise<Readonly<{
+        kind: "allow" | "deny" | "unavailable";
+    }>>;
+}
+/** Existing Agent message-log semantics, without framework conversion helpers. */
+export interface AgentHarnessMessagePort {
+    append(message: AgentMessage): Promise<number>;
+    appendMany(messages: AgentMessage[]): Promise<number>;
+    all(): Promise<StoredMessage[]>;
+    last(): Promise<StoredMessage | undefined>;
+    last(count: number): Promise<StoredMessage[]>;
+    count(): Promise<number>;
+}
+/**
+ * Existing durable Agent state semantics.
+ *
+ * `merge()` and `replace()` include the Agent's post-commit state-change hook.
+ * They may therefore reject after the new value is already durable; callers
+ * must read state before deciding whether a rejected mutation can be retried.
+ */
+export interface AgentHarnessStatePort<State extends Record<string, unknown>> {
+    get(): Promise<State>;
+    merge(patch: MergePatch<State>): Promise<State>;
+    replace(state: State): Promise<State>;
+}
+/** Existing durable Agent EventLog semantics. */
+export interface AgentHarnessEventPort {
+    emit(type: string, payload: unknown): Promise<number>;
+    read(afterSeq?: number, limit?: number): Promise<StoredEvent[]>;
+    count(): Promise<number>;
+}
+/**
+ * Existing Agent task scheduler semantics.
+ *
+ * Stable ids are pending-task upserts only. This is deliberately not a run
+ * admission ledger: there are no run statuses, terminal records, or durable
+ * idempotency history in this contract.
+ */
+export interface AgentHarnessTaskPort {
+    readonly delivery: "at-least-once";
+    queue(method: string, payload?: unknown, options?: ScheduleOptions): Promise<string>;
+    schedule(delaySeconds: number, method: string, payload?: unknown, options?: ScheduleOptions): Promise<string>;
+    every(intervalSeconds: number, method: string, payload?: unknown, options?: ScheduleOptions): Promise<string>;
+    cancel(id: string): Promise<boolean>;
+    list(): Promise<TaskRecord[]>;
+}
+/** Synchronous per-actor SQL surface matching ActorStorage exactly. */
+export interface AgentHarnessSqlPort {
+    exec<T extends Record<string, SqlValue> = Record<string, SqlValue>>(query: string, ...bindings: SqlBindValue[]): SqlCursor<T>;
+    transactionSync<T>(fn: () => T): T;
+}
+/**
+ * Versioned portable host contract for the execution harness.
+ *
+ * The environment is an explicitly selected, immutable capability bag. The
+ * raw Agent environment, actor context, and actor storage never cross this
+ * boundary.
+ */
+export interface AgentHarnessPorts<State extends Record<string, unknown> = Record<string, unknown>> {
+    readonly version: typeof AGENT_HARNESS_PORTS_VERSION;
+    readonly identity: AgentHarnessIdentity;
+    /** Opaque host-owned token stable for one live actor activation. */
+    readonly activation: object;
+    readonly clock: AgentHarnessClock;
+    /** Omitted until a host supplies the production gateway-attested provider. Approval paths fail closed. */
+    readonly authorization?: HarnessAuthorizationPort;
+    readonly messages: AgentHarnessMessagePort;
+    readonly state: AgentHarnessStatePort<State>;
+    readonly events: AgentHarnessEventPort;
+    readonly tasks: AgentHarnessTaskPort;
+    readonly sql: AgentHarnessSqlPort;
+    readonly environment: Readonly<Record<string, unknown>>;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.js

@@ -0,0 +1,3 @@
+/** Exact major contract implemented by every COMPUTE-705 adapter. */
+export const AGENT_HARNESS_PORTS_VERSION = 2;
+//# sourceMappingURL=ports.js.map

package/dist/runtime-adapter.d.ts

@@ -0,0 +1,15 @@
+import { type Env } from "@telnyx/edge-runtime/internal";
+import { type AgentHarnessPorts } from "./ports.js";
+/** Trusted construction options for selecting environment capabilities. */
+export interface RuntimeAgentHarnessPortsOptions<E extends Env> {
+    /** Only these bindings cross into the portable ports object. */
+    environmentKeys?: readonly (keyof E & string)[];
+}
+/**
+ * Adapt an actual Agent through its runtime-owned symbol seam.
+ *
+ * The function never reflects over protected fields and never adds a
+ * string-named method to the Agent instance. All calls remain in-process.
+ */
+export declare function createRuntimeAgentHarnessPorts<State extends Record<string, unknown>, E extends Env = Env>(agent: object, options?: RuntimeAgentHarnessPortsOptions<E>): AgentHarnessPorts<State>;
+//# sourceMappingURL=runtime-adapter.d.ts.map

package/dist/runtime-adapter.js

@@ -0,0 +1,70 @@
+import { getAgentHarnessHost, getAgentHarnessAuthorizationProvider, } from "@telnyx/edge-runtime/internal";
+import { AGENT_HARNESS_PORTS_VERSION, } from "./ports.js";
+const activations = new WeakMap();
+function activationFor(agent) {
+    let activation = activations.get(agent);
+    if (activation === undefined) {
+        activation = Object.freeze({});
+        activations.set(agent, activation);
+    }
+    return activation;
+}
+/**
+ * Adapt an actual Agent through its runtime-owned symbol seam.
+ *
+ * The function never reflects over protected fields and never adds a
+ * string-named method to the Agent instance. All calls remain in-process.
+ */
+export function createRuntimeAgentHarnessPorts(agent, options = {}) {
+    const host = getAgentHarnessHost(agent);
+    const authorization = getAgentHarnessAuthorizationProvider(agent);
+    const environment = host.selectEnvironment(options.environmentKeys ?? []);
+    const last = ((count) => count === undefined ? host.messages.last() : host.messages.last(count));
+    const messages = Object.freeze({
+        append: (message) => host.messages.append(message),
+        appendMany: (batch) => host.messages.appendMany(batch),
+        all: () => host.messages.all(),
+        last,
+        count: () => host.messages.count(),
+    });
+    const state = Object.freeze({
+        get: () => host.getState(),
+        merge: (patch) => host.mergeState(patch),
+        replace: (next) => host.replaceState(next),
+    });
+    const events = Object.freeze({
+        emit: (type, payload) => host.events.emit(type, payload),
+        read: (afterSeq, limit) => host.events.read(afterSeq, limit),
+        count: () => host.events.count(),
+    });
+    const tasks = Object.freeze({
+        delivery: "at-least-once",
+        queue: async (method, payload, scheduleOptions) => host.queue(method, payload, scheduleOptions),
+        schedule: async (delaySeconds, method, payload, scheduleOptions) => host.schedule(delaySeconds, method, payload, scheduleOptions),
+        every: async (intervalSeconds, method, payload, scheduleOptions) => host.every(intervalSeconds, method, payload, scheduleOptions),
+        cancel: (id) => host.cancelSchedule(id),
+        list: () => host.listSchedules(),
+    });
+    const ports = {
+        version: AGENT_HARNESS_PORTS_VERSION,
+        identity: Object.freeze({ id: host.id }),
+        activation: activationFor(agent),
+        clock: Object.freeze({ now: () => host.now() }),
+        ...(authorization === undefined ? {} : { authorization }),
+        messages,
+        state,
+        events,
+        tasks,
+        sql: Object.freeze({
+            exec(query, ...bindings) {
+                return host.sql.exec(query, ...bindings);
+            },
+            transactionSync(fn) {
+                return host.transactionSync(fn);
+            },
+        }),
+        environment,
+    };
+    return Object.freeze(ports);
+}
+//# sourceMappingURL=runtime-adapter.js.map

package/dist/runtime-config.d.ts

@@ -0,0 +1,38 @@
+type NamedValues<T> = Readonly<Record<string, T>>;
+type RuntimeTools = Readonly<Record<string, unknown>>;
+/** Immutable, executable configuration selected for exactly one harness turn. */
+export interface HarnessRuntimeConfig<Model = unknown, Tools extends RuntimeTools = RuntimeTools, Output = unknown> {
+    readonly model?: Model;
+    readonly instructions: string | undefined;
+    readonly tools?: Tools;
+    readonly limits: Readonly<{
+        steps: number;
+    }>;
+    readonly output?: Output;
+}
+/** Static executable configuration and immutable named registries owned by the host. */
+export interface HarnessRuntimeConfigBase<Model = unknown, Tools extends RuntimeTools = RuntimeTools, Output = unknown> extends HarnessRuntimeConfig<Model, Tools, Output> {
+    readonly activeTools?: readonly string[];
+    readonly models?: NamedValues<Model>;
+    readonly outputs?: NamedValues<Output>;
+}
+export interface HarnessRuntimeOverride {
+    readonly model?: string | null;
+    readonly instructions?: string | null;
+    readonly tools?: readonly string[] | null;
+    readonly limits?: Readonly<{
+        steps?: number | null;
+    }> | null;
+    readonly output?: string | null;
+}
+export interface HarnessRuntimeResolution<Model = unknown, Tools extends RuntimeTools = RuntimeTools, Output = unknown> {
+    readonly valid: boolean;
+    readonly config: HarnessRuntimeConfig<Model, Tools, Output>;
+}
+/**
+ * Resolves the fixed `__telnyx_agent_harness` state value. Invalid candidates
+ * preserve the caller-provided immutable last valid value without partial merge.
+ */
+export declare function resolveHarnessRuntimeConfig<Model, Tools extends RuntimeTools, Output>(base: HarnessRuntimeConfigBase<Model, Tools, Output>, overrideRoot: unknown, previous?: HarnessRuntimeConfig<Model, Tools, Output>): HarnessRuntimeResolution<Model, Tools, Output>;
+export {};
+//# sourceMappingURL=runtime-config.d.ts.map

package/dist/runtime-config.js

@@ -0,0 +1,104 @@
+import { z } from "zod/v4";
+const maxStepsSchema = z.number().int().positive();
+const configSchema = z
+    .object({
+    model: z.string().nullable().optional(),
+    instructions: z.string().nullable().optional(),
+    tools: z.array(z.string()).nullable().optional(),
+    limits: z.object({ steps: z.number().int().positive().nullable().optional() }).strict().nullable().optional(),
+    output: z.string().nullable().optional(),
+})
+    .strict();
+const rootSchema = z.object({ config: configSchema.nullable().optional() }).strict();
+function frozen(value) {
+    return Object.freeze(value);
+}
+function own(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function selectTools(tools, names) {
+    if (tools === undefined) {
+        if (names !== undefined && names.length > 0)
+            throw new TypeError("Harness runtime tools are unavailable");
+        return undefined;
+    }
+    const selectedNames = names ?? Object.keys(tools);
+    if (new Set(selectedNames).size !== selectedNames.length) {
+        throw new TypeError("Harness runtime tools cannot contain duplicate names");
+    }
+    const selected = {};
+    for (const name of selectedNames) {
+        if (!own(tools, name))
+            throw new TypeError(`Unknown harness runtime tool ${name}`);
+        selected[name] = tools[name];
+    }
+    return frozen(selected);
+}
+function staticConfig(base) {
+    const config = {
+        instructions: base.instructions,
+        limits: frozen({ steps: maxStepsSchema.parse(base.limits.steps) }),
+        ...(base.model === undefined ? {} : { model: base.model }),
+        ...(base.tools === undefined ? {} : { tools: selectTools(base.tools, base.activeTools) }),
+        ...(base.output === undefined ? {} : { output: base.output }),
+    };
+    return frozen(config);
+}
+/**
+ * Resolves the fixed `__telnyx_agent_harness` state value. Invalid candidates
+ * preserve the caller-provided immutable last valid value without partial merge.
+ */
+export function resolveHarnessRuntimeConfig(base, overrideRoot, previous = staticConfig(base)) {
+    const staticValue = staticConfig(base);
+    if (overrideRoot === undefined || overrideRoot === null) {
+        return frozen({ valid: true, config: staticValue });
+    }
+    const root = rootSchema.safeParse(overrideRoot);
+    if (!root.success || root.data.config === null || root.data.config === undefined) {
+        return root.success
+            ? frozen({ valid: true, config: staticValue })
+            : frozen({ valid: false, config: previous });
+    }
+    const override = root.data.config;
+    try {
+        if (override.tools !== undefined && override.tools !== null && staticValue.tools === undefined) {
+            throw new TypeError("Harness runtime tools are unavailable");
+        }
+        const model = override.model === undefined || override.model === null
+            ? staticValue.model
+            : base.models !== undefined && own(base.models, override.model)
+                ? base.models[override.model]
+                : undefined;
+        if (override.model !== undefined && override.model !== null && model === undefined) {
+            throw new TypeError(`Unknown harness runtime model ${override.model}`);
+        }
+        const output = override.output === undefined || override.output === null
+            ? staticValue.output
+            : base.outputs !== undefined && own(base.outputs, override.output)
+                ? base.outputs[override.output]
+                : undefined;
+        if (override.output !== undefined && override.output !== null && output === undefined) {
+            throw new TypeError(`Unknown harness runtime output ${override.output}`);
+        }
+        const config = {
+            instructions: override.instructions === undefined || override.instructions === null
+                ? staticValue.instructions
+                : override.instructions,
+            limits: frozen({
+                steps: override.limits?.steps === undefined || override.limits?.steps === null
+                    ? staticValue.limits.steps
+                    : override.limits.steps,
+            }),
+            ...(model === undefined ? {} : { model }),
+            ...(staticValue.tools === undefined
+                ? {}
+                : { tools: selectTools(base.tools, override.tools === null ? base.activeTools : override.tools ?? base.activeTools) }),
+            ...(output === undefined ? {} : { output }),
+        };
+        return frozen({ valid: true, config: frozen(config) });
+    }
+    catch {
+        return frozen({ valid: false, config: previous });
+    }
+}
+//# sourceMappingURL=runtime-config.js.map

package/dist/scheduling.d.ts

@@ -0,0 +1,46 @@
+import { type ToolSet } from "ai";
+import type { TaskRecord } from "@telnyx/edge-runtime/internal";
+import { type HarnessRun, type HarnessRunLedger } from "./durable.js";
+import { type Harness, type HarnessSpec } from "./harness.js";
+import type { AgentHarnessPorts } from "./ports.js";
+export type HarnessSchedule = Readonly<{
+    readonly id: string;
+    readonly mode: "delay" | "interval";
+    readonly nextFireAt: number;
+    readonly status: "active";
+} & (Readonly<{
+    intervalSeconds?: never;
+}> | Readonly<{
+    intervalSeconds: number;
+}>)>;
+export type HarnessScheduleRequest = Readonly<{
+    prompt: string;
+    delaySeconds?: number;
+    intervalSeconds?: number;
+}>;
+export interface HarnessScheduleCancellation {
+    readonly id: string;
+    readonly canceled: boolean;
+}
+export interface HarnessScheduling {
+    readonly tools: ToolSet;
+    schedule(input: HarnessScheduleRequest): Promise<Pick<HarnessSchedule, "id" | "mode" | "nextFireAt">>;
+    listSchedules(): Promise<readonly HarnessSchedule[]>;
+    cancelSchedule(id: string): Promise<HarnessScheduleCancellation>;
+    /** Dispatch a scheduler or harness admission task through durable ownership checks. */
+    dispatch(task: TaskRecord): Promise<HarnessRun | undefined>;
+    /** Reconcile durable schedule state with namespaced pending tasks after restart. */
+    recover(): Promise<number>;
+}
+/**
+ * Creates the bounded v0 model-facing schedule tools and the matching proactive
+ * task handler. Schedule definitions and occurrence-to-run correlation are
+ * private durable state; only active harness-owned schedules are projected.
+ */
+export declare function createHarnessScheduling(ports: AgentHarnessPorts, ledger: HarnessRunLedger): HarnessScheduling;
+/** Construct one durable harness with the bounded scheduling tools in its visible tool set. */
+export declare function createHarnessWithScheduling<State extends Record<string, unknown>>(spec: HarnessSpec<State, ToolSet>): Readonly<{
+    harness: Harness<ToolSet>;
+    scheduling: HarnessScheduling;
+}>;
+//# sourceMappingURL=scheduling.d.ts.map