@anureo/sdk 0.2.0 → 0.3.0

package/src/queue.js

@@ -0,0 +1,266 @@
+// Owns bounded admission, buffered drain and exclusive iterator ownership for one producer stream.
+import { HarnessSdkError } from "./errors.js";
+/**
+ * Buffer a producer stream within event and byte budgets, or await capacity with write.
+ * One iterator owns reads at a time. Returning it releases ownership while the producer stays open.
+ * Producers own closure and consumers own iterator release. Buffered regular events drain before
+ * buffered controls, then readers observe completion or failure. Values are retained by reference;
+ * keep their measured size stable while queued. EventHub uses a private queue per observer to
+ * isolate overflow, while adapter transports use queues for incoming frames or native input.
+ */
+export class BoundedEventQueue {
+    sizeOf;
+    /**
+     * Configure storage without claiming a reader. Invalid resolved budgets throw INVALID_PARAMS.
+     * Omitted or nullish budget fields select the QueueLimits defaults. The queue calls sizeOf during
+     * admission and propagates measurement failures. It defaults to measuring the UTF-8 byte length
+     * of the JSON serialization. A custom measurement must return a consistent, nonnegative byte
+     * count because a value can be measured more than once.
+     */
+    constructor(limits = {}, sizeOf = (value) => new TextEncoder().encode(JSON.stringify(value)).byteLength) {
+        this.sizeOf = sizeOf;
+        this.limits = {
+            maxEvents: limits.maxEvents ?? 2048,
+            maxBytes: limits.maxBytes ?? 16 * 1024 * 1024,
+            maxFrameBytes: limits.maxFrameBytes ?? 8 * 1024 * 1024,
+            maxWaitingWriters: limits.maxWaitingWriters ?? 32,
+            maxControlEvents: limits.maxControlEvents ?? 33,
+        };
+        if (Object.values(this.limits).some((n) => !Number.isSafeInteger(n) || n <= 0))
+            throw new HarnessSdkError("INVALID_PARAMS", "Queue limits must be positive integers");
+    }
+    /** Resolved construction-time budgets exposed for producers; callers must treat this object as read-only. */
+    limits;
+    /** Count regular events and controls currently in the buffer. */
+    get bufferedEvents() { return this.entries.length + this.controls.length; }
+    /** Count bytes reserved by buffered regular events. Controls consume their own event budget. */
+    get bufferedBytes() { return this.bytes; }
+    /**
+     * Check regular-event admission without reserving capacity. A later push can still fail.
+     * Throw the stored non-nullish closure cause (or STREAM_CLOSED), FRAME_TOO_LARGE, a measurement
+     * failure, or BACKPRESSURE_EXCEEDED for a full regular buffer.
+     */
+    assertWritable(value) {
+        this.assertOpen();
+        const bytes = this.checkedSize(value);
+        if (this.isRegularBufferFull(bytes))
+            throw new HarnessSdkError("BACKPRESSURE_EXCEEDED");
+    }
+    /**
+     * Deliver to a waiting read or buffer synchronously, throwing on closure, capacity or
+     * size/measurement failure without evicting data. Producers handle failures and own closure.
+     * EventHub.publish ends only the affected observer on failure. The message listener in
+     * createSocketTransport also closes the native socket.
+     */
+    push(value) {
+        // Run the overridable admission probe before measuring the value for storage.
+        this.assertWritable(value);
+        const bytes = this.checkedSize(value);
+        if (this.deliverToWaitingReader(value))
+            return;
+        this.entries.push({ value, bytes });
+        this.bytes += bytes;
+    }
+    /**
+     * Await capacity and resolve once delivered or buffered, without waiting for consumption.
+     * Reject on closure, size/measurement failure or exhausted writer capacity.
+     * Waking writers compete for capacity and recheck it before admitting a value. Pass accepted
+     * to run a synchronous callback after admission. If it throws, the promise rejects and the value
+     * remains admitted. Producers can end the queue to wake all blocked writers and reject admission.
+     */
+    async write(value, accepted) {
+        const bytes = this.checkedSize(value);
+        // Resuming notifies all waiting writers to recheck capacity; it reserves no slot.
+        while (this.isRegularBufferFull(bytes)) {
+            this.assertOpen();
+            if (this.waitingWriterResumes.size >= this.limits.maxWaitingWriters)
+                throw new HarnessSdkError("BACKPRESSURE_EXCEEDED");
+            await new Promise((resolve) => this.waitingWriterResumes.add(resolve));
+        }
+        this.push(value);
+        accepted?.();
+    }
+    /**
+     * Admit a control event even when the regular buffer is full. Each event still obeys
+     * maxFrameBytes and maxBytes; buffered controls have a separate maxControlEvents limit
+     * and do not contribute to bufferedBytes.
+     * Buffered regular events are delivered before buffered control events. Throws on closure,
+     * measurement/size failure or exhausted control capacity; callers still own producer closure.
+     */
+    pushControl(value) {
+        this.assertOpen();
+        this.checkedSize(value);
+        if (this.deliverToWaitingReader(value))
+            return;
+        if (this.controls.length >= this.limits.maxControlEvents)
+            throw new HarnessSdkError("BACKPRESSURE_EXCEEDED", "Control event limit exceeded");
+        this.controls.push(value);
+    }
+    /**
+     * Admit a final control under the usual control budget, then close admission. Readers can
+     * receive the control before completion. Already-ended queues ignore the value. If admission
+     * throws, the producer still owns recovery or closure.
+     */
+    endWithControl(value) {
+        if (this.ended)
+            return;
+        this.pushControl(value);
+        this.end();
+    }
+    /**
+     * Idempotently close admission, wake blocked writers so they can reject, and settle any pending read.
+     * Buffered values drain before a truthy cause rejects reads; falsy causes complete reads normally.
+     * Closure checks throw a non-nullish stored cause, otherwise STREAM_CLOSED.
+     * Reader ownership remains until next observes drained closure or the consumer calls return or
+     * throw on the iterator. The caller still owns stopping any native producer.
+     */
+    end(cause) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.failure = cause;
+        this.resumeWaitingWriters();
+        const waiter = this.takePendingRead();
+        if (!waiter)
+            return;
+        if (cause)
+            waiter.reject(cause);
+        else
+            waiter.resolve(completedRead());
+    }
+    /**
+     * Claim exclusive reader ownership, throwing EVENT_STREAM_ALREADY_OWNED until the prior reader
+     * releases it. next drains regular values then controls before terminal completion or rejection.
+     * A second next while a read is blocked rejects with CONCURRENT_EVENT_READ. return and throw
+     * release ownership and complete a blocked read while leaving the producer open. throw also
+     * rejects its own promise with the supplied cause. A pending read settled by end still needs
+     * a subsequent next, return or throw to release ownership.
+     */
+    [Symbol.asyncIterator]() {
+        if (this.activeReaderToken)
+            throw new HarnessSdkError("EVENT_STREAM_ALREADY_OWNED");
+        const readerToken = Symbol("reader");
+        this.activeReaderToken = readerToken;
+        return {
+            next: () => this.readNext(readerToken),
+            return: async () => {
+                this.detachReader(readerToken);
+                return completedRead();
+            },
+            throw: async (cause) => {
+                this.detachReader(readerToken);
+                throw cause;
+            },
+        };
+    }
+    entries = [];
+    bytes = 0;
+    activeReaderToken;
+    pendingRead;
+    controls = [];
+    ended = false;
+    failure;
+    waitingWriterResumes = new Set();
+    /**
+     * end, readBuffered and readNext wake blocked writers when they close the queue, free capacity
+     * or register a reader for direct delivery. Writers recheck admission on resumption.
+     */
+    resumeWaitingWriters() {
+        for (const resume of this.waitingWriterResumes)
+            resume();
+        this.waitingWriterResumes.clear();
+    }
+    /**
+     * assertWritable and write share this admission rule. A pending read permits direct delivery even
+     * at the buffer budget; checking capacity neither reserves a slot nor wakes a producer.
+     */
+    isRegularBufferFull(bytes) {
+        return !this.pendingRead && (this.entries.length >= this.limits.maxEvents || this.bytes + bytes > this.limits.maxBytes);
+    }
+    /**
+     * push and pushControl try direct delivery after checking size. Report whether this settled
+     * a pending read so the caller can skip buffering.
+     */
+    deliverToWaitingReader(value) {
+        const waiter = this.takePendingRead();
+        if (!waiter)
+            return false;
+        waiter.resolve({ done: false, value });
+        return true;
+    }
+    /** Remove the pending read before its caller delivers a value, completes it or rejects it. */
+    takePendingRead() {
+        const read = this.pendingRead;
+        this.pendingRead = undefined;
+        return read;
+    }
+    /**
+     * Producer admission uses this to check for closure. A closed queue throws the stored
+     * non-nullish cause or STREAM_CLOSED and keeps the reader attached.
+     */
+    assertOpen() { if (this.ended)
+        throw this.failure ?? new HarnessSdkError("STREAM_CLOSED"); }
+    /**
+     * assertWritable, push, write and pushControl call before admission. Measure without reserving
+     * capacity; throw FRAME_TOO_LARGE above either single-frame or regular-byte limits, including for
+     * controls. Propagate sizeOf failures unchanged so the producer can handle admission failure.
+     */
+    checkedSize(value) {
+        const bytes = this.sizeOf(value);
+        if (bytes > this.limits.maxFrameBytes || bytes > this.limits.maxBytes)
+            throw new HarnessSdkError("FRAME_TOO_LARGE");
+        return bytes;
+    }
+    /**
+     * Settle the iterator's next call from buffered data or drained closure. Otherwise register a
+     * pending read and wake writers because they can now deliver directly. A detached reader
+     * completes immediately, and an overlapping blocked read rejects without replacing the first.
+     */
+    readNext(readerToken) {
+        if (this.activeReaderToken !== readerToken)
+            return Promise.resolve(completedRead());
+        const buffered = this.readBuffered();
+        if (buffered)
+            return Promise.resolve(buffered);
+        if (this.ended) {
+            this.detachReader(readerToken);
+            return this.failure ? Promise.reject(this.failure) : Promise.resolve(completedRead());
+        }
+        if (this.pendingRead)
+            return Promise.reject(new HarnessSdkError("CONCURRENT_EVENT_READ"));
+        return new Promise((resolve, reject) => {
+            this.pendingRead = { resolve, reject };
+            this.resumeWaitingWriters();
+        });
+    }
+    /**
+     * readNext on drained closure and the iterator's return and throw release ownership here.
+     * createSubscription also calls return when cancelled. Only the active reader can have a pending
+     * read, so checking its token protects a replacement reader from stale calls.
+     */
+    detachReader(readerToken) {
+        if (this.activeReaderToken !== readerToken)
+            return;
+        this.activeReaderToken = undefined;
+        this.takePendingRead()?.resolve(completedRead());
+    }
+    /**
+     * Give readNext regular values before controls and release regular bytes before waking writers.
+     * Return undefined only when neither buffer has data, leaving terminal settlement to readNext.
+     */
+    readBuffered() {
+        const entry = this.entries.shift();
+        if (entry) {
+            this.bytes -= entry.bytes;
+            this.resumeWaitingWriters();
+            return { done: false, value: entry.value };
+        }
+        if (this.controls.length)
+            return { done: false, value: this.controls.shift() };
+        return undefined;
+    }
+}
+/** Give each completed read its own result object. */
+function completedRead() {
+    return { done: true, value: undefined };
+}

package/src/request.d.ts

@@ -0,0 +1,28 @@
+import type { RequestOptions } from "./types.js";
+/**
+ * Package-internal validation of explicit Client and Session wait durations in milliseconds.
+ * Return true for non-finite, non-positive or above 2_147_483_647. Omission and positive fractions
+ * within the limit pass. Client.initialize and Client.validateOpen throw INVALID_PARAMS on
+ * failure. Session.request, Session.submitExecution and Session.closeRequest return a rejection.
+ */
+export declare function invalidWait(wait?: RequestOptions): boolean;
+/**
+ * Await one operation with a caller-scoped deadline and optional abort signal.
+ * A pre-aborted signal rejects with REQUEST_ABORTED before timeout validation or invocation.
+ * A nullish timeout uses defaultTimeoutMs, which defaults to 30,000 ms. A non-finite or non-positive
+ * effective timeout rejects with INVALID_PARAMS. Rounding and timer range follow the host timer.
+ * The operation is invoked synchronously once. Its value or original failure, including a
+ * synchronous throw, settles the wait if it wins the race. Abort or expiry after invocation
+ * rejects with REQUEST_ABORTED or REQUEST_TIMEOUT and outcomeUnknown=true. Keep options.signal
+ * stable until settlement so the wait can remove its listener. Settlement clears the timer and
+ * the operation's rejection remains observed. Callers own any native cancellation, resource
+ * release or decision to retry.
+ *
+ * Turn.result returns this wait for the shared terminal snapshot. Session.submitExecution
+ * returns it for execution binding after dispatch, and Session.closeRequest uses it to
+ * observe close and backend cleanup.
+ * InteractionRegistry.deliverResponse and cancelPending await the supplied native responder and
+ * translate failures into interaction outcomes. AcpAdapter.call returns the native result or
+ * normalizes the rejection while preserving SDK errors.
+ */
+export declare function waitForRequest<T>(operation: () => Promise<T>, options?: RequestOptions, defaultTimeoutMs?: number): Promise<T>;

package/src/request.js

@@ -0,0 +1,81 @@
+// Owns caller deadlines and cancellation for observing one operation.
+import { HarnessSdkError } from "./errors.js";
+/**
+ * Package-internal validation of explicit Client and Session wait durations in milliseconds.
+ * Return true for non-finite, non-positive or above 2_147_483_647. Omission and positive fractions
+ * within the limit pass. Client.initialize and Client.validateOpen throw INVALID_PARAMS on
+ * failure. Session.request, Session.submitExecution and Session.closeRequest return a rejection.
+ */
+export function invalidWait(wait) {
+    return wait?.timeoutMs !== undefined
+        && (!Number.isFinite(wait.timeoutMs) || wait.timeoutMs <= 0 || wait.timeoutMs > 0x7fffffff);
+}
+/**
+ * Await one operation with a caller-scoped deadline and optional abort signal.
+ * A pre-aborted signal rejects with REQUEST_ABORTED before timeout validation or invocation.
+ * A nullish timeout uses defaultTimeoutMs, which defaults to 30,000 ms. A non-finite or non-positive
+ * effective timeout rejects with INVALID_PARAMS. Rounding and timer range follow the host timer.
+ * The operation is invoked synchronously once. Its value or original failure, including a
+ * synchronous throw, settles the wait if it wins the race. Abort or expiry after invocation
+ * rejects with REQUEST_ABORTED or REQUEST_TIMEOUT and outcomeUnknown=true. Keep options.signal
+ * stable until settlement so the wait can remove its listener. Settlement clears the timer and
+ * the operation's rejection remains observed. Callers own any native cancellation, resource
+ * release or decision to retry.
+ *
+ * Turn.result returns this wait for the shared terminal snapshot. Session.submitExecution
+ * returns it for execution binding after dispatch, and Session.closeRequest uses it to
+ * observe close and backend cleanup.
+ * InteractionRegistry.deliverResponse and cancelPending await the supplied native responder and
+ * translate failures into interaction outcomes. AcpAdapter.call returns the native result or
+ * normalizes the rejection while preserving SDK errors.
+ */
+export function waitForRequest(operation, options = {}, defaultTimeoutMs = 30_000) {
+    if (options.signal?.aborted)
+        return Promise.reject(new HarnessSdkError("REQUEST_ABORTED", "Request aborted before dispatch"));
+    const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        return Promise.reject(new HarnessSdkError("INVALID_PARAMS", "timeoutMs must be positive"));
+    return observeRequest({ operation, options, timeoutMs });
+}
+/**
+ * Dispatch the operation after waitForRequest validates admission. Own the timer and listener
+ * for this promise and attach the operation's continuations even if invocation triggers abort.
+ */
+function observeRequest({ operation, options, timeoutMs }) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        /**
+         * The operation continuations and abandon release wait resources before delivering the first
+         * outcome. Later outcomes leave the original settlement intact.
+         */
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", abort);
+            callback();
+        };
+        /**
+         * The abort listener and deadline callback reject the same wait with an unknown outcome.
+         * Build the error only if this callback wins settlement.
+         */
+        const abandon = (code) => {
+            finish(() => reject(new HarnessSdkError(code, "Request outcome is unknown after dispatch", false, true)));
+        };
+        /** The caller signal invokes this listener; finish removes this same reference on any settlement. */
+        const abort = () => abandon("REQUEST_ABORTED");
+        /** Forward invocation failures and promise rejections through the same cleanup. */
+        const rejectOperation = (cause) => finish(() => reject(cause));
+        const timer = setTimeout(() => abandon("REQUEST_TIMEOUT"), timeoutMs);
+        // Install before invoking operation: it may synchronously trigger the caller's abort signal.
+        options.signal?.addEventListener("abort", abort, { once: true });
+        // Keep the rejection handler attached after abandonment so late failures stay observed.
+        try {
+            operation().then((value) => finish(() => resolve(value)), rejectOperation);
+        }
+        catch (cause) {
+            rejectOperation(cause);
+        }
+    });
+}

package/src/requests/guard.d.ts

@@ -0,0 +1,15 @@
+import { type AhpRequestMap, type Capabilities } from "@anureo/protocol";
+import type { SessionMethod } from "../ports.js";
+/**
+ * Synchronously admit a typed session request in precedence order: protocol shape, session binding,
+ * operation capability, submission policy, then config values. Return void on admission; propagate
+ * assertRequest failures, throw SESSION_BINDING_MISMATCH for a foreign session, or throw
+ * CAPABILITY_UNSUPPORTED/INVALID_PARAMS for capability/config violations. No dispatch or state change.
+ * Session.submitExecution checks before allocating submission records; Session.request checks close
+ * requests before shared teardown; dispatchOperation checks before replay/capacity bookkeeping. They
+ * expose failures as rejected caller promises. OutputSession.execute checks transformed fallback
+ * requests against native capabilities and cleans up definite submission failures before propagating
+ * them (adding safe diagnostics if that cleanup also fails).
+ * Callers still own lifecycle/wait admission, dispatch deduplication and resource cleanup.
+ */
+export declare function guardRequest<M extends SessionMethod>(method: M, params: AhpRequestMap[M], sessionId: string, capabilities: Capabilities): void;

package/src/requests/guard.js

@@ -0,0 +1,93 @@
+// Enforces request shape, binding and capability policy; must not dispatch native operations.
+import { assertRequest, supportsCapability, validateJsonSchema } from "@anureo/protocol";
+import { HarnessSdkError } from "../errors.js";
+/**
+ * Synchronously admit a typed session request in precedence order: protocol shape, session binding,
+ * operation capability, submission policy, then config values. Return void on admission; propagate
+ * assertRequest failures, throw SESSION_BINDING_MISMATCH for a foreign session, or throw
+ * CAPABILITY_UNSUPPORTED/INVALID_PARAMS for capability/config violations. No dispatch or state change.
+ * Session.submitExecution checks before allocating submission records; Session.request checks close
+ * requests before shared teardown; dispatchOperation checks before replay/capacity bookkeeping. They
+ * expose failures as rejected caller promises. OutputSession.execute checks transformed fallback
+ * requests against native capabilities and cleans up definite submission failures before propagating
+ * them (adding safe diagnostics if that cleanup also fails).
+ * Callers still own lifecycle/wait admission, dispatch deduplication and resource cleanup.
+ */
+export function guardRequest(method, params, sessionId, capabilities) {
+    assertRequest(method, params);
+    if (params.sessionId !== sessionId)
+        throw new HarnessSdkError("SESSION_BINDING_MISMATCH");
+    if (!supportsOperation(method, params, capabilities))
+        throwCapabilityUnsupported();
+    if (method === "input/submit")
+        guardSubmissionCapability(params, capabilities);
+    if (method === "session/config/set")
+        guardSessionConfigCapability(params.patch, capabilities);
+}
+/**
+ * guardRequest, guardSubmissionCapability and guardSessionConfigCapability throw through
+ * this shared policy to guardRequest. Always throw a code-only SDK failure without exposing rejected
+ * capability details; the calling admission path owns propagation and any prior resource cleanup.
+ */
+function throwCapabilityUnsupported() {
+    throw new HarnessSdkError("CAPABILITY_UNSUPPORTED");
+}
+/**
+ * guardRequest checks operation support after shape and binding, before submission or config policy.
+ * Unrestricted methods pass. Session interruption also requires opt-in support for cancelling queued
+ * inputs when the caller requests it. A false result becomes CAPABILITY_UNSUPPORTED in guardRequest.
+ */
+function supportsOperation(method, params, capabilities) {
+    switch (method) {
+        case "turn/steer":
+            return Boolean(capabilities.input?.steer?.atomicMatch);
+        case "turn/interrupt":
+            return capabilities.input?.interrupt?.targets.includes("turn") ?? false;
+        case "session/revert":
+            return supportsCapability(capabilities, "session.revert", params.scope);
+        case "history/read":
+            return supportsCapability(capabilities, "session.history");
+        case "goal/set":
+        case "goal/clear":
+            return supportsCapability(capabilities, "goal.actions", method.split("/")[1]);
+        case "compact/start":
+            return Boolean(capabilities.compact);
+        case "review/start":
+            return Boolean(capabilities.review);
+        case "session/interrupt":
+            return Boolean(capabilities.input?.interrupt?.targets.includes("session")
+                && (!params.cancelQueued || capabilities.input?.interrupt?.cancelQueued));
+        default:
+            return true;
+    }
+}
+/**
+ * guardRequest checks input/submit delivery, output schema, modalities and override names in that
+ * order. Omitted input modalities allow text only. An unsupported option throws CAPABILITY_UNSUPPORTED.
+ */
+function guardSubmissionCapability(submission, capabilities) {
+    if (!capabilities.input?.delivery.includes(submission.delivery))
+        throwCapabilityUnsupported();
+    if (submission.outputSchema !== undefined && !capabilities.turn?.outputSchema)
+        throwCapabilityUnsupported();
+    const modalities = capabilities.turn?.inputModalities ?? ["text"];
+    if (submission.input.some((block) => !modalities.includes(block.type)))
+        throwCapabilityUnsupported();
+    if (submission.overrides && Object.keys(submission.overrides).some((key) => !capabilities.turn?.overrides?.includes(key)))
+        throwCapabilityUnsupported();
+}
+/**
+ * guardRequest calls this last. For session/config/set, visit patch entries in property order and
+ * require a session-scoped advertised option before validating its value. Throw CAPABILITY_UNSUPPORTED
+ * for an unknown/non-session option or INVALID_PARAMS for a schema mismatch; the first failing entry
+ * wins. Applying the validated patch remains the responsibility of the request implementation.
+ */
+function guardSessionConfigCapability(patch, capabilities) {
+    for (const [key, value] of Object.entries(patch)) {
+        const option = capabilities.config?.options.find((entry) => entry.id === key && entry.scope === "session");
+        if (!option)
+            throwCapabilityUnsupported();
+        if (!validateJsonSchema(option.schema, value))
+            throw new HarnessSdkError("INVALID_PARAMS", "Config value does not match schema");
+    }
+}