@astrosheep/square 0.3.63 → 0.3.64

package/dist/opencode.js

@@ -1,49 +1,154 @@
-import { presentPendingAtBoundary } from './boundary-presentation.js';
-import { automaticSessionEnd, automaticSessionStart } from './automatic-session.js';
-/** OpenCode's server plugin entrypoint for the published Square package. */
-export default async function squareOpenCodePlugin() {
-    const joining = new Map();
-    return {
-        event: async ({ event }) => {
-            if (event.type === 'session.created' || event.type === 'session.updated') {
-                const sessionID = event.properties?.sessionID;
-                const cwd = event.properties?.info?.directory || process.cwd();
-                if (sessionID) {
+import { automaticSessionStart, operationEnv } from './automatic-session.js';
+import { hostLedgerForEnv } from './registry.js';
+import { canonicalPath } from './canonical-path.js';
+import { openSquare } from './square-file-adapter.js';
+import { closeOpenSquare } from './open-square.js';
+import { Square } from './square-wiring.js';
+import { connectNative } from './packages/agent-delivery/src/opencode-native.js';
+import { observeOpenCodeContext, publishOpenCodeRoutes, receiveOpenCodePending } from './opencode-delivery.js';
+/** Actual OpenCode 2.0.20 server plugin. Harness identity belongs to ctx, never process.env. */
+export default {
+    id: 'square',
+    async setup(ctx) {
+        if (ctx.app.version !== '2.0.20')
+            return async () => { };
+        const env = { ...process.env };
+        const ledger = hostLedgerForEnv(env);
+        const lifetime = new AbortController();
+        const receivers = new Map(); // Operational handles only; presence owns membership.
+        const directory = await canonicalPath(ctx.location.directory);
+        let coordinating = Promise.resolve();
+        const coordinate = (operation) => {
+            const task = coordinating.then(() => lifetime.signal.aborted ? undefined : operation());
+            coordinating = task.catch(() => { }); // Optional Square hooks must never fail primary request preparation.
+            return coordinating;
+        };
+        const stop = (sessionId) => {
+            const receiver = receivers.get(sessionId);
+            receiver?.abort.abort();
+            receivers.delete(sessionId);
+            return receiver?.running;
+        };
+        const validate = async (sessionId) => {
+            let info;
+            const target = await connectNative({ sessionId, timeoutMs: 3000, signal: lifetime.signal, session: {
+                    async get(input) { info = await ctx.session.get(input); return info; },
+                    prompt: (input) => ctx.session.prompt(input),
+                } }).catch(() => undefined);
+            const record = info;
+            if (!target || !record?.location?.directory || record.projectID !== ctx.location.project.id
+                || record.location.workspaceID !== ctx.location.workspaceID
+                || await canonicalPath(record.location.directory) !== directory)
+                return undefined;
+            return target;
+        };
+        const reconcile = async (activeSession) => {
+            const candidates = new Set((await ledger.listPresence({})).filter((binding) => binding.channel === 'opencode').map((binding) => binding.session));
+            if (activeSession)
+                candidates.add(activeSession);
+            for (const sessionId of candidates) {
+                if (lifetime.signal.aborted)
+                    return;
+                const target = await validate(sessionId);
+                if (!target) {
+                    stop(sessionId);
+                    continue;
+                }
+                const scopedEnv = operationEnv('opencode', sessionId, env);
+                if (sessionId === activeSession)
+                    await automaticSessionStart('opencode', sessionId, directory, scopedEnv);
+                if (!await publishOpenCodeRoutes(sessionId, scopedEnv, lifetime.signal)) {
+                    stop(sessionId);
+                    continue;
+                }
+                if (receivers.has(sessionId))
+                    continue;
+                const abort = new AbortController();
+                const signal = AbortSignal.any([lifetime.signal, abort.signal]);
+                const running = receiveOpenCodePending(target, scopedEnv, signal).catch(() => { });
+                receivers.set(sessionId, { abort, running });
+            }
+            for (const sessionId of receivers.keys())
+                if (!candidates.has(sessionId))
+                    stop(sessionId);
+        };
+        const cancel = async (sessionId) => {
+            if (!receivers.has(sessionId))
+                return;
+            // Stop synchronously; persist the cutoff before allowing reconciliation to start fresh work.
+            stop(sessionId);
+            await ledger.withClaimLock(async () => {
+                for (const owner of (await ledger.listPresence({ session: sessionId })).filter((binding) => binding.channel === 'opencode')) {
+                    const square = await openSquare(owner.location, { hostLedger: ledger, env, signal: lifetime.signal });
                     try {
-                        const context = await automaticSessionStart('opencode', sessionID, cwd);
-                        if (context)
-                            joining.set(sessionID, context);
+                        await ledger.suppressPresence(owner, (await square.artifact.read(lifetime.signal)).state.runtime.nextActIndex - 1);
+                    }
+                    finally {
+                        await closeOpenSquare(square);
                     }
-                    catch { /* startup remains bounded */ }
+                }
+            }, lifetime.signal);
+            await reconcile();
+        };
+        const end = async (sessionId) => {
+            stop(sessionId);
+            const memberships = (await ledger.listPresence({ session: sessionId })).filter((binding) => binding.channel === 'opencode');
+            for (const owner of memberships) {
+                const square = await Square.at({ path: owner.location, hostLedger: ledger, env: operationEnv('opencode', sessionId, env) });
+                try {
+                    await square.endOwnedSession(owner.participant, sessionId, owner.epoch);
+                }
+                finally {
+                    await square.close();
                 }
             }
-            else if (event.type === 'session.deleted') {
-                const sessionID = event.properties?.sessionID;
-                const cwd = event.properties?.info?.directory || process.cwd();
-                if (sessionID) {
-                    joining.delete(sessionID);
-                    await automaticSessionEnd('opencode', sessionID, cwd);
+        };
+        await ctx.session.hook('prompt', (event) => coordinate(() => reconcile(event.sessionID)));
+        await ctx.session.hook('context', async (event) => {
+            await coordinate(() => reconcile(event.sessionID));
+            const receiver = receivers.get(event.sessionID);
+            if (!receiver || lifetime.signal.aborted)
+                return;
+            await observeOpenCodeContext(event.sessionID, event.messages, operationEnv('opencode', event.sessionID, env), AbortSignal.any([lifetime.signal, receiver.abort.signal])).catch(() => { });
+        });
+        const changes = await ledger.observeChanges();
+        changes.evidence.close(); // Manual joins activate an idle receiver; evidence already has a session observer.
+        const presenceLoop = (async () => {
+            while (!lifetime.signal.aborted) {
+                const baseline = await changes.presence.read(lifetime.signal);
+                await coordinate(() => reconcile());
+                await changes.presence.changed(baseline, Infinity, lifetime.signal);
+            }
+        })().catch(() => { });
+        const eventLoop = (async () => {
+            for await (const event of ctx.event.subscribe({ signal: lifetime.signal })) {
+                const sessionId = event.data.sessionID;
+                if (!sessionId)
+                    continue;
+                if (event.type === 'session.deleted')
+                    await coordinate(() => end(sessionId));
+                else if (event.type === 'session.moved')
+                    await coordinate(async () => { stop(sessionId); await reconcile(); });
+                else if (event.type === 'session.execution.interrupted' && event.data.reason === 'user') {
+                    receivers.get(sessionId)?.abort.abort();
+                    await coordinate(() => cancel(sessionId));
                 }
             }
-        },
-        'shell.env': async (input, output) => {
-            if (input.sessionID)
-                output.env.OPENCODE_SESSION_ID = input.sessionID;
-        },
-        'tool.execute.after': async (input, output) => {
+        })().catch(() => { });
+        // Do not await any native prompt in setup: plugin activation itself is lazy.
+        return async () => {
+            lifetime.abort();
+            changes.presence.close();
+            const tasks = [presenceLoop, eventLoop, coordinating, ...[...receivers.keys()].map(stop)];
+            let timer;
             try {
-                const joined = joining.get(input.sessionID);
-                if (joined) {
-                    joining.delete(input.sessionID);
-                    output.output = `${output.output}${output.output === '' ? '' : '\n\n'}${joined}`;
-                }
-                await presentPendingAtBoundary(input.sessionID, (context) => {
-                    output.output = `${output.output}${output.output === '' ? '' : '\n\n'}${context}`;
-                });
+                await Promise.race([Promise.allSettled(tasks), new Promise((resolve) => { timer = setTimeout(resolve, 3000); })]);
             }
-            catch {
-                // A failed admission remains available at a later boundary.
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
             }
-        },
-    };
-}
+            // Instance unload is not session deletion: retain memberships and uncertain correlations.
+        };
+    },
+};

package/dist/packages/agent-delivery/src/claude-auth.d.ts

@@ -0,0 +1,13 @@
+import { type LocalEndpoint } from './local-endpoint.js';
+export interface ClaudeAuthOptions {
+    readonly endpoint: LocalEndpoint | string;
+    readonly token?: string;
+    readonly claudeHome?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+}
+/**
+ * Explicit token, then the environment token bound to this exact endpoint, then
+ * the newest readable peer key for it. Windows requires a token; POSIX does not.
+ */
+export declare function resolveClaudeToken(options: ClaudeAuthOptions): Promise<string | undefined>;

package/dist/packages/agent-delivery/src/claude-auth.js

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { DeliveryError } from './errors.js';
+import { parseLocalEndpoint } from './local-endpoint.js';
+const TOKEN = /^[0-9a-f]{32}$/;
+const KEY = /^(\d+)\.([0-9a-f]{64})\.key$/;
+function validToken(value) { return typeof value === 'string' && TOKEN.test(value); }
+/**
+ * Explicit token, then the environment token bound to this exact endpoint, then
+ * the newest readable peer key for it. Windows requires a token; POSIX does not.
+ */
+export async function resolveClaudeToken(options) {
+    const endpoint = typeof options.endpoint === 'string' ? parseLocalEndpoint(options.endpoint) : options.endpoint;
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    if (options.token !== undefined) {
+        if (!validToken(options.token))
+            throw new DeliveryError('authentication_failed', false);
+        return options.token;
+    }
+    if (validToken(env.CLAUDE_CODE_MESSAGING_TOKEN) && env.CLAUDE_CODE_MESSAGING_SOCKET !== undefined) {
+        try {
+            if (parseLocalEndpoint(env.CLAUDE_CODE_MESSAGING_SOCKET).canonical === endpoint.canonical)
+                return env.CLAUDE_CODE_MESSAGING_TOKEN;
+        }
+        catch { /* an unrelated malformed environment coordinate is ignored */ }
+    }
+    const home = options.claudeHome ?? env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude');
+    const digest = createHash('sha256').update(endpoint.canonical).digest('hex');
+    const keys = [];
+    try {
+        for (const name of await readdir(join(home, 'sessions'))) {
+            const match = KEY.exec(name);
+            if (!match || match[2] !== digest)
+                continue;
+            try {
+                keys.push({ name, pid: Number(match[1]), mtimeMs: (await stat(join(home, 'sessions', name))).mtimeMs });
+            }
+            catch { /* unreadable entries are skipped */ }
+        }
+    }
+    catch { /* no registry is not an error; it only means no peer key */ }
+    keys.sort((a, b) => Number(isAlive(b.pid)) - Number(isAlive(a.pid)) || b.mtimeMs - a.mtimeMs);
+    for (const key of keys) {
+        try {
+            const value = JSON.parse(await readFile(join(home, 'sessions', key.name), 'utf8'));
+            if (value && typeof value === 'object' && validToken(value.peerToken)) {
+                return value.peerToken;
+            }
+        }
+        catch { /* the next readable matching key wins */ }
+    }
+    if (platform === 'win32')
+        throw new DeliveryError('authentication_failed', false);
+    return undefined;
+}
+/** A pid that exists, including one owned by another user, holds a live inbox. */
+function isAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}

package/dist/packages/agent-delivery/src/claude-native.d.ts

@@ -0,0 +1,28 @@
+/** Plain native coordinate; no Square facts, credentials or claimed authority. */
+export interface ClaudeNativeTarget {
+    readonly sessionId: string;
+    readonly endpoint: string;
+    readonly token?: string;
+    readonly claudeHome?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly messageId?: string;
+}
+export interface ClaudeNativeControl {
+    readonly deadline: number;
+    readonly signal?: AbortSignal;
+}
+export type NativeWriteResult = {
+    readonly outcome: 'written';
+    readonly message?: never;
+} | {
+    readonly outcome: 'unknown';
+    readonly code: 'aborted' | 'timeout' | 'transport';
+    readonly message: string;
+} | {
+    readonly outcome: 'unavailable';
+    readonly code: 'aborted' | 'timeout' | 'endpoint_unavailable' | 'invalid_arguments' | 'authentication_failed';
+    readonly message: string;
+};
+/** Submit once. Written means local bytes only, never native admission or consumption. */
+export declare function writeClaudeNative(target: ClaudeNativeTarget, text: string, control: ClaudeNativeControl): Promise<NativeWriteResult>;

package/dist/packages/agent-delivery/src/claude-native.js

@@ -0,0 +1,65 @@
+import { randomUUID } from 'node:crypto';
+import { deadline } from './deadline.js';
+import { connectLocal, LocalEndpointError, parseLocalEndpoint, writeFrames } from './local-endpoint.js';
+import { resolveClaudeToken } from './claude-auth.js';
+const detail = (code) => code === 'aborted' ? 'Native inbox write aborted.'
+    : code === 'timeout' ? 'Native inbox write deadline elapsed.'
+        : code === 'authentication_failed' ? 'Claude authentication failed.'
+            : 'Native inbox endpoint unavailable.';
+/** Submit once. Written means local bytes only, never native admission or consumption. */
+export async function writeClaudeNative(target, text, control) {
+    const remaining = control?.deadline - Date.now();
+    let endpoint;
+    try {
+        endpoint = parseLocalEndpoint(target?.endpoint);
+    }
+    catch {
+        return { outcome: 'unavailable', code: 'invalid_arguments', message: 'Invalid native inbox arguments.' };
+    }
+    if (!target || typeof target.sessionId !== 'string' || !target.sessionId.trim() ||
+        typeof text !== 'string' || !text.length || !control ||
+        !Number.isFinite(control.deadline) || control.deadline <= 0 || remaining > 2_147_483_647 ||
+        (control.signal !== undefined && !(control.signal instanceof AbortSignal))) {
+        return { outcome: 'unavailable', code: 'invalid_arguments', message: 'Invalid native inbox arguments.' };
+    }
+    if (control.signal?.aborted)
+        return { outcome: 'unavailable', code: 'aborted', message: detail('aborted') };
+    if (remaining <= 0)
+        return { outcome: 'unavailable', code: 'timeout', message: detail('timeout') };
+    let token;
+    try {
+        token = await resolveClaudeToken({ endpoint, token: target.token, claudeHome: target.claudeHome, env: target.env, platform: target.platform });
+    }
+    catch {
+        return { outcome: 'unavailable', code: 'authentication_failed', message: detail('authentication_failed') };
+    }
+    const frames = [
+        ...(token === undefined ? [] : [{ type: 'auth', token }]),
+        { msgV: 1, msg_id: target.messageId ?? randomUUID(), type: 'user', session_id: target.sessionId, message: { role: 'user', content: text }, priority: 'next' },
+    ];
+    const scope = deadline(Math.min(remaining, 2_147_483_647), control.signal);
+    let socket;
+    try {
+        scope.check();
+        socket = await connectLocal(endpoint, { signal: scope.signal, timeoutMs: Math.max(1, remaining) });
+        scope.check();
+        // A receiver that never drains must not hold the caller past its deadline.
+        await scope.wait(writeFrames(socket, frames));
+        scope.check();
+        return { outcome: 'written' };
+    }
+    catch (error) {
+        const local = error instanceof LocalEndpointError ? error : undefined;
+        const code = scope.code ?? local?.code;
+        if (code === 'aborted' || code === 'timeout') {
+            return { outcome: socket ? 'unknown' : 'unavailable', code, message: detail(code) };
+        }
+        if (socket)
+            return { outcome: 'unknown', code: 'transport', message: 'Native inbox write unconfirmed.' };
+        return { outcome: 'unavailable', code: 'endpoint_unavailable', message: detail('unavailable') };
+    }
+    finally {
+        socket?.destroy();
+        scope.close();
+    }
+}

package/dist/packages/agent-delivery/src/claude.d.ts

@@ -0,0 +1,14 @@
+import type { ClaudeDeliveryResult, ClaudeSendTextOptions, ClaudeTarget } from './types.js';
+export interface ClaudeConnectExistingOptions {
+    readonly harness: 'claude';
+    readonly sessionId: string;
+    readonly endpoint: string;
+    readonly token?: string;
+    readonly claudeHome?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** Resolve an explicitly identified existing Claude native inbox; never discovers or starts one. */
+export declare function connectExisting(options: ClaudeConnectExistingOptions): Promise<ClaudeTarget>;
+/** Write once to Claude's next native boundary; local write is never native admission. */
+export declare function sendText(target: ClaudeTarget, text: string, options?: ClaudeSendTextOptions): Promise<ClaudeDeliveryResult>;

package/dist/packages/agent-delivery/src/claude.js

@@ -0,0 +1,66 @@
+import { randomUUID } from 'node:crypto';
+import { deadline, validSignal, validTimeout } from './deadline.js';
+import { ConnectionError, DeliveryError } from './errors.js';
+import { isIdentity, isRecord } from './guards.js';
+import { parseLocalEndpoint } from './local-endpoint.js';
+import { writeClaudeNative } from './claude-native.js';
+import { resolveClaudeToken } from './claude-auth.js';
+const coordinates = new WeakMap();
+/** Resolve an explicitly identified existing Claude native inbox; never discovers or starts one. */
+export async function connectExisting(options) {
+    if (!isRecord(options) || options.harness !== 'claude' || !isIdentity(options.sessionId) ||
+        typeof options.endpoint !== 'string' || options.endpoint.includes('\0') ||
+        !validTimeout(options.timeoutMs) || !validSignal(options.signal))
+        throw new ConnectionError('invalid_arguments');
+    let endpoint;
+    try {
+        endpoint = parseLocalEndpoint(options.endpoint);
+    }
+    catch {
+        throw new ConnectionError('invalid_arguments');
+    }
+    if (!(process.platform === 'darwin' || process.platform === 'linux' || process.platform === 'win32'))
+        throw new ConnectionError('unsupported_platform');
+    if (process.platform === 'win32' ? endpoint.kind !== 'pipe' : endpoint.kind !== 'unix')
+        throw new ConnectionError('invalid_arguments');
+    const scope = deadline(options.timeoutMs, options.signal);
+    try {
+        scope.check();
+        // The ambient environment and platform are the only auth coordinates here.
+        const token = await resolveClaudeToken({ endpoint, token: options.token, claudeHome: options.claudeHome });
+        scope.check();
+        const target = Object.freeze({ harness: 'claude', sessionId: options.sessionId });
+        coordinates.set(target, { endpoint: options.endpoint, token, claudeHome: options.claudeHome });
+        return target;
+    }
+    catch (error) {
+        if (scope.code !== undefined)
+            throw new ConnectionError(scope.code);
+        if (error instanceof ConnectionError)
+            throw error;
+        if (error instanceof DeliveryError)
+            throw new ConnectionError(error.code);
+        throw new ConnectionError('invalid_response');
+    }
+    finally {
+        scope.close();
+    }
+}
+/** Write once to Claude's next native boundary; local write is never native admission. */
+export async function sendText(target, text, options = {}) {
+    const coordinate = isRecord(target) ? coordinates.get(target) : undefined;
+    if (!coordinate || target.harness !== 'claude' || !isIdentity(target.sessionId) || typeof text !== 'string' || !text.length || !isRecord(options) ||
+        (options.delivery !== undefined && options.delivery !== 'steer') || options.inputId !== undefined ||
+        !validTimeout(options.timeoutMs) || !validSignal(options.signal))
+        throw new TypeError('Invalid Claude sendText arguments.');
+    const messageId = randomUUID();
+    const result = await writeClaudeNative({ ...coordinate, sessionId: target.sessionId, messageId }, text, { deadline: Date.now() + (options.timeoutMs ?? 5_000), signal: options.signal });
+    const attempt = { harness: 'claude', sessionId: target.sessionId };
+    if (result.outcome === 'written')
+        return { ...attempt, state: 'written', messageId };
+    if (result.outcome === 'unknown')
+        return { ...attempt, state: 'unknown', code: result.code };
+    if (result.code === 'invalid_arguments')
+        throw new TypeError('Invalid Claude sendText arguments.');
+    return { ...attempt, state: 'unavailable', code: result.code };
+}

package/dist/packages/agent-delivery/src/deadline.d.ts

@@ -0,0 +1,11 @@
+export declare const DEFAULT_TIMEOUT_MS = 5000;
+export declare function validTimeout(value: unknown): value is number | undefined;
+export declare function validSignal(value: unknown): value is AbortSignal | undefined;
+/** Bounds caller waiting even for Service.discover, which cannot accept a signal. */
+export declare function deadline(timeoutMs?: number, parent?: AbortSignal): {
+    signal: AbortSignal;
+    readonly code: "aborted" | "timeout" | undefined;
+    check(): void;
+    wait<T>(operation: Promise<T>): Promise<T>;
+    close(): void;
+};

package/dist/packages/agent-delivery/src/deadline.js

@@ -0,0 +1,41 @@
+export const DEFAULT_TIMEOUT_MS = 5_000;
+export function validTimeout(value) {
+    // Node clamps larger timers to 1ms; do not silently turn a deadline into that.
+    return value === undefined ||
+        (typeof value === 'number' && Number.isFinite(value) && value > 0 && value <= 2_147_483_647);
+}
+export function validSignal(value) {
+    return value === undefined || value instanceof AbortSignal;
+}
+/** Bounds caller waiting even for Service.discover, which cannot accept a signal. */
+export function deadline(timeoutMs = DEFAULT_TIMEOUT_MS, parent) {
+    const controller = new AbortController();
+    let code;
+    let rejectStopped;
+    const stopped = new Promise((_, reject) => { rejectStopped = reject; });
+    // A pre-aborted scope may never reach wait().
+    void stopped.catch(() => { });
+    const stop = (reason) => {
+        if (code !== undefined)
+            return;
+        code = reason;
+        controller.abort();
+        rejectStopped(new Error('Operation stopped.'));
+    };
+    const onAbort = () => stop('aborted');
+    parent?.addEventListener('abort', onAbort, { once: true });
+    if (parent?.aborted)
+        onAbort();
+    const timer = setTimeout(() => stop('timeout'), timeoutMs);
+    return {
+        signal: controller.signal,
+        get code() { return code; },
+        check() { if (code !== undefined)
+            throw new Error('Operation stopped.'); },
+        wait(operation) { return Promise.race([operation, stopped]); },
+        close() {
+            clearTimeout(timer);
+            parent?.removeEventListener('abort', onAbort);
+        },
+    };
+}

package/dist/packages/agent-delivery/src/errors.d.ts

@@ -0,0 +1,16 @@
+export type DeliveryErrorCode = 'invalid_arguments' | 'unsupported_platform' | 'unavailable' | 'authentication_failed' | 'session_not_found' | 'rejected' | 'unsupported_version' | 'invalid_response' | 'timeout' | 'aborted' | 'transport';
+/** Diagnostics intentionally contain no endpoint, credentials, body, or SDK cause. */
+export declare class DeliveryError extends Error {
+    readonly code: DeliveryErrorCode;
+    readonly maybeDelivered: boolean;
+    readonly id?: string;
+    readonly status?: number;
+    constructor(code: DeliveryErrorCode, maybeDelivered?: boolean, id?: string, status?: number);
+}
+/** Internal connection precondition failure; the public entry translates it. */
+export type ConnectionErrorCode = DeliveryErrorCode | 'service_unavailable' | 'http_rejection';
+export declare class ConnectionError extends Error {
+    readonly code: ConnectionErrorCode;
+    readonly status?: number;
+    constructor(code: ConnectionErrorCode, status?: number);
+}

package/dist/packages/agent-delivery/src/errors.js

@@ -0,0 +1,41 @@
+const messages = {
+    invalid_arguments: 'Invalid delivery arguments.',
+    unsupported_platform: 'This delivery transport is not supported on this platform.',
+    unavailable: 'The delivery endpoint is unavailable.',
+    authentication_failed: 'Delivery authentication failed.',
+    session_not_found: 'The requested session was not found.',
+    rejected: 'The delivery was rejected.',
+    unsupported_version: 'The receiving service version is unsupported.',
+    invalid_response: 'The receiving service returned an invalid response.',
+    timeout: 'The delivery deadline expired.',
+    aborted: 'The delivery was aborted.',
+    transport: 'The delivery transport failed.',
+};
+/** Diagnostics intentionally contain no endpoint, credentials, body, or SDK cause. */
+export class DeliveryError extends Error {
+    code;
+    maybeDelivered;
+    id;
+    status;
+    constructor(code, maybeDelivered = false, id, status) {
+        super(messages[code]);
+        this.name = 'DeliveryError';
+        this.code = code;
+        this.maybeDelivered = maybeDelivered;
+        if (id !== undefined)
+            this.id = id;
+        if (status !== undefined && Number.isInteger(status) && status >= 100 && status <= 599)
+            this.status = status;
+    }
+}
+export class ConnectionError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(messages[code] ?? (code === 'http_rejection' ? 'The receiving service rejected the request.' : 'No compatible existing service is available.'));
+        this.name = 'ConnectionError';
+        this.code = code;
+        if (status !== undefined && Number.isInteger(status) && status >= 100 && status <= 599)
+            this.status = status;
+    }
+}

package/dist/packages/agent-delivery/src/guards.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The two structure checks every harness front door repeats: a plain object and a
+ * non-empty identity string. They live here once instead of once per transport.
+ */
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const isIdentity: (value: unknown) => value is string;

package/dist/packages/agent-delivery/src/guards.js

@@ -0,0 +1,6 @@
+/**
+ * The two structure checks every harness front door repeats: a plain object and a
+ * non-empty identity string. They live here once instead of once per transport.
+ */
+export const isRecord = (value) => typeof value === 'object' && value !== null;
+export const isIdentity = (value) => typeof value === 'string' && value.trim().length > 0;