@astrosheep/square 0.3.5 → 0.3.7

package/dist/notifications.js

@@ -2,56 +2,40 @@ import { spawn } from 'node:child_process';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 import { loadSquare } from './artifact.js';
-import { SquareError } from './model.js';
+import { isDeliveryDelivered, isPendingNotification, planActNotifications, } from './delivery.js';
+import { recordNotificationFailure } from './notification-failures.js';
 import { hasPresentedAttention } from './presented.js';
-import { SLEEP_MS, isDeliveryDelivered, resolveRosterName, rosterNames, } from './runtime.js';
-import { planActNotifications } from './delivery.js';
-import { defaultWakeSinks, } from './wake-sink.js';
-export { planActNotifications } from './delivery.js';
-export { matchesMentionTarget } from './runtime.js';
-function parsePositiveIntegerEnv(name, fallback) {
-    const raw = process.env[name];
-    if (raw === undefined)
-        return fallback;
-    const value = Number.parseInt(raw, 10);
-    if (!Number.isFinite(value) || value <= 0) {
-        throw new SquareError('invalid_args', `Invalid ${name}: expected a positive integer.`);
-    }
-    return value;
-}
-function resolveKnownParticipant(doc, name) {
-    const known = resolveRosterName(doc, name);
-    if (known === undefined) {
+import { SquareError } from './model.js';
+import { SLEEP_MS, matchesMentionTarget, resolveRosterName, rosterNames } from './runtime.js';
+import { defaultWakeSinks } from './paseo-delivery.js';
+export { planActNotifications, matchesMentionTarget };
+function known(doc, name) {
+    const value = resolveRosterName(doc, name);
+    if (value === undefined)
         throw new SquareError('invalid_args', `Unknown participant "${name}". Expected one of: ${rosterNames(doc).join(', ')}.`);
-    }
-    return known;
+    return value;
 }
+export { notificationMessageId } from './delivery.js';
 export function notificationDeliveryWaitMs() {
-    return parsePositiveIntegerEnv('SQUARE_NOTIFY_DELIVERY_WAIT_MS', 5000);
+    const value = Number.parseInt(process.env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? '5000', 10);
+    if (!Number.isFinite(value) || value <= 0)
+        throw new SquareError('invalid_args', 'Invalid SQUARE_NOTIFY_DELIVERY_WAIT_MS: expected a positive integer.');
+    return value;
 }
-export function hasDeliveredMention(squarePath, name, ref) {
+export function hasDeliveredNotification(squarePath, name, ref) {
     const doc = loadSquare(squarePath);
-    const known = resolveKnownParticipant(doc, name);
-    const index = typeof ref === 'number' ? ref : Number(ref.slice(4));
-    return isDeliveryDelivered(doc, known, index);
+    return isDeliveryDelivered(doc, known(doc, name), typeof ref === 'number' ? ref : Number(ref.slice(4)));
 }
-/**
- * Duplicate-wake suppression only. Delivery remains pending until the canonical
- * recipient/act receipt is delivered; presented is a machine-local cache.
- */
-export function hasAttentionMention(squarePath, name, ref, env = process.env) {
+export function hasAttentionNotification(squarePath, name, ref, env = process.env) {
     const doc = loadSquare(squarePath);
-    const known = resolveKnownParticipant(doc, name);
+    const recipient = known(doc, name);
     const index = typeof ref === 'number' ? ref : Number(ref.slice(4));
-    if (isDeliveryDelivered(doc, known, index))
-        return true;
-    return hasPresentedAttention(squarePath, known, index, env);
+    return isDeliveryDelivered(doc, recipient, index) || hasPresentedAttention(squarePath, recipient, index, env);
 }
-export async function waitForDeliveredMention(squarePath, name, ref, opts = {}) {
-    const timeoutMs = opts.timeoutMs ?? 30000;
-    const deadline = Date.now() + timeoutMs;
+export async function waitForDeliveredNotification(squarePath, name, ref, opts = {}) {
+    const deadline = Date.now() + (opts.timeoutMs ?? 30000);
     while (Date.now() <= deadline) {
-        if (hasDeliveredMention(squarePath, name, ref))
+        if (hasDeliveredNotification(squarePath, name, ref))
             return true;
         await sleep(Math.min(SLEEP_MS, Math.max(1, deadline - Date.now())));
     }
@@ -59,39 +43,40 @@ export async function waitForDeliveredMention(squarePath, name, ref, opts = {})
 }
 export async function processActNotificationsOnce(squarePath, actIndex, opts = {}) {
     const doc = loadSquare(squarePath);
-    const act = doc.acts.find((candidate) => candidate.index === actIndex);
-    if (!act)
-        return;
-    const item = { act, index: actIndex };
-    const notifications = planActNotifications(doc, item).filter((notification) => notification.via === 'mention' || notification.via === 'bell');
-    const sinks = opts.sinks ?? defaultWakeSinks();
-    if (sinks.length === 0)
+    const item = doc.acts.find((candidate) => candidate.index === actIndex);
+    if (item === undefined)
         return;
+    const notifications = planActNotifications(doc, item).filter(isPendingNotification);
     for (const notification of notifications) {
-        // Presented only avoids duplicate wake text. It does not affect delivery state.
-        if (hasAttentionMention(squarePath, notification.recipient, actIndex))
+        if (hasAttentionNotification(squarePath, notification.recipient, notification.item.index))
             continue;
-        for (const sink of sinks) {
-            await sink.dispatch(notification, { squarePath });
+        for (const sink of opts.sinks ?? defaultWakeSinks()) {
+            try {
+                await sink.dispatch(notification, { squarePath });
+            }
+            catch (error) {
+                recordNotificationFailure(squarePath, {
+                    actIndex: notification.item.index,
+                    recipient: notification.recipient,
+                    route: notification.route,
+                    sink: sink.name,
+                    message: error instanceof Error ? error.message : String(error),
+                    ...(error instanceof Error && 'diagnostic' in error ? { diagnostic: error.diagnostic } : {}),
+                });
+            }
         }
     }
 }
-function launchDetachedWorker(workerPath, args) {
-    const child = spawn(process.execPath, [workerPath, ...args], {
-        detached: true,
-        stdio: 'ignore',
-        env: process.env,
-    });
+function launchWorker(workerPath, args) {
+    const child = spawn(process.execPath, [workerPath, ...args], { detached: true, stdio: 'ignore', env: process.env });
     child.unref();
 }
+/** Start one detached worker only when this act contains directed attention. */
 export async function dispatchActNotifications(squarePath, item, opts = {}) {
-    if (process.env['SQUARE_DISABLE_PASEO_WAKE'] === '1')
+    if (process.env.SQUARE_DISABLE_PASEO_WAKE === '1')
         return;
     const doc = loadSquare(squarePath);
-    const notifications = planActNotifications(doc, item).filter((notification) => notification.via === 'mention' || notification.via === 'bell');
-    if (notifications.length === 0)
+    if (!planActNotifications(doc, item).some(isPendingNotification))
         return;
-    const workerPath = fileURLToPath(new URL('./cmd/notify-once.js', import.meta.url));
-    const launch = opts.launchWorker ?? launchDetachedWorker;
-    launch(workerPath, ['--square-path', squarePath, '--act-index', String(item.index)]);
+    (opts.launchWorker ?? launchWorker)(fileURLToPath(new URL('./cmd/notify-once.js', import.meta.url)), ['--square-path', squarePath, '--act-index', String(item.index)]);
 }

package/dist/paseo-delivery.js

@@ -0,0 +1,160 @@
+import { homedir } from 'node:os';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { loadSquare } from './artifact.js';
+import { isDeliveryDelivered, leaseOwnsNotification, } from './delivery.js';
+import { sessionInbox } from './inbox.js';
+import { hasPresentedForOwner, presentOnce } from './presented.js';
+import { lookupParticipant } from './registry.js';
+import { quoteShell } from './presentation.js';
+import { isCurrentlyJoined, resolveRosterName } from './runtime.js';
+import { discoverPaseoAgents, waitForPaseoWakeBoundary, } from './paseo-state.js';
+import { sendPaseoWake } from './wake-sink.js';
+export class PaseoWakeError extends Error {
+    diagnostic;
+    constructor(message, diagnostic) {
+        super(message);
+        this.diagnostic = diagnostic;
+        this.name = 'PaseoWakeError';
+    }
+}
+function endpoint() {
+    return process.env.SQUARE_PASEO_WS_URL ?? process.env.PASEO_LISTEN ?? '127.0.0.1:6767';
+}
+function diagnostic(phase, ownership, code) {
+    return {
+        phase,
+        code,
+        command: phase === 'discovery' ? 'paseo ls --json' : 'paseo send <agent-id> --prompt <prompt> --no-wait',
+        endpoint: endpoint(),
+        paseoAgentIds: ownership.map((item) => item.agentId),
+        ownerIds: [...new Set(ownership.map((item) => item.ownerId))],
+        passwordPresent: Boolean(process.env.PASEO_PASSWORD),
+    };
+}
+function native(binding) {
+    return ['claude-code', 'codex', 'opencode', 'pi'].includes(binding.channel);
+}
+function ownershipSnapshot(bindings) {
+    const out = new Map();
+    for (const binding of bindings) {
+        if (!binding.paseoAgentId)
+            continue;
+        const owner = bindings.filter((item) => item.ownerId === binding.ownerId);
+        out.set(`${binding.ownerId}\0${binding.paseoAgentId}`, {
+            agentId: binding.paseoAgentId,
+            ownerId: binding.ownerId,
+            sessionId: owner.find(native)?.sessionId ?? binding.sessionId,
+            nativeGuarantee: owner.some(native),
+        });
+    }
+    return [...out.values()];
+}
+function selectActiveAgents(ownership, agents) {
+    const ids = new Set(ownership.map((item) => item.agentId));
+    return agents.filter((agent) => ids.has(agent.id) && (agent.status === 'idle' || agent.status === 'running'));
+}
+function catchCommand(squarePath, recipient) {
+    return `square --as ${quoteShell(recipient)} --square-path ${quoteShell(squarePath)} catch --now`;
+}
+function prompt(notification, squarePath, nativeWake) {
+    const display = squarePath.startsWith(homedir()) ? `~${squarePath.slice(homedir().length)}` : squarePath;
+    const body = notification.item.body.length > 200 ? `${notification.item.body.slice(0, 197)}...` : notification.item.body;
+    return [
+        '<system-reminder source="square">',
+        `${notification.route === 'bell' ? 'Bell' : notification.route === 'beside' ? 'Beside' : 'Mention'} from @${notification.item.actor} in \`${display}\``,
+        nativeWake ? 'The native adapter will present it at the next boundary.' : `> ${body.replace(/\n/g, '\n> ')}`,
+        `\`${catchCommand(squarePath, notification.recipient)}\``,
+        '</system-reminder>',
+    ].join('\n');
+}
+async function waitForCatch(squarePath, recipient, actIndex, ownerId) {
+    const deadline = Date.now() + 180_000;
+    while (Date.now() < deadline) {
+        const doc = loadSquare(squarePath);
+        if (isDeliveryDelivered(doc, recipient, actIndex))
+            return true;
+        const binding = lookupParticipant(squarePath, recipient).find((item) => item.ownerId === ownerId);
+        const lease = binding && sessionInbox(binding.sessionId).find((item) => item.name === recipient)?.catchLease;
+        if (!lease || lease.expiresAt <= Date.now())
+            return false;
+        await sleep(Math.min(250, lease.expiresAt - Date.now()));
+    }
+    return false;
+}
+function send(request, ownership) {
+    try {
+        sendPaseoWake(request);
+    }
+    catch (error) {
+        throw new PaseoWakeError(error instanceof Error ? error.message : String(error), diagnostic('send', ownership, 'failed'));
+    }
+}
+export async function dispatchPaseoNotification(notification, ctx) {
+    const initial = loadSquare(ctx.squarePath);
+    const recipient = resolveRosterName(initial, notification.recipient);
+    if (!recipient || !isCurrentlyJoined(initial.acts, recipient))
+        return;
+    const ownership = ownershipSnapshot(lookupParticipant(ctx.squarePath, recipient));
+    if (ownership.length === 0)
+        return;
+    const discovery = discoverPaseoAgents();
+    if (discovery.error && discovery.agents.length === 0) {
+        throw new PaseoWakeError(`Paseo unavailable: ${discovery.error}`, diagnostic('discovery', ownership, 'unavailable'));
+    }
+    const active = selectActiveAgents(ownership, discovery.agents);
+    if (active.length === 0) {
+        throw new PaseoWakeError('No registered Paseo agent is idle or running.', diagnostic('selection', ownership, 'not_active'));
+    }
+    let boundaryTimedOut = false;
+    for (const agent of active) {
+        const owner = ownership.find((item) => item.agentId === agent.id);
+        if (!owner || hasPresentedForOwner(owner.ownerId, ctx.squarePath, recipient, notification.item.index))
+            continue;
+        if (!(await waitForPaseoWakeBoundary(agent))) {
+            boundaryTimedOut = true;
+            continue;
+        }
+        const latest = loadSquare(ctx.squarePath);
+        if (!isCurrentlyJoined(latest.acts, recipient) || isDeliveryDelivered(latest, recipient, notification.item.index))
+            return;
+        const current = lookupParticipant(ctx.squarePath, recipient).find((item) => item.ownerId === owner.ownerId && item.paseoAgentId === owner.agentId);
+        if (!current)
+            continue;
+        const activeCatch = sessionInbox(current.sessionId).find((item) => item.name === recipient)?.catchLease;
+        if (activeCatch &&
+            leaseOwnsNotification(activeCatch, {
+                actor: notification.item.actor,
+                body: notification.item.body,
+                route: notification.route,
+                recipient,
+            }) &&
+            (await waitForCatch(ctx.squarePath, recipient, notification.item.index, owner.ownerId))) {
+            return;
+        }
+        const nativeWake = owner.nativeGuarantee;
+        const request = {
+            agentId: agent.id,
+            prompt: prompt({ ...notification, recipient }, ctx.squarePath, nativeWake),
+        };
+        if (nativeWake) {
+            send(request, ownership);
+            return;
+        }
+        presentOnce(current.sessionId, (id) => sessionInbox(id)
+            .map((item) => ({ ...item, notifications: item.notifications.filter((note) => note.actIndex === notification.item.index) }))
+            .filter((item) => item.notifications.length > 0), () => {
+            send(request, ownership);
+            return true;
+        });
+        return;
+    }
+    if (boundaryTimedOut) {
+        throw new PaseoWakeError('Paseo did not reach the current tool boundary before the wake timeout.', diagnostic('boundary', ownership, 'timeout'));
+    }
+}
+export function paseoWakeSink() {
+    return { name: 'paseo', dispatch: dispatchPaseoNotification };
+}
+export function defaultWakeSinks() {
+    return process.env.SQUARE_DISABLE_PASEO_WAKE === '1' ? [] : [paseoWakeSink()];
+}

package/dist/paseo-state.js

@@ -0,0 +1,31 @@
+import { execFileSync } from 'node:child_process';
+import { waitForPaseoToolBoundary } from './paseo-timeline.js';
+export function discoverPaseoAgents(timeoutMs = 5000) {
+    try {
+        const raw = execFileSync(process.env.SQUARE_PASEO_BIN || 'paseo', ['ls', '--json'], {
+            encoding: 'utf8',
+            timeout: timeoutMs,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const parsed = JSON.parse(raw);
+        const agents = Array.isArray(parsed) ? parsed : parsed?.agents;
+        if (!Array.isArray(agents))
+            return { agents: [], error: 'Paseo returned malformed agent inventory.' };
+        return {
+            agents: agents.filter((item) => item !== null &&
+                typeof item === 'object' &&
+                typeof item.id === 'string' &&
+                typeof item.status === 'string'),
+        };
+    }
+    catch (error) {
+        return { agents: [], error: error instanceof Error ? error.message : String(error) };
+    }
+}
+export async function waitForPaseoWakeBoundary(agent) {
+    if (agent.status === 'idle')
+        return true;
+    if (agent.status !== 'running')
+        return false;
+    return waitForPaseoToolBoundary(agent.id);
+}

package/dist/paseo-timeline.js

@@ -1,206 +1,76 @@
-import { randomUUID } from 'node:crypto';
 import { setTimeout as sleep } from 'node:timers/promises';
-const DEFAULT_POLL_INTERVAL_MS = 100;
-const DEFAULT_REQUEST_TIMEOUT_MS = 3000;
-function paseoWebSocketUrl() {
-    const override = process.env['SQUARE_PASEO_WS_URL']?.trim();
-    if (override)
-        return override;
-    const listen = process.env['PASEO_LISTEN']?.trim();
-    if (!listen)
-        return 'ws://127.0.0.1:6767/ws';
-    if (/^wss?:\/\//i.test(listen)) {
-        const url = new URL(listen);
-        if (url.pathname === '/' || url.pathname === '')
-            url.pathname = '/ws';
-        return url.toString();
-    }
-    if (/^tcp:\/\//i.test(listen)) {
-        const url = new URL(listen);
-        const secure = url.searchParams.get('ssl') === 'true';
-        url.protocol = secure ? 'wss:' : 'ws:';
-        url.pathname = '/ws';
-        return url.toString();
-    }
-    if (/^\d+$/.test(listen))
-        return `ws://127.0.0.1:${listen}/ws`;
-    return `ws://${listen.replace(/\/$/, '')}/ws`;
-}
-function parseSnapshot(payload) {
-    if (payload === null || typeof payload !== 'object') {
-        throw new Error('Invalid Paseo timeline response.');
-    }
-    const response = payload;
-    if (typeof response.error === 'string' && response.error) {
-        throw new Error(response.error);
-    }
-    const latestTools = new Map();
-    for (const entry of response.entries ?? []) {
-        const item = entry.item;
-        if (item?.['type'] !== 'tool_call' ||
-            typeof item['callId'] !== 'string' ||
-            (item['status'] !== 'running' && item['status'] !== 'completed' && item['status'] !== 'failed')) {
-            continue;
-        }
-        latestTools.set(item['callId'], item['status']);
-    }
-    return {
-        agentStatus: typeof response.agent?.status === 'string' ? response.agent.status : 'unknown',
-        toolCalls: Array.from(latestTools, ([callId, status]) => ({ callId, status })),
-    };
-}
-class PaseoTimelineProbe {
-    socket;
-    pending = new Map();
-    constructor(socket) {
-        this.socket = socket;
-        socket.addEventListener('message', (event) => {
-            let envelope;
-            try {
-                envelope = JSON.parse(String(event.data));
-            }
-            catch {
-                return;
-            }
-            if (envelope === null || typeof envelope !== 'object')
-                return;
-            const outer = envelope;
-            if (outer.type !== 'session' || outer.message === null || typeof outer.message !== 'object') {
-                return;
-            }
-            const message = outer.message;
-            if (message.type !== 'fetch_agent_timeline_response' ||
-                message.payload === null ||
-                typeof message.payload !== 'object') {
-                return;
-            }
-            const requestId = message.payload.requestId;
-            if (typeof requestId !== 'string')
-                return;
-            const request = this.pending.get(requestId);
-            if (!request)
-                return;
-            clearTimeout(request.timer);
-            this.pending.delete(requestId);
-            try {
-                request.resolve(parseSnapshot(message.payload));
-            }
-            catch (error) {
-                request.reject(error instanceof Error ? error : new Error(String(error)));
-            }
-        });
-        const rejectPending = () => {
-            for (const [requestId, request] of this.pending) {
-                clearTimeout(request.timer);
-                request.reject(new Error('Paseo timeline connection closed.'));
-                this.pending.delete(requestId);
-            }
-        };
-        socket.addEventListener('close', rejectPending);
-        socket.addEventListener('error', rejectPending);
-    }
-    static async connect(timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
-        const socket = new WebSocket(paseoWebSocketUrl());
-        await new Promise((resolvePromise, reject) => {
-            const timer = setTimeout(() => {
-                socket.close();
-                reject(new Error('Timed out connecting to Paseo.'));
-            }, timeoutMs);
-            socket.addEventListener('open', () => {
-                clearTimeout(timer);
-                resolvePromise();
-            }, { once: true });
-            socket.addEventListener('error', () => {
-                clearTimeout(timer);
-                reject(new Error('Could not connect to Paseo.'));
-            }, { once: true });
-        });
-        const probe = new PaseoTimelineProbe(socket);
-        socket.send(JSON.stringify({
-            type: 'hello',
-            clientId: `square-wake-${process.pid}-${randomUUID()}`,
-            clientType: 'cli',
-            protocolVersion: 1,
-        }));
-        return probe;
-    }
-    snapshot(agentId, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
-        const requestId = randomUUID();
-        return new Promise((resolvePromise, reject) => {
-            const timer = setTimeout(() => {
-                this.pending.delete(requestId);
-                reject(new Error('Timed out reading Paseo timeline.'));
-            }, timeoutMs);
-            this.pending.set(requestId, { resolve: resolvePromise, reject, timer });
-            this.socket.send(JSON.stringify({
-                type: 'session',
-                message: {
-                    type: 'fetch_agent_timeline_request',
-                    agentId,
-                    requestId,
-                    direction: 'tail',
-                    limit: 200,
-                    projection: 'projected',
-                },
-            }));
-        });
-    }
-    close() {
-        this.socket.close();
-    }
-}
-async function waitWithSnapshots(agentId, readSnapshot, options) {
-    const initial = await readSnapshot(agentId);
+async function waitSnapshots(agentId, read, opts) {
+    const initial = await read(agentId);
     if (initial.agentStatus === 'idle')
         return true;
     if (initial.agentStatus !== 'running')
         return false;
-    const currentCalls = new Set(initial.toolCalls.filter((tool) => tool.status === 'running').map((tool) => tool.callId));
-    if (currentCalls.size === 0)
+    const running = new Set(initial.toolCalls.filter((tool) => tool.status === 'running').map((tool) => tool.callId));
+    if (running.size === 0)
         return true;
-    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-    const delay = options.delay ?? ((ms) => sleep(ms));
-    const deadline = options.timeoutMs === undefined ? null : Date.now() + options.timeoutMs;
-    while (deadline === null || Date.now() < deadline) {
-        await delay(pollIntervalMs);
-        const snapshot = await readSnapshot(agentId);
-        if (snapshot.agentStatus === 'idle')
+    const delay = opts.delay ?? ((ms) => sleep(ms));
+    const interval = opts.pollIntervalMs ?? 100;
+    const deadline = Date.now() + (opts.timeoutMs ?? 30_000);
+    while (Date.now() < deadline) {
+        await delay(interval);
+        const current = await read(agentId);
+        if (current.agentStatus === 'idle')
             return true;
-        if (snapshot.agentStatus !== 'running')
+        if (current.agentStatus !== 'running')
             return false;
-        const latest = new Map(snapshot.toolCalls.map((tool) => [tool.callId, tool.status]));
-        const allTerminal = Array.from(currentCalls).every((callId) => {
-            const status = latest.get(callId);
-            return status === 'completed' || status === 'failed';
-        });
-        if (allTerminal)
+        const states = new Map(current.toolCalls.map((tool) => [tool.callId, tool.status]));
+        if ([...running].every((id) => states.get(id) === 'completed' || states.get(id) === 'failed'))
             return true;
     }
     return false;
 }
-/**
- * Wait until the tool calls that were running at the initial snapshot finish.
- * Tool calls that start later are intentionally ignored: the subsequent
- * `paseo send` may replace the next tool call under the transitional policy.
- */
-export async function waitForPaseoToolBoundary(agentId, options = {}) {
-    if (options.readSnapshot) {
-        try {
-            return await waitWithSnapshots(agentId, options.readSnapshot, options);
-        }
-        catch {
-            return false;
-        }
-    }
-    let probe = null;
+function paseoUrl() {
+    const value = process.env.SQUARE_PASEO_WS_URL?.trim() || process.env.PASEO_LISTEN?.trim();
+    if (!value)
+        return 'ws://127.0.0.1:6767/ws';
+    if (/^wss?:\/\//i.test(value))
+        return value.replace(/\/$/, '') + (value.endsWith('/ws') ? '' : '/ws');
+    if (/^\d+$/.test(value))
+        return `ws://127.0.0.1:${value}/ws`;
+    return `ws://${value.replace(/\/$/, '')}/ws`;
+}
+async function remoteSnapshot(agentId) {
+    const socket = new WebSocket(paseoUrl());
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { socket.close(); reject(new Error('Paseo timeline connection timed out.')); }, 3000);
+        socket.addEventListener('open', () => { clearTimeout(timer); resolve(); }, { once: true });
+        socket.addEventListener('error', () => { clearTimeout(timer); reject(new Error('Paseo timeline unavailable.')); }, { once: true });
+    });
+    return await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { socket.close(); reject(new Error('Paseo timeline request timed out.')); }, 3000);
+        const requestId = `${process.pid}-${Date.now()}`;
+        socket.addEventListener('message', (event) => {
+            try {
+                const outer = JSON.parse(String(event.data));
+                const payload = outer?.message?.payload;
+                if (outer?.message?.type !== 'fetch_agent_timeline_response' || payload?.requestId !== requestId)
+                    return;
+                clearTimeout(timer);
+                socket.close();
+                const tools = new Map();
+                for (const entry of payload.entries ?? []) {
+                    const item = entry?.item;
+                    if (item?.type === 'tool_call' && typeof item.callId === 'string' && ['running', 'completed', 'failed'].includes(item.status))
+                        tools.set(item.callId, item.status);
+                }
+                resolve({ agentStatus: typeof payload.agent?.status === 'string' ? payload.agent.status : 'unknown', toolCalls: [...tools].map(([callId, status]) => ({ callId, status })) });
+            }
+            catch { /* ignore unrelated frames */ }
+        });
+        socket.send(JSON.stringify({ type: 'hello', clientId: `square-${process.pid}`, clientType: 'cli', protocolVersion: 1 }));
+        socket.send(JSON.stringify({ type: 'session', message: { type: 'fetch_agent_timeline_request', agentId, requestId, direction: 'tail', limit: 200, projection: 'projected' } }));
+    });
+}
+export async function waitForPaseoToolBoundary(agentId, opts = {}) {
     try {
-        probe = await PaseoTimelineProbe.connect();
-        return await waitWithSnapshots(agentId, (id) => probe.snapshot(id), options);
+        return await waitSnapshots(agentId, opts.readSnapshot ?? remoteSnapshot, opts);
     }
     catch {
         return false;
     }
-    finally {
-        probe?.close();
-    }
 }