@anureo/sdk 0.0.0-stage → 0.3.0

package/src/client.d.ts

@@ -0,0 +1,106 @@
+import { type AhpRequestMap, type SessionBinding, type SessionOpenParams } from '@anureo/protocol';
+import type { RequestOptions } from "./types.js";
+import type { ClientOptions } from "./client-options.js";
+import { Session } from "./session.js";
+export { Session } from "./session.js";
+export type { ClientOptions, InteractionHandlers, SubmitOptions } from "./client-options.js";
+/**
+ * Open and manage sessions through one adapter. Use createClient for an initialized client, or
+ * construct and initialize it explicitly. Await dispose to release owned sessions and the adapter.
+ */
+export declare class Client {
+    private readonly options;
+    /**
+     * Take ownership of the adapter without starting native I/O. Invalid identity, interaction
+     * registrations or retention limits throw INVALID_PARAMS. Direct callers must await initialize
+     * before opening sessions and later await dispose, including after failed initialization.
+     */
+    constructor(options: ClientOptions);
+    /** Read a fresh copy of the adapter and runtime configuration IDs used to check session bindings. */
+    get identity(): ClientOptions['identity'];
+    /**
+     * Negotiate adapter capabilities before opening sessions. Each call invokes adapter negotiation
+     * once if admitted and stores the validated capability snapshot on success. The wait defaults to
+     * 30 seconds unless configured by runtime.requestTimeoutMs. Invalid waits, adapter or protocol
+     * failures, abort and timeout reject. A negotiation that finishes after a failed wait cannot update
+     * the client's capabilities. createClient awaits this method and handles cleanup on failure.
+     */
+    initialize(wait?: RequestOptions): Promise<void>;
+    /**
+     * Open with explicit request and binding IDs. Resolve with the client-owned Session after backend
+     * attachment and initial state publication. Invalid input, unsupported mode, setup or wait failure
+     * rejects. The attachment wait defaults to 120 seconds unless configured by runtime.openTimeoutMs.
+     * If the wait ends early, the SDK closes local observation and still releases a late backend.
+     */
+    openSession(params: SessionOpenParams, wait?: RequestOptions): Promise<Session>;
+    /**
+     * Release the client and its sessions. Stop admitting opens immediately and share the disposal
+     * promise across calls. Await all owned session disposal attempts before releasing the adapter.
+     * Reject with RESOURCE_RELEASE_FAILED if release fails. Disposal ends local observation and leaves
+     * native execution stop unconfirmed. An open that delivers a backend after teardown releases it
+     * on its own attachment path.
+     */
+    dispose(): Promise<void>;
+    private initialized?;
+    private closed;
+    private disposing?;
+    private readonly owned;
+    private readonly createId;
+    /** Open sessions using generated request IDs and the same attachment wait and ownership as openSession. */
+    readonly sessions: {
+        /** Open a new session with a fresh binding. A throwing ID generator fails the call synchronously. */
+        create: (options: Omit<SessionOpenParams, "requestId" | "binding" | "mode">, wait?: RequestOptions) => Promise<Session>;
+        /** Reopen a saved session reference when supported. Foreign bindings reject and ID-generator throws propagate synchronously. */
+        resume: (reference: {
+            binding: SessionBinding;
+            cwd: string;
+        }, wait?: RequestOptions) => Promise<Session>;
+        /** Open a fresh session at a supported boundary in the referenced session. Foreign bindings reject before ID generation, which can throw synchronously. */
+        fork: (reference: {
+            binding: SessionBinding;
+            cwd: string;
+        }, options: {
+            boundary: AhpRequestMap["session/revert"]["boundary"];
+        }, wait?: RequestOptions) => Promise<Session>;
+    };
+    /**
+     * sessions.create and sessions.fork use this for a fresh destination after generating the request
+     * ID. Snapshot the configured identity before invoking the host's session ID generator.
+     */
+    private newBinding;
+    /**
+     * dispose caches this release attempt. Close admission before taking the session snapshot and
+     * keep the adapter alive until all session disposals settle. Report failures in session order,
+     * followed by the adapter failure, through the shared disposal promise.
+     */
+    private disposeOwnedResources;
+    /**
+     * openSession and sessions.create/resume/fork return this promise to hosts. Validate before
+     * allocating a Session, then own it before native callbacks or disposal can race attachment.
+     * Resolve the attached session, or remove it and await disposal before rejecting setup/wait failure
+     * (aggregated if cleanup fails). attachSession continues to release late backends after wait failure.
+     */
+    private open;
+    /**
+     * Client.open uses the returned negotiated capabilities to construct Session. Preserve admission
+     * precedence: wait validity, abort, client state, protocol shape, binding, then mode capability.
+     * Throws before session allocation/native dispatch; open exposes that failure as its rejection.
+     */
+    private validateOpen;
+    /**
+     * Client.open passes this operation to waitForRequest. Give the wrapped adapter a separate params
+     * clone and the Session sink, then await attachment/publication. This work outlives caller abort or
+     * timeout: OutputSession.open or Session.attach disposes a backend arriving after teardown.
+     * Native/attachment failures reject the operation and remain observed by waitForRequest.
+     */
+    private attachSession;
+}
+/**
+ * Create and initialize a client before opening sessions. A pre-aborted wait rejects before the
+ * client takes ownership of the adapter. Once construction succeeds, initialization failure triggers
+ * disposal before rejection. The original cause is preserved unless disposal also fails, in which
+ * case both failures are reported as RESOURCE_RELEASE_FAILED. Await dispose on the returned client.
+ * createRefactorClient and createReviewClient return this promise to their CLI commands, which
+ * await disposal after the run and report output.
+ */
+export declare function createClient(options: ClientOptions, wait?: RequestOptions): Promise<Client>;

package/src/client.js

@@ -0,0 +1,254 @@
+// Owns adapter negotiation, session open admission and client-wide resource release.
+import { randomUUID } from 'node:crypto';
+import { AHP_PROTOCOL_CONTRACT, assertRequest, assertResult, supportsCapability } from '@anureo/protocol';
+import { HarnessSdkError } from "./errors.js";
+import { invalidWait, waitForRequest } from "./request.js";
+import { Session } from "./session.js";
+import { immutable } from "./lifecycle/immutable.js";
+import { positive } from "./lifecycle/limits.js";
+import { combined } from "./lifecycle/errors.js";
+import { withStructuredOutput } from "./structured-output/adapter.js";
+export { Session } from "./session.js";
+/**
+ * Open and manage sessions through one adapter. Use createClient for an initialized client, or
+ * construct and initialize it explicitly. Await dispose to release owned sessions and the adapter.
+ */
+export class Client {
+    options;
+    /**
+     * Take ownership of the adapter without starting native I/O. Invalid identity, interaction
+     * registrations or retention limits throw INVALID_PARAMS. Direct callers must await initialize
+     * before opening sessions and later await dispose, including after failed initialization.
+     */
+    constructor(options) {
+        this.options = options;
+        this.options = {
+            ...options,
+            adapter: withStructuredOutput(options.adapter, {
+                queue: options.runtime?.queue,
+                maxSubmissions: options.limits?.maxSubmissions,
+                maxResultBytes: options.limits?.maxResultBytes,
+                maxItems: options.limits?.maxItems,
+            }),
+        };
+        this.createId = options.runtime?.createId ?? randomUUID;
+        assertClientOptions(options);
+    }
+    /** Read a fresh copy of the adapter and runtime configuration IDs used to check session bindings. */
+    get identity() {
+        return { adapterId: this.options.identity.adapterId, runtimeConfigId: this.options.identity.runtimeConfigId };
+    }
+    /**
+     * Negotiate adapter capabilities before opening sessions. Each call invokes adapter negotiation
+     * once if admitted and stores the validated capability snapshot on success. The wait defaults to
+     * 30 seconds unless configured by runtime.requestTimeoutMs. Invalid waits, adapter or protocol
+     * failures, abort and timeout reject. A negotiation that finishes after a failed wait cannot update
+     * the client's capabilities. createClient awaits this method and handles cleanup on failure.
+     */
+    async initialize(wait) {
+        if (invalidWait(wait))
+            throw new HarnessSdkError('INVALID_PARAMS');
+        const result = await waitForRequest(() => this.options.adapter.initialize({
+            protocolVersions: [1],
+            protocolContract: AHP_PROTOCOL_CONTRACT,
+            clientInfo: { name: 'anureo-native-lifecycle', version: '0.2.0' },
+            // Own keys advertise support even when the host will respond manually.
+            clientCapabilities: { interactions: Object.keys(this.options.interactions ?? {}) },
+        }), wait, this.options.runtime?.requestTimeoutMs);
+        assertResult('initialize', result);
+        this.initialized = immutable(result.capabilities);
+    }
+    /**
+     * Open with explicit request and binding IDs. Resolve with the client-owned Session after backend
+     * attachment and initial state publication. Invalid input, unsupported mode, setup or wait failure
+     * rejects. The attachment wait defaults to 120 seconds unless configured by runtime.openTimeoutMs.
+     * If the wait ends early, the SDK closes local observation and still releases a late backend.
+     */
+    openSession(params, wait) { return this.open(params, wait); }
+    /**
+     * Release the client and its sessions. Stop admitting opens immediately and share the disposal
+     * promise across calls. Await all owned session disposal attempts before releasing the adapter.
+     * Reject with RESOURCE_RELEASE_FAILED if release fails. Disposal ends local observation and leaves
+     * native execution stop unconfirmed. An open that delivers a backend after teardown releases it
+     * on its own attachment path.
+     */
+    dispose() {
+        return this.disposing ??= this.disposeOwnedResources();
+    }
+    // TypeScript emits these as own fields. Keep their initialization order relative to sessions.
+    initialized;
+    closed = false;
+    disposing;
+    owned = new Set();
+    createId;
+    /** Open sessions using generated request IDs and the same attachment wait and ownership as openSession. */
+    sessions = {
+        /** Open a new session with a fresh binding. A throwing ID generator fails the call synchronously. */
+        create: (options, wait) => this.open({
+            ...options, mode: 'new', requestId: this.createId(),
+            binding: this.newBinding(),
+        }, wait),
+        /** Reopen a saved session reference when supported. Foreign bindings reject and ID-generator throws propagate synchronously. */
+        resume: (reference, wait) => this.open({ ...reference, mode: 'resume', requestId: this.createId() }, wait),
+        /** Open a fresh session at a supported boundary in the referenced session. Foreign bindings reject before ID generation, which can throw synchronously. */
+        fork: (reference, options, wait) => {
+            if (!matchesIdentity(reference.binding, this.options.identity))
+                return Promise.reject(new HarnessSdkError('SESSION_BINDING_MISMATCH'));
+            return this.open({
+                cwd: reference.cwd, mode: 'fork', requestId: this.createId(),
+                binding: this.newBinding(),
+                fork: { sourceSessionId: reference.binding.sessionId, nativeRef: reference.binding.nativeRef, boundary: options.boundary },
+            }, wait);
+        },
+    };
+    /**
+     * sessions.create and sessions.fork use this for a fresh destination after generating the request
+     * ID. Snapshot the configured identity before invoking the host's session ID generator.
+     */
+    newBinding() {
+        return { ...this.options.identity, sessionId: this.createId() };
+    }
+    /**
+     * dispose caches this release attempt. Close admission before taking the session snapshot and
+     * keep the adapter alive until all session disposals settle. Report failures in session order,
+     * followed by the adapter failure, through the shared disposal promise.
+     */
+    async disposeOwnedResources() {
+        this.closed = true;
+        const sessions = await Promise.allSettled([...this.owned].map(session => session.dispose()));
+        const [adapter] = await Promise.allSettled([this.options.adapter.dispose()]);
+        this.owned.clear();
+        const failures = [...sessions, adapter].filter((result) => result.status === 'rejected');
+        if (failures.length)
+            throw combined(failures.map(failure => failure.reason));
+    }
+    /**
+     * openSession and sessions.create/resume/fork return this promise to hosts. Validate before
+     * allocating a Session, then own it before native callbacks or disposal can race attachment.
+     * Resolve the attached session, or remove it and await disposal before rejecting setup/wait failure
+     * (aggregated if cleanup fails). attachSession continues to release late backends after wait failure.
+     */
+    async open(params, wait) {
+        const capabilities = this.validateOpen(params, wait);
+        const session = new Session(structuredClone(params), this.options, capabilities, this.createId);
+        // Own the sink before dispatch: native events and client disposal can race attachment.
+        this.owned.add(session);
+        try {
+            await waitForRequest(() => this.attachSession(params, session), wait, this.options.runtime?.openTimeoutMs ?? 120_000);
+            if (this.closed)
+                throw new HarnessSdkError('CLIENT_DISPOSED');
+            return session;
+        }
+        catch (cause) {
+            this.owned.delete(session);
+            return rethrowAfterCleanup(cause, () => session.dispose());
+        }
+    }
+    /**
+     * Client.open uses the returned negotiated capabilities to construct Session. Preserve admission
+     * precedence: wait validity, abort, client state, protocol shape, binding, then mode capability.
+     * Throws before session allocation/native dispatch; open exposes that failure as its rejection.
+     */
+    validateOpen(params, wait) {
+        if (invalidWait(wait))
+            throw new HarnessSdkError('INVALID_PARAMS');
+        if (wait?.signal?.aborted)
+            throw new HarnessSdkError('REQUEST_ABORTED');
+        if (this.closed)
+            throw new HarnessSdkError('CLIENT_DISPOSED');
+        if (!this.initialized)
+            throw new HarnessSdkError('NOT_INITIALIZED');
+        assertRequest('session/open', params);
+        if (!matchesIdentity(params.binding, this.options.identity))
+            throw new HarnessSdkError('SESSION_BINDING_MISMATCH');
+        assertOpenCapability(params, this.initialized);
+        return this.initialized;
+    }
+    /**
+     * Client.open passes this operation to waitForRequest. Give the wrapped adapter a separate params
+     * clone and the Session sink, then await attachment/publication. This work outlives caller abort or
+     * timeout: OutputSession.open or Session.attach disposes a backend arriving after teardown.
+     * Native/attachment failures reject the operation and remain observed by waitForRequest.
+     */
+    async attachSession(params, session) {
+        const backend = await this.options.adapter.openSession(structuredClone(params), session);
+        await session.attach(backend);
+    }
+}
+/**
+ * Create and initialize a client before opening sessions. A pre-aborted wait rejects before the
+ * client takes ownership of the adapter. Once construction succeeds, initialization failure triggers
+ * disposal before rejection. The original cause is preserved unless disposal also fails, in which
+ * case both failures are reported as RESOURCE_RELEASE_FAILED. Await dispose on the returned client.
+ * createRefactorClient and createReviewClient return this promise to their CLI commands, which
+ * await disposal after the run and report output.
+ */
+export async function createClient(options, wait) {
+    if (wait?.signal?.aborted)
+        throw new HarnessSdkError('REQUEST_ABORTED');
+    const client = new Client({
+        ...options, identity: { ...options.identity }, runtime: { ...options.runtime },
+        interactions: { ...options.interactions }, limits: { ...options.limits },
+    });
+    try {
+        await client.initialize(wait);
+        return client;
+    }
+    catch (cause) {
+        return rethrowAfterCleanup(cause, () => client.dispose());
+    }
+}
+/**
+ * Client's constructor checks host identity, retention limits and interaction registrations here
+ * after installing the output wrapper. Throw INVALID_PARAMS before native initialization; no host
+ * callback is invoked and no native resource is acquired by these checks.
+ */
+function assertClientOptions(options) {
+    for (const value of [options.identity.adapterId, options.identity.runtimeConfigId]) {
+        if (typeof value !== 'string' || !value.trim())
+            throw new HarnessSdkError('INVALID_PARAMS');
+    }
+    for (const value of Object.values(options.limits ?? {}))
+        positive(value, 1);
+    for (const [kind, handler] of Object.entries(options.interactions ?? {})) {
+        if (!['approval', 'userInput', 'elicitation', 'dynamicTool'].includes(kind)
+            || handler !== undefined && typeof handler !== 'function')
+            throw new HarnessSdkError('INVALID_PARAMS');
+    }
+}
+/**
+ * Return whether a binding belongs to this adapter/configuration, without comparing session IDs.
+ * Client.sessions.fork rejects foreign sources with this result before generating IDs;
+ * Client.validateOpen rejects foreign destination bindings before allocating Session state.
+ */
+function matchesIdentity(binding, identity) {
+    return binding.adapterId === identity.adapterId && binding.runtimeConfigId === identity.runtimeConfigId;
+}
+/**
+ * Client.validateOpen calls this only after protocol shape and binding validation. Reject unsupported
+ * resume/fork modes with CAPABILITY_UNSUPPORTED before native work; new sessions need no mode
+ * capability. Keep shape checks with the caller so malformed fork details fail before capability checks.
+ */
+function assertOpenCapability(params, capabilities) {
+    if (params.mode === 'resume' && !supportsCapability(capabilities, 'session.resume')) {
+        throw new HarnessSdkError('CAPABILITY_UNSUPPORTED');
+    }
+    // assertRequest requires fork details in fork mode, although the public type leaves them optional.
+    if (params.mode === 'fork' && params.fork && !supportsCapability(capabilities, 'session.fork', params.fork.boundary.relation)) {
+        throw new HarnessSdkError('CAPABILITY_UNSUPPORTED');
+    }
+}
+/**
+ * Client.open supplies Session.dispose after failed attachment/wait; createClient supplies
+ * Client.dispose after failed initialization. Await that cleanup before rejecting with the original
+ * cause, or a privacy-safe aggregate if cleanup also fails. Callers return this rejection to hosts.
+ */
+async function rethrowAfterCleanup(cause, cleanup) {
+    try {
+        await cleanup();
+    }
+    catch (cleanupFailure) {
+        throw combined([cause, cleanupFailure]);
+    }
+    throw cause;
+}

package/src/diagnostics/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Classify a catalog failure for reporting without disclosing raw text. Return the allowlisted
+ * string or CATALOG_QUERY_FAILED. An object's own or inherited code property takes precedence,
+ * even when invalid. An Error without that property uses its message as the candidate.
+ * Property getters and proxy traps may throw synchronously. catalogPhase's failure report uses
+ * the returned value as errorCode.
+ */
+export declare function safeCatalogErrorCode(cause: unknown): string;
+/**
+ * Internal to diagnostics. reportCatalogFailure reads this value for the event's nativeRpcCode.
+ * Return undefined for a missing or nonnumeric rpcCode. Preserve separate reads for the type
+ * check and the returned value, which an accessor can observe. Property getters and proxy traps
+ * can throw synchronously, preventing the report and replacing the phase rejection.
+ */
+export declare function readNativeRpcCode(cause: unknown): number | undefined;

package/src/diagnostics/errors.js

@@ -0,0 +1,59 @@
+// Projects failure classifications without retaining native error text.
+/**
+ * Classify a catalog failure for reporting without disclosing raw text. Return the allowlisted
+ * string or CATALOG_QUERY_FAILED. An object's own or inherited code property takes precedence,
+ * even when invalid. An Error without that property uses its message as the candidate.
+ * Property getters and proxy traps may throw synchronously. catalogPhase's failure report uses
+ * the returned value as errorCode.
+ */
+export function safeCatalogErrorCode(cause) {
+    let code;
+    if (cause && typeof cause === 'object' && 'code' in cause) {
+        code = cause.code;
+    }
+    else if (cause instanceof Error) {
+        code = cause.message;
+    }
+    return typeof code === 'string' && safeCatalogCodes.has(code) ? code : 'CATALOG_QUERY_FAILED';
+}
+/**
+ * Internal to diagnostics. reportCatalogFailure reads this value for the event's nativeRpcCode.
+ * Return undefined for a missing or nonnumeric rpcCode. Preserve separate reads for the type
+ * check and the returned value, which an accessor can observe. Property getters and proxy traps
+ * can throw synchronously, preventing the report and replacing the phase rejection.
+ */
+export function readNativeRpcCode(cause) {
+    if (!cause || typeof cause !== 'object' || !('rpcCode' in cause))
+        return undefined;
+    if (typeof cause.rpcCode !== 'number')
+        return undefined;
+    return cause.rpcCode;
+}
+const safeCatalogCodes = new Set([
+    'AUTH_REQUIRED',
+    'AUTH_FORBIDDEN',
+    'HARNESS_UNAVAILABLE',
+    'HARNESS_CONFIG_INVALID',
+    'REQUEST_TIMEOUT',
+    'RPC_ABORTED',
+    'CATALOG_REFRESH_TIMEOUT',
+    'CATALOG_CANCELLED',
+    'CATALOG_LIMIT_EXCEEDED',
+    'CATALOG_SNAPSHOT_INVALID',
+    'CATALOG_MODELS_INVALID',
+    'MODELS_UNAVAILABLE',
+    'NATIVE_RPC_ERROR',
+    'PROTOCOL_ERROR',
+    'CONNECTION_CLOSED',
+    'RUNTIME_DISPOSED',
+    'PROCESS_DISPOSE_FAILED',
+    'PROCESS_WRITE_FAILED',
+    'FRAME_TOO_LARGE',
+    'MODEL_LIMIT_EXCEEDED',
+    'BACKPRESSURE_EXCEEDED',
+    'COMMAND_FORMAT_UNSUPPORTED',
+    'EXECUTABLE_NOT_FOUND',
+    'ENOENT',
+    'EACCES',
+    'EPERM',
+]);

package/src/diagnostics/events.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Observe a catalog operation's progress in LogTape or an onPhase callback. catalogPhase supplies
+ * error classifications. Hosts publishing their own events are responsible for safe field values.
+ */
+export interface CatalogProbeEvent {
+    /** Operation being observed; diagnostics do not enforce an order between phases. */
+    phase: 'spawn' | 'handshake' | 'models' | 'dispose';
+    /** catalogPhase reports cancelled when its signal is aborted at failure reporting, regardless of cause. */
+    outcome: 'started' | 'success' | 'error' | 'cancelled';
+    /**
+     * Elapsed milliseconds. catalogPhase includes synchronous started delivery and measures before
+     * delivering the terminal event. Started reports omit this field. LogTape receives rounded values.
+     */
+    durationMs?: number;
+    /** Safe allowlisted classification, never raw native error text. */
+    errorCode?: string;
+    /** Native RPC classification. catalogPhase includes this when the failure supplies a numeric rpcCode. */
+    nativeRpcCode?: number;
+}
+/**
+ * Configure observation and cancellation for a catalog probe. Codex and Claude catalog sessions
+ * accept these options on prepare and listModels and retain responsibility for native cleanup.
+ */
+export interface CatalogProbeOptions {
+    /** catalogPhase checks this before work, after fulfillment, and when choosing a failure outcome. */
+    signal?: AbortSignal;
+    /**
+     * Optional budget in milliseconds for the probe owner. In Codex, the options that start a
+     * connection set its per-RPC timeout, defaulting to 10,000 ms. Hosts set their own deadlines
+     * for Claude probes. The diagnostics helpers leave timeout enforcement to the probe owner.
+     */
+    timeoutMs?: number;
+    /**
+     * Register an observer for this probe. emitCatalogPhase invokes it synchronously with the original
+     * event after attempting to log. Synchronous throws are ignored and the host handles any
+     * rejections from asynchronous callbacks.
+     */
+    onPhase?: (event: CatalogProbeEvent) => void;
+}
+/**
+ * Publish a catalog report whose fields are safe to disclose. Attempt to log the known fields, then
+ * pass the original event to onPhase even if logging throws. Suppress synchronous observer throws.
+ * Return after the synchronous calls, leaving any asynchronous work to sinks and observers.
+ * catalogPhase calls this for its start and outcome reports. Hosts configure and dispose LogTape sinks.
+ */
+export declare function emitCatalogPhase(options: CatalogProbeOptions, event: CatalogProbeEvent): void;

package/src/diagnostics/events.js

@@ -0,0 +1,47 @@
+// Publishes catalog observations through host-configured logging and synchronous callbacks.
+import { getLogger } from '@logtape/logtape';
+/**
+ * Publish a catalog report whose fields are safe to disclose. Attempt to log the known fields, then
+ * pass the original event to onPhase even if logging throws. Suppress synchronous observer throws.
+ * Return after the synchronous calls, leaving any asynchronous work to sinks and observers.
+ * catalogPhase calls this for its start and outcome reports. Hosts configure and dispose LogTape sinks.
+ */
+export function emitCatalogPhase(options, event) {
+    logCatalogPhase(event);
+    try {
+        options.onPhase?.(event);
+    }
+    catch { /* An observer failure must leave the probe outcome intact. */ }
+}
+const catalogLogger = getLogger(['anureo', 'catalog']);
+/**
+ * emitCatalogPhase calls this before its observer so callback mutation cannot change logged fields.
+ * Route errors to error, cancellations to warning, and other outcomes to debug. Suppress projection
+ * and logging failures so emitCatalogPhase can still invoke the observer.
+ */
+function logCatalogPhase(event) {
+    try {
+        const properties = catalogLogProperties(event);
+        const message = 'catalog {phase} {outcome}';
+        if (event.outcome === 'error')
+            catalogLogger.error(message, properties);
+        else if (event.outcome === 'cancelled')
+            catalogLogger.warn(message, properties);
+        else
+            catalogLogger.debug(message, properties);
+    }
+    catch { /* Deliver the event to the observer even when logging fails. */ }
+}
+/**
+ * Give logCatalogPhase only the fields intended for logging. Round duration on the copy so
+ * observers still receive the original value. Reading the event can throw before logging.
+ */
+function catalogLogProperties(event) {
+    return {
+        phase: event.phase,
+        outcome: event.outcome,
+        ...(event.durationMs === undefined ? {} : { durationMs: Math.round(event.durationMs) }),
+        ...(event.errorCode === undefined ? {} : { errorCode: event.errorCode }),
+        ...(event.nativeRpcCode === undefined ? {} : { nativeRpcCode: event.nativeRpcCode }),
+    };
+}

package/src/diagnostics.d.ts

@@ -0,0 +1,20 @@
+import { type CatalogProbeEvent, type CatalogProbeOptions } from "./diagnostics/events.js";
+export { emitCatalogPhase } from "./diagnostics/events.js";
+export type { CatalogProbeEvent, CatalogProbeOptions } from "./diagnostics/events.js";
+export { safeCatalogErrorCode } from "./diagnostics/errors.js";
+/**
+ * Run one catalog phase and report its start and outcome. Deliver started before checking the
+ * signal, then invoke work at most once. Check cancellation again after work fulfills. Cancellation
+ * at either check rejects with RPC_ABORTED. While work is pending, the phase waits for it to settle.
+ * Resolve with the work value after success delivery, or reject with the original synchronous throw
+ * or promise rejection after failure delivery, including when that outcome is cancelled.
+ *
+ * The probe owner enforces deadlines, interrupts native work if needed, and releases resources
+ * even when the phase discards a successful result. Logger and synchronous observer failures are
+ * isolated. A cause or signal property that throws during failure reporting prevents terminal
+ * delivery and becomes the rejection.
+ *
+ * The Codex and Claude catalog sessions await the spawn and handshake phases during preparation and
+ * return the models phase value from listModels. Session users must await dispose after use.
+ */
+export declare function catalogPhase<T>(options: CatalogProbeOptions, phase: CatalogProbeEvent['phase'], work: () => Promise<T>): Promise<T>;

package/src/diagnostics.js

@@ -0,0 +1,56 @@
+// Observes catalog work while probe owners retain native resources and cleanup.
+import { emitCatalogPhase } from "./diagnostics/events.js";
+import { readNativeRpcCode, safeCatalogErrorCode } from "./diagnostics/errors.js";
+export { emitCatalogPhase } from "./diagnostics/events.js";
+export { safeCatalogErrorCode } from "./diagnostics/errors.js";
+/**
+ * Run one catalog phase and report its start and outcome. Deliver started before checking the
+ * signal, then invoke work at most once. Check cancellation again after work fulfills. Cancellation
+ * at either check rejects with RPC_ABORTED. While work is pending, the phase waits for it to settle.
+ * Resolve with the work value after success delivery, or reject with the original synchronous throw
+ * or promise rejection after failure delivery, including when that outcome is cancelled.
+ *
+ * The probe owner enforces deadlines, interrupts native work if needed, and releases resources
+ * even when the phase discards a successful result. Logger and synchronous observer failures are
+ * isolated. A cause or signal property that throws during failure reporting prevents terminal
+ * delivery and becomes the rejection.
+ *
+ * The Codex and Claude catalog sessions await the spawn and handshake phases during preparation and
+ * return the models phase value from listModels. Session users must await dispose after use.
+ */
+export async function catalogPhase(options, phase, work) {
+    const started = performance.now();
+    emitCatalogPhase(options, { phase, outcome: 'started' });
+    try {
+        throwIfCatalogAborted(options.signal);
+        const result = await work();
+        throwIfCatalogAborted(options.signal);
+        emitCatalogPhase(options, { phase, outcome: 'success', durationMs: performance.now() - started });
+        return result;
+    }
+    catch (cause) {
+        reportCatalogFailure(options, phase, started, cause);
+        throw cause;
+    }
+}
+/** Throw RPC_ABORTED at catalogPhase's pre/post-work checks so an aborted probe cannot publish success. */
+function throwIfCatalogAborted(signal) {
+    if (signal?.aborted)
+        throw Object.assign(new Error('RPC_ABORTED'), { code: 'RPC_ABORTED' });
+}
+/**
+ * Publish catalogPhase's failure report after classifying the cause, then let catalogPhase rethrow
+ * that cause. Classify before sampling cancellation so the outcome reflects the signal at reporting
+ * time. If classification or sampling throws, that failure escapes before a report is delivered.
+ */
+function reportCatalogFailure(options, phase, startedAt, cause) {
+    const errorCode = safeCatalogErrorCode(cause);
+    const nativeRpcCode = readNativeRpcCode(cause);
+    emitCatalogPhase(options, {
+        phase,
+        outcome: options.signal?.aborted ? 'cancelled' : 'error',
+        durationMs: performance.now() - startedAt,
+        errorCode,
+        ...(nativeRpcCode === undefined ? {} : { nativeRpcCode }),
+    });
+}

package/src/errors.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Inspect SDK or adapter failures by code and outcome. Producers must supply safe messages and
+ * details. Check outcomeUnknown before retrying an operation that may already have taken effect.
+ */
+export declare class HarnessSdkError extends Error {
+    /** Safe machine-readable failure code selected by the owning subsystem. */
+    readonly code: string;
+    /** Whether the operation’s safe failure policy permits a caller retry. */
+    readonly retryable: boolean;
+    /** Native acceptance/completion could not be established; retry may duplicate work. */
+    readonly outcomeUnknown: boolean;
+    /** Already-sanitized structured diagnostics supplied by the owning subsystem. */
+    readonly details?: Record<string, unknown> | undefined;
+    /**
+     * Create a failure with an already-sanitized code, message and diagnostics. The message defaults
+     * to the code, both flags default to false, and details are retained by reference.
+     */
+    constructor(
+    /** Safe machine-readable failure code selected by the owning subsystem. */
+    code: string, 
+    /** Caller-safe message; never populate this with an unfiltered native cause. */
+    message?: string, 
+    /** Whether the operation’s safe failure policy permits a caller retry. */
+    retryable?: boolean, 
+    /** Native acceptance/completion could not be established; retry may duplicate work. */
+    outcomeUnknown?: boolean, 
+    /** Already-sanitized structured diagnostics supplied by the owning subsystem. */
+    details?: Record<string, unknown> | undefined);
+    /** Error name used in diagnostics. */
+    readonly name = "HarnessSdkError";
+}
+/**
+ * Normalize a failure for SDK or adapter callers. Return existing HarnessSdkError instances by
+ * identity. For other objects with a code matching A-Z followed by up to 80 uppercase letters,
+ * digits or underscores, use the code as the message and copy only literal-true flags. A present
+ * outcomeUnknown property on such an object overrides the supplied default. Other causes use
+ * fallback (HARNESS_ERROR by default) as both code and message, with retryable false and the
+ * supplied outcomeUnknown default. Supply a safe fallback. Property access can throw if the
+ * cause has throwing getters or proxy traps.
+ *
+ * Called by:
+ * - Session.onRequestFailed to choose recovery state and publish safe submission failure status.
+ * - InteractionRegistry.deliverResponse to classify responder or publication failures for the
+ *   interaction waiter and, during delivery, for publication of an unknown outcome.
+ * - checkRelease in structured-output/errors to throw safe failures after cleanup attempts settle.
+ * Public consumers can apply the same normalization; callers own propagation, retries and cleanup.
+ */
+export declare function sdkError(cause: unknown, fallback?: string, outcomeUnknown?: boolean): HarnessSdkError;