@nylorun/harness 0.5.0-beta.1

package/dist/build/builder.js

@@ -0,0 +1,74 @@
+import { HarnessError } from "../errors.js";
+import { assembleAgent } from "./assemble.js";
+export class AgentBuildError extends HarnessError {
+    diagnostics;
+    constructor(diagnostics) {
+        super("agent.build-failed", diagnostics.map((item) => item.message).join("; ") || "Agent build failed");
+        this.diagnostics = diagnostics;
+        this.name = "AgentBuildError";
+    }
+}
+export class AgentLifecycleError extends HarnessError {
+    constructor(message) {
+        super("agent.lifecycle-sealed", message);
+        this.name = "AgentLifecycleError";
+    }
+}
+export function Agent(model, directive) {
+    return new AgentBuilder(model, directive);
+}
+export class AgentBuilder {
+    invoke;
+    directive;
+    middleware = [];
+    adapters = [];
+    sealed = false;
+    agent;
+    error;
+    middlewareSeq = 0;
+    constructor(invoke, directive) {
+        this.invoke = invoke;
+        this.directive = directive;
+    }
+    with(adapter, options) {
+        if (this.sealed)
+            throw new AgentLifecycleError("AgentBuilder cannot be changed after build()");
+        this.adapters.push({ adapter, ...(options === undefined ? {} : { options }) });
+        return this;
+    }
+    use(idOrMiddleware, middleware) {
+        if (typeof idOrMiddleware === "function") {
+            return this.push({ id: this.nextMiddlewareId(), handle: idOrMiddleware });
+        }
+        return this.push({ id: idOrMiddleware, handle: middleware });
+    }
+    build() {
+        if (this.agent)
+            return this.agent;
+        if (this.error)
+            throw this.error;
+        this.sealed = true;
+        const result = assembleAgent(this.middleware, this.invoke, this.adapters, this.directive);
+        if (!result.ok) {
+            this.error = new AgentBuildError(result.diagnostics);
+            throw this.error;
+        }
+        this.agent = result.agent;
+        return this.agent;
+    }
+    nextMiddlewareId() {
+        const taken = new Set(this.middleware.map((item) => item.id));
+        let id;
+        do {
+            this.middlewareSeq += 1;
+            id = `middleware-${this.middlewareSeq}`;
+        } while (taken.has(id));
+        return id;
+    }
+    push(entry) {
+        if (this.sealed)
+            throw new AgentLifecycleError("AgentBuilder cannot be changed after build()");
+        this.middleware.push(entry);
+        return this;
+    }
+}

package/dist/build/helpers.d.ts

@@ -0,0 +1,7 @@
+import type { ModelAdapter } from "../types/model.js";
+import type { StepMiddleware } from "../types/middleware.js";
+import type { ToolAdapter, ToolDefinition } from "../types/tool.js";
+export declare const tool: <T extends ToolDefinition>(value: T) => T;
+export declare const adapter: <T extends ToolAdapter>(value: T) => T;
+export declare const model: <T extends ModelAdapter>(value: T) => T;
+export declare const middleware: <T extends StepMiddleware>(value: T) => T;

package/dist/build/helpers.js

@@ -0,0 +1,5 @@
+import { prepareTool } from "./schema.js";
+export const tool = (value) => prepareTool(value);
+export const adapter = (value) => value;
+export const model = (value) => value;
+export const middleware = (value) => value;

package/dist/build/manifest.d.ts

@@ -0,0 +1,9 @@
+import type { AgentManifest } from "../types/manifest.js";
+import type { BoundMiddleware } from "../types/middleware.js";
+import type { ModelDirective } from "../types/model.js";
+import type { AdapterRegistry } from "./adapters.js";
+export declare function createManifest(input: {
+    middleware: readonly BoundMiddleware[];
+    directive?: ModelDirective;
+    adapters: AdapterRegistry;
+}): AgentManifest;

package/dist/build/manifest.js

@@ -0,0 +1,15 @@
+import { deepFreeze } from "../utils/immutable.js";
+export function createManifest(input) {
+    const middleware = input.middleware.map(({ id }) => ({ id }));
+    const adapters = [...input.adapters.entries].map(([, entry]) => ({
+        id: entry.adapter.id,
+        ...(entry.options.maxConcurrentCalls === undefined
+            ? {}
+            : { maxConcurrentCalls: entry.options.maxConcurrentCalls }),
+    }));
+    return deepFreeze({
+        middleware,
+        ...(input.directive === undefined ? {} : { model: input.directive }),
+        adapters,
+    });
+}

package/dist/build/schema.d.ts

@@ -0,0 +1,19 @@
+import type { output } from "zod";
+import type { ToolDefinition, ToolObjectSchema } from "../types/tool.js";
+export type SchemaValidation<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly issues: readonly string[];
+};
+export interface NormalizedToolSchema<T> {
+    readonly jsonSchema: import("../types/shared.js").JsonObject;
+    validate(value: unknown): SchemaValidation<T>;
+}
+/** Eagerly prepares a definition authored through Harness's tool() helper. */
+export declare function prepareTool<T extends ToolDefinition>(definition: T): T;
+/** Returns a cached normalized schema, preparing raw definitions on first bind. */
+export declare function normalizedSchemaFor(definition: ToolDefinition): NormalizedToolSchema<unknown>;
+/** Converts a synchronous Zod object schema into Harness's immutable runtime representation. */
+export declare function normalizeSchema<Parameters extends ToolObjectSchema>(parameters: Parameters): NormalizedToolSchema<output<Parameters>>;

package/dist/build/schema.js

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { HarnessError } from "../errors.js";
+import { copyJsonObject } from "../utils/immutable.js";
+const preparedSchemas = new WeakMap();
+/** Eagerly prepares a definition authored through Harness's tool() helper. */
+export function prepareTool(definition) {
+    normalizedSchemaFor(definition);
+    return definition;
+}
+/** Returns a cached normalized schema, preparing raw definitions on first bind. */
+export function normalizedSchemaFor(definition) {
+    const cached = preparedSchemas.get(definition);
+    if (cached)
+        return cached;
+    const normalized = normalizeSchema(definition.parameters);
+    preparedSchemas.set(definition, normalized);
+    return normalized;
+}
+/** Converts a synchronous Zod object schema into Harness's immutable runtime representation. */
+export function normalizeSchema(parameters) {
+    if (!(parameters instanceof z.ZodObject)) {
+        throw new HarnessError("tool.invalid-schema", "Tool parameters schema must be a Zod object schema");
+    }
+    if (hasDeclaredAsyncWork(parameters)) {
+        throw new HarnessError("tool.invalid-schema", "Tool parameters schema must validate synchronously");
+    }
+    let jsonSchema;
+    try {
+        jsonSchema = copyJsonObject(z.toJSONSchema(parameters, { target: "draft-07" }), "tool.parameters.jsonSchema");
+    }
+    catch (error) {
+        throw new HarnessError("tool.invalid-schema", `Tool parameters schema must convert to JSON Schema: ${message(error)}`, { cause: error });
+    }
+    if (jsonSchema.type !== "object") {
+        throw new HarnessError("tool.invalid-schema", "Tool JSON Schema root type must be object");
+    }
+    return Object.freeze({
+        jsonSchema,
+        validate(value) {
+            try {
+                const result = parameters.safeParse(value);
+                if (result.success)
+                    return { ok: true, value: result.data };
+                return {
+                    ok: false,
+                    issues: result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`),
+                };
+            }
+            catch (error) {
+                return { ok: false, issues: [synchronousIssue(error)] };
+            }
+        },
+    });
+}
+/** Zod exposes declared checks in its stable v4 definition graph; reject async checks before a run. */
+function hasDeclaredAsyncWork(schema) {
+    return visitDefinition(schema._zod?.def, new Set());
+}
+function visitDefinition(value, seen) {
+    if (typeof value === "function")
+        return value.constructor.name === "AsyncFunction";
+    if (!value || typeof value !== "object")
+        return false;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    // Nested Zod schemas carry their own definition graph. Inspect it directly so public helpers
+    // such as `parseAsync` do not make every otherwise-synchronous schema look asynchronous.
+    const nestedDefinition = value._zod?.def;
+    if (nestedDefinition !== undefined && nestedDefinition !== value)
+        return visitDefinition(nestedDefinition, seen);
+    for (const item of Object.values(value)) {
+        if (visitDefinition(item, seen))
+            return true;
+    }
+    return false;
+}
+function synchronousIssue(error) {
+    const reason = message(error);
+    return reason.includes("Promise during synchronous parse")
+        ? "Schema validation must be synchronous"
+        : reason;
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+/** Machine-readable error raised by Harness-owned code. */
+export type HarnessErrorCode = "adapter.invalid-outcome" | "adapter.not-registered" | "agent.build-failed" | "agent.lifecycle-sealed" | "context.invalid-item" | "context.invalid-item-type" | "context.invalid-order" | "context.invalid-reason" | "context.invalid-slot" | "interaction.invalid" | "interaction.missing-resume" | "interaction.uncorrelated-resume" | "json.invalid-data" | "json.invalid-object" | "middleware.next-after-return" | "middleware.next-called-twice" | "middleware.request-mutators-revoked" | "model.candidate-missing" | "model.invalid-candidate" | "model.invalid-directive" | "configuration.duplicate-tool-name" | "configuration.invalid" | "configuration.invalid-instructions" | "configuration.invalid-order" | "configuration.invalid-reason" | "configuration.invalid-slot" | "configuration.invalid-tools" | "configuration.model-selection-conflict" | "response.invalid-replacement" | "session.stale-result" | "tool.invalid-arguments" | "tool.invalid-name" | "tool.invalid-schema" | "tool.invalid-tool-result";
+export type HarnessErrorDetails = Readonly<Record<string, string | number | boolean>>;
+export interface HarnessErrorOptions {
+    readonly cause?: unknown;
+    readonly details?: HarnessErrorDetails;
+}
+/**
+ * The sole error shape produced by Harness itself. Message text is explanatory;
+ * callers must branch on `code`.
+ */
+export declare class HarnessError extends Error {
+    readonly code: HarnessErrorCode;
+    readonly details: HarnessErrorDetails;
+    constructor(code: HarnessErrorCode, message: string, options?: HarnessErrorOptions);
+}
+export declare function isHarnessError(error: unknown): error is HarnessError;

package/dist/errors.js

@@ -0,0 +1,17 @@
+/**
+ * The sole error shape produced by Harness itself. Message text is explanatory;
+ * callers must branch on `code`.
+ */
+export class HarnessError extends Error {
+    code;
+    details;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "HarnessError";
+        this.code = code;
+        this.details = Object.freeze({ ...(options.details ?? {}) });
+    }
+}
+export function isHarnessError(error) {
+    return error instanceof HarnessError;
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError } from "./build/builder.js";
+export { HarnessError, isHarnessError } from "./errors.js";
+export type { HarnessErrorCode, HarnessErrorDetails, HarnessErrorOptions } from "./errors.js";
+export { BuiltAgent } from "./build/agent.js";
+export { adapter, middleware, model, tool } from "./build/helpers.js";
+export type { AgentManifest } from "./types/manifest.js";
+export type { ModelCandidate, ModelControls, ModelDirective, ModelEvidence, ModelFinishReason, ModelAdapter, ModelAdapterContext, ContextContributor, ContextMutationOptions, ContextSnapshot, ModelCall, ModelCallTool, ModelOutputBlock, PromptContentPart, PromptItem, ModelConfigurationContributor, ModelConfigurationInstruction, ModelConfigurationMutationOptions, ModelConfigurationSnapshot, ModelConfigurationTool, ModelRequest, ModelToolCall, ModelUsage, } from "./types/model.js";
+export type { BoundMiddleware, StepInput, StepMiddleware, StepRequest, StepResponse, } from "./types/middleware.js";
+export type { BuildDiagnostic, ContextItem, JsonObject, JsonPrimitive, JsonValue, ObserveEvent, ObserveModelConfigurationSnapshot, ObserveModelRequested, ObserveSealedCall, ObserveToolSnapshot, Observer, Tripwire, } from "./types/shared.js";
+export type { InteractionReply, InputCompletion, InputEvent, InputHandle, InputOptions, MessageInput, Session, SessionInput, SessionEvent, SessionOptions, SessionSnapshot, TranscriptEntry, } from "./types/session.js";
+export type { BoundToolSchema, BoundToolDefinition, Interaction, PreflightOutcome, RequiredInteraction, SealedToolCall, ToolAdapter, AdapterExecutionOptions, ToolContent, ToolDefinition, ToolExecutionResume, ToolObjectSchema, ToolOutcome, ToolResult, } from "./types/tool.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError } from "./build/builder.js";
+export { HarnessError, isHarnessError } from "./errors.js";
+export { BuiltAgent } from "./build/agent.js";
+export { adapter, middleware, model, tool } from "./build/helpers.js";

package/dist/model-normalize.d.ts

@@ -0,0 +1,6 @@
+import { HarnessError } from "./errors.js";
+import type { ModelCandidate, ModelDirective, ModelOutputBlock } from "./types/model.js";
+export declare function normalizeDirective(value: unknown): ModelDirective | HarnessError;
+export declare function sameDirective(left: ModelDirective, right: ModelDirective): boolean;
+export declare function textFromOutput(output: readonly ModelOutputBlock[]): string;
+export declare function normalizeCandidate(value: ModelCandidate | string): ModelCandidate;

package/dist/model-normalize.js

@@ -0,0 +1,211 @@
+import { HarnessError, isHarnessError } from "./errors.js";
+import { digest } from "./utils/digest.js";
+import { copyJsonObject } from "./utils/immutable.js";
+const FINISH_REASONS = new Set([
+    "stop",
+    "length",
+    "tool-calls",
+    "content-filter",
+    "other",
+]);
+const USAGE_TOKEN_KEYS = [
+    "inputTokens",
+    "outputTokens",
+    "totalTokens",
+    "cachedTokens",
+    "reasoningTokens",
+];
+export function normalizeDirective(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return new HarnessError("model.invalid-directive", "Model directive must be an object");
+    const keys = Object.keys(value);
+    for (const key of keys) {
+        if (key !== "id" && key !== "controls" && key !== "config")
+            return new HarnessError("model.invalid-directive", `Model directive has unknown key '${key}'`, {
+                details: { path: key },
+            });
+    }
+    const raw = value;
+    if (raw.id !== undefined && (typeof raw.id !== "string" || raw.id.length === 0))
+        return new HarnessError("model.invalid-directive", "Model directive id must be a non-empty string", {
+            details: { path: "id" },
+        });
+    let controls;
+    if (raw.controls !== undefined) {
+        const normalized = normalizeControls(raw.controls);
+        if (isHarnessError(normalized))
+            return normalized;
+        controls = normalized;
+    }
+    let config;
+    if (raw.config !== undefined) {
+        try {
+            config = copyJsonObject(raw.config, "model directive config");
+        }
+        catch (error) {
+            return isHarnessError(error)
+                ? error
+                : new HarnessError("model.invalid-directive", String(error), { cause: error });
+        }
+    }
+    return Object.freeze({
+        ...(typeof raw.id === "string" ? { id: raw.id } : {}),
+        ...(controls === undefined ? {} : { controls }),
+        ...(config === undefined ? {} : { config }),
+    });
+}
+export function sameDirective(left, right) {
+    return digest(left) === digest(right);
+}
+export function textFromOutput(output) {
+    return output.flatMap((block) => (block.type === "text" ? [block.text] : [])).join("");
+}
+export function normalizeCandidate(value) {
+    if (typeof value === "string")
+        return Object.freeze({ output: freezeBlocks([{ type: "text", text: value }]) });
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw invalidCandidate("Model candidate must be an object or string");
+    if (!Array.isArray(value.output))
+        throw invalidCandidate("Model candidate output must be an array", "output");
+    const output = freezeBlocks(value.output.map((block, index) => normalizeBlock(block, index)));
+    return Object.freeze({
+        output,
+        ...(value.finishReason === undefined
+            ? {}
+            : { finishReason: normalizeFinishReason(value.finishReason) }),
+        ...(value.usage === undefined ? {} : { usage: normalizeUsage(value.usage) }),
+        ...(value.evidence === undefined ? {} : { evidence: normalizeEvidence(value.evidence) }),
+    });
+}
+function normalizeControls(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return new HarnessError("model.invalid-directive", "Model directive controls must be an object", {
+            details: { path: "controls" },
+        });
+    const keys = Object.keys(value);
+    for (const key of keys) {
+        if (key !== "temperature" && key !== "maxOutputTokens")
+            return new HarnessError("model.invalid-directive", `Model directive controls has unknown key '${key}'`, { details: { path: `controls.${key}` } });
+    }
+    const raw = value;
+    if (raw.temperature !== undefined && !isFiniteNumber(raw.temperature))
+        return new HarnessError("model.invalid-directive", "Model directive temperature must be a finite number", { details: { path: "controls.temperature" } });
+    if (raw.maxOutputTokens !== undefined && !isNonNegativeInteger(raw.maxOutputTokens))
+        return new HarnessError("model.invalid-directive", "Model directive maxOutputTokens must be a non-negative integer", { details: { path: "controls.maxOutputTokens" } });
+    return Object.freeze({
+        ...(raw.temperature === undefined ? {} : { temperature: raw.temperature }),
+        ...(raw.maxOutputTokens === undefined ? {} : { maxOutputTokens: raw.maxOutputTokens }),
+    });
+}
+function normalizeBlock(value, index) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw invalidCandidate(`Model output[${index}] must be an object`, `output[${index}]`);
+    const block = value;
+    if (block.type === "text" || block.type === "reasoning") {
+        rejectUnknownKeys(value, ["type", "text"], `Model output[${index}]`);
+        const text = value.text;
+        if (typeof text !== "string")
+            throw invalidCandidate(`Model output[${index}].text must be a string`, `output[${index}].text`);
+        return Object.freeze({ type: block.type, text });
+    }
+    if (block.type === "tool-call") {
+        rejectUnknownKeys(value, ["type", "id", "name", "args", "raw"], `Model output[${index}]`);
+        const raw = value;
+        if (raw.id !== undefined && typeof raw.id !== "string")
+            throw invalidCandidate(`Model output[${index}].id must be a string`, `output[${index}].id`);
+        if (raw.name !== undefined && typeof raw.name !== "string")
+            throw invalidCandidate(`Model output[${index}].name must be a string`, `output[${index}].name`);
+        let args;
+        try {
+            args = copyJsonObject(raw.args, `Model output[${index}].args`);
+        }
+        catch (error) {
+            throw isHarnessError(error) && error.code === "model.invalid-candidate"
+                ? error
+                : invalidCandidate(`Model output[${index}].args must be a JSON object`, `output[${index}].args`, error);
+        }
+        if (raw.raw !== undefined && typeof raw.raw !== "string")
+            throw invalidCandidate(`Model output[${index}].raw must be a string`, `output[${index}].raw`);
+        return Object.freeze({
+            type: "tool-call",
+            id: typeof raw.id === "string" ? raw.id : "",
+            name: typeof raw.name === "string" ? raw.name : "",
+            args,
+            ...(raw.raw === undefined ? {} : { raw: raw.raw }),
+        });
+    }
+    throw invalidCandidate(`Model output[${index}] has unknown type`, `output[${index}].type`);
+}
+function normalizeFinishReason(value) {
+    if (value === "error" || value === "aborted")
+        throw invalidCandidate("Model candidate finishReason cannot be error or aborted", "finishReason");
+    if (typeof value !== "string" || !FINISH_REASONS.has(value))
+        throw invalidCandidate("Model candidate finishReason is invalid", "finishReason");
+    return value;
+}
+function normalizeUsage(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw invalidCandidate("Model candidate usage must be an object", "usage");
+    rejectUnknownKeys(value, [...USAGE_TOKEN_KEYS, "costUsd"], "Model candidate usage");
+    const raw = value;
+    const usage = {};
+    for (const key of USAGE_TOKEN_KEYS) {
+        if (raw[key] === undefined)
+            continue;
+        if (!isNonNegativeInteger(raw[key]))
+            throw invalidCandidate(`Model candidate usage.${key} must be a non-negative integer`, `usage.${key}`);
+        usage[key] = raw[key];
+    }
+    if (raw.costUsd !== undefined) {
+        if (!isFiniteNumber(raw.costUsd))
+            throw invalidCandidate("Model candidate usage.costUsd must be a finite number", "usage.costUsd");
+        usage.costUsd = raw.costUsd;
+    }
+    return Object.freeze(usage);
+}
+function normalizeEvidence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw invalidCandidate("Model candidate evidence must be an object", "evidence");
+    rejectUnknownKeys(value, ["requestId", "resolvedModel", "warnings", "extras"], "Model candidate evidence");
+    const raw = value;
+    if (raw.requestId !== undefined && typeof raw.requestId !== "string")
+        throw invalidCandidate("Model candidate evidence.requestId must be a string", "evidence.requestId");
+    if (raw.resolvedModel !== undefined && typeof raw.resolvedModel !== "string")
+        throw invalidCandidate("Model candidate evidence.resolvedModel must be a string", "evidence.resolvedModel");
+    let warnings;
+    if (raw.warnings !== undefined) {
+        if (!Array.isArray(raw.warnings) || raw.warnings.some((item) => typeof item !== "string"))
+            throw invalidCandidate("Model candidate evidence.warnings must be an array of strings", "evidence.warnings");
+        warnings = Object.freeze([...raw.warnings]);
+    }
+    const extras = raw.extras === undefined
+        ? undefined
+        : copyJsonObject(raw.extras, "Model candidate evidence.extras");
+    return Object.freeze({
+        ...(typeof raw.requestId === "string" ? { requestId: raw.requestId } : {}),
+        ...(typeof raw.resolvedModel === "string" ? { resolvedModel: raw.resolvedModel } : {}),
+        ...(warnings === undefined ? {} : { warnings }),
+        ...(extras === undefined ? {} : { extras }),
+    });
+}
+function freezeBlocks(blocks) {
+    return Object.freeze(blocks.map((block) => Object.freeze(block)));
+}
+function rejectUnknownKeys(value, allowed, path) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key))
+            throw invalidCandidate(`${path} has unknown key '${key}'`, `${path}.${key}`);
+    }
+}
+function invalidCandidate(message, path, cause) {
+    return new HarnessError("model.invalid-candidate", message, {
+        ...(cause === undefined ? {} : { cause }),
+        ...(path === undefined ? {} : { details: { path } }),
+    });
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}

package/dist/session/event-log.d.ts

@@ -0,0 +1,11 @@
+import type { SessionEvent } from "../types/session.js";
+/** Session-lifetime conversation log. Each stream() call replays from the start. */
+export declare class SessionEventLog implements AsyncIterable<SessionEvent> {
+    private readonly events;
+    private readonly subscribers;
+    private done;
+    emit(event: SessionEvent): void;
+    finish(): void;
+    [Symbol.asyncIterator](): AsyncIterator<SessionEvent>;
+    private wake;
+}

package/dist/session/event-log.js

@@ -0,0 +1,63 @@
+/** Session-lifetime conversation log. Each stream() call replays from the start. */
+export class SessionEventLog {
+    events = [];
+    subscribers = [];
+    done = false;
+    emit(event) {
+        if (this.done)
+            return;
+        this.events.push(event);
+        this.wake();
+    }
+    finish() {
+        if (this.done)
+            return;
+        this.done = true;
+        this.wake();
+        this.subscribers.length = 0;
+    }
+    [Symbol.asyncIterator]() {
+        let index = 0;
+        let closed = false;
+        const waiting = [];
+        this.subscribers.push(waiting);
+        const detach = () => {
+            const position = this.subscribers.indexOf(waiting);
+            if (position !== -1)
+                this.subscribers.splice(position, 1);
+        };
+        const complete = () => {
+            closed = true;
+            detach();
+            return { done: true, value: undefined };
+        };
+        const pull = () => {
+            if (closed)
+                return Promise.resolve({ done: true, value: undefined });
+            if (index < this.events.length)
+                return Promise.resolve({ done: false, value: this.events[index++] });
+            if (this.done)
+                return Promise.resolve(complete());
+            return new Promise((resolve) => {
+                waiting.push(() => {
+                    void pull().then(resolve);
+                });
+            });
+        };
+        return {
+            next: pull,
+            return: () => {
+                const result = complete();
+                while (waiting.length)
+                    waiting.shift()();
+                return Promise.resolve(result);
+            },
+        };
+    }
+    wake() {
+        for (const waiting of this.subscribers) {
+            while (waiting.length)
+                waiting.shift()();
+        }
+    }
+}

package/dist/session/input-queue.d.ts

@@ -0,0 +1,29 @@
+import type { InputEvent, InputOptions } from "../types/session.js";
+import { SubmissionStream } from "./submission-stream.js";
+export interface QueuedInput {
+    readonly event: InputEvent;
+    readonly options?: InputOptions;
+    readonly stream: SubmissionStream;
+    cancelled: boolean;
+}
+export interface QueueAbortHandlers {
+    readonly isActive: () => boolean;
+    readonly abortActive: (reason: unknown) => void;
+    readonly cancelQueued: () => void;
+}
+export declare function isInteractionReply(event: InputEvent): event is Extract<InputEvent, {
+    kind: "approve" | "respond";
+}>;
+export declare function snapshotInput(event: InputEvent): InputEvent;
+/** Serializes ordinary input while allowing a matching interaction reply to resume immediately. */
+export declare class InputQueue {
+    private readonly values;
+    get size(): number;
+    add(input: QueuedInput, priority?: boolean): void;
+    take(waitingForInteraction: boolean): QueuedInput | undefined;
+    takeInterrupts(): QueuedInput[];
+    remove(input: QueuedInput): boolean;
+    drain(): readonly QueuedInput[];
+}
+/** Binds one caller-provided signal to its queue entry and always removes the listener at completion. */
+export declare function watchInputAbort(input: QueuedInput, handlers: QueueAbortHandlers): void;