@astrosheep/square 0.3.94 → 0.3.96

package/dist/delivery-operations.js

@@ -5,6 +5,7 @@ import { asSeatRef } from './seats.js';
 import { freshWatchLease } from './runtime.js';
 import { deliveryDeferralExpiry } from './delivery-deferral.js';
 import { leaseOwnsNotification } from './delivery.js';
+import { dispatchEffect } from './delivery-effects.js';
 function routeFor(location, seat, now) {
     if (seat.attachment !== 'attached' || seat.wakeAddress === undefined)
         return undefined;
@@ -37,19 +38,6 @@ async function currentness(artifact, request, now) {
     });
     return value;
 }
-async function attemptWakeWithin(transport, request, timeoutMs, beforeSend) {
-    let timer;
-    const timeout = new Promise((resolve) => {
-        timer = setTimeout(() => resolve({ outcome: 'unknown', diagnostic: 'transport timeout' }), timeoutMs);
-    });
-    try {
-        return await Promise.race([transport.attempt(request, timeoutMs, beforeSend), timeout]);
-    }
-    finally {
-        if (timer !== undefined)
-            clearTimeout(timer);
-    }
-}
 async function candidates(artifact, requested, now = Date.now()) {
     const { value } = await artifact.read((facts) => {
         const heads = requested === undefined
@@ -62,12 +50,6 @@ async function candidates(artifact, requested, now = Date.now()) {
     });
     return value;
 }
-function releaseClaim(artifact, seat, activity, claimToken, signature, message, diagnostic) {
-    return artifact.completeDelivery({ seat, activity, claimToken, outcome: 'released', at: Date.now(), signature,
-        ...(message === undefined ? {} : { message }),
-        ...(diagnostic === undefined ? {} : { diagnostic: safeJson(diagnostic) }),
-    }).catch(() => false);
-}
 function safeJson(value) {
     if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number')
         return value;
@@ -115,55 +97,48 @@ export async function deliverPending(input) {
         }
         const claimToken = randomUUID();
         const leaseMs = input.timeoutMs ?? 5000;
-        const claim = await input.artifact.claimDelivery({ seat: request.seat, activity: request.activity, kind: 'wake',
-            route: seat.wakeAddress, at: input.now ?? Date.now(), leaseMs, claimToken }).catch(() => ({ status: 'stale' }));
-        if (claim.status !== 'acquired')
-            return;
-        const withClaim = { ...request, claimToken, attemptN: claim.attemptN };
-        let final;
-        let suppressed = false;
-        const beforeSend = async () => {
-            try {
-                final = await currentness(input.artifact, withClaim, input.now ?? Date.now());
-                suppressed = !final.current;
-            }
-            catch {
-                suppressed = true;
-            }
-            return !suppressed;
-        };
-        let before;
-        try {
-            before = await currentness(input.artifact, withClaim, input.now ?? Date.now());
-        }
-        catch { /* unverifiable */ }
-        if (!before?.current) {
-            await releaseClaim(input.artifact, request.seat, request.activity, claimToken, 'pre_send_revalidation_failed', before === undefined ? 'Square delivery state could not be verified.' : 'The notification is no longer current.', before);
-            return;
-        }
-        let outcome;
-        try {
-            outcome = await attemptWakeWithin(input.transport, withClaim, leaseMs, beforeSend);
-        }
-        catch (error) {
-            outcome = { outcome: 'unknown', diagnostic: error instanceof Error ? error.message : String(error) };
-        }
-        if (suppressed) {
-            await releaseClaim(input.artifact, request.seat, request.activity, claimToken, 'pre_send_revalidation_failed', 'The notification changed before the final send check.', final ?? { observationAvailable: false });
-            return;
-        }
-        if (outcome.outcome === 'not-capable') {
-            await releaseClaim(input.artifact, request.seat, request.activity, claimToken, 'transport_not_capable', undefined, outcome.diagnostic);
-            return;
-        }
-        const mapped = outcome.outcome === 'accepted' ? 'accepted'
-            : outcome.outcome === 'unknown' ? 'unknown' : 'failed';
-        await input.artifact.completeDelivery({ seat: request.seat, activity: request.activity, claimToken,
-            outcome: mapped, at: Date.now(),
-            ...('signature' in outcome && outcome.signature !== undefined ? { signature: outcome.signature } : {}),
-            ...('message' in outcome && outcome.message !== undefined ? { message: outcome.message } : {}),
-            ...('diagnostic' in outcome && outcome.diagnostic !== undefined ? { diagnostic: safeJson(outcome.diagnostic) } : {}),
-        }).catch(() => false);
+        let snapshot;
+        await dispatchEffect({
+            async claim() {
+                const claim = await input.artifact.claimDelivery({ seat: request.seat, activity: request.activity, kind: 'wake',
+                    route: seat.wakeAddress, at: input.now ?? Date.now(), leaseMs, claimToken }).catch(() => ({ status: 'stale' }));
+                return claim.status === 'acquired' ? { token: claimToken, ordinal: claim.attemptN } : undefined;
+            },
+            async current() {
+                snapshot = undefined;
+                snapshot = await currentness(input.artifact, request, input.now ?? Date.now());
+                return snapshot.current;
+            },
+            async settle(claim, completion) {
+                let fields = {};
+                if (completion.reason === 'not-current')
+                    fields = {
+                        signature: 'pre_send_revalidation_failed',
+                        message: completion.phase === 'final' ? 'The notification changed before the final send check.'
+                            : snapshot === undefined ? 'Square delivery state could not be verified.' : 'The notification is no longer current.',
+                        diagnostic: snapshot ?? (completion.phase === 'final' ? { observationAvailable: false } : undefined),
+                    };
+                else if (completion.reason === 'timeout')
+                    fields = { diagnostic: 'transport timeout' };
+                else if (completion.reason === 'threw')
+                    fields = { diagnostic: completion.error instanceof Error ? completion.error.message : String(completion.error) };
+                else if (completion.reason === 'not-capable')
+                    fields = {
+                        signature: 'transport_not_capable', diagnostic: completion.data?.diagnostic,
+                    };
+                else if (completion.reason === 'returned')
+                    fields = completion.data;
+                return input.artifact.completeDelivery({ seat: request.seat, activity: request.activity, claimToken: claim.token,
+                    outcome: completion.outcome, at: Date.now(),
+                    ...(fields.signature === undefined ? {} : { signature: fields.signature }),
+                    ...(fields.message === undefined ? {} : { message: fields.message }),
+                    ...(fields.diagnostic === undefined ? {} : { diagnostic: safeJson(fields.diagnostic) }),
+                }).catch(() => false);
+            },
+        }, async ({ claim, timeoutMs, beforeSend }) => {
+            const outcome = await input.transport.attempt({ ...request, claimToken: claim.token, attemptN: claim.ordinal }, timeoutMs, beforeSend);
+            return { outcome: outcome.outcome, data: outcome };
+        }, { timeoutMs: leaseMs });
     };
     const groups = receivers.values();
     const settled = await Promise.allSettled(Array.from({ length: Math.min(4, receivers.size) }, async () => {

package/dist/delivery-primitives.d.ts

@@ -0,0 +1,5 @@
+/** Storage-independent attempt transitions and bound effect lifecycles. */
+export { claimAttempt, prepareAttempt, settleAttempt, presentationBlocksDispatch, automaticDispatchEligible } from './delivery-attempts.js';
+export type { DeliveryPurpose, AttemptOutcome, Attempt, AttemptRows, AttemptClaim } from './delivery-attempts.js';
+export { dispatchEffect, preparePresentation, presentPrepared, presentPreparedBatch } from './delivery-effects.js';
+export type { EffectClaim, EffectPort, Persistence, Settlement, DispatchOutcome, DispatchCompletion, DispatchContext, DispatchReport, PresentationCompletion, PresentationWork, PreparedPresentation, PresentationControl, PresentationReport } from './delivery-effects.js';

package/dist/delivery-primitives.js

@@ -0,0 +1,3 @@
+/** Storage-independent attempt transitions and bound effect lifecycles. */
+export { claimAttempt, prepareAttempt, settleAttempt, presentationBlocksDispatch, automaticDispatchEligible } from './delivery-attempts.js';
+export { dispatchEffect, preparePresentation, presentPrepared, presentPreparedBatch } from './delivery-effects.js';

package/dist/delivery.d.ts

@@ -40,7 +40,7 @@ export declare function pendingPages(artifact: SquareArtifactPort, scan: Pending
     at: number;
     actor: string;
     recipient: string;
-    route: "bell" | "mention" | "reply" | "attention";
+    route: import("./attention.js").AudienceRoute;
 }[], void, unknown>;
 /** A pass retains only its captured joins; routes and individual receipts are fresh. */
 export declare function pendingFacts(facts: SquareRead, scan: PendingScan, heads: readonly DirectedHead[]): {

package/dist/delivery.js

@@ -1,6 +1,7 @@
 import { renderAttentionPreview, renderSquareReminder } from './attention-presentation.js';
 import { parseActivityId } from './square-core.js';
 import { deliveryDeferralExpiry } from './delivery-deferral.js';
+import { automaticDispatchEligible, presentationBlocksDispatch } from './delivery-attempts.js';
 import { matchesCatchSelection } from './catch-selection.js';
 /** Exact stored activity projection for transports that send an awareness reminder. */
 export function wakePreview(facts, request) {
@@ -13,19 +14,19 @@ export function wakePreview(facts, request) {
         return undefined;
     return renderSquareReminder([renderAttentionPreview({
             squarePath: request.location, recipient: request.participant, actIndex: item.index,
-            actor: item.actor, route: head.route, body: item.body ?? '(structured activity)',
-        })]);
+            actor: item.actor, route: head.route, body: item.body ?? '(structured activity)', delivery: item.delivery,
+        })], [item.delivery]);
+}
+function custody(evidence) {
+    return evidence.map(row => ({ purpose: row.kind === 'wake' ? 'dispatch' : 'presentation', outcome: row.outcome, expiresAt: row.expiresAt }));
 }
 /** Presentation custody blocks a wake, independently of native wake acceptance. */
 export function presentationBlocksWake(evidence, now) {
-    return evidence.some((row) => row.kind === 'presentation'
-        && (row.outcome === 'presented' || row.outcome === 'clipped' || row.outcome === 'unknown'
-            || row.outcome === 'dispatching' && (row.expiresAt === undefined || row.expiresAt > now)));
+    return presentationBlocksDispatch(custody(evidence), now);
 }
 /** Preselection only: an expired wake dispatch is uncertain, never safe automatic replay. */
 export function automaticWakeEligible(evidence, now) {
-    return !presentationBlocksWake(evidence, now) && !evidence.some((row) => row.kind === 'wake'
-        && (row.outcome === 'accepted' || row.outcome === 'unknown' || row.outcome === 'dispatching'));
+    return automaticDispatchEligible(custody(evidence), now);
 }
 /** Notification pending is not cursor suffix or historical catch membership. */
 export function pendingHead(facts, name, index) {

package/dist/help.js

@@ -32,7 +32,7 @@ const COMMANDS = [
             '',
             'Options:',
             '  -f, --force       Express without first catching unread activity or satisfying attention etiquette.',
-            '  --no-wait         If held or throttled, save a draft and return instead of waiting. A held wait gives up on its own after 10 minutes.',
+            '  --no-wait         If throttled, save a draft and return instead of waiting.',
             '  --metadata <json> Attach a bounded JSON object (at most 16 KiB UTF-8 and 256 nesting levels); it may be the only content.',
             '                    Metadata is returned in structured activity results but is not shown in human text or searchable.',
         ],
@@ -70,8 +70,6 @@ const COMMANDS = [
         summary: 'Show the participant roster and current states.',
         details: ['Options:', '  --limit <count>  Show the first count names in human text (default 20, maximum 100).'],
     },
-    { names: ['hold'], usage: '--as <name> hold [reason | -]', usesSquare: true, group: 'participant', summary: 'Raise a hand and pause participant activity.' },
-    { names: ['resume'], usage: '--as <name> resume', usesSquare: true, group: 'participant', summary: 'Lower the raised hand and resume activity.' },
     {
         names: ['install'], usage: 'install (--all | <target>...) [-f]', group: 'maintenance',
         summary: 'Install Square support for one or more agent hosts.',
@@ -94,7 +92,7 @@ const COMMANDS = [
     {
         names: ['migrate'], usage: 'migrate', usesSquare: true, group: 'maintenance',
         summary: 'Convert a supported older square to the current format in place.',
-        details: ['For the selected .square artifact only. Stop sessions using this artifact before conversion. Back up the stopped artifact, migrate it, then run square --location <path> doctor before starting updated clients.', 'Versions 2–6 migrate explicitly to format 7; format 6 attachment is preserved and Body coordinates become opaque owners. Versions 4/5 first gain attached seats; 4 also gains empty deferrals. Version 1, unrelated or unsupported artifacts refuse without a write. Names whose legacy owner and routes agree may share an owner; ambiguous names stay standing without custody. Rejoin with the same owner after migration to republish discovery. There is no --check, --backup or --force.'],
+        details: ['For the selected .square artifact only. Stop sessions using this artifact before conversion. Back up the stopped artifact, migrate it, then run square --location <path> doctor before starting updated clients.', 'Versions 2–7 migrate explicitly to format 8. Format 7 migration deletes hold/resume activities and their keyed rows, clears replies to those activities, and preserves surviving activity ids with gaps. Format 6 attachment and opaque-owner conversion are preserved; versions 4/5 first gain attached seats, and 4 also gains empty deferrals. Version 1, unrelated or unsupported artifacts refuse without a write. Names whose legacy owner and routes agree may share an owner; ambiguous names stay standing without custody. Rejoin with the same owner after migration to republish discovery. There is no --check, --backup or --force.'],
     },
 ];
 function definitionFor(command) {
@@ -105,7 +103,7 @@ function isHelpFlag(value) {
 }
 export function renderGlobalHelp() {
     const groups = [
-        { key: 'participant', title: 'In the square:', order: ['join', 'express', 'listen', 'unlisten', 'ignore', 'listening', 'catch', 'history', 'status', 'hold', 'resume', 'done'] },
+        { key: 'participant', title: 'In the square:', order: ['join', 'express', 'listen', 'unlisten', 'ignore', 'listening', 'catch', 'history', 'status', 'done'] },
         { key: 'host', title: 'Prepare and manage:', order: ['build', 'list', 'participants'] },
         { key: 'maintenance', title: 'Setup:', order: ['install', 'uninstall', 'doctor', 'migrate'] },
     ];
@@ -121,7 +119,7 @@ export function renderGlobalHelp() {
         'Usage: square [--location <square>] [--as <name>] [--owner <id>] <command> [args...]',
         'Environment: SQUARE_LOCATION sets the CLI local artifact path; square-accessing commands require it or --location. Use --as to select a participant.',
         'Identity: --owner overrides SQUARE_OWNER, then a complete harness identity, then user:<OS user>@<host>. Incomplete or ambiguous harness identities refuse. Owners without wake use catch --idle.',
-        'Output: --json on join, express, catch, history, listen, ignore, unlisten, listening, hold, resume, done, status, participants and inbox prints the SDK result without observation; a participant handle becomes {name}.',
+        'Output: --json on join, express, catch, history, listen, ignore, unlisten, listening, done, status, participants and inbox prints the SDK result without observation; a participant handle becomes {name}.',
         'History emits one JSON document; stream --ndjson emits one SDK record per line.',
         '',
         ...commandLines,

package/dist/http-delivery.d.ts

@@ -0,0 +1,16 @@
+import type { WakeRoute } from './model.js';
+import type { WakeOutcome, WakeRequest, WakeTransportPort } from './ports.js';
+export interface HttpWakeTransportOptions {
+    fetch?: typeof fetch;
+    env?: NodeJS.ProcessEnv;
+}
+/** HTTP accepts wake custody only; it never consumes or presents Square activity. */
+export declare class HttpWakeTransport implements WakeTransportPort {
+    private readonly opts;
+    constructor(opts?: HttpWakeTransportOptions);
+    probe(route: WakeRoute): Promise<boolean | {
+        outcome: 'not-capable';
+        diagnostic: string;
+    }>;
+    attempt(request: WakeRequest, timeoutMs: number, beforeSend: () => Promise<boolean>): Promise<WakeOutcome>;
+}

package/dist/http-delivery.js

@@ -0,0 +1,101 @@
+import { wakePreview } from './delivery.js';
+/** Configuration only: probing never contacts the receiver. */
+function configuration(route, env) {
+    if (route.kind !== 'http')
+        return undefined;
+    try {
+        const url = new URL(route.address.url);
+        if (!['http:', 'https:'].includes(url.protocol) || !url.hostname || url.username || url.password
+            || route.address.url.includes('#'))
+            return undefined;
+        const headers = new Headers({ 'Content-Type': 'application/json' });
+        const tokenEnv = route.address.tokenEnv;
+        if (tokenEnv !== undefined) {
+            const token = tokenEnv.trim() ? env[tokenEnv] : undefined;
+            // RFC 6750 bearer credentials; whitespace/control characters cannot become headers.
+            if (!token || token !== token.trim() || !/^[A-Za-z0-9._~+\/-]+=*$/.test(token))
+                return undefined;
+            headers.set('Authorization', `Bearer ${token}`);
+        }
+        return { url: route.address.url, headers };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** HTTP accepts wake custody only; it never consumes or presents Square activity. */
+export class HttpWakeTransport {
+    opts;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    async probe(route) {
+        return configuration(route, this.opts.env ?? process.env) !== undefined
+            ? true : { outcome: 'not-capable', diagnostic: 'HTTP wake configuration unavailable.' };
+    }
+    async attempt(request, timeoutMs, beforeSend) {
+        const deadline = Date.now() + timeoutMs;
+        if (request.route.kind !== 'http')
+            return { outcome: 'not-capable' };
+        const config = configuration(request.route, this.opts.env ?? process.env);
+        if (config === undefined)
+            return { outcome: 'failed', signature: 'http_config_rejected', message: 'Invalid HTTP wake configuration.' };
+        const controller = new AbortController();
+        let sent = false;
+        const budgetUnavailable = () => sent
+            ? { outcome: 'unknown', signature: 'http_send_timeout', message: 'HTTP wake acceptance is unknown after timeout.' }
+            : { outcome: 'failed', signature: 'http_pre_send_timeout', message: 'HTTP wake budget elapsed before sending.' };
+        if (!Number.isFinite(timeoutMs) || Date.now() >= deadline)
+            return budgetUnavailable();
+        let timer;
+        const timeout = new Promise(resolve => {
+            timer = setTimeout(() => { controller.abort(); resolve(budgetUnavailable()); }, Math.max(0, deadline - Date.now()));
+        });
+        const send = async () => {
+            try {
+                const preview = request.artifact === undefined ? undefined
+                    : (await request.artifact.read(facts => wakePreview(facts, request), controller.signal)).value;
+                if (preview === undefined)
+                    return { outcome: 'not-capable', diagnostic: 'No pending Square activity to preview.' };
+                const body = JSON.stringify({
+                    location: request.location, participant: request.participant, activity: request.activity, actor: request.actor,
+                    ...(request.attemptN === undefined ? {} : { attemptN: request.attemptN }), preview,
+                });
+                if (controller.signal.aborted || Date.now() >= deadline)
+                    return budgetUnavailable();
+                if (!(await beforeSend()))
+                    return { outcome: 'not-capable' };
+                // Preview and the final gate spend the same absolute budget as the request.
+                if (controller.signal.aborted || Date.now() >= deadline)
+                    return budgetUnavailable();
+                sent = true;
+                const response = await (this.opts.fetch ?? fetch)(config.url, {
+                    method: 'POST', headers: config.headers, body, redirect: 'manual', signal: controller.signal,
+                });
+                // Status is the whole acknowledgement; never wait for or buffer a receiver body.
+                void response.body?.cancel().catch(() => undefined);
+                if (response.status >= 200 && response.status < 300)
+                    return { outcome: 'accepted', signature: 'http_accepted' };
+                return {
+                    outcome: 'failed', signature: response.status >= 500 && response.status < 600 ? 'http_status_transient' : 'http_status_rejected',
+                    message: `HTTP wake returned status ${response.status}.`,
+                };
+            }
+            catch {
+                // URLs, query credentials and raw fetch exceptions must never reach evidence.
+                if (controller.signal.aborted)
+                    return budgetUnavailable();
+                return sent
+                    ? { outcome: 'unknown', signature: 'http_send_unknown', message: 'HTTP wake acceptance is unknown after a network error.' }
+                    : { outcome: 'failed', signature: 'http_pre_send_failed', message: 'HTTP wake could not be prepared.' };
+            }
+        };
+        try {
+            return await Promise.race([send(), timeout]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+}

package/dist/inbox.js

@@ -149,6 +149,7 @@ async function projectPending(candidates, cache, signal) {
                     cached = { coordinate, version: header.revision, value: locatedSeats(facts, location, seats).map(membership => ({
                             ...membership, notifications: pendingNotifications(facts, membership.seat.participant).map(({ item, route }) => ({
                                 actIndex: item.index, actor: item.actor, at: item.at, body: item.body ?? '(structured activity)', route,
+                                ...(item.delivery === undefined ? {} : { delivery: item.delivery }),
                             })),
                         })) };
                 }
@@ -197,7 +198,8 @@ export function nativePendingPreview(facts, input) {
     if (item?.kind !== 'say' || deliveryDeferralExpiry(facts, seat, input.actIndex, input.now) !== undefined)
         return undefined;
     return { payload: renderSquareReminder([renderAttentionPreview({ squarePath: input.location, recipient: input.participant, actIndex: item.index,
-                actor: item.actor, route: head.route, body: item.body ?? '(structured activity)' })]), clipped: attentionBodyIsClipped(item.body ?? '(structured activity)') };
+                actor: item.actor, route: head.route, body: item.body ?? '(structured activity)', delivery: item.delivery })], [item.delivery]),
+        clipped: attentionBodyIsClipped(item.body ?? '(structured activity)', item.delivery) };
 }
 export async function sessionInbox(owner, env = process.env, signal) {
     return projectPending(await projectSessionCandidates({ owner, env }), undefined, signal);

package/dist/mcp.js

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { SQUARE_TOOLS, SQUARE_TOOL_INSTRUCTIONS, squareToolFailure, squareToolFailureText } from './square-tools.js';
+import { SQUARE_TOOLS, SQUARE_TOOL_INSTRUCTIONS, squareToolsEnabled, squareToolFailure, squareToolFailureText } from './square-tools.js';
 import { operationEnv } from './participant-identity.js';
 import { codexWakeAddress } from './codex-address.js';
 import { readClaudeMcpCall } from './claude-mcp-context.js';
@@ -10,76 +10,78 @@ import { harnessOwner } from './square-api.js';
 export function createSquareMcpServer(options) {
     const { owner: configuredOwner, wakeAddress, ...resourceOptions } = options;
     const baseEnv = { ...(resourceOptions.env ?? process.env) };
+    const toolsEnabled = squareToolsEnabled(baseEnv);
     const resources = createSquareResourceOwner();
     // 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: SQUARE_TOOL_INSTRUCTIONS,
+        ...(toolsEnabled ? { instructions: SQUARE_TOOL_INSTRUCTIONS } : {}),
     });
-    for (const tool of SQUARE_TOOLS) {
-        server.registerTool(tool.name, { description: tool.description, inputSchema: tool.inputSchema }, (args, extra) => {
-            const call = (async () => {
-                let square;
-                try {
-                    const { location } = args;
-                    const threadId = extra._meta?.threadId;
-                    const opencodeSessionId = extra._meta?.['ai.opencode/sessionID'];
-                    // 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 owner = claude !== undefined
-                        ? harnessOwner({ channel: 'claude-code', session: claude.sessionId, ...(claude.agentId === undefined ? {} : { agent: claude.agentId }) })
-                        : typeof threadId === 'string' && threadId.trim()
-                            ? harnessOwner({ channel: 'codex', session: threadId })
-                            : typeof opencodeSessionId === 'string' && opencodeSessionId.trim()
-                                ? harnessOwner({ channel: 'opencode', session: opencodeSessionId })
-                                : configuredOwner;
-                    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;
-                    square = await Square.at({
-                        ...resourceOptions, env, cwd: claude?.cwd ?? resourceOptions.cwd,
-                        path: location ?? options.path,
-                        // The server owner is bound to its configured square; overrides close after each call.
-                        resources: location === undefined && claude === undefined ? resources : undefined,
-                    }, { signal: extra.signal });
-                    const callWake = wakeAddress !== undefined && (owner === configuredOwner
-                        || wakeAddress.kind === 'paseo' && wakeAddress.address.agentId === baseEnv.PASEO_AGENT_ID
-                        || wakeAddress.kind === 'claude-native' && wakeAddress.address.sessionId === claude?.sessionId
-                        || wakeAddress.kind === 'opencode-server' && wakeAddress.address.sessionId === opencodeSessionId)
-                        ? wakeAddress : undefined;
-                    let text;
+    if (toolsEnabled)
+        for (const tool of SQUARE_TOOLS) {
+            server.registerTool(tool.name, { description: tool.description, inputSchema: tool.inputSchema }, (args, extra) => {
+                const call = (async () => {
+                    let square;
                     try {
-                        text = await tool.run(square, args, { signal: extra.signal }, {
-                            owner, wakeAddress: claude === undefined && typeof threadId === 'string' && threadId.trim()
-                                ? codexWakeAddress(threadId, env) : callWake,
-                        });
+                        const { location } = args;
+                        const threadId = extra._meta?.threadId;
+                        const opencodeSessionId = extra._meta?.['ai.opencode/sessionID'];
+                        // 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 owner = claude !== undefined
+                            ? harnessOwner({ channel: 'claude-code', session: claude.sessionId, ...(claude.agentId === undefined ? {} : { agent: claude.agentId }) })
+                            : typeof threadId === 'string' && threadId.trim()
+                                ? harnessOwner({ channel: 'codex', session: threadId })
+                                : typeof opencodeSessionId === 'string' && opencodeSessionId.trim()
+                                    ? harnessOwner({ channel: 'opencode', session: opencodeSessionId })
+                                    : configuredOwner;
+                        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;
+                        square = await Square.at({
+                            ...resourceOptions, env, cwd: claude?.cwd ?? resourceOptions.cwd,
+                            path: location ?? options.path,
+                            // The server owner is bound to its configured square; overrides close after each call.
+                            resources: location === undefined && claude === undefined ? resources : undefined,
+                        }, { signal: extra.signal });
+                        const callWake = wakeAddress !== undefined && (owner === configuredOwner
+                            || wakeAddress.kind === 'paseo' && wakeAddress.address.agentId === baseEnv.PASEO_AGENT_ID
+                            || wakeAddress.kind === 'claude-native' && wakeAddress.address.sessionId === claude?.sessionId
+                            || wakeAddress.kind === 'opencode-server' && wakeAddress.address.sessionId === opencodeSessionId)
+                            ? wakeAddress : undefined;
+                        let text;
+                        try {
+                            text = await tool.run(square, args, { signal: extra.signal }, {
+                                owner, wakeAddress: claude === undefined && typeof threadId === 'string' && threadId.trim()
+                                    ? codexWakeAddress(threadId, env) : callWake,
+                            });
+                        }
+                        finally {
+                            await square.close();
+                        }
+                        return { content: [{ type: 'text', text }] };
                     }
-                    finally {
-                        await square.close();
+                    catch (error) {
+                        const failure = squareToolFailure(error, extra.signal);
+                        const participant = args.as;
+                        return { isError: true, content: [{ type: 'text', text: squareToolFailureText(failure, {
+                                        location: square?.location ?? options.path,
+                                        participant: typeof participant === 'string' ? participant : undefined,
+                                    }) }] };
                     }
-                    return { content: [{ type: 'text', text }] };
-                }
-                catch (error) {
-                    const failure = squareToolFailure(error, extra.signal);
-                    const participant = args.as;
-                    return { isError: true, content: [{ type: 'text', text: squareToolFailureText(failure, {
-                                    location: square?.location ?? options.path,
-                                    participant: typeof participant === 'string' ? participant : undefined,
-                                }) }] };
-                }
-            })();
-            inFlight.add(call);
-            return call.finally(() => { inFlight.delete(call); });
-        });
-    }
+                })();
+                inFlight.add(call);
+                return call.finally(() => { inFlight.delete(call); });
+            });
+        }
     const close = server.close.bind(server);
     // One idempotent shutdown for both close paths: an explicit server.close() and a
     // transport-initiated disconnect, where the SDK protocol fires onclose by itself.

package/dist/model.d.ts

@@ -1,12 +1,17 @@
 import type { Act, ActivityId } from './square-core.js';
 export { formatActivityId, parseActivityId } from './square-core.js';
 export type { Act, ActivityId, Audience, Reach } from './square-core.js';
-export declare const WAKE_ROUTE_KINDS: readonly ["opencode-server", "codex-queue", "claude-native", "paseo"];
+export declare const WAKE_ROUTE_KINDS: readonly ["opencode-server", "codex-queue", "claude-native", "paseo", "http"];
 export type WakeRouteKind = typeof WAKE_ROUTE_KINDS[number];
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
 };
 export type ActivityMetadata = Readonly<Record<string, JsonValue>>;
+export interface ActivityDelivery {
+    readonly mode: 'direct';
+    readonly preview?: string;
+}
+export declare function validateActivityDelivery(value: unknown): ActivityDelivery | undefined;
 export declare const ACTIVITY_METADATA_MAX_BYTES: number;
 export declare const ACTIVITY_METADATA_MAX_DEPTH = 256;
 /** Validate the bounded, lossless JSON object carried by a say. */
@@ -41,7 +46,7 @@ export interface WakeRoute {
     address: Record<string, string>;
     updatedAt: number;
 }
-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 SquareErrorCode = 'invalid_name' | 'invalid_args' | 'unknown_participant' | 'not_joined' | 'already_joined' | 'already_done' | 'capped' | 'throttled' | 'bell_quota' | 'behind' | 'io' | 'unavailable';
 export type InternalSquareErrorCode = SquareErrorCode | 'not_found' | 'cap_reached' | 'conflict' | 'pending_peer';
 export interface SquareErrorFacts {
     /** Copyable recovery for a missing, detached or foreign seat. */
@@ -59,8 +64,6 @@ export interface SquareErrorFacts {
     /** Whether the artifact holds that activity at all; an unknown id needs an ordinary page. */
     activityExists?: boolean;
     pending?: number;
-    holder?: string;
-    holdReason?: string;
     retryAfterMs?: number;
 }
 declare class SquareErrorBase<Code extends string> extends Error {
@@ -100,13 +103,14 @@ export interface WatchLease {
     expiresAt: number;
     filter?: WatchLeaseFilter;
 }
-export type DirectedNotificationRoute = 'mention' | 'reply' | 'attention' | 'bell';
+export type DirectedNotificationRoute = import('./attention.js').AudienceRoute;
 export interface InboxNotification {
     actIndex: number;
     actor: string;
     at: number;
     route: DirectedNotificationRoute;
     body: string;
+    readonly delivery?: ActivityDelivery;
 }
 export interface LocatedSeat {
     readonly location: string;
@@ -127,7 +131,7 @@ export type PublicAct = Extract<StoredAct, {
     kind: 'say' | 'done';
 }>;
 export type RoomChangeAct = Extract<StoredAct, {
-    kind: 'join' | 'done' | 'hold' | 'resume' | 'listen' | 'ignore' | 'unlisten';
+    kind: 'join' | 'done' | 'listen' | 'ignore' | 'unlisten';
 }>;
 export declare function formatHardCap(hardCap: HardCap): string;
 export declare function parseParticipantList(value: string): string[];

package/dist/model.js

@@ -1,6 +1,25 @@
 // Shared model and constants for Square.
 export { formatActivityId, parseActivityId } from './square-core.js';
-export const WAKE_ROUTE_KINDS = ['opencode-server', 'codex-queue', 'claude-native', 'paseo'];
+export const WAKE_ROUTE_KINDS = ['opencode-server', 'codex-queue', 'claude-native', 'paseo', 'http'];
+export function validateActivityDelivery(value) {
+    if (value === undefined)
+        return undefined;
+    if (value !== null && typeof value === 'object'
+        && [Object.prototype, null].includes(Object.getPrototypeOf(value))
+        && Object.getOwnPropertySymbols(value).length === 0) {
+        const keys = Object.getOwnPropertyNames(value);
+        const mode = Object.getOwnPropertyDescriptor(value, 'mode');
+        const preview = Object.getOwnPropertyDescriptor(value, 'preview');
+        if (mode?.enumerable && 'value' in mode && mode.value === 'direct') {
+            if (keys.length === 1)
+                return { mode: 'direct' };
+            if (keys.length === 2 && preview?.enumerable && 'value' in preview
+                && typeof preview.value === 'string' && preview.value.trim() !== '')
+                return { mode: 'direct', preview: preview.value };
+        }
+    }
+    throw new SquareError('invalid_args', "Activity delivery must be { mode: 'direct', preview?: string }.");
+}
 export const ACTIVITY_METADATA_MAX_BYTES = 16 * 1024;
 export const ACTIVITY_METADATA_MAX_DEPTH = 256;
 /** Validate the bounded, lossless JSON object carried by a say. */