@astrosheep/square 0.3.95 → 0.3.96

package/dist/attention-presentation.d.ts

@@ -1,4 +1,4 @@
-import type { DirectedNotificationRoute } from './model.js';
+import type { ActivityDelivery, DirectedNotificationRoute } from './model.js';
 export declare const ATTENTION_BODY_MAX = 200;
 export interface AttentionPreview {
     squarePath: string;
@@ -7,13 +7,14 @@ export interface AttentionPreview {
     actor: string;
     route: DirectedNotificationRoute;
     body: string;
+    delivery?: ActivityDelivery;
 }
-export declare function previewAttentionBody(body: string): string;
-export declare function attentionBodyIsClipped(body: string): boolean;
+export declare function previewAttentionBody(body: string, delivery?: ActivityDelivery): string;
+export declare function attentionBodyIsClipped(body: string, delivery?: ActivityDelivery): boolean;
 export declare function displayAttentionPath(squarePath: string): 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;
 /** Shared model-facing envelope; transport correlation and human cards stay outside it. */
-export declare function renderSquareReminder(previews: readonly string[]): string;
+export declare function renderSquareReminder(previews: readonly string[], deliveries?: readonly (ActivityDelivery | undefined)[]): string;
 export declare function renderAttentionPreview(attention: AttentionPreview): string;

package/dist/attention-presentation.js

@@ -1,14 +1,16 @@
 import { homedir } from 'node:os';
 import { formatActivityId } from './square-core.js';
 export const ATTENTION_BODY_MAX = 200;
-export function previewAttentionBody(body) {
-    const compact = body.replace(/\r\n/g, '\n');
-    if (compact.length <= ATTENTION_BODY_MAX)
+export function previewAttentionBody(body, delivery) {
+    const compact = (delivery?.mode === 'direct' ? delivery.preview ?? body : body).replace(/\r\n/g, '\n');
+    if (delivery?.mode === 'direct' || compact.length <= ATTENTION_BODY_MAX)
         return compact;
     return `${compact.slice(0, ATTENTION_BODY_MAX).trimEnd()}…`;
 }
-export function attentionBodyIsClipped(body) {
-    return body.replace(/\r\n/g, '\n').length > ATTENTION_BODY_MAX;
+export function attentionBodyIsClipped(body, delivery) {
+    return delivery?.mode === 'direct'
+        ? delivery.preview !== undefined
+        : body.replace(/\r\n/g, '\n').length > ATTENTION_BODY_MAX;
 }
 export function displayAttentionPath(squarePath) {
     return squarePath.startsWith(homedir())
@@ -25,7 +27,7 @@ export function renderAttentionDescription({ actor, route }) {
 }
 /** Full notification text for human-facing expansion, never the bounded model preview. */
 export function renderAttentionFull(attention) {
-    return renderAttentionBlock(attention, attention.body);
+    return attention.delivery?.mode === 'direct' ? renderDirectBlock(attention) : renderAttentionBlock(attention, attention.body);
 }
 /** Attribute values keep their quotes; the stored body and the human card stay unescaped. */
 function escapeAttribute(value) {
@@ -49,14 +51,20 @@ function renderAttentionBlock(attention, body) {
         '</square-activity>',
     ].join('\n');
 }
+function renderDirectBlock(attention) {
+    return escapeSquareTags(previewAttentionBody(attention.body, attention.delivery));
+}
 /** Shared model-facing envelope; transport correlation and human cards stay outside it. */
-export function renderSquareReminder(previews) {
+export function renderSquareReminder(previews, deliveries = []) {
     if (previews.length === 0)
         return '';
+    const header = deliveries.some(item => item?.mode === 'direct')
+        ? 'This is an external notification, not a direct message from the user.'
+        : 'This is an external reminder from Square, not a direct message from the user.';
     return [
         '',
         '<system-reminder>',
-        'This is an external reminder from Square, not a direct message from the user.',
+        header,
         '',
         previews.join('\n\n'),
         '</system-reminder>',
@@ -64,6 +72,8 @@ export function renderSquareReminder(previews) {
     ].join('\n');
 }
 export function renderAttentionPreview(attention) {
+    if (attention.delivery?.mode === 'direct')
+        return renderDirectBlock(attention);
     const remaining = attention.body.replace(/\r\n/g, '\n').length - ATTENTION_BODY_MAX;
     const attributes = [
         `square="${escapeAttribute(displayAttentionPath(attention.squarePath))}"`,

package/dist/boundary-presentation.js

@@ -14,10 +14,13 @@ export function renderPendingAtBoundary(inbox) {
 function renderBoundary(inbox) {
     const queued = inbox.flatMap((membership) => membership.notifications.map((notification) => ({ membership, notification })));
     const blocks = [];
+    const agoraBlocks = [];
+    const deliveries = [];
+    let remainingAgora = queued.filter(({ notification }) => notification.delivery?.mode !== 'direct').length;
     const complete = [];
     let omitted = 0;
     const omission = (count) => `${count} more ${count === 1 ? 'activity' : 'activities'} not shown.`;
-    for (const [index, entry] of queued.entries()) {
+    for (const entry of queued) {
         const { membership, notification } = entry;
         const block = [
             renderAttentionPreview({
@@ -27,23 +30,29 @@ function renderBoundary(inbox) {
                 actor: notification.actor,
                 route: notification.route,
                 body: notification.body,
+                delivery: notification.delivery,
             }),
         ].join('\n');
-        const omittedAfter = omitted + queued.length - index - 1;
-        const prospective = renderSquareReminder([...blocks, block, ...(omittedAfter > 0 ? [omission(omittedAfter)] : [])]);
-        if (prospective.length > CONTEXT_MAX) {
-            omitted += 1;
-            continue;
+        if (notification.delivery?.mode !== 'direct') {
+            remainingAgora -= 1;
+            const omittedAfter = omitted + remainingAgora;
+            const prospective = renderSquareReminder([...agoraBlocks, block, ...(omittedAfter > 0 ? [omission(omittedAfter)] : [])]);
+            if (prospective.length > CONTEXT_MAX) {
+                omitted += 1;
+                continue;
+            }
+            agoraBlocks.push(block);
         }
         blocks.push(block);
+        deliveries.push(notification.delivery);
         complete.push({
             membership,
             actIndexes: [notification.actIndex],
-            markSeen: !attentionBodyIsClipped(notification.body),
+            markSeen: !attentionBodyIsClipped(notification.body, notification.delivery),
         });
     }
     return {
-        context: renderSquareReminder([...blocks, ...(omitted > 0 ? [omission(omitted)] : [])]),
+        context: renderSquareReminder([...blocks, ...(omitted > 0 ? [omission(omitted)] : [])], deliveries),
         complete,
     };
 }

package/dist/channel.d.ts

@@ -0,0 +1,72 @@
+import { type HarnessSessionChannel } from './participant-identity.js';
+import type { SquareResourceOwner, WakeTransportPort } from './ports.js';
+import type { ActivityId, ChannelSendInput, ChannelSendResult, DeliveryDeferral, HeldSeat, MetadataMatch, OperationControl, Owner, Participant, WakeAddress } from './square-facade.js';
+export { harnessOwner, decodeHarnessOwner, localUserOwner } from './owner.js';
+export type { ActivityDelivery, ActivityMetadata, ChannelTruncate } from './square-facade.js';
+export type { ActivityId, ChannelSendInput, ChannelSendResult, DeliveryDeferral, HeldSeat, MetadataMatch, OperationControl, Owner, WakeAddress, SquareResourceOwner, WakeTransportPort, HarnessSessionChannel };
+export interface ResolvedHarnessSession {
+    readonly channel: HarnessSessionChannel;
+    readonly sessionId: string;
+    readonly agentId?: string;
+    readonly owner: Owner;
+    readonly wakeAddress?: WakeAddress;
+}
+export declare function resolveHarnessSession(env?: NodeJS.ProcessEnv): ResolvedHarnessSession | undefined;
+export interface ChannelOpenInput {
+    readonly path: string;
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly clock?: () => number;
+    readonly wakeTransport?: WakeTransportPort | false;
+    readonly resources?: SquareResourceOwner;
+}
+export interface ChannelCreateInput extends ChannelOpenInput {
+    readonly force?: boolean;
+    readonly description?: string;
+}
+type EndpointOptions = {
+    readonly owner: Owner;
+    readonly wakeAddress?: WakeAddress;
+};
+type EndpointIdentity = {
+    readonly owner: Owner;
+    readonly generation: ActivityId;
+};
+/** A scoped direct-messaging vocabulary over the shared Square resource. */
+export declare class Channel {
+    private readonly square;
+    private constructor();
+    get location(): string;
+    static open(input: ChannelOpenInput, control?: OperationControl): Promise<Channel>;
+    static create(input: ChannelCreateInput, control?: OperationControl): Promise<Channel>;
+    static inMemory(input?: Omit<ChannelCreateInput, 'path' | 'resources' | 'force'>): Channel;
+    attach(name: string, options: EndpointOptions & {
+        readonly takeover?: boolean;
+    }, control?: OperationControl): Promise<ChannelEndpoint>;
+    reattach(name: string, options: EndpointOptions, control?: OperationControl): Promise<ChannelEndpoint | null>;
+    endpoint(name: string, options: {
+        readonly owner: Owner;
+    }): Promise<ChannelEndpoint>;
+    endpointsOf(owner: Owner): Promise<readonly HeldSeat[]>;
+    detach(name: string, identity: EndpointIdentity): Promise<true | null>;
+    remove(name: string, identity: EndpointIdentity): Promise<boolean>;
+    cancelDeliveries(name: string, identity: EndpointIdentity): Promise<boolean>;
+    send(input: ChannelSendInput, control?: OperationControl): Promise<ChannelSendResult>;
+    close(): Promise<void>;
+}
+/** Captures one recipient generation through its existing Participant handle. */
+export declare class ChannelEndpoint {
+    private readonly channel;
+    private readonly participant;
+    constructor(channel: Channel, participant: Participant);
+    get name(): string;
+    get generation(): ActivityId;
+    leave(control?: OperationControl): Promise<void>;
+    deferDelivery(input: Readonly<{
+        match: MetadataMatch;
+        durationMs: number;
+    }>, control?: OperationControl): Promise<DeliveryDeferral>;
+    renewDeliveryDeferral(id: string, durationMs: number, control?: OperationControl): Promise<DeliveryDeferral | null>;
+    releaseDeliveryDeferral(id: string, control?: OperationControl): Promise<boolean>;
+    send(input: Omit<ChannelSendInput, 'from'>, control?: OperationControl): Promise<ChannelSendResult>;
+}

package/dist/channel.js

@@ -0,0 +1,86 @@
+import { codexWakeAddress } from './codex-address.js';
+import { SquareError } from './model.js';
+import { harnessOwner } from './owner.js';
+import { harnessSessionSources } from './participant-identity.js';
+import { Square } from './square-api.js';
+import { squareLocation } from './square-location.js';
+export { harnessOwner, decodeHarnessOwner, localUserOwner } from './owner.js';
+export function resolveHarnessSession(env = process.env) {
+    for (const { variable, channel } of harnessSessionSources) {
+        const sessionId = env[variable]?.trim();
+        if (!sessionId)
+            continue;
+        const agentId = channel === 'claude-code' && env.CLAUDE_CODE_CHILD_SESSION?.trim() === '1'
+            ? env.CLAUDE_CODE_AGENT_ID?.trim() || undefined : undefined;
+        const wakeAddress = channel === 'codex' ? codexWakeAddress(sessionId, env)
+            : channel === 'paseo' ? { kind: 'paseo', address: { agentId: sessionId } } : undefined;
+        return { channel, sessionId, ...(agentId === undefined ? {} : { agentId }),
+            owner: harnessOwner({ channel, session: sessionId, ...(agentId === undefined ? {} : { agent: agentId }) }),
+            ...(wakeAddress === undefined ? {} : { wakeAddress }) };
+    }
+    return undefined;
+}
+function explicitLocation(input) {
+    if (typeof input?.path !== 'string' || input.path.trim() === '')
+        throw new SquareError('invalid_args', 'Channel path is required.');
+    return squareLocation(input);
+}
+/** A scoped direct-messaging vocabulary over the shared Square resource. */
+export class Channel {
+    square;
+    constructor(square) {
+        this.square = square;
+    }
+    get location() { return this.square.location; }
+    static async open(input, control) {
+        const path = explicitLocation(input);
+        return new Channel(await Square.at({ ...input, path }, control));
+    }
+    static async create(input, control) {
+        const path = explicitLocation(input);
+        return new Channel(await Square.build({ ...input, path, hardCap: null, markdown: input.description ?? '# Channel\n' }, control));
+    }
+    static inMemory(input = {}) {
+        return new Channel(Square.inMemory({ ...input, hardCap: null, markdown: input.description ?? '# Channel\n' }));
+    }
+    async attach(name, options, control) {
+        return new ChannelEndpoint(this, (await this.square.join(name, options, control)).participant);
+    }
+    async reattach(name, options, control) {
+        const participant = await this.square.reattach(name, options, control);
+        return participant === null ? null : new ChannelEndpoint(this, participant);
+    }
+    async endpoint(name, options) {
+        return new ChannelEndpoint(this, await this.square.participant(name, options));
+    }
+    endpointsOf(owner) { return this.square.seatsOf(owner); }
+    detach(name, identity) { return this.square.detach(name, identity); }
+    async remove(name, identity) { return await this.square.endHeld(name, identity) !== null; }
+    cancelDeliveries(name, identity) { return this.square.cancelDeliveries(name, identity); }
+    send(input, control) { return this.square.send(input, control); }
+    close() { return this.square.close(); }
+}
+/** Captures one recipient generation through its existing Participant handle. */
+export class ChannelEndpoint {
+    channel;
+    participant;
+    constructor(channel, participant) {
+        this.channel = channel;
+        this.participant = participant;
+    }
+    get name() { return this.participant.name; }
+    get generation() { return this.participant.generation; }
+    async leave(control) { await this.participant.done(undefined, {}, control); }
+    deferDelivery(input, control) {
+        return this.participant.deferDelivery(input, control);
+    }
+    renewDeliveryDeferral(id, durationMs, control) {
+        return this.participant.renewDeliveryDeferral(id, durationMs, control);
+    }
+    releaseDeliveryDeferral(id, control) {
+        return this.participant.releaseDeliveryDeferral(id, control);
+    }
+    send(input, control) {
+        return this.channel.send({ ...input, from: this.name }, control);
+    }
+}

package/dist/claude-delivery.js

@@ -150,7 +150,8 @@ export async function observeClaudeDelivery(sessionId, text, operation, env = pr
                 return { recognized, current: false };
             if (operation === 'stored')
                 await presentPending({ artifact: row.artifact, location: request.location,
-                    participant: request.participant, activity: request.activity, seat: request.seat, sink: { present() { } },
+                    // Claude's stored event consumes even Agora previews; retain that contract for both modes.
+                    participant: request.participant, activity: request.activity, seat: request.seat, markSeen: true, sink: { present() { } },
                     current: facts => currentPayload(facts, request) === payload });
         }
         return { recognized, current: true };

package/dist/delivery.js

@@ -14,8 +14,8 @@ 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 }));

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

@@ -7,6 +7,11 @@ 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. */
@@ -105,6 +110,7 @@ export interface InboxNotification {
     at: number;
     route: DirectedNotificationRoute;
     body: string;
+    readonly delivery?: ActivityDelivery;
 }
 export interface LocatedSeat {
     readonly location: 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', '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. */

package/dist/ports.d.ts

@@ -84,6 +84,9 @@ export interface ReceiptAssignment {
 }
 export type SeatRef = Pick<Seat, 'participant' | 'owner' | 'generation'>;
 export type ArtifactWriteAuthority = {
+    readonly kind: 'send';
+    readonly actor: string;
+} | {
     readonly kind: 'participant';
     readonly seat: SeatRef;
 } | {

package/dist/presentation-operations.d.ts

@@ -6,6 +6,7 @@ export declare function preparePendingPresentation(input: Omit<PresentPendingInp
     at?: number;
     body?: string;
     metadata?: import("./model.js").ActivityMetadata;
+    delivery?: import("./model.js").ActivityDelivery;
     mentions?: readonly import("./square-core.js").Participant[];
     reach?: import("./square-core.js").Reach;
     reply?: number;

package/dist/sqlite-square.d.ts

@@ -1,5 +1,5 @@
 import { type Owner } from './model.js';
-import type { HistoryQuery, HistoryResult, JoinOptions, JoinResult, LifecycleResult, ObservationOptions, OperationControl, Participant, SquareAtInput, SquareBuildInput, SquareLocation, StatusOptions, StatusResult, ParticipantsResult, RecoveryResult, DiscoveryOptions, InboxOptions, InboxResult, StreamOptions, StreamRecord, Activity, PerceivedActivity } from './square-facade.js';
+import type { HistoryQuery, HistoryResult, JoinOptions, JoinResult, LifecycleResult, ObservationOptions, OperationControl, Participant, SquareAtInput, SquareBuildInput, SquareLocation, StatusOptions, StatusResult, ParticipantsResult, RecoveryResult, DiscoveryOptions, InboxOptions, InboxResult, StreamOptions, StreamRecord, Activity, PerceivedActivity, ChannelSendInput, ChannelSendResult } from './square-facade.js';
 export type * from './square-facade.js';
 export { createSquareResourceOwner } from './artifact.js';
 export { formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
@@ -26,6 +26,8 @@ export declare class SqliteSquare {
     private contextObservation;
     private handle;
     private static readonly ParticipantHandle;
+    /** Direct messages use explicit recipients, not participant expression admission or body attention. */
+    send(input: ChannelSendInput, control?: OperationControl): Promise<ChannelSendResult>;
     participant(name: string, { owner }: {
         readonly owner: Owner;
     }): Promise<Participant>;