@nylorun/harness 0.5.0-beta.1

package/dist/step/canonicalize.js

@@ -0,0 +1,62 @@
+import { createId } from "../utils/ids.js";
+import { copyJson } from "../utils/immutable.js";
+export function canonicalizeCalls(calls) {
+    const idCounts = new Map();
+    for (const call of calls) {
+        if (typeof call.id === "string" && call.id)
+            idCounts.set(call.id, (idCounts.get(call.id) ?? 0) + 1);
+    }
+    return Object.freeze(calls.map((call) => {
+        const hasId = typeof call.id === "string" && call.id.length > 0;
+        const duplicateId = hasId && (idCounts.get(call.id) ?? 0) > 1 ? call.id : undefined;
+        return Object.freeze({
+            id: hasId && !duplicateId ? call.id : createId("call"),
+            name: typeof call.name === "string" && call.name ? call.name : "unknown",
+            args: call.args,
+            missingId: !hasId,
+            ...(duplicateId ? { duplicateId } : {}),
+        });
+    }));
+}
+export function callsFromCanonical(calls) {
+    return Object.freeze(calls.map((call) => Object.freeze({
+        id: call.id,
+        name: call.name,
+        args: call.args,
+    })));
+}
+export function canonicalizeOutput(output) {
+    const calls = canonicalizeCalls(output.flatMap((block) => (block.type === "tool-call" ? [block] : [])));
+    let index = 0;
+    return {
+        output: Object.freeze(output.map((block) => {
+            if (block.type !== "tool-call")
+                return block;
+            const call = calls[index++];
+            return Object.freeze({
+                type: "tool-call",
+                id: call.id,
+                name: call.name,
+                args: call.args,
+                ...(block.raw === undefined ? {} : { raw: block.raw }),
+            });
+        })),
+        calls,
+    };
+}
+export function candidateFromCanonical(candidate, output) {
+    return Object.freeze({
+        output,
+        ...(candidate.finishReason === undefined ? {} : { finishReason: candidate.finishReason }),
+        ...(candidate.usage === undefined ? {} : { usage: candidate.usage }),
+        ...(candidate.evidence === undefined ? {} : { evidence: candidate.evidence }),
+    });
+}
+export function identityKey(name, args) {
+    try {
+        return `${name}:${JSON.stringify(copyJson(args))}`;
+    }
+    catch {
+        return `${name}:${String(args)}`;
+    }
+}

package/dist/step/compose.d.ts

@@ -0,0 +1,4 @@
+import type { BoundMiddleware, StepResponse } from "../types/middleware.js";
+import type { ObserveEmit } from "../utils/observe.js";
+import { StepContext } from "./step-context.js";
+export declare function runMiddleware(middleware: readonly BoundMiddleware[], context: StepContext, terminal: () => Promise<StepResponse>, observe: ObserveEmit): Promise<StepResponse>;

package/dist/step/compose.js

@@ -0,0 +1,106 @@
+import { HarnessError, isHarnessError } from "../errors.js";
+import { isBrandedResponse, StepContext } from "./step-context.js";
+export async function runMiddleware(middleware, context, terminal, observe) {
+    const dispatch = async (index) => {
+        if (context.currentTripwire)
+            return context.tripwire(context.currentTripwire);
+        if (index === middleware.length)
+            return terminal();
+        const item = middleware[index];
+        const lease = context.requestFacade(item.id, index);
+        let returned = false;
+        let nextCalledTwice = false;
+        let nextPromise;
+        observe({
+            type: "middleware.entered",
+            turnId: context.input.turnId,
+            stepId: context.input.stepId,
+            middlewareId: item.id,
+        });
+        try {
+            let handlerError;
+            let result;
+            try {
+                result = await item.handle(lease.value, () => {
+                    if (returned)
+                        throw new HarnessError("middleware.next-after-return", `Middleware '${item.id}' called next() after returning`, { details: { middlewareId: item.id } });
+                    if (nextPromise) {
+                        nextCalledTwice = true;
+                        throw new HarnessError("middleware.next-called-twice", `Middleware '${item.id}' called next() more than once`, { details: { middlewareId: item.id } });
+                    }
+                    lease.revokeMutators();
+                    nextPromise = dispatch(index + 1);
+                    return nextPromise;
+                });
+            }
+            catch (error) {
+                handlerError = error;
+            }
+            finally {
+                returned = true;
+                lease.revokeMutators();
+            }
+            let inner;
+            if (nextPromise) {
+                try {
+                    inner = await nextPromise;
+                }
+                catch (error) {
+                    handlerError ??= error;
+                }
+            }
+            if (handlerError) {
+                if (nextCalledTwice ||
+                    (isHarnessError(handlerError) && handlerError.code === "middleware.next-called-twice")) {
+                    return context.tripwire({
+                        code: "middleware.next-called-twice",
+                        message: message(handlerError),
+                        scope: "session",
+                    });
+                }
+                return context.tripwire({
+                    code: isHarnessError(handlerError) ? handlerError.code : "middleware.failed",
+                    message: message(handlerError),
+                });
+            }
+            if (inner) {
+                if (result !== inner) {
+                    return context.tripwire({
+                        code: "middleware.invalid-response",
+                        message: `Middleware '${item.id}' must return the StepResponse from next()`,
+                        // Calling next() completed the step successfully; forgetting to
+                        // return that response is isolated to this step. A non-response
+                        // replacement remains a session-level middleware-contract breach.
+                        scope: result === undefined ? "step" : "session",
+                    });
+                }
+                return inner;
+            }
+            if (!isBrandedResponse(result)) {
+                return context.tripwire({
+                    code: "middleware.invalid-response",
+                    message: `Middleware '${item.id}' must return a branded StepResponse`,
+                    scope: "session",
+                });
+            }
+            return result;
+        }
+        finally {
+            observe({
+                type: "middleware.completed",
+                turnId: context.input.turnId,
+                stepId: context.input.stepId,
+                middlewareId: item.id,
+            });
+        }
+    };
+    try {
+        return await dispatch(0);
+    }
+    finally {
+        context.seal();
+    }
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/step/context-draft.d.ts

@@ -0,0 +1,10 @@
+import type { ContextMutationOptions, ContextSnapshot } from "../types/model.js";
+import type { ContextItem, JsonObject } from "../types/shared.js";
+/** Per-step runtime-context draft. Host context is injected fresh for every call. */
+export declare class ContextDraft {
+    #private;
+    private readonly hostContext?;
+    constructor(hostContext?: JsonObject | undefined);
+    set(middlewareId: string, middlewareOrder: number, slot: string, items: readonly ContextItem[], options?: ContextMutationOptions): void;
+    snapshot(): ContextSnapshot;
+}

package/dist/step/context-draft.js

@@ -0,0 +1,71 @@
+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}$/;
+/** Per-step runtime-context draft. Host context is injected fresh for every call. */
+export class ContextDraft {
+    hostContext;
+    #slots = new SlotDraft();
+    constructor(hostContext) {
+        this.hostContext = hostContext;
+    }
+    set(middlewareId, middlewareOrder, slot, items, options) {
+        if (!Array.isArray(items))
+            throw new HarnessError("context.invalid-item", "Runtime context items must be an array");
+        this.#slots.set({
+            middlewareId,
+            middlewareOrder,
+            slot,
+            value: Object.freeze(items.map(normalizeItem)),
+            order: options?.order,
+            reason: options?.reason,
+            invalidSlot: "context.invalid-slot",
+            invalidOrder: "context.invalid-order",
+            invalidReason: "context.invalid-reason",
+            label: "Runtime context",
+        });
+    }
+    snapshot() {
+        const slots = this.#slots.values();
+        const host = this.hostContext === undefined
+            ? []
+            : [Object.freeze({ type: "session", value: copyJson(this.hostContext) })];
+        const items = Object.freeze([...host, ...slots.flatMap((slot) => slot.value)]);
+        const contributors = Object.freeze([
+            ...(this.hostContext === undefined ? [] : [hostContributor()]),
+            ...slots.map((slot) => contributor(slot.owner, slot.reason)),
+        ]);
+        return Object.freeze({ items, contributors, digest: digest(items.map(itemDigest)) });
+    }
+}
+function normalizeItem(item) {
+    if (!item || typeof item !== "object")
+        throw new HarnessError("context.invalid-item", "Runtime context items must be objects");
+    if (item.type !== undefined && (typeof item.type !== "string" || !CONTEXT_TYPE.test(item.type)))
+        throw new HarnessError("context.invalid-item-type", "Runtime context item type must match [A-Za-z][A-Za-z0-9_-]{0,63}");
+    return Object.freeze({
+        ...(item.type === undefined ? {} : { type: item.type }),
+        value: copyJson(item.value),
+    });
+}
+function hostContributor() {
+    return Object.freeze({
+        middlewareId: "host",
+        slot: "session",
+        order: 0,
+        digest: digest({ middlewareId: "host", slot: "session", order: 0 }),
+    });
+}
+function contributor(owner, reason) {
+    return Object.freeze({
+        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.d.ts

@@ -0,0 +1,15 @@
+import type { ModelConfigurationMutationOptions, ModelConfigurationSnapshot, ModelDirective } from "../types/model.js";
+import type { ToolDefinition } from "../types/tool.js";
+import type { AdapterRegistry } from "../build/adapters.js";
+/** Per-step, middleware-owned model configuration draft. It never persists past the call. */
+export declare class ModelConfigurationDraft {
+    #private;
+    private readonly adapters;
+    constructor(adapters: AdapterRegistry, directive?: ModelDirective);
+    setInstructions(middlewareId: string, middlewareOrder: number, slot: string, items: readonly string[], options?: ModelConfigurationMutationOptions): void;
+    setTools(middlewareId: string, middlewareOrder: number, slot: string, tools: readonly ToolDefinition[], options?: ModelConfigurationMutationOptions): void;
+    select(middlewareId: string, middlewareOrder: number, directive: ModelDirective, options?: Omit<ModelConfigurationMutationOptions, "order">): void;
+    replace(middlewareId: string, middlewareOrder: number, directive: ModelDirective, options?: Omit<ModelConfigurationMutationOptions, "order">): void;
+    clear(options?: Omit<ModelConfigurationMutationOptions, "order">): void;
+    snapshot(): ModelConfigurationSnapshot;
+}

package/dist/step/model-configuration.js

@@ -0,0 +1,153 @@
+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. */
+export class ModelConfigurationDraft {
+    adapters;
+    #instructions = new SlotDraft();
+    #tools = new SlotDraft();
+    #model;
+    constructor(adapters, directive) {
+        this.adapters = adapters;
+        if (directive !== undefined)
+            this.#model = Object.freeze({ directive: checkedDirective(directive) });
+    }
+    setInstructions(middlewareId, middlewareOrder, slot, items, options) {
+        if (!Array.isArray(items) || items.some((item) => typeof item !== "string"))
+            throw new HarnessError("configuration.invalid-instructions", "Model configuration instructions must be strings");
+        this.#instructions.set({
+            middlewareId,
+            middlewareOrder,
+            slot,
+            value: Object.freeze([...items]),
+            order: options?.order,
+            reason: options?.reason,
+            invalidSlot: "configuration.invalid-slot",
+            invalidOrder: "configuration.invalid-order",
+            invalidReason: "configuration.invalid-reason",
+            label: "Model configuration",
+        });
+    }
+    setTools(middlewareId, middlewareOrder, slot, tools, options) {
+        if (!Array.isArray(tools))
+            throw new HarnessError("configuration.invalid-tools", "Model configuration tools must be an array");
+        this.#tools.set({
+            middlewareId,
+            middlewareOrder,
+            slot,
+            value: Object.freeze(tools.map((tool) => bindTool(tool, this.adapters))),
+            order: options?.order,
+            reason: options?.reason,
+            invalidSlot: "configuration.invalid-slot",
+            invalidOrder: "configuration.invalid-order",
+            invalidReason: "configuration.invalid-reason",
+            label: "Model configuration",
+        });
+    }
+    select(middlewareId, middlewareOrder, directive, options) {
+        const normalized = checkedDirective(directive);
+        if (this.#model && !sameDirective(this.#model.directive, normalized))
+            throw new HarnessError("configuration.model-selection-conflict", "A different model directive is already selected; use model.replace() to change it");
+        this.#model = Object.freeze({
+            directive: normalized,
+            owner: slotOwner(middlewareId, middlewareOrder, "model"),
+            ...(options?.reason === undefined
+                ? {}
+                : {
+                    reason: checkedReason(options.reason, "configuration.invalid-reason", "Model configuration"),
+                }),
+        });
+    }
+    replace(middlewareId, middlewareOrder, directive, options) {
+        this.#model = Object.freeze({
+            directive: checkedDirective(directive),
+            owner: slotOwner(middlewareId, middlewareOrder, "model"),
+            ...(options?.reason === undefined
+                ? {}
+                : {
+                    reason: checkedReason(options.reason, "configuration.invalid-reason", "Model configuration"),
+                }),
+        });
+    }
+    clear(options) {
+        if (options?.reason !== undefined)
+            checkedReason(options.reason, "configuration.invalid-reason", "Model configuration");
+        this.#model = undefined;
+    }
+    snapshot() {
+        const instructionSlots = this.#instructions.values();
+        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) })));
+        const seen = new Set();
+        const duplicate = new Set();
+        for (const item of sourcedTools) {
+            if (seen.has(item.tool.name))
+                duplicate.add(item.tool.name);
+            seen.add(item.tool.name);
+        }
+        if (duplicate.size)
+            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 }),
+            instructions: Object.freeze(instructions),
+            tools: Object.freeze(sourcedTools.map((item) => item.tool)),
+            toolContracts: Object.freeze(toolContracts),
+            contributors: Object.freeze([
+                ...instructionSlots.map((slot) => contributor(slot.owner, slot.reason)),
+                ...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 }),
+            }),
+        });
+    }
+}
+function checkedDirective(value) {
+    const normalized = normalizeDirective(value);
+    if (isHarnessError(normalized))
+        throw normalized;
+    return normalized;
+}
+function contributor(owner, reason) {
+    return Object.freeze({
+        middlewareId: owner.middlewareId,
+        slot: owner.slot,
+        order: owner.order,
+        digest: digest({ middlewareId: owner.middlewareId, slot: owner.slot, order: owner.order }),
+        ...(reason === undefined ? {} : { reason }),
+    });
+}
+function providerTool(tool) {
+    return {
+        name: tool.name,
+        ...(tool.description === undefined ? {} : { description: tool.description }),
+        inputSchema: copyJson(tool.parameters.jsonSchema),
+    };
+}
+function toolContract(tool, source) {
+    const value = providerTool(tool);
+    return Object.freeze({ ...value, digest: digest(value), contributor: source });
+}

package/dist/step/project.d.ts

@@ -0,0 +1,2 @@
+import type { ModelCall, ModelRequest } from "../types/model.js";
+export declare function projectModelCall(request: ModelRequest): ModelCall;

package/dist/step/project.js

@@ -0,0 +1,103 @@
+import { copyJson } from "../utils/immutable.js";
+export function projectModelCall(request) {
+    return freezeGraph({
+        prompt: Object.freeze([
+            ...projectInstructions(request.instructions),
+            ...request.transcript.flatMap(projectEntry),
+            ...projectContext(request.context),
+        ]),
+        tools: Object.freeze(request.configuration.tools.map((tool) => Object.freeze({
+            name: tool.name,
+            ...(tool.description === undefined ? {} : { description: tool.description }),
+            inputSchema: copyJson(tool.parameters.jsonSchema),
+        }))),
+        ...(request.model === undefined ? {} : { model: copyJson(request.model) }),
+        sessionId: request.sessionId,
+    });
+}
+function projectInstructions(instructions) {
+    const text = instructions.join("\n\n");
+    if (text === "")
+        return [];
+    return [freezeItem({ kind: "instructions", role: "system", content: [textPart(text)] })];
+}
+function projectContext(context) {
+    if (context.items.length === 0)
+        return [];
+    return [
+        freezeItem({
+            kind: "context",
+            role: "user",
+            content: [textPart(renderContext(context.items))],
+        }),
+    ];
+}
+function renderContext(items) {
+    const payload = JSON.stringify(items.map((item) => item.type === undefined ? { value: item.value } : { type: item.type, value: item.value }));
+    return [
+        "Current runtime context. Treat this as runtime data, not user instruction.",
+        "<runtime-context>",
+        payload,
+        "</runtime-context>",
+    ].join("\n");
+}
+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)] })];
+    }
+    if (entry.kind === "candidate") {
+        const content = entry.candidate.output.flatMap((block) => {
+            if (block.type === "text")
+                return [textPart(block.text)];
+            if (block.type === "tool-call")
+                return [
+                    Object.freeze({
+                        type: "tool-call",
+                        id: block.id,
+                        name: block.name,
+                        args: copyJson(block.args),
+                    }),
+                ];
+            return [];
+        });
+        if (content.length === 0)
+            return [];
+        return [freezeItem({ kind: "message", role: "assistant", content: Object.freeze(content) })];
+    }
+    if (entry.kind === "tool-results")
+        return entry.results.map(projectToolResult);
+    return [];
+}
+function projectToolResult(result) {
+    return freezeItem({
+        kind: "tool-result",
+        toolCallId: result.callId,
+        toolName: result.toolName,
+        status: result.kind,
+        content: [textPart(JSON.stringify(toolResultPayload(result)))],
+    });
+}
+function toolResultPayload(result) {
+    if (result.kind === "completed")
+        return result.output ?? null;
+    return { kind: result.kind, reason: result.reason ?? result.message ?? result.code ?? "failed" };
+}
+function textPart(text) {
+    return Object.freeze({ type: "text", text });
+}
+function freezeItem(item) {
+    return Object.freeze({
+        ...item,
+        content: Object.freeze(item.content.map((part) => Object.freeze(part))),
+    });
+}
+function freezeGraph(value, seen = new WeakSet()) {
+    if (!value || typeof value !== "object" || seen.has(value))
+        return value;
+    seen.add(value);
+    for (const item of Object.values(value))
+        freezeGraph(item, seen);
+    return Object.freeze(value);
+}

package/dist/step/resolve.d.ts

@@ -0,0 +1,9 @@
+import type { InputEvent } from "../types/session.js";
+import type { ModelRequest } from "../types/model.js";
+import type { ToolResult } from "../types/tool.js";
+import type { StepContext } from "./step-context.js";
+export declare function resolveModelRequest(input: {
+    context: StepContext;
+    arrivals: readonly InputEvent[];
+    toolResults: readonly ToolResult[];
+}): ModelRequest;

package/dist/step/resolve.js

@@ -0,0 +1,16 @@
+export function resolveModelRequest(input) {
+    const ctx = input.context;
+    return Object.freeze({
+        sessionId: ctx.input.sessionId,
+        turnId: ctx.input.turnId,
+        stepId: ctx.input.stepId,
+        ...(ctx.selectedDirective === undefined ? {} : { model: ctx.selectedDirective }),
+        configuration: ctx.configurationSnapshot(),
+        instructions: Object.freeze([...ctx.instructions]),
+        context: ctx.contextSnapshot(),
+        transcript: Object.freeze([...ctx.input.transcript]),
+        arrivals: Object.freeze([...input.arrivals]),
+        toolResults: Object.freeze([...input.toolResults]),
+        tools: Object.freeze([...ctx.offeredTools]),
+    });
+}

package/dist/step/run.d.ts

@@ -0,0 +1,27 @@
+import type { ModelCandidate } from "../types/model.js";
+import type { InputEvent, SessionSnapshot } from "../types/session.js";
+import type { LoopAgent } from "../build/agent.js";
+import type { ObserveEmit } from "../utils/observe.js";
+import { type SealedStepOutput } from "./seal.js";
+export interface StepRunResult {
+    readonly stepId: string;
+    readonly candidate?: ModelCandidate;
+    readonly output: SealedStepOutput;
+}
+export declare function runStep(input: {
+    agent: LoopAgent;
+    observe: ObserveEmit;
+    state: SessionSnapshot;
+    sessionId: string;
+    turnId: string;
+    stepId: string;
+    turnNumber: number;
+    stepNumber: number;
+    arrivals: readonly InputEvent[];
+    toolResults: readonly import("../types/tool.js").ToolResult[];
+    signal: AbortSignal;
+    session: Readonly<{
+        readonly userId?: string;
+        readonly context?: import("../types/shared.js").JsonObject;
+    }>;
+}): Promise<StepRunResult>;