@astrosheep/square 0.3.106 → 0.4.1

package/dist/inbox.js

@@ -1,391 +1,35 @@
-import { createArtifactPort, observeSquareDeliveryRevision, observeSquareRevision } from './artifact.js';
-import { indexedSquareEntries, observeSquareIndex } from './square-index.js';
+import path from 'node:path';
+import { createArtifactPort } from './artifact.js';
+import { discoverSquares, MAX_LIST_LIMIT } from './list.js';
 import { canonicalPath } from './canonical-path.js';
-import { formatActivityId, parseActivityId } from './square-core.js';
-import { freshWatchLease, WATCH_STALE_MS } from './runtime.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) {
-    return membership.location + '\0' + membership.seat.participant.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);
-}
-function eligibleNotifications(facts, membership, now = Date.now()) {
-    const seat = facts.seat(membership.seat.participant);
-    if (seat === undefined || seat.attachment !== 'attached' || seat.generation !== membership.seat.generation
-        || seat.owner !== membership.seat.owner)
-        return { notifications: [] };
-    const cancelledThrough = facts.cancelledThrough(seat.participant, seat.generation);
-    let expiry = Infinity;
-    const notifications = membership.notifications.filter(notification => {
-        if (cancelledThrough !== undefined && notification.actIndex <= cancelledThrough
-            || facts.deliveryEvidence(seat.participant, seat.generation, formatActivityId(notification.actIndex))
-                .some(row => row.outcome !== 'failed' && row.outcome !== 'released'))
-            return false;
-        const deferredUntil = deliveryDeferralExpiry(facts, seat, notification.actIndex, now);
-        if (deferredUntil === undefined)
-            return true;
-        expiry = Math.min(expiry, deferredUntil);
-        return false;
-    });
-    return { notifications, ...(expiry === Infinity ? {} : { deliveryDeferralExpiry: expiry }) };
-}
-/** 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 eligibility = eligibleNotifications(facts, membership);
-                return eligibility.notifications.length === 0 ? [] : [{ ...membership, ...eligibility }];
-            }));
-            pending.push(...value);
-        }
-        catch {
-            // An unreadable or stale candidate cannot authorize boundary presentation.
-        }
-        finally {
-            await artifact.close();
-        }
-    }
-    return pending;
-}
-/** 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({ owner: input.owner }, 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.owner]);
-        candidates.set(key, { location: entry.location, owner: entry.owner });
-    }
-    return [...candidates.values()];
-}
-function groupCandidates(candidates) {
-    const grouped = new Map();
-    for (const { location, owner } of candidates) {
-        const owners = grouped.get(location) ?? [];
-        owners.push(owner);
-        grouped.set(location, owners);
-    }
-    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, owners] of groupCandidates(await projectSessionCandidates(input))) {
-        signal?.throwIfAborted();
-        const artifact = createArtifactPort(location, undefined, signal);
-        try {
-            seats.push(...(await artifact.read(facts => locatedSeats(facts, location, owners.flatMap(owner => facts.seatsForOwner(owner))), 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. */
+/** Filesystem-scoped membership counts. This is a World read, not a delivery scan. */
 export async function sessionInboxCounts(input, signal) {
+    const root = path.resolve(input.cwd ?? process.cwd());
     const rows = [];
-    for (const [location, owners] of groupCandidates(await projectSessionCandidates(input))) {
-        signal?.throwIfAborted();
-        const artifact = createArtifactPort(location, undefined, signal);
-        try {
-            rows.push(...(await artifact.read(facts => locatedSeats(facts, location, owners.flatMap(owner => facts.seatsForOwner(owner).filter(seat => seat.attachment === 'attached'))).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;
-}
-/** One authoritative read per canonical artifact, even when discovery names several bodies. */
-async function projectPending(candidates, cache, signal) {
-    const pending = [];
-    for (const [location, owners] of groupCandidates(candidates)) {
+    let after;
+    do {
         signal?.throwIfAborted();
-        const artifact = createArtifactPort(location, undefined, signal);
-        try {
-            const { value: current } = await artifact.read(facts => {
-                const seats = owners.flatMap(owner => facts.seatsForOwner(owner).filter(seat => seat.attachment === 'attached'));
-                const coordinate = JSON.stringify([owners, seats.map(seat => [seat.participant, seat.owner, 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 => {
-                            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.
-                return { cached, pending: cached.value.map(membership => {
-                        const catchLease = freshWatchLease(facts, membership.seat.participant);
-                        return { ...membership, ...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;
-            // Unreadable candidates remain watch targets, but never authorize cached content.
-        }
-        finally {
-            await artifact.close();
-        }
-    }
-    return pending;
-}
-function sameWakeAddress(address, kind, requested) {
-    if (address?.kind !== kind || Object.keys(address.address).length !== Object.keys(requested).length)
-        return false;
-    return Object.entries(requested).every(([key, value]) => address.address[key] === value);
-}
-/** Current-generation native attention, owned by its exact wake address and catch state. */
-export function nativePendingPreview(facts, input) {
-    const seat = facts.seat(input.participant);
-    if (seat === undefined || seat.attachment !== 'attached' || seat.generation !== input.generation
-        || !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' || 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)', 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);
-}
-async function capture(observer, kind, signal) {
-    const generation = observer.generation;
-    try {
-        const value = await observer.read(signal);
-        return { kind, value, wait: (timeout, abort) => observer.changed(value, timeout, abort) };
-    }
-    catch (error) {
-        if (signal.aborted)
-            throw signal.reason ?? error;
-        // Failed revision reads are not changes; only a successful retry wakes projection.
-        return { kind, wait: async (timeout, abort) => {
-                const deadline = Date.now() + Math.max(0, timeout);
-                let since = generation;
-                while (await observer.hinted(since, Math.max(0, deadline - Date.now()), abort)) {
-                    since = observer.generation;
-                    try {
-                        await observer.read(abort);
-                        return true;
-                    }
-                    catch (error) {
-                        if (abort.aborted)
-                            throw abort.reason ?? error;
-                    }
-                }
-                return false;
-            } };
-    }
-}
-/** Session-scoped projection over process-shared storage change detectors. */
-export async function observeSessionPending(owner, suppliedEnv = process.env) {
-    const env = { ...suppliedEnv };
-    const query = { owner, env };
-    const index = await observeSquareIndex(env);
-    const artifacts = new Map();
-    const cache = new Map();
-    const lifetime = new AbortController();
-    async function currentInbox(candidates, signal) {
-        const inbox = await projectPending(candidates, cache, signal);
-        const now = Date.now();
-        return inbox.map((membership) => {
-            const { catchLease, ...rest } = membership;
-            return catchLease !== undefined && catchLease.expiresAt > now && now - catchLease.heartbeatAt <= WATCH_STALE_MS
-                ? membership : rest;
-        });
-    }
-    function eligibleInbox(inbox, excludeKeys) {
-        const eligible = pendingAtBoundary(inbox);
-        return excludeKeys === undefined ? eligible : eligible.flatMap((membership) => {
-            const notifications = membership.notifications.filter((notification) => !excludeKeys.has(pendingKey(membership, notification.actIndex)));
-            return notifications.length === 0 ? [] : [{ ...membership, notifications }];
-        });
-    }
-    return {
-        async read(options = {}) {
-            const signal = AbortSignal.any([lifetime.signal, ...(options.signal === undefined ? [] : [options.signal])]);
-            signal.throwIfAborted();
-            const inbox = await currentInbox(await projectSessionCandidates(query), signal);
-            const pending = eligibleInbox(inbox, options.excludeKeys);
-            signal.throwIfAborted();
-            return pending;
-        },
-        async wait(timeoutMs, options = {}) {
-            const deadline = Date.now() + Math.max(0, timeoutMs);
-            const expired = new AbortController();
-            const timer = Number.isFinite(timeoutMs) && timeoutMs > 0
-                ? setTimeout(() => expired.abort(), Math.min(timeoutMs, 2_147_483_647)) : undefined;
-            const signal = AbortSignal.any([lifetime.signal, expired.signal, ...(options.signal === undefined ? [] : [options.signal])]);
-            let canReturn = !options.skipImmediate;
-            let previousEligible;
-            let armed = false;
-            let candidates = [];
-            let candidatePresence;
-            let discoveredCandidates = false;
+        const page = await discoverSquares(root, { limit: MAX_LIST_LIMIT, ...(after === undefined ? {} : { after }) }, { signal });
+        for (const item of page.items) {
+            signal?.throwIfAborted();
+            const location = await canonicalPath(path.resolve(root, item.path));
+            const artifact = createArtifactPort(location, undefined, signal);
             try {
-                while (!signal.aborted) {
-                    // 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, delivery });
-                    }
-                    // 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 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;
-                    if (signal.aborted)
-                        return [];
-                    if (canReturn && pending.length > 0)
-                        return pending;
-                    const remaining = deadline - Date.now();
-                    if (remaining <= 0)
-                        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, ...inbox.map(membership => membership.deliveryDeferralExpiry ?? Infinity));
-                    const duration = Math.min(remaining, Math.max(1, nextExpiry - Date.now()));
-                    const cancelled = new AbortController();
-                    const waitSignal = AbortSignal.any([signal, cancelled.signal]);
-                    const waits = sources.map(async (source) => {
-                        try {
-                            return await source.wait(duration, waitSignal) ? source.kind : 'deadline';
-                        }
-                        catch (error) {
-                            if (waitSignal.aborted)
-                                throw error;
-                            return source.kind;
-                        }
-                    });
-                    if (!armed) {
-                        armed = true;
-                        options.onChangeArmed?.(true);
-                    }
-                    try {
-                        const change = await Promise.race(waits);
-                        if (change !== 'delivery')
-                            canReturn = true;
-                    }
-                    finally {
-                        cancelled.abort();
-                        await Promise.allSettled(waits);
-                    }
-                }
-                return [];
+                rows.push(...(await artifact.read(facts => facts.seatsForOwner(input.owner)
+                    .filter(seat => facts.participant(seat.participant)?.joined)
+                    .map(seat => ({ name: seat.participant, squarePath: location,
+                    pending: facts.directedCount(seat.participant, { unseenOnly: true, currentGeneration: true }) })), signal)).value);
             }
             catch (error) {
-                if (signal.aborted)
-                    return [];
-                throw error;
+                if (signal?.aborted)
+                    throw signal.reason ?? error;
+                // Discovery candidates may disappear or become unreadable before this read.
             }
             finally {
-                if (timer !== undefined)
-                    clearTimeout(timer);
-                if (!armed)
-                    options.onChangeArmed?.(false);
-            }
-        },
-        close() {
-            if (lifetime.signal.aborted)
-                return;
-            lifetime.abort();
-            index.close();
-            for (const entry of artifacts.values()) {
-                entry.observer.close();
-                entry.delivery.close();
+                await artifact.close();
             }
-            artifacts.clear();
-            cache.clear();
-        },
-    };
+        }
+        after = page.next;
+    } while (after !== undefined);
+    return rows;
 }

package/dist/index.d.ts

@@ -1,6 +1,9 @@
-export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare, migrateSquare } from './square-api.js';
+export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare } from './square-api.js';
 export { SquareError, ACTIVITY_METADATA_MAX_BYTES } from './model.js';
-export { selectOwnSeat, requireOwner, localUserOwner, harnessOwner, decodeHarnessOwner } from './square-api.js';
-export type { WakeTransportPort, WakeRequest, WakeOutcome } from './ports.js';
-export type { WakeTransports } from './notifications.js';
+export { selectOwnSeat, requireOwner, requireJoinName, localUserOwner, harnessOwner, decodeHarnessOwner } from './square-api.js';
+export { postAndDispatch, dispatchEligibleCards } from './notifications.js';
+export { DeliveryLedger, deliveryLedgerLocation } from './delivery-ledger.js';
+export type * from './delivery-ledger.js';
+export { isCardPresentation } from './card-presentation.js';
+export type { CardPresentation } from './card-presentation.js';
 export type * from './square-facade.js';

package/dist/index.js

@@ -1,3 +1,6 @@
-export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare, migrateSquare } from './square-api.js';
+export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare } from './square-api.js';
 export { SquareError, ACTIVITY_METADATA_MAX_BYTES } from './model.js';
-export { selectOwnSeat, requireOwner, localUserOwner, harnessOwner, decodeHarnessOwner } from './square-api.js';
+export { selectOwnSeat, requireOwner, requireJoinName, localUserOwner, harnessOwner, decodeHarnessOwner } from './square-api.js';
+export { postAndDispatch, dispatchEligibleCards } from './notifications.js';
+export { DeliveryLedger, deliveryLedgerLocation } from './delivery-ledger.js';
+export { isCardPresentation } from './card-presentation.js';

package/dist/mcp.d.ts

@@ -1,10 +1,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Owner } from './square-api.js';
 import type { SquareAtInput } from './square-facade.js';
+import type { WakeAddress } from './model.js';
 /** The server owns its artifact connection lifetime, so callers cannot lend one. */
 export interface SquareMcpOptions extends Omit<SquareAtInput, 'resources'> {
     readonly owner?: Owner;
-    readonly wakeAddress?: import('./model.js').WakeAddress;
+    readonly wakeAddress?: WakeAddress;
 }
 export type SquareMcpServer = McpServer;
 export declare function createSquareMcpServer(options: SquareMcpOptions): SquareMcpServer;

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, SquareExpressDrafts, squareToolsEnabled, squareToolFailure, squareToolFailureText } from './square-tools.js';
+import { SQUARE_TOOLS, SQUARE_TOOL_INSTRUCTIONS, createSquareToolRunner, squareToolsEnabled } from './square-tools.js';
 import { operationEnv } from './participant-identity.js';
 import { codexWakeAddress } from './codex-address.js';
 import { readClaudeMcpCall } from './claude-mcp-context.js';
@@ -12,7 +12,7 @@ export function createSquareMcpServer(options) {
     const baseEnv = { ...(resourceOptions.env ?? process.env) };
     const toolsEnabled = squareToolsEnabled(baseEnv);
     const resources = createSquareResourceOwner();
-    const drafts = new SquareExpressDrafts();
+    const invoke = createSquareToolRunner();
     // Calls to the configured square borrow one server-owned connection.
     const inFlight = new Set();
     const server = new McpServer({ name: 'square', version: SQUARE_IDENTITY.packageVersion }, {
@@ -21,77 +21,47 @@ export function createSquareMcpServer(options) {
     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;
-                    let toolArgs = args;
-                    let owner;
-                    let draftToken;
-                    let expressAttempted = false;
-                    try {
-                        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;
-                        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;
-                        if (tool.name === 'express') {
-                            const resolved = drafts.resolve(toolArgs, owner);
-                            toolArgs = resolved.args;
-                            draftToken = resolved.token;
-                        }
-                        const { location } = toolArgs;
-                        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({
+                const call = invoke(tool, args, { signal: extra.signal }, async () => {
+                    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),
+                            // An agent loop ID is not a session ID.
+                            CLAUDE_CODE_CHILD_SESSION: claude.agentId === undefined ? '' : '1' }
+                        : typeof threadId === 'string' && threadId.trim()
+                            ? operationEnv('codex', threadId, baseEnv)
+                            : typeof opencodeSessionId === 'string' && opencodeSessionId.trim()
+                                ? operationEnv('opencode', opencodeSessionId, baseEnv)
+                                : baseEnv;
+                    const 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;
+                    return {
+                        identity: { owner, wakeAddress: claude === undefined && typeof threadId === 'string' && threadId.trim()
+                                ? { ...codexWakeAddress(threadId, env), kind: 'codex-queue' } : callWake },
+                        open: (location, control) => 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.
+                            // Overrides and Claude calls own their connections.
                             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 {
-                            expressAttempted = tool.name === 'express';
-                            text = await tool.run(square, toolArgs, { signal: extra.signal }, {
-                                owner, wakeAddress: claude === undefined && typeof threadId === 'string' && threadId.trim()
-                                    ? codexWakeAddress(threadId, env) : callWake,
-                            });
-                            drafts.consume(draftToken);
-                        }
-                        finally {
-                            await square.close();
-                        }
-                        return { content: [{ type: 'text', text }] };
-                    }
-                    catch (error) {
-                        const failure = squareToolFailure(error, extra.signal);
-                        const participant = toolArgs.as;
-                        const draft = tool.name === 'express' ? drafts.retain(toolArgs, owner, draftToken, failure, expressAttempted) : undefined;
-                        return { isError: true, content: [{ type: 'text', text: squareToolFailureText(failure, {
-                                        location: square?.location ?? options.path,
-                                        participant: typeof participant === 'string' ? participant : undefined,
-                                        draft,
-                                    }) }] };
-                    }
-                })();
+                        }, control),
+                    };
+                }, options.path).then(({ text, isError }) => ({
+                    ...(isError ? { isError } : {}), content: [{ type: 'text', text }],
+                }));
                 inFlight.add(call);
                 return call.finally(() => { inFlight.delete(call); });
             });

package/dist/message.d.ts

@@ -0,0 +1,7 @@
+export type MessageId = `msg/${number}`;
+/** Opaque endpoint custody token, allocated when an endpoint is established. */
+export type EndpointGeneration = string;
+export declare function formatMessageId(index: number): MessageId;
+export declare function parseMessageId(value: string): number | undefined;
+export declare function newEndpointGeneration(): EndpointGeneration;
+export declare function validateEndpointGeneration(value: unknown): EndpointGeneration;

package/dist/message.js

@@ -0,0 +1,23 @@
+// Message coordinates belong to Channel alone; Agora activity ids are a separate coordinate.
+import crypto from 'node:crypto';
+export function formatMessageId(index) {
+    if (!Number.isSafeInteger(index) || index < 0)
+        throw new Error(`Invalid message index: ${index}`);
+    return `msg/${index}`;
+}
+export function parseMessageId(value) {
+    if (value === 'msg/0')
+        return 0;
+    if (typeof value !== 'string' || !/^msg\/[1-9]\d*$/.test(value))
+        return undefined;
+    const index = Number(value.slice(4));
+    return Number.isSafeInteger(index) ? index : undefined;
+}
+export function newEndpointGeneration() {
+    return `endpoint/${crypto.randomUUID()}`;
+}
+export function validateEndpointGeneration(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 512 || /[\u0000-\u001f\u007f-\u009f]/u.test(value))
+        throw new TypeError('Endpoint generation must be a non-empty opaque token without control characters.');
+    return value;
+}