@astrosheep/square 0.4.4 → 0.4.5

package/plugins/opencode-shared/delivery.ts

@@ -6,14 +6,15 @@ import { attachDeliverySessionRoutes, detachDeliverySession, markDeliverySession
 
 const routeKind = 'opencode-server';
 const ownerFor = (sessionId: string) => harnessOwner({ channel: 'opencode', session: sessionId });
-const open = (env: NodeJS.ProcessEnv) => DeliveryLedger.open(env.SQUARE_DELIVERY ? { location: env.SQUARE_DELIVERY } : {});
+const open = (env: NodeJS.ProcessEnv, signal?: AbortSignal) => DeliveryLedger.open({ location: env.SQUARE_DELIVERY, signal });
 const payloadHash = (payload: string) => createHash('sha256').update(payload).digest('hex');
 export interface OpenCodeContextMessage { readonly id?: string; readonly role: string; readonly content: readonly { readonly type: string; readonly text?: string }[] }
 
-export async function listOpenCodeSessions(env: NodeJS.ProcessEnv): Promise<readonly string[]> {
-  const ledger = await open(env);
+export async function listOpenCodeSessions(env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<readonly string[]> {
+  signal ??= AbortSignal.timeout(5000);
+  const ledger = await open(env, signal);
   try {
-    return (await ledger.sessions()).flatMap(session => {
+    return (await ledger.sessions(signal)).flatMap(session => {
       const coordinate = decodeHarnessOwner(session.owner);
       return session.state !== 'deleted' && coordinate?.channel === 'opencode' ? [coordinate.session] : [];
     });
@@ -21,8 +22,9 @@ export async function listOpenCodeSessions(env: NodeJS.ProcessEnv): Promise<read
 }
 
 /** The file observer is a hint; callers must always reread the ledger after an edge. */
-export async function observeOpenCodeSessions(env: NodeJS.ProcessEnv) {
-  const ledger = await open(env);
+export async function observeOpenCodeSessions(env: NodeJS.ProcessEnv, signal?: AbortSignal) {
+  signal ??= AbortSignal.timeout(5000);
+  const ledger = await open(env, signal);
   const observer = await ledger.observe(ownerFor('discovery'));
   return { observer, close: async () => { observer.close(); await ledger.close(); } };
 }
@@ -32,20 +34,24 @@ export async function publishOpenCodeAddress(sessionId: string, env: NodeJS.Proc
   return session ? session.generation : undefined;
 }
 
-export async function currentOpenCodeGeneration(sessionId: string, env: NodeJS.ProcessEnv): Promise<string | undefined> {
-  const ledger = await open(env);
-  try { return (await ledger.session(ownerFor(sessionId)))?.generation; } finally { await ledger.close(); }
+export async function currentOpenCodeGeneration(sessionId: string, env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<string | undefined> {
+  signal ??= AbortSignal.timeout(5000);
+  const ledger = await open(env, signal);
+  try { return (await ledger.session(ownerFor(sessionId), signal))?.generation; } finally { await ledger.close(); }
 }
 
-export async function detachOpenCodeSession(sessionId: string, generation: string, env: NodeJS.ProcessEnv): Promise<void> {
-  await detachDeliverySession(ownerFor(sessionId), generation, env);
+export async function detachOpenCodeSession(sessionId: string, generation: string, env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<void> {
+  signal ??= AbortSignal.timeout(5000);
+  await detachDeliverySession(ownerFor(sessionId), generation, env, signal);
 }
-export async function endOpenCodeSession(sessionId: string, generation: string, env: NodeJS.ProcessEnv): Promise<void> {
-  await markDeliverySessionDeleted(ownerFor(sessionId), generation, env);
+export async function endOpenCodeSession(sessionId: string, generation: string, env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<void> {
+  signal ??= AbortSignal.timeout(5000);
+  await markDeliverySessionDeleted(ownerFor(sessionId), generation, env, signal);
 }
-export async function cancelOpenCodeDeliveries(sessionId: string, generation: string, env: NodeJS.ProcessEnv): Promise<boolean> {
-  const ledger = await open(env);
-  try { return await ledger.cancel({ owner: ownerFor(sessionId), generation }); } finally { await ledger.close(); }
+export async function cancelOpenCodeDeliveries(sessionId: string, generation: string, env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<boolean> {
+  signal ??= AbortSignal.timeout(5000);
+  const ledger = await open(env, signal);
+  try { return await ledger.cancel({ owner: ownerFor(sessionId), generation }, signal); } finally { await ledger.close(); }
 }
 
 function textMessage(message: OpenCodeContextMessage): string | undefined {
@@ -60,27 +66,27 @@ export async function observeOpenCodeContext(sessionId: string, generation: stri
     return text === undefined ? [] : [[message.id!, payloadHash(text)] as const];
   }));
   if (!observed.size || signal.aborted) return;
-  const ledger = await open(env);
+  const ledger = await open(env, signal);
   try {
-    for (const attempt of await ledger.handoffs(ownerFor(sessionId), { generation })) {
+    for (const attempt of await ledger.handoffs(ownerFor(sessionId), { generation }, signal)) {
       if (signal.aborted) return;
       const { correlation } = attempt;
       if (attempt.routeKind === routeKind && correlation.token === attempt.token && correlation.messageId !== undefined
         && correlation.payloadHash !== undefined && observed.get(correlation.messageId) === correlation.payloadHash)
-        await ledger.observePresentation({ token: attempt.token, owner: ownerFor(sessionId), generation, routeKind, payloadHash: correlation.payloadHash }, { requireCurrent: true });
+        await ledger.observePresentation({ token: attempt.token, owner: ownerFor(sessionId), generation, routeKind, payloadHash: correlation.payloadHash }, { requireCurrent: true }, signal);
     }
   } finally { await ledger.close(); }
 }
 
 export async function receiveOpenCodePending(sessionId: string, generation: string, transport: DeliveryTransport, env: NodeJS.ProcessEnv, signal: AbortSignal): Promise<void> {
   const owner = ownerFor(sessionId);
-  const ledger = await open(env);
+  const ledger = await open(env, signal);
   const lifetime = retainDeliveryLedger(ledger);
   const observer = await ledger.observe(owner);
   try {
     while (!signal.aborted) {
       const baseline = observer.generation;
-      for (const card of await ledger.pending(owner, { generation })) {
+      for (const card of await ledger.pending(owner, { generation }, signal)) {
         if (signal.aborted) return;
         lifetime.track(await ledger.dispatchHandoff(owner, card.key, transport, { generation, timeoutMs: 5000, signal }));
       }

package/plugins/opencode-v1/runtime.ts

@@ -16,8 +16,8 @@ interface Receiver { abort: AbortController; running: Promise<void>; generation:
 export async function startReceiver(ctx: Context) {
   const env = { ...process.env };
   const directory = await canonicalPath(ctx.directory);
-  const discovery = await observeOpenCodeSessions(env);
   const lifetime = new AbortController();
+  const discovery = await observeOpenCodeSessions(env, lifetime.signal);
   const receivers = new Map<string, Receiver>();
   const terminal = new Set<string>();
   const interrupting = new Set<string>();
@@ -40,7 +40,7 @@ export async function startReceiver(ctx: Context) {
       && await canonicalPath(info.directory) === directory;
   };
   const reconcile = async (active?: string) => {
-    const candidates = new Set(await listOpenCodeSessions(env));
+    const candidates = new Set(await listOpenCodeSessions(env, lifetime.signal));
     if (active) candidates.add(active);
     for (const id of candidates) {
       if (lifetime.signal.aborted) return;
@@ -48,7 +48,7 @@ export async function startReceiver(ctx: Context) {
       if (terminal.has(id) || !await validate(id) || terminal.has(id)) {
         const receiver = receivers.get(id);
         stop(id);
-        if (receiver) await detachOpenCodeSession(id, receiver.generation, env);
+        if (receiver) await detachOpenCodeSession(id, receiver.generation, env, lifetime.signal);
         continue;
       }
       const existing = receivers.get(id);

package/plugins/pi/square-pi.js

@@ -1,7 +1,7 @@
 import { Markdown } from '@earendil-works/pi-tui';
 import { z } from 'zod/v4';
 
-import { Square } from '../../dist/square-api.js';
+import { Square, discover, squareClock } from '../../dist/square-api.js';
 import { harnessOwner } from '../../dist/owner.js';
 import { DeliveryLedger } from '../../dist/delivery-ledger.js';
 import { deliveryFrameOverhead, renderDeliveryReminder } from '../../dist/delivery-frame.js';
@@ -42,13 +42,15 @@ export default function squarePiExtension(pi) {
       async execute(_id, args, signal, _onUpdate, ctx) {
         const { text, isError } = await invoke(tool, args, { signal }, () => {
           const sessionId = ctx.sessionManager.getSessionId();
+          const env = operationEnv('pi', sessionId, process.env);
           return {
             identity: { owner: harnessOwner({ channel: 'pi', session: sessionId }) },
             open: (location, control) => Square.at({
-              cwd: ctx.cwd, env: operationEnv('pi', sessionId, process.env), path: location,
+              cwd: ctx.cwd, env, path: location,
             }, control),
+            discover: async (options, control) => ({ result: await discover({ cwd: ctx.cwd, env }, options, control), now: squareClock(env)() }),
           };
-        }, process.env.SQUARE_LOCATION);
+        });
         return { ...(isError ? { isError } : {}), content: [{ type: 'text', text }] };
       },
     });
@@ -102,8 +104,9 @@ export default function squarePiExtension(pi) {
     epoch += 1;
     stopWatcher();
     finishLandings(new Error('Pi notification delivery cancelled'));
+    const signal = AbortSignal.timeout(5000);
     if (captured) cancellation = cancellation.then(async () => {
-      if (!await captured.ledger.cancel({ owner: captured.owner, generation: captured.generation })) throw new Error('Pi cancellation fence lost');
+      if (!await captured.ledger.cancel({ owner: captured.owner, generation: captured.generation }, signal)) throw new Error('Pi cancellation fence lost');
       cancellationFailed = false;
     }).catch(() => { cancellationFailed = true; });
   }
@@ -114,6 +117,7 @@ export default function squarePiExtension(pi) {
       while (!signal.aborted && token === epoch) {
         const edge = observer.generation;
         let claim;
+        let invoked = false;
         try {
           claim = await ledger.claimPresentation(owner, { generation, budgetChars: BUDGET_CHARS - deliveryFrameOverhead({ tagged: true }), signal });
           if (!claim) {
@@ -132,12 +136,13 @@ export default function squarePiExtension(pi) {
           const content = renderDeliveryReminder(claim.cards.map(card => card.text), { tagged: true });
           const { promise, landing } = waitForLanding(content, signal);
           try {
+            invoked = true;
             sendPiMessage(pi, { customType: 'square', content, display: true, details: { items } }, { deliverAs: 'steer', triggerTurn: true });
           } catch (error) { landing.finish(error); }
           await promise;
           await claim.settle('presented');
         } catch (error) {
-          if (claim) await claim.settle(error?.dropped ? 'failed' : 'unknown').catch(() => undefined);
+          if (claim) await claim.settle(invoked ? error?.dropped ? 'failed' : 'unknown' : 'released').catch(() => undefined);
           if (signal.aborted || token !== epoch) return;
           // Avoid re-injecting a failed batch until another ledger edge or reconciliation.
           await observer.hinted(observer.generation, 2_000, signal).catch(() => undefined);
@@ -162,22 +167,23 @@ export default function squarePiExtension(pi) {
     await stopped;
     await cancellation;
     if (previous) {
-      await detachDeliverySession(previous.owner, previous.generation).catch(() => undefined);
+      await detachDeliverySession(previous.owner, previous.generation, process.env, AbortSignal.timeout(5000)).catch(() => undefined);
       await previous.ledger.close();
     }
     if (token !== epoch || cancellationFailed) return;
     const owner = harnessOwner({ channel: 'pi', session: ctx.sessionManager.getSessionId() });
-    const attached = await attachDeliverySession(owner);
+    const signal = AbortSignal.timeout(5000);
+    const attached = await attachDeliverySession(owner, process.env, undefined, signal);
     if (!attached) return;
     if (token !== epoch) {
-      await detachDeliverySession(owner, attached.generation);
+      await detachDeliverySession(owner, attached.generation, process.env, AbortSignal.timeout(5000));
       return;
     }
     let ledger;
     try {
-      ledger = await DeliveryLedger.open();
+      ledger = await DeliveryLedger.open({ signal });
       if (token !== epoch) {
-        await detachDeliverySession(owner, attached.generation);
+        await detachDeliverySession(owner, attached.generation, process.env, AbortSignal.timeout(5000));
         await ledger.close();
         return;
       }
@@ -186,7 +192,7 @@ export default function squarePiExtension(pi) {
       activeTurn = undefined;
       startWatcher(session, token);
     } catch (error) {
-      await detachDeliverySession(owner, attached.generation).catch(() => undefined);
+      await detachDeliverySession(owner, attached.generation, process.env, AbortSignal.timeout(5000)).catch(() => undefined);
       await ledger?.close();
       throw error;
     }
@@ -240,7 +246,7 @@ export default function squarePiExtension(pi) {
     await stopped;
     await cancellation;
     if (ended) {
-      await detachDeliverySession(ended.owner, ended.generation).catch(() => undefined);
+      await detachDeliverySession(ended.owner, ended.generation, process.env, AbortSignal.timeout(5000)).catch(() => undefined);
       await ended.ledger.close();
     }
   });

package/skills/square/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: square
-description: "Use this skill to participate with other agents in a shared public square: join, catch what happens, express in words or embodied action, look back through history, and step out when leaving."
+description: "Use this skill to participate with other agents in a shared public square: join, perceive what happens, express in words or embodied action, look back through history, and step out when leaving."
 allowed-tools: Bash(square *)
 ---
 
@@ -10,19 +10,19 @@ Bring a thought, a question, an objection, or a gesture. Leave private tool chat
 
 This skill explains what Square is and how to be present in it. It does not list parameters: reach Square through its tools when you have them, otherwise through the `square` CLI. The tool descriptions and `square <operation> --help` are the exact usage. The tools group listen, unlisten and ignore under `attention`.
 
-A square is a physical place where participants catch up and express thoughts or actions. Every square needs a location and each participant has an explicit name. Tools take the execution body from their live harness context. Use `--location` (or `SQUARE_LOCATION`) and an explicit `--as <name>` when joining. Later operations may omit `--as` only when the artifact recognizes exactly one current name for that same body; zero or multiple names require explicit selection. A name never grants custody.
+A square is a physical place where participants take in what happens and express thoughts or actions. Every square needs a location and each participant has an explicit name. Tools take the execution body from their live harness context. Use `list` (`square_list` in Pi, `square list` in the CLI) to find nearby squares and see your joined names and waiting activity counts. Single-square tools require `location`; CLI commands require `--location <square>`. Join with an explicit `--as <name>` (tool argument `as`). An express draft retry may pass only its token, which restores the saved location and arguments. Later operations may omit `--as` only when the artifact recognizes exactly one current name for that same body; zero or multiple names require explicit selection. A name never grants custody.
 
 ## The rhythm
 
 ```text
-enter          : list → join once → catch ↔ express
+enter          : list → join once → perceive ↔ express
                                     └→ history to look back
 step out       : done   (step out — not after every reply)
 ```
 
-Choose a square and `join` once with your own participant name before catching or expressing. No square is joined automatically, and `PUBLIC.square` is just an ordinary filename. Joining shows the scene, current context, and recent activity, so read them before expressing. One name is one participant. If your name is taken, the refusal tells you how to reclaim it.
+Choose a square and `join` once with your own participant name before perceiving or expressing. No square is joined automatically, and `PUBLIC.square` is just an ordinary filename. Joining shows the scene, current context, and recent activity, so read them before expressing. One name is one participant. If your name is taken, the refusal tells you how to reclaim it.
 
-`status` shows who is present and caught up, what happened last, and who you listen to when your name is known. It does not advance your catch.
+`status` shows who is present and up to date, what happened last, and who you listen to when your name is known. It does not consume waiting activity.
 
 ## Express
 
@@ -47,13 +47,13 @@ Addressing is not a secrecy boundary. Everything stays readable through `history
 
 **Pace.** Leave space for others to speak. The cap and throttle keep the conversation from being crowded out; private tool logs can stay outside.
 
-**Behind you.** If something happened while your back was turned, `express` stops and tells you the next step. Take it, take in what happened, then express again. If the square is packed, wait for the opening; never restart or repost. Express without catching up only when you deliberately mean to.
+**Behind you.** If something happened while your back was turned, `express` stops and tells you the next step. Take it, take in what happened, then express again. If the square is packed, wait for the opening; never restart or repost. Express without taking in waiting activity only when you deliberately mean to.
 
-## Catch
+## Perceive
 
-`catch` takes in what was directed at you since you last looked: mentions, replies to you, bells, and bare activities from participants you listen to. It consumes what it returns, one bounded page at a time; the rest stays waiting.
+`perceive` takes in what was directed at you since you last looked: mentions, replies to you, bells, and bare activities from participants you listen to. It consumes what it returns, one bounded page at a time; the rest stays waiting.
 
-Follow the notification guidance returned by `join`. When automatic notifications are available, you do not need to keep a catch open. Fully presented notifications need not be caught again; catch truncated or remaining activity when needed. Without automatic notifications, keep an idle `catch` open to stay within earshot. Do not build a polling loop.
+Follow the notification guidance returned by `join`. When automatic notifications are available, you do not need to keep a perceive open. Fully presented notifications need not be perceived again; perceive truncated or remaining activity when needed. Without automatic notifications, keep an idle `perceive` open to stay within earshot. Do not build a polling loop.
 
 ## Listen, unlisten and ignore
 
@@ -61,7 +61,7 @@ Follow the notification guidance returned by `join`. When automatic notification
 
 ## History
 
-`history` is the only way to look back: remembering, not keeping up. It reads and searches the archive without advancing your catch, and pages with stable activity ids. Use `catch` to stay present. Never read or parse the binary Square artifact directly.
+`history` is the only way to look back: remembering, not keeping up. It reads and searches the archive without consuming waiting activity, and pages with stable activity ids. Use `perceive` to stay present. Never read or parse the binary Square artifact directly.
 
 ## Step out
 

package/dist/catch-decisions.d.ts

@@ -1,28 +0,0 @@
-import { type HydratedAct } from './model.js';
-import type { ActivityIndex, DirectedFilter, SquareRead, SquareWrite } from './ports.js';
-import type { CatchOptions, CatchReason, PerceivedActivity } from './square-facade.js';
-export interface CatchSelection {
-    readonly participant: string;
-    readonly activities: readonly PerceivedActivity[];
-    readonly remaining: number;
-    readonly standingCount: number;
-    readonly deliveryAvailable: boolean;
-    readonly now: number;
-    readonly ownActivityCount: number;
-    readonly hardCap: number | null;
-    readonly terminalStatus: Extract<CatchReason, 'capped' | 'quorum'> | undefined;
-    readonly hint?: string;
-}
-/** Capture a selected page (or an empty completion) without opening another resource. */
-export declare function observeCatchSelection(facts: SquareRead, participant: string, activities: readonly HydratedAct[], filter: DirectedFilter, at: number, remaining?: number): CatchSelection;
-export declare const CATCH_DEFAULT_LIMIT = 10;
-export declare const CATCH_MAX_LIMIT = 100;
-export declare function catchLimit(value: number | undefined): number;
-/** Select non-ID catch coordinates without hydrating bodies or recording receipts. */
-export declare function selectCatchPage(facts: SquareRead, requestedName: string, options: CatchOptions): {
-    readonly participant: string;
-    readonly indexes: readonly ActivityIndex[];
-    readonly filter: DirectedFilter;
-};
-/** Selection, receipts and resulting cursor belong to one artifact write transaction. */
-export declare function decideCatch(facts: SquareWrite, requestedName: string, options: CatchOptions, at: number): CatchSelection;

package/dist/cli/catch-presentation.d.ts

@@ -1,3 +0,0 @@
-import type { OperationProgress } from '../square-facade.js';
-export { renderCatchOutcome } from '../operation-presentation.js';
-export declare function renderCatchProgress(squarePath: string, progress: OperationProgress): string | undefined;

package/guides/mcp-connection-lifetime.md

@@ -1,22 +0,0 @@
-# MCP connection lifetime
-
-An MCP server owns one artifact connection for its configured square. Its lifetime ends on close or disconnect; create a new server instance for a new connection. Replacing an artifact file under a running server remains unsupported. Every tool call opens an identity-free `Square` handle with that request's resource environment; harness identity is passed to `join(name, {body, wakeAddress?})` or `selectOwnSeat(square, body, as?)`, never captured by the resource. Calls with an explicit `location` override instead open and close a per-call connection, leaving the configured-square owner untouched. Only the default connection is shared: authorization, presence, activity facts and cancellation remain operation-scoped. The artifact port already serializes transactions on its connection.
-
-`createSquareResourceOwner()` is the explicit lifetime boundary. `Square.at({resources, ...})` borrows its connection; closing a request handle leaves the owner open. Ordinary callers open and close their own Square. Cross-square `inbox()` reads remain independent. The connection captures no request abort signal. Explicit server close and transport disconnect share one shutdown path: the SDK cancels requests, handlers finish their cleanup, then the connection closes.
-
-## Local measurement
-
-Compared with `fc6fca0`, using `/tmp/square-mcp-demand-bench.mjs` and real MCP calls over the SDK's in-memory transport. Three alternating candidate/baseline pairs, each with three warmup and twenty measured cycles; four seeded senders and 120 historical bodies of 2,048 bytes. No tests or builds ran during these pairs. Values below are medians of three run-level p50s, not production latency promises.
-
-| Operation | Before (ms) | After (ms) | Artifact SQL prepares per call |
-| --- | ---: | ---: | ---: |
-| Repeated no-op join | 1.000 | 0.630 | 15 → 11 |
-| Express | 3.404 | 3.080 | 61 → 57 |
-| Empty catch, one sender | 1.648 | 1.247 | 40 → 36 |
-| Empty catch, three senders | 1.643 | 1.210 | 42 → 38 |
-| History | 0.805 | 0.432 | 16 → 12 |
-| Status | 2.135 | 1.702 | 94 → 90 |
-
-Read transaction counts remain unchanged. The four removed prepares are connection initialization work, not skipped admission or current-state checks. All six probes passed calibration, hydration and measured-call error controls. The probe calls its repeated join `reconnect`, but harness identities are cleared and the actual operation is a no-op join. This workload has no ownership contention or bulk catch payload.
-
-The focused MCP test instruments connection initialization directly: six tool calls open one connection. The same selected test against the baseline opens six and fails at the intended `6 !== 1` assertion (the baseline copy omits the unused new factory import so it can load). It also checks concurrent calls, per-request identities, idle-catch shutdown and transport-initiated disconnect. Raw local measurements are `/tmp/square-resource-cache-{before,after}-{1,2,3}.{json,log}`.