@nylorun/harness 0.5.0-beta.1 → 0.7.0-beta.1

package/dist/turn/runner.d.ts

@@ -1,9 +1,10 @@
-import type { InputEvent, SessionEvent, SessionSnapshot } from "../types/session.js";
+import type { ActiveExecutionRecord, InputEvent, SessionEvent, SessionRecord, SessionSnapshot } from "../types/session.js";
 import type { JsonObject, Tripwire } from "../types/shared.js";
 import type { RequiredInteraction } from "../types/tool.js";
 import type { LoopAgent } from "../build/agent.js";
 import type { ObserveEmit } from "../utils/observe.js";
 import { ToolPlanRunner } from "./plan-runner.js";
+import type { CapabilityStateRegistry } from "../session/capability-state.js";
 export interface PendingTurn {
     readonly plan: ToolPlanRunner;
     readonly turnId: string;
@@ -21,6 +22,12 @@ export type TurnProgress = {
     readonly state: SessionSnapshot;
     readonly pending: PendingTurn;
     readonly interaction: RequiredInteraction;
+} | {
+    readonly kind: "deferred";
+    readonly state: SessionSnapshot;
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly active: ActiveExecutionRecord;
 } | {
     readonly kind: "tripwire";
     readonly state: SessionSnapshot;
@@ -30,14 +37,18 @@ export type TurnProgress = {
 };
 export interface TurnRunContext {
     readonly signal: AbortSignal;
+    readonly states: CapabilityStateRegistry;
     readonly observe: ObserveEmit;
     readonly assertCurrent: () => void;
     readonly onPlanActive: (pending: PendingTurn | undefined) => void;
-    readonly onState: (state: SessionSnapshot) => void;
+    readonly commit: (state: SessionSnapshot, transition: SessionRecord["transition"], active?: ActiveExecutionRecord) => Promise<SessionSnapshot>;
     readonly onConversation: (event: SessionEvent) => void;
-    readonly claimInterrupts: (turnId: string) => readonly InputEvent[];
+    readonly claimInterrupts: (state: SessionSnapshot, turnId: string) => Promise<{
+        readonly state: SessionSnapshot;
+        readonly arrivals: readonly InputEvent[];
+    }>;
 }
-/** Advances one Turn until it finalizes, trips a policy, or pauses for an interaction. */
+/** Advances one Turn until it finalizes, trips policy, or reaches a waiting barrier. */
 export declare class TurnRunner {
     private readonly agent;
     private readonly sessionId;
@@ -47,7 +58,10 @@ export declare class TurnRunner {
         readonly context?: JsonObject;
     }>);
     start(state: SessionSnapshot, event: InputEvent, context: TurnRunContext): Promise<TurnProgress>;
+    continue(state: SessionSnapshot, context: TurnRunContext): Promise<TurnProgress>;
     resume(state: SessionSnapshot, pending: PendingTurn, event: InputEvent, context: TurnRunContext): Promise<TurnProgress>;
     private advance;
+    private waitForInteraction;
+    private waitForDeferred;
     private runPlan;
 }

package/dist/turn/runner.js

@@ -1,9 +1,9 @@
-import { beginTurn, commitCandidate, commitFinal, commitInput, commitToolResults, } from "../session/state.js";
+import { beginTurn, commitCandidate, commitFinal, commitToolResults, withStatus, } from "../session/state.js";
 import { runStep } from "../step/run.js";
 import { createId } from "../utils/ids.js";
 import { copyJson } from "../utils/immutable.js";
 import { ToolPlanRunner } from "./plan-runner.js";
-/** Advances one Turn until it finalizes, trips a policy, or pauses for an interaction. */
+/** Advances one Turn until it finalizes, trips policy, or reaches a waiting barrier. */
 export class TurnRunner {
     agent;
     sessionId;
@@ -15,19 +15,27 @@ export class TurnRunner {
     }
     async start(state, event, context) {
         const turnId = createId("turn");
-        const started = beginTurn(state, turnId, event);
-        context.onState(started);
+        state = await context.commit(beginTurn(state, turnId, event), "input");
         context.onConversation({ type: "input", event, turnId });
-        return this.advance(started, turnId, 1, [event], [], context);
+        return this.advance(state, turnId, 1, [event], [], context);
+    }
+    async continue(state, context) {
+        const turnId = createId("turn");
+        return this.advance(beginTurn(state, turnId), turnId, 1, [], [], context);
     }
     async resume(state, pending, event, context) {
+        const resume = pending.plan.interactionResume(event);
+        const active = pending.plan.activeInteractionRecord(pending.turnId, pending.stepId, resume);
+        state = await context.commit(withStatus(state, "running", undefined, active), "input", active);
         context.onConversation({ type: "input", event, turnId: pending.turnId });
         const progress = await this.runPlan(pending, context, event);
         if (progress.kind === "interaction-required")
-            return { kind: "interaction-required", state, pending, interaction: progress.interaction };
-        const afterTools = commitToolResults(state, pending.turnId, pending.stepId, progress.results);
-        context.onState(afterTools);
-        const claimed = claimAndRecord(afterTools, pending.turnId, context);
+            return this.waitForInteraction(state, pending, progress.interaction, context);
+        if (progress.kind === "deferred")
+            return this.waitForDeferred(state, pending, pending.plan.activeToolsRecord(pending.turnId, pending.stepId), context);
+        state = await context.commit(commitToolResults(state, pending.turnId, pending.stepId, progress.results), "tool-results");
+        pending.plan.publishSettlements(context.observe);
+        const claimed = await context.claimInterrupts(state, pending.turnId);
         return this.advance(claimed.state, pending.turnId, pending.stepNumber + 1, claimed.arrivals, progress.results, context);
     }
     async advance(initialState, turnId, firstStep, arrivals, initialResults, context) {
@@ -49,80 +57,100 @@ export class TurnRunner {
                 toolResults,
                 signal: context.signal,
                 session: this.session,
+                states: context.states,
+                recordModelRequested: (next, active) => context.commit(next, "model-requested", active),
             });
             context.assertCurrent();
+            state = run.state;
+            const pending = run.output.kind === "tools"
+                ? {
+                    plan: new ToolPlanRunner(run.output.plan),
+                    turnId,
+                    stepId,
+                    stepNumber,
+                }
+                : undefined;
             if (run.candidate) {
-                state = commitCandidate(state, turnId, stepId, run.candidate);
-                context.onState(state);
+                const active = pending?.plan.activeToolsRecord(turnId, stepId);
+                state = await context.commit(commitCandidate(state, turnId, stepId, run.candidate), "candidate", active);
+                context.observe({
+                    type: "model.completed",
+                    turnId,
+                    stepId,
+                    ...(run.requestedModelId === undefined ? {} : { requestedModelId: run.requestedModelId }),
+                    attributes: run.candidate,
+                });
                 context.onConversation({ type: "candidate", turnId, stepId, candidate: run.candidate });
             }
             if (run.output.kind === "tripwire")
                 return { kind: "tripwire", state, turnId, stepId, tripwire: run.output.tripwire };
-            if (run.output.kind === "final")
-                return {
-                    kind: "final",
-                    state: commitFinal(state, turnId, stepId, run.output.output),
-                    turnId,
-                    stepId,
-                    output: run.output.output,
-                };
-            const plan = run.output.plan;
+            if (run.output.kind === "deferred-model") {
+                state = await context.commit(withStatus(state, "waiting", undefined, run.output.active), "waiting", run.output.active);
+                return { kind: "deferred", state, turnId, stepId, active: run.output.active };
+            }
+            if (run.output.kind === "final") {
+                state = await context.commit(withStatus(commitFinal(state, turnId, stepId, run.output.output), "idle"), "final");
+                return { kind: "final", state, turnId, stepId, output: run.output.output };
+            }
+            const toolPlan = run.output.plan;
             context.observe(() => ({
                 type: "tool.sealed",
                 turnId,
                 stepId,
                 attributes: {
-                    executable: Object.freeze(plan.executable.map((entry) => Object.freeze({
+                    executable: Object.freeze(toolPlan.executable.map((entry) => Object.freeze({
                         callId: entry.call.callId,
                         toolName: entry.call.toolName,
                         args: copyJson(entry.call.args),
-                        executeWith: entry.call.executeWith,
                         invocationId: entry.invocationId,
-                        ...(entry.preflight === undefined ? {} : { preflight: entry.preflight }),
+                        owner: entry.owner,
                         ...(entry.interaction === undefined
                             ? {}
                             : { interaction: copyJson(entry.interaction) }),
                     }))),
-                    immediate: copyJson(plan.immediateResults),
+                    immediate: copyJson(toolPlan.immediateResults),
                 },
             }));
-            const pending = {
-                plan: new ToolPlanRunner(run.output.plan),
-                turnId,
-                stepId,
-                stepNumber,
-            };
             const progress = await this.runPlan(pending, context);
             if (progress.kind === "interaction-required")
-                return { kind: "interaction-required", state, pending, interaction: progress.interaction };
-            state = commitToolResults(state, turnId, stepId, progress.results);
-            context.onState(state);
-            const claimed = claimAndRecord(state, turnId, context);
+                return this.waitForInteraction(state, pending, progress.interaction, context);
+            if (progress.kind === "deferred")
+                return this.waitForDeferred(state, pending, pending.plan.activeToolsRecord(turnId, stepId), context);
+            state = await context.commit(commitToolResults(state, turnId, stepId, progress.results), "tool-results");
+            pending.plan.publishSettlements(context.observe);
+            const claimed = await context.claimInterrupts(state, turnId);
             state = claimed.state;
             stepArrivals = claimed.arrivals;
             toolResults = progress.results;
         }
     }
+    async waitForInteraction(state, pending, interaction, context) {
+        const active = pending.plan.activeInteractionRecord(pending.turnId, pending.stepId);
+        state = await context.commit(withStatus(state, "waiting", interaction, active), "waiting", active);
+        pending.plan.publishSettlements(context.observe);
+        return { kind: "interaction-required", state, pending, interaction };
+    }
+    async waitForDeferred(state, pending, active, context) {
+        state = await context.commit(withStatus(state, "waiting", undefined, active), "waiting", active);
+        pending.plan.publishSettlements(context.observe);
+        return {
+            kind: "deferred",
+            state,
+            turnId: pending.turnId,
+            stepId: pending.stepId,
+            active,
+        };
+    }
     async runPlan(pending, context, resume) {
         context.onPlanActive(pending);
         const progress = await pending.plan.run({
-            adapters: this.agent.adapters,
             signal: context.signal,
             observe: context.observe,
             ids: { sessionId: this.sessionId, turnId: pending.turnId, stepId: pending.stepId },
+            states: context.states,
         }, resume);
         context.assertCurrent();
         context.onPlanActive(undefined);
         return progress;
     }
 }
-function claimAndRecord(state, turnId, context) {
-    const arrivals = context.claimInterrupts(turnId);
-    if (arrivals.length === 0)
-        return { state, arrivals };
-    let next = state;
-    for (const event of arrivals)
-        next = commitInput(next, turnId, event);
-    context.onState(next);
-    return { state: next, arrivals };
-}

package/dist/types/manifest.d.ts

@@ -1,15 +1,9 @@
 import type { BoundMiddleware } from "./middleware.js";
-import type { ModelDirective } from "./model.js";
 import type { BuildDiagnostic } from "./shared.js";
 export interface AgentManifest {
     readonly middleware: readonly {
         readonly id: string;
     }[];
-    readonly model?: ModelDirective;
-    readonly adapters: readonly {
-        readonly id: string;
-        readonly maxConcurrentCalls?: number;
-    }[];
 }
 export type BuildResult<Agent> = {
     readonly ok: true;

package/dist/types/middleware.d.ts

@@ -1,5 +1,5 @@
 import type { ContextMutationOptions, ModelCandidate, ModelDirective, ModelToolCall, ModelConfigurationMutationOptions } from "./model.js";
-import type { InputEvent, TranscriptEntry } from "./session.js";
+import type { InputEvent, SessionIdentity, TranscriptEntry } from "./session.js";
 import type { ContextItem, JsonObject, Tripwire } from "./shared.js";
 import type { Interaction, ToolDefinition, ToolResult } from "./tool.js";
 export interface StepInput {
@@ -18,7 +18,7 @@ export interface StepInput {
     readonly toolResults: readonly ToolResult[];
     readonly transcript: readonly TranscriptEntry[];
 }
-export interface StepRequest {
+interface StepRequestBase {
     /** Opaque identity of the Session that owns this Step. */
     readonly sessionId: string;
     /** Opaque identity of the Turn that owns this Step. */
@@ -49,17 +49,38 @@ export interface StepRequest {
     };
     tripwire(error: Tripwire): StepResponse;
 }
+export type StepRequest<State = never> = StepRequestBase & ([State] extends [never] ? object : {
+    readonly state: Promise<State>;
+});
 export interface StepResponse {
     candidate(): Readonly<ModelCandidate> | undefined;
     toolCalls(): readonly ModelToolCall[];
     replace(candidate: ModelCandidate): void;
     deny(callId: string, reason: string): void;
     requireInteraction(callId: string, interaction: Interaction): void;
-    requirePreflight(callId: string, kind: "sandbox" | "validation"): void;
     tripwire(error: Tripwire): StepResponse;
 }
-export type StepMiddleware = (request: StepRequest, next: () => Promise<StepResponse>) => Promise<StepResponse>;
+export type StepMiddleware<State = never> = (request: StepRequest<State>, next: () => Promise<StepResponse>) => Promise<StepResponse>;
+export interface CapabilityState<State> {
+    create(session: SessionIdentity, signal: AbortSignal): State | Promise<State>;
+    dispose?(value: State): void | Promise<void>;
+}
+export type CapabilityItems<Item> = readonly Item[] | Readonly<{
+    readonly slot: string;
+    readonly items: readonly Item[];
+}>;
+/** A named capability that may supply static model surface and one typed middleware handler. */
+export interface CapabilityDeclaration<State = never> {
+    readonly id: string;
+    readonly tools?: CapabilityItems<ToolDefinition<ToolDefinition["parameters"], State>>;
+    readonly instructions?: CapabilityItems<string>;
+    readonly model?: ModelDirective;
+    readonly state?: CapabilityState<State>;
+    readonly middleware?: StepMiddleware<State>;
+}
 export interface BoundMiddleware {
     readonly id: string;
     readonly handle: StepMiddleware;
+    readonly state?: CapabilityState<unknown>;
 }
+export {};

package/dist/types/model.d.ts

@@ -1,4 +1,4 @@
-import type { ContextItem, JsonObject } from "./shared.js";
+import type { ContextItem, DeferredOutcome, JsonObject } from "./shared.js";
 import type { InputEvent, TranscriptEntry } from "./session.js";
 import type { BoundToolDefinition, ToolResult } from "./tool.js";
 export interface ModelToolCall {
@@ -161,6 +161,7 @@ export interface ModelCall {
 }
 export interface ModelAdapterContext {
     readonly request: ModelRequest;
+    readonly invocationId: string;
     readonly signal: AbortSignal;
 }
-export type ModelAdapter = (call: ModelCall, context: ModelAdapterContext) => Promise<ModelCandidate | string>;
+export type ModelAdapter = (call: ModelCall, context: ModelAdapterContext) => Promise<ModelCandidate | string | DeferredOutcome>;

package/dist/types/session.d.ts

@@ -1,6 +1,6 @@
-import type { ModelCandidate } from "./model.js";
+import type { ModelCall, ModelCandidate } from "./model.js";
 import type { JsonObject, JsonValue, Observer, Tripwire } from "./shared.js";
-import type { RequiredInteraction, ToolResult } from "./tool.js";
+import type { RequiredInteraction, ToolExecutionResume, ToolOwner, ToolResult } from "./tool.js";
 export type InputEvent = {
     readonly kind: "user-message";
     readonly text: string;
@@ -39,6 +39,10 @@ export type SessionEvent = {
     readonly type: "tripwire";
     readonly tripwire: Tripwire;
     readonly turnId: string;
+} | {
+    readonly type: "execution.deferred";
+    readonly active: ActiveExecutionRecord;
+    readonly turnId: string;
 } | {
     readonly type: "input.queued";
     readonly inputId: string;
@@ -67,7 +71,23 @@ export interface SessionOptions {
     readonly id?: string;
     readonly userId?: string;
     readonly context?: JsonObject;
+    readonly seed?: never;
+    readonly recorder?: SessionRecorder;
+}
+/** Stable host-owned facts available while a capability creates session-local state. */
+export interface SessionIdentity {
+    readonly id: string;
+    readonly userId?: string;
+    readonly context?: JsonObject;
+}
+export interface SeededSessionOptions {
+    readonly seed: SessionSeed;
+    readonly recorder?: SessionRecorder;
+    readonly id?: never;
+    readonly userId?: never;
+    readonly context?: never;
 }
+export type SessionRunOptions = SessionOptions | SeededSessionOptions;
 export interface InputOptions {
     readonly signal?: AbortSignal;
 }
@@ -108,14 +128,78 @@ export interface SessionSnapshot {
     readonly id: string;
     readonly status: "idle" | "running" | "waiting" | "stopped";
     readonly turnCount: number;
+    readonly revision: number;
     readonly transcript: readonly TranscriptEntry[];
     readonly pendingInteraction?: RequiredInteraction;
+    readonly active?: ActiveExecutionRecord;
+}
+export interface SessionSeed {
+    readonly id?: string;
+    readonly userId?: string;
+    readonly context?: JsonObject;
+    readonly turnCount?: number;
+    readonly revision?: number;
+    readonly transcript: readonly TranscriptEntry[];
+}
+export interface ActiveModelExecutionRecord {
+    readonly kind: "model";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly invocationId: string;
+    readonly call: ModelCall;
+    readonly token?: JsonValue;
+}
+export interface ActiveToolCallRecord {
+    readonly callId: string;
+    readonly toolName: string;
+    readonly args: JsonValue;
+    readonly invocationId: string;
+    readonly owner: ToolOwner;
+    readonly status: "pending" | "settled" | "deferred";
+    readonly result?: ToolResult;
+    readonly token?: JsonValue;
+}
+export interface ActiveToolsExecutionRecord {
+    readonly kind: "tools";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly calls: readonly ActiveToolCallRecord[];
+}
+export interface ActiveInteractionExecutionRecord {
+    readonly kind: "interaction";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly callId: string;
+    readonly toolName: string;
+    readonly interaction: RequiredInteraction;
+    readonly token?: JsonValue;
+    readonly resume?: ToolExecutionResume;
+    readonly tools: ActiveToolsExecutionRecord;
+}
+export type ActiveExecutionRecord = ActiveModelExecutionRecord | ActiveToolsExecutionRecord | ActiveInteractionExecutionRecord;
+export interface SessionRecord {
+    readonly version: 1;
+    readonly revision: number;
+    readonly transition: "input" | "model-requested" | "candidate" | "tool-results" | "waiting" | "final" | "stopped";
+    readonly session: {
+        readonly id: string;
+        readonly userId?: string;
+        readonly context?: JsonObject;
+        readonly turnCount: number;
+        readonly status: SessionSnapshot["status"];
+    };
+    readonly transcript: readonly TranscriptEntry[];
+    readonly active?: ActiveExecutionRecord;
+}
+export interface SessionRecorder {
+    record(value: SessionRecord): Promise<void>;
 }
 export interface Session {
     readonly id: string;
     readonly state: SessionSnapshot;
     input(event: SessionInput, options?: InputOptions): InputHandle;
     interrupt(event: MessageInput, options?: InputOptions): InputHandle;
+    continue(options?: InputOptions): InputHandle;
     stream(): AsyncIterable<SessionEvent>;
     observe(listener: Observer): () => void;
     stop(reason?: string): Promise<void>;

package/dist/types/shared.d.ts

@@ -6,6 +6,10 @@ export type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
 export type JsonObject = {
     readonly [key: string]: JsonValue;
 };
+export interface DeferredOutcome {
+    readonly kind: "deferred";
+    readonly token?: JsonValue;
+}
 export interface BuildDiagnostic {
     readonly code: string;
     readonly message: string;
@@ -25,7 +29,10 @@ export interface Tripwire {
 export interface ObserveToolSnapshot {
     readonly name: string;
     readonly description?: string;
-    readonly executeWith: string;
+    readonly owner: {
+        readonly middlewareId: string;
+        readonly slot: string;
+    };
     readonly parameters: {
         readonly jsonSchema: JsonObject;
     };
@@ -38,9 +45,11 @@ export interface ObserveSealedCall {
     readonly callId: string;
     readonly toolName: string;
     readonly args: JsonValue;
-    readonly executeWith: string;
     readonly invocationId: string;
-    readonly preflight?: "sandbox" | "validation";
+    readonly owner: {
+        readonly middlewareId: string;
+        readonly slot: string;
+    };
     readonly interaction?: RequiredInteraction;
 }
 export interface ObserveModelRequested {
@@ -54,6 +63,25 @@ export interface ObserveModelRequested {
 export type ObserveEvent = {
     readonly type: "session.stopped";
     readonly reason: string;
+} | {
+    readonly type: "capability.state.dispose.failed";
+    readonly capabilityId: string;
+    readonly attributes: {
+        readonly message: string;
+    };
+} | {
+    readonly type: "session.seeded";
+    readonly revision: number;
+    readonly transcriptEntries: number;
+} | {
+    readonly type: "session.continued";
+    readonly inputId?: string;
+} | {
+    readonly type: "session.record.failed";
+    readonly code: string;
+    readonly attributes: {
+        readonly message: string;
+    };
 } | {
     readonly type: "input.received";
     readonly inputId: string;
@@ -83,6 +111,15 @@ export type ObserveEvent = {
     readonly inputId?: string;
     readonly requestedModelId?: string;
     readonly attributes: ModelCandidate;
+} | {
+    readonly type: "model.deferred";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly invocationId: string;
+    readonly attributes: {
+        readonly token?: JsonValue;
+    };
 } | {
     readonly type: "step.started";
     readonly turnId: string;
@@ -122,28 +159,47 @@ export type ObserveEvent = {
         readonly immediate: readonly ToolResult[];
     };
 } | {
-    readonly type: "adapter.preflight.started" | "adapter.started";
+    readonly type: "tool.started";
+    readonly sessionId: string;
     readonly turnId: string;
     readonly stepId: string;
     readonly inputId?: string;
-    readonly adapterId: string;
     readonly toolName: string;
     readonly callId: string;
-    readonly invocationId?: string;
+    readonly invocationId: string;
+    readonly middlewareId: string;
+    readonly slot: string;
     readonly attributes: {
         readonly args: JsonValue;
     };
 } | {
-    readonly type: "adapter.preflight.completed" | "adapter.completed";
+    readonly type: "tool.completed";
+    readonly sessionId: string;
     readonly turnId: string;
     readonly stepId: string;
     readonly inputId?: string;
-    readonly adapterId: string;
     readonly toolName: string;
     readonly callId: string;
+    readonly invocationId: string;
+    readonly middlewareId: string;
+    readonly slot: string;
     readonly outcome: string;
     readonly code?: string;
     readonly attributes?: ToolResult;
+} | {
+    readonly type: "tool.deferred";
+    readonly sessionId: string;
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly toolName: string;
+    readonly callId: string;
+    readonly invocationId: string;
+    readonly middlewareId: string;
+    readonly slot: string;
+    readonly attributes: {
+        readonly token?: JsonValue;
+    };
 } | {
     readonly type: "turn.completed";
     readonly turnId: string;
@@ -161,7 +217,7 @@ export type ObserveEvent = {
     readonly kind: string;
     readonly callId?: string;
     readonly toolName?: string;
-    readonly phase?: "interaction" | "preflight" | "execute";
+    readonly phase?: "interaction" | "execute";
     readonly attributes: {
         readonly prompt: string;
         readonly metadata?: JsonObject;