@astrosheep/square 0.3.58 → 0.3.62

package/dist/host-ledger.d.ts

@@ -1,5 +1,4 @@
 import type { WakeRouteKind } from './model.js';
-export type HostLedgerScope = 'user' | 'local';
 export type PresenceChannel = 'claude-code' | 'codex' | 'opencode' | 'pi' | 'paseo' | 'unknown';
 export interface PresenceRecord {
     readonly location: string;
@@ -11,13 +10,13 @@ export interface PresenceRecord {
         readonly address: Readonly<Record<string, string>>;
     };
     readonly updatedAt?: number;
+    readonly epoch?: number;
 }
 export type PresenceKey = Pick<PresenceRecord, 'location' | 'participant' | 'session' | 'channel'>;
 export interface PresenceLookup {
     readonly location?: string;
     readonly participant?: string;
     readonly session?: string;
-    readonly scopes?: readonly HostLedgerScope[];
     readonly now?: number;
 }
 export type PresenceResult = {
@@ -147,29 +146,11 @@ export type ClaimResult = {
     readonly status: 'degraded';
     readonly error: unknown;
 };
-export interface ReconcileBindingInput {
-    readonly scopes?: readonly HostLedgerScope[];
-    readonly now?: number;
-    readonly artifact?: {
-        read(): Promise<{
-            state: {
-                acts: readonly {
-                    kind: string;
-                    actor?: string;
-                }[];
-            };
-        }>;
-    };
-}
-export type ReconcileBindingResult = {
-    readonly status: 'reconciled' | 'degraded';
-    readonly bindings: readonly PresenceRecord[];
-    readonly error?: unknown;
-};
 export interface HostLedgerPort {
-    claimPresence(input: PresenceRecord, scope?: HostLedgerScope): Promise<PresenceClaimResult>;
-    ensurePresence(input: PresenceRecord, scope?: HostLedgerScope): Promise<PresenceResult>;
+    claimPresence(input: PresenceRecord, signal?: AbortSignal): Promise<PresenceClaimResult>;
+    ensurePresence(input: PresenceRecord): Promise<PresenceResult>;
     removePresence(input: PresenceKey): Promise<void>;
+    removePresenceIfUnchanged(input: PresenceRecord): Promise<boolean>;
     listPresence(input: PresenceLookup): Promise<readonly PresenceRecord[]>;
     claimEvidence(input: EvidenceClaim): Promise<ClaimResult>;
     releaseEvidence(input: EvidenceRelease): Promise<void>;
@@ -185,5 +166,4 @@ export interface HostLedgerPort {
     transitionWakeDispatch(input: WakeDispatchTransitionInput): Promise<boolean>;
     releaseWakeDispatch(input: WakeDispatchReleaseInput): Promise<void>;
     gcEvidence(input: EvidenceGc): Promise<void>;
-    reconcileBinding(input: ReconcileBindingInput): Promise<ReconcileBindingResult>;
 }

package/dist/inbox.d.ts

@@ -1,14 +1,19 @@
 import { type InboxMembership } from './model.js';
-export declare function hostLedgerForEnv(env: NodeJS.ProcessEnv): import("./host-ledger.js").HostLedgerPort;
+export declare function hostLedgerForEnv(env: NodeJS.ProcessEnv): import("./host-ledger-file-adapter.js").FileHostLedgerPort;
 export interface PendingWaitOptions {
     signal?: AbortSignal;
-    /** Ephemeral watcher de-duplication; never persisted or used by delivery derivation. */
+    /** Local delivery suppression, never persisted as evidence of receipt. */
     excludeKeys?: ReadonlySet<string>;
-    /** After a delivery failure, wait for a new state edge before retrying the same pending work. */
+    /** Arm before dispatch; retry only after a substantive change, not our failed evidence write. */
     skipImmediate?: boolean;
-    /** Reports whether a change wait has been established for a deferred retry. */
     onChangeArmed?: (armed: boolean) => void;
 }
 export declare function sessionInbox(sessionId: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<InboxMembership[]>;
-/** Wait for a bound square to produce a new pending notification without consuming it. */
+export interface SessionPendingObserver {
+    wait(timeoutMs: number, options?: PendingWaitOptions): Promise<InboxMembership[]>;
+    close(): void;
+}
+/** Session-scoped projection over process-shared storage change detectors. */
+export declare function observeSessionPending(sessionId: string, suppliedEnv?: NodeJS.ProcessEnv): Promise<SessionPendingObserver>;
+/** Finite one-shot consumers retain their API; Pi owns a long-lived observer instead. */
 export declare function waitForSessionPending(sessionId: string, timeoutMs: number, options?: PendingWaitOptions, env?: NodeJS.ProcessEnv): Promise<InboxMembership[]>;

package/dist/inbox.js

@@ -1,94 +1,179 @@
-import { openSquare } from './square-file-adapter.js';
-import { closeOpenSquare } from './open-square.js';
-import { waitForSquareChanges } from './square-file-adapter.js';
-import path from 'node:path';
+import { hostLedgerRoot } from './host-ledger-root.js';
+import { openSquareArtifact, observeSquareChanges } from './square-file-adapter.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
-import { projectPresentation, projectSessionBindings } from './square-projections.js';
+import { canonicalFilePath } from './file-changes.js';
+import { pendingAtBoundary, presentationSuppressesWake, projectPresentation, projectPresentationEvidence, projectSessionBindings } from './square-projections.js';
+import { formatActivityId } from './square-core.js';
+import { WATCH_STALE_MS } from './runtime.js';
 export function hostLedgerForEnv(env) {
-    const root = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
-    return createHostLedgerPort({
-        userPath: env.SQUARE_HOST_LEDGER_USER ?? root,
-        localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? root,
-    });
+    return createHostLedgerPort({ rootPath: hostLedgerRoot(env) });
 }
 function notificationKey(membership, actIndex) {
-    return `${membership.squarePath}\u0000${membership.name.toLocaleLowerCase()}\u0000${actIndex}`;
-}
-function withoutExcluded(inbox, excludeKeys) {
-    if (excludeKeys === undefined || excludeKeys.size === 0)
-        return inbox;
-    return inbox
-        .map((membership) => ({
-        ...membership,
-        notifications: membership.notifications.filter((notification) => !excludeKeys.has(notificationKey(membership, notification.actIndex))),
-    }))
-        .filter((membership) => membership.notifications.length > 0);
+    return membership.squarePath + '\0' + membership.name.toLocaleLowerCase() + '\0' + actIndex;
 }
 export async function sessionInbox(sessionId, env = process.env, signal) {
     const inbox = [];
     const hostLedger = hostLedgerForEnv(env);
     for (const binding of await projectSessionBindings({ hostLedger, sessionId })) {
-        let square;
+        if (signal?.aborted)
+            throw signal.reason;
+        const artifact = openSquareArtifact(binding.location, signal);
         try {
-            square = await openSquare(binding.location, { env, hostLedger, signal });
-            const projection = await projectPresentation({ artifact: square.artifact, binding, now: square.clock() });
+            const projection = await projectPresentation({ artifact, binding, now: Date.now() });
             if (!projection.joined)
                 continue;
-            inbox.push({
-                name: projection.binding.participant,
-                squarePath: projection.binding.location,
+            inbox.push({ name: projection.binding.participant, squarePath: projection.binding.location,
                 notifications: [...projection.notifications],
-                ...(projection.catchLease !== undefined ? { catchLease: projection.catchLease } : {}),
-            });
+                ...(projection.catchLease === undefined ? {} : { catchLease: projection.catchLease }) });
         }
-        catch {
-            // A stale discovery-cache row only disables delivery for that membership.
+        catch (error) {
+            if (signal?.aborted)
+                throw signal.reason ?? error;
+            // A stale or unreadable membership cannot disable delivery for other memberships.
         }
         finally {
-            if (square !== undefined)
-                await closeOpenSquare(square);
+            await artifact.close();
         }
     }
     return inbox;
 }
-/** Wait for a bound square to produce a new pending notification without consuming it. */
-export async function waitForSessionPending(sessionId, timeoutMs, options = {}, env = process.env) {
-    const deadline = Date.now() + Math.max(0, timeoutMs);
-    if (!options.skipImmediate) {
-        const immediate = withoutExcluded(await sessionInbox(sessionId, env), options.excludeKeys);
-        if (immediate.some((membership) => membership.notifications.length > 0))
-            return immediate;
+async function capture(observer, kind, signal) {
+    const generation = observer.generation;
+    try {
+        const value = await observer.read(signal);
+        return { kind, wait: (timeout, abort) => observer.changed(value, timeout, abort) };
     }
-    if (timeoutMs <= 0 || options.signal?.aborted) {
-        options.onChangeArmed?.(false);
-        return [];
+    catch (error) {
+        if (signal.aborted)
+            throw signal.reason ?? error;
+        // Keep watching an unreadable/missing artifact so repair can restore delivery.
+        return { kind, wait: (timeout, abort) => observer.hinted(generation, timeout, abort) };
     }
-    const bindings = await projectSessionBindings({ hostLedger: hostLedgerForEnv(env), sessionId });
-    const paths = [...new Set(bindings.map((binding) => binding.location))];
-    let aborted = false;
-    let projectAfterReady = !options.skipImmediate;
-    const onAbort = () => { aborted = true; };
-    options.signal?.addEventListener('abort', onAbort, { once: true });
-    try {
-        while (!aborted) {
-            const remaining = deadline - Date.now();
-            if (remaining <= 0)
-                return [];
-            const change = await waitForSquareChanges(paths, remaining, options.signal, async () => {
-                if (!projectAfterReady)
-                    return undefined;
-                const current = withoutExcluded(await sessionInbox(sessionId, env), options.excludeKeys);
-                return current.some((membership) => membership.notifications.length > 0) ? current : undefined;
-            }, options.onChangeArmed);
-            if (aborted || change.status === 'expired')
+}
+/** Session-scoped projection over process-shared storage change detectors. */
+export async function observeSessionPending(sessionId, suppliedEnv = process.env) {
+    const env = { ...suppliedEnv };
+    const hostLedger = hostLedgerForEnv(env);
+    const ledger = await hostLedger.observeChanges();
+    const artifacts = new Map();
+    const lifetime = new AbortController();
+    return {
+        async wait(timeoutMs, options = {}) {
+            const deadline = Date.now() + Math.max(0, timeoutMs);
+            const expired = new AbortController();
+            const timer = Number.isFinite(timeoutMs) && timeoutMs > 0
+                ? setTimeout(() => expired.abort(), Math.min(timeoutMs, 2_147_483_647)) : undefined;
+            const signal = AbortSignal.any([lifetime.signal, expired.signal, ...(options.signal === undefined ? [] : [options.signal])]);
+            let canReturn = !options.skipImmediate;
+            let previousEligible;
+            let armed = false;
+            try {
+                while (!signal.aborted) {
+                    // Subscribe/capture the ledger BEFORE discovering bindings; a concurrent join cannot fall in a gap.
+                    const sources = await Promise.all([capture(ledger.presence, 'presence', signal), capture(ledger.evidence, 'evidence', signal)]);
+                    const bindings = await projectSessionBindings({ hostLedger, sessionId });
+                    const paths = new Set(await Promise.all(bindings.map((binding) => canonicalFilePath(binding.location))));
+                    for (const [file, observer] of artifacts) {
+                        if (!paths.has(file)) {
+                            observer.close();
+                            artifacts.delete(file);
+                        }
+                    }
+                    for (const file of paths) {
+                        if (artifacts.has(file))
+                            continue;
+                        const observer = await observeSquareChanges(file);
+                        if (signal.aborted) {
+                            observer.close();
+                            return [];
+                        }
+                        artifacts.set(file, observer);
+                    }
+                    sources.push(...await Promise.all([...artifacts.values()].map((observer) => capture(observer, 'artifact', signal))));
+                    const inbox = await sessionInbox(sessionId, env, signal);
+                    const pending = [];
+                    for (const membership of pendingAtBoundary(inbox)) {
+                        const evidence = await projectPresentationEvidence({ hostLedger, location: membership.squarePath, participant: membership.name, sessionId });
+                        const notifications = membership.notifications.filter((notification) => !options.excludeKeys?.has(notificationKey(membership, notification.actIndex)) &&
+                            !presentationSuppressesWake(evidence.filter((row) => row.activity === formatActivityId(notification.actIndex))));
+                        if (notifications.length > 0)
+                            pending.push({ ...membership, notifications });
+                    }
+                    const eligible = JSON.stringify(pending.flatMap((membership) => membership.notifications.map((note) => notificationKey(membership, note.actIndex))).sort());
+                    if (previousEligible !== undefined && previousEligible !== eligible)
+                        canReturn = true;
+                    previousEligible = eligible;
+                    if (signal.aborted)
+                        return [];
+                    if (canReturn && pending.length > 0)
+                        return pending;
+                    const remaining = deadline - Date.now();
+                    if (remaining <= 0)
+                        return [];
+                    // Eligibility may change at lease expiry without any storage write.
+                    const leaseExpiry = Math.min(Infinity, ...inbox.flatMap((membership) => membership.catchLease === undefined ? [] : [Math.min(membership.catchLease.expiresAt, membership.catchLease.heartbeatAt + WATCH_STALE_MS + 1)]));
+                    const nextExpiry = Math.min(leaseExpiry, await hostLedger.nextExpiry(sessionId));
+                    const duration = Math.min(remaining, Math.max(1, nextExpiry - Date.now()));
+                    const cancelled = new AbortController();
+                    const waitSignal = AbortSignal.any([signal, cancelled.signal]);
+                    const waits = sources.map(async (source) => {
+                        try {
+                            return await source.wait(duration, waitSignal) ? source.kind : 'deadline';
+                        }
+                        catch (error) {
+                            if (waitSignal.aborted)
+                                throw error;
+                            return source.kind;
+                        }
+                    });
+                    if (!armed) {
+                        armed = true;
+                        options.onChangeArmed?.(true);
+                    }
+                    try {
+                        const change = await Promise.race(waits);
+                        // Evidence writes from our own failed injection must not generate a retry loop.
+                        if (change !== 'evidence')
+                            canReturn = true;
+                    }
+                    finally {
+                        cancelled.abort();
+                        await Promise.allSettled(waits);
+                    }
+                }
                 return [];
-            if (change.status === 'ready')
-                return change.value;
-            projectAfterReady = true;
-        }
-        return [];
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return [];
+                throw error;
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                if (!armed)
+                    options.onChangeArmed?.(false);
+            }
+        },
+        close() {
+            if (lifetime.signal.aborted)
+                return;
+            lifetime.abort();
+            ledger.presence.close();
+            ledger.evidence.close();
+            for (const observer of artifacts.values())
+                observer.close();
+            artifacts.clear();
+        },
+    };
+}
+/** Finite one-shot consumers retain their API; Pi owns a long-lived observer instead. */
+export async function waitForSessionPending(sessionId, timeoutMs, options = {}, env = process.env) {
+    const observer = await observeSessionPending(sessionId, env);
+    try {
+        return await observer.wait(timeoutMs, options);
     }
     finally {
-        options.signal?.removeEventListener('abort', onAbort);
+        observer.close();
     }
 }

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export { Square } from './square-wiring.js';
+export { createSquareApplication } from './square-application.js';
 export { SquareError } from './model.js';
 export { bindCurrentParticipant, squareAssignedParticipantName, unbindCurrentParticipant } from './registry.js';
 export { createDefaultWakeTransport } from './notifications.js';
 export { createHostLedgerPort, FileHostLedgerPort } from './host-ledger-file-adapter.js';
 export type { HostLedgerPort, PresenceRecord, EvidenceRecord } from './host-ledger.js';
 export type { PresentationSinkPort } from './ports.js';
+export type { SquareApplication, SquareApplicationContext, JoinApplicationOptions, JoinApplicationResult, ExpressApplicationOptions, ApplicationStatus, ApplicationStatusProjection, ApplicationParticipants } from './square-application.js';
 export type { ActivityId } from './square-core.js';
-export type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, HistoryQuery, ListenerChangeResult, OpenOptions, Participant, ParticipantStatus, PerceivedActivity, SquareAtInput, SquareBuildInput, SquareSnapshot, SquareSource, } from './square-facade.js';
+export type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, HistoryQuery, OperationControl, OperationProgress, ListenerChangeResult, OpenOptions, Participant, ParticipantStatus, PerceivedActivity, SquareAtInput, SquareBuildInput, SquareSnapshot, SquareSource, } from './square-facade.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { Square } from './square-wiring.js';
+export { createSquareApplication } from './square-application.js';
 export { SquareError } from './model.js';
 export { bindCurrentParticipant, squareAssignedParticipantName, unbindCurrentParticipant } from './registry.js';
 export { createDefaultWakeTransport } from './notifications.js';

package/dist/list.js

@@ -5,6 +5,7 @@ import { closeOpenSquare } from './open-square.js';
 import { listPresentation } from './views.js';
 import { formatRelativeTime } from './time.js';
 import { participantIdentity, quoteShell } from './presentation.js';
+import { style } from './tty-style.js';
 const DEFAULT_LIST_DEPTH = 4;
 const MAX_LIST_DEPTH = 16;
 const DEFAULT_LIST_LIMIT = 20;
@@ -84,35 +85,37 @@ function renderSquareList(items, stopped, depth, limit, after) {
     const page = after === undefined ? items : items.filter((item) => item.path.localeCompare(after) > 0);
     const shownItems = page.slice(0, limit);
     if (items.length === 0) {
-        return [`(no squares found)`, ...(stopped ? [`○ discovery stopped after examining ${LIST_DISCOVERY_BUDGET} filesystem entries; results may be incomplete`] : [])].join('\n') + '\n';
+        return [`(no squares found)`, ...(stopped ? [style('dim', `○ the walk stopped early — deeper squares may still be hiding`)] : [])].join('\n') + '\n';
     }
     const now = Date.now();
     const lines = ['squares'];
     for (const item of shownItems) {
-        lines.push(`${item.activities > 0 ? '●' : '○'} ${characterPreview(item.path)} · ${formatRelativeTime(item.lastActiveAt, now)} · ${item.participants.length} in square · ${item.activities} activities`);
+        const glyph = item.activities > 0 ? '●' : style('dim', '○');
+        lines.push(`${glyph} ${characterPreview(item.path)}${style('dim', ` · ${formatRelativeTime(item.lastActiveAt, now)} · ${item.participants.length} in the square · ${item.activities} ${item.activities === 1 ? 'activity' : 'activities'}`)}`);
         const shownContext = item.context.slice(0, CONTEXT_PREVIEW_LINES);
         if (shownContext.length === 0) {
-            lines.push('  context · (none)');
+            lines.push(`  ${style('dim', 'context')} · (none)`);
         }
         else {
-            shownContext.forEach((line, index) => lines.push(`  ${index === 0 ? 'context' : '       '} · ${characterPreview(line)}`));
+            shownContext.forEach((line, index) => lines.push(`  ${index === 0 ? style('dim', 'context') : '       '} · ${characterPreview(line)}`));
             const hiddenContext = item.context.length - shownContext.length;
             if (hiddenContext > 0)
-                lines.push(`          · … ${hiddenContext} more ${hiddenContext === 1 ? 'line' : 'lines'}`);
+                lines.push(style('dim', `          · … ${hiddenContext} more ${hiddenContext === 1 ? 'line' : 'lines'}`));
         }
         const shownParticipants = item.participants.slice(0, PARTICIPANT_PREVIEW_COUNT);
         const hiddenParticipants = item.participants.length - shownParticipants.length;
-        lines.push(`  participants · ${shownParticipants.length === 0 ? 'nobody' : shownParticipants.map((participant) => participantIdentity(characterPreview(participant))).join(' · ')}${hiddenParticipants > 0 ? ` · … ${hiddenParticipants} more` : ''}`);
+        const participantNames = shownParticipants.length === 0 ? 'nobody' : shownParticipants.map((participant) => participantIdentity(characterPreview(participant))).join(' · ');
+        lines.push(`  ${style('dim', 'participants')} · ${participantNames}${hiddenParticipants > 0 ? style('dim', ` · … ${hiddenParticipants} more`) : ''}`);
     }
     const hiddenItems = page.length - shownItems.length;
     if (hiddenItems > 0) {
         const cursor = shownItems.at(-1)?.path;
-        lines.push(stopped ? '  … more squares' : `  … ${hiddenItems} more ${hiddenItems === 1 ? 'square' : 'squares'}`);
+        lines.push(style('dim', stopped ? '  … more squares' : `  … ${hiddenItems} more ${hiddenItems === 1 ? 'square' : 'squares'}`));
         if (cursor !== undefined)
-            lines.push(`» square list --depth ${depth} --limit ${limit} --after ${quoteShell(cursor)}`);
+            lines.push(`square list --depth ${depth} --limit ${limit} --after ${quoteShell(cursor)}`);
     }
     if (stopped)
-        lines.push(`○ discovery stopped after examining ${LIST_DISCOVERY_BUDGET} filesystem entries; results may be incomplete`);
+        lines.push(style('dim', `○ the walk stopped early — deeper squares may still be hiding`));
     return lines.join('\n') + '\n';
 }
 function parseListOptions(args, usage) {

package/dist/mcp.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type SquareApplicationContext } from './square-application.js';
+export interface SquareMcpOptions extends SquareApplicationContext {
+}
+export type SquareMcpServer = McpServer;
+export declare function createSquareMcpServer(options: SquareMcpOptions): SquareMcpServer;
+export declare function runSquareMcpStdio(options: SquareMcpOptions): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,122 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod/v4';
+import { SquareError, isSquareError } from './model.js';
+import { createSquareApplication } from './square-application.js';
+const activityIdSchema = { type: 'string', pattern: '^act/(0|[1-9][0-9]*)$' };
+const stringArraySchema = { type: 'array', items: { type: 'string' } };
+function objectSchema(properties, required = []) { return { properties, required }; }
+const TOOL_DEFINITIONS = [
+    { name: 'join', description: 'Join the square as the configured participant.', inputSchema: objectSchema({ takeover: { type: 'boolean' } }) },
+    { name: 'express', description: 'Express a message or embodied action in the square.', inputSchema: objectSchema({ body: { type: 'string' }, mentions: stringArraySchema, reach: { type: 'string', enum: ['bell'] }, reply: activityIdSchema, force: { type: 'boolean' }, noWait: { type: 'boolean' } }, ['body']) },
+    { name: 'catch', description: 'Catch and consume activities perceptible to the configured participant.', inputSchema: objectSchema({ id: activityIdSchema, idle: { type: 'number', minimum: 0 }, from: stringArraySchema, mention: { type: 'boolean' }, limit: { type: 'integer', minimum: 1 } }) },
+    { name: 'history', description: 'Read the activity stream using stable activity-id cursors.', inputSchema: objectSchema({ limit: { type: 'integer', minimum: 1 }, order: { type: 'string', enum: ['asc', 'desc'] }, before: activityIdSchema, after: activityIdSchema, grep: { type: 'string' }, fixed: { type: 'string' }, from: stringArraySchema, mention: { type: 'string' } }) },
+    { name: 'listen', description: 'Listen for future activity from a participant.', inputSchema: objectSchema({ target: { type: 'string' } }, ['target']) },
+    { name: 'ignore', description: 'Stop listening for future activity from a participant.', inputSchema: objectSchema({ target: { type: 'string' } }, ['target']) },
+    { name: 'listening', description: 'List participants this participant is listening to.', inputSchema: objectSchema({}) },
+    { name: 'hold', description: 'Raise a hand to hold the square.', inputSchema: objectSchema({ reason: { type: 'string' } }) },
+    { name: 'resume', description: 'Release the current hold.', inputSchema: objectSchema({}) },
+    { name: 'done', description: 'Leave the square without adding a message.', inputSchema: objectSchema({}) },
+    { name: 'status', description: 'Read the public status of the square.', inputSchema: objectSchema({}) },
+    { name: 'participants', description: 'List participants standing in or done with the square.', inputSchema: objectSchema({}) },
+];
+function zodInputSchema(schema) {
+    const shape = {};
+    for (const [key, property] of Object.entries(schema.properties)) {
+        let field;
+        if (property.type === 'string' && property.enum !== undefined)
+            field = z.enum(property.enum);
+        else if (property.type === 'string')
+            field = property.pattern === undefined ? z.string() : z.string().regex(new RegExp(property.pattern));
+        else if (property.type === 'boolean')
+            field = z.boolean();
+        else if (property.type === 'number')
+            field = z.number().finite().min(property.minimum ?? -Infinity);
+        else if (property.type === 'integer')
+            field = z.number().int().min(property.minimum ?? -Infinity);
+        else if (property.type === 'array')
+            field = z.array(z.string());
+        else
+            throw new Error(`Unsupported input schema type: ${property.type}`);
+        shape[key] = schema.required.includes(key) ? field : field.optional();
+    }
+    return z.object(shape).strict();
+}
+function isObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function publicActivity(activity) { return { ...activity }; }
+function publicResult(name, value) {
+    if (name === 'status') {
+        const result = value;
+        const state = result.status;
+        const { latestAct, participants, ...rest } = state;
+        return {
+            hardCap: rest.hardCap,
+            ...(rest.throttlePerMinute === undefined ? {} : { throttlePerMinute: rest.throttlePerMinute }),
+            activeCount: rest.activeCount,
+            doneCount: rest.doneCount,
+            hold: rest.holdActive ? { by: rest.holdActor, ...(rest.holdReason === undefined ? {} : { reason: rest.holdReason }), ...(rest.holdAt === undefined ? {} : { at: rest.holdAt }) } : null,
+            participants: participants.filter((participant) => participant.state !== 'not joined').map((participant) => ({ name: participant.name, state: participant.state, presence: participant.presence, activityCount: participant.activityCount, ...(participant.lastActiveAt === undefined ? {} : { lastActiveAt: participant.lastActiveAt }), unreadActivityCount: participant.unreadActivityCount, pendingMentionCount: participant.pendingMentionCount, listening: participant.listening })),
+            ...(latestAct === undefined ? {} : { latestActivity: publicActivity({ id: `act/${latestAct.index}`, at: latestAct.at, kind: latestAct.kind, actor: latestAct.actor ?? '', ...('body' in latestAct && latestAct.body !== undefined ? { body: latestAct.body } : {}), mentions: 'mentions' in latestAct ? latestAct.mentions ?? [] : [], ...('target' in latestAct ? { target: latestAct.target } : {}), ...(latestAct.kind === 'say' && latestAct.reach !== undefined ? { reach: latestAct.reach } : {}), ...(latestAct.kind === 'say' && latestAct.reply !== undefined ? { reply: `act/${latestAct.reply}` } : {}) }) }),
+            now: rest.now,
+        };
+    }
+    if (name === 'express' || name === 'hold' || name === 'resume' || name === 'done') {
+        const result = value;
+        return { ...(result.activity === undefined ? {} : { activity: result.activity === null ? null : publicActivity(result.activity) }), ...(result.waited === undefined ? {} : { waited: result.waited }) };
+    }
+    if (name === 'history')
+        return { activities: value };
+    if (name === 'participants')
+        return { participants: value };
+    if (name === 'listening')
+        return { listening: value };
+    return value;
+}
+function operation(app, name, args, control) {
+    switch (name) {
+        case 'join': return app.join({ takeover: args.takeover }, control);
+        case 'express': {
+            const { body, noWait, ...options } = args;
+            return app.express(body, { ...options, noWait }, control);
+        }
+        case 'catch': return app.catch(args, control);
+        case 'history': return app.history(args, control);
+        case 'listen': return app.listen(args.target, control);
+        case 'ignore': return app.ignore(args.target, control);
+        case 'listening': return app.listening(control);
+        case 'hold': return app.hold(args.reason, control);
+        case 'resume': return app.resume(control);
+        case 'done': return app.done(undefined, control);
+        case 'status': return app.status();
+        case 'participants': return app.participants();
+        default: throw new SquareError('invalid_args', `Unknown tool: ${name}`);
+    }
+}
+export function createSquareMcpServer(options) {
+    const app = createSquareApplication(options);
+    const server = new McpServer({ name: 'square', version: '0.3.61' }, {
+        instructions: 'The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.',
+    });
+    for (const tool of TOOL_DEFINITIONS) {
+        server.registerTool(tool.name, { description: tool.description, inputSchema: zodInputSchema(tool.inputSchema) }, async (args, extra) => {
+            try {
+                const value = await operation(app, tool.name, args, { signal: extra.signal });
+                const projected = publicResult(tool.name, value);
+                const structuredContent = isObject(projected) ? projected : { result: projected };
+                return { content: [{ type: 'text', text: JSON.stringify(structuredContent) }], structuredContent };
+            }
+            catch (error) {
+                const normalized = extra.signal.aborted
+                    ? { code: 'cancelled', message: 'The MCP request was cancelled' }
+                    : isSquareError(error)
+                        ? { code: error.code, message: error.message, ...(error.facts === undefined ? {} : { facts: error.facts }) }
+                        : { code: 'internal', message: error instanceof Error ? error.message : String(error) };
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify(normalized) }], structuredContent: { error: normalized } };
+            }
+        });
+    }
+    return server;
+}
+export async function runSquareMcpStdio(options) {
+    await createSquareMcpServer(options).connect(new StdioServerTransport());
+}

package/dist/mention-parse.d.ts

@@ -0,0 +1,8 @@
+export interface MentionCandidate {
+    /** The maximal name-grammar token after `@` (roster-free; resolution may shorten it). */
+    readonly token: string;
+    /** UTF-16 index of the `@` in the body. */
+    readonly index: number;
+}
+export declare function scanMentionCandidates(body: string): MentionCandidate[];
+export declare function resolveNameAt(body: string, candidate: MentionCandidate, names: readonly string[]): string | undefined;