@nylorun/harness 0.9.0-beta.1 → 0.11.1-beta

package/dist/session/session.js

@@ -1,6 +1,8 @@
+import { HarnessError } from "../errors.js";
 import { SessionScheduler } from "./scheduler.js";
-import { copyJsonObject } from "../utils/immutable.js";
+import { copyJson, copyJsonObject } from "../utils/immutable.js";
 import { normalizeSessionSeed } from "./seed.js";
+import { bindOutputContract } from "./output-contract.js";
 export class LiveSession {
     id;
     scheduler;
@@ -24,7 +26,13 @@ export class LiveSession {
         return this.scheduler.snapshot;
     }
     input(event, options) {
-        return this.scheduler.submit(normalizeInput(event), options);
+        const output = options?.outputSchema === undefined ? undefined : bindOutputContract(options.outputSchema);
+        if (output && isInteractionReply(event))
+            throw new HarnessError("output.invalid-schema", "Interaction replies cannot define a turn outputSchema");
+        return this.scheduler.submit(normalizeInput(event), {
+            ...(options?.signal === undefined ? {} : { signal: options.signal }),
+            ...(output === undefined ? {} : { output }),
+        });
     }
     interrupt(event, options) {
         return this.scheduler.submit(normalizeMessage("interrupt", event), options);
@@ -50,6 +58,14 @@ function isInteractionReply(value) {
 function normalizeMessage(kind, value) {
     if (typeof value === "string")
         return { kind, text: value };
+    if ("content" in value)
+        return {
+            kind,
+            content: snapshotContent(value.content),
+            ...(value.metadata === undefined
+                ? {}
+                : { metadata: copyJsonObject(value.metadata, "input metadata") }),
+        };
     return {
         kind,
         text: value.text,
@@ -65,3 +81,23 @@ function normalizeInput(input) {
         return input;
     return normalizeMessage("user-message", input);
 }
+function snapshotContent(value) {
+    if (!Array.isArray(value))
+        throw new HarnessError("input.invalid-content", "Input content must be an array");
+    return Object.freeze(value.map((part, index) => {
+        if (!part || typeof part !== "object")
+            throw new HarnessError("input.invalid-content", `Input content part ${index} must be an object`);
+        if (part.type === "text") {
+            if (typeof part.text !== "string")
+                throw new HarnessError("input.invalid-content", `Input text part ${index} must contain text`);
+            return Object.freeze({ type: "text", text: part.text });
+        }
+        if (part.type !== "media" || typeof part.mediaType !== "string" || part.mediaType === "")
+            throw new HarnessError("input.invalid-content", `Input media part ${index} must contain a non-empty mediaType`);
+        return Object.freeze({
+            type: "media",
+            mediaType: part.mediaType,
+            reference: copyJson(part.reference),
+        });
+    }));
+}

package/dist/session/state.d.ts

@@ -12,4 +12,4 @@ export declare function beginTurn(state: SessionSnapshot, turnId: string, event?
 export declare const commitInput: (state: SessionSnapshot, turnId: string, event: InputEvent) => SessionSnapshot;
 export declare const commitCandidate: (state: SessionSnapshot, turnId: string, stepId: string, candidate: ModelCandidate) => SessionSnapshot;
 export declare const commitToolResults: (state: SessionSnapshot, turnId: string, stepId: string, results: readonly ToolResult[]) => SessionSnapshot;
-export declare const commitFinal: (state: SessionSnapshot, turnId: string, stepId: string, output: string) => SessionSnapshot;
+export declare const commitFinal: (state: SessionSnapshot, turnId: string, stepId: string, output: import("../types/shared.js").JsonValue) => SessionSnapshot;

package/dist/session/submission-stream.d.ts

@@ -1,15 +1,16 @@
 import type { InputCompletion, InputHandle, SessionEvent } from "../types/session.js";
-export declare class SubmissionStream implements InputHandle {
+import type { JsonValue } from "../types/shared.js";
+export declare class SubmissionStream implements InputHandle<JsonValue> {
     readonly inputId: string;
-    readonly completed: Promise<InputCompletion>;
+    readonly completed: Promise<InputCompletion<JsonValue>>;
     private resolveCompletion;
     private rejectCompletion;
     private readonly events;
     private readonly cleanups;
     private done;
     constructor(inputId: string);
-    emit(event: SessionEvent): void;
-    finish(status: InputCompletion["status"]): void;
+    emit(event: SessionEvent<JsonValue>): void;
+    finish(status: InputCompletion<JsonValue>["status"]): void;
     fail(error: unknown): void;
     onFinish(cleanup: () => void): void;
 }

package/dist/step/canonicalize.js

@@ -38,6 +38,9 @@ export function canonicalizeOutput(output) {
                 id: call.id,
                 name: call.name,
                 args: call.args,
+                ...(block.providerMetadata === undefined
+                    ? {}
+                    : { providerMetadata: block.providerMetadata }),
                 ...(block.raw === undefined ? {} : { raw: block.raw }),
             });
         })),

package/dist/step/context-draft.js

@@ -1,5 +1,4 @@
 import { HarnessError } from "../errors.js";
-import { digest } from "../utils/digest.js";
 import { copyJson } from "../utils/immutable.js";
 import { SlotDraft } from "./slot-assembly.js";
 const CONTEXT_TYPE = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
@@ -36,7 +35,7 @@ export class ContextDraft {
             ...(this.hostContext === undefined ? [] : [hostContributor()]),
             ...slots.map((slot) => contributor(slot.owner, slot.reason)),
         ]);
-        return Object.freeze({ items, contributors, digest: digest(items.map(itemDigest)) });
+        return Object.freeze({ items, contributors });
     }
 }
 function normalizeItem(item) {
@@ -54,7 +53,6 @@ function hostContributor() {
         middlewareId: "host",
         slot: "session",
         order: 0,
-        digest: digest({ middlewareId: "host", slot: "session", order: 0 }),
     });
 }
 function contributor(owner, reason) {
@@ -62,10 +60,6 @@ function contributor(owner, reason) {
         middlewareId: owner.middlewareId,
         slot: owner.slot,
         order: owner.order,
-        digest: digest({ middlewareId: owner.middlewareId, slot: owner.slot, order: owner.order }),
         ...(reason === undefined ? {} : { reason }),
     });
 }
-function itemDigest(item) {
-    return item.type === undefined ? { value: item.value } : { type: item.type, value: item.value };
-}

package/dist/step/model-configuration.js

@@ -1,7 +1,6 @@
 import { bindTool } from "../build/bind-tool.js";
 import { HarnessError, isHarnessError } from "../errors.js";
 import { normalizeDirective, sameDirective } from "../model/normalize.js";
-import { digest } from "../utils/digest.js";
 import { copyJson } from "../utils/immutable.js";
 import { checkedReason, slotOwner, SlotDraft } from "./slot-assembly.js";
 /** Per-step, middleware-owned model configuration draft. It never persists past the call. */
@@ -80,7 +79,6 @@ export class ModelConfigurationDraft {
         const toolSlots = this.#tools.values();
         const instructions = instructionSlots.flatMap((slot) => slot.value.map((text) => Object.freeze({
             text,
-            digest: digest(text),
             contributor: contributor(slot.owner, slot.reason),
         })));
         const sourcedTools = toolSlots.flatMap((slot) => slot.value.map((tool) => Object.freeze({ tool, contributor: contributor(slot.owner, slot.reason) })));
@@ -95,15 +93,6 @@ export class ModelConfigurationDraft {
             throw new HarnessError("configuration.duplicate-tool-name", `Duplicate Tool '${[...duplicate].sort().join("', '")}'`);
         const toolContracts = sourcedTools.map(({ tool, contributor: source }) => toolContract(tool, source));
         const model = this.#model?.directive;
-        const logical = digest({
-            instructions: instructions.map((item) => item.text),
-            tools: toolContracts.map(({ name, description, inputSchema }) => ({
-                name,
-                ...(description === undefined ? {} : { description }),
-                inputSchema,
-            })),
-        });
-        const modelDigest = digest(model ?? null);
         return Object.freeze({
             version: 1,
             ...(model === undefined ? {} : { model }),
@@ -115,11 +104,6 @@ export class ModelConfigurationDraft {
                 ...toolSlots.map((slot) => contributor(slot.owner, slot.reason)),
                 ...(this.#model?.owner ? [contributor(this.#model.owner, this.#model.reason)] : []),
             ]),
-            digests: Object.freeze({
-                logical,
-                model: modelDigest,
-                request: digest({ logical, model: modelDigest }),
-            }),
         });
     }
 }
@@ -134,7 +118,6 @@ function contributor(owner, reason) {
         middlewareId: owner.middlewareId,
         slot: owner.slot,
         order: owner.order,
-        digest: digest({ middlewareId: owner.middlewareId, slot: owner.slot, order: owner.order }),
         ...(reason === undefined ? {} : { reason }),
     });
 }
@@ -142,10 +125,13 @@ function providerTool(tool) {
     return {
         name: tool.name,
         ...(tool.description === undefined ? {} : { description: tool.description }),
-        inputSchema: copyJson(tool.parameters.jsonSchema),
+        inputSchema: copyJson(tool.inputSchema.jsonSchema),
+        ...(tool.outputSchema === undefined
+            ? {}
+            : { outputSchema: copyJson(tool.outputSchema.jsonSchema) }),
     };
 }
 function toolContract(tool, source) {
     const value = providerTool(tool);
-    return Object.freeze({ ...value, digest: digest(value), contributor: source });
+    return Object.freeze({ ...value, contributor: source });
 }

package/dist/step/project.js

@@ -9,9 +9,10 @@ export function projectModelCall(request) {
         tools: Object.freeze(request.configuration.tools.map((tool) => Object.freeze({
             name: tool.name,
             ...(tool.description === undefined ? {} : { description: tool.description }),
-            inputSchema: copyJson(tool.parameters.jsonSchema),
+            inputSchema: copyJson(tool.inputSchema.jsonSchema),
         }))),
         ...(request.model === undefined ? {} : { model: copyJson(request.model) }),
+        ...(request.outputSchema === undefined ? {} : { outputSchema: copyJson(request.outputSchema) }),
         sessionId: request.sessionId,
     });
 }
@@ -45,12 +46,29 @@ function projectEntry(entry) {
     if (entry.kind === "input") {
         if (entry.event.kind !== "user-message" && entry.event.kind !== "interrupt")
             return [];
-        return [freezeItem({ kind: "message", role: "user", content: [textPart(entry.event.text)] })];
+        return [
+            freezeItem({
+                kind: "message",
+                role: "user",
+                content: "content" in entry.event
+                    ? entry.event.content.map((part) => part.type === "text"
+                        ? textPart(part.text)
+                        : Object.freeze({
+                            type: "media",
+                            mediaType: part.mediaType,
+                            reference: copyJson(part.reference),
+                        }))
+                    : [textPart(entry.event.text)],
+            }),
+        ];
     }
     if (entry.kind === "candidate") {
         const content = entry.candidate.output.flatMap((block) => {
-            if (block.type === "text")
-                return [textPart(block.text)];
+            if (block.type === "text" ||
+                (block.type === "reasoning" && block.providerMetadata !== undefined))
+                return [Object.freeze({ ...block })];
+            if (block.type === "json")
+                return [textPart(JSON.stringify(block.value))];
             if (block.type === "tool-call")
                 return [
                     Object.freeze({
@@ -58,6 +76,9 @@ function projectEntry(entry) {
                         id: block.id,
                         name: block.name,
                         args: copyJson(block.args),
+                        ...(block.providerMetadata === undefined
+                            ? {}
+                            : { providerMetadata: copyJson(block.providerMetadata) }),
                     }),
                 ];
             return [];
@@ -84,7 +105,12 @@ function toolResultPayload(result) {
         return result.output;
     if (result.kind === "denied")
         return { kind: result.kind, reason: result.reason };
-    return { kind: result.kind, code: result.code, message: result.message };
+    return {
+        kind: result.kind,
+        code: result.code,
+        message: result.message,
+        ...(result.details === undefined ? {} : { details: result.details }),
+    };
 }
 function textPart(text) {
     return Object.freeze({ type: "text", text });

package/dist/step/resolve.d.ts

@@ -6,4 +6,5 @@ export declare function resolveModelRequest(input: {
     context: StepContext;
     arrivals: readonly InputEvent[];
     toolResults: readonly ToolResult[];
+    output?: import("../session/output-contract.js").TurnOutputContract;
 }): ModelRequest;

package/dist/step/resolve.js

@@ -12,5 +12,6 @@ export function resolveModelRequest(input) {
         arrivals: Object.freeze([...input.arrivals]),
         toolResults: Object.freeze([...input.toolResults]),
         tools: Object.freeze([...ctx.offeredTools]),
+        ...(input.output === undefined ? {} : { outputSchema: input.output.schema.jsonSchema }),
     });
 }

package/dist/step/run.d.ts

@@ -28,5 +28,6 @@ export declare function runStep(input: {
         readonly context?: import("../types/shared.js").JsonObject;
     }>;
     states: CapabilityStateRegistry;
+    output?: import("../session/output-contract.js").TurnOutputContract;
     recordModelRequested(state: SessionSnapshot, active: ActiveModelExecutionRecord): Promise<SessionSnapshot>;
 }): Promise<StepRunResult>;

package/dist/step/run.js

@@ -52,6 +52,7 @@ export async function runStep(input) {
             context,
             arrivals: input.arrivals,
             toolResults: input.toolResults,
+            output: input.output,
         });
         requestedModelId = request.model?.id;
         const call = projectModelCall(request);
@@ -76,10 +77,26 @@ export async function runStep(input) {
             }),
         }));
         try {
+            let prepared = false;
             const outcome = await input.agent.invoke(call, {
                 request,
                 invocationId,
                 signal: input.signal,
+                reportPreparedCall(value) {
+                    if (prepared)
+                        throw new HarnessError("model.adapter-invalid-options", "Model adapter may report only one prepared call per invocation");
+                    if (typeof value.adapter !== "string" || value.adapter === "")
+                        throw new HarnessError("model.adapter-invalid-options", "Prepared model call adapter must be a non-empty string");
+                    prepared = true;
+                    const reported = Object.freeze({ adapter: value.adapter, call: copyJson(value.call) });
+                    input.observe(() => ({
+                        type: "model.prepared",
+                        turnId: input.turnId,
+                        stepId: input.stepId,
+                        ...(request.model?.id === undefined ? {} : { requestedModelId: request.model.id }),
+                        attributes: reported,
+                    }));
+                },
             });
             if (input.signal.aborted)
                 throw input.signal.reason;
@@ -103,7 +120,7 @@ export async function runStep(input) {
             });
         }
     }, input.observe);
-    const output = sealStep(context);
+    const output = sealStep(context, input.output);
     const candidate = output.kind === "tools" ? output.plan.candidate : context.currentCandidate;
     return Object.freeze({
         stepId: input.stepId,
@@ -136,7 +153,6 @@ function snapshotConfiguration(configuration) {
         tools: snapshotTools(configuration.tools),
         toolContracts: copyJson(configuration.toolContracts),
         contributors: copyJson(configuration.contributors),
-        digests: copyJson(configuration.digests),
     });
 }
 function snapshotTools(tools) {
@@ -144,6 +160,11 @@ function snapshotTools(tools) {
         name: tool.name,
         ...(tool.description === undefined ? {} : { description: tool.description }),
         owner: tool.owner,
-        parameters: Object.freeze({ jsonSchema: copyJson(tool.parameters.jsonSchema) }),
+        inputSchema: Object.freeze({ jsonSchema: copyJson(tool.inputSchema.jsonSchema) }),
+        ...(tool.outputSchema === undefined
+            ? {}
+            : {
+                outputSchema: Object.freeze({ jsonSchema: copyJson(tool.outputSchema.jsonSchema) }),
+            }),
     })));
 }

package/dist/step/seal.d.ts

@@ -2,11 +2,13 @@ import type { ModelCandidate } from "../types/model.js";
 import type { Tripwire } from "../types/shared.js";
 import type { BoundToolDefinition, RequiredInteraction, SealedToolCall, ToolOwner, ToolResult } from "../types/tool.js";
 import type { StepContext } from "./step-context.js";
+import type { TurnOutputContract } from "../session/output-contract.js";
 export interface ExecutablePlanEntry {
     readonly call: SealedToolCall;
     readonly invocationId: string;
     readonly owner: ToolOwner;
     readonly execute: BoundToolDefinition["execute"];
+    readonly outputSchema?: BoundToolDefinition["outputSchema"];
     readonly interaction?: RequiredInteraction;
 }
 export interface InternalToolPlan {
@@ -23,7 +25,7 @@ export type SealedStepOutput = {
     readonly tripwire: Tripwire;
 } | {
     readonly kind: "final";
-    readonly output: string;
+    readonly output: import("../types/shared.js").JsonValue;
 } | {
     readonly kind: "deferred-model";
     readonly active: import("../types/session.js").ActiveModelExecutionRecord;
@@ -32,4 +34,4 @@ export type SealedStepOutput = {
     readonly plan: InternalToolPlan;
 };
 /** Converts the reviewed canonical candidate into either a final response or an executable tool plan. */
-export declare function sealStep(context: StepContext): SealedStepOutput;
+export declare function sealStep(context: StepContext, outputContract?: TurnOutputContract): SealedStepOutput;

package/dist/step/seal.js

@@ -2,19 +2,29 @@ import { textFromOutput } from "../model/normalize.js";
 import { createId } from "../utils/ids.js";
 import { HarnessError, isHarnessError } from "../errors.js";
 import { assertJson, copyJson } from "../utils/immutable.js";
-const failed = (callId, toolName, code, message) => Object.freeze({ kind: "failed", callId, toolName, code, message });
+const failed = (callId, toolName, code, message, details) => Object.freeze({
+    kind: "failed",
+    callId,
+    toolName,
+    code,
+    message,
+    ...(details ? { details } : {}),
+});
 /** Converts the reviewed canonical candidate into either a final response or an executable tool plan. */
-export function sealStep(context) {
+export function sealStep(context, outputContract) {
     if (context.currentTripwire)
         return Object.freeze({ kind: "tripwire", tripwire: context.currentTripwire });
     if (context.currentModelDeferred)
         return Object.freeze({ kind: "deferred-model", active: context.currentModelDeferred });
     const calls = context.canonicalCalls();
-    if (!calls.length)
+    if (!calls.length) {
+        if (outputContract)
+            return sealStructuredOutput(context, outputContract);
         return Object.freeze({
             kind: "final",
             output: textFromOutput(context.currentCandidate?.output ?? []),
         });
+    }
     const catalog = context.catalogByName;
     const sealed = calls.map((call) => sealCall(context, catalog, call));
     const canonicalCandidate = context.currentCandidate ?? Object.freeze({ output: Object.freeze([]) });
@@ -28,6 +38,28 @@ export function sealStep(context) {
         }),
     });
 }
+function sealStructuredOutput(context, contract) {
+    const output = context.currentCandidate?.output ?? [];
+    const json = output.filter((block) => block.type === "json");
+    if (json.length !== 1 || output.some((block) => block.type === "text"))
+        return invalidOutput("Structured terminal output must contain exactly one JSON block and no text blocks");
+    const validation = contract.schema.validate(json[0].value);
+    if (!validation.ok)
+        return invalidOutput(`Structured terminal output failed validation: ${validation.issues.map(renderIssue).join("; ")}`);
+    try {
+        assertJson(validation.value, "structured terminal output");
+        return Object.freeze({ kind: "final", output: copyJson(validation.value) });
+    }
+    catch (error) {
+        return invalidOutput(error instanceof Error ? error.message : String(error));
+    }
+}
+function invalidOutput(message) {
+    return Object.freeze({
+        kind: "tripwire",
+        tripwire: Object.freeze({ code: "output.invalid", message }),
+    });
+}
 function sealCall(context, catalog, candidate) {
     const order = Object.freeze({ callId: candidate.id, toolName: candidate.name });
     const canonical = Object.freeze({
@@ -55,11 +87,11 @@ function sealCall(context, catalog, candidate) {
             immediate: failed(candidate.id, candidate.name, "tool.unknown", `Unknown Tool '${candidate.name}'`),
         };
     const args = validatedArguments(tool, candidate);
-    if (isHarnessError(args))
+    if (!args.ok)
         return {
             order,
             canonical,
-            immediate: failed(candidate.id, candidate.name, args.code, args.message),
+            immediate: failed(candidate.id, candidate.name, "tool.invalid-arguments", args.message, args.details),
         };
     const denial = context.denialFor(candidate.id);
     if (denial)
@@ -84,26 +116,45 @@ function sealCall(context, catalog, candidate) {
             call: Object.freeze({
                 callId: candidate.id,
                 toolName: candidate.name,
-                args,
+                args: args.value,
             }),
             invocationId: createId("invocation"),
             owner: tool.owner,
             execute: tool.execute,
+            ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
             ...(interaction ? { interaction } : {}),
         }),
     };
 }
 function validatedArguments(tool, candidate) {
-    const validation = tool.parameters.validate(candidate.args);
+    const validation = tool.inputSchema.validate(candidate.args);
     if (!validation.ok)
-        return new HarnessError("tool.invalid-arguments", validation.issues.join("; "));
+        return {
+            ok: false,
+            message: validation.issues.map(renderIssue).join("; "),
+            details: Object.freeze({ phase: "input", issues: validation.issues }),
+        };
     try {
         assertJson(validation.value, `arguments for '${candidate.name}'`);
-        return copyJson(validation.value);
+        return { ok: true, value: copyJson(validation.value) };
     }
     catch (error) {
-        return isHarnessError(error)
-            ? error
-            : new HarnessError("tool.invalid-arguments", String(error), { cause: error });
+        return {
+            ok: false,
+            message: isHarnessError(error) ? error.message : String(error),
+            details: Object.freeze({
+                phase: "input",
+                issues: Object.freeze([
+                    Object.freeze({
+                        path: Object.freeze([]),
+                        code: "invalid_json",
+                        message: isHarnessError(error) ? error.message : String(error),
+                    }),
+                ]),
+            }),
+        };
     }
 }
+function renderIssue(issue) {
+    return `${issue.path.join(".") || "(root)"}: ${issue.message}`;
+}

package/dist/turn/plan-runner.js

@@ -1,6 +1,6 @@
 import { HarnessError, isHarnessError } from "../errors.js";
 import { createId } from "../utils/ids.js";
-import { copyJson, copyJsonObject } from "../utils/immutable.js";
+import { assertJson, copyJson, copyJsonObject } from "../utils/immutable.js";
 /** Owns one sealed plan's deterministic interaction and concurrent execution progress. */
 export class ToolPlanRunner {
     plan;
@@ -309,8 +309,18 @@ function resumeValue(event, pending) {
 function resultFrom(entry, outcome) {
     const base = { callId: entry.call.callId, toolName: entry.call.toolName };
     switch (outcome.kind) {
-        case "completed":
-            return Object.freeze({ ...base, kind: "completed", output: copyJson(outcome.output) });
+        case "completed": {
+            const output = validatedOutput(entry, outcome.output);
+            if (!output.ok)
+                return Object.freeze({
+                    ...base,
+                    kind: "failed",
+                    code: "tool.invalid-output",
+                    message: output.message,
+                    details: output.details,
+                });
+            return Object.freeze({ ...base, kind: "completed", output: output.value });
+        }
         case "denied":
             if (typeof outcome.reason !== "string")
                 throw new HarnessError("tool.invalid-tool-result", "Tool denial reason must be a string");
@@ -326,6 +336,31 @@ function resultFrom(entry, outcome) {
             });
     }
 }
+function validatedOutput(entry, value) {
+    const validation = entry.outputSchema?.validate(value) ?? { ok: true, value };
+    if (!validation.ok)
+        return validationFailure("output", validation.issues);
+    try {
+        assertJson(validation.value, `output for '${entry.call.toolName}'`);
+        return { ok: true, value: copyJson(validation.value) };
+    }
+    catch (error) {
+        return validationFailure("output", [
+            Object.freeze({
+                path: Object.freeze([]),
+                code: "invalid_json",
+                message: error instanceof Error ? error.message : String(error),
+            }),
+        ]);
+    }
+}
+function validationFailure(phase, issues) {
+    return {
+        ok: false,
+        message: issues.map((item) => `${item.path.join(".") || "(root)"}: ${item.message}`).join("; "),
+        details: Object.freeze({ phase, issues: Object.freeze([...issues]) }),
+    };
+}
 function completedEvent(entry, context, result) {
     return {
         type: "tool.completed",

package/dist/turn/runner.d.ts

@@ -1,22 +1,24 @@
 import type { ActiveExecutionRecord, InputEvent, SessionEvent, SessionRecord, SessionSnapshot } from "../types/session.js";
-import type { JsonObject, Tripwire } from "../types/shared.js";
+import type { JsonObject, JsonValue, 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";
+import type { TurnOutputContract } from "../session/output-contract.js";
 export interface PendingTurn {
     readonly plan: ToolPlanRunner;
     readonly turnId: string;
     readonly stepId: string;
     readonly stepNumber: number;
+    readonly output?: TurnOutputContract;
 }
 export type TurnProgress = {
     readonly kind: "final";
     readonly state: SessionSnapshot;
     readonly turnId: string;
     readonly stepId: string;
-    readonly output: string;
+    readonly output: JsonValue;
 } | {
     readonly kind: "interaction-required";
     readonly state: SessionSnapshot;
@@ -42,7 +44,7 @@ export interface TurnRunContext {
     readonly assertCurrent: () => void;
     readonly onPlanActive: (pending: PendingTurn | undefined) => void;
     readonly commit: (state: SessionSnapshot, transition: SessionRecord["transition"], active?: ActiveExecutionRecord) => Promise<SessionSnapshot>;
-    readonly onConversation: (event: SessionEvent) => void;
+    readonly onConversation: (event: SessionEvent<JsonValue>) => void;
     readonly claimInterrupts: (state: SessionSnapshot, turnId: string) => Promise<{
         readonly state: SessionSnapshot;
         readonly arrivals: readonly InputEvent[];
@@ -57,7 +59,7 @@ export declare class TurnRunner {
         readonly userId?: string;
         readonly context?: JsonObject;
     }>);
-    start(state: SessionSnapshot, event: InputEvent, context: TurnRunContext): Promise<TurnProgress>;
+    start(state: SessionSnapshot, event: InputEvent, context: TurnRunContext, output?: TurnOutputContract): Promise<TurnProgress>;
     continue(state: SessionSnapshot, context: TurnRunContext): Promise<TurnProgress>;
     resume(state: SessionSnapshot, pending: PendingTurn, event: InputEvent, context: TurnRunContext): Promise<TurnProgress>;
     private advance;