@anureo/sdk 0.2.0 → 0.3.0

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

@@ -0,0 +1,8 @@
+import type { HarnessAdapter } from "../ports.js";
+import type { OutputLimits } from "./limits.js";
+/**
+ * Client's constructor installs this package-internal adapter wrapper without native I/O.
+ * The wrapper owns the native adapter, tracked output sessions and one lazy bridge manager.
+ * Client initializes before opening and awaits wrapper disposal after its Session cleanup.
+ */
+export declare function withStructuredOutput(adapter: HarnessAdapter, limits?: OutputLimits): HarnessAdapter;

package/src/structured-output/adapter.js

@@ -0,0 +1,54 @@
+// Owns adapter-wide structured-output resources.
+import { HarnessSdkError, sdkError } from "../errors.js";
+import { OutputBridgeManager } from "./bridge.js";
+import { checkRelease } from "./errors.js";
+import { OutputSession } from "./session.js";
+/**
+ * Client's constructor installs this package-internal adapter wrapper without native I/O.
+ * The wrapper owns the native adapter, tracked output sessions and one lazy bridge manager.
+ * Client initializes before opening and awaits wrapper disposal after its Session cleanup.
+ */
+export function withStructuredOutput(adapter, limits = {}) {
+    const manager = new OutputBridgeManager(limits.queue?.maxFrameBytes);
+    const sessions = new Set();
+    let nativeOutput = false;
+    return {
+        /** Client.initialize awaits native negotiation through this port and validates its result. Remember native schema support for later opens and propagate negotiation failures. */
+        async initialize(params) {
+            const result = await adapter.initialize(params);
+            nativeOutput = result.capabilities.turn?.outputSchema === true;
+            return result;
+        },
+        /**
+         * Client.attachSession awaits the opened wrapper before attaching it. Track the session
+         * before native open so adapter disposal can see it during setup. If setup fails, await
+         * session cleanup before rejecting with the setup cause or a safe release failure.
+         */
+        async openSession(params, sink) {
+            const session = new OutputSession({ params, sink, manager, limits, forget: () => sessions.delete(session) });
+            sessions.add(session);
+            try {
+                return await session.open({ adapter, nativeOutput });
+            }
+            catch (cause) {
+                try {
+                    await session.dispose();
+                }
+                catch {
+                    throw new HarnessSdkError('RESOURCE_RELEASE_FAILED', 'Structured output setup cleanup failed', false, sdkError(cause).outcomeUnknown);
+                }
+                throw cause;
+            }
+        },
+        /**
+         * Client.dispose awaits this after attempting Session cleanup. Settle tracked output session
+         * disposals before starting bridge manager and native adapter disposal. Classify rejected
+         * release promises after those stages settle.
+         */
+        async dispose() {
+            const results = await Promise.allSettled([...sessions].map(session => session.dispose()));
+            results.push(...await Promise.allSettled([manager.dispose(), adapter.dispose()]));
+            checkRelease(results);
+        },
+    };
+}

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

@@ -0,0 +1,81 @@
+import { type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { McpServer } from '@anureo/protocol';
+export { OUTPUT_SERVER_NAME, OUTPUT_TOOL, toolError } from "./tool.js";
+/** Internal endpoint and cleanup handle retained by OutputSession.prepareBridge. The manager owns the shared listener. */
+export interface OutputBridgeLease {
+    /** Native-reachable config containing lease credentials. Keep it out of public state and history. */
+    readonly config: McpServer;
+    /**
+     * Revoke admission immediately, then await active protocol closes. Reject with
+     * RESOURCE_RELEASE_FAILED if any close rejects. Other leases remain usable. Repeated calls
+     * return without waiting for an earlier disposal or retrying cleanup.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Internal bridge owner constructed by withStructuredOutput for one Client. OutputSession.prepareBridge
+ * requests independent session leases. The adapter wrapper must dispose this manager after session
+ * cleanup to release the shared listener, even when individual lease cleanup fails.
+ */
+export declare class OutputBridgeManager {
+    private readonly maxFrameBytes;
+    /** Set the HTTP body limit in bytes (default 8 MiB). A create call starts the listener on demand. */
+    constructor(maxFrameBytes?: number);
+    /**
+     * Allocate an authenticated endpoint and native MCP configuration, awaiting shared listener startup.
+     * OutputSession.prepareBridge supplies a serialized submitValue handler, injects config into native
+     * open params and on setup failure releases any acquired lease before publishing a warning. Stdio
+     * entry resolution happens before listener startup. Resolution and startup failures reject.
+     * Observing manager disposal before lease allocation rejects with CLIENT_DISPOSED. Keep credentials
+     * private and dispose the lease after use.
+     */
+    create(transport: 'http' | 'stdio', handler: Handler): Promise<OutputBridgeLease>;
+    /**
+     * Close admission, settle active protocol closes, then stop the listener and its connections.
+     * withStructuredOutput's dispose port awaits this after attempting session disposal and classifies
+     * shutdown rejection with other resource failures. Individual protocol close rejections are ignored
+     * here. Listener shutdown errors reject. Repeated calls return without awaiting an earlier disposal.
+     */
+    dispose(): Promise<void>;
+    private listener?;
+    private starting?;
+    private closed;
+    private readonly leases;
+    /**
+     * OutputBridgeManager.create awaits this port before allocating a lease. Lazily start one
+     * loopback HTTP listener and cache its port promise, including startup or disposal-race rejection.
+     */
+    private listen;
+    /**
+     * The listener's request callback starts this operation without awaiting it. Admit, parse and dispatch
+     * one request. Contain failures with a 500 status when headers permit, then release its concurrency permit.
+     * Accounting ends when dispatch/error handling settles, independently of response-close cleanup.
+     */
+    private handleRequest;
+    /**
+     * Apply endpoint, credential, host/origin, POST and 32-request concurrency checks in that order.
+     * Write the rejection response and return no lease on failure. handleRequest reserves the permit
+     * synchronously after success. An absent or empty Origin is allowed for native clients.
+     */
+    private admitRequest;
+    /**
+     * Read one bounded JSON body for handleRequest. Return undefined after a 413 size rejection or a
+     * 400 parse rejection. Stream failures reject into handleRequest's HTTP error path. Parsing waits
+     * for the body to end, while an oversized body is rejected immediately.
+     */
+    private readRequestBody;
+    /**
+     * Connect a fresh stateless MCP server/transport and await its HTTP dispatch for handleRequest.
+     * Setup or dispatch rejections reach handleRequest's HTTP error path. Response close removes
+     * the server and attempts best-effort close. Lease and manager disposal also close tracked servers.
+     */
+    private dispatchRequest;
+    /**
+     * The returned lease callback delegates here when OutputSession.release or prepareBridge awaits
+     * disposal. Revoke this endpoint before awaiting closes, clear its server registry after settlement
+     * and reject RESOURCE_RELEASE_FAILED on any close rejection. Revocation is permanent even on failure.
+     */
+    private releaseLease;
+}
+/** OutputSession.prepareBridge supplies a serialized submitValue callback whose result becomes the tool response. */
+type Handler = (args: unknown) => Promise<CallToolResult>;

package/src/structured-output/bridge.js

@@ -0,0 +1,274 @@
+// Owns the shared loopback listener, authenticated session leases and request-scoped MCP transports.
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { OUTPUT_SERVER_NAME, OUTPUT_TOOL, toolError } from "./tool.js";
+import { HarnessSdkError } from "../errors.js";
+// Preserve existing bridge imports while production callers depend on the tool contract directly.
+export { OUTPUT_SERVER_NAME, OUTPUT_TOOL, toolError } from "./tool.js";
+/**
+ * Internal bridge owner constructed by withStructuredOutput for one Client. OutputSession.prepareBridge
+ * requests independent session leases. The adapter wrapper must dispose this manager after session
+ * cleanup to release the shared listener, even when individual lease cleanup fails.
+ */
+export class OutputBridgeManager {
+    maxFrameBytes;
+    /** Set the HTTP body limit in bytes (default 8 MiB). A create call starts the listener on demand. */
+    constructor(maxFrameBytes = 8 * 1024 * 1024) {
+        this.maxFrameBytes = maxFrameBytes;
+    }
+    /**
+     * Allocate an authenticated endpoint and native MCP configuration, awaiting shared listener startup.
+     * OutputSession.prepareBridge supplies a serialized submitValue handler, injects config into native
+     * open params and on setup failure releases any acquired lease before publishing a warning. Stdio
+     * entry resolution happens before listener startup. Resolution and startup failures reject.
+     * Observing manager disposal before lease allocation rejects with CLIENT_DISPOSED. Keep credentials
+     * private and dispose the lease after use.
+     */
+    async create(transport, handler) {
+        if (this.closed)
+            throw new HarnessSdkError('CLIENT_DISPOSED');
+        const resolvedTransport = transport === 'stdio'
+            ? { type: 'stdio', proxy: createRequire(import.meta.url).resolve('@anureo/sdk/structured-output-stdio') }
+            : { type: transport };
+        const port = await this.listen();
+        if (this.closed)
+            throw new HarnessSdkError('CLIENT_DISPOSED');
+        const path = `/mcp/${randomBytes(24).toString('hex')}`;
+        const credential = randomBytes(32).toString('hex');
+        const lease = { credential, handler, active: new Set(), disposed: false, requests: 0 };
+        this.leases.set(path, lease);
+        const url = `http://127.0.0.1:${port}${path}`;
+        return {
+            config: bridgeConfig({ transport: resolvedTransport, url, credential }),
+            dispose: () => this.releaseLease(path, lease),
+        };
+    }
+    /**
+     * Close admission, settle active protocol closes, then stop the listener and its connections.
+     * withStructuredOutput's dispose port awaits this after attempting session disposal and classifies
+     * shutdown rejection with other resource failures. Individual protocol close rejections are ignored
+     * here. Listener shutdown errors reject. Repeated calls return without awaiting an earlier disposal.
+     */
+    async dispose() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const lease of this.leases.values()) {
+            lease.disposed = true;
+            await closeLeaseServers(lease);
+        }
+        this.leases.clear();
+        if (this.starting)
+            await this.starting.catch(() => { });
+        const listener = this.listener;
+        if (listener?.listening)
+            await stopListener(listener);
+    }
+    listener;
+    starting;
+    closed = false;
+    leases = new Map();
+    /**
+     * OutputBridgeManager.create awaits this port before allocating a lease. Lazily start one
+     * loopback HTTP listener and cache its port promise, including startup or disposal-race rejection.
+     */
+    listen() {
+        return this.starting ??= new Promise((resolve, reject) => {
+            const listener = this.listener = createServer((req, res) => {
+                void this.handleRequest(req, res, listener);
+            });
+            listener.requestTimeout = 30_000;
+            listener.headersTimeout = 10_000;
+            listener.once('error', reject);
+            listener.listen(0, '127.0.0.1', () => {
+                const address = listener.address();
+                if (!address || typeof address === 'string') {
+                    reject(new HarnessSdkError('STRUCTURED_OUTPUT_BRIDGE_FAILED'));
+                    return;
+                }
+                if (this.closed) {
+                    listener.close();
+                    reject(new HarnessSdkError('CLIENT_DISPOSED'));
+                    return;
+                }
+                resolve(address.port);
+            });
+        });
+    }
+    /**
+     * The listener's request callback starts this operation without awaiting it. Admit, parse and dispatch
+     * one request. Contain failures with a 500 status when headers permit, then release its concurrency permit.
+     * Accounting ends when dispatch/error handling settles, independently of response-close cleanup.
+     */
+    handleRequest(req, res, listener) {
+        let countedLease;
+        // Keep accounting outside dispatch so an error response precedes permit release.
+        return (async () => {
+            const lease = this.admitRequest(req, res, listener);
+            if (!lease)
+                return;
+            lease.requests++;
+            countedLease = lease;
+            const body = await this.readRequestBody(req, res);
+            if (body === undefined)
+                return;
+            if (lease.disposed) {
+                res.writeHead(404).end();
+                return;
+            }
+            await this.dispatchRequest(req, res, body, lease);
+        })().catch(() => {
+            if (!res.headersSent)
+                res.writeHead(500);
+            res.end();
+        }).finally(() => {
+            if (countedLease)
+                countedLease.requests--;
+        });
+    }
+    /**
+     * Apply endpoint, credential, host/origin, POST and 32-request concurrency checks in that order.
+     * Write the rejection response and return no lease on failure. handleRequest reserves the permit
+     * synchronously after success. An absent or empty Origin is allowed for native clients.
+     */
+    admitRequest(req, res, listener) {
+        const lease = this.leases.get(req.url ?? '');
+        if (this.closed || !lease || lease.disposed) {
+            res.writeHead(404).end();
+            return;
+        }
+        if (req.headers.authorization !== `Bearer ${lease.credential}`) {
+            res.writeHead(401).end();
+            return;
+        }
+        const address = listener.address();
+        const expectedHost = typeof address === 'object' && address ? `127.0.0.1:${address.port}` : '';
+        const origin = req.headers.origin;
+        if (req.headers.host !== expectedHost || (origin && origin !== `http://${expectedHost}`)) {
+            res.writeHead(403).end();
+            return;
+        }
+        if (req.method !== 'POST') {
+            res.writeHead(405).end();
+            return;
+        }
+        if (lease.requests >= 32) {
+            res.writeHead(429).end();
+            return;
+        }
+        return lease;
+    }
+    /**
+     * Read one bounded JSON body for handleRequest. Return undefined after a 413 size rejection or a
+     * 400 parse rejection. Stream failures reject into handleRequest's HTTP error path. Parsing waits
+     * for the body to end, while an oversized body is rejected immediately.
+     */
+    async readRequestBody(req, res) {
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of req) {
+            size += chunk.length;
+            if (size > this.maxFrameBytes) {
+                res.writeHead(413).end();
+                return;
+            }
+            chunks.push(Buffer.from(chunk));
+        }
+        try {
+            return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch {
+            res.writeHead(400).end();
+            return;
+        }
+    }
+    /**
+     * Connect a fresh stateless MCP server/transport and await its HTTP dispatch for handleRequest.
+     * Setup or dispatch rejections reach handleRequest's HTTP error path. Response close removes
+     * the server and attempts best-effort close. Lease and manager disposal also close tracked servers.
+     */
+    async dispatchRequest(req, res, body, lease) {
+        const server = createToolServer(lease);
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+        lease.active.add(server);
+        res.once('close', () => {
+            lease.active.delete(server);
+            void server.close().catch(() => { });
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, body);
+    }
+    /**
+     * The returned lease callback delegates here when OutputSession.release or prepareBridge awaits
+     * disposal. Revoke this endpoint before awaiting closes, clear its server registry after settlement
+     * and reject RESOURCE_RELEASE_FAILED on any close rejection. Revocation is permanent even on failure.
+     */
+    async releaseLease(path, lease) {
+        if (lease.disposed)
+            return;
+        lease.disposed = true;
+        this.leases.delete(path);
+        const results = await closeLeaseServers(lease);
+        lease.active.clear();
+        if (results.some(result => result.status === 'rejected'))
+            throw new HarnessSdkError('RESOURCE_RELEASE_FAILED');
+    }
+}
+/** Build native config for create using the resolved transport, with the bearer credential in headers or subprocess env. */
+function bridgeConfig({ transport, url, credential }) {
+    if (transport.type === 'http') {
+        return { type: 'http', name: OUTPUT_SERVER_NAME, url, headers: { Authorization: `Bearer ${credential}` } };
+    }
+    return {
+        type: 'stdio',
+        name: OUTPUT_SERVER_NAME,
+        command: process.execPath,
+        args: [transport.proxy],
+        env: { ANUREO_OUTPUT_BRIDGE_URL: url, ANUREO_OUTPUT_BRIDGE_AUTH: credential },
+    };
+}
+/**
+ * Register MCP tool handlers for dispatchRequest before it connects the server. The SDK invokes
+ * them to list the shared tool or call the lease handler after checking revocation and tool name.
+ * The SDK handles handler rejections as protocol failures. dispatchRequest owns connection and tracking.
+ */
+function createToolServer(lease) {
+    const server = new Server({ name: OUTPUT_SERVER_NAME, version: '1.0.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [OUTPUT_TOOL] }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        if (lease.disposed)
+            return toolError('STRUCTURED_OUTPUT_EXPIRED');
+        if (request.params.name !== OUTPUT_TOOL.name)
+            return toolError('UNKNOWN_TOOL');
+        return lease.handler(request.params.arguments);
+    });
+    return server;
+}
+/**
+ * Snapshot and close every currently active server for releaseLease or manager disposal, settling all
+ * rejections so each caller can apply its own failure and registry policy. Callers revoke admission first.
+ */
+function closeLeaseServers(lease) {
+    return Promise.allSettled([...lease.active].map(server => server.close()));
+}
+/**
+ * Stop a listening server after OutputBridgeManager.dispose settles protocol cleanup and startup.
+ * Force remaining connections closed so idle HTTP peers cannot hold disposal open. Resolve after
+ * listener closure, ignoring an already-stopped race, and reject other listener shutdown errors.
+ */
+function stopListener(listener) {
+    const stopped = new Promise((resolve, reject) => {
+        listener.close(error => {
+            if (error && error.code !== 'ERR_SERVER_NOT_RUNNING')
+                reject(error);
+            else
+                resolve();
+        });
+    });
+    listener.closeAllConnections();
+    return stopped;
+}

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

@@ -0,0 +1,17 @@
+import type { HarnessError } from '@anureo/protocol';
+/**
+ * Return a nonretryable, known-outcome protocol failure using the code as its message.
+ * OutputSession.bind retains binding conflicts, submitCandidate returns these failures on candidate
+ * rejection and publishOutput embeds them in failed terminals consumed by Session and Turn.result.
+ * Supply safe codes and JSON-compatible details. Details are retained by reference.
+ */
+export declare function failure(code: string, details?: Record<string, unknown>): HarnessError;
+/**
+ * withStructuredOutput.dispose and OutputSession.release/dispose call this after owned release stages
+ * settle. Return void when all attempts fulfilled, throw the single normalized failure, or aggregate
+ * multiple failures with flattened release diagnostics. The aggregate outcome is unknown if any
+ * normalized cause has an unknown outcome. sdkError preserves existing SDK errors.
+ * Callers still own every cleanup
+ * attempt and decide how the resulting rejection reaches Client or Session disposal consumers.
+ */
+export declare function checkRelease(results: PromiseSettledResult<unknown>[]): void;

package/src/structured-output/errors.js

@@ -0,0 +1,31 @@
+import { HarnessSdkError, sdkError } from "../errors.js";
+/**
+ * Return a nonretryable, known-outcome protocol failure using the code as its message.
+ * OutputSession.bind retains binding conflicts, submitCandidate returns these failures on candidate
+ * rejection and publishOutput embeds them in failed terminals consumed by Session and Turn.result.
+ * Supply safe codes and JSON-compatible details. Details are retained by reference.
+ */
+export function failure(code, details) {
+    return { code, message: code, retryable: false, outcomeUnknown: false, ...(details ? { details: details } : {}) };
+}
+/**
+ * withStructuredOutput.dispose and OutputSession.release/dispose call this after owned release stages
+ * settle. Return void when all attempts fulfilled, throw the single normalized failure, or aggregate
+ * multiple failures with flattened release diagnostics. The aggregate outcome is unknown if any
+ * normalized cause has an unknown outcome. sdkError preserves existing SDK errors.
+ * Callers still own every cleanup
+ * attempt and decide how the resulting rejection reaches Client or Session disposal consumers.
+ */
+export function checkRelease(results) {
+    const causes = results
+        .filter((result) => result.status === 'rejected')
+        .map(result => sdkError(result.reason, 'RESOURCE_RELEASE_FAILED', true));
+    if (causes.length === 0)
+        return;
+    if (causes.length === 1)
+        throw causes[0];
+    const errors = causes.flatMap(error => error.code === 'RESOURCE_RELEASE_FAILED' && Array.isArray(error.details?.errors)
+        ? error.details.errors
+        : [{ code: error.code, outcomeUnknown: error.outcomeUnknown }]);
+    throw new HarnessSdkError('RESOURCE_RELEASE_FAILED', 'Structured output resources could not be released', false, causes.some(error => error.outcomeUnknown), { errors });
+}

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

@@ -0,0 +1,19 @@
+import type { QueueLimits } from "../queue.js";
+/**
+ * Client passes event and retention budgets through withStructuredOutput to each OutputSession.
+ * Client validates scalar retention limits during construction. The wrapper also uses the frame
+ * budget when constructing the bridge manager. Omitted values use the consuming operation's defaults.
+ */
+export interface OutputLimits {
+    /**
+     * Queued plus held output events: maxEvents defaults to 2048 and maxBytes to 16 MiB.
+     * maxFrameBytes defaults to 8 MiB per event, transformed request or bridge request body.
+     */
+    queue?: QueueLimits;
+    /** Separate count caps for retained output submissions and terminal-version markers, each defaulting to 1024. */
+    maxSubmissions?: number;
+    /** Serialized UTF-8 byte limit for session-wide output retention and for each candidate, defaulting to 16 MiB. */
+    maxResultBytes?: number;
+    /** Distinct text-bearing item cap within each structured submission, defaulting to 2048. */
+    maxItems?: number;
+}

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

@@ -0,0 +1,20 @@
+import type { JsonSchema } from '@anureo/protocol';
+/**
+ * Prepare a detached schema and synchronous candidate checks without network I/O or source mutation.
+ * This package-internal compiler defaults to draft-07, supports explicit 2020-12 and ignores
+ * formats during value checks. Unsupported or invalid definitions throw INVALID_PARAMS. Cloning
+ * failures propagate directly. OutputSession.prepareOutput compiles before retaining submission state
+ * or dispatching input. The returned checks require no disposal.
+ */
+export declare function compileOutputSchema(source: JsonSchema): {
+    schema: JsonSchema;
+    check: (value: unknown) => void;
+    /**
+     * Decode and check JSON, throwing STRUCTURED_OUTPUT_MISSING for blank text,
+     * STRUCTURED_OUTPUT_NOT_JSON for malformed JSON or check's invalid-value error for a mismatch.
+     * OutputSession.outputValue parses native finals; publishOutput rechecks projected JSON so
+     * privacy redaction cannot bypass schema constraints. publishOutput turns parse failures into a
+     * failed terminal, using STRUCTURED_OUTPUT_REDACTED when the projected JSON fails revalidation.
+     */
+    parse(text: string): unknown;
+};

package/src/structured-output/schema.js

@@ -0,0 +1,122 @@
+// Owns synchronous local schema compilation and value checks.
+import Ajv from 'ajv';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { HarnessSdkError } from "../errors.js";
+/**
+ * Prepare a detached schema and synchronous candidate checks without network I/O or source mutation.
+ * This package-internal compiler defaults to draft-07, supports explicit 2020-12 and ignores
+ * formats during value checks. Unsupported or invalid definitions throw INVALID_PARAMS. Cloning
+ * failures propagate directly. OutputSession.prepareOutput compiles before retaining submission state
+ * or dispatching input. The returned checks require no disposal.
+ */
+export function compileOutputSchema(source) {
+    const schema = structuredClone(source);
+    const validate = compileValidator(schema);
+    /**
+     * Check a value without coercion or default insertion. Throw STRUCTURED_OUTPUT_INVALID with at
+     * most sixteen path/keyword issues on mismatch. OutputSession.submitCandidate converts failures
+     * into retry decisions. OutputSession.publishOutput converts them into failed terminals before serialization.
+     */
+    const check = (value) => {
+        if (validate(value))
+            return;
+        const issues = validate.errors?.slice(0, 16).map(error => ({ path: error.instancePath, code: error.keyword })) ?? [];
+        throw new HarnessSdkError('STRUCTURED_OUTPUT_INVALID', 'Output does not match its schema', false, false, { issues });
+    };
+    return {
+        schema,
+        check,
+        /**
+         * Decode and check JSON, throwing STRUCTURED_OUTPUT_MISSING for blank text,
+         * STRUCTURED_OUTPUT_NOT_JSON for malformed JSON or check's invalid-value error for a mismatch.
+         * OutputSession.outputValue parses native finals; publishOutput rechecks projected JSON so
+         * privacy redaction cannot bypass schema constraints. publishOutput turns parse failures into a
+         * failed terminal, using STRUCTURED_OUTPUT_REDACTED when the projected JSON fails revalidation.
+         */
+        parse(text) {
+            if (!text.trim())
+                throw new HarnessSdkError('STRUCTURED_OUTPUT_MISSING');
+            let value;
+            try {
+                value = JSON.parse(text);
+            }
+            catch {
+                throw new HarnessSdkError('STRUCTURED_OUTPUT_NOT_JSON');
+            }
+            check(value);
+            return value;
+        },
+    };
+}
+/**
+ * Compile an already cloned schema for compileOutputSchema. Normalize definition and compilation
+ * failures to INVALID_PARAMS, leaving an existing HarnessSdkError intact.
+ */
+function compileValidator(schema) {
+    try {
+        validateSchemaNode(schema, 0);
+        const engine = schemaEngine(schema);
+        const ajv = new engine({ allErrors: true, strict: false, validateFormats: false, multipleOfPrecision: 6, logger: false });
+        return ajv.compile(schema);
+    }
+    catch (cause) {
+        if (cause instanceof HarnessSdkError)
+            throw cause;
+        throw new HarnessSdkError('INVALID_PARAMS', 'Unsupported or invalid output schema');
+    }
+}
+/**
+ * Choose the Ajv implementation for the root dialect after traversal. An absent dialect uses
+ * draft-07, including for boolean schemas. compileValidator normalizes unsupported dialect errors.
+ */
+function schemaEngine(schema) {
+    const dialect = typeof schema === 'object' ? schema.$schema : undefined;
+    switch (dialect) {
+        case undefined:
+        case 'http://json-schema.org/draft-07/schema#':
+            return Ajv;
+        case 'https://json-schema.org/draft/2020-12/schema':
+            return Ajv2020;
+        default:
+            throw new Error('dialect');
+    }
+}
+/**
+ * Reject non-fragment references and async schemas at visited nodes, and traversal beyond 128
+ * levels, for compileValidator. Follow the supported child keywords so example/default instance data
+ * stays opaque. Check depth even for absent or scalar children to preserve the traversal bound.
+ */
+function validateSchemaNode(node, depth) {
+    if (depth > 128)
+        throw new Error('depth');
+    if (!node || typeof node !== 'object')
+        return;
+    const value = node;
+    assertLocalReference(value.$ref);
+    assertLocalReference(value.$dynamicRef);
+    if (value.$async)
+        throw new Error('async schema');
+    const visitChild = (child) => validateSchemaNode(child, depth + 1);
+    for (const key of ['properties', 'patternProperties', 'definitions', '$defs', 'dependentSchemas']) {
+        const children = value[key];
+        if (children && typeof children === 'object')
+            Object.values(children).forEach(visitChild);
+    }
+    for (const key of ['allOf', 'anyOf', 'oneOf', 'prefixItems']) {
+        const children = value[key];
+        if (Array.isArray(children))
+            children.forEach(visitChild);
+    }
+    for (const key of ['items', 'contains', 'additionalProperties', 'additionalItems', 'propertyNames', 'not', 'if', 'then', 'else']) {
+        const child = value[key];
+        if (Array.isArray(child))
+            child.forEach(visitChild);
+        else
+            visitChild(child);
+    }
+}
+/** Restrict string references to local fragments during traversal. Ajv checks malformed keyword values. */
+function assertLocalReference(reference) {
+    if (typeof reference === 'string' && !reference.startsWith('#'))
+        throw new Error('external reference');
+}