@astrosheep/square 0.3.2

package/dist/presented.js

@@ -0,0 +1,211 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { canonicalSquarePath, lookupParticipant, lookupSessionBindings } from './registry.js';
+import { sameName } from './model.js';
+const RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+const LOCK_STALE_MS = 5 * 60_000;
+const LOCK_RETRY_MS = 10;
+const lockWait = new Int32Array(new SharedArrayBuffer(4));
+const heldLocks = new Set();
+export function presentedPath(env = process.env) {
+    return env.SQUARE_PRESENTED || path.join(os.homedir(), '.square', 'presented.ndjsonl');
+}
+function rowKey(row) {
+    return `${row.owner_id}\u0000${canonicalSquarePath(row.square_path)}\u0000${row.name.toLocaleLowerCase()}\u0000${row.act_index}`;
+}
+function readRows(filePath, now = Date.now()) {
+    let text;
+    try {
+        text = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const cutoff = now - RETENTION_MS;
+    const rows = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed.v !== 2 ||
+                typeof parsed.ts !== 'number' ||
+                typeof parsed.owner_id !== 'string' ||
+                typeof parsed.presenter_session_id !== 'string' ||
+                typeof parsed.square_path !== 'string' ||
+                typeof parsed.name !== 'string' ||
+                typeof parsed.act_index !== 'number' ||
+                parsed.ts < cutoff) {
+                continue;
+            }
+            rows.push(parsed);
+        }
+        catch {
+            // The presented ledger is a disposable cache; malformed rows are ignored.
+        }
+    }
+    return rows;
+}
+function writeRows(filePath, rows) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const temp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temp, rows.map((row) => JSON.stringify(row)).join('\n') + (rows.length ? '\n' : ''), {
+        mode: 0o600,
+    });
+    fs.renameSync(temp, filePath);
+}
+function lockOwnerState(lockPath) {
+    let pid;
+    try {
+        pid = Number.parseInt(fs.readFileSync(lockPath, 'utf8').split('\n')[0], 10);
+    }
+    catch {
+        return 'unknown';
+    }
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return 'unknown';
+    try {
+        process.kill(pid, 0);
+        return 'alive';
+    }
+    catch (error) {
+        return error.code === 'ESRCH' ? 'dead' : 'alive';
+    }
+}
+function withFileLock(lockPath, fn) {
+    if (heldLocks.has(lockPath))
+        throw new Error(`Reentrant presented lock: ${lockPath}`);
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    while (true) {
+        let acquired = false;
+        try {
+            const fd = fs.openSync(lockPath, 'wx', 0o600);
+            try {
+                fs.writeFileSync(fd, `${process.pid}\n${Date.now()}\n`, 'utf8');
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            acquired = true;
+            heldLocks.add(lockPath);
+            return fn();
+        }
+        catch (error) {
+            const errno = error;
+            if (acquired || errno.code !== 'EEXIST')
+                throw error;
+            try {
+                const stat = fs.statSync(lockPath);
+                if (lockOwnerState(lockPath) === 'dead' || Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+                    fs.unlinkSync(lockPath);
+                    continue;
+                }
+            }
+            catch { }
+            Atomics.wait(lockWait, 0, 0, LOCK_RETRY_MS);
+        }
+        finally {
+            if (acquired) {
+                heldLocks.delete(lockPath);
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch { }
+            }
+        }
+    }
+}
+function membershipKey(membership) {
+    return `${canonicalSquarePath(membership.squarePath)}\u0000${membership.name.toLocaleLowerCase()}`;
+}
+function attentionLockPath(filePath, membership) {
+    const digest = createHash('sha256').update(membershipKey(membership)).digest('hex');
+    return `${filePath}.${digest}.lock`;
+}
+function withAttentionLocks(filePath, inbox, fn) {
+    const lockPaths = [...new Set(inbox.map((membership) => attentionLockPath(filePath, membership)))].sort();
+    function acquire(index) {
+        if (index >= lockPaths.length)
+            return fn();
+        return withFileLock(lockPaths[index], () => acquire(index + 1));
+    }
+    return acquire(0);
+}
+function ownerFor(sessionId, membership) {
+    const squarePath = canonicalSquarePath(membership.squarePath);
+    const binding = lookupSessionBindings(sessionId).find((candidate) => candidate.squarePath === squarePath && sameName(candidate.name, membership.name));
+    return binding?.ownerId ?? `session:${sessionId}`;
+}
+function selectUnpresented(sessionId, inbox, rows) {
+    const known = new Set(rows.map(rowKey));
+    return inbox.flatMap((membership) => {
+        const ownerId = ownerFor(sessionId, membership);
+        const notifications = membership.notifications.filter((notification) => !known.has(rowKey({
+            owner_id: ownerId,
+            square_path: membership.squarePath,
+            name: membership.name,
+            act_index: notification.actIndex,
+        })));
+        return notifications.length === 0
+            ? []
+            : [{ membership: { ...membership, notifications }, ownerId }];
+    });
+}
+/** True when the current participant owner has already received this attention. */
+export function hasPresentedAttention(squarePath, name, actIndex, env = process.env) {
+    const ownerIds = new Set(lookupParticipant(squarePath, name).map((binding) => binding.ownerId));
+    if (ownerIds.size === 0)
+        return false;
+    const resolved = canonicalSquarePath(squarePath);
+    return readRows(presentedPath(env)).some((row) => ownerIds.has(row.owner_id) &&
+        canonicalSquarePath(row.square_path) === resolved &&
+        sameName(row.name, name) &&
+        row.act_index === actIndex);
+}
+/**
+ * Serialize presentation only for the affected participants. Delivery runs
+ * outside the short ledger-write lock, so unrelated owners never wait on an
+ * adapter. A throwing callback leaves no row and remains retryable.
+ */
+export function presentOnce(sessionId, lookup, deliver, env = process.env, at = Date.now()) {
+    const filePath = presentedPath(env);
+    const initial = lookup(sessionId).filter((membership) => membership.notifications.length > 0);
+    if (initial.length === 0)
+        return undefined;
+    const lockedMemberships = new Set(initial.map(membershipKey));
+    return withAttentionLocks(filePath, initial, () => {
+        const current = lookup(sessionId).filter((membership) => lockedMemberships.has(membershipKey(membership)));
+        const selected = selectUnpresented(sessionId, current, readRows(filePath, at));
+        if (selected.length === 0)
+            return undefined;
+        const result = deliver(selected.map(({ membership }) => membership));
+        withFileLock(`${filePath}.lock`, () => {
+            const rows = readRows(filePath, at);
+            const known = new Set(rows.map(rowKey));
+            for (const { membership, ownerId } of selected) {
+                for (const notification of membership.notifications) {
+                    const row = {
+                        v: 2,
+                        ts: at,
+                        owner_id: ownerId,
+                        presenter_session_id: sessionId,
+                        square_path: canonicalSquarePath(membership.squarePath),
+                        name: membership.name,
+                        act_index: notification.actIndex,
+                    };
+                    const key = rowKey(row);
+                    if (known.has(key))
+                        continue;
+                    rows.push(row);
+                    known.add(key);
+                }
+            }
+            writeRows(filePath, rows);
+        });
+        return result;
+    });
+}

package/dist/registry.js

@@ -0,0 +1,299 @@
+/**
+ * Machine-local participant discovery cache.
+ *
+ * The Square artifact remains authoritative for membership. This append-only
+ * cache only maps native harness sessions and optional Paseo agent ids back to
+ * active (square path, participant name) pairs.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { nameKey, sameName } from './model.js';
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const COMPACT_BYTES = 64 * 1024;
+const COMPACT_LINES = 1000;
+const VALID_CHANNELS = new Set(['claude-code', 'codex', 'opencode', 'pi', 'paseo', 'unknown']);
+export function registryPath() {
+    if (process.env['SQUARE_REGISTRY'])
+        return process.env['SQUARE_REGISTRY'];
+    return path.join(homedir(), '.square', 'sessions.ndjsonl');
+}
+export function canonicalSquarePath(squarePath) {
+    const absolute = path.resolve(squarePath);
+    try {
+        return fs.realpathSync.native(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+function bindingKey(sessionId, squarePath, name) {
+    return JSON.stringify([sessionId, canonicalSquarePath(squarePath), nameKey(name)]);
+}
+function participantKey(squarePath, name) {
+    return JSON.stringify([canonicalSquarePath(squarePath), nameKey(name)]);
+}
+function nextOwnerId() {
+    return randomUUID();
+}
+function parseLine(raw, now) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const entry = value;
+    if ((entry.v !== undefined && entry.v !== 1) ||
+        (entry.op !== 'join' && entry.op !== 'done') ||
+        typeof entry.session_id !== 'string' ||
+        entry.session_id === '' ||
+        typeof entry.name !== 'string' ||
+        entry.name === '' ||
+        typeof entry.square_path !== 'string' ||
+        entry.square_path === '' ||
+        typeof entry.ts !== 'string') {
+        return undefined;
+    }
+    const updatedAt = Date.parse(entry.ts);
+    if (!Number.isFinite(updatedAt) || updatedAt > now || now - updatedAt > MAX_AGE_MS)
+        return undefined;
+    const channel = entry.channel ?? 'unknown';
+    if (!VALID_CHANNELS.has(channel))
+        return undefined;
+    if (entry.child !== undefined && entry.child !== true)
+        return undefined;
+    if (entry.paseo_agent_id !== undefined && typeof entry.paseo_agent_id !== 'string')
+        return undefined;
+    if (entry.owner_id !== undefined && typeof entry.owner_id !== 'string')
+        return undefined;
+    return { ...entry, v: 1, channel };
+}
+function foldRegistry(raw, now) {
+    const state = new Map();
+    // A later claim replaces the participant's prior agent, while one claim may retain multiple adapter identities.
+    const owners = new Map();
+    let order = 0;
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        const entry = parseLine(line, now);
+        if (!entry)
+            continue;
+        order++;
+        const ownerId = entry.owner_id ?? `legacy:${order}`;
+        state.set(bindingKey(entry.session_id, entry.square_path, entry.name), {
+            entry,
+            updatedAt: Date.parse(entry.ts),
+            ownerId,
+        });
+        if (entry.op === 'join')
+            owners.set(participantKey(entry.square_path, entry.name), ownerId);
+    }
+    const active = [];
+    for (const { entry, updatedAt, ownerId } of state.values()) {
+        if (entry.op !== 'join')
+            continue;
+        if (owners.get(participantKey(entry.square_path, entry.name)) !== ownerId)
+            continue;
+        active.push({
+            sessionId: entry.session_id,
+            name: entry.name,
+            squarePath: canonicalSquarePath(entry.square_path),
+            channel: entry.channel,
+            child: entry.child === true,
+            ...(entry.paseo_agent_id ? { paseoAgentId: entry.paseo_agent_id } : {}),
+            ownerId,
+            updatedAt,
+        });
+    }
+    return active.sort((a, b) => b.updatedAt - a.updatedAt);
+}
+function compactRegistry(filePath, raw, now) {
+    const active = foldRegistry(raw, now);
+    const compacted = active
+        .slice()
+        .reverse()
+        .map((binding) => JSON.stringify({
+        v: 1,
+        ts: new Date(binding.updatedAt).toISOString(),
+        op: 'join',
+        channel: binding.channel,
+        session_id: binding.sessionId,
+        name: binding.name,
+        square_path: binding.squarePath,
+        ...(binding.child ? { child: true } : {}),
+        ...(binding.paseoAgentId ? { paseo_agent_id: binding.paseoAgentId } : {}),
+        owner_id: binding.ownerId,
+    }))
+        .join('\n');
+    const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, compacted === '' ? '' : `${compacted}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, filePath);
+}
+function maybeCompactRegistry(filePath, now) {
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (stat.size <= COMPACT_BYTES)
+        return;
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const lines = raw.split('\n').filter(Boolean).length;
+    if (stat.size > COMPACT_BYTES || lines > COMPACT_LINES)
+        compactRegistry(filePath, raw, now);
+}
+function appendRegistryLine(entry, now) {
+    const filePath = registryPath();
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    maybeCompactRegistry(filePath, now);
+    const fd = fs.openSync(filePath, 'a', 0o600);
+    try {
+        fs.writeSync(fd, `${JSON.stringify(entry)}\n`);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function writeLifecycle(op, sessionId, name, squarePath, options) {
+    if (!sessionId || !name || !squarePath)
+        return;
+    const at = options.at ?? Date.now();
+    if (!Number.isFinite(at))
+        return;
+    try {
+        appendRegistryLine({
+            v: 1,
+            ts: new Date(at).toISOString(),
+            op,
+            channel: options.channel ?? 'unknown',
+            session_id: sessionId,
+            name,
+            square_path: canonicalSquarePath(squarePath),
+            ...(options.child ? { child: true } : {}),
+            ...(options.paseoAgentId ? { paseo_agent_id: options.paseoAgentId } : {}),
+            ...(op === 'join' ? { owner_id: options.ownerId ?? nextOwnerId() } : {}),
+        }, at);
+    }
+    catch (error) {
+        process.stderr.write(`! square registry write failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+export function recordJoin(sessionId, name, squarePath, options = {}) {
+    writeLifecycle('join', sessionId, name, squarePath, options);
+}
+export function recordDone(sessionId, name, squarePath, options = {}) {
+    writeLifecycle('done', sessionId, name, squarePath, options);
+}
+function readActiveBindings(now = Date.now()) {
+    try {
+        return foldRegistry(fs.readFileSync(registryPath(), 'utf8'), now);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        return [];
+    }
+}
+export function lookupSessionBindings(sessionId, now = Date.now()) {
+    return readActiveBindings(now).filter((binding) => binding.sessionId === sessionId);
+}
+export function lookupSession(sessionId, now = Date.now()) {
+    return lookupSessionBindings(sessionId, now).map(({ name, squarePath }) => ({ name, squarePath }));
+}
+export function lookupParticipant(squarePath, name, now = Date.now()) {
+    const canonicalPath = canonicalSquarePath(squarePath);
+    return readActiveBindings(now).filter((binding) => binding.squarePath === canonicalPath && sameName(binding.name, name));
+}
+export function localSessionIdentities(env = process.env) {
+    const paseoAgentId = env['PASEO_AGENT_ID']?.trim() || undefined;
+    const identities = [];
+    const claudeSessionId = env['CLAUDE_CODE_SESSION_ID']?.trim();
+    if (claudeSessionId) {
+        identities.push({
+            sessionId: claudeSessionId,
+            channel: 'claude-code',
+            child: env['CLAUDE_CODE_CHILD_SESSION'] === '1',
+            ...(paseoAgentId ? { paseoAgentId } : {}),
+        });
+    }
+    const codexThreadId = env['CODEX_THREAD_ID']?.trim();
+    if (codexThreadId && !identities.some((identity) => identity.sessionId === codexThreadId)) {
+        identities.push({
+            sessionId: codexThreadId,
+            channel: 'codex',
+            child: false,
+            ...(paseoAgentId ? { paseoAgentId } : {}),
+        });
+    }
+    const openCodeSessionId = env['OPENCODE_SESSION_ID']?.trim();
+    if (openCodeSessionId && !identities.some((identity) => identity.sessionId === openCodeSessionId)) {
+        identities.push({
+            sessionId: openCodeSessionId,
+            channel: 'opencode',
+            child: false,
+            ...(paseoAgentId ? { paseoAgentId } : {}),
+        });
+    }
+    const piSessionId = env['SQUARE_PI_SESSION_ID']?.trim();
+    if (piSessionId && !identities.some((identity) => identity.sessionId === piSessionId)) {
+        identities.push({
+            sessionId: piSessionId,
+            channel: 'pi',
+            child: false,
+            ...(paseoAgentId ? { paseoAgentId } : {}),
+        });
+    }
+    if (paseoAgentId && !identities.some((identity) => identity.sessionId === paseoAgentId)) {
+        identities.push({
+            sessionId: paseoAgentId,
+            channel: 'paseo',
+            child: false,
+            paseoAgentId,
+        });
+    }
+    return identities;
+}
+/** True when this process belongs to a harness that can deliver Square attention without a foreground catch. */
+export function hasAutomaticDeliveryIdentity(env = process.env) {
+    return localSessionIdentities(env).length > 0;
+}
+export function recordLocalJoin(name, squarePath, env = process.env) {
+    const at = Date.now();
+    const identities = localSessionIdentities(env);
+    const identityIds = new Set(identities.map((identity) => identity.sessionId));
+    const current = lookupParticipant(squarePath, name, at);
+    const ownerId = current.find((binding) => identityIds.has(binding.sessionId))?.ownerId ?? nextOwnerId();
+    for (const identity of identities) {
+        recordJoin(identity.sessionId, name, squarePath, { ...identity, at, ownerId });
+    }
+}
+export function recordLocalDone(name, squarePath, env = process.env) {
+    const at = Date.now();
+    const identities = localSessionIdentities(env);
+    const identityIds = new Set(identities.map((identity) => identity.sessionId));
+    const current = lookupParticipant(squarePath, name, at);
+    const ownerId = current.find((binding) => identityIds.has(binding.sessionId))?.ownerId;
+    if (ownerId === undefined) {
+        for (const identity of identities)
+            recordDone(identity.sessionId, name, squarePath, { ...identity, at });
+        return;
+    }
+    for (const binding of current.filter((candidate) => candidate.ownerId === ownerId)) {
+        recordDone(binding.sessionId, binding.name, binding.squarePath, {
+            channel: binding.channel,
+            child: binding.child,
+            ...(binding.paseoAgentId ? { paseoAgentId: binding.paseoAgentId } : {}),
+            at,
+        });
+    }
+}