@astrosheep/square 0.3.5 → 0.3.6

package/dist/wake-sink.js

@@ -1,219 +1,165 @@
-/**
- * wake-sink.ts — shared paseo wake dispatch.
- *
- * This is the single canonical implementation of "wake a paseo agent
- * when they receive an undelivered @mention or --bell in a square."
- *
- * The detached one-shot notification worker uses this module after the
- * natural-delivery grace period. The WakeSink is stateless; the worker owns
- * receipt checks, timing, and failure isolation.
- */
-import { execSync, spawnSync } from 'node:child_process';
-import { setTimeout as sleep } from 'node:timers/promises';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { homedir } from 'node:os';
+import { setTimeout as sleep } from 'node:timers/promises';
 import { loadSquare } from './artifact.js';
-import { SquareError } from './model.js';
-import { leaseOwnsNotification } from './delivery.js';
+import { leaseOwnsNotification, isDeliveryDelivered } from './delivery.js';
 import { sessionInbox } from './inbox.js';
-import { waitForPaseoToolBoundary } from './paseo-timeline.js';
-import { hasPresentedAttention, presentOnce } from './presented.js';
+import { hasPresentedForOwner, presentOnce } from './presented.js';
 import { lookupParticipant } from './registry.js';
 import { quoteShell } from './presentation.js';
-import { isDeliveryDelivered, resolveRosterName } from './runtime.js';
-async function waitForCatchDelivery(squarePath, recipient, notification, ownerId) {
-    const deadline = Date.now() + 180_000;
-    while (Date.now() < deadline) {
-        const doc = loadSquare(squarePath);
-        const known = resolveRosterName(doc, recipient) ?? recipient;
-        if (isDeliveryDelivered(doc, known, notification.item.index))
-            return true;
-        const lease = lookupParticipant(squarePath, known).find((binding) => binding.ownerId === ownerId);
-        const activeLease = lease === undefined
-            ? undefined
-            : sessionInbox(lease.sessionId).find((membership) => membership.name === known)?.catchLease;
-        if (activeLease === undefined || activeLease.expiresAt <= Date.now())
-            return false;
-        await sleep(Math.min(250, Math.max(1, activeLease.expiresAt - Date.now())));
+import { isCurrentlyJoined, resolveRosterName } from './runtime.js';
+import { waitForPaseoToolBoundary } from './paseo-timeline.js';
+export class PaseoWakeError extends Error {
+    diagnostic;
+    constructor(message, diagnostic) {
+        super(message);
+        this.diagnostic = diagnostic;
+        this.name = 'PaseoWakeError';
     }
-    return false;
 }
-const DEFAULT_PASEO_WAKE_TIMEOUT_MS = 90_000;
-function paseoWakeTimeoutMs() {
-    const raw = process.env['SQUARE_PASEO_WAKE_TIMEOUT_MS'];
-    if (raw === undefined)
-        return DEFAULT_PASEO_WAKE_TIMEOUT_MS;
-    const value = Number.parseInt(raw, 10);
-    if (!Number.isFinite(value) || value <= 0) {
-        throw new SquareError('invalid_args', 'Invalid SQUARE_PASEO_WAKE_TIMEOUT_MS: expected a positive integer.');
-    }
-    return value;
+function endpoint() {
+    return process.env.SQUARE_PASEO_WS_URL ?? process.env.PASEO_LISTEN ?? '127.0.0.1:6767';
 }
-// ── helpers ──────────────────────────────────────────────────────
-function previewBody(body) {
-    return body.length > 200 ? body.slice(0, 197) + '...' : body;
+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 wakeNowCommand(squarePath, recipient) {
-    return `square --as ${quoteShell(recipient)} --square-path ${quoteShell(squarePath)} catch --now`;
+function native(binding) {
+    return ['claude-code', 'codex', 'opencode', 'pi'].includes(binding.channel);
 }
-function nativeWakePrompt(squarePath, recipient) {
-    return [
-        '<system-reminder source="square">',
-        `Square activity is waiting for @${recipient} in ${squarePath}.`,
-        'The native adapter will present it at the next boundary. If it does not:',
-        `\`${wakeNowCommand(squarePath, recipient)}\``,
-        '</system-reminder>',
-    ].join('\n');
+export function paseoOwnershipSnapshot(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 fullWakePrompt(notification, squarePath) {
-    const { item, recipient } = notification;
-    const home = homedir();
-    const displayPath = squarePath.startsWith(home) ? `~${squarePath.slice(home.length)}` : squarePath;
-    return [
-        '<system-reminder source="square">',
-        `Mentioned by @${item.act.actor} in \`${displayPath}\``,
-        '',
-        `> ${previewBody(item.act.body).replace(/\n/g, '\n> ')}`,
-        '',
-        'To catch up and keep presence current:',
-        `\`${wakeNowCommand(squarePath, recipient)}\``,
-        '',
-        '*(Async notification from Square.)*',
-        '</system-reminder>',
-    ].join('\n');
+export function selectPaseoWakeAgents(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 hasNativeGuarantee(bindings, ownerId) {
-    return bindings.some((binding) => binding.ownerId === ownerId &&
-        (binding.channel === 'claude-code' ||
-            binding.channel === 'codex' ||
-            binding.channel === 'opencode' ||
-            binding.channel === 'pi'));
+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) };
+    }
 }
-function sendPaseoPrompt(agentId, prompt) {
-    const result = spawnSync('paseo', ['send', agentId, '--prompt', prompt, '--no-wait'], {
-        stdio: 'ignore',
-        timeout: 5000,
-    });
+function send(agentId, prompt) {
+    const result = spawnSync(process.env.SQUARE_PASEO_BIN || 'paseo', ['send', agentId, '--prompt', prompt, '--no-wait'], { stdio: 'ignore', timeout: 5000, env: process.env });
     if (result.error)
         throw result.error;
     if (result.status !== 0)
         throw new Error(`paseo send exited with ${result.status ?? 'no status'}`);
 }
-// ── paseo agent discovery ────────────────────────────────────────
-/** List all paseo agents. Returns empty array if paseo is unavailable. */
-export function listPaseoAgents() {
-    try {
-        return JSON.parse(execSync('paseo ls --json', {
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        }));
-    }
-    catch {
-        return [];
-    }
+function catchCommand(squarePath, recipient) {
+    return `square --as ${quoteShell(recipient)} --square-path ${quoteShell(squarePath)} catch --now`;
 }
-/**
- * Wait for the tool calls that are running now to finish. Calls that start
- * afterward are deliberately ignored: the transitional wake policy allows
- * `paseo send` to replace the next call.
- */
-export async function waitForToolEnd(agentId, timeoutMs) {
-    return waitForPaseoToolBoundary(agentId, {
-        timeoutMs: timeoutMs ?? paseoWakeTimeoutMs(),
-    });
+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');
 }
-// ── paseo wake dispatch ──────────────────────────────────────────
-/**
- * Dispatch a paseo send wake prompt for a single notification.
- *
- * Resolves exact Paseo agent ids from the machine-local participant registry.
- * Idle agents receive the wake immediately. Running agents wait for the
- * current tool call boundary; the following `paseo send` may replace the next
- * call by design.
- */
-export function selectPaseoWakeAgents(squarePath, recipient, agents = listPaseoAgents()) {
-    const ids = new Set(lookupParticipant(squarePath, recipient)
-        .map((binding) => binding.paseoAgentId)
-        .filter((id) => id !== undefined));
-    return agents.filter((agent) => ids.has(agent.id) && (agent.status === 'running' || agent.status === 'idle'));
+async function waitForCatch(squarePath, recipient, notification, ownerId) {
+    const deadline = Date.now() + 180_000;
+    while (Date.now() < deadline) {
+        const doc = loadSquare(squarePath);
+        if (isDeliveryDelivered(doc, recipient, notification.item.index))
+            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;
 }
-export async function dispatchPaseoWake(notification, ctx) {
-    const { item, recipient } = notification;
+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 bindings = lookupParticipant(ctx.squarePath, recipient);
-    const activeAgents = selectPaseoWakeAgents(ctx.squarePath, recipient);
-    if (activeAgents.length === 0)
+    const ownership = paseoOwnershipSnapshot(bindings);
+    if (ownership.length === 0)
         return;
-    const wokenOwners = new Set();
-    for (const active of activeAgents) {
-        if (active.status === 'running') {
-            const reachedBoundary = await waitForToolEnd(active.id);
-            if (!reachedBoundary)
-                continue;
+    const discovery = discoverPaseoAgents();
+    if (discovery.error && discovery.agents.length === 0) {
+        throw new PaseoWakeError(`Paseo unavailable: ${discovery.error}`, diagnostic('discovery', ownership, 'unavailable'));
+    }
+    const active = selectPaseoWakeAgents(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 (agent.status === 'running' && !(await waitForPaseoToolBoundary(agent.id))) {
+            boundaryTimedOut = true;
+            continue;
         }
-        // Re-read after the tool wait: harness inject may have presented during the wait.
-        try {
-            const doc = loadSquare(ctx.squarePath);
-            const known = resolveRosterName(doc, recipient) ?? recipient;
-            if (isDeliveryDelivered(doc, known, item.index))
-                return;
-            if (hasPresentedAttention(ctx.squarePath, known, item.index))
+        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 })) {
+            if (await waitForCatch(ctx.squarePath, recipient, notification, owner.ownerId))
                 return;
         }
-        catch {
-            // Receipt re-read failure fails open toward wake.
-        }
-        const binding = bindings.find((candidate) => candidate.paseoAgentId === active.id);
-        if (binding === undefined || wokenOwners.has(binding.ownerId))
-            continue;
-        try {
-            const catchMembership = sessionInbox(binding.sessionId).find((membership) => membership.name === (resolveRosterName(loadSquare(ctx.squarePath), recipient) ?? recipient) &&
-                membership.catchLease !== undefined &&
-                leaseOwnsNotification(membership.catchLease, {
-                    actor: item.act.actor,
-                    body: item.act.body,
-                    via: notification.via === 'bell' ? 'bell' : 'mention',
-                }));
-            if (catchMembership?.catchLease !== undefined) {
-                if (await waitForCatchDelivery(ctx.squarePath, recipient, notification, binding.ownerId))
-                    return;
-                const current = lookupParticipant(ctx.squarePath, recipient).find((candidate) => candidate.paseoAgentId === active.id);
-                if (current?.ownerId !== binding.ownerId)
-                    continue;
-                const doc = loadSquare(ctx.squarePath);
-                const known = resolveRosterName(doc, recipient) ?? recipient;
-                if (isDeliveryDelivered(doc, known, item.index) ||
-                    hasPresentedAttention(ctx.squarePath, known, item.index)) {
-                    return;
-                }
+        if (owner.nativeGuarantee) {
+            try {
+                send(agent.id, prompt({ ...notification, recipient }, ctx.squarePath, true));
             }
-            if (hasNativeGuarantee(bindings, binding.ownerId)) {
-                sendPaseoPrompt(active.id, nativeWakePrompt(ctx.squarePath, recipient));
-                wokenOwners.add(binding.ownerId);
-                continue;
+            catch (error) {
+                throw new PaseoWakeError(error instanceof Error ? error.message : String(error), diagnostic('send', ownership, 'failed'));
             }
-            presentOnce(binding.sessionId, (sessionId) => sessionInbox(sessionId)
-                .map((membership) => ({
-                ...membership,
-                notifications: membership.notifications.filter((candidate) => candidate.actIndex === item.index),
-            }))
-                .filter((membership) => membership.notifications.length > 0), () => sendPaseoPrompt(active.id, fullWakePrompt(notification, ctx.squarePath)));
-            wokenOwners.add(binding.ownerId);
-        }
-        catch {
-            // Paseo unavailable: notification remains unpresented for a later retry.
+            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), () => {
+            try {
+                send(agent.id, prompt({ ...notification, recipient }, ctx.squarePath, false));
+            }
+            catch (error) {
+                throw new PaseoWakeError(error instanceof Error ? error.message : String(error), diagnostic('send', ownership, 'failed'));
+            }
+            return true;
+        });
+        return;
     }
+    if (boundaryTimedOut)
+        throw new PaseoWakeError('Paseo did not reach the current tool boundary before the wake timeout.', diagnostic('boundary', ownership, 'timeout'));
 }
-// ── WakeSink factory ─────────────────────────────────────────────
-/** Create the default paseo WakeSink used by both sync and async paths. */
-export function paseoWakeSink() {
-    return {
-        name: 'paseo',
-        dispatch: dispatchPaseoWake,
-    };
-}
-/** Default sink list, respecting SQUARE_DISABLE_PASEO_WAKE. */
-export function defaultWakeSinks() {
-    if (process.env.SQUARE_DISABLE_PASEO_WAKE === '1')
-        return [];
-    return [paseoWakeSink()];
-}
+export function paseoWakeSink() { return { name: 'paseo', dispatch: dispatchPaseoNotification }; }
+export function defaultWakeSinks() { return process.env.SQUARE_DISABLE_PASEO_WAKE === '1' ? [] : [paseoWakeSink()]; }