@astrosheep/square 0.3.86 → 0.3.87

package/dist/inbox.js

@@ -1,78 +1,198 @@
-import { nameKey } from './model.js';
-import { createArtifactPort, observeSquareRevision } from './artifact.js';
-import { hostLedgerForEnv } from './registry.js';
+import { sameBody } from './model.js';
+import { createArtifactPort, observeSquareDeliveryRevision, observeSquareRevision } from './artifact.js';
+import { indexedSquareEntries, observeSquareIndex } from './square-index.js';
 import { canonicalPath } from './canonical-path.js';
-import { projectBoundaryEligibility, projectSessionBindings } from './square-projections.js';
+import { formatActivityId, parseActivityId } from './square-core.js';
 import { freshWatchLease, WATCH_STALE_MS } from './runtime.js';
 import { pendingHead, pendingNotifications, leaseOwnsNotification } from './delivery.js';
 import { attentionBodyIsClipped, renderAttentionPreview, renderSquareReminder } from './attention-presentation.js';
-function bindingCoordinate(binding) {
-    return JSON.stringify([binding.location, nameKey(binding.participant), binding.sessionId, binding.channel, binding.epoch, binding.cancelledThrough ?? -1]);
+export function pendingKey(membership, actIndex) {
+    return membership.location + '\0' + membership.seat.participant.toLocaleLowerCase() + '\0' + actIndex;
 }
-function notificationKey(membership, actIndex) {
-    return membership.squarePath + '\0' + membership.name.toLocaleLowerCase() + '\0' + actIndex;
+export function pendingAtBoundary(inbox) {
+    return inbox.map((membership) => {
+        const lease = membership.catchLease;
+        if (lease === undefined)
+            return membership;
+        return { ...membership, notifications: membership.notifications.filter((notification) => !leaseOwnsNotification(lease, { ...notification, recipient: membership.seat.participant })) };
+    }).filter((membership) => membership.notifications.length > 0);
 }
-export function projectPresentation(facts, requested, now = Date.now()) {
-    const participant = facts.participant(requested.participant);
-    if (!participant?.joined)
-        return { binding: requested, joined: false, notifications: [] };
-    const binding = { ...requested, participant: participant.name };
-    const notifications = pendingNotifications(facts, participant.name).map(({ item, route }) => ({
-        actIndex: item.index, actor: item.actor, at: item.at, body: item.body, route,
-    }));
-    const catchLease = freshWatchLease(facts, participant.name, now);
-    return { binding, joined: true, notifications, ...(catchLease === undefined ? {} : { catchLease }) };
+function eligibleNotifications(facts, membership) {
+    const seat = facts.seat(membership.seat.participant);
+    if (seat === undefined || seat.generation !== membership.seat.generation
+        || !sameBody(seat.body, membership.seat.body))
+        return [];
+    const cancelledThrough = facts.cancelledThrough(seat.participant, seat.generation);
+    return membership.notifications.filter(notification => (cancelledThrough === undefined || notification.actIndex > cancelledThrough)
+        && !facts.deliveryEvidence(seat.participant, seat.generation, formatActivityId(notification.actIndex))
+            .some(row => row.kind === 'presentation' && (row.outcome === 'presented' || row.outcome === 'clipped')));
 }
-/** First matching ordered route, exact native epoch/address and catch ownership. */
-export function nativePendingPreview(facts, input) {
-    const route = facts.routes().find((candidate) => candidate.kind === input.routeKind && candidate.sessionId === input.sessionId
-        && candidate.epoch === input.epoch && nameKey(candidate.participant) === nameKey(input.participant)
-        && (input.routeKind === 'claude-native' ? candidate.address.endpoint === input.address.endpoint : candidate.address.sessionId === input.address.sessionId));
-    if (!route || input.actIndex <= (input.cancelledThrough ?? -1))
-        return undefined;
-    const head = pendingHead(facts, input.participant, input.actIndex);
-    const lease = freshWatchLease(facts, input.participant, input.now);
-    if (!head || (lease !== undefined && leaseOwnsNotification(lease, head)))
-        return undefined;
-    const item = facts.activity(input.actIndex);
-    if (item?.kind !== 'say')
-        return undefined;
-    return { payload: renderSquareReminder([renderAttentionPreview({ squarePath: input.location, recipient: input.participant, actIndex: item.index,
-                actor: item.actor, route: head.route, body: item.body })]), clipped: attentionBodyIsClipped(item.body) };
+/** Revalidate a supplied batch immediately before the boundary's independent claim/send checks. */
+export async function projectBoundaryEligibility(inbox) {
+    const grouped = new Map();
+    for (const membership of pendingAtBoundary(inbox)) {
+        const entries = grouped.get(membership.location) ?? [];
+        entries.push(membership);
+        grouped.set(membership.location, entries);
+    }
+    const pending = [];
+    for (const [location, memberships] of grouped) {
+        const artifact = createArtifactPort(location);
+        try {
+            const { value } = await artifact.read(facts => memberships.flatMap(membership => {
+                const notifications = eligibleNotifications(facts, membership);
+                return notifications.length === 0 ? [] : [{ ...membership, notifications }];
+            }));
+            pending.push(...value);
+        }
+        catch {
+            // An unreadable or stale candidate cannot authorize boundary presentation.
+        }
+        finally {
+            await artifact.close();
+        }
+    }
+    return pending;
 }
-async function readInboxMembership(binding, signal) {
-    const artifact = createArtifactPort(binding.location, undefined, signal);
-    try {
-        return await artifact.read((facts) => {
-            const projection = projectPresentation(facts, binding);
-            if (!projection.joined)
-                return undefined;
-            return { name: projection.binding.participant, squarePath: projection.binding.location, notifications: [...projection.notifications],
-                ...(projection.catchLease === undefined ? {} : { catchLease: projection.catchLease }) };
-        }, signal);
+/** HOME is a candidate path index; current seats and delivery evidence live in the artifact. */
+export async function projectSessionCandidates(input) {
+    const location = input.location === undefined ? undefined : await canonicalPath(input.location);
+    const entries = await indexedSquareEntries({ body: input.body, session: input.sessionId, channel: input.channel, agent: input.agent }, input.env ?? process.env);
+    const candidates = new Map();
+    for (const entry of entries) {
+        if (location !== undefined && location !== entry.location)
+            continue;
+        const key = JSON.stringify([entry.location, entry.body.channel, entry.body.session, entry.body.agent ?? null]);
+        candidates.set(key, { location: entry.location, body: entry.body });
+    }
+    return [...candidates.values()];
+}
+function groupCandidates(candidates) {
+    const grouped = new Map();
+    for (const { location, body } of candidates) {
+        const bodies = grouped.get(location) ?? [];
+        bodies.push(body);
+        grouped.set(location, bodies);
     }
-    finally {
-        await artifact.close();
+    return grouped;
+}
+function locatedSeats(facts, location, seats) {
+    return seats.flatMap(seat => {
+        const index = parseActivityId(seat.generation);
+        const joined = index === undefined ? undefined : facts.activity(index);
+        return joined?.kind !== 'join' ? [] : [{ location, seat, joinedAt: joined.at }];
+    });
+}
+/** Lifecycle reads resolve seats and join times, never pending activity bodies. */
+export async function projectSessionSeats(input, signal) {
+    const seats = [];
+    for (const [location, bodies] of groupCandidates(await projectSessionCandidates(input))) {
+        signal?.throwIfAborted();
+        const artifact = createArtifactPort(location, undefined, signal);
+        try {
+            seats.push(...(await artifact.read(facts => locatedSeats(facts, location, bodies.flatMap(body => facts.seatsForBody(body))), signal)).value);
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw signal.reason ?? error;
+        }
+        finally {
+            await artifact.close();
+        }
+    }
+    return seats;
+}
+/** Public count boundary: one coherent read per artifact, without pending body hydration. */
+export async function sessionInboxCounts(input, signal) {
+    const rows = [];
+    for (const [location, bodies] of groupCandidates(await projectSessionCandidates(input))) {
+        signal?.throwIfAborted();
+        const artifact = createArtifactPort(location, undefined, signal);
+        try {
+            rows.push(...(await artifact.read(facts => locatedSeats(facts, location, bodies.flatMap(body => facts.seatsForBody(body))).map(({ seat }) => ({
+                name: seat.participant, squarePath: location, pending: facts.directedCount(seat.participant, { unseenOnly: true }),
+            })), signal)).value);
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw signal.reason ?? error;
+        }
+        finally {
+            await artifact.close();
+        }
     }
+    return rows;
 }
-export async function sessionInbox(sessionId, env = process.env, signal) {
-    const inbox = [];
-    const hostLedger = hostLedgerForEnv(env);
-    for (const binding of await projectSessionBindings({ hostLedger, sessionId })) {
-        if (signal?.aborted)
-            throw signal.reason;
+/** One authoritative read per canonical artifact, even when discovery names several bodies. */
+async function projectPending(candidates, cache, signal) {
+    const pending = [];
+    for (const [location, bodies] of groupCandidates(candidates)) {
+        signal?.throwIfAborted();
+        const artifact = createArtifactPort(location, undefined, signal);
         try {
-            const { value: membership } = await readInboxMembership(binding, signal);
-            if (membership !== undefined)
-                inbox.push(membership);
+            const { value: current } = await artifact.read(facts => {
+                const seats = bodies.flatMap(body => facts.seatsForBody(body));
+                const coordinate = JSON.stringify([bodies, seats.map(seat => [seat.participant, seat.body, seat.generation])]);
+                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,
+                            })),
+                        })) };
+                }
+                // 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.
+                return { cached, pending: cached.value.map(membership => {
+                        const catchLease = freshWatchLease(facts, membership.seat.participant);
+                        return { ...membership, notifications: eligibleNotifications(facts, membership),
+                            ...(catchLease === undefined ? {} : { catchLease }) };
+                    }) };
+            }, signal);
+            cache?.set(location, current.cached);
+            pending.push(...current.pending);
         }
         catch (error) {
+            cache?.delete(location);
             if (signal?.aborted)
                 throw signal.reason ?? error;
-            // A stale or unreadable membership cannot disable delivery for other memberships.
+            // Unreadable candidates remain watch targets, but never authorize cached content.
+        }
+        finally {
+            await artifact.close();
         }
     }
-    return inbox;
+    return pending;
+}
+function sameWakeAddress(address, kind, requested) {
+    if (address?.kind !== kind)
+        return false;
+    return Object.entries(requested).every(([key, value]) => address.address[key] === value);
+}
+/** First matching current seat, exact body/generation/address and catch ownership. */
+export function nativePendingPreview(facts, input) {
+    const seat = facts.seat(input.participant);
+    if (seat === undefined || seat.body.session !== input.sessionId
+        || !sameWakeAddress(seat.wakeAddress, input.routeKind, input.address))
+        return undefined;
+    const cancelledThrough = facts.cancelledThrough(seat.participant, seat.generation);
+    if (input.actIndex <= Math.max(input.cancelledThrough ?? -1, cancelledThrough ?? -1))
+        return undefined;
+    const head = pendingHead(facts, seat.participant, input.actIndex);
+    const lease = freshWatchLease(facts, input.participant, input.now);
+    if (!head || (lease !== undefined && leaseOwnsNotification(lease, head)))
+        return undefined;
+    const item = facts.activity(input.actIndex);
+    if (item?.kind !== 'say')
+        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)') };
+}
+export async function sessionInbox(identity, env = process.env, signal) {
+    const query = 'allAgents' in identity ? { channel: identity.channel, sessionId: identity.session, env }
+        : { body: identity, env };
+    return projectPending(await projectSessionCandidates(query), undefined, signal);
 }
 async function capture(observer, kind, signal) {
     const generation = observer.generation;
@@ -103,34 +223,27 @@ async function capture(observer, kind, signal) {
     }
 }
 /** Session-scoped projection over process-shared storage change detectors. */
-export async function observeSessionPending(sessionId, suppliedEnv = process.env) {
+export async function observeSessionPending(identity, suppliedEnv = process.env) {
     const env = { ...suppliedEnv };
-    const hostLedger = hostLedgerForEnv(env);
-    const ledger = await hostLedger.observeChanges();
+    const query = 'allAgents' in identity ? { channel: identity.channel, sessionId: identity.session, env }
+        : { body: identity, env };
+    const index = await observeSquareIndex(env);
     const artifacts = new Map();
+    const cache = new Map();
     const lifetime = new AbortController();
-    const bindingsNow = async () => Promise.all((await projectSessionBindings({ hostLedger, sessionId })).map(async (binding) => ({ ...binding, location: await canonicalPath(binding.location) })));
-    async function membershipAt(binding, version, signal) {
-        const cache = artifacts.get(binding.location)?.inbox;
-        const name = nameKey(binding.participant);
-        const coordinate = bindingCoordinate(binding);
-        let cached = cache?.get(name);
-        if (cached === undefined || cached.version !== version || cached.binding !== coordinate) {
-            cached = { ...await readInboxMembership(binding, signal), binding: coordinate };
-            cache?.set(name, cached);
-        }
-        const membership = cached.value;
-        if (membership === undefined)
-            return undefined;
-        const { catchLease, ...rest } = membership;
+    async function currentInbox(candidates, signal) {
+        const inbox = await projectPending(candidates, cache, signal);
         const now = Date.now();
-        return catchLease !== undefined && catchLease.expiresAt > now && now - catchLease.heartbeatAt <= WATCH_STALE_MS
-            ? membership : rest;
+        return inbox.map((membership) => {
+            const { catchLease, ...rest } = membership;
+            return catchLease !== undefined && catchLease.expiresAt > now && now - catchLease.heartbeatAt <= WATCH_STALE_MS
+                ? membership : rest;
+        });
     }
-    async function eligibleInbox(inbox, excludeKeys) {
-        const eligible = await projectBoundaryEligibility({ hostLedger, sessionId, inbox });
+    function eligibleInbox(inbox, excludeKeys) {
+        const eligible = pendingAtBoundary(inbox);
         return excludeKeys === undefined ? eligible : eligible.flatMap((membership) => {
-            const notifications = membership.notifications.filter((notification) => !excludeKeys.has(notificationKey(membership, notification.actIndex)));
+            const notifications = membership.notifications.filter((notification) => !excludeKeys.has(pendingKey(membership, notification.actIndex)));
             return notifications.length === 0 ? [] : [{ ...membership, notifications }];
         });
     }
@@ -138,34 +251,8 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
         async read(options = {}) {
             const signal = AbortSignal.any([lifetime.signal, ...(options.signal === undefined ? [] : [options.signal])]);
             signal.throwIfAborted();
-            const bindings = await bindingsNow();
-            const revisions = new Map();
-            const inbox = [];
-            for (const binding of bindings) {
-                signal.throwIfAborted();
-                try {
-                    let version = revisions.get(binding.location);
-                    if (version === undefined) {
-                        const artifact = createArtifactPort(binding.location);
-                        try {
-                            version = await artifact.revision(signal);
-                        }
-                        finally {
-                            await artifact.close();
-                        }
-                        revisions.set(binding.location, version);
-                    }
-                    const membership = await membershipAt(binding, version, signal);
-                    if (membership !== undefined)
-                        inbox.push(membership);
-                }
-                catch (error) {
-                    if (signal.aborted)
-                        throw signal.reason ?? error;
-                    // An unreadable current revision must never authorize cached content.
-                }
-            }
-            const pending = await eligibleInbox(inbox, options.excludeKeys);
+            const inbox = await currentInbox(await projectSessionCandidates(query), signal);
+            const pending = eligibleInbox(inbox, options.excludeKeys);
             signal.throwIfAborted();
             return pending;
         },
@@ -178,55 +265,51 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
             let canReturn = !options.skipImmediate;
             let previousEligible;
             let armed = false;
+            let candidates = [];
+            let candidatePresence;
+            let discoveredCandidates = false;
             try {
                 while (!signal.aborted) {
-                    // Subscribe/capture the ledger BEFORE discovering bindings; a concurrent join cannot fall in a gap.
-                    const sources = await Promise.all([capture(ledger.presence, 'presence', signal), capture(ledger.evidence, 'evidence', signal)]);
-                    const bindings = await bindingsNow();
-                    const paths = new Set(bindings.map((binding) => binding.location));
+                    // Subscribe to the candidate index before discovering artifacts; a concurrent join can
+                    // publish its path without touching the artifact revision.
+                    const sources = [await capture(index, 'index', signal)];
+                    const presence = sources[0];
+                    const currentPresence = presence.value;
+                    if (!discoveredCandidates || currentPresence !== undefined && !Object.is(currentPresence, candidatePresence)) {
+                        candidates = await projectSessionCandidates(query);
+                        candidatePresence = currentPresence;
+                        discoveredCandidates = true;
+                    }
+                    const paths = new Set(candidates.map((candidate) => candidate.location));
                     for (const [file, entry] of artifacts) {
                         if (!paths.has(file)) {
                             entry.observer.close();
+                            entry.delivery.close();
                             artifacts.delete(file);
+                            cache.delete(file);
                         }
                     }
                     for (const file of paths) {
                         if (artifacts.has(file))
                             continue;
                         const observer = await observeSquareRevision(file);
+                        const delivery = await observeSquareDeliveryRevision(file);
                         if (signal.aborted) {
                             observer.close();
+                            delivery.close();
                             return [];
                         }
-                        artifacts.set(file, { observer, inbox: new Map() });
+                        artifacts.set(file, { observer, delivery });
                     }
-                    const revisions = new Map();
-                    for (const [file, entry] of artifacts) {
-                        const source = await capture(entry.observer, 'artifact', signal);
-                        sources.push(source);
-                        revisions.set(file, source.value);
-                        const names = new Set(bindings.filter((binding) => binding.location === file).map((binding) => nameKey(binding.participant)));
-                        for (const name of entry.inbox.keys())
-                            if (!names.has(name))
-                                entry.inbox.delete(name);
-                    }
-                    const inbox = [];
-                    for (const binding of bindings) {
-                        if (signal.aborted)
-                            return [];
-                        try {
-                            const membership = await membershipAt(binding, revisions.get(binding.location), signal);
-                            if (membership !== undefined)
-                                inbox.push(membership);
-                        }
-                        catch (error) {
-                            if (signal.aborted)
-                                throw signal.reason ?? error;
-                            // Unreadable projections are retried, never cached as current.
-                        }
+                    // Capture both revision baselines before selecting seats and pending facts. A takeover
+                    // during an empty selection must remain visible to the already armed observers.
+                    for (const entry of artifacts.values()) {
+                        sources.push(await capture(entry.observer, 'artifact', signal));
+                        sources.push(await capture(entry.delivery, 'delivery', signal));
                     }
-                    const pending = await eligibleInbox(inbox, options.excludeKeys);
-                    const eligibleKeys = JSON.stringify(pending.flatMap((membership) => membership.notifications.map((note) => notificationKey(membership, note.actIndex))).sort());
+                    const inbox = await currentInbox(candidates, signal);
+                    const pending = eligibleInbox(inbox, options.excludeKeys);
+                    const eligibleKeys = JSON.stringify(pending.flatMap((membership) => membership.notifications.map((note) => pendingKey(membership, note.actIndex))).sort());
                     if (previousEligible !== undefined && previousEligible !== eligibleKeys)
                         canReturn = true;
                     previousEligible = eligibleKeys;
@@ -239,7 +322,7 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
                         return [];
                     // Eligibility may change at lease expiry without any storage write.
                     const leaseExpiry = Math.min(Infinity, ...inbox.flatMap((membership) => membership.catchLease === undefined ? [] : [Math.min(membership.catchLease.expiresAt, membership.catchLease.heartbeatAt + WATCH_STALE_MS + 1)]));
-                    const nextExpiry = Math.min(leaseExpiry, await hostLedger.nextExpiry(sessionId));
+                    const nextExpiry = leaseExpiry;
                     const duration = Math.min(remaining, Math.max(1, nextExpiry - Date.now()));
                     const cancelled = new AbortController();
                     const waitSignal = AbortSignal.any([signal, cancelled.signal]);
@@ -259,8 +342,7 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
                     }
                     try {
                         const change = await Promise.race(waits);
-                        // Evidence writes from our own failed injection must not generate a retry loop.
-                        if (change !== 'evidence')
+                        if (change !== 'delivery')
                             canReturn = true;
                     }
                     finally {
@@ -286,11 +368,13 @@ export async function observeSessionPending(sessionId, suppliedEnv = process.env
             if (lifetime.signal.aborted)
                 return;
             lifetime.abort();
-            ledger.presence.close();
-            ledger.evidence.close();
-            for (const entry of artifacts.values())
+            index.close();
+            for (const entry of artifacts.values()) {
                 entry.observer.close();
+                entry.delivery.close();
+            }
             artifacts.clear();
+            cache.clear();
         },
     };
 }

package/dist/index.d.ts

@@ -1,9 +1,8 @@
 export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare, migrateSquare } from './square-api.js';
-export { SquareError } from './model.js';
-export { squareAssignedParticipantName } from './registry.js';
+export { SquareError, ACTIVITY_METADATA_MAX_BYTES } from './model.js';
+export type { WakeTransportPort, WakeRequest, WakeOutcome } from './ports.js';
+export type { WakeTransports } from './notifications.js';
 export { createDefaultWakeTransport } from './notifications.js';
-export { createHostLedgerPort, FileHostLedgerPort } from './host-ledger-file-adapter.js';
-export type { HostLedgerPort, PresenceRecord, EvidenceRecord } from './host-ledger.js';
 export type { PresentationSinkPort } from './ports.js';
 export type * from './square-backend.js';
 export type * from './square-facade.js';

package/dist/index.js

@@ -1,5 +1,3 @@
 export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare, migrateSquare } from './square-api.js';
-export { SquareError } from './model.js';
-export { squareAssignedParticipantName } from './registry.js';
+export { SquareError, ACTIVITY_METADATA_MAX_BYTES } from './model.js';
 export { createDefaultWakeTransport } from './notifications.js';
-export { createHostLedgerPort, FileHostLedgerPort } from './host-ledger-file-adapter.js';

package/dist/list.js

@@ -1,7 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { openSquare } from './open-square.js';
-import { closeOpenSquare } from './open-square.js';
+import { createArtifactPort } from './artifact.js';
 import { listPresentation } from './views.js';
 import { SquareError } from './model.js';
 export const DEFAULT_LIST_DEPTH = 4;
@@ -16,8 +15,14 @@ async function readSquareListItem(filePath, root, options, control) {
     try {
         control?.signal?.throwIfAborted();
         const stat = await fs.promises.stat(filePath);
-        const square = await openSquare(filePath, { ...options, env: options.env ?? {}, signal: control?.signal }, control);
-        const projection = await listPresentation(square, control).finally(() => closeOpenSquare(square));
+        const artifact = createArtifactPort(filePath, undefined, control?.signal);
+        let projection;
+        try {
+            projection = (await artifact.read(listPresentation, control?.signal)).value;
+        }
+        finally {
+            await artifact.close();
+        }
         return {
             path: path.relative(root, filePath) || path.basename(filePath),
             lastActiveAt: stat.mtimeMs,

package/dist/mcp.js

@@ -25,6 +25,14 @@ export function createSquareMcpServer(options) {
                     const claude = baseEnv.SQUARE_CLAUDE_MCP_CONTEXT === '1'
                         ? await readClaudeMcpCall(extra._meta?.['claudecode/toolUseId'], baseEnv)
                         : undefined;
+                    const body = claude !== undefined
+                        ? { channel: 'claude-code', session: claude.sessionId,
+                            ...(claude.agentId === undefined ? {} : { agent: claude.agentId }) }
+                        : typeof threadId === 'string' && threadId.trim()
+                            ? { channel: 'codex', session: threadId }
+                            : typeof opencodeSessionId === 'string' && opencodeSessionId.trim()
+                                ? { channel: 'opencode', session: opencodeSessionId }
+                                : options.body;
                     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.
@@ -35,7 +43,10 @@ export function createSquareMcpServer(options) {
                                 ? operationEnv('opencode', opencodeSessionId, baseEnv)
                                 : baseEnv;
                     square = await Square.at({
-                        ...options, env, cwd: claude?.cwd ?? options.cwd,
+                        ...options, env, body, cwd: claude?.cwd ?? options.cwd,
+                        // A call-local Codex thread uses its native queue even when managed by Paseo.
+                        wakeAddress: claude === undefined && typeof threadId === 'string' && threadId.trim()
+                            ? { kind: 'codex-queue', address: { threadId } } : options.wakeAddress,
                         path: location ?? options.path,
                         participant: participant ?? options.participant,
                         // The server owner is bound to its configured square; overrides close after each call.

package/dist/model.d.ts

@@ -3,6 +3,37 @@ 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 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 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. */
+export declare function validateActivityMetadata(value: unknown): ActivityMetadata | undefined;
+export declare function activityMetadataHasContent(metadata: ActivityMetadata | undefined): boolean;
+export interface Body {
+    readonly channel: string;
+    readonly session: string;
+    readonly agent?: string;
+}
+export interface WakeAddress {
+    readonly kind: WakeRouteKind;
+    readonly address: Readonly<Record<string, string>>;
+}
+/** Artifact-owned custody binding. Generation is the join activity that established it. */
+export interface Seat {
+    readonly participant: string;
+    readonly body: Body;
+    readonly generation: ActivityId;
+    readonly wakeAddress?: WakeAddress;
+}
+export interface SeatWatchLease {
+    readonly generation: ActivityId;
+    readonly lease: WatchLease;
+}
+export declare function sameBody(left: Body, right: Body): boolean;
+export declare function validateBody(body: Body): void;
 export declare function isWakeRouteKind(value: unknown): value is WakeRouteKind;
 export interface WakeRoute {
     /** Ownership generation, when the receiver publishes a fenced route. */
@@ -80,11 +111,14 @@ export interface InboxNotification {
     route: DirectedNotificationRoute;
     body: string;
 }
-export interface InboxMembership {
-    name: string;
-    squarePath: string;
-    notifications: InboxNotification[];
-    catchLease?: WatchLease;
+export interface LocatedSeat {
+    readonly location: string;
+    readonly seat: Seat;
+    readonly joinedAt: number;
+}
+export interface PendingMembership extends LocatedSeat {
+    readonly notifications: InboxNotification[];
+    readonly catchLease?: WatchLease;
 }
 export interface WatchOptions {
     id?: ActivityId;