@anureo/sdk 0.0.0-stage → 0.3.0

package/src/structured-output/stdio.mjs

@@ -0,0 +1,83 @@
+/**
+ * Internal package entry resolved by OutputBridgeManager.create and launched by the native MCP
+ * client over stdio. ANUREO_OUTPUT_BRIDGE_URL and ANUREO_OUTPUT_BRIDGE_AUTH identify the private
+ * session lease. Forward tool listings and calls over HTTP. Begin shutdown on stdin end, SIGTERM,
+ * SIGINT, parent loss or failed upstream ping. Startup failures write a safe code to stderr.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+
+const parent = process.ppid
+const upstream = new Client({ name: 'anureo-output-proxy', version: '1.0.0' })
+const downstream = new Server({ name: 'anureo_output', version: '1.0.0' }, { capabilities: { tools: {} } })
+let closing = false
+let ready = false
+let checking = false
+
+/**
+ * Stop heartbeat, settle both MCP peer closes (ignoring their rejections), then exit with code.
+ * Stdin-end and signal listeners start cleanup. checkLiveness and startup failure await it.
+ * The first call selects the exit code (default 0). Later calls return without waiting.
+ */
+async function close(code = 0) {
+  if (closing) return
+  closing = true
+  clearInterval(heartbeat)
+  await Promise.allSettled([downstream.close(), upstream.close()])
+  process.exit(code)
+}
+
+/**
+ * The 2-second heartbeat invokes this without awaiting. Check owner identity even during startup,
+ * then ping only after upstream connects, allowing 3 seconds for a reply. Owner loss requests
+ * exit with 0 and ping failure requests exit with 1. Skip ticks while a ping is pending.
+ */
+async function checkLiveness() {
+  if (closing || checking) return
+  if (process.ppid !== parent || process.ppid === 1) {
+    await close()
+    return
+  }
+  if (!ready) return
+  checking = true
+  try { await upstream.ping({ timeout: 3000 }) } catch { await close(1) }
+  finally { checking = false }
+}
+
+/**
+ * Connect upstream with the required lease URL/credential before attaching downstream stdio.
+ * Upstream initialization uses a 10-second request timeout. Connection enables heartbeat pings. The SDK
+ * invokes the registered downstream handlers, which return upstream tool lists/results or propagate rejection
+ * to protocol handling. Configuration/connection failures reject to the module entry for safe stderr
+ * reporting and close(1).
+ */
+async function connectProxy() {
+  const url = process.env.ANUREO_OUTPUT_BRIDGE_URL
+  const credential = process.env.ANUREO_OUTPUT_BRIDGE_AUTH
+  if (!url || !credential) throw new Error('configuration')
+  const transport = new StreamableHTTPClientTransport(new URL(url), {
+    requestInit: { headers: { Authorization: `Bearer ${credential}` } },
+  })
+  await upstream.connect(transport, { timeout: 10000 })
+  ready = true
+  downstream.setRequestHandler(ListToolsRequestSchema, () => upstream.listTools())
+  downstream.setRequestHandler(CallToolRequestSchema, request => upstream.callTool(request.params))
+  await downstream.connect(new StdioServerTransport())
+}
+
+// Register shutdown before connecting so startup is covered by the owner and signal checks.
+const heartbeat = setInterval(() => { void checkLiveness() }, 2000)
+heartbeat.unref()
+process.stdin.once('end', () => { void close() })
+process.once('SIGTERM', () => { void close() })
+process.once('SIGINT', () => { void close() })
+
+try {
+  await connectProxy()
+} catch {
+  process.stderr.write('STRUCTURED_OUTPUT_BRIDGE_FAILED\n')
+  await close(1)
+}

package/src/structured-output/tool.d.ts

@@ -0,0 +1,38 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Internal reserved MCP identity for bridge configuration and fallback instructions.
+ * OutputSession.prepareBridge rejects configurations that already claim this name before lease
+ * allocation. OutputBridgeManager.create assigns it to the injected server configuration and
+ * fallbackInput names it in the model's submission instructions.
+ */
+export declare const OUTPUT_SERVER_NAME = "anureo_output";
+/**
+ * Wire contract exposed to MCP clients by the ListTools handler registered in createToolServer.
+ * Pass the current submission's exact outputId and its candidate JSON value. OutputSession.submitValue
+ * checks the envelope and ID before submitCandidate validates the value against the submission schema.
+ * Acceptance is provisional until terminal publication rechecks the value and its privacy projection.
+ */
+export declare const OUTPUT_TOOL: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            outputId: {
+                type: string;
+                minLength: number;
+            };
+            value: {};
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+};
+/**
+ * Format a caller-supplied safe code, optional issues and recovery guidance as an MCP error result.
+ * The CallTool handler registered in createToolServer returns this for expired leases or unknown
+ * tools. OutputSession.submitValue returns it for envelope and candidate rejections. Supply safe,
+ * JSON-serializable details because they go directly to the client. Serialization failures throw.
+ * Falsy message and issues arguments are omitted from the JSON text.
+ */
+export declare function toolError(code: string, issues?: unknown, message?: string): CallToolResult;

package/src/structured-output/tool.js

@@ -0,0 +1,34 @@
+/**
+ * Internal reserved MCP identity for bridge configuration and fallback instructions.
+ * OutputSession.prepareBridge rejects configurations that already claim this name before lease
+ * allocation. OutputBridgeManager.create assigns it to the injected server configuration and
+ * fallbackInput names it in the model's submission instructions.
+ */
+export const OUTPUT_SERVER_NAME = 'anureo_output';
+/**
+ * Wire contract exposed to MCP clients by the ListTools handler registered in createToolServer.
+ * Pass the current submission's exact outputId and its candidate JSON value. OutputSession.submitValue
+ * checks the envelope and ID before submitCandidate validates the value against the submission schema.
+ * Acceptance is provisional until terminal publication rechecks the value and its privacy projection.
+ */
+export const OUTPUT_TOOL = {
+    name: 'submit_result',
+    description: 'Submit the final structured result for the current task. Use its outputId and satisfy its JSON Schema. After acceptance, end the task. On validation errors, correct the value and submit again.',
+    inputSchema: {
+        type: 'object',
+        properties: { outputId: { type: 'string', minLength: 1 }, value: {} },
+        required: ['outputId', 'value'],
+        additionalProperties: false,
+    },
+};
+/**
+ * Format a caller-supplied safe code, optional issues and recovery guidance as an MCP error result.
+ * The CallTool handler registered in createToolServer returns this for expired leases or unknown
+ * tools. OutputSession.submitValue returns it for envelope and candidate rejections. Supply safe,
+ * JSON-serializable details because they go directly to the client. Serialization failures throw.
+ * Falsy message and issues arguments are omitted from the JSON text.
+ */
+export function toolError(code, issues, message) {
+    const text = JSON.stringify({ code, ...(message ? { message } : {}), ...(issues ? { issues } : {}) });
+    return { isError: true, content: [{ type: 'text', text }] };
+}

package/src/turn.d.ts

@@ -0,0 +1,75 @@
+import type { AhpEvent } from '@anureo/protocol';
+import type { ExecutionObservation } from "./lifecycle/execution-observation.js";
+import type { EventSubscriptionOptions, Input, RequestOptions, TurnResult } from "./types.js";
+/** Internal Session-to-Turn port exposed here for constructor typing. */
+export type { ExecutionObservation } from "./lifecycle/execution-observation.js";
+/**
+ * Observe one execution's live events and retained terminal result, and explicitly steer or interrupt it.
+ * Get a handle from Session.submit or Session.review once the input or review is associated with
+ * an execution. Use observe to create an independently disposable sibling.
+ */
+export declare class Turn {
+    private readonly execution;
+    /**
+     * Internal construction from the shared execution port. Session.submitExecution calls this when
+     * association resolves, and Turn.observe calls it to create a sibling with its own cancellation.
+     * The shared execution may already be terminal.
+     */
+    constructor(execution: ExecutionObservation);
+    /** The stable execution ID shared by sibling handles, available after disposal. */
+    get id(): string;
+    /**
+     * Subscribe immediately to future events for this execution without replay. Invalid queue limits
+     * throw INVALID_PARAMS synchronously. Buffered events drain before overflow or stream failure
+     * rejects reads. Exhaust or return the iterator to release it. While the subscription is live,
+     * abort or disposal completes pending reads and skips buffered events. An already ended stream's
+     * completion or failure is still observable, including when subscribing through a disposed handle.
+     */
+    events(options?: EventSubscriptionOptions): AsyncIterable<AhpEvent>;
+    /**
+     * Await the shared frozen terminal snapshot, including failed or interrupted status values.
+     * Reject with TURN_DISPOSED when called after disposal, or propagate observation closure and wait
+     * failures. Caller abort and the deadline (30 seconds by default) affect only this wait.
+     * Disposing the handle rejects its pending result waits with REQUEST_ABORTED.
+     */
+    result(wait?: RequestOptions): Promise<TurnResult>;
+    /**
+     * Append text or input blocks to this exact execution. Requires atomic turn matching support.
+     * Resolve after the native control receipt is validated. Use result to await execution completion.
+     * Normalization, admission, dispatch and wait failures reject. Omit the timeout to use the
+     * session's request deadline (30 seconds by default). A disposed handle throws TURN_DISPOSED
+     * synchronously. Wait cancellation leaves admitted work alive. Disposal leaves an already invoked
+     * control wait active.
+     */
+    steer(options: {
+        input: Input;
+    }, wait?: RequestOptions): Promise<void>;
+    /**
+     * Request interruption of this execution. Requires adapter support for turn interruption.
+     * Resolve after the native control receipt is validated. Use result to await terminal status.
+     * Admission, dispatch and wait failures reject. Omit the timeout to use the session's request
+     * deadline (30 seconds by default). A disposed handle throws TURN_DISPOSED synchronously. Wait
+     * cancellation leaves admitted work alive. Disposal leaves an already invoked control wait active.
+     */
+    interrupt(wait?: RequestOptions): Promise<void>;
+    /**
+     * Create an independently disposable handle for the same execution, including a retained terminal
+     * result when available. Throws TURN_DISPOSED synchronously if this handle is closed.
+     */
+    observe(): Turn;
+    /**
+     * Idempotently cancel this handle's live subscriptions and pending result waits before resolving.
+     * Sibling handles and explicit control waits retain their own lifetimes. Call interrupt to request
+     * native interruption while the handle is open.
+     */
+    dispose(): Promise<void>;
+    private disposed;
+    private readonly observationController;
+    /**
+     * events and result combine caller cancellation with this handle's disposal signal, so either can
+     * end a local observation without affecting siblings. Explicit control methods do not use it.
+     */
+    private observationSignal;
+    /** steer, interrupt and observe throw TURN_DISPOSED here before invoking a port or creating a sibling. */
+    private assertOpen;
+}

package/src/turn.js

@@ -0,0 +1,95 @@
+import { HarnessSdkError } from "./errors.js";
+import { waitForRequest } from "./request.js";
+/**
+ * Observe one execution's live events and retained terminal result, and explicitly steer or interrupt it.
+ * Get a handle from Session.submit or Session.review once the input or review is associated with
+ * an execution. Use observe to create an independently disposable sibling.
+ */
+export class Turn {
+    execution;
+    /**
+     * Internal construction from the shared execution port. Session.submitExecution calls this when
+     * association resolves, and Turn.observe calls it to create a sibling with its own cancellation.
+     * The shared execution may already be terminal.
+     */
+    constructor(execution) {
+        this.execution = execution;
+    }
+    /** The stable execution ID shared by sibling handles, available after disposal. */
+    get id() { return this.execution.id; }
+    /**
+     * Subscribe immediately to future events for this execution without replay. Invalid queue limits
+     * throw INVALID_PARAMS synchronously. Buffered events drain before overflow or stream failure
+     * rejects reads. Exhaust or return the iterator to release it. While the subscription is live,
+     * abort or disposal completes pending reads and skips buffered events. An already ended stream's
+     * completion or failure is still observable, including when subscribing through a disposed handle.
+     */
+    events(options = {}) {
+        return this.execution.events.subscribe({ ...options, signal: this.observationSignal(options.signal) });
+    }
+    /**
+     * Await the shared frozen terminal snapshot, including failed or interrupted status values.
+     * Reject with TURN_DISPOSED when called after disposal, or propagate observation closure and wait
+     * failures. Caller abort and the deadline (30 seconds by default) affect only this wait.
+     * Disposing the handle rejects its pending result waits with REQUEST_ABORTED.
+     */
+    result(wait = {}) {
+        if (this.disposed)
+            return Promise.reject(new HarnessSdkError('TURN_DISPOSED'));
+        return waitForRequest(() => this.execution.result, { ...wait, signal: this.observationSignal(wait.signal) });
+    }
+    /**
+     * Append text or input blocks to this exact execution. Requires atomic turn matching support.
+     * Resolve after the native control receipt is validated. Use result to await execution completion.
+     * Normalization, admission, dispatch and wait failures reject. Omit the timeout to use the
+     * session's request deadline (30 seconds by default). A disposed handle throws TURN_DISPOSED
+     * synchronously. Wait cancellation leaves admitted work alive. Disposal leaves an already invoked
+     * control wait active.
+     */
+    steer(options, wait) {
+        this.assertOpen();
+        return this.execution.steer(options.input, wait);
+    }
+    /**
+     * Request interruption of this execution. Requires adapter support for turn interruption.
+     * Resolve after the native control receipt is validated. Use result to await terminal status.
+     * Admission, dispatch and wait failures reject. Omit the timeout to use the session's request
+     * deadline (30 seconds by default). A disposed handle throws TURN_DISPOSED synchronously. Wait
+     * cancellation leaves admitted work alive. Disposal leaves an already invoked control wait active.
+     */
+    interrupt(wait) {
+        this.assertOpen();
+        return this.execution.interrupt(wait);
+    }
+    /**
+     * Create an independently disposable handle for the same execution, including a retained terminal
+     * result when available. Throws TURN_DISPOSED synchronously if this handle is closed.
+     */
+    observe() {
+        this.assertOpen();
+        return new Turn(this.execution);
+    }
+    /**
+     * Idempotently cancel this handle's live subscriptions and pending result waits before resolving.
+     * Sibling handles and explicit control waits retain their own lifetimes. Call interrupt to request
+     * native interruption while the handle is open.
+     */
+    async dispose() {
+        this.disposed = true;
+        this.observationController.abort();
+    }
+    disposed = false;
+    observationController = new AbortController();
+    /**
+     * events and result combine caller cancellation with this handle's disposal signal, so either can
+     * end a local observation without affecting siblings. Explicit control methods do not use it.
+     */
+    observationSignal(signal) {
+        return signal ? AbortSignal.any([signal, this.observationController.signal]) : this.observationController.signal;
+    }
+    /** steer, interrupt and observe throw TURN_DISPOSED here before invoking a port or creating a sibling. */
+    assertOpen() {
+        if (this.disposed)
+            throw new HarnessSdkError('TURN_DISPOSED');
+    }
+}

package/src/types.d.ts

@@ -0,0 +1,62 @@
+import type { HarnessError, InputBlock, Item, Usage } from '@anureo/protocol';
+/**
+ * Send text or protocol blocks through Session.submit or Turn.steer. Text becomes one text block
+ * and block arrays are cloned. Invalid input rejects before native dispatch.
+ */
+export type Input = string | readonly InputBlock[];
+/**
+ * Read the frozen terminal snapshot returned by Turn.result. Failed and interrupted executions
+ * resolve with those statuses. Closing observation before the terminal or ending the caller's wait
+ * rejects the promise. Request history/read separately for native history when supported.
+ */
+export type TurnResult = {
+    /** Text of final-phase agent messages in retained item order, separated by newlines. */
+    text: string;
+    /** Privacy-projected snapshots retained for this execution, including non-message items. */
+    items: readonly Item[];
+    /** Terminal turn-scoped usage, or the latest observed turn-scoped usage when the terminal has none. */
+    usage?: Usage;
+} & ({
+    status: 'completed';
+} | {
+    status: 'interrupted';
+    /** Safe native interruption details when supplied by the terminal event. */
+    error?: HarnessError;
+} | {
+    status: 'failed';
+    /** Safe terminal failure, with TURN_FAILED supplied when native details are absent. */
+    error: HarnessError;
+});
+/**
+ * Bound one caller's wait for a Client, Session or Turn operation. Abort or timeout after dispatch
+ * rejects the waiter with outcomeUnknown while native work can continue. Use an explicit interrupt
+ * operation to request that execution stop.
+ */
+export interface RequestOptions {
+    /** Stops this caller waiting; does not interrupt accepted native execution. */
+    signal?: AbortSignal;
+    /**
+     * Positive finite observation deadline in milliseconds; omission uses the operation default.
+     * Client/Session admission also rejects values above 2_147_483_647; standalone waits use host timers.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Configure an independent queue for Session.events or Turn.events. Invalid budgets throw at
+ * subscription. Overflow rejects that observer's reads after buffered events drain, without
+ * pausing the native producer. Exhaust or return the iterator, or abort this subscription.
+ */
+export interface EventSubscriptionOptions {
+    /** Aborts only this observer, releasing its pending read and membership. */
+    signal?: AbortSignal;
+    /** Independent observer budgets, each a positive safe integer; omission selects hub defaults. */
+    queue?: {
+        /** Maximum buffered regular events; defaults to 2048. Direct delivery to a pending read needs no slot. */
+        maxEvents?: number;
+        /**
+         * Maximum serialized bytes buffered for this observer; defaults to 16 MiB.
+         * Single events are also limited to the smaller of this budget and 8 MiB.
+         */
+        maxBytes?: number;
+    };
+}