@astrosheep/square 0.3.95 → 0.3.97

package/dist/identity.d.ts

@@ -8,6 +8,5 @@ export declare const SQUARE_IDENTITY: Readonly<{
     cliName: "square";
     pluginId: "square@astrosheep";
     hookCommand: "square codex-hook";
-    hookMarker: "square-codex-hook";
     clientName: "astrosheep_square";
 }>;

package/dist/identity.js

@@ -22,6 +22,5 @@ export const SQUARE_IDENTITY = Object.freeze({
     cliName: 'square',
     pluginId: 'square@astrosheep',
     hookCommand: 'square codex-hook',
-    hookMarker: 'square-codex-hook',
     clientName: 'astrosheep_square',
 });

package/dist/inbox.js

@@ -3,7 +3,7 @@ import { indexedSquareEntries, observeSquareIndex } from './square-index.js';
 import { canonicalPath } from './canonical-path.js';
 import { formatActivityId, parseActivityId } from './square-core.js';
 import { freshWatchLease, WATCH_STALE_MS } from './runtime.js';
-import { pendingHead, pendingNotifications, leaseOwnsNotification } from './delivery.js';
+import { pendingHead, pendingHeads, leaseOwnsNotification } from './delivery.js';
 import { deliveryDeferralExpiry } from './delivery-deferral.js';
 import { attentionBodyIsClipped, renderAttentionPreview, renderSquareReminder } from './attention-presentation.js';
 export function pendingKey(membership, actIndex) {
@@ -146,11 +146,14 @@ async function projectPending(candidates, cache, signal) {
                 const header = facts.header();
                 let cached = cache?.get(location);
                 if (cached?.coordinate !== coordinate || cached.version !== header.revision) {
-                    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,
-                            })),
-                        })) };
+                    cached = { coordinate, version: header.revision, value: locatedSeats(facts, location, seats).map(membership => {
+                            const heads = pendingHeads(facts, membership.seat.participant);
+                            const routes = new Map(heads.map(head => [head.index, head.route]));
+                            return { ...membership, notifications: facts.activities(heads.map(head => head.index)).flatMap(item => item.kind === 'say'
+                                    ? [{ actIndex: item.index, actor: item.actor, at: item.at, body: item.body ?? '(structured activity)',
+                                            route: routes.get(item.index), ...(item.delivery === undefined ? {} : { delivery: item.delivery }) }]
+                                    : []) };
+                        }) };
                 }
                 // Cache conversation content, never leases or delivery eligibility: evidence can change
                 // without a conversation revision and must not force body hydration or self-wake retries.
@@ -197,7 +200,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/notifications.d.ts

@@ -1,6 +1,5 @@
 import { type WakeRouteKind } from './model.js';
 import type { WakeTransportPort } from './ports.js';
-export type { PlannedNotification } from './delivery.js';
 export declare const PRIVILEGED_HOOK_BUDGET_MS = 3000;
 export declare function wakeGraceMs(env?: NodeJS.ProcessEnv): number;
 export type WakeTransports = Readonly<Partial<Record<WakeRouteKind, WakeTransportPort>>>;
@@ -24,3 +23,4 @@ export interface SweepPendingNotificationsOptions {
 }
 /** Select old pending attention at a bounded action boundary for an explicit executor. */
 export declare function sweepPendingNotifications(squarePath: string, opts?: SweepPendingNotificationsOptions): Promise<number[]>;
+export {};

package/dist/ports.d.ts

@@ -63,6 +63,8 @@ export interface DirectedFilter {
     readonly beforeIndex?: number;
     readonly throughIndex?: number;
     readonly unseenOnly?: true;
+    /** Exact own-property scalar equalities, applied before paging or counting. */
+    readonly metadataMatch?: MetadataMatch;
     readonly senders?: readonly string[];
     readonly attentionOnly?: true;
 }
@@ -78,12 +80,11 @@ export interface ReceiptFacts {
     readonly latestAt?: number;
     readonly latestActorActivityIndex?: number;
 }
-export interface ReceiptAssignment {
-    readonly owner: string;
-    readonly index: ActivityIndex;
-}
 export type SeatRef = Pick<Seat, 'participant' | 'owner' | 'generation'>;
 export type ArtifactWriteAuthority = {
+    readonly kind: 'send';
+    readonly actor: string;
+} | {
     readonly kind: 'participant';
     readonly seat: SeatRef;
 } | {
@@ -199,7 +200,6 @@ export interface SquareRead {
         readonly at: number;
     } | undefined;
     receiptFacts(requestedName: string, afterIndex: number): ReceiptFacts;
-    receiptAssignments(): readonly ReceiptAssignment[];
     lease(requestedName: string): WatchLease | undefined;
     deliveryDeferrals(participant: string, generation: ActivityId): readonly DeliveryDeferralFact[];
 }

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,13 +26,14 @@ 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>;
     join(requested: string, options: JoinOptions, control?: OperationControl): Promise<JoinResult>;
     /** Restore only a standing seat; a concurrent departure or takeover cannot be revived. */
     reattach(name: string, { owner, wakeAddress }: Pick<JoinOptions, 'owner' | 'wakeAddress'>, control?: OperationControl): Promise<Participant | null>;
-    snapshot(control?: OperationControl): Promise<import("./square-facade.js").SquareSnapshot>;
     history(query?: HistoryQuery, control?: OperationControl): Promise<HistoryResult>;
     status(options?: StatusOptions, control?: OperationControl): Promise<StatusResult>;
     participants(options?: ObservationOptions, control?: OperationControl): Promise<ParticipantsResult>;

package/dist/sqlite-square.js

@@ -1,18 +1,19 @@
-import { formatActivityId } from './square-core.js';
+import { formatActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
 import { assertCurrentSeat } from './square-domain.js';
 import { canonicalPath } from './canonical-path.js';
 import { validateMetadataMatch, validateDeferralDuration, validateDeferralId } from './delivery-deferral.js';
 import { squareLocation } from './square-location.js';
 import crypto from 'node:crypto';
 import { setTimeout as sleep } from 'node:timers/promises';
-import { InternalSquareError, SquareError, isSquareError, nameKey, validateName } from './model.js';
-import { coreDone, coreIgnore, coreListen, coreListening, coreUnlisten, decideAct, decideJoin, resolveKnownName, validateDoneBody } from './decisions.js';
+import { activityMetadataHasContent, InternalSquareError, SquareError, isSquareError, nameKey, sameName, validateActivityMetadata, validateName } from './model.js';
+import { attentionChange, coreDone, coreListening, decideAct, decideJoin, resolveKnownName, validateDoneBody } from './decisions.js';
 import { WATCH_HEARTBEAT_MS, inSquareCount, presenceAnchor } from './runtime.js';
 import { catchLimit, decideCatch, observeCatchSelection, selectCatchPage } from './catch-decisions.js';
 import { expressionContext } from './activity-feed.js';
 import { expressHint } from './hints.js';
+import { ATTENTION_BODY_MAX } from './attention-presentation.js';
 import { asSeatRef, participantAuthority, requireOwner, requireJoinName } from './seats.js';
-import { recoveryObservation, entryPresentation, snapshot, queryStatus, queryParticipants, catchPresence, parseRequiredActivityId, toPublicActivity, publicActivities, selectHistory, NON_READ, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
+import { recoveryObservation, entryPresentation, queryStatus, queryParticipants, catchPresence, parseRequiredActivityId, toPublicActivity, toPerceivedActivity, publicActivities, selectHistory, NON_READ, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
 import { sessionInboxCounts } from './inbox.js';
 import { rememberSquarePath, squareIndexPath } from './square-index.js';
 import { deliverPending } from './delivery-operations.js';
@@ -133,6 +134,7 @@ export class SqliteSquare {
             this.owner = owner;
             this.seat = seat;
         }
+        get generation() { return this.seat.generation; }
         async express(bodyOrInput, optionsOrControl = {}, operationControl) {
             const square = this.owner;
             const input = typeof bodyOrInput === 'object' && bodyOrInput !== null ? bodyOrInput : undefined;
@@ -214,7 +216,7 @@ export class SqliteSquare {
             checkControl(control);
             const seat = this.seat, now = square.clock();
             return (await square.artifact.transactAs(participantAuthority(seat), facts => {
-                const act = verb === 'listen' ? coreListen(facts, name, target, now) : verb === 'ignore' ? coreIgnore(facts, name, target, now) : coreUnlisten(facts, name, target, now);
+                const act = attentionChange(facts, verb, name, target, now);
                 const activity = act === undefined ? null : toPublicActivity(facts.land(act));
                 return { activity, ...(!options.observe ? {} : { observation: {
                             ...square.observation(inSquareCount(facts), name, now), participant: name,
@@ -342,6 +344,37 @@ export class SqliteSquare {
                     await releaseWatchLease(square.artifact, seat, leaseId).catch(() => undefined);
             }
         }
+        async pending(options = {}, control) {
+            checkControl(control);
+            const limit = options.limit ?? 100;
+            if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+                throw new SquareError('invalid_args', 'Pending limit must be a positive integer no greater than 100.');
+            const match = options.match === undefined ? undefined : validateMetadataMatch(options.match);
+            const square = this.owner;
+            return (await square.artifact.read(facts => {
+                assertCurrentSeat(facts, asSeatRef(this.seat));
+                const filter = { unseenOnly: true, ...(match === undefined ? {} : { metadataMatch: match }) };
+                const heads = facts.directed(this.name, filter, { edge: 'oldest', limit });
+                const activities = facts.activities(heads.items.map(head => head.index))
+                    .map(activity => toPerceivedActivity(facts, activity, this.name));
+                return { activities, remaining: facts.directedCount(this.name, filter) - activities.length };
+            }, control?.signal)).value;
+        }
+        async ack(ids, control) {
+            checkControl(control);
+            if (!Array.isArray(ids))
+                throw new SquareError('invalid_args', 'Ack requires an array of activity IDs.');
+            const indexes = [...new Set(Array.from(ids, parseRequiredActivityId))], square = this.owner;
+            return (await square.artifact.transactAs(participantAuthority(this.seat), facts => {
+                for (const index of indexes) {
+                    if (facts.directedAt(this.name, index) === undefined)
+                        throw new SquareError('invalid_args', `${formatActivityId(index)} is not addressed to you.`, {
+                            reason: 'not_addressed', activityId: formatActivityId(index),
+                        });
+                }
+                return { consumed: facts.markSeen(this.name, indexes, square.clock()) };
+            }, control?.signal)).value;
+        }
         async deferDelivery(input, control) {
             checkControl(control);
             const match = validateMetadataMatch(input?.match), duration = validateDeferralDuration(input?.durationMs);
@@ -382,6 +415,56 @@ export class SqliteSquare {
             }, control?.signal)).value;
         }
     };
+    /** Direct messages use explicit recipients, not participant expression admission or body attention. */
+    async send(input, control) {
+        checkControl(control);
+        const { from, to, body, truncate = ATTENTION_BODY_MAX } = input;
+        if (typeof from !== 'string')
+            throw new SquareError('invalid_args', 'Channel sender must be a name.');
+        validateName(from);
+        const targets = typeof to === 'string' ? [to] : to;
+        if (!Array.isArray(targets) || targets.length < 1 || targets.length > MAX_IDENTITY_SET_SIZE)
+            throw new SquareError('invalid_args', `Channel needs between 1 and ${MAX_IDENTITY_SET_SIZE} recipients.`);
+        const unique = [];
+        for (const target of targets) {
+            if (typeof target !== 'string')
+                throw new SquareError('invalid_args', 'Channel recipients must be names.');
+            validateName(target);
+            if (!unique.some(name => sameName(name, target)))
+                unique.push(target);
+        }
+        if (typeof body !== 'string' || body.trim() === '')
+            throw new SquareError('invalid_args', 'Channel body must be non-empty.');
+        if (truncate !== false && (!Number.isSafeInteger(truncate) || truncate < 1))
+            throw new SquareError('invalid_args', 'Channel truncate must be false or a positive integer.');
+        const fullBody = body.replace(/\r\n/g, '\n');
+        const preview = truncate !== false && fullBody.length > truncate
+            ? `${fullBody.slice(0, truncate).trimEnd()}… (truncated ${fullBody.length - truncate} chars)`
+            : undefined;
+        const delivery = preview === undefined ? { mode: 'direct' } : { mode: 'direct', preview };
+        const metadata = validateActivityMetadata(input.metadata);
+        const { stored, resolvedTo } = (await this.artifact.transactAs({ kind: 'send', actor: from }, facts => {
+            const standing = facts.roster().filter(p => p.joined), resolvedTo = [], missing = [];
+            for (const target of unique) {
+                const recipient = standing.find(p => sameName(p.name, target));
+                if (recipient === undefined)
+                    missing.push(target);
+                else
+                    resolvedTo.push(recipient.name);
+            }
+            if (missing.length > 0)
+                throw new SquareError('invalid_args', `Channel recipients are not standing: ${missing.join(', ')}`, {
+                    reason: 'not_standing', targets: missing, activityUnsent: true,
+                });
+            return { stored: facts.land({ kind: 'say', actor: from, at: this.clock(), body: fullBody,
+                    ...(activityMetadataHasContent(metadata) ? { metadata } : {}), delivery, mentions: resolvedTo }), resolvedTo };
+        }, control?.signal)).value;
+        if (this.wakeTransport !== undefined)
+            await deliverPending({ artifact: this.artifact, transport: this.wakeTransport, location: this.deliveryLocation,
+                activity: stored.index, now: stored.at }).catch(() => undefined);
+        return { id: formatActivityId(stored.index), at: stored.at, from: stored.actor, to: resolvedTo, body: preview ?? fullBody,
+            ...(stored.kind !== 'say' || stored.metadata === undefined ? {} : { metadata: stored.metadata }) };
+    }
     async participant(name, { owner }) {
         validateName(name);
         requireOwner(owner);
@@ -432,10 +515,10 @@ export class SqliteSquare {
                     kind = 'reconnected';
                 }
                 if (kind !== 'reconnected') {
-                    const decision = decideJoin(facts, participant, now);
-                    if (decision.joinAct === undefined)
+                    const joinAct = decideJoin(facts, participant, now);
+                    if (joinAct === undefined)
                         throw new SquareError('already_joined', `${participantIdentity(participant)} could not be joined`);
-                    activity = toPublicActivity(facts.land(decision.joinAct));
+                    activity = toPublicActivity(facts.land(joinAct));
                 }
                 const seat = facts.seat(participant);
                 if (seat === undefined)
@@ -480,7 +563,6 @@ export class SqliteSquare {
             await this.publishSeat(owner);
         return seat === null ? null : this.handle(seat);
     }
-    async snapshot(control) { return (await this.artifact.read(facts => snapshot(facts, this.clock()), control?.signal)).value; }
     async history(query = {}, control) {
         if (query.limit !== undefined && query.limit !== null && (!Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > HISTORY_MAX_LIMIT))
             throw new SquareError('invalid_args', `History limit must be a positive integer no greater than ${HISTORY_MAX_LIMIT}`);

package/dist/square-core.d.ts

@@ -26,6 +26,7 @@ export type Act = {
     at?: number;
     body?: string;
     metadata?: import('./model.js').ActivityMetadata;
+    delivery?: import('./model.js').ActivityDelivery;
     mentions?: readonly Participant[];
     reach?: Reach;
     reply?: number;

package/dist/square-domain.js

@@ -1,7 +1,16 @@
-import { SquareError, formatActivityId, parseActivityId, sameName, validateOwner, validateName } from './model.js';
+import { SquareError, formatActivityId, parseActivityId, sameName, validateActivityDelivery, validateOwner, validateName } from './model.js';
 import { resolveAudience } from './attention.js';
 /** The single landing transition, shared by both adapters and explicit rebuild. */
 export function deriveLanding(activity, facts) {
+    if (activity.kind === 'say' && activity.delivery?.mode === 'direct') {
+        const audience = [];
+        for (const mention of activity.mentions ?? []) {
+            const recipient = facts.standing.find(item => sameName(item.name, mention))?.name;
+            if (recipient !== undefined && !audience.some(item => sameName(item.recipient, recipient)))
+                audience.push({ recipient, route: 'mention' });
+        }
+        return { activity, audience };
+    }
     const audience = activity.kind === 'say' ? resolveAudience({
         actor: activity.actor, recipients: facts.standing.map((item) => item.name),
         mentions: activity.mentions, replyAuthor: facts.replyAuthor, reach: activity.reach,
@@ -60,15 +69,15 @@ export function wrapSquareWrite(read, writes, authority) {
         throw new SquareError('invalid_args', 'Artifact writes require an explicit authority.');
     const { applyLanding, ...mutations } = writes;
     const seated = authority.kind === 'participant' || authority.kind === 'host-cleanup';
-    const expectedName = seated ? authority.seat?.participant : authority.participant;
-    if (!['participant', 'host-cleanup', 'join', 'takeover'].includes(authority.kind) || typeof expectedName !== 'string')
+    const expectedName = seated ? authority.seat?.participant : authority.kind === 'send' ? authority.actor : authority.participant;
+    if (!['participant', 'host-cleanup', 'join', 'takeover', 'send'].includes(authority.kind) || typeof expectedName !== 'string')
         throw new SquareError('invalid_args', 'Artifact write authority is malformed.');
     validateName(expectedName);
     if (seated) {
         validateOwner(authority.seat.owner);
         validateGeneration(authority.seat.generation);
     }
-    else {
+    else if (authority.kind !== 'send') {
         validateOwner(authority.owner);
         if (authority.kind === 'takeover')
             validateGeneration(authority.expectedGeneration);
@@ -100,7 +109,7 @@ export function wrapSquareWrite(read, writes, authority) {
             reconnectSeat = seat;
         }
     }
-    else {
+    else if (authority.kind === 'takeover') {
         const current = read.seat(expectedName);
         if (current === undefined || current.generation !== authority.expectedGeneration)
             throw new SquareError('already_joined', 'The participant seat changed before takeover.');
@@ -114,7 +123,13 @@ export function wrapSquareWrite(read, writes, authority) {
             validateName(actor);
             if (!sameName(actor, expectedName))
                 throw new SquareError('already_joined', 'Activity actor does not match the artifact authority.');
-            if (authority.kind === 'participant') {
+            if (activity.kind === 'say')
+                validateActivityDelivery(activity.delivery);
+            if (authority.kind === 'send') {
+                if (activity.kind !== 'say' || activity.delivery?.mode !== 'direct' || activity.reach !== undefined || activity.reply !== undefined)
+                    throw new SquareError('invalid_args', 'Send authority may only land direct messages without bell or reply.');
+            }
+            else if (authority.kind === 'participant') {
                 assertSeat(authority.seat);
                 if (activity.kind === 'join')
                     throw new SquareError('invalid_args', 'A participant seat can only be re-established by join.');
@@ -150,7 +165,7 @@ export function wrapSquareWrite(read, writes, authority) {
             const stored = { ...activity, index };
             applyLanding(deriveLanding(stored, landingFacts(read, stored)));
             if (stored.kind === 'join') {
-                if (seated)
+                if (authority.kind !== 'join' && authority.kind !== 'takeover')
                     throw new SquareError('invalid_args', 'Seat authority cannot establish another seat.');
                 const seat = {
                     participant: stored.actor,