@astrosheep/square 0.3.63 → 0.3.65

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

@@ -0,0 +1,83 @@
+import { DeliveryError } from './errors.js';
+export interface SendOptions {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface KeyedSendOptions extends SendOptions {
+    readonly id?: string;
+}
+export interface Receipt {
+    readonly id: string;
+    readonly proof: 'written' | 'admitted' | 'observed';
+}
+export interface Steerable<O = SendOptions> {
+    steer(text: string, options?: O): Promise<Receipt>;
+}
+export interface Queueable<O = SendOptions> {
+    queue(text: string, options?: O): Promise<Receipt>;
+}
+export interface OpenCodeConnectOptions {
+    readonly harness: 'opencode';
+    readonly sessionId: string;
+    readonly endpoint?: {
+        readonly url: string;
+        readonly auth?: {
+            readonly type: 'basic';
+            readonly username: string;
+            readonly password: string;
+        };
+    };
+    readonly registrationFile?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ClaudeConnectOptions {
+    readonly harness: 'claude';
+    readonly sessionId: string;
+    readonly endpoint: string;
+    readonly token?: string;
+    readonly claudeHome?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface PiConnectOptions {
+    readonly harness: 'pi';
+    readonly sessionId: string;
+    readonly endpoint: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface PaseoConnectOptions {
+    readonly harness: 'paseo';
+    readonly agentId: string;
+    readonly endpoint?: string;
+    readonly password?: string;
+    readonly authHeader?: string;
+    readonly localCredential?: string;
+    readonly paseoHome?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export type OpenCodeAgent = Steerable<KeyedSendOptions> & Queueable<KeyedSendOptions> & {
+    readonly harness: 'opencode';
+    readonly sessionId: string;
+};
+export type ClaudeAgent = Steerable & {
+    readonly harness: 'claude';
+    readonly sessionId: string;
+};
+export type PiAgent = Steerable & Queueable & {
+    readonly harness: 'pi';
+    readonly sessionId: string;
+};
+export type PaseoAgent = Steerable<KeyedSendOptions> & {
+    readonly harness: 'paseo';
+    readonly agentId: string;
+};
+export type Agent = OpenCodeAgent | ClaudeAgent | PiAgent | PaseoAgent;
+export declare function connect(options: OpenCodeConnectOptions): Promise<OpenCodeAgent>;
+export declare function connect(options: ClaudeConnectOptions): Promise<ClaudeAgent>;
+export declare function connect(options: PiConnectOptions): Promise<PiAgent>;
+export declare function connect(options: PaseoConnectOptions): Promise<PaseoAgent>;
+export { DeliveryError };
+export type { DeliveryErrorCode } from './errors.js';

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

@@ -0,0 +1,110 @@
+import { ConnectionError, DeliveryError } from './errors.js';
+import { isRecord } from './guards.js';
+const codes = {
+    invalid_arguments: 'invalid_arguments', unsupported_platform: 'unsupported_platform',
+    service_unavailable: 'unavailable', authentication_failed: 'authentication_failed',
+    session_not_found: 'session_not_found', http_rejection: 'rejected',
+    unsupported_version: 'unsupported_version', invalid_response: 'invalid_response',
+    timeout: 'timeout', aborted: 'aborted', transport: 'transport',
+};
+/**
+ * One classification path for a connection failure, a send failure and the
+ * harness's own attempt state. Past the send precondition an unclassified
+ * failure may have reached the receiver.
+ */
+function failure(error, phase, id) {
+    if (error instanceof DeliveryError)
+        return error;
+    if (error instanceof ConnectionError)
+        return new DeliveryError(codes[error.code] ?? 'transport', false, id, error.status);
+    if (error instanceof TypeError)
+        return new DeliveryError('invalid_arguments', false, id);
+    const attempt = error;
+    if (typeof attempt?.state !== 'string')
+        return new DeliveryError('transport', phase === 'send', id);
+    const code = attempt.state === 'unavailable'
+        ? attempt.code === 'aborted' ? 'aborted' : attempt.code === 'timeout' ? 'timeout'
+            : attempt.code === 'authentication_failed' ? 'authentication_failed' : 'unavailable'
+        : attempt.state === 'rejected' ? attempt.code === 'not_found' ? 'session_not_found' : 'rejected'
+            : codes[attempt.code ?? 'transport'] ?? 'transport';
+    return new DeliveryError(code, attempt.state === 'unknown', id ?? attempt.inputId, attempt.status);
+}
+const harnesses = {
+    opencode: {
+        harness: 'opencode', proof: 'admitted', accepted: 'accepted', coordinate: 'sessionId', keyed: true, queue: true,
+        id: (result) => result.inputId,
+        open: async (options) => {
+            const { connectExisting, sendText } = await import('./opencode.js');
+            const target = await connectExisting(options);
+            return { coordinate: target.sessionId, send: (text, value) => sendText(target, text, value) };
+        },
+    },
+    claude: {
+        harness: 'claude', proof: 'written', accepted: 'written', coordinate: 'sessionId', keyed: false, queue: false,
+        id: (result) => result.messageId,
+        open: async (options) => {
+            const { connectExisting, sendText } = await import('./claude.js');
+            const target = await connectExisting(options);
+            return { coordinate: target.sessionId, send: (text, value) => sendText(target, text, value) };
+        },
+    },
+    pi: {
+        harness: 'pi', proof: 'observed', accepted: 'observed', coordinate: 'sessionId', keyed: false, queue: true,
+        id: (result) => result.inputId,
+        open: async (options) => {
+            const { connectPi, sendPiText } = await import('./pi-client.js');
+            const target = await connectPi(options);
+            return { coordinate: target.sessionId, send: (text, value) => sendPiText(target, text, value) };
+        },
+    },
+    paseo: {
+        harness: 'paseo', proof: 'admitted', accepted: 'admitted', coordinate: 'agentId', keyed: true, queue: false,
+        id: (result) => result.inputId,
+        open: async (options) => {
+            const { connectPaseo, sendPaseoText } = await import('./paseo.js');
+            const target = await connectPaseo(options);
+            return { coordinate: target.agentId, send: (text, value) => sendPaseoText(target, text, value) };
+        },
+    },
+};
+export async function connect(options) {
+    const harness = isRecord(options) && typeof options.harness === 'string' ? options.harness : undefined;
+    // An own-key check keeps Object.prototype names out of the transport table.
+    const spec = harness !== undefined && Object.hasOwn(harnesses, harness) ? harnesses[harness] : undefined;
+    if (spec === undefined)
+        throw new DeliveryError('invalid_arguments');
+    let opened;
+    try {
+        opened = await spec.open(options);
+    }
+    catch (error) {
+        throw failure(error, 'connect');
+    }
+    const send = async (text, value, delivery) => {
+        const options = value === undefined ? {} : value;
+        if (!isRecord(options))
+            throw new DeliveryError('invalid_arguments');
+        // An unusable caller id is an argument precondition; the native sender rejects it.
+        const id = options.id;
+        try {
+            const result = await opened.send(text, spec.keyed
+                ? { delivery, inputId: id, timeoutMs: options.timeoutMs, signal: options.signal }
+                : { delivery, timeoutMs: options.timeoutMs, signal: options.signal });
+            if (result.state !== spec.accepted)
+                throw failure(result, 'send', id);
+            return { id: spec.id(result), proof: spec.proof };
+        }
+        catch (error) {
+            throw failure(error, 'send', id);
+        }
+    };
+    const agent = {
+        harness: spec.harness,
+        [spec.coordinate]: opened.coordinate,
+        steer: (text, value) => send(text, value, 'steer'),
+    };
+    if (spec.queue)
+        agent.queue = (text, value) => send(text, value, 'queue');
+    return Object.freeze(agent);
+}
+export { DeliveryError };

package/dist/packages/agent-delivery/src/local-endpoint.d.ts

@@ -0,0 +1,26 @@
+import net from 'node:net';
+export interface LocalEndpoint {
+    readonly kind: 'unix' | 'pipe';
+    /** What the socket connects to. */
+    readonly path: string;
+    /** What the native receiver fingerprints; also the auth key file digest input. */
+    readonly canonical: string;
+}
+/**
+ * A local endpoint is either a Windows named pipe or an absolute Unix socket
+ * path. There is no `stat().isSocket()` check: connecting is the existence check.
+ */
+export declare function parseLocalEndpoint(raw: unknown): LocalEndpoint;
+export declare class LocalEndpointError extends Error {
+    readonly code: 'unavailable' | 'aborted' | 'timeout' | 'transport';
+    readonly maybeDelivered: boolean;
+    constructor(code: LocalEndpointError['code'], maybeDelivered?: boolean);
+}
+export interface LocalConnectScope {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+}
+/** Connect with bounded waiting. A connect failure is `unavailable`: nothing was written. */
+export declare function connectLocal(endpoint: LocalEndpoint, scope?: LocalConnectScope): Promise<net.Socket>;
+/** LF-delimited JSON frames. Any failure here is past the uncertainty boundary. */
+export declare function writeFrames(socket: net.Socket, frames: object[]): Promise<void>;

package/dist/packages/agent-delivery/src/local-endpoint.js

@@ -0,0 +1,114 @@
+import net from 'node:net';
+import { resolve } from 'node:path';
+/** Claude's own pipe spelling: `\\.\pipe\<lowercased name>`. */
+const PIPE = /^[\\/]{2}[.?][\\/]pipe[\\/](?:(LOCAL)[\\/])?([^\\/]+)$/i;
+/**
+ * A local endpoint is either a Windows named pipe or an absolute Unix socket
+ * path. There is no `stat().isSocket()` check: connecting is the existence check.
+ */
+export function parseLocalEndpoint(raw) {
+    if (typeof raw !== 'string' || raw.includes('\0'))
+        throw new Error('Invalid local endpoint.');
+    const pipe = PIPE.exec(raw);
+    if (pipe) {
+        const canonical = `\\\\.\\pipe\\${pipe[2].toLowerCase()}`;
+        return { kind: 'pipe', path: canonical, canonical };
+    }
+    if (!(process.platform === 'win32' ? /^[A-Za-z]:[\\/]/.test(raw) : raw.startsWith('/')))
+        throw new Error('Invalid local endpoint.');
+    const limit = process.platform === 'darwin' ? 103 : process.platform === 'linux' ? 107 : undefined;
+    if (limit !== undefined && Buffer.byteLength(raw) > limit)
+        throw new Error('Invalid local endpoint.');
+    const canonical = resolve(raw);
+    return { kind: 'unix', path: canonical, canonical };
+}
+export class LocalEndpointError extends Error {
+    code;
+    maybeDelivered;
+    constructor(code, maybeDelivered = false) {
+        super(code);
+        this.name = 'LocalEndpointError';
+        this.code = code;
+        this.maybeDelivered = maybeDelivered;
+    }
+}
+function errnoCode(error) {
+    let code;
+    if (typeof error === 'object' && error !== null)
+        code = error.code;
+    if (code === 'ENOENT' || code === 'ECONNREFUSED' || code === 'EPIPE' || code === 'EBUSY' || code === 'EACCES')
+        return 'unavailable';
+    return 'transport';
+}
+/** Connect with bounded waiting. A connect failure is `unavailable`: nothing was written. */
+export function connectLocal(endpoint, scope = {}) {
+    return new Promise((resolveSocket, reject) => {
+        const socket = new net.Socket();
+        let settled = false;
+        const timeout = scope.timeoutMs === undefined ? undefined : setTimeout(() => finish(new LocalEndpointError('timeout')), scope.timeoutMs);
+        // Error/close handlers stay attached past settling: an already scheduled I/O
+        // failure must not become an unhandled event once this promise is done.
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            scope.signal?.removeEventListener('abort', aborted);
+            socket.removeListener('connect', connected);
+            if (error) {
+                socket.destroy();
+                reject(error);
+            }
+            else
+                resolveSocket(socket);
+        };
+        const aborted = () => finish(new LocalEndpointError('aborted'));
+        const connected = () => finish();
+        const failed = (error) => finish(new LocalEndpointError(errnoCode(error)));
+        socket.once('connect', connected);
+        socket.once('error', failed);
+        socket.once('close', () => { if (!settled)
+            finish(new LocalEndpointError('unavailable')); });
+        scope.signal?.addEventListener('abort', aborted, { once: true });
+        if (scope.signal?.aborted) {
+            aborted();
+            return;
+        }
+        try {
+            socket.connect(endpoint.path);
+        }
+        catch (error) {
+            failed(error);
+        }
+    });
+}
+/** LF-delimited JSON frames. Any failure here is past the uncertainty boundary. */
+export function writeFrames(socket, frames) {
+    const payload = frames.map((frame) => JSON.stringify(frame)).join('\n') + '\n';
+    return new Promise((resolveWrite, reject) => {
+        let settled = false;
+        // Error/close handlers stay attached past settling, so a later I/O failure is
+        // swallowed here instead of surfacing as an unhandled socket event.
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolveWrite();
+        };
+        const failed = (error) => finish(new LocalEndpointError(errnoCode(error), true));
+        socket.once('error', failed);
+        socket.once('close', () => finish(new LocalEndpointError('transport', true)));
+        socket.end(payload, 'utf8', (error) => {
+            if (error) {
+                failed(error);
+                return;
+            }
+            finish();
+        });
+    });
+}

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

@@ -0,0 +1,33 @@
+import type { OpenCodeDeliveryResult, OpenCodeSendTextOptions } from './types.js';
+/** Injected native capability. No endpoint discovery or SDK initialization. */
+export interface OpenCodeSessionCapability {
+    get(input: {
+        sessionID: string;
+    }, options?: {
+        signal: AbortSignal;
+    }): Promise<unknown>;
+    prompt(input: {
+        sessionID: string;
+        id: string;
+        text: string;
+        delivery: 'steer' | 'queue';
+        resume: true;
+    }, options?: {
+        signal: AbortSignal;
+    }): Promise<unknown>;
+}
+export interface OpenCodeNativeSession {
+    readonly sessionId: string;
+    readonly session: OpenCodeSessionCapability;
+}
+export declare function isNativeSession(value: unknown, sessionId: string): value is Record<string, unknown>;
+/** Validate an explicit existing identity against the receiving backend. */
+export declare function connectNative(options: {
+    sessionId: string;
+    session: OpenCodeSessionCapability;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<OpenCodeNativeSession>;
+export declare function createNativeInputId(): string;
+/** Submit once. Deadline/cancellation bounds waiting, not in-process native custody. */
+export declare function sendNativeText(target: OpenCodeNativeSession, text: string, options?: OpenCodeSendTextOptions): Promise<OpenCodeDeliveryResult>;

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

@@ -0,0 +1,75 @@
+import { randomUUID } from 'node:crypto';
+import { deadline, validSignal, validTimeout } from './deadline.js';
+import { ConnectionError } from './errors.js';
+const record = (v) => typeof v === 'object' && v !== null;
+const identity = (v) => typeof v === 'string' && v.trim().length > 0;
+export function isNativeSession(value, sessionId) {
+    return record(value) && value.id === sessionId;
+}
+/** Validate an explicit existing identity against the receiving backend. */
+export async function connectNative(options) {
+    if (!record(options) || !identity(options.sessionId) || !record(options.session) ||
+        typeof options.session.get !== 'function' || typeof options.session.prompt !== 'function' ||
+        !validTimeout(options.timeoutMs) || !validSignal(options.signal))
+        throw new ConnectionError('invalid_arguments');
+    const scope = deadline(options.timeoutMs, options.signal);
+    try {
+        scope.check();
+        const session = await scope.wait(options.session.get({ sessionID: options.sessionId }, { signal: scope.signal }));
+        scope.check();
+        if (!isNativeSession(session, options.sessionId))
+            throw new ConnectionError('invalid_response');
+        return { sessionId: options.sessionId, session: options.session };
+    }
+    catch (error) {
+        if (scope.code !== undefined)
+            throw new ConnectionError(scope.code);
+        if (error instanceof ConnectionError)
+            throw error;
+        throw new ConnectionError('service_unavailable');
+    }
+    finally {
+        scope.close();
+    }
+}
+function admission(value, sessionId, inputId) {
+    return record(value) && value.id === inputId && value.sessionID === sessionId &&
+        value.type === 'user' && (value.delivery === 'steer' || value.delivery === 'queue') &&
+        record(value.payload) && typeof value.payload.text === 'string' &&
+        record(value.time) && typeof value.time.created === 'number' &&
+        Number.isFinite(value.time.created) && value.time.created >= 0;
+}
+export function createNativeInputId() { return `msg_${randomUUID()}`; }
+/** Submit once. Deadline/cancellation bounds waiting, not in-process native custody. */
+export async function sendNativeText(target, text, options = {}) {
+    if (!record(target) || !identity(target.sessionId) || !record(target.session) || typeof target.session.prompt !== 'function' ||
+        typeof text !== 'string' || text.length === 0 || !record(options) ||
+        !validTimeout(options.timeoutMs) || !validSignal(options.signal) ||
+        (options.delivery !== undefined && options.delivery !== 'steer' && options.delivery !== 'queue') ||
+        (options.inputId !== undefined && (typeof options.inputId !== 'string' || !options.inputId.startsWith('msg_') || options.inputId.length <= 4))) {
+        throw new TypeError('Invalid sendText arguments.');
+    }
+    const inputId = options.inputId ?? createNativeInputId();
+    const attempt = { harness: 'opencode', sessionId: target.sessionId, inputId };
+    const scope = deadline(options.timeoutMs, options.signal);
+    let invoked = false;
+    try {
+        scope.check();
+        invoked = true;
+        const value = await scope.wait(target.session.prompt({
+            sessionID: target.sessionId, id: inputId, text, delivery: options.delivery ?? 'steer', resume: true,
+        }, { signal: scope.signal }));
+        scope.check();
+        if (!admission(value, target.sessionId, inputId))
+            return { ...attempt, state: 'unknown', code: 'invalid_response' };
+        const receipt = value;
+        return { ...attempt, state: 'accepted', inboxId: receipt.id, delivery: receipt.delivery };
+    }
+    catch {
+        return invoked ? { ...attempt, state: 'unknown', code: scope.code ?? 'transport' }
+            : { ...attempt, state: 'unavailable', code: scope.code ?? 'aborted' };
+    }
+    finally {
+        scope.close();
+    }
+}

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

@@ -0,0 +1,14 @@
+import { type Endpoint } from '@opencode/client/service';
+import type { OpenCodeDeliveryResult, OpenCodeTarget, OpenCodeSendTextOptions } from './types.js';
+export interface OpenCodeConnectExistingOptions {
+    readonly harness: 'opencode';
+    readonly sessionId: string;
+    readonly endpoint?: Endpoint;
+    readonly registrationFile?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+/** Resolve an existing service and persisted session. Never starts or stops a service. */
+export declare function connectExisting(options: OpenCodeConnectExistingOptions): Promise<OpenCodeTarget>;
+/** Submit once through the shared native sender; HTTP metadata alone refines rejection. */
+export declare function sendText(target: OpenCodeTarget, text: string, options?: OpenCodeSendTextOptions): Promise<OpenCodeDeliveryResult>;

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

@@ -0,0 +1,127 @@
+import { isAbsolute } from 'node:path';
+import { OpenCode } from '@opencode/client';
+import { Service } from '@opencode/client/service';
+import { deadline, validSignal, validTimeout } from './deadline.js';
+import { ConnectionError } from './errors.js';
+import { isIdentity, isRecord } from './guards.js';
+import { isNativeSession, sendNativeText } from './opencode-native.js';
+const endpoints = new WeakMap();
+const isV2 = (version) => /^2\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version);
+function endpointValid(value) {
+    if (!isRecord(value) || typeof value.url !== 'string')
+        return false;
+    try {
+        const url = new URL(value.url);
+        // Secrets belong only in auth, never URL userinfo/query/fragment. No redirects.
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return value.auth === undefined || (isRecord(value.auth) && value.auth.type === 'basic' &&
+        typeof value.auth.username === 'string' && typeof value.auth.password === 'string');
+}
+/** SDK transport observation: never parse or expose arbitrary error bodies. */
+function transport(endpoint, scope) {
+    let dispatched = false;
+    let status;
+    const client = OpenCode.make({
+        baseUrl: endpoint.url,
+        headers: Service.headers(endpoint),
+        fetch: async (input, init) => {
+            scope.check();
+            dispatched = true;
+            status = undefined;
+            const response = await globalThis.fetch(input, { ...init, redirect: 'manual' });
+            status = response.status;
+            return response;
+        },
+    });
+    return { client, get dispatched() { return dispatched; }, get status() { return status; } };
+}
+function connectionFailure(status, phase) {
+    if (status === 401 || status === 403)
+        return new ConnectionError('authentication_failed', status);
+    if (status === 404 && phase === 'session')
+        return new ConnectionError('session_not_found', status);
+    if (status !== undefined && status !== 200)
+        return new ConnectionError('http_rejection', status);
+    return new ConnectionError(status === 200 ? 'invalid_response' : 'service_unavailable');
+}
+/** Resolve an existing service and persisted session. Never starts or stops a service. */
+export async function connectExisting(options) {
+    if (!isRecord(options) || options.harness !== 'opencode' || !isIdentity(options.sessionId) ||
+        !validTimeout(options.timeoutMs) || !validSignal(options.signal) ||
+        (options.endpoint !== undefined && options.registrationFile !== undefined) ||
+        (options.endpoint !== undefined && !endpointValid(options.endpoint)) ||
+        (options.registrationFile !== undefined &&
+            (typeof options.registrationFile !== 'string' || !isAbsolute(options.registrationFile)))) {
+        throw new ConnectionError('invalid_arguments');
+    }
+    const scope = deadline(options.timeoutMs, options.signal);
+    let current;
+    let phase = 'health';
+    try {
+        scope.check();
+        const endpoint = options.endpoint ?? await scope.wait(Service.discover({
+            file: options.registrationFile,
+            version: isV2,
+        }));
+        // Discover may finish later than the caller deadline: never continue from it.
+        scope.check();
+        if (endpoint === undefined)
+            throw new ConnectionError('service_unavailable');
+        if (!endpointValid(endpoint))
+            throw new ConnectionError('invalid_response');
+        const privateEndpoint = {
+            url: endpoint.url,
+            ...(endpoint.auth === undefined ? {} : { auth: { ...endpoint.auth } }),
+        };
+        current = transport(privateEndpoint, scope);
+        const info = await scope.wait(current.client.server.info({ signal: scope.signal }));
+        scope.check();
+        if (!isRecord(info) || typeof info.version !== 'string' ||
+            !Number.isInteger(info.pid) || info.pid < 0)
+            throw new ConnectionError('invalid_response');
+        if (!isV2(info.version))
+            throw new ConnectionError('unsupported_version');
+        phase = 'session';
+        const session = await scope.wait(current.client.session.get({ sessionID: options.sessionId }, { signal: scope.signal }));
+        scope.check();
+        if (!isNativeSession(session, options.sessionId))
+            throw new ConnectionError('invalid_response');
+        const target = Object.freeze({ harness: 'opencode', sessionId: options.sessionId });
+        endpoints.set(target, privateEndpoint);
+        return target;
+    }
+    catch (error) {
+        if (scope.code !== undefined)
+            throw new ConnectionError(scope.code);
+        if (error instanceof ConnectionError)
+            throw error;
+        throw connectionFailure(current?.status, phase);
+    }
+    finally {
+        scope.close();
+    }
+}
+/** Submit once through the shared native sender; HTTP metadata alone refines rejection. */
+export async function sendText(target, text, options = {}) {
+    if (!isRecord(target) || !endpoints.has(target)) {
+        throw new TypeError('Invalid sendText arguments.');
+    }
+    const current = transport(endpoints.get(target), { check() { } });
+    const result = await sendNativeText({ sessionId: target.sessionId, session: current.client.session }, text, options);
+    if (result.state !== 'unknown')
+        return result;
+    // Only native validation/auth/not-found/conflict responses establish rejection.
+    // A proxy or backend can fail after durable admission, including with a 5xx.
+    if (current.status !== undefined && [400, 401, 403, 404, 409].includes(current.status)) {
+        return { harness: result.harness, sessionId: result.sessionId, inputId: result.inputId,
+            state: 'rejected', code: 'http_rejection', status: current.status };
+    }
+    if (!current.dispatched)
+        return { ...result, state: 'unavailable', code: result.code === 'timeout' ? 'timeout' : 'aborted' };
+    return { ...result, code: current.status === 200 && result.code === 'transport' ? 'invalid_response' : result.code };
+}

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

@@ -0,0 +1,58 @@
+/** A resolved daemon coordinate: one WebSocket URL and, for IPC, its socket path. */
+export interface PaseoDaemonTarget {
+    readonly url: string;
+    readonly socketPath?: string;
+    /** A password spelled into a tcp:// endpoint, when that endpoint carries one. */
+    readonly password?: string;
+}
+/** Authentication for one daemon connection; the daemon client claims at most one. */
+export interface PaseoCredential {
+    readonly authHeader?: string;
+    readonly password?: string;
+    readonly localCredential?: () => string | undefined;
+}
+/** One projected timeline entry, as far as a wake boundary check reads it. */
+export interface PaseoAgentTimeline {
+    readonly agent?: {
+        readonly status?: string;
+    };
+    readonly entries?: readonly {
+        readonly item: {
+            readonly type?: string;
+            readonly callId?: string;
+            readonly status?: string;
+        };
+    }[];
+}
+/** The daemon client subset every Paseo caller uses; the SDK stays a dynamic import. */
+export interface PaseoClient {
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    sendAgentMessage(agentId: string, text: string, options: {
+        messageId: string;
+        activeTurnBehavior: 'steer';
+    }): Promise<unknown>;
+    fetchAgentTimeline(agentId: string, options: {
+        direction: 'tail';
+        limit: number;
+        projection: 'projected';
+        timeout: number;
+    }): Promise<PaseoAgentTimeline>;
+}
+/** `~/` expansion plus the daemon's default home directory. */
+export declare function paseoHome(explicit?: string, env?: NodeJS.ProcessEnv): string;
+/** One resolution for every Paseo caller. Never starts or stops anything. */
+export declare function resolvePaseoDaemon(endpoint: string | undefined, env?: NodeJS.ProcessEnv, home?: string): PaseoDaemonTarget | undefined;
+/** Explicit credential first, then the endpoint's own password, then the daemon's local credential, then `PASEO_PASSWORD`. */
+export declare function daemonCredential(options: {
+    readonly authHeader?: string;
+    readonly password?: string;
+    readonly localCredential?: string;
+    /** The password spelled into the resolved endpoint, when it carries one. */
+    readonly endpointPassword?: string;
+}, env?: NodeJS.ProcessEnv, home?: string): PaseoCredential;
+/**
+ * Open one daemon connection. The SDK and `ws` load only when a Paseo call actually
+ * runs, so importing this module never pulls an optional peer dependency.
+ */
+export declare function openPaseoClient(target: PaseoDaemonTarget, credential?: PaseoCredential, timeoutMs?: number): Promise<PaseoClient>;