melchizedek-agents 1.6.0 → 1.7.0

package/dist/lib/script/journal.d.ts

@@ -0,0 +1,137 @@
+/**
+ * lib/script/journal.ts — a script run's record of its calls, kept as
+ * node-style events in the conversation (ADR 0137 items 8, 9 and 11).
+ *
+ * ONE EVENT PER CALL. Each agent, tool, askUser, now and random call a run
+ * makes is one event: authored by the script's name, `nodeInfo.path`
+ * `<script>.<seq>`, the call in `actions.agentState.script_call` (the run,
+ * its seq, the kind, the name and a hash of the arguments) and its result in
+ * `event.output`, with no content parts. Those are the fields the Supabase
+ * store's trimEventForStorage never touches, so the journal replays the same
+ * from it and from Postgres; and with no text part, long-term memory
+ * ingestion (which reads text) never sees it.
+ *
+ * THE PAUSE. A live askUser writes the request ADK's ask_user node writes
+ * (`adk_request_input`, lib/workflow/pause.ts), so `result.input` is one
+ * shape for every method, plus `script_pause`: the run's pinned source, its
+ * message and transcript, which the resume runs again (item 11). Its answer
+ * is a second event for the same seq, carrying `{ reply, input }`.
+ *
+ * WHEN IT IS STORED. Only a run that pauses needs its journal, to replay
+ * it, so the runner keeps the events in memory and stores them with the
+ * pause; a run that finishes stores none, and the conversation keeps only
+ * the exchange, as for a dispatch route (on the Supabase store every append
+ * rewrites the session's events). A resumed run that ends stores its
+ * answer's event and an `end` marker, closing it.
+ *
+ * WHICH RUN IS OPEN. The conversation's last journal event decides: a pause
+ * with no answer after it is a run waiting for the person; anything else is
+ * a finished run, and the next message starts a new one.
+ */
+import type { TurnEvent } from '../runtime/events.ts';
+import type { PendingApproval } from '../runtime/approvals.ts';
+import type { PendingInput } from '../workflowConfig.ts';
+/** What a script calls. */
+/** What a script calls; `end` marks a resumed run that finished, so the next message starts a new one. */
+export type ScriptCallKind = 'agent' | 'tool' | 'askUser' | 'now' | 'random' | 'end';
+/** `actions.agentState.script_call`. */
+export interface ScriptCallRecord {
+    run: string;
+    seq: number;
+    kind: ScriptCallKind;
+    name: string;
+    hash: string;
+}
+/** `actions.agentState.script_run`: what a resume runs again, pinned when the run first stores anything. */
+export interface ScriptPinRecord {
+    run: string;
+    source: string;
+    source_hash: string;
+    message: string;
+    transcript: string;
+}
+/** `actions.agentState.script_pause`: the pin, and what the run waits on. */
+export interface ScriptPauseRecord extends ScriptPinRecord {
+    /** The interrupt id the person's answer resolves: a question's, or an approval request's. */
+    interrupt_id: string;
+    /** `question` (askUser) or `approval` (a gated tool() call). Absent: question. */
+    kind?: 'question' | 'approval';
+}
+/** What one call returned, as the journal keeps it: a value, or the error it threw into the script. */
+export type ScriptCallOutcome = {
+    value: unknown;
+} | {
+    error: {
+        name: string;
+        message: string;
+    };
+};
+/** One recorded call. */
+export interface JournalEntry extends ScriptCallRecord {
+    /** Absent for a pause still waiting for its answer. */
+    outcome?: ScriptCallOutcome;
+    /** The pause record, on an askUser that paused the run. */
+    pause?: ScriptPauseRecord;
+}
+/** The journal events' marker keys under agentState. */
+export declare const SCRIPT_CALL = "script_call";
+export declare const SCRIPT_PAUSE = "script_pause";
+export declare const SCRIPT_RUN = "script_run";
+/**
+ * Set on a session store that wants every journal event as its call ends,
+ * not only when the run pauses: the durable-run store (ADR 0113), whose
+ * checkpoint boundary a journal append is, so a worker killed mid-script
+ * resumes from its last call (ADR 0137 item 8).
+ */
+export declare const JOURNAL_EVERY_CALL: unique symbol;
+/** True when `sessions` asks for every journal event as its call ends. */
+export declare function journalsEveryCall(sessions: unknown): boolean;
+/** True for a script's journal event. */
+export declare function isJournalEvent(event: TurnEvent): boolean;
+/** The hash a call is matched on: its kind, name and arguments. */
+export declare function callHash(kind: ScriptCallKind, name: string, args: unknown): string;
+/** The hash a run's source is pinned by. */
+export declare function sourceHash(source: string): string;
+/** The event for a call that returned (or threw into the script); `pin` on the first event a run stores call by call. */
+export declare function callEvent(script: string, invocationId: string, call: ScriptCallRecord, outcome: ScriptCallOutcome, pin?: ScriptPinRecord): TurnEvent;
+/** The marker a resumed run that ended leaves: its run is closed. */
+export declare function endEvent(script: string, invocationId: string, run: string, seq: number): TurnEvent;
+/** The event for an askUser that pauses the run: ADK's input request, stamped as a journal entry, with the pinned run. */
+export declare function pauseEvent(script: string, invocationId: string, call: ScriptCallRecord, pause: ScriptPauseRecord, request: {
+    message: string;
+    payload?: unknown;
+    schema?: Record<string, unknown>;
+}): TurnEvent;
+/**
+ * The event for a gated tool() call that pauses the run: ADK's approval
+ * request (`adk_request_confirmation`, lib/runtime/approvals.ts), pinning
+ * the call and its arguments, stamped as a journal entry, with the pinned run.
+ */
+export declare function approvalEvent(script: string, invocationId: string, call: ScriptCallRecord, pause: ScriptPauseRecord, request: {
+    tool: string;
+    args: unknown;
+    hint: string;
+}): TurnEvent;
+/** A run the conversation has not finished: one waiting on the person, or one a stopped worker left mid-way. */
+export interface OpenRun {
+    /** `paused`: its last event is a pause. `unfinished`: a run stored call by call whose last event is a call (a durable job resumed after its worker stopped). */
+    state: 'paused' | 'unfinished';
+    pin: ScriptPinRecord;
+    /** The pause, when paused. */
+    pause?: ScriptPauseRecord;
+    /** Every call it recorded, in seq order. */
+    entries: JournalEntry[];
+}
+/** The run a conversation has open, or undefined: the last journal event decides (a pause, a call of a run stored call by call, or a closing `end`). */
+export declare function openRun(events: readonly TurnEvent[], script: string): OpenRun | undefined;
+/**
+ * What a script run in a conversation waits on, read as a caller reads a
+ * nested syndicate's conversation (lib/runtime/native/interrupts.ts): the
+ * open pause of the run whose last event it is, as an approval request or a
+ * question, authored by the script. With `id`, only that request counts.
+ */
+export declare function scriptPauseIn(events: readonly TurnEvent[], id?: string): {
+    asker: string;
+    approval?: PendingApproval;
+    question?: PendingInput;
+} | undefined;

package/dist/lib/script/journal.js

@@ -0,0 +1,193 @@
+/**
+ * lib/script/journal.ts — a script run's record of its calls, kept as
+ * node-style events in the conversation (ADR 0137 items 8, 9 and 11).
+ *
+ * ONE EVENT PER CALL. Each agent, tool, askUser, now and random call a run
+ * makes is one event: authored by the script's name, `nodeInfo.path`
+ * `<script>.<seq>`, the call in `actions.agentState.script_call` (the run,
+ * its seq, the kind, the name and a hash of the arguments) and its result in
+ * `event.output`, with no content parts. Those are the fields the Supabase
+ * store's trimEventForStorage never touches, so the journal replays the same
+ * from it and from Postgres; and with no text part, long-term memory
+ * ingestion (which reads text) never sees it.
+ *
+ * THE PAUSE. A live askUser writes the request ADK's ask_user node writes
+ * (`adk_request_input`, lib/workflow/pause.ts), so `result.input` is one
+ * shape for every method, plus `script_pause`: the run's pinned source, its
+ * message and transcript, which the resume runs again (item 11). Its answer
+ * is a second event for the same seq, carrying `{ reply, input }`.
+ *
+ * WHEN IT IS STORED. Only a run that pauses needs its journal, to replay
+ * it, so the runner keeps the events in memory and stores them with the
+ * pause; a run that finishes stores none, and the conversation keeps only
+ * the exchange, as for a dispatch route (on the Supabase store every append
+ * rewrites the session's events). A resumed run that ends stores its
+ * answer's event and an `end` marker, closing it.
+ *
+ * WHICH RUN IS OPEN. The conversation's last journal event decides: a pause
+ * with no answer after it is a run waiting for the person; anything else is
+ * a finished run, and the next message starts a new one.
+ */
+import { createHash } from 'node:crypto';
+import { createTurnEvent } from '../runtime/events.js';
+import { requestInputEvent } from '../workflow/pause.js';
+import { APPROVAL_REQUEST, approvalRequestOf } from '../runtime/approvals.js';
+import { getFunctionCalls } from '../runtime/events.js';
+import { inputRequestFrom } from '../workflowConfig.js';
+/** The journal events' marker keys under agentState. */
+export const SCRIPT_CALL = 'script_call';
+export const SCRIPT_PAUSE = 'script_pause';
+export const SCRIPT_RUN = 'script_run';
+/**
+ * Set on a session store that wants every journal event as its call ends,
+ * not only when the run pauses: the durable-run store (ADR 0113), whose
+ * checkpoint boundary a journal append is, so a worker killed mid-script
+ * resumes from its last call (ADR 0137 item 8).
+ */
+export const JOURNAL_EVERY_CALL = Symbol.for('melchizedek.script.journalEveryCall');
+/** True when `sessions` asks for every journal event as its call ends. */
+export function journalsEveryCall(sessions) {
+    return !!sessions && typeof sessions === 'object' && sessions[JOURNAL_EVERY_CALL] === true;
+}
+/** True for a script's journal event. */
+export function isJournalEvent(event) {
+    return !!recordOf(event);
+}
+/** A canonical JSON text: object keys sorted, so a hash does not depend on key order. */
+function canonical(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+}
+/** The hash a call is matched on: its kind, name and arguments. */
+export function callHash(kind, name, args) {
+    return createHash('sha256').update(canonical([kind, name, args])).digest('hex').slice(0, 24);
+}
+/** The hash a run's source is pinned by. */
+export function sourceHash(source) {
+    return createHash('sha256').update(source).digest('hex').slice(0, 24);
+}
+/** The event for a call that returned (or threw into the script); `pin` on the first event a run stores call by call. */
+export function callEvent(script, invocationId, call, outcome, pin) {
+    return createTurnEvent({
+        author: script,
+        invocationId,
+        nodeInfo: { path: `${script}.${call.seq}` },
+        actions: { agentState: { [SCRIPT_CALL]: { ...call }, ...(pin ? { [SCRIPT_RUN]: { ...pin } } : {}) } },
+        output: outcome,
+    });
+}
+/** The marker a resumed run that ended leaves: its run is closed. */
+export function endEvent(script, invocationId, run, seq) {
+    return createTurnEvent({
+        author: script,
+        invocationId,
+        nodeInfo: { path: `${script}.${seq}` },
+        actions: { agentState: { [SCRIPT_CALL]: { run, seq, kind: 'end', name: 'end', hash: '' } } },
+    });
+}
+/** The event for an askUser that pauses the run: ADK's input request, stamped as a journal entry, with the pinned run. */
+export function pauseEvent(script, invocationId, call, pause, request) {
+    const event = requestInputEvent({ interruptId: pause.interrupt_id, message: request.message, payload: request.payload, ...(request.schema ? { responseSchema: request.schema } : {}) });
+    event.author = script;
+    event.invocationId = invocationId;
+    event.nodeInfo = { path: `${script}.${call.seq}` };
+    event.actions.agentState = { [SCRIPT_CALL]: { ...call }, [SCRIPT_PAUSE]: { ...pause } };
+    return event;
+}
+/**
+ * The event for a gated tool() call that pauses the run: ADK's approval
+ * request (`adk_request_confirmation`, lib/runtime/approvals.ts), pinning
+ * the call and its arguments, stamped as a journal entry, with the pinned run.
+ */
+export function approvalEvent(script, invocationId, call, pause, request) {
+    const originalFunctionCall = { name: request.tool, args: request.args ?? {}, id: `${call.run}.${call.seq}` };
+    return createTurnEvent({
+        author: script,
+        invocationId,
+        nodeInfo: { path: `${script}.${call.seq}` },
+        content: {
+            role: 'model',
+            parts: [{ functionCall: { name: APPROVAL_REQUEST, id: pause.interrupt_id, args: { originalFunctionCall, toolConfirmation: { hint: request.hint, confirmed: false } } } }],
+        },
+        actions: { agentState: { [SCRIPT_CALL]: { ...call }, [SCRIPT_PAUSE]: { ...pause, kind: 'approval' } } },
+    });
+}
+function recordOf(event) {
+    const rec = event.actions?.agentState?.[SCRIPT_CALL];
+    return rec && typeof rec.run === 'string' && typeof rec.seq === 'number' && typeof rec.kind === 'string' ? rec : undefined;
+}
+/** The run a conversation has open, or undefined: the last journal event decides (a pause, a call of a run stored call by call, or a closing `end`). */
+export function openRun(events, script) {
+    let last;
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        if (e.author === script && recordOf(e)) {
+            last = e;
+            break;
+        }
+    }
+    if (!last)
+        return undefined;
+    const lastRec = recordOf(last);
+    if (lastRec.kind === 'end')
+        return undefined;
+    const pause = last.actions.agentState?.[SCRIPT_PAUSE];
+    const run = lastRec.run;
+    const bySeq = new Map();
+    let pin = pause && typeof pause.source === 'string' ? pause : undefined;
+    for (const e of events) {
+        const rec = e.author === script ? recordOf(e) : undefined;
+        if (!rec || rec.run !== run)
+            continue;
+        const outcome = e.output;
+        const p = e.actions.agentState?.[SCRIPT_PAUSE];
+        const pinned = e.actions.agentState?.[SCRIPT_RUN];
+        if (!pin && pinned && typeof pinned.source === 'string')
+            pin = pinned;
+        const prior = bySeq.get(rec.seq);
+        bySeq.set(rec.seq, {
+            ...rec,
+            ...(outcome && typeof outcome === 'object' && ('value' in outcome || 'error' in outcome) ? { outcome } : prior?.outcome ? { outcome: prior.outcome } : {}),
+            ...(p ? { pause: p } : prior?.pause ? { pause: prior.pause } : {}),
+        });
+    }
+    if (!pin)
+        return undefined;
+    const entries = [...bySeq.values()].sort((a, b) => a.seq - b.seq);
+    // The last event a pause whose answer has not been stored: the run waits on it.
+    if (pause && typeof pause.source === 'string' && !bySeq.get(lastRec.seq)?.outcome)
+        return { state: 'paused', pin, pause, entries };
+    return { state: 'unfinished', pin, entries };
+}
+/**
+ * What a script run in a conversation waits on, read as a caller reads a
+ * nested syndicate's conversation (lib/runtime/native/interrupts.ts): the
+ * open pause of the run whose last event it is, as an approval request or a
+ * question, authored by the script. With `id`, only that request counts.
+ */
+export function scriptPauseIn(events, id) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        const rec = recordOf(e);
+        if (!rec || !e.author)
+            continue;
+        const pause = e.actions.agentState?.[SCRIPT_PAUSE];
+        if (!pause || e.output !== undefined || (id !== undefined && pause.interrupt_id !== id))
+            return undefined;
+        for (const call of getFunctionCalls(e)) {
+            if (call.id !== pause.interrupt_id)
+                continue;
+            if (call.name === APPROVAL_REQUEST)
+                return { asker: e.author, approval: approvalRequestOf(e, call) };
+            const question = inputRequestFrom(e.author, call);
+            if (question)
+                return { asker: e.author, question };
+        }
+        return undefined;
+    }
+    return undefined;
+}

package/dist/lib/script/run.d.ts

@@ -0,0 +1,138 @@
+/**
+ * lib/script/run.ts — one run of a syndicate's `script:` (ADR 0137 Part B):
+ * the script in the sandbox, its calls journaled, a paused or interrupted
+ * run resumed by replaying them.
+ *
+ * WHAT THE SCRIPT IS PASSED (item 6): `message`, `transcript` and
+ * `variables`, and the functions `agent`, `tool`, `askUser`, `now`,
+ * `random`, `log`, plus the sandbox's `parallel`. Nothing else reaches it.
+ * The host (lib/runtime/syndicateTurn.ts) supplies what `agent` and `tool`
+ * do; this module owns the journal, the replay, the pauses and the spans.
+ *
+ * REPLAY (item 9). A paused run's next message runs the script again from
+ * the top, on the source, message and transcript the run pinned. Each call
+ * is answered from the journal while one is recorded for it: a call is
+ * matched on its kind, its name and the hash of its arguments, the first
+ * unconsumed entry that matches, so concurrency under `parallel` (whose
+ * calls start in an order that depends on what finished first) replays the
+ * same. The open pause takes the person's answer; the calls after it run
+ * live. A run that ends with recorded calls it never made again diverged:
+ * it fails SCRIPT_DIVERGED, naming the first. Replayed calls are never
+ * charged again, open no span, and log() lines are not repeated while the
+ * run replays.
+ *
+ * THE PAUSES (items 8 and 10). A live askUser, and a tool() call to a tool
+ * in `script.require_approval`, let the calls already in flight settle,
+ * store the run's journal and the pause, then halt the sandbox; a call
+ * started after it waits forever and dies with the run, so a second pause
+ * is reached only once the first is answered. A question's answer is the
+ * next message (a JSON reply to a question with a schema is parsed, plain
+ * text passes as is, as an ask_user node's). An approval's answer is the
+ * decision: approved, the pinned arguments run; refused, the script gets
+ * `{ error }`, as a refused tool node's output is.
+ *
+ * WHEN THE JOURNAL IS STORED. Only a paused run reads it, so by default it
+ * is stored with the pause and a run that finishes stores none (on the
+ * Supabase store every append rewrites the session's events). A durable
+ * run's store (JOURNAL_EVERY_CALL, lib/runtime/native/checkpoint.ts) takes
+ * each event as its call ends, the first carrying the pin, and treats each
+ * as a checkpoint boundary, so a worker killed mid-script resumes from its
+ * last call. A resumed run that ends, and a durable run that finishes,
+ * store an `end` marker.
+ *
+ * THE SPANS (item 16). `script.invoke <name>` around the run and
+ * `script.call <kind>:<name>` around each live call, in their own trace,
+ * with no argument and no result on them; each agent() call's own turn
+ * span carries `script.run` and `script.call.seq` (the host adds them), so
+ * a trace view pairs them.
+ */
+import type { TurnEvent } from '../runtime/events.ts';
+import type { PendingApproval } from '../runtime/approvals.ts';
+import { SandboxHalt } from '../sandbox/sandbox.ts';
+import type { SandboxLimits } from '../sandbox/sandbox.ts';
+import type { PendingInput } from '../workflowConfig.ts';
+import type { JournalEntry } from './journal.ts';
+export { openRun, scriptPauseIn, SCRIPT_CALL, SCRIPT_PAUSE, SCRIPT_RUN } from './journal.ts';
+export type { JournalEntry, OpenRun, ScriptCallKind, ScriptCallOutcome, ScriptCallRecord, ScriptPauseRecord, ScriptPinRecord } from './journal.ts';
+/** The most calls one run may journal (item 13), as a walk has NODE_RUN_LIMIT. */
+export declare const SCRIPT_CALL_LIMIT = 1000;
+/** Where a call sits in its run: what the host stamps on an agent's span and lane. */
+export interface ScriptCallSite {
+    run: string;
+    seq: number;
+}
+/** What the turn runner gives a run. */
+export interface ScriptHost {
+    /** The script's name: every journal event's author and span's. */
+    script: string;
+    invocationId: string;
+    /** The conversation, for the spans. */
+    sessionId?: string;
+    /** Runs a declared agent; a plain Error is thrown into the script, a SandboxHalt ends the run. */
+    agent(name: string, input: unknown, opts: Record<string, unknown>, site: ScriptCallSite): Promise<unknown>;
+    /** Runs an allowed registry tool; errors as for agent. */
+    tool(name: string, args: unknown, site: ScriptCallSite): Promise<unknown>;
+    /** Whether a tool's calls wait for a person's approval (`script.require_approval`). */
+    gated?(name: string): boolean;
+    /** Appends a journal event to the conversation. */
+    append(event: TurnEvent): Promise<void>;
+    /** Every journal event as its call ends (a durable run), not only when the run pauses. */
+    journalEveryCall?: boolean;
+    /** Called once, before a pause is stored. */
+    beforePause?(): Promise<void>;
+    /** A `[STATUS]` progress line. */
+    log(text: string): void;
+    signal: AbortSignal;
+    newInterruptId?: () => string;
+}
+export interface ScriptRunInput {
+    source: string;
+    message: string;
+    transcript: string;
+    variables: Record<string, unknown>;
+    /**
+     * The run being resumed: its id and journal, and what the open pause
+     * takes: the person's answer to a question, or the decision on an
+     * approval. A run a stopped worker left (no pause) takes neither.
+     */
+    resume?: {
+        run: string;
+        entries: JournalEntry[];
+        answer?: string;
+        decision?: {
+            approved: boolean;
+        };
+    };
+    callLimit?: number;
+    limits?: Partial<SandboxLimits>;
+}
+export type ScriptRunOutcome = {
+    status: 'completed';
+    run: string;
+    value: unknown;
+    logs: string;
+} | {
+    status: 'paused';
+    run: string;
+    input: PendingInput;
+    logs: string;
+} | {
+    status: 'approval';
+    run: string;
+    approval: PendingApproval;
+    logs: string;
+} | {
+    status: 'failed';
+    run: string;
+    error: {
+        code: string;
+        message: string;
+    };
+    logs: string;
+};
+/** Fatal: thrown by a host function to fail the turn with a code. */
+export declare class ScriptFatal extends SandboxHalt {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function runScript(input: ScriptRunInput, host: ScriptHost): Promise<ScriptRunOutcome>;