@astrosheep/square 0.3.86 → 0.3.88

package/dist/delivery.js

@@ -1,4 +1,29 @@
+import { renderAttentionPreview, renderSquareReminder } from './attention-presentation.js';
+import { parseActivityId } from './square-core.js';
 import { matchesCatchSelection } from './catch-selection.js';
+/** Exact stored activity projection for transports that send an awareness reminder. */
+export function wakePreview(facts, request) {
+    const index = parseActivityId(request.activity);
+    const head = index === undefined ? undefined : pendingHead(facts, request.participant, index);
+    const item = index === undefined ? undefined : facts.activity(index);
+    if (head === undefined || item?.kind !== 'say')
+        return undefined;
+    return renderSquareReminder([renderAttentionPreview({
+            squarePath: request.location, recipient: request.participant, actIndex: item.index,
+            actor: item.actor, route: head.route, body: item.body ?? '(structured activity)',
+        })]);
+}
+/** Presentation custody blocks a wake, independently of native wake acceptance. */
+export function presentationBlocksWake(evidence, now) {
+    return evidence.some((row) => row.kind === 'presentation'
+        && (row.outcome === 'presented' || row.outcome === 'clipped' || row.outcome === 'unknown'
+            || row.outcome === 'dispatching' && (row.expiresAt === undefined || row.expiresAt > now)));
+}
+/** Preselection only: an expired wake dispatch is uncertain, never safe automatic replay. */
+export function automaticWakeEligible(evidence, now) {
+    return !presentationBlocksWake(evidence, now) && !evidence.some((row) => row.kind === 'wake'
+        && (row.outcome === 'accepted' || row.outcome === 'unknown' || row.outcome === 'dispatching'));
+}
 /** Notification pending is not cursor suffix or historical catch membership. */
 export function pendingHead(facts, name, index) {
     const participant = facts.participant(name);
@@ -6,8 +31,15 @@ export function pendingHead(facts, name, index) {
         return undefined;
     return facts.directedAt(participant.name, index);
 }
-/** Complete recipient projection, assembled inside its one transaction. */
-export function pendingNotifications(facts, name) {
+/** One activity's landed recipients that still owe a wake; the rest of the roster is untouched. */
+export function pendingRecipients(facts, index) {
+    return facts.audience(index).flatMap(({ recipient }) => {
+        const head = pendingHead(facts, recipient, index);
+        return head === undefined ? [] : [head];
+    });
+}
+/** Still-pending directed heads for one recipient, oldest first. Bodies belong to presentation. */
+export function pendingHeads(facts, name) {
     const participant = facts.participant(name);
     if (!participant?.joined)
         return [];
@@ -20,9 +52,14 @@ export function pendingNotifications(facts, name) {
             break;
         afterIndex = page.items.at(-1).index;
     }
+    return heads;
+}
+/** Complete recipient projection, assembled inside its one transaction. */
+export function pendingNotifications(facts, name) {
+    const heads = pendingHeads(facts, name), recipient = heads[0]?.recipient ?? name;
     const routes = new Map(heads.map((head) => [head.index, head.route]));
     return facts.activities(heads.map((head) => head.index)).flatMap((item) => item.kind === 'say'
-        ? [{ item, recipient: participant.name, route: routes.get(item.index) }] : []);
+        ? [{ item, recipient, route: routes.get(item.index) }] : []);
 }
 export function capturePendingScan(facts) {
     return { roster: facts.roster().filter((participant) => participant.joined), throughIndex: facts.header().lastActIndex };
@@ -53,23 +90,16 @@ export async function* pendingPages(artifact, scan, afterIndex = -1) {
 /** A pass retains only its captured joins; routes and individual receipts are fresh. */
 export function pendingFacts(facts, scan, heads) {
     const joined = new Set(scan.roster.filter((participant) => sameJoin(facts, participant)).map((participant) => participant.name));
-    return { routes: facts.routes(), pending: heads.filter((head) => joined.has(head.recipient)
+    return { pending: heads.filter((head) => joined.has(head.recipient)
             && pendingHead(facts, head.recipient, head.index) !== undefined) };
 }
-/** Global discovery alone uses pendingAudience; exact dispatch uses its one landed audience. */
-export async function collectPending(artifact, index) {
-    const { value: initial } = await artifact.read((facts) => ({
-        scan: capturePendingScan(facts),
-        pending: index === undefined ? [] : facts.audience(index).flatMap(({ recipient }) => {
-            const head = pendingHead(facts, recipient, index);
-            return head === undefined ? [] : [head];
-        }),
-    }));
-    const pending = [...initial.pending];
-    if (index === undefined)
-        for await (const page of pendingPages(artifact, initial.scan))
-            pending.push(...page);
-    const { value } = await artifact.read((facts) => ({ scan: initial.scan, ...pendingFacts(facts, initial.scan, pending) }));
+/** Global discovery alone sweeps pendingAudience; exact dispatch uses pendingRecipients. */
+export async function collectPending(artifact) {
+    const { value: scan } = await artifact.read(capturePendingScan);
+    const pending = [];
+    for await (const page of pendingPages(artifact, scan))
+        pending.push(...page);
+    const { value } = await artifact.read((facts) => ({ scan, ...pendingFacts(facts, scan, pending) }));
     return value;
 }
 /** A live catch owns every matching notification, independent of its page size. */

package/dist/file-lock.d.ts

@@ -2,9 +2,16 @@ export interface FileLockOptions {
     retryMs: number;
     signal?: AbortSignal;
     createParent?: boolean;
+    /** Optional discovery may skip a busy lock; ordinary lock users still wait. */
+    skipIfBusy?: boolean;
 }
 export declare class FileLockError extends Error {
     readonly code: "not_a_database";
     constructor(lockPath: string, cause?: unknown);
 }
-export declare function withFileLock<T>(lockPath: string, options: FileLockOptions, fn: () => T | Promise<T>): Promise<T>;
+export declare function withFileLock<T>(lockPath: string, options: FileLockOptions & {
+    skipIfBusy: true;
+}, fn: () => T | Promise<T>): Promise<T | undefined>;
+export declare function withFileLock<T>(lockPath: string, options: FileLockOptions & {
+    skipIfBusy?: false;
+}, fn: () => T | Promise<T>): Promise<T>;

package/dist/file-lock.js

@@ -36,6 +36,8 @@ export async function withFileLock(lockPath, options, fn) {
             }
             catch { }
             if (isBusy(error)) {
+                if (options.skipIfBusy)
+                    return undefined;
                 await sleep(options.retryMs, undefined, { signal: options.signal });
                 continue;
             }

package/dist/help.js

@@ -1,7 +1,7 @@
 const COMMANDS = [
     { names: ['help'], usage: 'help [command]', summary: 'Show the command index or help for one command.' },
     { names: ['version'], usage: 'version', summary: 'Print the installed version.', hiddenFromIndex: true },
-    { names: ['mcp-server'], usage: 'mcp-server', summary: 'Start the MCP stdio server.', usesSquare: true, hiddenFromIndex: true, details: ['Set SQUARE_LOCATION or pass --location before the command.', 'Participant tools accept as on each call. Set the default with SQUARE_PARTICIPANT_NAME or --as.', 'Session identity comes from request _meta.threadId (Codex) or _meta["ai.opencode/sessionID"] (OpenCode), falling back to the startup environment.'] },
+    { names: ['mcp-server'], usage: 'mcp-server', summary: 'Start the MCP stdio server.', usesSquare: true, hiddenFromIndex: true, details: ['Set SQUARE_LOCATION or pass --location before the command.', 'Participant tools accept as on each call. Set the default with --as.', 'Session identity comes from request _meta.threadId (Codex) or _meta["ai.opencode/sessionID"] (OpenCode), falling back to the startup environment.'] },
     {
         names: ['build'], usage: 'build [--cap <N|unlimited>] [--template <name>] [--throttle N] [-f] < body.md', usesSquare: true, group: 'host',
         summary: 'Create a square from Markdown on stdin.',
@@ -17,7 +17,7 @@ const COMMANDS = [
         details: ['Options:', '  --last <N>  Show the last N public activities (default 10, maximum 100).', '  --kick      End the standing participant and reclaim the name for this session.'],
     },
     {
-        names: ['express'], usage: '--as <name> express [-f|--force] [--no-wait] [--mention <name>... | --bell] [--no-mention] [--reply <activity-id>] <activity | ->', usesSquare: true, group: 'participant',
+        names: ['express'], usage: '--as <name> express [-f|--force] [--no-wait] [--metadata <json>] [--mention <name>... | --bell] [--no-mention] [--reply <activity-id>] [<activity> | -]', usesSquare: true, group: 'participant',
         summary: 'Speak, gesture, or do both.',
         details: [
             'Reach:',
@@ -32,6 +32,8 @@ const COMMANDS = [
             'Options:',
             '  -f, --force       Express without first catching unread activity or satisfying attention etiquette.',
             '  --no-wait         If held or throttled, save a draft and return instead of waiting. A held wait gives up on its own after 10 minutes.',
+            '  --metadata <json> Attach a bounded JSON object (at most 16 KiB UTF-8 and 256 nesting levels); it may be the only content.',
+            '                    Metadata is returned in structured activity results but is not shown in human text or searchable.',
         ],
     },
     { names: ['listen'], usage: '--as <name> listen <participant>', usesSquare: true, group: 'participant', summary: 'Turn an ear toward one participant\'s future activity.' },
@@ -90,13 +92,8 @@ const COMMANDS = [
     },
     {
         names: ['migrate'], usage: 'migrate', usesSquare: true, group: 'maintenance',
-        summary: 'Convert an existing version 1 or 2 square to current format 3 in place.',
-        details: ['For the selected .square artifact only. Global identity and delivery records use square ledger migrate instead.', 'Stop sessions and services using this artifact before conversion. Back up the stopped artifact, migrate it, then run square --location <path> doctor before starting updated clients.', 'A version 3 square is left untouched; an unrelated or unsupported artifact is refused without a write. There is no --check, --backup or --force.'],
-    },
-    {
-        names: ['ledger'], usage: 'ledger <verify|migrate|gc>', usesSquare: false, group: 'maintenance',
-        summary: 'Verify, convert, or reclaim the machine-local host ledger.',
-        details: ['verify: read-only SQLite integrity or full legacy readiness with accepted/ignored/rejected counts and source hashes; not-ready exits 2, an empty root stays empty. An older supported SQLite format requires explicit migration. Unsupported versions or invalid databases need diagnosis; migration is not a repair command.', 'migrate: stop agent sessions and MCP services using Square with this ledger first, then convert legacy NDJSON or upgrade supported SQLite version 1 in place. Keep them stopped, run square ledger verify afterward, then start them with the updated Square version. Sources, records, order and observer revisions are preserved; an existing current ledger is an untouched no-op.', 'gc [--dry-run]: reclaim old wake/presentation evidence only where the square artifact proves the recipient is closed — the activity reached them and catch receipted it or they later rejoined. Dispatching, lifecycle and unprovable rows are retained. Deleted rows free reusable pages, not file size (no VACUUM); retired Claude recognition tokens keep growing in total.', 'Run gc with --dry-run first: it reports eligible, retired, cas-miss and unreadable-artifact counts without writing. Eligible rows are candidates only: a changed record or an unusable Claude correlation is retained.', 'No participant or square location is required. Uses SQUARE_HOST_LEDGER_ROOT, then SQUARE_REGISTRY’s directory, then ~/.square/host-ledger.', 'These commands never stop, restart, install into or schedule hosts; conversion and schema upgrade are never automatic. No --force or repair.'],
+        summary: 'Convert an existing version 2 or 3 square to current format 4 in place.',
+        details: ['For the selected .square artifact only. Stop sessions using this artifact before conversion. Back up the stopped artifact, migrate it, then run square --location <path> doctor before starting updated clients.', 'A version 2 or 3 square is accepted; version 1, unrelated or unsupported artifacts are refused without a write. There is no --check, --backup or --force.'],
     },
 ];
 function definitionFor(command) {
@@ -109,7 +106,7 @@ export function renderGlobalHelp() {
     const groups = [
         { key: 'participant', title: 'In the square:', order: ['join', 'express', 'listen', 'unlisten', 'ignore', 'listening', 'catch', 'history', 'status', 'hold', 'resume', 'done'] },
         { key: 'host', title: 'Prepare and manage:', order: ['build', 'list', 'participants'] },
-        { key: 'maintenance', title: 'Setup:', order: ['install', 'uninstall', 'doctor', 'migrate', 'ledger'] },
+        { key: 'maintenance', title: 'Setup:', order: ['install', 'uninstall', 'doctor', 'migrate'] },
     ];
     const commandLines = groups.flatMap(({ key, title, order }) => [
         title,
@@ -121,7 +118,7 @@ export function renderGlobalHelp() {
     ]);
     return [
         'Usage: square [--location <square>] [--as <name>] <command> [args...]',
-        'Environment: SQUARE_LOCATION sets the CLI location (local artifact path or stdio://name/key); square-accessing commands require it or --location. SQUARE_PARTICIPANT_NAME sets the participant name.',
+        'Environment: SQUARE_LOCATION sets the CLI location (local artifact path or stdio://name/key); square-accessing commands require it or --location. Use --as to select a participant.',
         'Backends: SQUARE_BACKENDS_CONFIG selects {backends:{name:{command,args?,cwd?,env?}}}; default ~/.config/square/backends.json. See guides/backends.md.',
         'CLI flags override environment values. Participants join explicitly; no square is joined automatically.',
         '',

package/dist/inbox.d.ts

@@ -1,5 +1,5 @@
-import { type InboxMembership } from './model.js';
-import type { PresentationProjection, SessionBindingProjection, SquareRead } from './ports.js';
+import { type Body, type LocatedSeat, type PendingMembership } from './model.js';
+import type { SquareRead } from './ports.js';
 export interface PendingWaitOptions {
     signal?: AbortSignal;
     /** Local delivery suppression, never persisted as evidence of receipt. */
@@ -8,7 +8,28 @@ export interface PendingWaitOptions {
     skipImmediate?: boolean;
     onChangeArmed?: (armed: boolean) => void;
 }
-export declare function projectPresentation(facts: SquareRead, requested: SessionBindingProjection, now?: number): PresentationProjection;
+export declare function pendingKey(membership: LocatedSeat, actIndex: number): string;
+export declare function pendingAtBoundary(inbox: readonly PendingMembership[]): PendingMembership[];
+/** Revalidate a supplied batch immediately before the boundary's independent claim/send checks. */
+export declare function projectBoundaryEligibility(inbox: readonly PendingMembership[]): Promise<PendingMembership[]>;
+export interface SessionBindingCandidate {
+    readonly location: string;
+    readonly body: Body;
+}
+/** HOME is a candidate path index; current seats and delivery evidence live in the artifact. */
+export declare function projectSessionCandidates(input: SessionSeatQuery): Promise<readonly SessionBindingCandidate[]>;
+export interface SessionSeatQuery {
+    readonly body?: Body;
+    readonly sessionId?: string;
+    readonly channel?: string;
+    readonly agent?: string;
+    readonly location?: string;
+    readonly env?: NodeJS.ProcessEnv;
+}
+/** Lifecycle reads resolve seats and join times, never pending activity bodies. */
+export declare function projectSessionSeats(input: SessionSeatQuery, signal?: AbortSignal): Promise<LocatedSeat[]>;
+/** Public count boundary: one coherent read per artifact, without pending body hydration. */
+export declare function sessionInboxCounts(input: SessionSeatQuery, signal?: AbortSignal): Promise<import('./square-facade.js').InboxMembershipSummary[]>;
 export interface NativePendingPreview {
     readonly payload: string;
     readonly clipped: boolean;
@@ -18,7 +39,6 @@ export type NativePendingPreviewInput = {
     readonly sessionId: string;
     readonly participant: string;
     readonly actIndex: number;
-    readonly epoch?: number;
     readonly cancelledThrough?: number;
     readonly now: number;
 } & ({
@@ -32,14 +52,20 @@ export type NativePendingPreviewInput = {
         readonly sessionId: string;
     };
 });
-/** First matching ordered route, exact native epoch/address and catch ownership. */
+/** First matching current seat, exact body/generation/address and catch ownership. */
 export declare function nativePendingPreview(facts: SquareRead, input: NativePendingPreviewInput): NativePendingPreview | undefined;
-export declare function sessionInbox(sessionId: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<InboxMembership[]>;
+export interface SessionIdentityQuery {
+    readonly channel: string;
+    readonly session: string;
+    readonly allAgents?: true;
+}
+export type SessionIdentity = Body | SessionIdentityQuery;
+export declare function sessionInbox(identity: SessionIdentity, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<PendingMembership[]>;
 export interface SessionPendingObserver {
     /** Read committed revisions before reusing content; filesystem hints are only for waiting. */
-    read(options?: Pick<PendingWaitOptions, 'signal' | 'excludeKeys'>): Promise<InboxMembership[]>;
-    wait(timeoutMs: number, options?: PendingWaitOptions): Promise<InboxMembership[]>;
+    read(options?: Pick<PendingWaitOptions, 'signal' | 'excludeKeys'>): Promise<PendingMembership[]>;
+    wait(timeoutMs: number, options?: PendingWaitOptions): Promise<PendingMembership[]>;
     close(): void;
 }
 /** Session-scoped projection over process-shared storage change detectors. */
-export declare function observeSessionPending(sessionId: string, suppliedEnv?: NodeJS.ProcessEnv): Promise<SessionPendingObserver>;
+export declare function observeSessionPending(identity: SessionIdentity, suppliedEnv?: NodeJS.ProcessEnv): Promise<SessionPendingObserver>;