@nylorun/harness 0.8.0-beta.1 → 0.11.0-beta

package/dist/step/seal.js

@@ -1,20 +1,30 @@
-import { textFromOutput } from "../model-normalize.js";
+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/step/step-context.js

@@ -1,6 +1,6 @@
 import { HarnessError, isHarnessError } from "../errors.js";
 import { callsFromCanonical, candidateFromCanonical, canonicalizeOutput, identityKey, } from "./canonicalize.js";
-import { normalizeCandidate } from "../model-normalize.js";
+import { normalizeCandidate } from "../model/normalize.js";
 import { ContextDraft } from "./context-draft.js";
 import { ModelConfigurationDraft } from "./model-configuration.js";
 const branded = new WeakSet();

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;

package/dist/turn/runner.js

@@ -13,11 +13,11 @@ export class TurnRunner {
         this.sessionId = sessionId;
         this.session = session;
     }
-    async start(state, event, context) {
+    async start(state, event, context, output) {
         const turnId = createId("turn");
         state = await context.commit(beginTurn(state, turnId, event), "input");
         context.onConversation({ type: "input", event, turnId });
-        return this.advance(state, turnId, 1, [event], [], context);
+        return this.advance(state, turnId, 1, [event], [], context, output);
     }
     async continue(state, context) {
         const turnId = createId("turn");
@@ -36,9 +36,9 @@ export class TurnRunner {
         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);
+        return this.advance(claimed.state, pending.turnId, pending.stepNumber + 1, claimed.arrivals, progress.results, context, pending.output);
     }
-    async advance(initialState, turnId, firstStep, arrivals, initialResults, context) {
+    async advance(initialState, turnId, firstStep, arrivals, initialResults, context, output) {
         let state = initialState;
         let stepArrivals = arrivals;
         let toolResults = initialResults;
@@ -58,6 +58,7 @@ export class TurnRunner {
                 signal: context.signal,
                 session: this.session,
                 states: context.states,
+                output,
                 recordModelRequested: (next, active) => context.commit(next, "model-requested", active),
             });
             context.assertCurrent();
@@ -68,6 +69,7 @@ export class TurnRunner {
                     turnId,
                     stepId,
                     stepNumber,
+                    ...(output === undefined ? {} : { output }),
                 }
                 : undefined;
             if (run.candidate) {

package/dist/types/manifest.d.ts

@@ -1,11 +1,12 @@
-import type { BoundMiddleware } from "./middleware.js";
+import type { BoundMiddleware, MiddlewareContributions } from "./middleware.js";
 import type { BuildDiagnostic } from "./shared.js";
+export interface MiddlewareManifest extends MiddlewareContributions {
+    readonly id: string;
+}
 export interface AgentManifest {
     readonly id: string;
     readonly name: string;
-    readonly middleware: readonly {
-        readonly id: string;
-    }[];
+    readonly middleware: readonly MiddlewareManifest[];
 }
 export type BuildResult<Agent> = {
     readonly ok: true;

package/dist/types/middleware.d.ts

@@ -72,15 +72,24 @@ export type CapabilityItems<Item> = readonly Item[] | Readonly<{
 /** 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 tools?: CapabilityItems<ToolDefinition<ToolDefinition["inputSchema"], State>>;
     readonly instructions?: CapabilityItems<string>;
     readonly model?: ModelDirective;
     readonly state?: CapabilityState<State>;
     readonly middleware?: StepMiddleware<State>;
 }
+export interface MiddlewareContributions {
+    readonly instructions?: readonly string[];
+    readonly tools?: readonly {
+        readonly name: string;
+        readonly description?: string;
+    }[];
+    readonly model?: Pick<ModelDirective, "id" | "controls">;
+}
 export interface BoundMiddleware {
     readonly id: string;
     readonly handle: StepMiddleware;
     readonly state?: CapabilityState<unknown>;
+    readonly contributions?: MiddlewareContributions;
 }
 export {};

package/dist/types/model.d.ts

@@ -1,4 +1,4 @@
-import type { ContextItem, DeferredOutcome, JsonObject } from "./shared.js";
+import type { ContextItem, DeferredOutcome, JsonObject, JsonValue } from "./shared.js";
 import type { InputEvent, TranscriptEntry } from "./session.js";
 import type { BoundToolDefinition, ToolResult } from "./tool.js";
 export interface ModelToolCall {
@@ -12,6 +12,9 @@ export type ModelOutputBlock = {
 } | {
     readonly type: "reasoning";
     readonly text: string;
+} | {
+    readonly type: "json";
+    readonly value: JsonValue;
 } | {
     readonly type: "tool-call";
     readonly id: string;
@@ -58,34 +61,27 @@ export interface ModelConfigurationContributor {
     readonly middlewareId: string;
     readonly slot: string;
     readonly order: number;
-    readonly digest: string;
     readonly reason?: string;
 }
 export interface ModelConfigurationTool {
     readonly name: string;
     readonly description?: string;
     readonly inputSchema: JsonObject;
-    readonly digest: string;
+    readonly outputSchema?: JsonObject;
     readonly contributor: ModelConfigurationContributor;
 }
 export interface ModelConfigurationInstruction {
     readonly text: string;
-    readonly digest: string;
     readonly contributor: ModelConfigurationContributor;
 }
 export interface ModelConfigurationSnapshot {
     readonly version: 1;
     readonly model?: ModelDirective;
     readonly instructions: readonly ModelConfigurationInstruction[];
-    /** Bound tools are retained for execution; their digest covers only their provider-visible contract. */
+    /** Bound tools are retained for execution. */
     readonly tools: readonly BoundToolDefinition[];
     readonly toolContracts: readonly ModelConfigurationTool[];
     readonly contributors: readonly ModelConfigurationContributor[];
-    readonly digests: Readonly<{
-        readonly logical: string;
-        readonly model: string;
-        readonly request: string;
-    }>;
 }
 /** A middleware-owned declaration for this model call's runtime context. */
 export interface ContextMutationOptions {
@@ -96,14 +92,12 @@ export interface ContextContributor {
     readonly middlewareId: string;
     readonly slot: string;
     readonly order: number;
-    readonly digest: string;
     readonly reason?: string;
 }
-/** Canonical runtime context for one model call. Not part of the configuration digest. */
+/** Canonical runtime context for one model call. */
 export interface ContextSnapshot {
     readonly items: readonly ContextItem[];
     readonly contributors: readonly ContextContributor[];
-    readonly digest: string;
 }
 export interface ModelRequest {
     readonly sessionId: string;
@@ -119,10 +113,16 @@ export interface ModelRequest {
     readonly toolResults: readonly ToolResult[];
     /** Tools are normalized and immutable by the time a Model sees them. */
     readonly tools: readonly BoundToolDefinition[];
+    /** Optional portable contract for this turn's terminal JSON result. */
+    readonly outputSchema?: JsonObject;
 }
 export type PromptContentPart = {
     readonly type: "text";
     readonly text: string;
+} | {
+    readonly type: "media";
+    readonly mediaType: string;
+    readonly reference: JsonValue;
 } | {
     readonly type: "tool-call";
     readonly id: string;
@@ -157,11 +157,19 @@ export interface ModelCall {
     readonly model?: ModelDirective;
     readonly prompt: readonly PromptItem[];
     readonly tools: readonly ModelCallTool[];
+    /** Optional portable contract for this turn's terminal JSON result. */
+    readonly outputSchema?: JsonObject;
     readonly sessionId: string;
 }
 export interface ModelAdapterContext {
     readonly request: ModelRequest;
     readonly invocationId: string;
     readonly signal: AbortSignal;
+    /** Publishes one JSON-safe provider request derived from the canonical ModelCall. */
+    reportPreparedCall(prepared: ModelPreparedCall): void;
+}
+export interface ModelPreparedCall {
+    readonly adapter: string;
+    readonly call: JsonValue;
 }
 export type ModelAdapter = (call: ModelCall, context: ModelAdapterContext) => Promise<ModelCandidate | string | DeferredOutcome>;

package/dist/types/session.d.ts

@@ -1,13 +1,15 @@
 import type { ModelCall, ModelCandidate } from "./model.js";
 import type { JsonObject, JsonValue, Observer, Tripwire } from "./shared.js";
-import type { RequiredInteraction, ToolExecutionResume, ToolOwner, ToolResult } from "./tool.js";
+import type { RequiredInteraction, SchemaOutput, ToolExecutionResume, ToolOwner, ToolResult, ToolSchemaSource } from "./tool.js";
 export type InputEvent = {
-    readonly kind: "user-message";
+    readonly kind: "user-message" | "interrupt";
     readonly text: string;
     readonly metadata?: JsonObject;
 } | {
-    readonly kind: "interrupt";
-    readonly text: string;
+    readonly kind: "user-message" | "interrupt";
+    readonly content: readonly UserContentPart[];
+    /** Undefined for content-bearing events; retained for text-event narrowing compatibility. */
+    readonly text?: undefined;
     readonly metadata?: JsonObject;
 } | {
     readonly kind: "approve";
@@ -18,7 +20,7 @@ export type InputEvent = {
     readonly interactionId: string;
     readonly value: JsonValue;
 };
-export type SessionEvent = {
+export type SessionEvent<Output = string> = {
     readonly type: "input";
     readonly event: InputEvent;
     readonly turnId: string;
@@ -29,7 +31,7 @@ export type SessionEvent = {
     readonly candidate: ModelCandidate;
 } | {
     readonly type: "final";
-    readonly output: string;
+    readonly output: Output;
     readonly turnId: string;
 } | {
     readonly type: "interaction.required";
@@ -58,14 +60,14 @@ export type SessionEvent = {
     readonly type: "session.stopped";
     readonly sessionId: string;
 };
-export interface InputCompletion {
+export interface InputCompletion<Output = string> {
     readonly inputId: string;
     readonly status: "completed" | "waiting" | "rejected" | "cancelled" | "stopped";
-    readonly events: readonly SessionEvent[];
+    readonly events: readonly SessionEvent<Output>[];
 }
-export interface InputHandle {
+export interface InputHandle<Output = string> {
     readonly inputId: string;
-    readonly completed: Promise<InputCompletion>;
+    readonly completed: Promise<InputCompletion<Output>>;
 }
 export interface SessionOptions {
     readonly id?: string;
@@ -91,9 +93,25 @@ export type SessionRunOptions = SessionOptions | SeededSessionOptions;
 export interface InputOptions {
     readonly signal?: AbortSignal;
 }
+/** Per-turn, locally-enforced terminal JSON contract. */
+export interface OutputInputOptions<Schema extends ToolSchemaSource = ToolSchemaSource> extends InputOptions {
+    readonly outputSchema?: Schema;
+}
+/** Ordered, model-visible user content. Media references stay host-owned JSON values. */
+export type UserContentPart = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "media";
+    readonly mediaType: string;
+    readonly reference: JsonValue;
+};
 export type MessageInput = string | {
     readonly text: string;
     readonly metadata?: JsonObject;
+} | {
+    readonly content: readonly UserContentPart[];
+    readonly metadata?: JsonObject;
 };
 export type InteractionReply = Extract<InputEvent, {
     kind: "approve" | "respond";
@@ -121,7 +139,7 @@ export interface TranscriptFinalEntry {
     readonly kind: "final";
     readonly turnId: string;
     readonly stepId: string;
-    readonly output: string;
+    readonly output: JsonValue;
 }
 export type TranscriptEntry = TranscriptInputEntry | TranscriptCandidateEntry | TranscriptToolsEntry | TranscriptFinalEntry;
 export interface SessionSnapshot {
@@ -197,10 +215,13 @@ export interface SessionRecorder {
 export interface Session {
     readonly id: string;
     readonly state: SessionSnapshot;
-    input(event: SessionInput, options?: InputOptions): InputHandle;
+    input<Schema extends ToolSchemaSource>(event: MessageInput, options: OutputInputOptions<Schema> & {
+        readonly outputSchema: Schema;
+    }): InputHandle<SchemaOutput<Schema>>;
+    input(event: SessionInput, options?: InputOptions): InputHandle<string>;
     interrupt(event: MessageInput, options?: InputOptions): InputHandle;
     continue(options?: InputOptions): InputHandle;
-    stream(): AsyncIterable<SessionEvent>;
+    stream(): AsyncIterable<SessionEvent<JsonValue>>;
     observe(listener: Observer): () => void;
     stop(reason?: string): Promise<void>;
 }

package/dist/types/shared.d.ts

@@ -33,7 +33,10 @@ export interface ObserveToolSnapshot {
         readonly middlewareId: string;
         readonly slot: string;
     };
-    readonly parameters: {
+    readonly inputSchema: {
+        readonly jsonSchema: JsonObject;
+    };
+    readonly outputSchema?: {
         readonly jsonSchema: JsonObject;
     };
 }
@@ -55,7 +58,7 @@ export interface ObserveSealedCall {
 export interface ObserveModelRequested {
     /** The exact immutable logical input supplied to the ModelAdapter. */
     readonly call: ModelCall;
-    /** Canonical configuration facts and attribution; hashes have no policy semantics. */
+    /** Canonical configuration facts and attribution. */
     readonly configuration: ObserveModelConfigurationSnapshot;
     /** Current-step runtime context and attribution. */
     readonly context: ContextSnapshot;
@@ -104,6 +107,16 @@ export type ObserveEvent = {
     readonly inputId?: string;
     readonly requestedModelId?: string;
     readonly attributes: ObserveModelRequested;
+} | {
+    readonly type: "model.prepared";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly requestedModelId?: string;
+    readonly attributes: {
+        readonly adapter: string;
+        readonly call: JsonValue;
+    };
 } | {
     readonly type: "model.completed";
     readonly turnId: string;
@@ -206,7 +219,7 @@ export type ObserveEvent = {
     readonly stepId: string;
     readonly inputId?: string;
     readonly attributes: {
-        readonly output: string;
+        readonly output: JsonValue;
     };
 } | {
     readonly type: "interaction.required";