@astrosheep/square 0.3.93 → 0.3.94

package/dist/inbox.js

@@ -1,4 +1,3 @@
-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';
@@ -20,8 +19,8 @@ export function pendingAtBoundary(inbox) {
 }
 function eligibleNotifications(facts, membership, now = Date.now()) {
     const seat = facts.seat(membership.seat.participant);
-    if (seat === undefined || seat.generation !== membership.seat.generation
-        || !sameBody(seat.body, membership.seat.body))
+    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;
@@ -68,22 +67,22 @@ export async function projectBoundaryEligibility(inbox) {
 /** 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 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.body.channel, entry.body.session, entry.body.agent ?? null]);
-        candidates.set(key, { location: entry.location, body: entry.body });
+        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, body } of candidates) {
-        const bodies = grouped.get(location) ?? [];
-        bodies.push(body);
-        grouped.set(location, bodies);
+    for (const { location, owner } of candidates) {
+        const owners = grouped.get(location) ?? [];
+        owners.push(owner);
+        grouped.set(location, owners);
     }
     return grouped;
 }
@@ -97,11 +96,11 @@ function locatedSeats(facts, location, seats) {
 /** 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))) {
+    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, bodies.flatMap(body => facts.seatsForBody(body))), signal)).value);
+            seats.push(...(await artifact.read(facts => locatedSeats(facts, location, owners.flatMap(owner => facts.seatsForOwner(owner))), signal)).value);
         }
         catch (error) {
             if (signal?.aborted)
@@ -116,11 +115,11 @@ export async function projectSessionSeats(input, signal) {
 /** 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))) {
+    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, bodies.flatMap(body => facts.seatsForBody(body))).map(({ seat }) => ({
+            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);
         }
@@ -137,13 +136,13 @@ export async function sessionInboxCounts(input, signal) {
 /** 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)) {
+    for (const [location, owners] of groupCandidates(candidates)) {
         signal?.throwIfAborted();
         const artifact = createArtifactPort(location, undefined, signal);
         try {
             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 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) {
@@ -177,14 +176,14 @@ async function projectPending(candidates, cache, signal) {
     return pending;
 }
 function sameWakeAddress(address, kind, requested) {
-    if (address?.kind !== kind)
+    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);
 }
-/** First matching current seat, exact body/generation/address and catch ownership. */
+/** 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.body.session !== input.sessionId
+    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);
@@ -200,10 +199,8 @@ export function nativePendingPreview(facts, input) {
     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);
+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;
@@ -234,10 +231,9 @@ async function capture(observer, kind, signal) {
     }
 }
 /** Session-scoped projection over process-shared storage change detectors. */
-export async function observeSessionPending(identity, suppliedEnv = process.env) {
+export async function observeSessionPending(owner, suppliedEnv = process.env) {
     const env = { ...suppliedEnv };
-    const query = 'allAgents' in identity ? { channel: identity.channel, sessionId: identity.session, env }
-        : { body: identity, env };
+    const query = { owner, env };
     const index = await observeSquareIndex(env);
     const artifacts = new Map();
     const cache = new Map();

package/dist/index.d.ts

@@ -1,8 +1,6 @@
 export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare, migrateSquare } 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 { createDefaultWakeTransport } from './notifications.js';
-export type { PresentationSinkPort } from './ports.js';
-export type * from './square-backend.js';
 export type * from './square-facade.js';

package/dist/index.js

@@ -1,3 +1,3 @@
 export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare, migrateSquare } from './square-api.js';
 export { SquareError, ACTIVITY_METADATA_MAX_BYTES } from './model.js';
-export { createDefaultWakeTransport } from './notifications.js';
+export { selectOwnSeat, requireOwner, localUserOwner, harnessOwner, decodeHarnessOwner } from './square-api.js';

package/dist/mcp.d.ts

@@ -1,7 +1,10 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Owner } from './square-api.js';
 import type { SquareAtInput } from './square-facade.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;
 }
 export type SquareMcpServer = McpServer;
 export declare function createSquareMcpServer(options: SquareMcpOptions): SquareMcpServer;

package/dist/mcp.js

@@ -6,8 +6,10 @@ import { codexWakeAddress } from './codex-address.js';
 import { readClaudeMcpCall } from './claude-mcp-context.js';
 import { SQUARE_IDENTITY } from './identity.js';
 import { Square, createSquareResourceOwner } from './square-api.js';
+import { harnessOwner } from './square-api.js';
 export function createSquareMcpServer(options) {
-    const baseEnv = { ...(options.env ?? process.env) };
+    const { owner: configuredOwner, wakeAddress, ...resourceOptions } = options;
+    const baseEnv = { ...(resourceOptions.env ?? process.env) };
     const resources = createSquareResourceOwner();
     // Calls to the configured square borrow one server-owned connection.
     const inFlight = new Set();
@@ -19,21 +21,20 @@ export function createSquareMcpServer(options) {
             const call = (async () => {
                 let square;
                 try {
-                    const { as: participant, location } = args;
+                    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 body = claude !== undefined
-                        ? { channel: 'claude-code', session: claude.sessionId,
-                            ...(claude.agentId === undefined ? {} : { agent: claude.agentId }) }
+                    const owner = claude !== undefined
+                        ? harnessOwner({ channel: 'claude-code', session: claude.sessionId, ...(claude.agentId === undefined ? {} : { agent: claude.agentId }) })
                         : typeof threadId === 'string' && threadId.trim()
-                            ? { channel: 'codex', session: threadId }
+                            ? harnessOwner({ channel: 'codex', session: threadId })
                             : typeof opencodeSessionId === 'string' && opencodeSessionId.trim()
-                                ? { channel: 'opencode', session: opencodeSessionId }
-                                : options.body;
+                                ? 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.
@@ -44,37 +45,35 @@ export function createSquareMcpServer(options) {
                                 ? operationEnv('opencode', opencodeSessionId, baseEnv)
                                 : baseEnv;
                     square = await Square.at({
-                        ...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()
-                            ? codexWakeAddress(threadId, env) : options.wakeAddress,
+                        ...resourceOptions, env, cwd: claude?.cwd ?? resourceOptions.cwd,
                         path: location ?? options.path,
-                        participant: participant ?? options.participant,
                         // The server owner is bound to its configured square; overrides close after each call.
                         resources: location === undefined && claude === undefined ? resources : undefined,
                     }, { signal: extra.signal });
-                    let receipt;
-                    // The transport shows people the square, so it asks for the rendering facts
-                    // the CLI already gathers and keeps that request out of the tool schema.
+                    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 {
-                        receipt = await tool.run(square, args, { signal: extra.signal, observe: true });
+                        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();
                     }
-                    // A missing observation renders as nothing, never as raw JSON for a person to read.
-                    const text = tool.render(receipt, args) ?? '';
-                    // Observation facts are a rendering aid, not part of the receipt machines receive.
-                    const { observation: _observation, ...structuredContent } = receipt;
-                    return { content: [{ type: 'text', text }], structuredContent };
+                    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 : options.participant,
-                                }) }], structuredContent: { error: failure } };
+                                    participant: typeof participant === 'string' ? participant : undefined,
+                                }) }] };
                 }
             })();
             inFlight.add(call);

package/dist/model.d.ts

@@ -12,11 +12,8 @@ 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;
-}
+/** Opaque custody identity. Harness coordinates are adapter-owned. */
+export type Owner = string;
 export interface WakeAddress {
     readonly kind: WakeRouteKind;
     readonly address: Readonly<Record<string, string>>;
@@ -24,24 +21,22 @@ export interface WakeAddress {
 /** Artifact-owned custody binding. Generation is the join activity that established it. */
 export interface Seat {
     readonly participant: string;
-    readonly body: Body;
+    readonly owner: Owner;
     readonly generation: ActivityId;
+    readonly attachment: 'attached' | 'detached';
     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 validateOwner(owner: Owner): Owner;
 export declare function isWakeRouteKind(value: unknown): value is WakeRouteKind;
 export interface WakeRoute {
     /** Ownership generation, when the receiver publishes a fenced route. */
     epoch?: number;
     location: string;
     participant: string;
-    sessionId: string;
-    channel: string;
     kind: WakeRouteKind;
     address: Record<string, string>;
     updatedAt: number;
@@ -49,10 +44,12 @@ export interface WakeRoute {
 export type SquareErrorCode = 'invalid_name' | 'invalid_args' | 'unknown_participant' | 'not_joined' | 'already_joined' | 'already_done' | 'held' | 'capped' | 'throttled' | 'bell_quota' | 'behind' | 'io' | 'unavailable';
 export type InternalSquareErrorCode = SquareErrorCode | 'not_found' | 'cap_reached' | 'conflict' | 'pending_peer';
 export interface SquareErrorFacts {
+    /** Copyable recovery for a missing, detached or foreign seat. */
+    join?: string;
     /** Express admission rejected before any activity was committed. */
     activityUnsent?: true;
     /** Refusal reason, including absent participants, conflicting reach, and inaccessible activities. */
-    reason?: 'never_joined' | 'not_standing' | 'bell_mention_conflict' | 'not_addressed' | 'migration_required' | 'invalid_reply' | 'invalid_done_body';
+    reason?: 'never_joined' | 'not_standing' | 'bell_mention_conflict' | 'not_addressed' | 'migration_required' | 'invalid_reply' | 'invalid_done_body' | 'needs_seat';
     /** The activity id a `catch --id` refusal named. */
     activityId?: string;
     /** The host ledger requiring offline migration, rather than the selected artifact. */
@@ -122,13 +119,9 @@ export interface PendingMembership extends LocatedSeat {
     readonly deliveryDeferralExpiry?: number;
 }
 export interface WatchOptions {
-    id?: ActivityId;
     participants?: string[];
     mention?: string;
-    limit?: number;
-    idleMs?: number;
     replace?: boolean;
-    now?: boolean;
 }
 export type PublicAct = Extract<StoredAct, {
     kind: 'say' | 'done';

package/dist/model.js

@@ -76,14 +76,11 @@ export function validateActivityMetadata(value) {
 export function activityMetadataHasContent(metadata) {
     return metadata !== undefined && Object.keys(metadata).length > 0;
 }
-export function sameBody(left, right) {
-    return left.channel === right.channel && left.session === right.session && left.agent === right.agent;
-}
-export function validateBody(body) {
-    if (!body || typeof body.channel !== 'string' || !body.channel || typeof body.session !== 'string' || !body.session
-        || (body.agent !== undefined && (typeof body.agent !== 'string' || !body.agent))) {
-        throw new SquareError('invalid_args', 'A participant write requires an explicit channel and session body.');
+export function validateOwner(owner) {
+    if (typeof owner !== 'string' || !owner || Buffer.byteLength(owner, 'utf8') > 512 || /[\u0000-\u001f\u007f-\u009f]/u.test(owner)) {
+        throw new SquareError('invalid_args', 'A participant write requires a non-empty owner without control characters (at most 512 UTF-8 bytes).');
     }
+    return owner;
 }
 export function isWakeRouteKind(value) {
     return typeof value === 'string' && WAKE_ROUTE_KINDS.includes(value);

package/dist/notifications.d.ts

@@ -13,7 +13,7 @@ interface ProcessNotificationOptions {
 export declare function createDefaultWakeTransport(env?: NodeJS.ProcessEnv, suppliedTransports?: WakeTransports): Promise<WakeTransportPort>;
 /** Route selection only: all implementations receive the same request and final gate. */
 export declare function createWakeTransport(transports: WakeTransports): WakeTransportPort;
-export declare function processActNotificationsOnce(squarePath: string, actIndex: number, opts?: ProcessNotificationOptions): Promise<import("./ports.js").DeliveryResult>;
+export declare function processActNotificationsOnce(squarePath: string, actIndex: number, opts?: ProcessNotificationOptions): Promise<void>;
 /** Privileged hook fallback: sweep indexed squares plus the current cwd's local squares within one boundary budget. */
 export declare function sweepPrivilegedPending(cwd: string, env?: NodeJS.ProcessEnv, suppliedTransports?: WakeTransports, deadline?: number, signal?: AbortSignal): Promise<void>;
 export interface SweepPendingNotificationsOptions {

package/dist/notifications.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { canonicalPath } from './canonical-path.js';
 import fs from 'node:fs';
 import { indexedSquareEntries } from './square-index.js';
 import { InternalSquareError, SquareError } from './model.js';
@@ -55,16 +56,15 @@ export function createWakeTransport(transports) {
 export async function processActNotificationsOnce(squarePath, actIndex, opts = {}) {
     const env = opts.env ?? process.env;
     const now = opts.now ?? Date.now;
+    squarePath = await canonicalPath(squarePath);
     const artifact = createArtifactPort(squarePath);
     try {
         await artifact.read(facts => facts.header());
         const transport = await createDefaultWakeTransport(env, opts.transports);
         try {
-            return await deliverPending({ artifact, transport, location: squarePath, activity: actIndex, timeoutMs: Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000), now: now() });
-        }
-        catch {
-            return { attempted: 0, accepted: 0, failed: 0, unknown: 0, notCapable: 1 };
+            await deliverPending({ artifact, transport, location: squarePath, activity: actIndex, timeoutMs: Number(env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? 5000), now: now() });
         }
+        catch { /* Delivery failure does not undo the activity. */ }
     }
     catch (error) {
         if (error instanceof InternalSquareError && error.code === 'not_found')
@@ -92,10 +92,11 @@ export async function sweepPrivilegedPending(cwd, env = process.env, suppliedTra
     if (remainingMs() === 0 || signal?.aborted)
         return;
     const transport = await createDefaultWakeTransport(env, suppliedTransports);
-    for (const squarePath of paths) {
+    for (const candidate of paths) {
         if (remainingMs() === 0 || signal?.aborted)
             break;
         try {
+            const squarePath = await canonicalPath(candidate);
             const artifact = createArtifactPort(squarePath, undefined, signal);
             try {
                 await artifact.read(facts => facts.header(), signal);

package/dist/operation-presentation.d.ts

@@ -7,10 +7,10 @@ export type JoinPresentation = Omit<JoinResult, 'participant'> & {
         readonly name: string;
     } | string;
 };
-export declare function renderJoinResult(data: JoinPresentation): string | undefined;
-export declare function renderExpression(squarePath: string, data: ExpressResult): string | undefined;
+export declare function renderJoinResult(data: JoinPresentation, owner?: string): string | undefined;
+export declare function renderExpression(squarePath: string, data: ExpressResult, owner?: string): string | undefined;
 /** Render settled catch facts; no selection, terminal decisions, receipts or wait machinery. */
-export declare function renderCatchOutcome(squarePath: string, data: CatchResult, options?: CatchOptions): {
+export declare function renderCatchOutcome(squarePath: string, data: CatchResult, options?: CatchOptions, owner?: string): {
     stdout: string;
     exitCode: number;
 };
@@ -31,7 +31,7 @@ export interface FailureReport {
     readonly code: string;
     readonly message: string;
     readonly facts?: {
-        readonly reason?: 'never_joined' | 'not_standing' | 'bell_mention_conflict' | 'not_addressed' | 'migration_required' | 'invalid_reply' | 'invalid_done_body';
+        readonly reason?: 'never_joined' | 'not_standing' | 'bell_mention_conflict' | 'not_addressed' | 'migration_required' | 'invalid_reply' | 'invalid_done_body' | 'needs_seat';
         readonly activityId?: string;
         readonly ledgerRoot?: string;
         readonly activityExists?: boolean;
@@ -42,4 +42,5 @@ export interface FailureReport {
 export declare function renderFailureLines(failure: FailureReport, options?: {
     squarePath?: string;
     name?: string;
+    owner?: string;
 }): string[];