@astrosheep/square 0.3.2

package/dist/claude-hook.js

@@ -0,0 +1,112 @@
+import { leaseOwnsNotification } from './delivery.js';
+import { notificationMessageId } from './delivery-health.js';
+import { sessionInbox } from './inbox.js';
+import { participantCommandPrefix } from './presentation.js';
+import { presentOnce } from './presented.js';
+function pendingCount(inbox) {
+    return inbox.reduce((total, membership) => total + membership.notifications.length, 0);
+}
+const INJECT_BODY_MAX = 2048;
+/** Let a fresh blocking catch own notifications it can deliver; hook injection remains the fallback. */
+export function deferToActiveCatch(inbox) {
+    return inbox
+        .map((membership) => {
+        const lease = membership.catchLease;
+        if (lease === undefined)
+            return membership;
+        return {
+            ...membership,
+            notifications: membership.notifications.filter((notification) => !leaseOwnsNotification(lease, notification)),
+        };
+    })
+        .filter((membership) => membership.notifications.length > 0);
+}
+function injectBodyPreview(body, squarePath, name, actIndex) {
+    const compact = body.replace(/\r\n/g, '\n');
+    if (compact.length <= INJECT_BODY_MAX)
+        return compact;
+    const pointer = `${participantCommandPrefix(squarePath, name)} echo --ids act_${actIndex} --full`;
+    return `${compact.slice(0, INJECT_BODY_MAX).trimEnd()}\n… [truncated] full echo: ${pointer}`;
+}
+export function renderClaudeInboxContext(inbox) {
+    const count = pendingCount(inbox);
+    const noun = count === 1 ? 'notification' : 'notifications';
+    return [
+        `<system-reminder source="square">You have ${count} unread Square ${noun}.`,
+        ...inbox.flatMap((membership) => {
+            const command = `${participantCommandPrefix(membership.squarePath, membership.name)} catch --now`;
+            return membership.notifications.map((notification) => {
+                const id = notificationMessageId(membership.squarePath, notification.actIndex);
+                const body = injectBodyPreview(notification.body, membership.squarePath, membership.name, notification.actIndex);
+                return [
+                    `${id} · ${membership.squarePath}: @${membership.name} from @${notification.actor} (${notification.via})`,
+                    body,
+                    `Ack with: ${command}`,
+                ].join('\n');
+            });
+        }),
+        // Body here is a cache only. Delivered is written solely by catch.
+        'Ids are stable across turns. If you already acted on an id, do not repeat the action; still run catch --now to mark delivered.',
+        'Read and respond in the square before finishing the current turn.</system-reminder>',
+    ].join('\n');
+}
+function nativeHookResponse(input, lookup, env) {
+    if (typeof input.session_id !== 'string' || input.session_id === '')
+        return undefined;
+    if (input.hook_event_name !== 'UserPromptSubmit' && input.hook_event_name !== 'Stop') {
+        return undefined;
+    }
+    if (input.hook_event_name === 'Stop' && input.stop_hook_active === true)
+        return undefined;
+    // Delivery membership is only claimed by explicit participant actions (join/act/catch/...).
+    // Inherited PASEO_AGENT_ID proves process ancestry, not conversational ownership.
+    // Stop is the guaranteed "don't leave while undelivered" nudge; it does not consume presentation.
+    if (input.hook_event_name === 'Stop') {
+        const pending = lookup(input.session_id).filter((membership) => membership.notifications.length > 0);
+        if (pendingCount(pending) === 0)
+            return undefined;
+        return { decision: 'block', reason: renderClaudeInboxContext(pending) };
+    }
+    return presentOnce(input.session_id, (sessionId) => deferToActiveCatch(lookup(sessionId)), (inbox) => ({
+        hookSpecificOutput: {
+            hookEventName: 'UserPromptSubmit',
+            additionalContext: renderClaudeInboxContext(inbox),
+        },
+    }), env);
+}
+export function claudeHookResponse(input, lookup = sessionInbox, env = process.env) {
+    return nativeHookResponse(input, lookup, env);
+}
+/** Codex shares Claude's turn-boundary protocol; keep a dedicated command for churn isolation. */
+export function codexHookResponse(input, lookup = sessionInbox, env = process.env) {
+    return nativeHookResponse(input, lookup, env);
+}
+export function opencodeHookResponse(input, lookup = sessionInbox, env = process.env) {
+    return nativeHookResponse(input, lookup, env);
+}
+export function runClaudeHook(inputText, env = process.env) {
+    let input;
+    try {
+        input = JSON.parse(inputText);
+    }
+    catch {
+        return '';
+    }
+    if (input === null || typeof input !== 'object')
+        return '';
+    const response = claudeHookResponse(input, sessionInbox, env);
+    return response === undefined ? '' : `${JSON.stringify(response)}\n`;
+}
+export function runCodexHook(inputText, env = process.env) {
+    let input;
+    try {
+        input = JSON.parse(inputText);
+    }
+    catch {
+        return '';
+    }
+    if (input === null || typeof input !== 'object')
+        return '';
+    const response = codexHookResponse(input, sessionInbox, env);
+    return response === undefined ? '' : `${JSON.stringify(response)}\n`;
+}

package/dist/cmd/notify-once.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { setTimeout as sleep } from 'node:timers/promises';
+import { resolve } from 'node:path';
+import { notificationDeliveryWaitMs, processActNotificationsOnce, } from '../notifications.js';
+function parseArgs(argv) {
+    let squarePath;
+    let actIndex;
+    for (let index = 0; index < argv.length; index++) {
+        const argument = argv[index];
+        if (argument === '--square-path' && argv[index + 1] !== undefined) {
+            squarePath = resolve(argv[++index]);
+            continue;
+        }
+        if (argument === '--act-index' && argv[index + 1] !== undefined) {
+            const value = Number(argv[++index]);
+            if (Number.isInteger(value) && value >= 0)
+                actIndex = value;
+            continue;
+        }
+        throw new Error(`Unknown notify-once argument: ${argument}`);
+    }
+    if (!squarePath || actIndex === undefined) {
+        throw new Error('notify-once requires --square-path and --act-index.');
+    }
+    return { squarePath, actIndex };
+}
+async function main() {
+    if (process.env['SQUARE_DISABLE_PASEO_WAKE'] === '1')
+        return;
+    const { squarePath, actIndex } = parseArgs(process.argv.slice(2));
+    await sleep(notificationDeliveryWaitMs());
+    await processActNotificationsOnce(squarePath, actIndex);
+}
+main().catch(() => {
+    // Detached notification delivery must never surface as a CLI failure.
+    process.exitCode = 0;
+});

package/dist/compact.js

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import { loadSquare, renderArtifactAct } from './artifact.js';
+import { SquareError } from './model.js';
+import { withPathOutput } from './presentation.js';
+import { withSquareLock, writeSquareDoc } from './runtime.js';
+import { coreCompact } from './decisions.js';
+function sidecarPath(squarePath) {
+    return squarePath.replace(/\.md$/, '') + '.archive.md';
+}
+export async function cmdCompact(squarePath, opts) {
+    try {
+        let archivedCount;
+        let keptCount;
+        const archive = sidecarPath(squarePath);
+        await withSquareLock(squarePath, () => {
+            const doc = loadSquare(squarePath);
+            const result = coreCompact(doc, opts.keep);
+            archivedCount = result.archived.length;
+            keptCount = result.doc.acts.length;
+            if (archivedCount > 0) {
+                const sidecarExists = fs.existsSync(archive);
+                const block = result.archived
+                    .map((act, index) => renderArtifactAct(act, { first: !sidecarExists && index === 0 }))
+                    .join('\n');
+                fs.appendFileSync(archive, block + '\n');
+                writeSquareDoc(squarePath, result.doc);
+            }
+        });
+        const summary = ['✓ compacted', `  · archived ${archivedCount} acts`, `  · kept ${keptCount} acts`, ...(archivedCount > 0 ? [`  · sidecar ${archive}`] : [])].join('\n');
+        process.stdout.write(withPathOutput(squarePath, summary));
+    }
+    catch (err) {
+        if (err instanceof SquareError) {
+            process.stderr.write(err.message + '\n');
+            process.exit(err.code === 'not_found' ? 1 : 2);
+        }
+        throw err;
+    }
+}

package/dist/decisions.js

@@ -0,0 +1,286 @@
+import { SquareError, sameName, validateName, } from './model.js';
+import { UNREAD_BLOCK_GRACE_MS, actStableIndex, currentHold, foldedState, freshWatchLease, getReadState, publicActs, readCursor, resolveRosterName, rosterNames, extractMentions, matchesMentionTarget, isPostJoinActivity, isDeliveryDelivered, THROTTLE_WINDOW_MS, } from './runtime.js';
+import { indexedDelta, peerPublicActs, peerRoomChanges } from './activity-feed.js';
+import { validate } from './square-core.js';
+import { deriveDeliveryModel } from './delivery.js';
+import { compileSearchPattern } from './search.js';
+export function resolveKnownName(doc, name) {
+    validateName(name);
+    const known = resolveRosterName(doc, name);
+    if (known === undefined) {
+        const roster = rosterNames(doc);
+        throw new SquareError('invalid_args', `Unknown participant "${name}". Expected one of: ${roster.join(', ')}.`);
+    }
+    return known;
+}
+function participantState(state, name) {
+    return state.participants.find((participant) => sameName(participant.name, name));
+}
+export function decideJoin(doc, name, now) {
+    const knownName = resolveRosterName(doc, name);
+    const joinedName = knownName ?? name;
+    const state = foldedState(doc);
+    const result = validate(state, { kind: 'join', actor: joinedName, at: now });
+    if (!result.ok && result.reason === 'already_joined') {
+        throw new SquareError('conflict', `A participant named "${joinedName}" is already in this square.`);
+    }
+    return {
+        joinedName,
+        addParticipant: knownName === undefined,
+        joinAct: { kind: 'join', actor: joinedName, at: now, body: '' },
+    };
+}
+const UNREAD_PREVIEW_LIMIT = 3;
+export function decideAct(doc, input) {
+    const { now, force } = input;
+    const name = resolveKnownName(doc, input.name);
+    const body = input.body;
+    if (body.trim() === '')
+        throw new SquareError('invalid_args', 'act body cannot be empty');
+    const reach = input.reach;
+    const state = foldedState(doc);
+    const current = participantState(state, name);
+    const result = validate(state, { kind: 'say', actor: name, at: now, body, ...(reach !== undefined ? { reach } : {}) }, { hardCap: doc.hardCap, throttlePerMinute: doc.throttlePerMinute, throttleWindowMs: THROTTLE_WINDOW_MS });
+    if (!result.ok) {
+        if (result.reason === 'done')
+            throw new SquareError('conflict', `${name} is done; rejoin to act again`);
+        if (result.reason === 'held')
+            return { type: 'held', reason: result.hold.reason };
+        if (result.reason === 'hard_cap')
+            return { type: 'capped', count: result.count, hardCap: result.hardCap };
+        if (result.reason === 'throttled')
+            return { type: 'throttled', delayMs: result.delayMs };
+        if (result.reason === 'bell_quota')
+            return { type: 'bell_quota', nextAt: result.nextAt };
+        if (result.reason === 'not_joined')
+            throw new SquareError('conflict', `${name} has not joined this square`);
+    }
+    const delta = indexedDelta(doc.acts, readCursor(doc, name));
+    const unreadPublic = peerPublicActs(delta, name);
+    const unreadRoomChanges = peerRoomChanges(delta, name);
+    const sayCountByActor = new Map();
+    const unreadByParticipant = new Map();
+    for (const item of delta) {
+        if (item.act.kind === 'say') {
+            const key = item.act.actor.toLocaleLowerCase();
+            sayCountByActor.set(key, (sayCountByActor.get(key) ?? 0) + 1);
+        }
+        if (item.act.kind !== 'say' || sameName(item.act.actor, name))
+            continue;
+        const actorKey = item.act.actor.toLocaleLowerCase();
+        const currentSummary = unreadByParticipant.get(item.act.actor);
+        unreadByParticipant.set(item.act.actor, {
+            count: (currentSummary?.count ?? 0) + 1,
+            latestAt: currentSummary === undefined ? item.act.at : Math.max(currentSummary.latestAt, item.act.at),
+            previews: [
+                ...(currentSummary?.previews ?? []),
+                { number: sayCountByActor.get(actorKey) ?? 1, act: item.act },
+            ].slice(-UNREAD_PREVIEW_LIMIT),
+        });
+    }
+    const activitySummaries = [...unreadByParticipant.entries()]
+        .map(([participant, summary]) => ({
+        name: participant,
+        count: summary.count,
+        latestActivityAgeMs: Math.max(0, now - summary.latestAt),
+        previews: summary.previews,
+    }))
+        .sort((a, b) => a.latestActivityAgeMs - b.latestActivityAgeMs || a.name.localeCompare(b.name));
+    const latestActivityAgeMs = activitySummaries[0]?.latestActivityAgeMs;
+    const hasUnread = unreadPublic.length > 0 || unreadRoomChanges.length > 0;
+    const hasFreshUnreadActivity = latestActivityAgeMs !== undefined && latestActivityAgeMs <= UNREAD_BLOCK_GRACE_MS;
+    if (!force && hasUnread && !hasFreshUnreadActivity) {
+        return { type: 'blocked', activitySummaries, unreadRoomChanges };
+    }
+    const ownActCount = (current?.activityCount ?? 0) + 1;
+    return {
+        type: 'sent',
+        act: { kind: 'say', actor: name, at: now, body, ...(reach !== undefined ? { reach } : {}) },
+        confirmation: `● heads turn your way — #${ownActCount}`,
+        ownActCount,
+        pendingPublic: unreadPublic,
+        pendingRoomChanges: unreadRoomChanges,
+    };
+}
+export function coreDone(doc, name, body, now) {
+    const resolvedName = resolveKnownName(doc, name);
+    return { kind: 'done', actor: resolvedName, at: now, body: body.replace(/\r\n/g, '\n').trim() };
+}
+export function coreHold(_doc, actor, body, now) {
+    return { kind: 'hold', actor, at: now, body: body.replace(/\r\n/g, '\n').trim() };
+}
+export function coreResume(_doc, actor, now) {
+    return { kind: 'resume', actor, at: now, body: '' };
+}
+export function corePresence(doc, now) {
+    const state = foldedState(doc);
+    return rosterNames(doc).map((participant) => {
+        const snapshot = participantState(state, participant);
+        if (snapshot?.done)
+            return { name: participant, state: 'done', lastAt: snapshot.lastActiveAt };
+        const cursor = getReadState(doc, participant);
+        const lease = freshWatchLease(doc, participant, now);
+        if (lease !== undefined)
+            return { name: participant, state: 'watching', lastAt: cursor?.updatedAt ?? lease.heartbeatAt };
+        const lastAt = cursor?.updatedAt ?? (snapshot?.joined ? snapshot.lastActiveAt : undefined);
+        if (lastAt === undefined)
+            return { name: participant, state: 'never-joined', lastAt: undefined };
+        return { name: participant, state: 'active', lastAt };
+    });
+}
+function buildParticipantStatuses(doc, now, state = foldedState(doc)) {
+    const delivery = deriveDeliveryModel(doc);
+    return state.participants.map(({ name: participant }) => {
+        const snapshot = participantState(state, participant);
+        const cursor = getReadState(doc, participant);
+        const lease = freshWatchLease(doc, participant, now);
+        const presence = snapshot?.done
+            ? { state: 'done', lastAt: snapshot.lastActiveAt }
+            : lease !== undefined
+                ? { state: 'watching', lastAt: cursor?.updatedAt ?? lease.heartbeatAt }
+                : cursor !== undefined || snapshot?.joined
+                    ? { state: 'active', lastAt: cursor?.updatedAt ?? snapshot?.lastActiveAt }
+                    : { state: 'never-joined', lastAt: undefined };
+        const participantStatus = snapshot?.done ? 'done' : snapshot?.joined ? 'active' : 'not joined';
+        const consumedThrough = readCursor(doc, participant);
+        let unreadActivityCount = 0;
+        if (snapshot?.joined) {
+            for (const act of doc.acts) {
+                if (actStableIndex(act) <= consumedThrough || act.actor === undefined || sameName(act.actor, participant))
+                    continue;
+                if (act.kind !== 'read')
+                    unreadActivityCount++;
+            }
+        }
+        return {
+            name: participant,
+            state: participantStatus,
+            activityCount: snapshot?.activityCount ?? 0,
+            lastActiveAt: snapshot?.lastActiveAt,
+            presence: presence.state,
+            presenceAt: presence.lastAt,
+            unreadActivityCount,
+            pendingMentionCount: snapshot?.joined ? delivery.pendingFor(participant).length : 0,
+        };
+    });
+}
+export function coreStatus(doc, now) {
+    const state = foldedState(doc);
+    const latestAct = publicActs(doc.acts).at(-1);
+    return {
+        hardCap: doc.hardCap,
+        throttlePerMinute: doc.throttlePerMinute,
+        participantCount: state.joined.length,
+        activeCount: state.joined.length,
+        doneCount: state.done.length,
+        holdActive: state.hold.active,
+        holdReason: state.hold.reason,
+        holdActor: state.hold.actor,
+        holdAt: state.hold.at,
+        participants: buildParticipantStatuses(doc, now, state),
+        latestAct,
+        now,
+    };
+}
+export function coreParticipants(doc, now) {
+    return { participants: buildParticipantStatuses(doc, now), now };
+}
+/** True when a say is a bell or explicitly @viewer — not broadcast. */
+function addressesViewer(act, viewer) {
+    if (act.kind !== 'say')
+        return false;
+    if (act.reach === 'bell')
+        return true;
+    return extractMentions(act.body).some((name) => sameName(name, viewer));
+}
+export function coreActivities(doc, opts) {
+    const participants = opts.participants ?? [];
+    const canonicalParticipants = participants.map((participant) => resolveKnownName(doc, participant));
+    const viewer = opts.viewer !== undefined ? resolveKnownName(doc, opts.viewer) : undefined;
+    let acts = doc.acts.map((act) => ({ act, index: actStableIndex(act) }));
+    // --at establishes a context window first; other filters AND inside it.
+    if (opts.atIndex != null) {
+        const before = opts.beforeContext ?? 0;
+        const after = opts.afterContext ?? 0;
+        const centerPos = acts.findIndex((item) => item.index === opts.atIndex);
+        if (centerPos < 0)
+            return [];
+        acts = acts.slice(Math.max(0, centerPos - before), centerPos + after + 1);
+    }
+    if (opts.ids !== undefined && opts.ids.length > 0) {
+        const wanted = new Set(opts.ids);
+        acts = acts.filter(({ index }) => wanted.has(index));
+    }
+    if (opts.afterIndex != null)
+        acts = acts.filter(({ index }) => index > opts.afterIndex);
+    if (canonicalParticipants.length > 0) {
+        acts = acts.filter(({ act }) => (act.kind === 'say' && act.reach === 'bell') ||
+            (act.actor !== undefined && canonicalParticipants.some((participant) => sameName(participant, act.actor))));
+    }
+    if (opts.before != null)
+        acts = acts.filter(({ act }) => act.at < opts.before);
+    if (opts.after != null)
+        acts = acts.filter(({ act }) => act.at > opts.after);
+    if (opts.mention != null) {
+        const mention = resolveKnownName(doc, opts.mention);
+        acts = acts.filter(({ act }) => act.kind === 'say' && (act.reach === 'bell' || matchesMentionTarget(act, mention)));
+    }
+    if (opts.mentionsViewer) {
+        if (viewer === undefined)
+            return [];
+        acts = acts.filter(({ act }) => addressesViewer(act, viewer));
+    }
+    if (opts.pending) {
+        if (viewer === undefined)
+            return [];
+        acts = acts.filter(({ act, index }) => {
+            if (!addressesViewer(act, viewer))
+                return false;
+            if (!isPostJoinActivity(doc.acts, viewer, index))
+                return false;
+            return !isDeliveryDelivered(doc, viewer, index);
+        });
+    }
+    const search = opts.grep !== undefined ? { pattern: opts.grep, fixed: false } : opts.fixed !== undefined ? { pattern: opts.fixed, fixed: true } : undefined;
+    if (search !== undefined && search.pattern !== '') {
+        // Search output is defined over the same public say/done activities in every
+        // presentation mode, including --count, --json, and human-readable echo.
+        acts = acts.filter(({ act }) => act.kind === 'say' || act.kind === 'done');
+        const re = compileSearchPattern(search.pattern, search.fixed);
+        acts = acts.filter(({ act }) => 'body' in act && typeof act.body === 'string' && re.test(act.body));
+    }
+    if (opts.order === 'desc') {
+        acts = [...acts].sort((a, b) => b.index - a.index || b.act.at - a.act.at);
+    }
+    else {
+        acts = [...acts].sort((a, b) => a.index - b.index || a.act.at - b.act.at);
+    }
+    return acts;
+}
+export function coreCompact(doc, keep) {
+    if (doc.acts.length <= keep)
+        return { archived: [], doc };
+    const splitAt = doc.acts.length - keep;
+    const archived = doc.acts.slice(0, splitAt);
+    const retained = doc.acts.slice(splitAt);
+    const cutoffIndex = actStableIndex(archived[archived.length - 1]);
+    const unread = rosterNames(doc).filter((participant) => {
+        if (!resolveRosterName(doc, participant) || !currentHold(doc.acts))
+            return false;
+        if (!foldedState(doc).participants.some((entry) => sameName(entry.name, participant) && entry.joined))
+            return false;
+        return readCursor(doc, participant) < cutoffIndex;
+    });
+    if (unread.length > 0) {
+        throw new SquareError('conflict', `Refusing to compact: ${unread.join(', ')} ${unread.length === 1 ? 'has' : 'have'} not read through the acts being archived.`);
+    }
+    const firstActIndex = retained.length > 0 ? actStableIndex(retained[0]) : doc.runtime.nextActIndex;
+    return {
+        archived,
+        doc: {
+            ...doc,
+            acts: retained,
+            runtime: { ...doc.runtime, firstActIndex },
+        },
+    };
+}