@telnyx/agent-harness 0.1.0-beta.0

package/dist/scheduling.js

@@ -0,0 +1,425 @@
+import { createHash } from "node:crypto";
+import { tool } from "ai";
+import { z } from "zod/v4";
+import { HarnessAdmissionRejected, createScheduleAdmissionRollbackError, ensureHarnessDurabilitySchema } from "./durable.js";
+import { createHarness } from "./harness.js";
+import { currentHarnessToolContext } from "./tool-context.js";
+const SCHEDULE_TASK_METHOD = "__telnyx_agent_harness_schedule";
+const SCHEDULE_TASK_PREFIX = `${SCHEDULE_TASK_METHOD}/`;
+const MAX_ID_BYTES = 512;
+const MAX_INPUT_BYTES = 64 * 1024;
+const MAX_ACTIVE_SCHEDULES = 32;
+const SCHEDULE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function first(rows) { return rows[0]; }
+function requireBoundedNonblank(value, name, maximum) {
+    if (!value.trim())
+        throw new Error(`${name} must not be blank`);
+    if (Buffer.byteLength(value, "utf8") > maximum)
+        throw new Error(`${name} exceeds ${maximum} UTF-8 bytes`);
+}
+function requireScheduleId(value) {
+    requireBoundedNonblank(value, "schedule id", MAX_ID_BYTES);
+    if (!SCHEDULE_ID_PATTERN.test(value))
+        throw new Error("schedule id must be canonical");
+}
+function isScheduleId(value) {
+    try {
+        requireScheduleId(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function requireSeconds(mode, seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0 || (mode === "interval" && seconds === 0)) {
+        throw new Error(mode === "delay" ? "delay seconds must be finite and non-negative" : "interval seconds must be finite and positive");
+    }
+}
+function taskId(id) { return `${SCHEDULE_TASK_PREFIX}${id}`; }
+function keyForOccurrence(id, scheduledFor) {
+    return `schedule:${id}:${scheduledFor}`;
+}
+function schedulePayload(id, scheduledFor) {
+    return Object.freeze({ id, scheduledFor });
+}
+function dueDelaySeconds(now, due) {
+    return Math.max(0, (due - now) / 1_000);
+}
+function publicSchedule(row) {
+    if (row.mode === "delay") {
+        return Object.freeze({ id: row.id, mode: "delay", nextFireAt: row.next_due_at, status: "active" });
+    }
+    return Object.freeze({ id: row.id, mode: "interval", intervalSeconds: row.seconds, nextFireAt: row.next_due_at, status: "active" });
+}
+function scheduleMode(request) {
+    const hasDelay = request.delaySeconds !== undefined;
+    const hasInterval = request.intervalSeconds !== undefined;
+    if (hasDelay === hasInterval)
+        throw new Error("schedule requires exactly one delaySeconds or intervalSeconds");
+    const mode = hasDelay ? "delay" : "interval";
+    const seconds = hasDelay ? request.delaySeconds : request.intervalSeconds;
+    requireSeconds(mode, seconds);
+    return Object.freeze({ mode, seconds });
+}
+function taskScheduleIdentity(task) {
+    if (task.name !== SCHEDULE_TASK_METHOD || task.payload === null || typeof task.payload !== "object" || Array.isArray(task.payload))
+        return undefined;
+    const id = Object.getOwnPropertyDescriptor(task.payload, "id");
+    const scheduledFor = Object.getOwnPropertyDescriptor(task.payload, "scheduledFor");
+    if (id === undefined || !("value" in id) || typeof id.value !== "string"
+        || scheduledFor === undefined || !("value" in scheduledFor) || !Number.isSafeInteger(scheduledFor.value) || scheduledFor.value < 0)
+        return undefined;
+    try {
+        requireScheduleId(id.value);
+    }
+    catch {
+        return undefined;
+    }
+    return task.id === taskId(id.value) ? Object.freeze({ id: id.value, scheduledFor: scheduledFor.value }) : undefined;
+}
+function ensureSchedulingSchema(ports) {
+    ports.sql.transactionSync(() => {
+        ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_schedules (id TEXT PRIMARY KEY NOT NULL, mode TEXT NOT NULL CHECK(mode IN ('delay','interval')), seconds REAL NOT NULL, input TEXT NOT NULL, next_due_at INTEGER NOT NULL, active INTEGER NOT NULL CHECK(active IN (0,1)), origin_run_id TEXT, origin_tool_ordinal INTEGER, origin_journal_marker TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL)");
+        const columns = new Set((ports.sql.exec("PRAGMA table_info('__telnyx_agent_harness_schedules')").toArray()).map((column) => column.name));
+        if (!columns.has("origin_run_id"))
+            ports.sql.exec("ALTER TABLE __telnyx_agent_harness_schedules ADD COLUMN origin_run_id TEXT");
+        if (!columns.has("origin_tool_ordinal"))
+            ports.sql.exec("ALTER TABLE __telnyx_agent_harness_schedules ADD COLUMN origin_tool_ordinal INTEGER");
+        if (!columns.has("origin_journal_marker"))
+            ports.sql.exec("ALTER TABLE __telnyx_agent_harness_schedules ADD COLUMN origin_journal_marker TEXT");
+        ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_schedule_occurrences (schedule_id TEXT NOT NULL, scheduled_for INTEGER NOT NULL, run_id TEXT, journal_seq INTEGER, status TEXT NOT NULL CHECK(status IN ('pending','admitted','canceled')), created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, PRIMARY KEY(schedule_id,scheduled_for), FOREIGN KEY(schedule_id) REFERENCES __telnyx_agent_harness_schedules(id))");
+        const occurrenceColumns = new Set((ports.sql.exec("PRAGMA table_info('__telnyx_agent_harness_schedule_occurrences')").toArray()).map((column) => column.name));
+        if (!occurrenceColumns.has("journal_seq"))
+            ports.sql.exec("ALTER TABLE __telnyx_agent_harness_schedule_occurrences ADD COLUMN journal_seq INTEGER");
+    });
+}
+/**
+ * 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 function createHarnessScheduling(ports, ledger) {
+    let initialized = false;
+    const ensure = () => {
+        if (initialized)
+            return;
+        ensureHarnessDurabilitySchema(ports);
+        ensureSchedulingSchema(ports);
+        initialized = true;
+    };
+    const readSchedule = (id) => first(ports.sql.exec("SELECT id,mode,seconds,input,next_due_at,active,origin_run_id,origin_tool_ordinal,origin_journal_marker FROM __telnyx_agent_harness_schedules WHERE id = ?", id).toArray());
+    const schedule = async (request, context) => {
+        ensure();
+        const { mode, seconds } = scheduleMode(request);
+        requireBoundedNonblank(request.prompt, "schedule prompt", MAX_INPUT_BYTES);
+        const origin = context === undefined ? undefined : (() => {
+            if (context.toolName !== "schedule")
+                throw new Error("schedule tool context is invalid");
+            const row = first(ports.sql.exec("SELECT journal_marker FROM __telnyx_agent_harness_tool_calls WHERE run_id = ? AND tool_name = ? AND ordinal = ?", context.runId, context.toolName, context.ordinal).toArray());
+            if (row?.journal_marker === null || row?.journal_marker === undefined)
+                throw new Error("schedule tool journal linkage is unavailable");
+            return Object.freeze({ ...context, journalMarker: row.journal_marker });
+        })();
+        const id = origin === undefined
+            ? `schedule-${crypto.randomUUID()}`
+            : `schedule-${createHash("sha256").update(`${origin.runId}\u0000${origin.toolName}\u0000${origin.ordinal}`).digest("hex")}`;
+        requireScheduleId(id);
+        const now = ports.clock.now();
+        const nextDueAt = Math.floor(now + seconds * 1_000);
+        if (!Number.isSafeInteger(nextDueAt) || nextDueAt < 0)
+            throw new Error("schedule deadline is invalid");
+        const admitted = ports.sql.transactionSync(() => {
+            // Durable tool replay uses the same deterministic id. An already committed
+            // schedule is authoritative even when the actor is at capacity; do not
+            // overwrite or re-arm it if a later replay cannot reach the host scheduler.
+            const existing = readSchedule(id);
+            if (existing?.active === 1)
+                return Object.freeze({ created: false, schedule: existing });
+            const count = first(ports.sql.exec("SELECT COUNT(*) AS count FROM __telnyx_agent_harness_schedules WHERE active = 1").toArray())?.count ?? 0;
+            if (count >= MAX_ACTIVE_SCHEDULES)
+                throw new Error(`active schedule limit (${MAX_ACTIVE_SCHEDULES}) reached`);
+            ports.sql.exec("INSERT INTO __telnyx_agent_harness_schedules(id,mode,seconds,input,next_due_at,active,origin_run_id,origin_tool_ordinal,origin_journal_marker,created_at,updated_at) VALUES (?,?,?,?,?,1,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET mode = excluded.mode, seconds = excluded.seconds, input = excluded.input, next_due_at = excluded.next_due_at, active = 1, origin_run_id = excluded.origin_run_id, origin_tool_ordinal = excluded.origin_tool_ordinal, origin_journal_marker = excluded.origin_journal_marker, updated_at = excluded.updated_at", id, mode, seconds, request.prompt, nextDueAt, origin?.runId ?? null, origin?.ordinal ?? null, origin?.journalMarker ?? null, now, now);
+            return Object.freeze({ created: true, schedule: Object.freeze({ id, mode, next_due_at: nextDueAt }) });
+        });
+        if (!admitted.created) {
+            const { id: existingId, mode: existingMode, next_due_at: existingNextFireAt } = admitted.schedule;
+            return Object.freeze({ id: existingId, mode: existingMode, nextFireAt: existingNextFireAt });
+        }
+        // Stable namespaced task ids make an upsert/re-arm independent of unrelated Agent tasks.
+        try {
+            if (mode === "delay") {
+                await ports.tasks.schedule(seconds, SCHEDULE_TASK_METHOD, schedulePayload(id, nextDueAt), { id: taskId(id), maxRetries: 5 });
+            }
+            else {
+                await ports.tasks.schedule(seconds, SCHEDULE_TASK_METHOD, schedulePayload(id, nextDueAt), { id: taskId(id), maxRetries: 5 });
+            }
+        }
+        catch (error) {
+            ports.sql.transactionSync(() => ports.sql.exec("DELETE FROM __telnyx_agent_harness_schedules WHERE id = ? AND active = 1", id));
+            if (context !== undefined)
+                throw createScheduleAdmissionRollbackError(`tool:${context.toolName}:${context.ordinal}`, error);
+            throw error;
+        }
+        return Object.freeze({ id, mode, nextFireAt: nextDueAt });
+    };
+    const listSchedules = async () => {
+        ensure();
+        const rows = ports.sql.exec("SELECT id,mode,seconds,input,next_due_at,active FROM __telnyx_agent_harness_schedules WHERE active = 1 ORDER BY id").toArray();
+        return Object.freeze(rows.map(publicSchedule));
+    };
+    const cancelSchedule = async (id) => {
+        ensure();
+        requireScheduleId(id);
+        const canceled = ports.sql.transactionSync(() => {
+            const current = readSchedule(id);
+            if (current === undefined || current.active !== 1)
+                return false;
+            ports.sql.exec("UPDATE __telnyx_agent_harness_schedules SET active = 0, updated_at = ? WHERE id = ? AND active = 1", ports.clock.now(), id);
+            return true;
+        });
+        if (canceled) {
+            try {
+                await ports.tasks.cancel(taskId(id));
+            }
+            catch { /* durable inactive state fences late delivery */ }
+        }
+        return Object.freeze({ id, canceled });
+    };
+    const admitOccurrence = async (_task, identity) => {
+        ensure();
+        const { id, scheduledFor } = identity;
+        const prepared = ports.sql.transactionSync(() => {
+            const current = readSchedule(id);
+            if (current === undefined || current.active !== 1)
+                return undefined;
+            const occurrence = first(ports.sql.exec("SELECT schedule_id,scheduled_for,run_id,journal_seq FROM __telnyx_agent_harness_schedule_occurrences WHERE schedule_id = ? AND scheduled_for = ?", id, scheduledFor).toArray());
+            if (occurrence?.run_id !== null && occurrence?.run_id !== undefined)
+                return Object.freeze({ schedule: current, occurrence });
+            if (occurrence === undefined) {
+                ports.sql.exec("INSERT INTO __telnyx_agent_harness_schedule_occurrences(schedule_id,scheduled_for,run_id,status,created_at,updated_at) VALUES (?,?,NULL,'pending',?,?)", id, scheduledFor, ports.clock.now(), ports.clock.now());
+            }
+            return Object.freeze({ schedule: current, occurrence: undefined });
+        });
+        if (prepared === undefined)
+            return;
+        if (prepared.occurrence?.run_id !== undefined && prepared.occurrence.run_id !== null) {
+            if (prepared.schedule.active === 1 && prepared.schedule.mode === "interval") {
+                const delay = dueDelaySeconds(ports.clock.now(), prepared.schedule.next_due_at);
+                await ports.tasks.schedule(delay, SCHEDULE_TASK_METHOD, schedulePayload(id, prepared.schedule.next_due_at), { id: taskId(id), maxRetries: 5 });
+            }
+            return;
+        }
+        // Cancellation is authoritative until admission begins; an already admitted
+        // run is intentionally left to the existing run-cancellation surface.
+        const stillActive = ports.sql.transactionSync(() => readSchedule(id)?.active === 1);
+        if (!stillActive) {
+            ports.sql.transactionSync(() => ports.sql.exec("UPDATE __telnyx_agent_harness_schedule_occurrences SET status = 'canceled', updated_at = ? WHERE schedule_id = ? AND scheduled_for = ? AND run_id IS NULL", ports.clock.now(), id, scheduledFor));
+            return;
+        }
+        let accepted;
+        try {
+            const journalSeq = await ports.messages.count();
+            accepted = await ledger.accept(prepared.schedule.input, {
+                key: keyForOccurrence(id, scheduledFor),
+                admit: () => readSchedule(id)?.active === 1,
+                journalSeq,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof HarnessAdmissionRejected))
+                throw error;
+            ports.sql.transactionSync(() => ports.sql.exec("UPDATE __telnyx_agent_harness_schedule_occurrences SET status = 'canceled', updated_at = ? WHERE schedule_id = ? AND scheduled_for = ? AND run_id IS NULL", ports.clock.now(), id, scheduledFor));
+            return;
+        }
+        const nextInterval = ports.sql.transactionSync(() => {
+            const current = readSchedule(id);
+            ports.sql.exec("UPDATE __telnyx_agent_harness_schedule_occurrences SET run_id = ?, status = 'admitted', updated_at = ? WHERE schedule_id = ? AND scheduled_for = ? AND run_id IS NULL", accepted.runId, ports.clock.now(), id, scheduledFor);
+            if (current?.active === 1 && current.mode === "delay") {
+                ports.sql.exec("UPDATE __telnyx_agent_harness_schedules SET active = 0, updated_at = ? WHERE id = ?", ports.clock.now(), id);
+            }
+            else if (current?.active === 1 && current.mode === "interval") {
+                const nextFireAt = Math.floor(ports.clock.now() + current.seconds * 1_000);
+                ports.sql.exec("UPDATE __telnyx_agent_harness_schedules SET next_due_at = ?, updated_at = ? WHERE id = ?", nextFireAt, ports.clock.now(), id);
+                return Object.freeze({ id: current.id, nextFireAt });
+            }
+            return undefined;
+        });
+        if (nextInterval !== undefined) {
+            await ports.tasks.schedule(dueDelaySeconds(ports.clock.now(), nextInterval.nextFireAt), SCHEDULE_TASK_METHOD, schedulePayload(nextInterval.id, nextInterval.nextFireAt), { id: taskId(nextInterval.id), maxRetries: 5 });
+        }
+    };
+    const dispatch = async (task) => {
+        ensure();
+        const identity = taskScheduleIdentity(task);
+        if (task.name === SCHEDULE_TASK_METHOD) {
+            if (typeof task.id !== "string" || !task.id)
+                throw new Error("scheduled task is invalid");
+            if (identity === undefined) {
+                if (task.id.startsWith(SCHEDULE_TASK_PREFIX))
+                    throw new Error("scheduled task is invalid");
+                return undefined;
+            }
+            await admitOccurrence(task, identity);
+            return undefined;
+        }
+        const dispatched = await ledger.dispatch(task);
+        if (dispatched !== null && typeof dispatched === "object"
+            && "id" in dispatched && typeof dispatched.id === "string"
+            && "status" in dispatched && dispatched.status === "completed") {
+            // This runs directly after the durable run's journal barrier, while the
+            // actor turn is serialized. Persisting that exact sequence makes the
+            // occurrence -> run -> journal relationship recoverable without trying
+            // to infer it from actor-global history later.
+            // The durable run is already terminal. Correlation is repaired from the
+            // run-owned journal marker during recovery, so a transient read failure
+            // must not make the host retry this completed run task.
+            ports.sql.transactionSync(() => ports.sql.exec("UPDATE __telnyx_agent_harness_schedule_occurrences SET journal_seq = (SELECT journal_seq FROM __telnyx_agent_harness_run_journal WHERE run_id = __telnyx_agent_harness_schedule_occurrences.run_id), updated_at = ? WHERE run_id = ? AND status = 'admitted' AND EXISTS (SELECT 1 FROM __telnyx_agent_harness_run_journal WHERE run_id = __telnyx_agent_harness_schedule_occurrences.run_id)", ports.clock.now(), dispatched.id));
+        }
+        return dispatched;
+    };
+    const recover = async () => {
+        ensure();
+        // A process can stop after ledger.accept() commits its idempotent run but
+        // before the occurrence receives that run id. Reconcile that committed
+        // admission before considering the schedule's current active state:
+        // cancellation after admission must not erase the admitted occurrence.
+        ports.sql.transactionSync(() => ports.sql.exec("UPDATE __telnyx_agent_harness_schedule_occurrences SET run_id = (SELECT id FROM __telnyx_agent_harness_runs WHERE key = ('schedule:' || __telnyx_agent_harness_schedule_occurrences.schedule_id || ':' || __telnyx_agent_harness_schedule_occurrences.scheduled_for)), status = 'admitted', updated_at = ? WHERE status = 'pending' AND run_id IS NULL AND EXISTS (SELECT 1 FROM __telnyx_agent_harness_runs WHERE key = ('schedule:' || __telnyx_agent_harness_schedule_occurrences.schedule_id || ':' || __telnyx_agent_harness_schedule_occurrences.scheduled_for))", ports.clock.now()));
+        // The run-owned marker is committed by the durable turn before its final
+        // run transition, so this repair never guesses from later actor history.
+        ports.sql.transactionSync(() => ports.sql.exec("UPDATE __telnyx_agent_harness_schedule_occurrences SET journal_seq = (SELECT journal_seq FROM __telnyx_agent_harness_run_journal WHERE run_id = __telnyx_agent_harness_schedule_occurrences.run_id), updated_at = ? WHERE status = 'admitted' AND run_id IS NOT NULL AND EXISTS (SELECT 1 FROM __telnyx_agent_harness_run_journal WHERE run_id = __telnyx_agent_harness_schedule_occurrences.run_id)", ports.clock.now()));
+        const pending = ports.sql.exec("SELECT schedules.id,schedules.mode,schedules.seconds,schedules.input,schedules.next_due_at,schedules.active,occurrences.scheduled_for FROM __telnyx_agent_harness_schedule_occurrences AS occurrences JOIN __telnyx_agent_harness_schedules AS schedules ON schedules.id = occurrences.schedule_id WHERE occurrences.status = 'pending' AND occurrences.run_id IS NULL AND schedules.active = 1 ORDER BY occurrences.scheduled_for,schedules.id").toArray();
+        let repaired = 0;
+        for (const occurrence of pending) {
+            let accepted;
+            try {
+                const journalSeq = await ports.messages.count();
+                accepted = await ledger.accept(occurrence.input, {
+                    key: keyForOccurrence(occurrence.id, occurrence.scheduled_for),
+                    admit: () => readSchedule(occurrence.id)?.active === 1,
+                    journalSeq,
+                });
+            }
+            catch (error) {
+                if (!(error instanceof HarnessAdmissionRejected))
+                    throw error;
+                ports.sql.transactionSync(() => ports.sql.exec("UPDATE __telnyx_agent_harness_schedule_occurrences SET status = 'canceled', updated_at = ? WHERE schedule_id = ? AND scheduled_for = ? AND run_id IS NULL", ports.clock.now(), occurrence.id, occurrence.scheduled_for));
+                continue;
+            }
+            ports.sql.transactionSync(() => {
+                ports.sql.exec("UPDATE __telnyx_agent_harness_schedule_occurrences SET run_id = ?, status = 'admitted', updated_at = ? WHERE schedule_id = ? AND scheduled_for = ? AND run_id IS NULL AND status = 'pending'", accepted.runId, ports.clock.now(), occurrence.id, occurrence.scheduled_for);
+                if (occurrence.mode === "delay") {
+                    ports.sql.exec("UPDATE __telnyx_agent_harness_schedules SET active = 0, updated_at = ? WHERE id = ? AND active = 1", ports.clock.now(), occurrence.id);
+                }
+                else {
+                    ports.sql.exec("UPDATE __telnyx_agent_harness_schedules SET next_due_at = ?, updated_at = ? WHERE id = ? AND active = 1", Math.floor(ports.clock.now() + occurrence.seconds * 1_000), ports.clock.now(), occurrence.id);
+                }
+            });
+            repaired += 1;
+        }
+        const active = ports.sql.exec("SELECT id,mode,seconds,input,next_due_at,active FROM __telnyx_agent_harness_schedules WHERE active = 1 ORDER BY id").toArray();
+        const expected = new Set(active.map((row) => taskId(row.id)));
+        const tasks = await ports.tasks.list();
+        for (const task of tasks) {
+            // Prefix resemblance is not ownership. Only a fully validated private
+            // envelope can be reconciled or canceled by this harness.
+            if (taskScheduleIdentity(task) !== undefined && !expected.has(task.id)) {
+                try {
+                    if (await ports.tasks.cancel(task.id))
+                        repaired += 1;
+                }
+                catch { /* retry on next recovery */ }
+            }
+        }
+        const present = new Map(tasks.map((task) => [task.id, task]));
+        for (const row of active) {
+            const id = taskId(row.id);
+            const task = present.get(id);
+            const everyMs = undefined;
+            if (task !== undefined
+                && task.name === SCHEDULE_TASK_METHOD
+                && task.due === row.next_due_at
+                && task.everyMs === everyMs
+                && taskScheduleIdentity(task)?.id === row.id
+                && taskScheduleIdentity(task)?.scheduledFor === row.next_due_at)
+                continue;
+            const delay = dueDelaySeconds(ports.clock.now(), row.next_due_at);
+            if (row.mode === "delay")
+                await ports.tasks.schedule(delay, SCHEDULE_TASK_METHOD, schedulePayload(row.id, row.next_due_at), { id, maxRetries: 5 });
+            else
+                await ports.tasks.schedule(delay, SCHEDULE_TASK_METHOD, schedulePayload(row.id, row.next_due_at), { id, maxRetries: 5 });
+            repaired += 1;
+        }
+        return repaired;
+    };
+    const tools = Object.freeze({
+        schedule: tool({
+            inputSchema: z.object({
+                prompt: z.string(),
+                delaySeconds: z.number().optional(),
+                intervalSeconds: z.number().optional(),
+            }).refine((input) => (input.delaySeconds === undefined) !== (input.intervalSeconds === undefined), {
+                message: "schedule requires exactly one delaySeconds or intervalSeconds",
+            }),
+            execute: (async (input) => {
+                const context = currentHarnessToolContext();
+                if (context === undefined)
+                    throw new Error("schedule tool requires durable admission");
+                return await schedule(input, context);
+            }),
+        }),
+        list_schedules: tool({
+            inputSchema: z.object({}),
+            execute: (async (_input) => {
+                const context = currentHarnessToolContext();
+                if (context === undefined)
+                    throw new Error("list_schedules tool requires durable admission");
+                return await listSchedules();
+            }),
+        }),
+        cancel_schedule: tool({
+            inputSchema: z.object({ id: z.string().refine(isScheduleId, { message: "schedule id must be bounded and canonical" }) }),
+            execute: (async ({ id }) => {
+                const context = currentHarnessToolContext();
+                if (context === undefined)
+                    throw new Error("cancel_schedule tool requires durable admission");
+                return await cancelSchedule(id);
+            }),
+        }),
+    });
+    return Object.freeze({ tools, schedule, listSchedules, cancelSchedule, dispatch, recover });
+}
+/** Construct one durable harness with the bounded scheduling tools in its visible tool set. */
+export function createHarnessWithScheduling(spec) {
+    let baseHarness;
+    const requireBaseHarness = () => {
+        if (baseHarness === undefined)
+            throw new Error("harness scheduling is unavailable during construction");
+        return baseHarness;
+    };
+    const ledger = Object.freeze({
+        accept: async (input, options) => requireBaseHarness().accept(input, options),
+        get: async (runId) => requireBaseHarness().get(runId),
+        status: async (runId) => requireBaseHarness().status(runId),
+        list: async (options) => requireBaseHarness().list(options),
+        cancel: async (runId) => requireBaseHarness().cancel(runId),
+        recover: async () => requireBaseHarness().recover(),
+        run: async (runId) => requireBaseHarness().run(runId),
+        dispatch: async (task) => requireBaseHarness().dispatch(task),
+    });
+    const scheduling = createHarnessScheduling(spec.ports, ledger);
+    const collisions = Object.keys(spec.tools).filter((name) => Object.hasOwn(scheduling.tools, name));
+    if (collisions.length > 0)
+        throw new TypeError(`Harness scheduling tools collide with supplied tools: ${collisions.join(",")}`);
+    const activeTools = spec.activeTools === undefined
+        ? undefined
+        : Object.freeze([...new Set([...spec.activeTools, ...Object.keys(scheduling.tools)])]);
+    baseHarness = createHarness({ ...spec, tools: Object.freeze({ ...spec.tools, ...scheduling.tools }), ...(activeTools === undefined ? {} : { activeTools: activeTools }) });
+    const harness = Object.freeze({
+        ...baseHarness,
+        dispatch: scheduling.dispatch,
+        recover: async () => (await baseHarness.recover()) + (await scheduling.recover()),
+    });
+    return Object.freeze({ harness, scheduling });
+}
+//# sourceMappingURL=scheduling.js.map

package/dist/steps.d.ts

@@ -0,0 +1,52 @@
+import type { AgentHarnessPorts } from "./ports.js";
+import { type HarnessCheckpoint } from "./durable.js";
+export interface HarnessStepContextOptions {
+    readonly runId: string;
+    readonly input: unknown;
+    readonly version: string;
+    /** True only when this durable run is replaying after interruption or approval. */
+    readonly isContinuation?: boolean;
+    /** Deterministic test seam. Production callers must not use this to infer external-effect success. */
+    readonly checkpoints?: HarnessCheckpoint;
+}
+export interface HarnessStepOptions {
+    /** Marks a call that can mutate an external system and therefore needs reconciliation after an interrupted effect. */
+    readonly external?: boolean;
+    /** JSON-safe effect input used for this step's durable memo fingerprint. */
+    readonly input?: unknown;
+    /** Explicit effect contract version used for this step's durable memo identity. */
+    readonly version?: string;
+    /** Private synchronous hook committed with the external effect-start fence. */
+    readonly beforeEffect?: () => void;
+}
+export interface HarnessStepContext {
+    /** Private durable run identity for harness-owned continuation state. */
+    readonly runId: string;
+    /** True only when this durable run is replaying after interruption or approval. */
+    readonly isContinuation: boolean;
+    /**
+     * Executes a named effect once per stable run/input/version identity, then
+     * durably returns its JSON-safe output on replay. External effects are
+     * at-least-once: an interruption after the effect starts is outcome-unknown,
+     * never silently retried.
+     */
+    step<T>(name: string, fn: () => Promise<T>, options?: HarnessStepOptions): Promise<T>;
+    /** True only when this exact durable step has committed its memoized output. */
+    isCompleted(name: string, options?: Pick<HarnessStepOptions, "input" | "version">): boolean;
+    /** Allocates a run-scoped logical tool position independent of provider call IDs. */
+    nextToolCallOrdinal(toolName: string, toolCallId: string | undefined): number;
+    /** Associates this provider step's correlation IDs with its already-reserved durable positions. */
+    associateToolCallJournal(calls: readonly Readonly<{
+        toolName: string;
+        toolCallId: string;
+    }>[]): ReadonlyMap<string, string>;
+    /** Reconciles harness-owned journal markers with durable message history. */
+    reconcileToolCallJournal(journalMarkers: ReadonlySet<string>): void;
+}
+/** Private durable marker that never shares the tool-output value channel. */
+export declare class HarnessStepOutputSerializationError extends Error {
+    constructor();
+}
+export declare function isToolOutputSerializationFailure(value: unknown): boolean;
+export declare function createHarnessStepContext(ports: AgentHarnessPorts, options: HarnessStepContextOptions): HarnessStepContext;
+//# sourceMappingURL=steps.d.ts.map