@hunterzhu/pulse-runtime 0.1.0

package/dist/dsl/session.d.ts

@@ -0,0 +1,45 @@
+import type { PulseRuntime } from '../scheduler/runtime.js';
+import type { JsonValue, Outcome, RuntimeEvent } from '../core/types.js';
+export type SessionEventKind = 'fact' | 'observation' | 'gap' | 'snapshot';
+/**
+ * Session events use the DSL's `kind` field. `type` remains as a compatibility
+ * alias for the initial runtime API and is emitted with the same value.
+ */
+export interface SessionEvent {
+    kind: SessionEventKind;
+    type: SessionEventKind;
+    seq: number;
+    event?: RuntimeEvent;
+    observation?: JsonValue;
+    fromSeq?: number;
+    toSeq?: number;
+    snapshot?: JsonValue;
+}
+export interface PulseSessionSnapshot {
+    schemaVersion: 1;
+    agentId: string;
+    now: number;
+    eventSeq: number;
+    agent: JsonValue;
+    lanes: unknown[];
+    effects: unknown[];
+    waits: unknown[];
+    results: unknown[];
+    mergeProposals: unknown[];
+    quarantine: unknown[];
+    observationsPending: number;
+}
+export declare class PulseSession {
+    private readonly runtime;
+    readonly agentId: string;
+    private readonly execution;
+    /** Stable session handle used by the explicit warm-start API. */
+    readonly sessionId: string;
+    constructor(runtime: PulseRuntime, agentId: string);
+    private ownsEvent;
+    stream(fromSeq?: number): AsyncIterable<SessionEvent>;
+    snapshot(): Promise<PulseSessionSnapshot>;
+    outcome(): Promise<Outcome>;
+    reply(effectId: string, value: JsonValue): Promise<void>;
+    cancel(reason: string): Promise<void>;
+}

package/dist/dsl/session.js

@@ -0,0 +1,93 @@
+export class PulseSession {
+    runtime;
+    agentId;
+    execution;
+    /** Stable session handle used by the explicit warm-start API. */
+    sessionId;
+    constructor(runtime, agentId) {
+        this.runtime = runtime;
+        this.agentId = agentId;
+        this.sessionId = agentId;
+        this.execution = runtime.runAgent(agentId).then((result) => {
+            const root = runtime.state.lanes.get(runtime.state.agents.get(agentId)?.rootLaneId ?? '');
+            return {
+                status: result.status,
+                ...(root?.resultRef === undefined ? {} : { resultRef: root.resultRef }),
+                ...(root?.failure === undefined ? {} : { error: root.failure.error }),
+                ...(result.status === 'cancelled' && root?.cancelReason !== undefined ? { reason: root.cancelReason } : {}),
+                ...((result.unresolvedEffectIds ?? []).length ? { unresolvedEffectIds: [...(result.unresolvedEffectIds ?? [])] } : {}),
+            };
+        });
+    }
+    ownsEvent(event) {
+        if (event.agentId === this.agentId)
+            return true;
+        if (event.laneId !== undefined)
+            return this.runtime.state.lanes.get(event.laneId)?.agentId === this.agentId;
+        if (event.effectId !== undefined)
+            return this.runtime.state.effects.get(event.effectId)?.agentId === this.agentId;
+        return false;
+    }
+    async *stream(fromSeq = 0) {
+        let cursor = fromSeq;
+        let observationCursor = 0;
+        while (true) {
+            const oldest = this.runtime.state.events[0]?.seq;
+            const compactedThrough = this.runtime.state.eventsCompactedThrough ?? 0;
+            const gapEnd = oldest === undefined ? compactedThrough : oldest - 1;
+            if (cursor < gapEnd) {
+                yield { kind: 'gap', type: 'gap', seq: gapEnd, fromSeq: cursor + 1, toSeq: gapEnd };
+                cursor = gapEnd;
+            }
+            const events = this.runtime.state.events.filter((event) => event.seq > cursor);
+            for (const event of events) {
+                cursor = event.seq;
+                if (this.ownsEvent(event))
+                    yield { kind: 'fact', type: 'fact', seq: event.seq, event: structuredClone(event) };
+            }
+            const observationGapEnd = this.runtime.observationInbox.droppedThrough(this.agentId);
+            if (observationCursor < observationGapEnd) {
+                yield { kind: 'gap', type: 'gap', seq: observationGapEnd, fromSeq: observationCursor + 1, toSeq: observationGapEnd };
+                observationCursor = observationGapEnd;
+            }
+            for (const observation of this.runtime.observationInbox.drain(this.agentId)) {
+                observationCursor = Math.max(observationCursor, observation.seq);
+                yield { kind: 'observation', type: 'observation', seq: observation.seq, observation: observation };
+            }
+            const root = [...this.runtime.state.lanes.values()].find((lane) => lane.agentId === this.agentId && lane.ownerLaneId === undefined);
+            if (root && ['succeeded', 'failed', 'cancelled'].includes(root.status) && (this.runtime.state.events.at(-1)?.seq ?? compactedThrough) === cursor)
+                return;
+            await new Promise((resolve) => setImmediate(resolve));
+        }
+    }
+    async snapshot() {
+        const agent = this.runtime.state.agents.get(this.agentId);
+        const laneIds = new Set([...this.runtime.state.lanes.values()].filter((lane) => lane.agentId === this.agentId).map((lane) => lane.id));
+        const effects = [...this.runtime.state.effects.values()].filter((effect) => effect.agentId === this.agentId);
+        const effectIds = new Set(effects.map((effect) => effect.id));
+        return {
+            schemaVersion: 1,
+            agentId: this.agentId,
+            now: this.runtime.state.now,
+            eventSeq: this.runtime.state.events.at(-1)?.seq ?? 0,
+            agent: agent ? structuredClone({ id: agent.id, goal: agent.goal ?? null, state: agent.state ?? null, latestGlobalVersion: agent.latestGlobalVersion, globalVersions: [...agent.globalVersions.entries()].map(([version, value]) => ({ version, value, ...(agent.globalPrivacy?.get(version) === undefined ? {} : { privacy: agent.globalPrivacy.get(version) }) })) }) : null,
+            lanes: [...this.runtime.state.lanes.values()].filter((lane) => laneIds.has(lane.id)).map((lane) => structuredClone({ id: lane.id, agentId: lane.agentId, ownerLaneId: lane.ownerLaneId ?? null, status: lane.status, cancelReason: lane.cancelReason ?? null, failure: lane.failure ?? null, version: lane.version, goal: lane.goal, priority: lane.priority, inheritedFloor: lane.inheritedFloor ?? null, readySince: lane.readySince, resume: lane.resume, pendingResumeInput: lane.pendingResumeInput ?? null, contextSnapshotVersion: lane.contextSnapshotVersion, context: lane.context, visibleResultRefs: lane.visibleResultRefs ? [...lane.visibleResultRefs] : [], historyPressure: lane.historyPressure ?? null, activeWaitId: lane.activeWaitId ?? null, children: [...lane.children], ownedEffectIds: [...lane.ownedEffectIds], resultRef: lane.resultRef ?? null, closingResult: lane.closingResult ?? null, consecutiveControlErrors: lane.consecutiveControlErrors ?? 0, unresolvedEffectIds: lane.unresolvedEffectIds ?? [], progressWatchdog: lane.progressWatchdog ?? null })),
+            effects: effects.map((effect) => structuredClone(effect)),
+            waits: [...this.runtime.state.waits.values()].filter((wait) => laneIds.has(wait.laneId)).map((wait) => structuredClone(wait)),
+            results: [...this.runtime.state.results.values()].filter((result) => (result.effectId !== undefined && effectIds.has(result.effectId)) || [...this.runtime.state.lanes.values()].some((lane) => laneIds.has(lane.id) && lane.resultRef === result.id)).map((result) => structuredClone(result)),
+            mergeProposals: [...this.runtime.state.mergeProposals.values()].filter((proposal) => proposal.agentId === this.agentId).map((proposal) => structuredClone(proposal)),
+            quarantine: structuredClone(this.runtime.quarantine.snapshot().filter((entry) => effectIds.has(entry.effectId))),
+            observationsPending: this.runtime.observationInbox.snapshot().filter((observation) => observation.agentId === this.agentId).length,
+        };
+    }
+    async outcome() { return this.execution; }
+    async reply(effectId, value) {
+        const effect = this.runtime.state.effects.get(effectId);
+        if (!effect || effect.agentId !== this.agentId)
+            throw new Error('EFFECT_NOT_OWNED');
+        if (effect.kind !== 'human' || effect.outcome)
+            throw new Error('EFFECT_NOT_REPLYABLE');
+        this.runtime.enqueueHostCommand({ type: 'reply', agentId: this.agentId, effectId, value });
+    }
+    async cancel(reason) { this.runtime.requestCancel(this.agentId, reason); }
+}

package/dist/dsl/templates-index.d.ts

@@ -0,0 +1 @@
+export * from './templates.js';

package/dist/dsl/templates-index.js

@@ -0,0 +1 @@
+export * from './templates.js';

package/dist/dsl/templates.d.ts

@@ -0,0 +1,85 @@
+import { type LaneProgramDefinition, type StepContext, type InstructionView, type NextStepTarget, type StepInputs } from './program.js';
+import type { LaneProgram } from '../scheduler/runtime.js';
+import type { Outcome, JsonValue } from '../core/types.js';
+import type { ZodTypeAny } from 'zod';
+export interface ProgramRef {
+    programId: string;
+    programVersion: string;
+    step?: string;
+    locals?: JsonValue;
+}
+export declare function defineReActLane(config: {
+    id: string;
+    version?: string;
+    system?: string;
+    toolSet?: string;
+    task?: string;
+    instruction: string | ((view: InstructionView<JsonValue>) => string);
+    inputs?: (ctx: StepContext<JsonValue>) => StepInputs;
+    toolAllow?: string[];
+    maxTurns?: number;
+    outputSchema?: ZodTypeAny;
+    requirements?: Record<string, JsonValue>;
+    toolApproval?: {
+        prompt: string | ((calls: JsonValue, ctx: StepContext<JsonValue>) => string);
+        onDenied?: (reason: string, ctx: StepContext<JsonValue>) => NextStepTarget<JsonValue>;
+    };
+    historyCompaction?: {
+        summarizeTask: string;
+        keepRecentRounds: number;
+    };
+}): LaneProgramDefinition;
+export declare function defineSeriesLane(config: {
+    id: string;
+    version?: string;
+    steps: string[];
+} | {
+    id: string;
+    version?: string;
+    member: LaneProgram | ProgramRef;
+    keys?: string[];
+    onMemberFailure?: 'continue' | 'abort';
+}): LaneProgramDefinition;
+export interface PlanWorker extends ProgramRef {
+    goal?: string;
+}
+export interface PlanTask {
+    key: string;
+    goal: string;
+    affinityKey?: string;
+}
+export interface PlanDocument {
+    tasks: PlanTask[];
+}
+export interface PlanAndExecuteConfig {
+    id: string;
+    version?: string;
+    system?: string;
+    toolSet?: string;
+    planInstruction?: string;
+    planner?: {
+        task?: string;
+        instruction: string;
+        schema?: ZodTypeAny;
+    };
+    workers: Record<string, PlanWorker | {
+        goal: string;
+        programId: string;
+        programVersion?: string;
+    }>;
+    affinity?: 'collapse' | 'ack';
+    synthesizer?: {
+        task?: string;
+        instruction: string | ((ctx: StepContext) => string);
+        schema?: ZodTypeAny;
+    };
+}
+export declare function definePlanAndExecuteLane(config: PlanAndExecuteConfig): LaneProgramDefinition;
+export declare function defineScatterGatherLane<TItem>(config: {
+    id: string;
+    version?: string;
+    items: (ctx: StepContext) => TItem[];
+    worker: ProgramRef;
+    batch?: number;
+    reducer: (outcomes: Outcome[], ctx: StepContext) => NextStepTarget;
+}): LaneProgramDefinition;

package/dist/dsl/templates.js

@@ -0,0 +1,110 @@
+import { defineLaneProgram } from './program.js';
+export function defineReActLane(config) {
+    return defineLaneProgram({ id: config.id, version: config.version ?? '1', ...(config.system === undefined ? {} : { system: config.system }), ...(config.toolSet === undefined ? {} : { toolSet: config.toolSet }), ...(config.historyCompaction === undefined ? {} : { historyCompaction: config.historyCompaction }) }, (builder) => {
+        const onFinish = config.outputSchema === undefined
+            ? { text: (resultRef) => ({ complete: { value: { textRef: resultRef } } }) }
+            : { text: (resultRef) => ({ complete: { value: { textRef: resultRef } } }), structured: { schema: config.outputSchema, onParsed: (value) => ({ complete: { value: value } }) } };
+        builder.addReActLoopStep('react', { ...(config.task === undefined ? {} : { task: config.task }), instruction: config.instruction, ...(config.inputs === undefined ? {} : { inputs: config.inputs }), ...(config.toolAllow === undefined ? {} : { toolAllow: config.toolAllow }), ...(config.maxTurns === undefined ? {} : { maxTurns: config.maxTurns }), ...(config.outputSchema === undefined ? {} : { outputSchema: config.outputSchema }), ...(config.requirements === undefined ? {} : { requirements: config.requirements }), ...(config.toolApproval === undefined ? {} : { toolApproval: config.toolApproval }), onFinish });
+    });
+}
+export function defineSeriesLane(config) {
+    if ('steps' in config)
+        return defineLaneProgram({ id: config.id, version: config.version ?? '1' }, (builder) => { config.steps.forEach((step, index) => builder.addStep(step, () => ({ actions: [{ type: 'complete', result: { step } }], next: config.steps[index + 1] ?? 'finish' }))); builder.addStep('finish', () => ({ actions: [{ type: 'complete', result: { ok: true } }], next: 'finish' })); });
+    const member = config.member;
+    const ref = 'id' in member ? { programId: member.id, programVersion: member.version, step: member.entry ?? 'start', locals: {} } : { programId: member.programId, programVersion: member.programVersion, step: member.step ?? 'start', locals: member.locals ?? {} };
+    const wrapper = defineLaneProgram({ id: config.id, version: config.version ?? '1' }, (builder) => { builder.addStep('start', () => ({ actions: [{ type: 'complete', result: { results: {} } }], next: 'start' })); });
+    wrapper.entry = 'start';
+    wrapper.seriesMember = ref;
+    if ('id' in member && 'step' in member)
+        wrapper.seriesMemberProgram = member;
+    wrapper.seriesKeys = [...(config.keys ?? ['member'])];
+    wrapper.seriesOnMemberFailure = config.onMemberFailure ?? 'continue';
+    return wrapper;
+}
+const permissiveSchema = { safeParse: (value) => ({ success: true, data: value }) };
+function workerProgram(worker) {
+    return { programId: worker.programId, programVersion: worker.programVersion ?? '1', ...(!('step' in worker) || worker.step === undefined ? {} : { step: worker.step }), ...(!('locals' in worker) || worker.locals === undefined ? {} : { locals: worker.locals }) };
+}
+function plannedWorkers(config, ctx) {
+    const laneState = ctx.laneState;
+    const plan = laneState && typeof laneState === 'object' && !Array.isArray(laneState)
+        ? laneState.plan
+        : undefined;
+    const tasks = plan && typeof plan === 'object' && !Array.isArray(plan)
+        ? plan.tasks
+        : undefined;
+    // Keep the legacy permissive-planner behavior when no task list was declared.
+    // A typed planner schema produces `tasks` and therefore takes the dynamic path.
+    if (!Array.isArray(tasks))
+        return Object.fromEntries(Object.entries(config.workers).map(([key, worker]) => [key, { goal: 'goal' in worker && worker.goal !== undefined ? worker.goal : key, program: workerProgram(worker) }]));
+    const lanes = {};
+    for (const task of tasks) {
+        if (!task || typeof task !== 'object' || Array.isArray(task))
+            throw Object.assign(new Error('Planner task must be an object.'), { code: 'INVALID_PLAN' });
+        const entry = task;
+        const key = entry.key;
+        const goal = entry.goal;
+        if (typeof key !== 'string' || key.length === 0 || typeof goal !== 'string' || goal.length === 0)
+            throw Object.assign(new Error('Planner task requires a worker key and goal.'), { code: 'INVALID_PLAN' });
+        if (lanes[key] !== undefined || config.workers[key] === undefined)
+            throw Object.assign(new Error(`Planner task references an unavailable or duplicate worker: ${key}`), { code: 'INVALID_PLAN' });
+        const affinityKey = entry.affinityKey;
+        if (affinityKey !== undefined && (typeof affinityKey !== 'string' || affinityKey.length === 0))
+            throw Object.assign(new Error(`Planner task affinityKey must be a non-empty string: ${key}`), { code: 'INVALID_PLAN' });
+        lanes[key] = { goal, program: workerProgram(config.workers[key]), ...(affinityKey === undefined ? {} : { affinityKey }) };
+    }
+    return lanes;
+}
+export function definePlanAndExecuteLane(config) {
+    const planner = config.planner ?? { task: 'plan', instruction: config.planInstruction ?? 'Create an executable plan for the goal.' };
+    const synthesizer = config.synthesizer ?? { task: 'merge', instruction: 'Synthesize the joined worker outcomes into a concise final report.' };
+    return defineLaneProgram({ id: config.id, version: config.version ?? '1', ...(config.system === undefined ? {} : { system: config.system }), ...(config.toolSet === undefined ? {} : { toolSet: config.toolSet }) }, (builder) => {
+        builder.addStructuredLLMStep('plan', {
+            task: planner.task ?? 'plan',
+            instruction: planner.instruction,
+            schema: planner.schema ?? permissiveSchema,
+            onSuccess: (plan, ctx) => {
+                ctx.mutateLane((draft) => {
+                    if (draft && typeof draft === 'object' && !Array.isArray(draft))
+                        draft.plan = plan;
+                });
+                return 'dispatch';
+            },
+        });
+        builder.addDynamicForkStep('dispatch', {
+            lanes: (ctx) => plannedWorkers(config, ctx),
+            affinity: config.affinity === 'ack' ? 'ack' : 'collapse',
+            next: 'synthesize',
+        });
+        builder.addMergeStep('synthesize', {
+            task: synthesizer.task ?? 'merge',
+            instruction: synthesizer.instruction,
+            ...(synthesizer.schema === undefined ? {} : { schema: synthesizer.schema }),
+            sources: { proposals: 'joined', outcomes: 'joined' },
+            onSynthesized: (report, ctx) => {
+                ctx.commitGlobal({ ops: [{ op: 'set', path: ['synthesis'], value: report }], adoptImmediately: true });
+                return 'finish';
+            },
+            next: 'finish',
+        });
+        builder.addStep('finish', (ctx) => ({ actions: [{ type: 'complete', result: { ok: true, globalVersion: ctx.globalVersion } }], next: 'finish' }));
+    });
+}
+export function defineScatterGatherLane(config) {
+    const batch = Math.max(1, Math.floor(config.batch ?? 1));
+    return defineLaneProgram({ id: config.id, version: config.version ?? '1' }, (builder) => {
+        builder.addDynamicForkStep('scatter', {
+            lanes: (ctx) => {
+                const items = config.items(ctx);
+                const lanes = {};
+                for (let index = 0; index < items.length; index += batch) {
+                    const group = items.slice(index, index + batch);
+                    const key = `item-${index}`;
+                    lanes[key] = { goal: JSON.stringify(group), program: { ...config.worker, locals: { items: group } } };
+                }
+                return lanes;
+            }, affinity: 'ack', onJoin: (outcomes, ctx) => config.reducer([...outcomes.values()], ctx), next: 'finish',
+        });
+        builder.addStep('finish', (ctx) => ({ actions: [{ type: 'complete', result: { gathered: true, outcomes: (ctx.resumeInput?.type === 'wait' ? Object.fromEntries(Object.entries(ctx.resumeInput.resolution.dependencies).map(([key, value]) => [key, value.state === 'pending' ? null : value.outcome])) : {}) } }], next: 'finish' }));
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * from './core/types.js';
+export * from './core/errors.js';
+export * from './core/mutations.js';
+export * from './core/inbox.js';
+export * from './core/factory.js';
+export * from './transitions/index.js';
+export * from './dependencies/index.js';
+export * from './scheduler/index.js';
+export * from './scheduler/runtime.js';
+export * from './lifecycle/index.js';
+export * from './context/index.js';
+export * from './models/index.js';
+export * from './tools/registry.js';
+export * from './storage/index.js';
+export * from './dsl/index.js';

package/dist/index.js

@@ -0,0 +1,15 @@
+export * from './core/types.js';
+export * from './core/errors.js';
+export * from './core/mutations.js';
+export * from './core/inbox.js';
+export * from './core/factory.js';
+export * from './transitions/index.js';
+export * from './dependencies/index.js';
+export * from './scheduler/index.js';
+export * from './scheduler/runtime.js';
+export * from './lifecycle/index.js';
+export * from './context/index.js';
+export * from './models/index.js';
+export * from './tools/registry.js';
+export * from './storage/index.js';
+export * from './dsl/index.js';

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,2 @@
+export * from './scopes.js';
+export * from './watchdog.js';

package/dist/lifecycle/index.js

@@ -0,0 +1,2 @@
+export * from './scopes.js';
+export * from './watchdog.js';

package/dist/lifecycle/scopes.d.ts

@@ -0,0 +1,38 @@
+export declare class CancellationScope {
+    readonly ownerId: string;
+    readonly parent?: CancellationScope | undefined;
+    readonly children: Set<CancellationScope>;
+    cancelled: boolean;
+    reason?: string;
+    constructor(ownerId: string, parent?: CancellationScope | undefined);
+    cancel(reason?: string): void;
+    canCancel(target: CancellationScope): boolean;
+    dispose(): void;
+}
+export interface QuarantineEntry {
+    effectId: string;
+    unresolvedAt: number;
+    reason: string;
+}
+export declare class QuarantineScope {
+    private readonly entries;
+    add(effectId: string, unresolvedAt: number, reason?: string): void;
+    reconcile(effectId: string): boolean;
+    abandon(effectId: string): boolean;
+    has(effectId: string): boolean;
+    get unresolvedEffectIds(): string[];
+    snapshot(): QuarantineEntry[];
+    restore(entries: QuarantineEntry[]): void;
+    run<T>(work: () => T): {
+        value: T;
+        unresolvedEffectIds: string[];
+    };
+}
+export declare class HostCommandQueue {
+    private draining;
+    private readonly pending;
+    enqueue(command: () => void): void;
+    beginDrain(): void;
+    finishDrain(): void;
+    get size(): number;
+}

package/dist/lifecycle/scopes.js

@@ -0,0 +1,50 @@
+export class CancellationScope {
+    ownerId;
+    parent;
+    children = new Set();
+    cancelled = false;
+    reason;
+    constructor(ownerId, parent) {
+        this.ownerId = ownerId;
+        this.parent = parent;
+        parent?.children.add(this);
+    }
+    cancel(reason = 'USER_REQUESTED') { if (this.cancelled)
+        return; this.cancelled = true; this.reason = reason; for (const child of this.children)
+        child.cancel(reason); }
+    canCancel(target) { let current = target; while (current) {
+        if (current === this)
+            return true;
+        current = current.parent;
+    } return false; }
+    dispose() { this.parent?.children.delete(this); for (const child of this.children)
+        child.dispose(); this.children.clear(); }
+}
+export class QuarantineScope {
+    entries = new Map();
+    add(effectId, unresolvedAt, reason = 'cancel_grace_elapsed') { this.entries.set(effectId, { effectId, unresolvedAt, reason }); }
+    reconcile(effectId) { return this.entries.delete(effectId); }
+    abandon(effectId) { return this.entries.delete(effectId); }
+    has(effectId) { return this.entries.has(effectId); }
+    get unresolvedEffectIds() { return [...this.entries.keys()]; }
+    snapshot() { return [...this.entries.values()].map((entry) => ({ ...entry })); }
+    restore(entries) { for (const entry of entries)
+        this.entries.set(entry.effectId, { ...entry }); }
+    run(work) { return { value: work(), unresolvedEffectIds: this.unresolvedEffectIds }; }
+}
+export class HostCommandQueue {
+    draining = false;
+    pending = [];
+    enqueue(command) { if (this.draining)
+        this.pending.push(command);
+    else
+        command(); }
+    beginDrain() { this.draining = true; }
+    finishDrain() {
+        this.draining = false;
+        const commands = this.pending.splice(0);
+        for (const command of commands)
+            command();
+    }
+    get size() { return this.pending.length; }
+}

package/dist/lifecycle/watchdog.d.ts

@@ -0,0 +1,16 @@
+import type { LaneRecord, LaneStepOutput, ProgressWatchdogState, RuntimeError, RuntimeState } from '../core/types.js';
+export interface ProgressWatchdogOptions {
+    windowSize?: number;
+    noProgressThreshold?: number;
+    repeatedActionThreshold?: number;
+    admission?: boolean;
+}
+export interface ProgressObservation {
+    state: ProgressWatchdogState;
+    fingerprint: string;
+    progressed: boolean;
+    repeatedActionCount: number;
+    rejected?: RuntimeError;
+}
+export declare function progressFingerprint(lane: LaneRecord, output: LaneStepOutput, state: RuntimeState): string;
+export declare function observeProgress(lane: LaneRecord, output: LaneStepOutput, state: RuntimeState, previous?: ProgressWatchdogState, options?: ProgressWatchdogOptions): ProgressObservation;

package/dist/lifecycle/watchdog.js

@@ -0,0 +1,66 @@
+import { contentHash } from '../context/builder.js';
+import { provenanceRefId } from '../core/types.js';
+function withoutSdk(value) {
+    if (Array.isArray(value))
+        return value.map(withoutSdk);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value).filter(([key]) => key !== '$sdk').map(([key, item]) => [key, withoutSdk(item)]));
+}
+function canonical(value, key) {
+    if (key === 'id' || key === 'effectId' || key === 'attemptId' || key === 'toolCallId' || key === 'requestId' || key === 'providerId' || key === 'timestamp' || key === 'seq' || key === 'telemetry')
+        return null;
+    if (Array.isArray(value))
+        return value.map((item) => canonical(item));
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value).filter(([entryKey]) => entryKey !== 'derivedFrom').sort(([left], [right]) => left.localeCompare(right)).map(([entryKey, item]) => [entryKey, canonical(item, entryKey)]));
+}
+function actionSignature(output) {
+    return contentHash(output.actions.map((action) => canonical(action)));
+}
+function resultSignature(output, state) {
+    const refs = output.actions.flatMap((action) => 'derivedFrom' in action && action.derivedFrom ? action.derivedFrom : []);
+    const results = refs.map((ref) => {
+        const result = state.results.get(provenanceRefId(ref));
+        return result?.normalized ?? result?.value;
+    }).filter((value) => value !== undefined);
+    const terminalResults = output.actions.filter((action) => action.type === 'complete').map((action) => action.result);
+    const all = [...results, ...terminalResults];
+    return all.length ? contentHash(all.map((value) => canonical(value))) : undefined;
+}
+function progressKey(lane, output) {
+    return contentHash({ goal: canonical(lane.goal), contextVersion: lane.context.version, context: canonical(lane.context.state), resumeStep: output.next.step, localsHash: contentHash(withoutSdk(output.next.locals)) });
+}
+export function progressFingerprint(lane, output, state) {
+    const action = actionSignature(output);
+    const result = resultSignature(output, state);
+    return contentHash({ goalStateHash: contentHash({ goal: canonical(lane.goal), context: canonical(lane.context.state) }), contextVersion: lane.context.version, actionSignature: action, ...(result === undefined ? {} : { resultSignature: result }), resumeStep: output.next.step, localsHash: contentHash(withoutSdk(output.next.locals)) });
+}
+export function observeProgress(lane, output, state, previous, options = {}) {
+    const fingerprint = progressFingerprint(lane, output, state);
+    const windowSize = options.windowSize ?? 8;
+    const threshold = Math.max(1, options.noProgressThreshold ?? 3);
+    const repeatedThreshold = Math.max(1, options.repeatedActionThreshold ?? 3);
+    const prior = previous ?? { window: [], noProgressCount: 0, interventionLevel: 0 };
+    const action = actionSignature(output);
+    const progress = progressKey(lane, output);
+    const priorActions = prior.actionSignatures ?? [];
+    const priorProgress = prior.progressKeys ?? [];
+    const repeatedActionCount = priorActions.filter((candidate) => candidate === action).length + 1;
+    const sameProgress = priorProgress.at(-1) === progress;
+    const progressed = prior.lastFingerprint === undefined || !sameProgress;
+    const qualifies = sameProgress && priorActions.includes(action) && repeatedActionCount >= repeatedThreshold;
+    const noProgressCount = qualifies ? prior.noProgressCount + 1 : sameProgress ? prior.noProgressCount : 0;
+    const reached = qualifies && noProgressCount >= threshold;
+    if (reached && options.admission) {
+        const interventionLevel = Math.min(3, prior.interventionLevel + 1);
+        const rejection = { code: 'NO_PROGRESS_DETECTED', message: interventionLevel >= 3 ? 'Lane made no observable progress within the watchdog threshold.' : 'Lane repeated an action without material progress; change strategy before retrying.', details: { repeatedActionCount, noProgressCount, interventionLevel } };
+        return { fingerprint, progressed: false, repeatedActionCount, rejected: rejection, state: { ...prior, noProgressCount: 0, interventionLevel, lastReason: rejection.code } };
+    }
+    const interventionLevel = progressed ? 0 : Math.max(prior.interventionLevel, Math.min(3, Math.floor(noProgressCount / threshold)));
+    const window = [...prior.window, fingerprint].slice(-windowSize);
+    const actionSignatures = [...priorActions, action].slice(-windowSize);
+    const progressKeys = [...priorProgress, progress].slice(-windowSize);
+    return { fingerprint, progressed, repeatedActionCount, state: { window, actionSignatures, progressKeys, noProgressCount, interventionLevel, lastFingerprint: fingerprint, ...(interventionLevel === 0 ? {} : { lastReason: 'NO_PROGRESS_DETECTED' }) } };
+}

package/dist/models/actions.d.ts

@@ -0,0 +1,10 @@
+import type { PrivacyLabel, ProvenanceRef, RuntimeAction } from '../core/types.js';
+import type { LLMResult } from './router.js';
+export interface ActionDecoderOptions {
+    allowedTools: ReadonlySet<string>;
+    wait?: boolean;
+    llmEffectId?: string;
+    privacy?: PrivacyLabel;
+    derivedFrom?: ProvenanceRef[];
+}
+export declare function decodeLLMActions(result: LLMResult, options: ActionDecoderOptions): RuntimeAction[];

package/dist/models/actions.js

@@ -0,0 +1,68 @@
+import { validateActionToolCalls, validateAdapterResult } from './router.js';
+function toJsonValue(value, seen = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error('ACTION_INPUT_NOT_SERIALIZABLE');
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            throw new Error('ACTION_INPUT_NOT_SERIALIZABLE');
+        seen.add(value);
+        try {
+            return value.map((item) => toJsonValue(item, seen));
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    if (typeof value === 'object') {
+        if (value instanceof Uint8Array || value instanceof ArrayBuffer || value instanceof Date || Object.getPrototypeOf(value) !== Object.prototype || seen.has(value))
+            throw new Error('ACTION_INPUT_NOT_SERIALIZABLE');
+        seen.add(value);
+        try {
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, toJsonValue(item, seen)]));
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    throw new Error('ACTION_INPUT_NOT_SERIALIZABLE');
+}
+function cloneProvenanceRefs(refs) {
+    return refs === undefined ? undefined : refs.map((ref) => typeof ref === 'string' ? ref : { ...ref });
+}
+export function decodeLLMActions(result, options) {
+    validateAdapterResult(result);
+    validateActionToolCalls(result, options.allowedTools);
+    if (result.finishReason !== 'tool_calls')
+        return [];
+    if (result.toolCalls.length === 0)
+        throw new Error('INVALID_TOOL_CALL_FINISH_REASON');
+    const privacy = options.privacy ?? result.privacy;
+    const inheritedDerivedFrom = cloneProvenanceRefs(options.derivedFrom ?? result.derivedFrom);
+    return [{
+            type: 'submit_effects',
+            effects: result.toolCalls.map((call) => {
+                const derivedFrom = inheritedDerivedFrom === undefined ? undefined : cloneProvenanceRefs(inheritedDerivedFrom);
+                const input = { toolCallId: call.toolCallId, name: call.name, arguments: toJsonValue(call.input) };
+                if (privacy !== undefined)
+                    input.privacy = privacy;
+                if (derivedFrom !== undefined)
+                    input.derivedFrom = derivedFrom;
+                return {
+                    key: `tool:${call.toolCallId}`,
+                    toolCallId: call.toolCallId,
+                    ...(options.llmEffectId === undefined ? {} : { llmEffectId: options.llmEffectId }),
+                    ...(privacy === undefined ? {} : { privacy }),
+                    ...(derivedFrom === undefined ? {} : { derivedFrom }),
+                    kind: 'tool',
+                    concurrencyClass: 'tool',
+                    input,
+                };
+            }),
+            ...(options.wait === false ? {} : { wait: { onUnsatisfied: 'resume_with_error', reason: 'effect' } }),
+        }];
+}

package/dist/models/index.d.ts

@@ -0,0 +1,2 @@
+export * from './router.js';
+export * from './actions.js';

package/dist/models/index.js

@@ -0,0 +1,2 @@
+export * from './router.js';
+export * from './actions.js';