@astrosheep/square 0.3.61 → 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/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;

package/dist/mention-parse.js

@@ -0,0 +1,107 @@
+import { NAME_GRAPHEME_SOURCE, sameName } from './model.js';
+/**
+ * Roster-free scan for `@name` candidates in an activity body. Resolution against the
+ * standing roster happens at landing time in decideAct; this scanner only knows the
+ * name grammar and Markdown code spans.
+ *
+ * Guard rails:
+ * - Backtick code spans never yield candidates (also the escape hatch: `` `@name` `` stays literal).
+ * - A `@` glued to a handle-like prefix does not start a candidate, so emails
+ *   (`user@host`), URLs (`x.com/@user`), and `snake_@case` stay literal. Only ASCII
+ *   word characters, `_`, `-`, `/`, and `@` block a boundary: CJK adjacency like
+ *   `告诉@rei` stays mentionable because CJK text has no spaces to lean on.
+ * - The token must be a complete name (slash-separated segments allowed); resolution
+ *   never backs off to a shorter prefix, so `@rei2` does not mention `rei`.
+ */
+const MENTION_TOKEN = new RegExp(`@((?:${NAME_GRAPHEME_SOURCE})+(?:/(?:${NAME_GRAPHEME_SOURCE})+)*)`, 'vg');
+const BOUNDARY_BLOCKER = /[A-Za-z0-9_\-/@]/;
+/** Ranges [from, to) covered by Markdown code spans (backtick runs close at a run of equal length). */
+function codeSpanRanges(body) {
+    const ranges = [];
+    let index = 0;
+    while (index < body.length) {
+        if (body[index] !== '`') {
+            index += 1;
+            continue;
+        }
+        let runEnd = index;
+        while (runEnd < body.length && body[runEnd] === '`')
+            runEnd += 1;
+        const runLength = runEnd - index;
+        let scan = runEnd;
+        let closedEnd = -1;
+        while (scan < body.length) {
+            if (body[scan] !== '`') {
+                scan += 1;
+                continue;
+            }
+            let closeEnd = scan;
+            while (closeEnd < body.length && body[closeEnd] === '`')
+                closeEnd += 1;
+            if (closeEnd - scan === runLength) {
+                closedEnd = closeEnd;
+                break;
+            }
+            scan = closeEnd;
+        }
+        if (closedEnd === -1) {
+            // Unmatched backticks are literal text; scanning continues after the run.
+            index = runEnd;
+            continue;
+        }
+        ranges.push([index, closedEnd]);
+        index = closedEnd;
+    }
+    return ranges;
+}
+function codePointBefore(body, index) {
+    if (index <= 0)
+        return undefined;
+    const unit = body.charCodeAt(index - 1);
+    if (unit >= 0xdc00 && unit <= 0xdfff && index >= 2)
+        return String.fromCodePoint(body.codePointAt(index - 2));
+    return String.fromCodePoint(unit);
+}
+export function scanMentionCandidates(body) {
+    const spans = codeSpanRanges(body);
+    const found = [];
+    const seen = new Set();
+    for (const match of body.matchAll(MENTION_TOKEN)) {
+        const start = match.index;
+        if (spans.some(([from, to]) => start >= from && start < to))
+            continue;
+        const previous = codePointBefore(body, start);
+        if (previous !== undefined && BOUNDARY_BLOCKER.test(previous))
+            continue;
+        const token = match[1];
+        const key = token.toLocaleLowerCase();
+        if (!seen.has(key)) {
+            seen.add(key);
+            found.push({ token, index: start });
+        }
+    }
+    return found;
+}
+/**
+ * Resolve the longest standing name starting at one candidate's position. A partial
+ * match is only accepted when the character right after it is not handle-continuation
+ * (ASCII word char, `_`, `-`, `/`): `@rei2` never degrades into mentioning `rei`, while
+ * CJK-fluent text like `告诉@rei这个` still mentions `rei`.
+ */
+const TRAILING_BLOCKER = /[A-Za-z0-9_\-/]/;
+export function resolveNameAt(body, candidate, names) {
+    const text = body.slice(candidate.index + 1, candidate.index + 1 + candidate.token.length);
+    let best;
+    for (const name of names) {
+        if (name.length > text.length)
+            continue;
+        if (!sameName(text.slice(0, name.length), name))
+            continue;
+        const after = text[name.length];
+        if (after !== undefined && TRAILING_BLOCKER.test(after))
+            continue;
+        if (best === undefined || name.length > best.length)
+            best = name;
+    }
+    return best;
+}

package/dist/model.d.ts

@@ -18,8 +18,11 @@ export interface ReceiverRoute extends WakeRoute {
 export type SquareErrorCode = 'invalid_name' | 'invalid_args' | 'unknown_participant' | 'not_joined' | 'already_joined' | 'already_done' | 'held' | 'capped' | 'throttled' | 'bell_quota' | 'behind' | 'io' | 'unavailable';
 export type InternalSquareErrorCode = SquareErrorCode | 'not_found' | 'cap_reached' | 'conflict' | 'pending_peer';
 export interface SquareErrorFacts {
+    /** Express admission rejected before any activity was committed. */
+    activityUnsent?: true;
     pending?: number;
     holder?: string;
+    holdReason?: string;
     retryAfterMs?: number;
 }
 declare class SquareErrorBase<Code extends string> extends Error {
@@ -132,4 +135,6 @@ export declare function parseParticipantList(value: string): string[];
 export declare function nameKey(name: string): string;
 export declare function sameName(a: string, b: string): boolean;
 export declare function findParticipantName(participants: string[], name: string): string | undefined;
+/** One name grapheme: Unicode letters, digits, marks, hyphens, or underscores (no isolated variation selectors), or a complete RGI emoji. Shared by name validation and body @mention scanning. */
+export declare const NAME_GRAPHEME_SOURCE: string;
 export declare function validateName(name: string): void;

package/dist/model.js

@@ -39,8 +39,11 @@ export function sameName(a, b) {
 export function findParticipantName(participants, name) {
     return participants.find((participant) => sameName(participant, name));
 }
+/** One name grapheme: Unicode letters, digits, marks, hyphens, or underscores (no isolated variation selectors), or a complete RGI emoji. Shared by name validation and body @mention scanning. */
+export const NAME_GRAPHEME_SOURCE = String.raw `[[\p{L}\p{N}\p{M}_\x2D]--[\p{Variation_Selector}]]|\p{RGI_Emoji}`;
+const NAME_PATTERN = new RegExp(`^(?:${NAME_GRAPHEME_SOURCE})+(?:/(?:${NAME_GRAPHEME_SOURCE})+)*$`, 'v');
 export function validateName(name) {
-    if (!name || !/^(?:[[\p{L}\p{N}\p{M}_\x2D]--[\p{Variation_Selector}]]|\p{RGI_Emoji})+(?:\/(?:[[\p{L}\p{N}\p{M}_\x2D]--[\p{Variation_Selector}]]|\p{RGI_Emoji})+)*$/v.test(name)) {
+    if (!name || !NAME_PATTERN.test(name)) {
         throw new SquareError('invalid_name', 'Invalid name: names must contain non-empty slash-separated segments using Unicode letters, digits, marks, hyphens, underscores, or complete RGI emoji graphemes.');
     }
 }