@astrosheep/square 0.3.62 → 0.3.64

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

@@ -0,0 +1,122 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_TIMEOUT_MS } from './deadline.js';
+import { isIdentity } from './guards.js';
+const DEFAULT_HOST = '127.0.0.1:6767';
+/** The daemon writes a 32-byte base64url local credential; anything else is not one. */
+const LOCAL_CREDENTIAL = /^[A-Za-z0-9_-]{43}$/;
+let clientSequence = 0;
+function expandHome(value) {
+    return value === '~' ? homedir() : value.startsWith('~/') ? join(homedir(), value.slice(2)) : value;
+}
+/** `~/` expansion plus the daemon's default home directory. */
+export function paseoHome(explicit, env = process.env) {
+    const fromEnv = env.PASEO_HOME;
+    const value = isIdentity(explicit) ? explicit.trim() : typeof fromEnv === 'string' ? fromEnv.trim() : '';
+    return value === '' ? join(homedir(), '.paseo') : expandHome(value);
+}
+/** The daemon spellings the Paseo CLI accepts: IPC URIs, named pipes, socket paths, ports and `host:port`. */
+function normalizedHost(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return undefined;
+    const value = raw.trim();
+    if (value.startsWith('unix://') || value.startsWith('pipe://') || value.startsWith('tcp://'))
+        return value;
+    if (value.startsWith('\\\\.\\pipe\\'))
+        return `pipe://${value}`;
+    if (value.startsWith('/') || value.startsWith('~/'))
+        return `unix://${expandHome(value)}`;
+    if (/^\d+$/.test(value))
+        return `127.0.0.1:${value}`;
+    return value.includes(':') ? value : undefined;
+}
+/** One resolution for every Paseo caller. Never starts or stops anything. */
+export function resolvePaseoDaemon(endpoint, env = process.env, home = paseoHome(undefined, env)) {
+    // The caller's own endpoint wins; only an absent one falls through to `PASEO_HOST`
+    // and then to the daemon's own state files.
+    let host = endpoint !== undefined ? normalizedHost(endpoint) : normalizedHost(env.PASEO_HOST);
+    if (endpoint === undefined && host === undefined) {
+        for (const file of ['paseo.pid', 'config.json']) {
+            try {
+                const state = JSON.parse(readFileSync(join(home, file), 'utf8'));
+                host = normalizedHost(state.daemon?.listen ?? state.listen ?? state.sockPath);
+                if (host !== undefined)
+                    break;
+            }
+            catch { /* absent or unreadable */ }
+        }
+        host ??= DEFAULT_HOST;
+    }
+    if (host === undefined)
+        return undefined;
+    if (host.startsWith('unix://') || host.startsWith('pipe://')) {
+        const unix = host.startsWith('unix://');
+        if (unix && process.platform === 'win32')
+            return undefined;
+        const socketPath = expandHome(host.slice(unix ? 'unix://'.length : 'pipe://'.length).trim());
+        if (socketPath === '')
+            return undefined;
+        return { url: unix ? `ws+unix://${socketPath}:/ws` : 'ws://localhost/ws', socketPath };
+    }
+    if (host.startsWith('tcp://')) {
+        let uri;
+        try {
+            uri = new URL(host);
+        }
+        catch {
+            return undefined;
+        }
+        const name = uri.hostname.replace(/^\[|\]$/g, '');
+        if (name === '')
+            return undefined;
+        const address = `${name.includes(':') ? `[${name}]` : name}:${uri.port || '6767'}`;
+        const password = uri.searchParams.get('password');
+        return {
+            url: `${uri.searchParams.get('ssl') === 'true' ? 'wss' : 'ws'}://${address}/ws`,
+            ...(password === null || password === '' ? {} : { password }),
+        };
+    }
+    return { url: `ws://${host.replace(/\/$/, '')}/ws` };
+}
+/** Explicit credential first, then the endpoint's own password, then the daemon's local credential, then `PASEO_PASSWORD`. */
+export function daemonCredential(options, env = process.env, home = paseoHome(undefined, env)) {
+    if (isIdentity(options.authHeader))
+        return { authHeader: options.authHeader };
+    if (isIdentity(options.password))
+        return { password: options.password };
+    if (isIdentity(options.localCredential))
+        return { localCredential: () => options.localCredential };
+    if (isIdentity(options.endpointPassword))
+        return { password: options.endpointPassword };
+    try {
+        const token = readFileSync(join(home, 'local-credential'), 'utf8').trim();
+        if (LOCAL_CREDENTIAL.test(token))
+            return { localCredential: () => token };
+    }
+    catch { /* no readable local credential is not an error */ }
+    const password = env.PASEO_PASSWORD;
+    return isIdentity(password) ? { password: password.trim() } : {};
+}
+/**
+ * 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 async function openPaseoClient(target, credential = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const sdk = await import('@getpaseo/client/internal/daemon-client');
+    const { default: WebSocket } = await import('ws');
+    return new sdk.DaemonClient({
+        url: target.url,
+        clientId: `agent-delivery-${process.pid}-${Date.now()}-${++clientSequence}`,
+        clientType: 'cli',
+        appVersion: 'agent-delivery',
+        ...credential,
+        connectTimeoutMs: timeoutMs,
+        reconnect: { enabled: false },
+        // `ws` carries the daemon's auth headers and, for IPC targets, its socket path.
+        webSocketFactory: (url, options) => new WebSocket(url, options?.protocols, {
+            headers: options?.headers,
+            ...(target.socketPath === undefined ? {} : { socketPath: target.socketPath }),
+        }),
+    });
+}

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

@@ -0,0 +1,19 @@
+import type { PaseoDeliveryResult, PaseoSendTextOptions, PaseoTarget } from './types.js';
+export interface PaseoConnectExistingOptions {
+    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;
+}
+/** Connect to an existing daemon and address one existing agent. Never starts or stops anything. */
+export declare function connectPaseo(options: PaseoConnectExistingOptions): Promise<PaseoTarget>;
+/**
+ * Every call owns its daemon connection: one for connect to prove the endpoint
+ * and credential, and one per send, closed again as soon as the daemon answers.
+ */
+export declare function sendPaseoText(target: PaseoTarget, text: string, options?: PaseoSendTextOptions): Promise<PaseoDeliveryResult>;

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

@@ -0,0 +1,106 @@
+import { randomUUID } from 'node:crypto';
+import { deadline, validSignal, validTimeout } from './deadline.js';
+import { ConnectionError } from './errors.js';
+import { isIdentity, isRecord } from './guards.js';
+import { daemonCredential, openPaseoClient, paseoHome, resolvePaseoDaemon, } from './paseo-native.js';
+const connections = new WeakMap();
+/** Connect to an existing daemon and address one existing agent. Never starts or stops anything. */
+export async function connectPaseo(options) {
+    if (!isRecord(options) || options.harness !== 'paseo' || !isIdentity(options.agentId) ||
+        !validTimeout(options.timeoutMs) || !validSignal(options.signal) ||
+        (options.endpoint !== undefined && !isIdentity(options.endpoint)) ||
+        (options.password !== undefined && !isIdentity(options.password)) ||
+        (options.authHeader !== undefined && !isIdentity(options.authHeader)) ||
+        (options.localCredential !== undefined && !isIdentity(options.localCredential)) ||
+        (options.paseoHome !== undefined && !isIdentity(options.paseoHome))) {
+        throw new ConnectionError('invalid_arguments');
+    }
+    const home = paseoHome(options.paseoHome);
+    const target = resolvePaseoDaemon(options.endpoint, process.env, home);
+    if (target === undefined)
+        throw new ConnectionError('invalid_arguments');
+    const credential = daemonCredential({ ...options, endpointPassword: target.password }, process.env, home);
+    const scope = deadline(options.timeoutMs, options.signal);
+    let client;
+    try {
+        client = await openPaseoClient(target, credential, options.timeoutMs);
+    }
+    catch {
+        throw new ConnectionError('service_unavailable');
+    }
+    try {
+        scope.check();
+        await scope.wait(client.connect());
+        scope.check();
+    }
+    catch (error) {
+        if (scope.code !== undefined)
+            throw new ConnectionError(scope.code);
+        if (error instanceof Error && error.name === 'DaemonAuthenticationError')
+            throw new ConnectionError('authentication_failed');
+        throw new ConnectionError('service_unavailable');
+    }
+    finally {
+        scope.close();
+        // A connected client owns a socket and a heartbeat timer. Nothing outlives
+        // this call, so a caller's process is free to exit the moment it is done.
+        await client.close().catch(() => { });
+    }
+    const addressed = Object.freeze({ harness: 'paseo', agentId: options.agentId });
+    connections.set(addressed, { target, credential });
+    return addressed;
+}
+/**
+ * Every call owns its daemon connection: one for connect to prove the endpoint
+ * and credential, and one per send, closed again as soon as the daemon answers.
+ */
+export async function sendPaseoText(target, text, options = {}) {
+    const connection = connections.get(target);
+    if (connection === undefined || typeof text !== 'string' || text.length === 0 ||
+        !validTimeout(options.timeoutMs) || !validSignal(options.signal) ||
+        (options.inputId !== undefined && !isIdentity(options.inputId)) ||
+        (options.delivery !== undefined && options.delivery !== 'steer')) {
+        throw new TypeError('Invalid sendText arguments.');
+    }
+    const inputId = options.inputId ?? randomUUID();
+    const attempt = { harness: 'paseo', agentId: target.agentId, inputId };
+    const scope = deadline(options.timeoutMs, options.signal);
+    const client = await openPaseoClient(connection.target, connection.credential, options.timeoutMs);
+    // The connection is the uncertainty boundary: before it, nothing was written.
+    let connected = false;
+    try {
+        scope.check();
+        await scope.wait(client.connect());
+        connected = true;
+        scope.check();
+        await scope.wait(client.sendAgentMessage(target.agentId, text, { messageId: inputId, activeTurnBehavior: 'steer' }));
+        return { ...attempt, state: 'admitted' };
+    }
+    catch (error) {
+        if (scope.code !== undefined) {
+            return { ...attempt, state: connected ? 'unknown' : 'unavailable', code: scope.code };
+        }
+        if (error instanceof Error && error.name === 'DaemonAuthenticationError') {
+            return { ...attempt, state: 'unavailable', code: 'authentication_failed' };
+        }
+        // Only a connection that completed can carry the daemon's own answer.
+        if (!connected)
+            return { ...attempt, state: 'unavailable', code: 'transport' };
+        if (error instanceof Error) {
+            // A receipt still `pending` means an earlier attempt may have landed.
+            if (error.message.includes('agent_request_outcome_unknown')) {
+                return { ...attempt, state: 'unknown', code: 'transport' };
+            }
+            if (error.name === 'Error') {
+                const refusal = error.message.includes('agent_request_key_conflict') ? 'key_conflict'
+                    : /not found/i.test(error.message) ? 'not_found' : 'refused';
+                return { ...attempt, state: 'rejected', code: refusal };
+            }
+        }
+        return { ...attempt, state: 'unknown', code: 'transport' };
+    }
+    finally {
+        scope.close();
+        await client.close().catch(() => { });
+    }
+}

package/dist/packages/agent-delivery/src/pi-client.d.ts

@@ -0,0 +1,10 @@
+import type { PiDeliveryResult, PiSendTextOptions, PiTarget } from './types.js';
+export interface PiConnectExistingOptions {
+    readonly harness: 'pi';
+    readonly sessionId: string;
+    readonly endpoint: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export declare function connectPi(options: PiConnectExistingOptions): Promise<PiTarget>;
+export declare function sendPiText(target: PiTarget, text: string, options?: PiSendTextOptions): Promise<PiDeliveryResult>;

package/dist/packages/agent-delivery/src/pi-client.js

@@ -0,0 +1,106 @@
+import { randomUUID } from 'node:crypto';
+import { deadline, validSignal } from './deadline.js';
+import { ConnectionError } from './errors.js';
+import { connectLocal, LocalEndpointError, parseLocalEndpoint } from './local-endpoint.js';
+import { MAX_TEXT_BYTES, VERSION, frame, identity, readFrame, record, waitValid } from './pi-protocol.js';
+const endpoints = new WeakMap();
+const timeoutValid = (value) => value === undefined || waitValid(value);
+/** One socket/one request. No automatic retry. Write attempt is the uncertainty boundary. */
+async function request(endpoint, body, timeoutMs, signal) {
+    const scope = deadline(timeoutMs, signal);
+    let dispatched = false;
+    let socket;
+    let detach;
+    try {
+        scope.check();
+        const bytes = frame(body);
+        socket = await connectLocal(endpoint, { signal: scope.signal, timeoutMs });
+        scope.check();
+        // Conservative: an attempted write can have reached the native receiver even on later error.
+        dispatched = true;
+        const response = await scope.wait(new Promise((resolve, reject) => {
+            socket.on('error', () => reject(new Error()));
+            socket.on('close', () => reject(new Error()));
+            detach = readFrame(socket, resolve, () => reject(new ConnectionError('invalid_response')));
+            socket.write(bytes, (error) => { if (error)
+                reject(new Error()); });
+        }));
+        return { response, dispatched };
+    }
+    catch (error) {
+        const local = error instanceof LocalEndpointError ? error : undefined;
+        // A failed local connect is Pi's transport failure: nothing reached the receiver.
+        const localCode = local === undefined || local.code === 'unavailable' ? undefined : local.code;
+        const code = scope.code ?? localCode ??
+            (error instanceof ConnectionError ? 'invalid_response' : 'transport');
+        return { dispatched, code };
+    }
+    finally {
+        detach?.();
+        socket?.destroy();
+        scope.close();
+    }
+}
+export async function connectPi(options) {
+    if (!record(options) || options.harness !== 'pi' || !identity(options.sessionId) ||
+        typeof options.endpoint !== 'string' || !timeoutValid(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')
+        throw new ConnectionError('unsupported_platform');
+    if (endpoint.kind !== 'unix')
+        throw new ConnectionError('invalid_arguments');
+    const answer = await request(endpoint, { protocol: VERSION, harness: 'pi', op: 'hello', sessionId: options.sessionId }, options.timeoutMs, options.signal);
+    if (answer.code !== undefined)
+        throw new ConnectionError(answer.code === 'transport' ? 'service_unavailable' : answer.code);
+    const value = answer.response;
+    if (record(value) && value.protocol === VERSION && value.state === 'rejected' && value.code === 'wrong_session') {
+        throw new ConnectionError('session_not_found');
+    }
+    if (!record(value) || value.protocol !== VERSION || value.harness !== 'pi' || value.sessionId !== options.sessionId) {
+        throw new ConnectionError('invalid_response');
+    }
+    const target = Object.freeze({ harness: 'pi', sessionId: options.sessionId });
+    endpoints.set(target, endpoint);
+    return target;
+}
+export async function sendPiText(target, text, options = {}) {
+    if (!record(target) || !endpoints.has(target) || typeof text !== 'string' || text.length === 0 ||
+        Buffer.byteLength(text) > MAX_TEXT_BYTES || !record(options) || !timeoutValid(options.timeoutMs) ||
+        !validSignal(options.signal) || options.inputId !== undefined ||
+        (options.delivery !== undefined && options.delivery !== 'steer' && options.delivery !== 'queue')) {
+        throw new TypeError('Invalid sendText arguments.');
+    }
+    const inputId = randomUUID();
+    const delivery = options.delivery ?? 'steer';
+    const attempt = { harness: 'pi', sessionId: target.sessionId, inputId };
+    const body = { protocol: VERSION, harness: 'pi', op: 'send',
+        sessionId: target.sessionId, inputId, text, delivery, timeoutMs: options.timeoutMs ?? 5_000 };
+    frame(body); // Reject excessive JSON escaping before opening any socket.
+    const answer = await request(endpoints.get(target), body, options.timeoutMs, options.signal);
+    if (answer.code !== undefined) {
+        return { ...attempt, state: answer.dispatched ? 'unknown' : 'unavailable', code: answer.code };
+    }
+    const value = answer.response;
+    if (record(value) && value.protocol === VERSION) {
+        if (value.state === 'rejected' && ['wrong_session', 'invalid_request', 'duplicate_inflight_id'].includes(value.code)) {
+            return { ...attempt, state: 'rejected', code: value.code };
+        }
+        if (value.harness === 'pi' && value.sessionId === target.sessionId && value.inputId === inputId && value.delivery === delivery) {
+            if (value.state === 'observed' && value.evidence === 'message_end') {
+                return { ...attempt, state: 'observed', evidence: 'message_end', delivery };
+            }
+            if (value.state === 'unknown' && ['timeout', 'transport', 'session_replaced', 'native_call'].includes(value.code)) {
+                return { ...attempt, state: 'unknown', code: value.code };
+            }
+        }
+    }
+    return { ...attempt, state: 'unknown', code: 'invalid_response' };
+}

package/dist/packages/agent-delivery/src/pi-protocol.d.ts

@@ -0,0 +1,15 @@
+import type { Socket } from 'node:net';
+export declare const VERSION = "agent-delivery/pi/1";
+export declare const MAX_FRAME_BYTES: number;
+export declare const MAX_TEXT_BYTES: number;
+export declare const MAX_WAIT_MS = 30000;
+export declare const FRAME_WAIT_MS = 5000;
+export declare const MAX_CONNECTIONS = 64;
+export declare const CUSTOM_TYPE = "agent-delivery";
+export declare const record: (value: unknown) => value is Record<string, unknown>;
+export declare const identity: (value: unknown) => value is string;
+export declare const endpointValid: (value: unknown) => value is string;
+export declare const waitValid: (value: unknown) => value is number;
+/** One bounded UTF-8 JSON object terminated only by LF, never Unicode separators. */
+export declare function readFrame(socket: Socket, receive: (value: unknown) => void, invalid: () => void): () => void;
+export declare function frame(value: unknown): Buffer;

package/dist/packages/agent-delivery/src/pi-protocol.js

@@ -0,0 +1,50 @@
+import { isAbsolute } from 'node:path';
+export const VERSION = 'agent-delivery/pi/1';
+export const MAX_FRAME_BYTES = 256 * 1024;
+export const MAX_TEXT_BYTES = 128 * 1024;
+export const MAX_WAIT_MS = 30_000;
+export const FRAME_WAIT_MS = 5_000;
+export const MAX_CONNECTIONS = 64;
+export const CUSTOM_TYPE = 'agent-delivery';
+export const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export const identity = (value) => typeof value === 'string' && value.trim().length > 0 && value.length <= 256;
+export const endpointValid = (value) => typeof value === 'string' && isAbsolute(value) && !value.includes('\0') && Buffer.byteLength(value) <= 103;
+export const waitValid = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0 && value <= MAX_WAIT_MS;
+/** One bounded UTF-8 JSON object terminated only by LF, never Unicode separators. */
+export function readFrame(socket, receive, invalid) {
+    let chunks = [];
+    let size = 0;
+    const onData = (chunk) => {
+        size += chunk.length;
+        if (size > MAX_FRAME_BYTES) {
+            stop();
+            invalid();
+            return;
+        }
+        const newline = chunk.indexOf(10);
+        chunks.push(newline < 0 ? chunk : chunk.subarray(0, newline));
+        if (newline < 0)
+            return;
+        stop();
+        try {
+            if (newline !== chunk.length - 1)
+                throw new Error();
+            const bytes = Buffer.concat(chunks);
+            const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            receive(JSON.parse(text));
+        }
+        catch {
+            invalid();
+        }
+        chunks = [];
+    };
+    const stop = () => socket.off('data', onData);
+    socket.on('data', onData);
+    return stop;
+}
+export function frame(value) {
+    const bytes = Buffer.from(JSON.stringify(value) + '\n');
+    if (bytes.length > MAX_FRAME_BYTES)
+        throw new TypeError('Pi request is too large.');
+    return bytes;
+}

package/dist/packages/agent-delivery/src/pi-send.d.ts

@@ -0,0 +1,23 @@
+/** SDK-free structural subset of Pi's custom message and native options. */
+export interface PiMessage<T = unknown> {
+    customType: string;
+    content: string | ({
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image';
+        data: string;
+        mimeType: string;
+    })[];
+    display: boolean;
+    details?: T;
+}
+export interface PiSendOptions {
+    deliverAs?: 'steer' | 'followUp' | 'nextTurn';
+    triggerTurn?: boolean;
+}
+export interface PiSender {
+    sendMessage<T = unknown>(message: PiMessage<T>, options?: PiSendOptions): void;
+}
+/** One stateless invocation. Void is not admission or observable async failure. */
+export declare function sendPiMessage<T>(pi: PiSender, message: PiMessage<T>, options?: PiSendOptions): void;

package/dist/packages/agent-delivery/src/pi-send.js

@@ -0,0 +1,4 @@
+/** One stateless invocation. Void is not admission or observable async failure. */
+export function sendPiMessage(pi, message, options) {
+    pi.sendMessage(message, options);
+}

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

@@ -0,0 +1,25 @@
+import { type PiSender } from './pi-send.js';
+export { sendPiMessage } from './pi-send.js';
+export type { PiMessage, PiSender, PiSendOptions } from './pi-send.js';
+interface PiContext {
+    sessionManager: {
+        getSessionId(): string;
+    };
+}
+export interface PiReceiverAPI extends PiSender {
+    on(event: 'session_start', handler: (event: unknown, ctx: PiContext) => Promise<void>): unknown;
+    on(event: 'session_shutdown', handler: () => Promise<void>): unknown;
+    on(event: 'message_end', handler: (event: {
+        message: unknown;
+    }, ctx: PiContext) => void): unknown;
+}
+export interface PiReceiverOptions {
+    readonly endpoint?: string;
+}
+/**
+ * Resources start only on session_start. Missing endpoint leaves the extension inert.
+ * SDK hosts that dispose without session_shutdown must explicitly close this receiver.
+ */
+export declare function createPiReceiver(pi: PiReceiverAPI, options?: PiReceiverOptions): {
+    close(): Promise<void>;
+};