@astrosheep/square 0.3.76 → 0.3.78

package/dist/attention-presentation.d.ts

@@ -11,7 +11,7 @@ export interface AttentionPreview {
 export declare function previewAttentionBody(body: string): string;
 export declare function attentionBodyIsClipped(body: string): boolean;
 export declare function displayAttentionPath(squarePath: string): string;
-export declare function renderAttentionDescription({ actor, recipient, route }: Pick<AttentionPreview, 'actor' | 'recipient' | 'route'>): string;
+export declare function renderAttentionDescription({ actor, route }: Pick<AttentionPreview, 'actor' | 'route'>): string;
 /** Full notification text for human-facing expansion, never the bounded model preview. */
 export declare function renderAttentionFull(attention: AttentionPreview): string;
 export declare function renderAttentionPreview(attention: AttentionPreview): string;

package/dist/attention-presentation.js

@@ -1,6 +1,5 @@
 import { homedir } from 'node:os';
 import { formatActivityId } from './square-core.js';
-import { participantCommandPrefix } from './presentation.js';
 export const ATTENTION_BODY_MAX = 200;
 export function previewAttentionBody(body) {
     const compact = body.replace(/\r\n/g, '\n');
@@ -16,12 +15,12 @@ export function displayAttentionPath(squarePath) {
         ? `~${squarePath.slice(homedir().length)}`
         : squarePath;
 }
-export function renderAttentionDescription({ actor, recipient, route }) {
+export function renderAttentionDescription({ actor, route }) {
     switch (route) {
-        case 'mention': return `${actor} spoke your name (${recipient})`;
-        case 'reply': return `${actor} answered you (${recipient})`;
-        case 'attention': return `${actor} spoke · you’re listening to ${actor}`;
-        case 'bell': return `${actor} rang the bell · everyone’s attention`;
+        case 'mention': return `${actor} spoke your name`;
+        case 'reply': return `${actor} answered you`;
+        case 'attention': return `${actor} spoke · you’re listening`;
+        case 'bell': return `${actor} rang the bell`;
     }
 }
 /** Full notification text for human-facing expansion, never the bounded model preview. */
@@ -31,7 +30,7 @@ export function renderAttentionFull(attention) {
 function renderAttentionBlock(attention, body) {
     return [
         '<square-activity>',
-        `· ${displayAttentionPath(attention.squarePath)} · ${formatActivityId(attention.actIndex)}`,
+        `· ${displayAttentionPath(attention.squarePath)} · ${attention.recipient} · ${formatActivityId(attention.actIndex)}`,
         `● ${renderAttentionDescription(attention)}`,
         '',
         body,
@@ -41,10 +40,8 @@ function renderAttentionBlock(attention, body) {
 export function renderAttentionPreview(attention) {
     return [
         renderAttentionBlock(attention, previewAttentionBody(attention.body)),
-        // A clipped body ends with the full command to read it all: a labeled caption, then the
-        // command bare on its own line so it can be copied and run as it is.
         ...(attentionBodyIsClipped(attention.body)
-            ? ['· clipped — read it all:', `${participantCommandPrefix(attention.squarePath, attention.recipient)} catch --id ${formatActivityId(attention.actIndex)}`]
+            ? ['· clipped — catch it to read the rest']
             : []),
     ].join('\n');
 }

package/dist/boundary-presentation.js

@@ -46,6 +46,7 @@ function renderBoundary(inbox) {
     const blocks = [];
     const complete = [];
     let omitted = 0;
+    const omission = (count) => `… ${count} more — catch up to read them`;
     for (const [index, entry] of queued.entries()) {
         const { membership, notification } = entry;
         const block = [
@@ -59,7 +60,7 @@ function renderBoundary(inbox) {
             }),
         ].join('\n');
         const omittedAfter = omitted + queued.length - index - 1;
-        const prospective = frameBoundary([...blocks, block, ...(omittedAfter > 0 ? [`… ${omittedAfter} ${omittedAfter === 1 ? 'notification' : 'notifications'} omitted.`] : [])]);
+        const prospective = frameBoundary([...blocks, block, ...(omittedAfter > 0 ? [omission(omittedAfter)] : [])]);
         if (prospective.length > CONTEXT_MAX) {
             omitted += 1;
             continue;
@@ -72,7 +73,7 @@ function renderBoundary(inbox) {
         });
     }
     return {
-        context: frameBoundary([...blocks, ...(omitted > 0 ? [`… ${omitted} ${omitted === 1 ? 'notification' : 'notifications'} omitted.`] : [])]),
+        context: frameBoundary([...blocks, ...(omitted > 0 ? [omission(omitted)] : [])]),
         complete,
     };
 }

package/dist/claude-mcp-context.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod/v4';
+declare const coordinate: z.ZodObject<{
+    toolUseId: z.ZodString;
+    sessionId: z.ZodString;
+    cwd: z.ZodString;
+    agentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ClaudeMcpCall = z.infer<typeof coordinate>;
+export declare function beginClaudeMcpCall(input: ClaudeMcpCall, env?: NodeJS.ProcessEnv): Promise<{
+    token: string;
+}>;
+export declare function endClaudeMcpCall(toolUseId: string, token: string, env?: NodeJS.ProcessEnv): Promise<void>;
+/** Expiry gates lookup only; an executing tool keeps its captured coordinate. */
+export declare function readClaudeMcpCall(toolUseId: unknown, env?: NodeJS.ProcessEnv): Promise<ClaudeMcpCall>;
+export {};

package/dist/claude-mcp-context.js

@@ -0,0 +1,82 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod/v4';
+import { withFileLock } from './file-lock.js';
+import { hostLedgerRoot } from './host-ledger-root.js';
+import { SquareError } from './model.js';
+const LEASE_MS = 10 * 60 * 1000;
+const text = z.string().max(4096).refine(value => value.trim().length > 0 && !/[\x00-\x1f\x7f]/u.test(value));
+const coordinate = z.object({
+    toolUseId: text, sessionId: text, cwd: text.refine(path.isAbsolute), agentId: text.optional(),
+});
+const record = coordinate.extend({ token: z.string().regex(/^[a-f0-9]{64}$/u), expiresAt: z.number() });
+const unavailable = () => new SquareError('unavailable', 'Claude MCP call context unavailable');
+const storeRoot = (env) => path.resolve(hostLedgerRoot(env), 'claude-mcp-calls');
+const callFile = (root, id) => path.join(root, `${createHash('sha256').update(id).digest('hex')}.json`);
+async function readRecord(file) {
+    try {
+        return record.parse(JSON.parse(await fs.readFile(file, 'utf8')));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw unavailable();
+    }
+}
+// Only publishers/cleanup mutate this private transport directory. Readers see an
+// immutable record via atomic rename, so they need neither a lock nor housekeeping.
+async function mutate(env, fn) {
+    const root = storeRoot(env);
+    await fs.mkdir(root, { recursive: true, mode: 0o700 });
+    await fs.chmod(root, 0o700);
+    return withFileLock(path.join(root, 'store.lock'), { retryMs: 10, signal: AbortSignal.timeout(2000) }, () => fn(root));
+}
+export async function beginClaudeMcpCall(input, env = process.env) {
+    const parsed = coordinate.safeParse(input);
+    if (!parsed.success)
+        throw unavailable();
+    return mutate(env, async (root) => {
+        const now = Date.now();
+        for (const name of await fs.readdir(root)) {
+            if (!/^[a-f0-9]{64}\.json$/u.test(name))
+                continue;
+            const file = path.join(root, name);
+            const old = await readRecord(file).catch(() => undefined);
+            if (old && old.expiresAt <= now)
+                await fs.unlink(file);
+        }
+        const file = callFile(root, parsed.data.toolUseId);
+        if (await readRecord(file))
+            throw unavailable();
+        const token = randomBytes(32).toString('hex');
+        const temporary = path.join(root, `${token}.tmp`);
+        try {
+            await fs.writeFile(temporary, JSON.stringify({ ...parsed.data, token, expiresAt: now + LEASE_MS }), { flag: 'wx', mode: 0o600 });
+            await fs.rename(temporary, file);
+        }
+        finally {
+            await fs.rm(temporary, { force: true });
+        }
+        return { token };
+    });
+}
+export async function endClaudeMcpCall(toolUseId, token, env = process.env) {
+    if (!text.safeParse(toolUseId).success || !text.safeParse(token).success)
+        throw unavailable();
+    await mutate(env, async (root) => {
+        const file = callFile(root, toolUseId);
+        const stored = await readRecord(file);
+        if (stored?.toolUseId === toolUseId && stored.token === token)
+            await fs.unlink(file);
+    });
+}
+/** Expiry gates lookup only; an executing tool keeps its captured coordinate. */
+export async function readClaudeMcpCall(toolUseId, env = process.env) {
+    if (!text.safeParse(toolUseId).success)
+        throw unavailable();
+    const stored = await readRecord(callFile(storeRoot(env), toolUseId));
+    if (!stored || stored.toolUseId !== toolUseId || stored.expiresAt <= Date.now())
+        throw unavailable();
+    return coordinate.parse(stored);
+}

package/dist/claude-mod.js

@@ -7,6 +7,7 @@ import { Square } from './square-application.js';
 import { observeClaudeDelivery } from './claude-delivery.js';
 import { processActNotificationsOnce } from './notifications.js';
 import { sweepPending } from './delivery-operations.js';
+import { beginClaudeMcpCall, endClaudeMcpCall } from './claude-mcp-context.js';
 /** JSON stdin bridge. Identity is explicit per operation; process.env is never rewritten. */
 export async function runClaudeMod(inputText, env = process.env) {
     if (inputText.length > 512_000)
@@ -14,6 +15,13 @@ export async function runClaudeMod(inputText, env = process.env) {
     const input = JSON.parse(inputText);
     if (!input || typeof input.sessionId !== 'string' || !input.sessionId || typeof input.cwd !== 'string')
         throw new Error('Claude bridge coordinate missing.');
+    if (input.operation === 'tool-begin') {
+        return `${JSON.stringify(await beginClaudeMcpCall({ toolUseId: input.toolUseId, sessionId: input.sessionId, cwd: input.cwd, agentId: input.agentId }, env))}\n`;
+    }
+    if (input.operation === 'tool-end') {
+        await endClaudeMcpCall(input.toolUseId, input.token, env);
+        return '{}\n';
+    }
     const scoped = operationEnv('claude', input.sessionId, env);
     const ledger = hostLedgerForEnv(env);
     const signal = AbortSignal.timeout(2500);

package/dist/cli/context.js

@@ -100,7 +100,6 @@ const LOCATION_REQUIRED_COMMANDS = new Set([
     'history',
     'status',
     'participants',
-    'mcp-server',
     'doctor',
     'migrate',
 ]);

package/dist/cli/maintenance-commands.js

@@ -1,5 +1,5 @@
 import { createSquareApplication } from '../square-application.js';
-import { renderDoctorClean, renderDoctorUnfixable, withPathOutput } from '../presentation.js';
+import { commandPrefix, renderDoctorClean, renderDoctorUnfixable, withPathOutput } from '../presentation.js';
 import { requireSquarePath, usage } from './context.js';
 export const migrateCommand = {
     parse(argv, context) {
@@ -32,7 +32,7 @@ export const doctorCommand = {
         const squarePath = requireSquarePath(context);
         const { data: diagnosis, projection } = await createSquareApplication({ cwd: context.cwd, env: context.env, squarePath }).diagnose();
         if (diagnosis.migrationRequired !== undefined) {
-            return { output: withPathOutput(squarePath, `${diagnosis.migrationRequired}\n`), exitCode: 2 };
+            return { output: withPathOutput(squarePath, `${diagnosis.migrationRequired}\n${commandPrefix(squarePath)} migrate\n`), exitCode: 2 };
         }
         if (diagnosis.unfixable !== undefined || diagnosis.standingCount === undefined) {
             return {

package/dist/cli/program.js

@@ -8,11 +8,17 @@ async function handleSquareError(error, context) {
         throw error;
     const detail = error.operation;
     const squarePath = context?.squarePath;
-    const recovery = context === undefined || squarePath === undefined ? undefined
+    const recovery = error.facts?.reason === 'migration_required' || context === undefined || squarePath === undefined ? undefined
         : await applicationFor({ ...context, name: detail?.participant ?? context.name }).recovery().catch(() => undefined);
     const name = detail?.participant ?? recovery?.data.participant ?? context?.name;
     const existing = [refusalText(error)];
-    if (squarePath !== undefined && name !== undefined && error.code === 'already_joined') {
+    if (error.facts?.reason === 'migration_required') {
+        if (error.facts.ledgerRoot !== undefined)
+            existing.push('square ledger migrate', 'square ledger verify');
+        else if (squarePath !== undefined)
+            existing.push(`${commandPrefix(squarePath)} migrate`);
+    }
+    else if (squarePath !== undefined && name !== undefined && error.code === 'already_joined') {
         existing.splice(0, 1, `✕ ${participantIdentity(name)} shoos you out of the square`, `  · ${participantIdentity(name)} already stands here — another session holds the name`);
         existing.push(...takeoverRecoveryLines(squarePath, name));
     }

package/dist/host-ledger-migration.js

@@ -5,7 +5,7 @@ import { DatabaseSync } from 'node:sqlite';
 import { canonicalPathSync } from './canonical-path.js';
 import { withFileLock } from './file-lock.js';
 import { hostLedgerRoot } from './host-ledger-root.js';
-import { LEDGER_FILENAME, initializeLedger, insertLedgerRecord, ledgerRecordColumns, setLedgerRevisions, upgradeLedger, validateLedger, verifyLedger, inspectLedgerIdentity, } from './host-ledger-sqlite.js';
+import { LEDGER_FILENAME, initializeLedger, insertLedgerRecord, ledgerRecordColumns, setLedgerRevisions, upgradeLedger, validateLedger, verifyLedger, inspectLedgerIdentity, migrationRequired, } from './host-ledger-sqlite.js';
 import { inSqliteTransaction } from './sqlite-transaction.js';
 function rootFor(options) {
     return canonicalPathSync(options.rootPath ?? hostLedgerRoot(options.env));
@@ -25,10 +25,6 @@ async function exists(file) {
         throw error;
     }
 }
-function migrationGuidance(root, file) {
-    const name = file ?? path.join(root, LEDGER_FILENAME);
-    return `Host ledger at ${root} has a supported older format (${name}).\nStop agent sessions and MCP services using Square with this ledger; keep them stopped until migration and verification succeed; then start them with the updated Square version.\nsquare ledger migrate\nsquare ledger verify`;
-}
 function verificationFailure(root, file, format) {
     const name = file ?? path.join(root, LEDGER_FILENAME);
     const detail = format === 'unsupported'
@@ -62,7 +58,7 @@ async function verifyDatabase(file, root, signal) {
             db = undefined;
         }
         if (format === 'old-sqlite')
-            throw new Error(migrationGuidance(root, file));
+            throw migrationRequired(root);
         throw verificationFailure(root, file, format);
     }
     finally {

package/dist/host-ledger-sqlite.js

@@ -3,7 +3,7 @@ import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { nameKey } from './model.js';
+import { SquareError, nameKey } from './model.js';
 import { inSqliteTransaction, retrySqliteBusy } from './sqlite-transaction.js';
 export const LEDGER_FILENAME = 'host-ledger.sqlite';
 export const LEDGER_APPLICATION_ID = 0x5351484c;
@@ -175,7 +175,7 @@ catch (error) {
     throw error;
 } }
 export function migrationRequired(root) {
-    return new Error(`Host ledger legacy format needs offline migration at ${root}.\nStop agent sessions and MCP services using Square with this ledger; keep them stopped until migration and verification succeed; then start them with the updated Square version.\nRun square ledger migrate from the same environment, then square ledger verify.`);
+    return new SquareError('invalid_args', `Host ledger at ${root} needs offline migration.\nStop sessions and MCP services using it, back it up, then migrate and verify from the same environment before restarting.`, { reason: 'migration_required', ledgerRoot: root });
 }
 /** Compact runtime framing. Full schema, projections and integrity belong to explicit verify. */
 function validateLedgerHeader(db, version = LEDGER_VERSION) {

package/dist/mcp.js

@@ -1,80 +1,51 @@
 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 { SQUARE_TOOLS, SQUARE_TOOL_INSTRUCTIONS, squareToolFailure } from './square-tools.js';
 import { operationEnv } from './automatic-session.js';
+import { readClaudeMcpCall } from './claude-mcp-context.js';
 import { SQUARE_IDENTITY } from './identity.js';
 import { createSquareApplication, createSquareResourceOwner } from './square-application.js';
-const activityId = z.string().regex(/^act\/(0|[1-9][0-9]*)$/);
-const stringArray = z.array(z.string());
-const participantName = z.string().optional().describe("Participant name, same as --as. Defaults to the server's configured participant.");
-const TOOL_DEFINITIONS = [
-    { name: 'join', description: 'Join the square as a participant.', inputSchema: z.object({ as: participantName, takeover: z.boolean().optional() }).strict() },
-    { name: 'express', description: 'Express a message or embodied action in the square.', inputSchema: z.object({ as: participantName, body: z.string(), mentions: stringArray.optional(), reach: z.enum(['bell']).optional(), reply: activityId.optional(), force: z.boolean().optional(), noWait: z.boolean().optional() }).strict() },
-    { name: 'catch', description: 'Catch and consume activities perceptible to the participant.', inputSchema: z.object({ as: participantName, id: activityId.optional(), idle: z.number().finite().min(0).optional(), from: stringArray.optional(), mention: z.boolean().optional(), limit: z.number().int().min(1).optional() }).strict() },
-    { name: 'history', description: 'Read the activity stream using stable activity-id cursors.', inputSchema: z.object({ limit: z.number().int().min(1).optional(), order: z.enum(['asc', 'desc']).optional(), before: activityId.optional(), after: activityId.optional(), grep: z.string().optional(), fixed: z.string().optional(), from: stringArray.optional(), mention: z.string().optional() }).strict() },
-    { name: 'listen', description: 'Listen for future activity from a participant.', inputSchema: z.object({ as: participantName, target: z.string() }).strict() },
-    { name: 'ignore', description: 'Stop listening for future activity from a participant.', inputSchema: z.object({ as: participantName, target: z.string() }).strict() },
-    { name: 'listening', description: 'List participants this participant is listening to.', inputSchema: z.object({ as: participantName }).strict() },
-    { name: 'hold', description: 'Raise a hand to hold the square.', inputSchema: z.object({ as: participantName, reason: z.string().optional() }).strict() },
-    { name: 'resume', description: 'Release the current hold.', inputSchema: z.object({ as: participantName }).strict() },
-    { name: 'done', description: 'Leave the square without adding a message.', inputSchema: z.object({ as: participantName }).strict() },
-    { name: 'status', description: 'Read the public status of the square.', inputSchema: z.object({}).strict() },
-    { name: 'participants', description: 'List participants standing in or done with the square.', inputSchema: z.object({}).strict() },
-];
-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(undefined, control);
-        case 'participants': return app.participants(control);
-        default: throw new SquareError('invalid_args', `Unknown tool: ${name}`);
-    }
-}
 export function createSquareMcpServer(options) {
     const baseEnv = { ...options.env };
     const resources = createSquareResourceOwner();
-    // One explicit lifetime for this server: every tool call borrows the same connection.
+    // Calls to the configured square borrow one server-owned connection.
     const inFlight = new Set();
     const server = new McpServer({ name: 'square', version: SQUARE_IDENTITY.packageVersion }, {
-        instructions: 'The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.',
+        instructions: SQUARE_TOOL_INSTRUCTIONS,
     });
-    for (const tool of TOOL_DEFINITIONS) {
+    for (const tool of SQUARE_TOOLS) {
         server.registerTool(tool.name, { description: tool.description, inputSchema: tool.inputSchema }, (args, extra) => {
             const call = (async () => {
                 try {
-                    const { as: participant, ...operationArgs } = args;
+                    const { as: participant, location } = args;
                     const threadId = extra._meta?.threadId;
                     const opencodeSessionId = extra._meta?.['ai.opencode/sessionID'];
-                    const env = typeof threadId === 'string' && threadId.trim()
-                        ? operationEnv('codex', threadId, baseEnv)
-                        : typeof opencodeSessionId === 'string' && opencodeSessionId.trim()
-                            ? operationEnv('opencode', opencodeSessionId, baseEnv)
-                            : baseEnv;
-                    const app = createSquareApplication({ ...options, env, participant: participant ?? options.participant, resources }, { presentation: false });
-                    const outcome = await operation(app, tool.name, operationArgs, { signal: extra.signal });
+                    // Claude's plugin endpoint requires the mod's call-local coordinate, never startup identity.
+                    const claude = baseEnv.SQUARE_CLAUDE_MCP_CONTEXT === '1'
+                        ? await readClaudeMcpCall(extra._meta?.['claudecode/toolUseId'], baseEnv)
+                        : undefined;
+                    const env = claude !== undefined
+                        ? { ...operationEnv('claude', claude.sessionId, baseEnv),
+                            // Preserve Claude's session + child flag semantics; an agent loop ID is not a session ID.
+                            CLAUDE_CODE_CHILD_SESSION: claude.agentId === undefined ? '' : '1' }
+                        : typeof threadId === 'string' && threadId.trim()
+                            ? operationEnv('codex', threadId, baseEnv)
+                            : typeof opencodeSessionId === 'string' && opencodeSessionId.trim()
+                                ? operationEnv('opencode', opencodeSessionId, baseEnv)
+                                : baseEnv;
+                    const app = createSquareApplication({
+                        ...options, env, cwd: claude?.cwd ?? options.cwd,
+                        squarePath: location ?? options.squarePath,
+                        participant: participant ?? options.participant,
+                        // The server owner is bound to its configured square; overrides close after each call.
+                        resources: location === undefined && claude === undefined ? resources : undefined,
+                    }, { presentation: false });
+                    const outcome = await tool.run(app, args, { signal: extra.signal });
                     const structuredContent = outcome.data;
                     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) };
-                    const operation = error instanceof Error ? error.operation : undefined;
-                    const failure = operation === undefined ? normalized : { ...normalized, operation };
+                    const failure = squareToolFailure(error, extra.signal);
                     return { isError: true, content: [{ type: 'text', text: JSON.stringify(failure) }], structuredContent: { error: failure } };
                 }
             })();

package/dist/model.d.ts

@@ -24,6 +24,8 @@ export interface SquareErrorFacts {
     reason?: 'never_joined' | 'not_standing' | 'bell_mention_conflict' | 'not_addressed' | 'migration_required' | 'explicit_reach_required' | 'invalid_reply' | 'invalid_done_body';
     /** The activity id a `catch --id` refusal named. */
     activityId?: string;
+    /** The host ledger requiring offline migration, rather than the selected artifact. */
+    ledgerRoot?: string;
     /** Requested recipient spellings, without parsing presentation copy. */
     targets?: readonly string[];
     /** Whether the artifact holds that activity at all; an unknown id needs an ordinary page. */

package/dist/square-sqlite.d.ts

@@ -25,17 +25,11 @@ export interface LegacyFraming {
     readonly userVersion: number;
     readonly journalMode: string;
 }
-/**
- * The one recovery command for an owned legacy artifact, with a shell-quoted
- * path. Kept beside framing recognition so the refusal and migration
- * instruction cannot drift apart. This codec stays free of the renderer.
- */
-export declare function migrationRecoveryCommand(location: string): string;
 /**
  * Read-only legacy framing: application id, format version, journal mode and the
  * exact owned snapshot schema. It decodes no snapshot payload, writes no pragma
- * and runs no DDL, so ordinary open can establish ownership before offering
- * the migration command. Anything else is unrelated or unsupported, not repaired.
+ * and runs no DDL, so ordinary open can establish ownership before requiring
+ * migration. Anything else is unrelated or unsupported, not repaired.
  */
 export declare function validateLegacyFraming(database: DatabaseSync, applicationId: number, location?: string): LegacyFraming;
 export declare const SCHEMA_SQL = "CREATE TABLE square_meta (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  revision INTEGER NOT NULL CHECK (revision BETWEEN 0 AND 9007199254740991),\n  next_act_index INTEGER NOT NULL CHECK (next_act_index BETWEEN 0 AND 9007199254740991),\n  hard_cap INTEGER CHECK (hard_cap BETWEEN 1 AND 9007199254740991),\n  throttle_per_minute INTEGER CHECK (throttle_per_minute BETWEEN 1 AND 9007199254740991),\n  preamble_json TEXT NOT NULL CHECK (json_valid(preamble_json)),\n  warmup_json TEXT NOT NULL CHECK (json_valid(warmup_json))\n);\nCREATE TABLE activities (\n  act_index INTEGER PRIMARY KEY CHECK (act_index BETWEEN 0 AND 9007199254740991),\n  at REAL NOT NULL,\n  kind TEXT NOT NULL CHECK (kind IN ('join','done','say','hold','resume','read','listen','ignore')),\n  actor_json TEXT COLLATE BINARY,\n  actor_key_json TEXT COLLATE BINARY,\n  reach TEXT CHECK (reach = 'bell'),\n  reply_index INTEGER CHECK (reply_index >= 0 AND reply_index < act_index),\n  payload_json TEXT NOT NULL CHECK (json_valid(payload_json)),\n  CHECK ((actor_json IS NULL) = (actor_key_json IS NULL)),\n  CHECK (kind IN ('hold','resume') OR actor_json IS NOT NULL),\n  CHECK (kind = 'say' OR (reach IS NULL AND reply_index IS NULL))\n);\nCREATE INDEX activity_kind_index ON activities(kind, act_index);\nCREATE INDEX activity_actor_index ON activities(actor_key_json, act_index);\nCREATE INDEX activity_say_actor_index ON activities(actor_key_json, act_index) WHERE kind='say';\nCREATE INDEX activity_say_time ON activities(at, act_index) WHERE kind='say';\nCREATE INDEX activity_bell_actor_time ON activities(actor_key_json, at, act_index) WHERE kind='say' AND reach='bell';\n\nCREATE TABLE receipts (\n  owner_json TEXT COLLATE BINARY NOT NULL,\n  act_index INTEGER NOT NULL CHECK (act_index BETWEEN 0 AND 9007199254740991),\n  at REAL NOT NULL,\n  PRIMARY KEY (owner_json, act_index)\n) WITHOUT ROWID;\nCREATE INDEX receipt_owner_time ON receipts(owner_json, at);\nCREATE TABLE catch_leases (\n  owner_json TEXT COLLATE BINARY PRIMARY KEY NOT NULL,\n  lease_id_json TEXT NOT NULL,\n  heartbeat_at REAL NOT NULL,\n  expires_at REAL NOT NULL CHECK (expires_at >= heartbeat_at),\n  filter_json TEXT CHECK (filter_json IS NULL OR json_valid(filter_json))\n) WITHOUT ROWID;\n\nCREATE TABLE routes (\n  position INTEGER PRIMARY KEY CHECK (position >= 0),\n  participant_key_json TEXT COLLATE BINARY NOT NULL,\n  session_json TEXT COLLATE BINARY NOT NULL,\n  kind TEXT NOT NULL CHECK (kind IN ('opencode-server','codex-queue','claude-native','paseo')),\n  updated_at REAL NOT NULL,\n  payload_json TEXT NOT NULL CHECK (json_valid(payload_json))\n);\nCREATE INDEX route_participant ON routes(participant_key_json, position);\nCREATE INDEX route_session ON routes(session_json, position);\n\nCREATE TABLE participants (\n  name_key_json TEXT COLLATE BINARY PRIMARY KEY NOT NULL,\n  name_json TEXT NOT NULL,\n  first_index INTEGER NOT NULL UNIQUE,\n  joined INTEGER NOT NULL CHECK (joined IN (0,1)),\n  done INTEGER NOT NULL CHECK (done IN (0,1)),\n  say_count INTEGER NOT NULL CHECK (say_count >= 0),\n  last_active_at REAL,\n  last_join_index INTEGER,\n  CHECK (NOT (joined=1 AND done=1))\n) WITHOUT ROWID;\nCREATE TABLE attention (\n  listener_key_json TEXT COLLATE BINARY NOT NULL,\n  target_key_json TEXT COLLATE BINARY NOT NULL,\n  target_json TEXT NOT NULL,\n  kind TEXT NOT NULL CHECK (kind IN ('listen','ignore')),\n  since_index INTEGER NOT NULL,\n  PRIMARY KEY (listener_key_json, target_key_json)\n) WITHOUT ROWID;\nCREATE INDEX attention_target ON attention(target_key_json, kind, listener_key_json);\nCREATE TABLE landed_audience (\n  act_index INTEGER NOT NULL,\n  recipient_key_json TEXT COLLATE BINARY NOT NULL,\n  recipient_order INTEGER NOT NULL CHECK (recipient_order >= 0),\n  route TEXT NOT NULL CHECK (route IN ('mention','reply','attention','bell')),\n  PRIMARY KEY (act_index, recipient_key_json),\n  UNIQUE (act_index, recipient_order)\n) WITHOUT ROWID;\nCREATE INDEX audience_recipient ON landed_audience(recipient_key_json, act_index);";

package/dist/square-sqlite.js

@@ -13,19 +13,11 @@ const V1_SNAPSHOT_COLUMNS = [
     { cid: 1, name: 'revision', type: 'INTEGER', notnull: 1, dflt_value: null, pk: 0, hidden: 0 },
     { cid: 2, name: 'state', type: 'TEXT', notnull: 1, dflt_value: null, pk: 0, hidden: 0 },
 ];
-/**
- * The one recovery command for an owned legacy artifact, with a shell-quoted
- * path. Kept beside framing recognition so the refusal and migration
- * instruction cannot drift apart. This codec stays free of the renderer.
- */
-export function migrationRecoveryCommand(location) {
-    return `square --location '${location.replace(/'/g, `'\\''`)}' migrate`;
-}
 /**
  * Read-only legacy framing: application id, format version, journal mode and the
  * exact owned snapshot schema. It decodes no snapshot payload, writes no pragma
- * and runs no DDL, so ordinary open can establish ownership before offering
- * the migration command. Anything else is unrelated or unsupported, not repaired.
+ * and runs no DDL, so ordinary open can establish ownership before requiring
+ * migration. Anything else is unrelated or unsupported, not repaired.
  */
 export function validateLegacyFraming(database, applicationId, location = '') {
     const identity = database.prepare('SELECT application_id, user_version FROM pragma_application_id, pragma_user_version').get();
@@ -328,7 +320,7 @@ export function validateSqliteHeader(db, location = '') {
     requireFact(identity.application_id === APPLICATION_ID, 'unrelated SQLite database.');
     if (identity.user_version === 1) {
         validateLegacyFraming(db, APPLICATION_ID, location);
-        throw new SquareError('invalid_args', `Square artifact needs migration.\n${migrationRecoveryCommand(location)}`, { reason: 'migration_required' });
+        throw new SquareError('invalid_args', `Square artifact at ${location} needs migration.\nStop sessions using it, back it up, then migrate and verify before restarting.`, { reason: 'migration_required' });
     }
     requireFact(identity.user_version === 2, 'unsupported SQLite format version.');
     const actual = db.prepare("SELECT sql FROM sqlite_schema WHERE name NOT GLOB 'sqlite_*' AND sql IS NOT NULL").all().map(r => normalizedSql(string(r.sql))).sort();

package/dist/square-tools.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod/v4';
+import type { ApplicationOutcome, OperationControl, SquareApplication } from './square-facade.js';
+type JsonObject = Record<string, unknown>;
+type Outcome = Promise<ApplicationOutcome<object, unknown, false>>;
+interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<z.ZodRawShape>;
+    run(app: SquareApplication<false>, args: JsonObject, control: OperationControl): Outcome;
+}
+export declare const SQUARE_TOOL_INSTRUCTIONS = "The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.";
+export declare const SQUARE_TOOLS: readonly ToolDefinition[];
+export declare function squareToolFailure(error: unknown, signal?: AbortSignal): JsonObject;
+export {};

package/dist/square-tools.js

@@ -0,0 +1,50 @@
+import { z } from 'zod/v4';
+import { isSquareError } from './model.js';
+const location = z.string().optional().describe('Path to the .square artifact, relative to the current working directory. Defaults to the configured square.');
+const participant = z.string().optional().describe('Participant name. Defaults to the configured participant or the current session’s unambiguous participant.');
+const activityId = z.string().regex(/^act\/(0|[1-9][0-9]*)$/);
+const stringArray = z.array(z.string());
+function tool(name, description, shape, run) {
+    const inputSchema = z.object({ ...shape, location }).strict();
+    return { name, description, inputSchema, run: (app, args, control) => {
+            const { location: _location, ...operationArgs } = inputSchema.parse(args);
+            return run(app, operationArgs, control);
+        } };
+}
+export const SQUARE_TOOL_INSTRUCTIONS = 'The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.';
+export const SQUARE_TOOLS = [
+    tool('join', 'Join the square as a participant.', { as: participant, takeover: z.boolean().optional().describe('Take the name from its current session owner.') }, (app, { takeover }, control) => app.join({ takeover }, control)),
+    tool('express', 'Express a message or embodied action in the square. Mentions and replies direct attention; bell reaches everyone. Bare activity is valid even with no listeners.', {
+        as: participant, body: z.string(), mentions: stringArray.optional(), reach: z.enum(['bell']).optional(),
+        reply: activityId.optional(), noMention: z.boolean().optional().describe('Disable body @name scanning; explicit mentions and reply still apply.'),
+        force: z.boolean().optional().describe('Speak without first catching unread activity or satisfying attention etiquette.'),
+        noWait: z.boolean().optional().describe('Return an error rather than waiting when held or throttled.'),
+    }, (app, { body, as: _participant, ...options }, control) => app.express(body, options, control)),
+    tool('catch', 'Catch and consume activities perceptible to the participant. idle waits for relevant activity or this many milliseconds of quiet; omitted means immediate. id catches one activity and cannot be combined with filters, idle or limit.', {
+        as: participant, id: activityId.optional(), idle: z.number().finite().min(0).optional(), from: stringArray.optional(),
+        mention: z.boolean().optional(), limit: z.number().int().min(1).optional(),
+    }, (app, { as: _participant, ...options }, control) => app.catch(options, control)),
+    tool('history', 'Read the activity stream without consuming it, using stable activity-id cursors. Default page size is 10, maximum 100. grep is a regex; fixed is literal text; use only one.', {
+        limit: z.number().int().min(1).optional(), order: z.enum(['asc', 'desc']).optional(), before: activityId.optional(), after: activityId.optional(),
+        grep: z.string().optional(), fixed: z.string().optional(), from: stringArray.optional(), mention: z.string().optional(),
+    }, (app, args, control) => app.history(args, control)),
+    tool('listen', 'Listen for future bare activity from a participant, clearing any ignore of them.', { as: participant, target: z.string() }, (app, { target }, control) => app.listen(target, control)),
+    tool('ignore', 'Block a participant’s future mentions and bare activity. Listening again clears the ignore; already landed activity is unchanged.', { as: participant, target: z.string() }, (app, { target }, control) => app.ignore(target, control)),
+    tool('listening', 'List participants this participant is listening to.', { as: participant }, (app, _args, control) => app.listening(control)),
+    tool('hold', 'Raise a hand to hold the square.', { as: participant, reason: z.string().optional() }, (app, { reason }, control) => app.hold(reason, control)),
+    tool('resume', 'Release the current hold.', { as: participant }, (app, _args, control) => app.resume(control)),
+    tool('done', 'Leave the square without adding a message.', { as: participant }, (app, _args, control) => app.done(undefined, control)),
+    tool('status', 'Read the public status of the square.', {}, (app, _args, control) => app.status(undefined, control)),
+    tool('participants', 'List participants standing in or done with the square.', {}, (app, _args, control) => app.participants(control)),
+];
+export function squareToolFailure(error, signal) {
+    const normalized = signal?.aborted
+        ? { code: 'cancelled', message: 'The Square operation was cancelled' }
+        : isSquareError(error)
+            ? { code: error.code, message: error.message, ...(error.facts === undefined ? {} : { facts: error.facts }) }
+            : error instanceof z.ZodError
+                ? { code: 'invalid_args', message: error.message }
+                : { code: 'internal', message: error instanceof Error ? error.message : String(error) };
+    const operation = error instanceof Error ? error.operation : undefined;
+    return operation === undefined ? normalized : { ...normalized, operation };
+}

package/guides/application-facade-design.md

@@ -81,7 +81,10 @@ Array-bearing results use object envelopes (`{activities}`, `{participants}`, `{
 - **Adapter boundary.** CLI/MCP reach storage, actions, decisions, views, wakes, list, stream, diagnosis/migration, inbox and notification execution only through `square-application.ts`. Private concern helpers retain their existing typed ports and internal dependencies; they are not callable from adapter execution paths.
 - **Facade.** `square-facade.ts` defines contracts; it must not derive contracts from `ReturnType`/`Awaited<ReturnType>` of private functions, and public activity IDs are formatted/parsed only by the existing core implementation.
 - **CLI (`cli/**`).** Owns argv/stdin, scoped help, shell quoting, sensory rendering/recovery, drafts, stdout/stderr, exit codes, SIGINT -> `AbortSignal` and stream backpressure. It maps returned classifications to copy/exit status, and preserves query argv in continuation commands; it cannot derive admission, commit certainty, terminal states or pagination eligibility from display text. File path display and draft-file I/O are allowed; opening an artifact or resolving ownership is not path formatting.
-- **MCP (`mcp.ts`).** Owns Zod schemas, registration, request-local `as`/`_meta.threadId`/session mapping, signal forwarding, JSON-RPC envelopes and stdio lifecycle. Request environment derivation stays immutable; no shared `process.env` writes and no invented session identity. Its method-name dispatch is a thin argument-to-method mapping, not a second policy dispatcher.
+- **Tools (`square-tools.ts`).** Owns shared Zod input schemas, descriptions and typed argument-to-facade calls for MCP and Pi. No session, environment, connection lifetime or business policy lives here.
+- **MCP (`mcp.ts`).** Owns registration, request-local `location`/`as`/metadata session mapping, signal forwarding, JSON-RPC envelopes and stdio lifecycle. Request environment derivation stays immutable; no shared `process.env` writes and no invented session identity.
+- **Claude mod (`plugins/claude/hooks/register.js`).** Owns the pending MCP call's identity association, publishing before `next(e)` and removing its exact token in `finally` through the existing native helper. `claude-mcp-context.ts` stores only transient transport coordinates, outside Square domain/artifact state. The bundled MCP adapter reads them using Claude's tool-use metadata; model-visible schemas contain no identity fields.
+- **Pi (`plugins/pi/square-pi.js`).** Registers the same operations as native codemode tools. Each call derives its identity and cwd from the live Pi context and uses the facade's per-operation connection lifetime. JSON schemas come from the shared Zod definitions; Pi has no separate parameter contract.
 - **Closed exceptions.** Harness install/uninstall/doctor, scoped help/version, meta commands and native hook input/output keep their existing protocol owners; that exception does not cover join, expression, catch, history, status, participants, build, stream, discovery, inbox, artifact doctor or migrate. Native changes stay limited to the required owner import migration.
 - **Storage/native scope.** SQLite schema/framing, artifact version, migration protocol, receipt model, ownership CAS, notification cancellation suppression and delivery eligibility rules are unchanged. Transactions stay synchronous and typed. The journaled amendment permits only build/create signal propagation through the existing adapter/storage/artifact retries and transactions, and captured-env propagation through default Codex wake construction/executable selection. A committed build is returned despite later cancellation; temporary-file cleanup does not reuse the aborted signal.
 

package/guides/claude-native.md

@@ -19,6 +19,35 @@ peer/plugin authority. Native OS-user socket permissions and Claude policy apply
 `square harness doctor delivery` derives current routes/evidence without sending.
 An absent/broken endpoint is unavailable; it does not consume Square activity.
 
+## MCP tools and call identity
+
+The plugin's `.mcp.json` starts the existing Square MCP server. The mod no longer
+registers an argv wrapper or executes participant CLI commands. MCP and Pi native
+tools share their operation definitions and facade calls in `square-tools.ts`.
+
+Before a bundled MCP call, the mod uses the existing `square claude-mod` helper
+to publish `{toolUseId, sessionId, cwd, agentId?}`. It then calls `next(e)` unchanged.
+The server correlates `_meta["claudecode/toolUseId"]` with that association: no
+session, agent, token or other transport field is added to the model's schema or
+arguments. Claude's native **session ID plus child flag** semantics are preserved;
+the child loop's `agentId` is retained for attribution, not substituted as a session ID.
+Calls use the live cwd and session even if the MCP process started earlier.
+
+`SQUARE_CLAUDE_MCP_CONTEXT=1` is set only by the bundled MCP configuration. That
+endpoint fails closed if an association is missing or expired; it never silently
+uses the startup parent identity. Generic MCP configurations retain their existing
+identity handling. The hook targets `mcp__plugin_square_square__*`, not unrelated
+servers with similar operation names.
+
+The mod owns publication and token-matched removal in `finally`; the server only
+reads. Associations are private, transient transport files under
+`<host-ledger-root>/claude-mcp-calls`, not Square domain state or another artifact.
+Normal completion/errors remove them. If abrupt cancellation, unload or a crash
+prevents cleanup, they expire after ten minutes and the next publication prunes
+them. Expiry gates lookup, not an operation that already captured its context.
+MCP owns operation cancellation and connection shutdown. No second execution
+protocol, resident service or ledger schema migration is introduced.
+
 ## Membership and lifecycle
 
 If `.square/PUBLIC.square` already exists, the mod joins the automatic participant.
@@ -46,7 +75,9 @@ old ends cannot retire that replacement. Unchanged reload preserves epochs.
 ## Body, admission, and presentation
 
 The coordinator uses Square's canonical audience projection and bounded body
-preview. A clipped preview ends with the full `catch --id act/<index>` command.
+preview. Each notification identifies the square, receiving participant and
+activity before its event and body. A clipped preview describes catching that
+activity to read it in full; it never embeds shell commands or tool-call syntax.
 Opaque text correlation resolves through bound memberships and the existing
 attempt ledger, never a path or asserted source from incoming text.