@astrosheep/square 0.4.3 → 0.4.5

package/dist/sqlite-transaction.js

@@ -3,8 +3,11 @@ function abort(signal) {
     if (signal?.aborted)
         throw signal.reason ?? new Error('SQLite operation aborted');
 }
-function isBusy(error) {
-    return error instanceof Error && /database is locked|database is busy|SQLITE_BUSY/i.test(error.message);
+function isSqliteBusy(error) {
+    const code = error?.code;
+    return typeof code === 'string' && /^SQLITE_BUSY(?:_|$)/.test(code)
+        || typeof error?.errcode === 'number' && (error.errcode & 0xff) === 5
+        || error instanceof Error && /database is locked|database is busy|SQLITE_BUSY/i.test(error.message);
 }
 /** Yield rather than blocking the process while another connection owns SQLite. */
 export async function retrySqliteBusy(operation, signal, retryMs = 25) {
@@ -14,7 +17,7 @@ export async function retrySqliteBusy(operation, signal, retryMs = 25) {
             return operation();
         }
         catch (error) {
-            if (!isBusy(error))
+            if (!isSqliteBusy(error))
                 throw error;
             try {
                 await sleep(typeof retryMs === 'function' ? retryMs() : retryMs, undefined, { signal });
@@ -26,6 +29,25 @@ export async function retrySqliteBusy(operation, signal, retryMs = 25) {
         }
     }
 }
+/** Cancel a queued caller promptly without releasing its place in the connection's serial chain. */
+export async function awaitSqliteQueue(result, signal, started) {
+    if (!signal)
+        return result;
+    let onAbort;
+    try {
+        return await Promise.race([result, new Promise((_, reject) => {
+                onAbort = () => { if (!started())
+                    reject(signal.reason ?? new Error('SQLite operation aborted')); };
+                signal.addEventListener('abort', onAbort, { once: true });
+                if (signal.aborted)
+                    onAbort();
+            })]);
+    }
+    finally {
+        if (onAbort)
+            signal.removeEventListener('abort', onAbort);
+    }
+}
 /** Acquisition may retry; COMMIT retries retain the callback's result and transaction. */
 export async function inSqliteTransaction(db, write, validate, change, signal) {
     let begun = false, backoffMs = 25;

package/dist/square-api.d.ts

@@ -16,4 +16,4 @@ export declare function selectOwnSeat(square: Pick<SqliteSquare, 'participant' |
 }): Promise<Participant | undefined>;
 export { ACTIVITY_METADATA_MAX_BYTES } from './model.js';
 export { localUserOwner, harnessOwner, decodeHarnessOwner } from './owner.js';
-export { squareClock, createSquareResourceOwner, formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE, CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT, DEFAULT_LIST_DEPTH, MAX_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, diagnoseSquare, discover, inbox } from './sqlite-square.js';
+export { squareClock, formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE, PERCEIVE_DEFAULT_LIMIT, PERCEIVE_MAX_LIMIT, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT, DEFAULT_LIST_DEPTH, MAX_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, diagnoseSquare, discover, inbox } from './sqlite-square.js';

package/dist/square-api.js

@@ -24,4 +24,4 @@ export async function selectOwnSeat(square, owner, name, options) {
 }
 export { ACTIVITY_METADATA_MAX_BYTES } from './model.js';
 export { localUserOwner, harnessOwner, decodeHarnessOwner } from './owner.js';
-export { squareClock, createSquareResourceOwner, formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE, CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT, DEFAULT_LIST_DEPTH, MAX_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, diagnoseSquare, discover, inbox } from './sqlite-square.js';
+export { squareClock, formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE, PERCEIVE_DEFAULT_LIMIT, PERCEIVE_MAX_LIMIT, HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT, DEFAULT_LIST_DEPTH, MAX_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT, diagnoseSquare, discover, inbox } from './sqlite-square.js';

package/dist/square-domain.js

@@ -2,7 +2,7 @@ import { SquareError, nameKey, sameName, validateOwner, validateName } from './m
 import { newEndpointGeneration, validateEndpointGeneration } from './message.js';
 import { resolveAudience } from './attention.js';
 import { freshWatchLease } from './runtime.js';
-import { leaseOwnsNotification } from './catch-selection.js';
+import { leaseOwnsNotification } from './perceive-selection.js';
 export function deriveLanding(activity, facts) {
     const audience = activity.kind === 'say' ? resolveAudience({
         actor: activity.actor, recipients: facts.standing.map(item => item.name), mentions: activity.mentions,

package/dist/square-facade.d.ts

@@ -2,7 +2,6 @@ import type { MetadataMatch } from './delivery-deferral.js';
 export type { MetadataMatch, MetadataScalar } from './delivery-deferral.js';
 import type { ActivityId, Perception, Reach } from './square-core.js';
 import type { Owner, HydratedAct, WakeAddress, ActivityMetadata, DirectedNotificationRoute } from './model.js';
-import type { SquareResourceOwner } from './ports.js';
 import type { OperationControl } from './neutral.js';
 export interface ActivitySearch {
     readonly text: string;
@@ -17,7 +16,7 @@ export interface HeldSeat {
     readonly name: string;
     readonly generation: string;
 }
-export type { CatchWaitStart, OperationProgress, OperationControl, OperationFailureDetail, OperationError } from './neutral.js';
+export type { PerceiveWaitStart, OperationProgress, OperationControl, OperationFailureDetail, OperationError } from './neutral.js';
 export type { ActivityId, Perception, Reach } from './square-core.js';
 export type { Owner, WakeAddress, ActivityMetadata, JsonValue, DirectedNotificationRoute } from './model.js';
 /** Indexed archive event, including read bookkeeping and a say's linked content. */
@@ -76,7 +75,7 @@ export interface LifecycleResult {
     readonly activity: Activity;
     readonly observation?: SquareObservation;
 }
-export interface CatchOptions extends ObservationOptions {
+export interface PerceiveOptions extends ObservationOptions {
     readonly id?: ActivityId;
     readonly idle?: number;
     readonly from?: readonly string[];
@@ -105,14 +104,14 @@ export interface PendingResult {
     /** Matching unconsumed activities outside this page. */
     readonly remaining: number;
 }
-export type CatchReason = 'drained' | 'idle' | 'capped' | 'quorum' | 'replaced' | 'already-active';
-export interface CatchResult {
+export type PerceiveReason = 'drained' | 'idle' | 'capped' | 'quorum' | 'replaced' | 'already-active';
+export interface PerceiveResult {
     readonly activities: readonly PerceivedActivity[];
     readonly remaining: number;
-    readonly reason: CatchReason;
+    readonly reason: PerceiveReason;
     /** Occasional participant-facing nudge; not part of any activity. */
     readonly hint?: string;
-    readonly observation?: CatchObservation;
+    readonly observation?: PerceiveObservation;
 }
 export interface HistoryQuery extends ActivityQuery, ObservationOptions {
     /** Ten by default; null explicitly reads the full archive. */
@@ -136,8 +135,6 @@ export interface SquareLocation {
     readonly env?: NodeJS.ProcessEnv;
 }
 export interface SquareAtInput extends SquareLocation, OpenOptions {
-    /** A caller-owned connection; closing this Square never closes its owner. */
-    readonly resources?: SquareResourceOwner;
 }
 export interface SquareBuildInput extends SquareAtInput {
     readonly markdown: string;
@@ -167,7 +164,7 @@ export interface Participant {
     ignore(target: string, options?: ObservationOptions, control?: OperationControl): Promise<ListenerChangeResult>;
     unlisten(target: string, options?: ObservationOptions, control?: OperationControl): Promise<ListenerChangeResult>;
     listening(options?: ObservationOptions, control?: OperationControl): Promise<ListeningResult>;
-    catch(options?: CatchOptions, control?: OperationControl): Promise<CatchResult>;
+    perceive(options?: PerceiveOptions, control?: OperationControl): Promise<PerceiveResult>;
     pending(options?: PendingOptions, control?: OperationControl): Promise<PendingResult>;
     /** Local custody only: ledger-only detach/delete is observed on privileged reconciliation. */
     ack(ids: readonly ActivityId[], control?: OperationControl): Promise<AckResult>;
@@ -204,11 +201,16 @@ export interface ParticipantsResult {
     readonly observation?: ParticipantsObservation;
 }
 export interface DiscoveryOptions {
+    readonly owner?: Owner;
     readonly depth?: number;
     readonly limit?: number;
     readonly after?: string;
 }
 export interface SquareListItem {
+    readonly joined?: readonly {
+        readonly name: string;
+        readonly pending: number;
+    }[];
     readonly path: string;
     readonly lastActiveAt: number;
     readonly context: readonly string[];
@@ -272,7 +274,7 @@ export interface PresenceClassification {
     readonly lingeringCount: number;
     readonly classificationByName: Readonly<Record<string, 'here' | 'lingering' | 'away' | 'done' | 'not-joined'>>;
 }
-export interface CatchPresence {
+export interface PerceivePresence {
     readonly participants: readonly ParticipantSummary[];
     readonly now: number;
 }
@@ -306,10 +308,10 @@ export interface ExpressObservation extends SquareObservation, ExpressionObserva
     readonly participant: string;
     readonly context: ExpressContext;
 }
-export interface CatchObservation extends SquareObservation, ExpressionObservation {
+export interface PerceiveObservation extends SquareObservation, ExpressionObservation {
     readonly deliveryAvailable: boolean;
     readonly participant: string;
-    readonly presence?: CatchPresence;
+    readonly presence?: PerceivePresence;
     readonly enrichmentUnavailable?: true;
 }
 export interface HistoryContinuation {

package/dist/square-location.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { SquareError } from './neutral.js';
 export function squareLocation(input) {
-    const selected = input.path ?? (input.env ?? process.env).SQUARE_LOCATION;
+    const selected = input.path;
     if (selected === undefined || selected.trim() === '')
         throw new SquareError('invalid_args', 'Square needs a location');
     // Windows roots include drive-relative prefixes such as D:.

package/dist/square-posting.d.ts

@@ -2,12 +2,12 @@ import { DeliveryLedger, type DeliveryRoute, type DeliverySession } from './deli
 import { type Seat } from './model.js';
 import type { SquareArtifactPort } from './ports.js';
 /** Local producer custody and current host attachment are different observations. */
-export declare function deliverySessionsForSeats(ledger: DeliveryLedger, seats: readonly Seat[]): Promise<ReadonlyMap<string, DeliverySession | undefined>>;
+export declare function deliverySessionsForSeats(ledger: DeliveryLedger, seats: readonly Seat[], signal?: AbortSignal): Promise<ReadonlyMap<string, DeliverySession | undefined>>;
 /** Read-only host observations for status; callers fence them against the captured World seats. */
-export declare function readSquareSessions(seats: readonly Seat[], env: NodeJS.ProcessEnv): Promise<ReadonlyMap<string, DeliverySession | undefined>>;
+export declare function readSquareSessions(seats: readonly Seat[], env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<ReadonlyMap<string, DeliverySession | undefined>>;
 /** A first producer join may register an absent owner, never resume or revive one. */
-export declare function ensureInitialDeliverySession(owner: Seat['owner'], env: NodeJS.ProcessEnv, route?: DeliveryRoute): Promise<boolean>;
+export declare function ensureInitialDeliverySession(owner: Seat['owner'], env: NodeJS.ProcessEnv, route?: DeliveryRoute, signal?: AbortSignal): Promise<boolean>;
 /** Called only by privileged mutations. Sandbox lease/ACK/selection never enters here. */
-export declare function reconcileSquareDelivery(artifact: SquareArtifactPort, location: string, env: NodeJS.ProcessEnv, clock: () => number): Promise<void>;
+export declare function reconcileSquareDelivery(artifact: SquareArtifactPort, location: string, env: NodeJS.ProcessEnv, clock: () => number, signal?: AbortSignal): Promise<void>;
 /** One export path for Square activities and Square-owned notices. No transaction spans I/O. */
-export declare function flushSquarePosts(artifact: SquareArtifactPort, location: string, env: NodeJS.ProcessEnv, clock: () => number): Promise<void>;
+export declare function flushSquarePosts(artifact: SquareArtifactPort, location: string, env: NodeJS.ProcessEnv, clock: () => number, signal?: AbortSignal): Promise<void>;

package/dist/square-posting.js

@@ -7,8 +7,8 @@ import { coreDone } from './decisions.js';
 import { activityMetadataHasContent } from './model.js';
 import { formatActivityId } from './square-core.js';
 import { squarePostKey } from './square-post.js';
-const openLedger = (env) => DeliveryLedger.open({
-    location: deliveryLedgerLocation(env),
+const openLedger = (env, signal) => DeliveryLedger.open({
+    location: deliveryLedgerLocation(env), signal,
 });
 function renderPost(location, post) {
     if (post.kind === 'notice')
@@ -19,35 +19,35 @@ function renderPost(location, post) {
     return { text: projected.text, full: projected.isFull };
 }
 /** Local producer custody and current host attachment are different observations. */
-export async function deliverySessionsForSeats(ledger, seats) {
+export async function deliverySessionsForSeats(ledger, seats, signal) {
     const owners = [...new Set(seats.map(seat => seat.owner))];
-    return new Map(await Promise.all(owners.map(async (owner) => [owner, await ledger.session(owner)])));
+    return new Map(await Promise.all(owners.map(async (owner) => [owner, await ledger.session(owner, signal)])));
 }
 /** Read-only host observations for status; callers fence them against the captured World seats. */
-export async function readSquareSessions(seats, env) {
+export async function readSquareSessions(seats, env, signal) {
     if (!seats.length)
         return new Map();
-    const ledger = await openLedger(env);
+    const ledger = await openLedger(env, signal);
     try {
-        return await deliverySessionsForSeats(ledger, seats);
+        return await deliverySessionsForSeats(ledger, seats, signal);
     }
     finally {
         await ledger.close();
     }
 }
 /** A first producer join may register an absent owner, never resume or revive one. */
-export async function ensureInitialDeliverySession(owner, env, route) {
-    const ledger = await openLedger(env);
+export async function ensureInitialDeliverySession(owner, env, route, signal) {
+    const ledger = await openLedger(env, signal);
     try {
-        const current = await ledger.session(owner);
+        const current = await ledger.session(owner, signal);
         if (!current) {
-            return !!await ledger.attach({ owner, expectedGeneration: null, routes: route ? [route] : [] });
+            return !!await ledger.attach({ owner, expectedGeneration: null, routes: route ? [route] : [] }, signal);
         }
         if (current.state !== 'attached')
             return false;
         if (route)
-            return ledger.updateRoutes({ owner, generation: current.generation,
-                routes: [...current.routes.filter(candidate => candidate.kind !== route.kind), route] });
+            return await ledger.updateRoutes({ owner, generation: current.generation,
+                routes: [...current.routes.filter(candidate => candidate.kind !== route.kind), route] }, signal);
         return true;
     }
     finally {
@@ -55,14 +55,14 @@ export async function ensureInitialDeliverySession(owner, env, route) {
     }
 }
 /** Called only by privileged mutations. Sandbox lease/ACK/selection never enters here. */
-export async function reconcileSquareDelivery(artifact, location, env, clock) {
+export async function reconcileSquareDelivery(artifact, location, env, clock, signal) {
     const snapshot = (await artifact.read(facts => ({ seats: facts.roster().filter(person => person.joined)
-            .flatMap(person => { const seat = facts.seat(person.name); return seat ? [seat] : []; }), posts: facts.postedPosts() }))).value;
+            .flatMap(person => { const seat = facts.seat(person.name); return seat ? [seat] : []; }), posts: facts.postedPosts() }), signal)).value;
     if (!snapshot.seats.length && !snapshot.posts.length)
         return;
-    const ledger = await openLedger(env);
+    const ledger = await openLedger(env, signal);
     try {
-        const sessions = await deliverySessionsForSeats(ledger, snapshot.seats);
+        const sessions = await deliverySessionsForSeats(ledger, snapshot.seats, signal);
         for (const seat of snapshot.seats) {
             const session = sessions.get(seat.owner);
             if (!session)
@@ -72,71 +72,72 @@ export async function reconcileSquareDelivery(artifact, location, env, clock) {
                     const current = facts.seat(seat.participant);
                     if (current?.owner === seat.owner && current.generation === seat.generation && facts.participant(seat.participant)?.joined)
                         facts.land(coreDone(facts, seat.participant, '', clock()));
-                });
+                }, signal);
             }
             else if (seat.attachment !== session.state) {
                 const attachment = session.state;
-                await artifact.transactAs({ kind: 'producer' }, facts => facts.setSeatAttachment(seat, attachment));
+                await artifact.transactAs({ kind: 'producer' }, facts => facts.setSeatAttachment(seat, attachment), signal);
             }
         }
         // A full receipt is monotonic external presentation evidence, never inferred from silence.
         const receipts = new Map();
         for (const owner of new Set(snapshot.posts.map(post => post.owner))) {
             const keys = snapshot.posts.filter(post => post.owner === owner).map(post => squarePostKey(location, post));
-            receipts.set(owner, new Map((await ledger.receipts(owner, { keys })).map(receipt => [receipt.key, receipt.at])));
+            receipts.set(owner, new Map((await ledger.receipts(owner, { keys }, signal)).map(receipt => [receipt.key, receipt.at])));
         }
         for (const post of snapshot.posts) {
             const cardKey = squarePostKey(location, post);
             const receipt = receipts.get(post.owner)?.get(cardKey);
             if (receipt !== undefined && post.full === true && !post.consumed)
-                await artifact.transactAs({ kind: 'producer' }, facts => facts.foldReceipt(post, receipt));
+                await artifact.transactAs({ kind: 'producer' }, facts => facts.foldReceipt(post, receipt), signal);
         }
-        await suppressWithdrawn(artifact, ledger, location);
+        await suppressWithdrawn(artifact, ledger, location, signal);
     }
     finally {
         await ledger.close();
     }
 }
-async function suppressWithdrawn(artifact, ledger, location) {
+async function suppressWithdrawn(artifact, ledger, location, signal) {
     const posts = (await artifact.read(facts => facts.postedPosts().filter(post => {
         const seat = facts.seat(post.recipient);
         return post.consumed || !seat || seat.owner !== post.owner || seat.generation !== post.generation;
-    }))).value;
+    }), signal)).value;
     // Departure withdraws only the captured notification, never producer read history or held effects.
     for (const post of posts)
-        await ledger.suppress({ owner: post.owner, key: squarePostKey(location, post), scope: 'exact' });
+        await ledger.suppress({ owner: post.owner, key: squarePostKey(location, post), scope: 'exact' }, signal);
 }
 /** One export path for Square activities and Square-owned notices. No transaction spans I/O. */
-export async function flushSquarePosts(artifact, location, env, clock) {
+export async function flushSquarePosts(artifact, location, env, clock, signal) {
+    signal ??= AbortSignal.timeout(5000);
     // Delivery enrichment cannot turn a committed producer mutation into a retry of that mutation.
     let lifetime;
     try {
-        const snapshot = (await artifact.read(facts => ({ pending: facts.pendingPosts(), posted: facts.postedPosts() }))).value;
+        const snapshot = (await artifact.read(facts => ({ pending: facts.pendingPosts(), posted: facts.postedPosts() }), signal)).value;
         if (!snapshot.pending.length && !snapshot.posted.length)
             return;
-        const ledger = await openLedger(env);
+        const ledger = await openLedger(env, signal);
         lifetime = retainDeliveryLedger(ledger);
         for (const post of snapshot.pending) {
-            const session = await ledger.session(post.owner);
+            const session = await ledger.session(post.owner, signal);
             if (session?.state !== 'attached')
                 continue;
             const rendered = renderPost(location, post), token = randomUUID();
-            const owned = (await artifact.transactAs({ kind: 'producer' }, facts => facts.acquirePost({ ...post, full: rendered.full }, token, process.pid, clock(), Date.now()))).value;
+            const owned = (await artifact.transactAs({ kind: 'producer' }, facts => facts.acquirePost({ ...post, full: rendered.full }, token, process.pid, clock(), Date.now()), signal)).value;
             if (!owned)
                 continue;
             let posted = false, knownUnsent = true;
             try {
                 // This check is not custody across the await; the ledger independently fences delivery.
-                const current = await ledger.session(post.owner);
+                const current = await ledger.session(post.owner, signal);
                 if (current?.state !== 'attached' || current.generation !== session.generation
-                    || !(await artifact.read(facts => facts.ownsPost(token, Date.now()))).value)
+                    || !(await artifact.read(facts => facts.ownsPost(token, Date.now()), signal)).value)
                     continue;
                 knownUnsent = false;
                 const result = await ledger.post({ owner: post.owner, key: squarePostKey(location, post), text: rendered.text,
                     ...(post.kind === 'activity' ? { details: { kind: 'presentation', origin: displayAttentionPath(location),
                             ref: formatActivityId(post.index), author: post.from, body: post.body ?? '',
                             ...(post.route === 'bell' ? { badge: '🔔' } : {}) } } : {}),
-                });
+                }, signal);
                 posted = ['posted', 'duplicate', 'suppressed'].includes(result.status);
                 knownUnsent = !posted;
                 if (result.status === 'conflict')
@@ -147,20 +148,20 @@ export async function flushSquarePosts(artifact, location, env, clock) {
                 await artifact.settleAs({ kind: 'producer' }, facts => facts.settlePost(token, rendered.full, disposition));
             }
         }
-        await suppressWithdrawn(artifact, ledger, location);
+        await suppressWithdrawn(artifact, ledger, location, signal);
         const posts = (await artifact.read(facts => facts.postedPosts().filter(post => {
             const seat = facts.seat(post.recipient);
             return !post.consumed && seat?.owner === post.owner && seat.generation === post.generation;
-        }))).value;
+        }), signal)).value;
         for (const owner of new Set(posts.map(post => post.owner))) {
-            const session = await ledger.session(owner);
+            const session = await ledger.session(owner, signal);
             if (session?.state !== 'attached')
                 continue;
-            const pendingKeys = new Set((await ledger.pending(owner, { generation: session.generation })).map(card => card.key));
+            const pendingKeys = new Set((await ledger.pending(owner, { generation: session.generation }, signal)).map(card => card.key));
             for (const post of posts.filter(post => post.owner === owner)) {
                 const key = squarePostKey(location, post);
                 if (pendingKeys.has(key))
-                    await dispatchPostedCard(ledger, owner, key, lifetime.track, env);
+                    await dispatchPostedCard(ledger, owner, key, lifetime.track, env, signal);
             }
         }
     }

package/dist/square-tools.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod/v4';
 import { type Square } from './square-api.js';
-import type { Owner, WakeAddress, OperationControl } from './square-facade.js';
+import type { Owner, WakeAddress, OperationControl, DiscoveryOptions, DiscoveryResult } from './square-facade.js';
 export interface ToolIdentity {
     readonly owner?: Owner;
     readonly wakeAddress?: WakeAddress;
@@ -19,20 +19,31 @@ export declare class SquareExpressDrafts {
 interface ToolBinding {
     identity: ToolIdentity;
     open(location: string | undefined, control: OperationControl): Promise<Square>;
+    discover(options: DiscoveryOptions, control: OperationControl): Promise<{
+        result: DiscoveryResult;
+        now: number;
+    }>;
 }
-export declare function createSquareToolRunner(): (tool: ToolDefinition, args: JsonObject, control: OperationControl, bind: () => Promise<ToolBinding> | ToolBinding, defaultLocation?: string) => Promise<{
+export declare function createSquareToolRunner(): (tool: ToolDefinition, args: JsonObject, control: OperationControl, bind: () => Promise<ToolBinding> | ToolBinding) => Promise<{
     text: string;
     isError?: true;
 }>;
-interface ToolDefinition {
+interface SingleSquareToolDefinition {
     name: string;
     description: string;
     inputSchema: z.ZodObject<z.ZodRawShape>;
     /** Human text identical to what the CLI prints; domain receipts stay inside the adapter. */
     run(square: Square, args: JsonObject, control: OperationControl, identity: ToolIdentity): Promise<string>;
 }
+interface DiscoveryToolDefinition {
+    name: 'list';
+    description: string;
+    inputSchema: z.ZodObject<z.ZodRawShape>;
+    runDiscovery(args: JsonObject, control: OperationControl, binding: ToolBinding): Promise<string>;
+}
+type ToolDefinition = SingleSquareToolDefinition | DiscoveryToolDefinition;
 export declare function squareToolsEnabled(env?: NodeJS.ProcessEnv): boolean;
-export declare const SQUARE_TOOL_INSTRUCTIONS = "Join once. Then express to speak, and catch to take in what reached you. History looks back without taking anything in.";
+export declare const SQUARE_TOOL_INSTRUCTIONS = "List nearby squares and your joined names with list. Pass location for a single square. Join once. Then express to speak, and perceive to take in what reached you. History looks back without taking anything in.";
 export declare const SQUARE_TOOLS: readonly ToolDefinition[];
 export declare function squareToolFailure(error: unknown, signal?: AbortSignal): JsonObject;
 /** Readable failure text with the same recovery commands the CLI offers, never raw JSON. */

package/dist/square-tools.js

@@ -1,8 +1,8 @@
 import crypto from 'node:crypto';
 import { z } from 'zod/v4';
 import { isSquareError, SquareError } from './model.js';
-import { requireOwner, requireJoinName, selectOwnSeat, CATCH_DEFAULT_LIMIT } from './square-api.js';
-import { renderCatchOutcome, renderExpression, renderFailureLines, renderHistoryResult, renderJoinResult, renderLifecycleResult, renderListenerChange, renderStatusResult, } from './operation-presentation.js';
+import { requireOwner, requireJoinName, selectOwnSeat, PERCEIVE_DEFAULT_LIMIT, DEFAULT_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_DEPTH, MAX_LIST_LIMIT } from './square-api.js';
+import { renderPerceiveOutcome, renderExpression, renderFailureLines, renderHistoryResult, renderJoinResult, renderLifecycleResult, renderListenerChange, renderStatusResult, renderSquareList, } from './operation-presentation.js';
 /** Process-local recovery: FIFO 64, fixed two-hour TTL, consumed only by a successful express. */
 const EXPRESS_DRAFT_TTL_MS = 2 * 60 * 60 * 1000;
 const EXPRESS_DRAFT_LIMIT = 64;
@@ -33,7 +33,8 @@ export class SquareExpressDrafts {
         const effect = failure.operation?.expressEffect;
         // After an attempt, only an admission or argument refusal proves that retrying cannot duplicate an activity.
         const unsent = !expressAttempted || effect === 'unsent' || (effect === undefined && failure.code === 'invalid_args');
-        if (!unsent || effect === 'landed' || effect === 'unknown' || typeof args.body !== 'string' || args.draft !== undefined)
+        if (!unsent || effect === 'landed' || effect === 'unknown' || typeof args.body !== 'string' || args.draft !== undefined
+            || typeof args.location !== 'string' || !args.location.trim())
             return undefined;
         this.purgeExpired();
         if (token !== undefined && this.drafts.has(token))
@@ -47,7 +48,7 @@ export class SquareExpressDrafts {
 }
 export function createSquareToolRunner() {
     const drafts = new SquareExpressDrafts();
-    return async (tool, args, control, bind, defaultLocation) => {
+    return async (tool, args, control, bind) => {
         let toolArgs = args;
         let owner;
         let token;
@@ -56,6 +57,8 @@ export function createSquareToolRunner() {
         try {
             const binding = await bind();
             owner = binding.identity.owner;
+            if ('runDiscovery' in tool)
+                return { text: await tool.runDiscovery(toolArgs, control, binding) };
             if (tool.name === 'express') {
                 const resolved = drafts.resolve(toolArgs, owner);
                 toolArgs = resolved.args;
@@ -77,14 +80,15 @@ export function createSquareToolRunner() {
             const failure = squareToolFailure(error, control.signal);
             const draft = tool.name === 'express' ? drafts.retain(toolArgs, owner, token, failure, attempted) : undefined;
             return { isError: true, text: squareToolFailureText(failure, {
-                    location: square?.location ?? toolArgs.location ?? defaultLocation,
+                    location: square?.location ?? toolArgs.location,
                     participant: typeof toolArgs.as === 'string' ? toolArgs.as : undefined,
                     draft,
                 }) };
         }
     };
 }
-const location = z.string().optional().describe('Which square: a .square file path. Relative paths start from the working directory. Leave it out for the configured square.');
+const location = z.string().describe('Which square: a .square file path. Relative paths start from the working directory.');
+const expressLocation = z.string().optional().describe('Which square: a .square file path. Relative paths start from the working directory. Required unless retrying with a draft token.');
 const participant = z.string().optional().describe('Your name in the square. Leave it out if you hold exactly one name here.');
 const activityId = z.string().regex(/^act\/(0|[1-9][0-9]*)$/);
 const stringArray = z.array(z.string());
@@ -93,7 +97,7 @@ function rendering(render) {
     return (result, args) => render(result, args);
 }
 function tool(name, description, shape, run, render) {
-    const inputSchema = z.object({ ...shape, location }).strict();
+    const inputSchema = z.object({ ...shape, location: name === 'express' ? expressLocation : location }).strict();
     return { name, description, inputSchema,
         run: async (square, args, control, identity) => {
             const { location: _location, ...operationArgs } = inputSchema.parse(args);
@@ -109,7 +113,7 @@ export function squareToolsEnabled(env = process.env) {
         return false;
     throw new SquareError('invalid_args', 'Invalid SQUARE_TOOLS: expected 0, 1, true, false, or none.');
 }
-export const SQUARE_TOOL_INSTRUCTIONS = 'Join once. Then express to speak, and catch to take in what reached you. History looks back without taking anything in.';
+export const SQUARE_TOOL_INSTRUCTIONS = 'List nearby squares and your joined names with list. Pass location for a single square. Join once. Then express to speak, and perceive to take in what reached you. History looks back without taking anything in.';
 function historyToolQuery({ grep, fixed, before, after, ...query }) {
     if (grep !== undefined && fixed !== undefined)
         throw new SquareError('invalid_args', 'Use grep or fixed, not both.');
@@ -121,8 +125,22 @@ function historyToolQuery({ grep, fixed, before, after, ...query }) {
     };
 }
 const target = z.string().describe('The participant to turn toward or away from.');
+const listSchema = z.object({
+    depth: z.number().int().min(0).max(MAX_LIST_DEPTH).optional().describe('How many directory levels to explore (default 4).'),
+    limit: z.number().int().min(1).max(MAX_LIST_LIMIT).optional().describe('How many squares per page (default 20).'),
+    after: z.string().min(1).optional().describe('Continue after this relative square path.'),
+}).strict();
 export const SQUARE_TOOLS = [
-    tool('join', 'Step into the square under your name. Do this once before you speak or catch. You arrive seeing what was said most recently.', {
+    {
+        name: 'list', description: 'Find nearby squares, including your joined names and what is waiting for them. Start here to choose a location.',
+        inputSchema: listSchema,
+        async runDiscovery(args, control, binding) {
+            const options = listSchema.parse(args);
+            const { result, now } = await binding.discover({ ...options, owner: binding.identity.owner }, control);
+            return renderSquareList(result, { now, depth: options.depth ?? DEFAULT_LIST_DEPTH, limit: options.limit ?? DEFAULT_LIST_LIMIT });
+        },
+    },
+    tool('join', 'Step into the square under your name. Do this once before you speak or perceive. You arrive seeing what was said most recently.', {
         as: z.string().optional().describe('Your name in the square. Give it explicitly when joining.'), takeover: z.boolean().optional().describe('Claim this name even though another session holds it now. That session loses it.'),
     }, (square, { as, takeover }, control, identity) => square.join(requireJoinName(as), { ...identity, owner: requireOwner(identity.owner), takeover, observe: true }, control), rendering((result) => renderJoinResult(result))),
     tool('express', 'Speak or act in the square. Plain words, half-formed ideas and *actions* all belong here. Mention or reply to someone to be heard by them; ring the bell to be heard by everyone. Said to no one in particular, your words reach those who listen to you.', {
@@ -133,7 +151,7 @@ export const SQUARE_TOOLS = [
         reach: z.enum(['bell']).optional().describe('"bell" calls everyone in the square. Cannot be used with mentions.'),
         reply: activityId.optional().describe('The activity you are answering, like act/12. Its author hears you if still here.'),
         noMention: z.boolean().optional().describe('Leave @names in the body as plain text. Mentions and reply still reach people.'),
-        force: z.boolean().optional().describe('Speak now, even if something reached you that you have not caught yet.'),
+        force: z.boolean().optional().describe('Speak now, even if something reached you that you have not perceived yet.'),
         noWait: z.boolean().optional().describe('If you are speaking too fast, return at once instead of waiting.'),
     }, async (square, { body, draft, as, ...options }, control, identity) => {
         if (draft !== undefined)
@@ -142,20 +160,20 @@ export const SQUARE_TOOLS = [
             throw new SquareError('invalid_args', 'Express needs a body or a draft token.');
         return (await selectOwnSeat(square, identity.owner, as)).express(body, { ...options, observe: true }, control);
     }, rendering((result) => renderExpression(result.observation?.location ?? '', result))),
-    tool('catch', 'Take in what reached you since you last looked: mentions, replies, bells, and words from those you listen to. What you catch no longer waits for you; history lets you look back.', {
+    tool('perceive', 'Take in what reached you since you last looked: mentions, replies, bells, and words from those you listen to. What you perceive no longer waits for you; history lets you look back.', {
         as: participant,
-        id: activityId.optional().describe('Take in this activity in full, like act/12, even if you caught it before. Do not combine with idle, from, mention or limit.'),
+        id: activityId.optional().describe('Take in this activity in full, like act/12, even if you perceived it before. Do not combine with idle, from, mention or limit.'),
         idle: z.number().finite().min(0).optional().describe('When nothing is waiting, wait until something arrives or until it has been quiet this many milliseconds. Leave it out to return at once.'),
         from: stringArray.optional().describe('Only what these participants said.'),
         mention: z.boolean().optional().describe('Only what was addressed to you, and bells.'),
         limit: z.number().int().min(1).optional().describe('At most this many at once (default 10, up to 100). The rest keeps waiting.'),
-    }, async (square, { as, ...options }, control, identity) => (await selectOwnSeat(square, identity.owner, as)).catch({ ...options, observe: true }, control), rendering((result, args) => {
+    }, async (square, { as, ...options }, control, identity) => (await selectOwnSeat(square, identity.owner, as)).perceive({ ...options, observe: true }, control), rendering((result, args) => {
         // The CLI always spells the default cap in its continuation, so the tool does too.
         const options = args;
-        const renderOptions = options.id === undefined ? { ...options, limit: options.limit ?? CATCH_DEFAULT_LIMIT } : options;
-        return renderCatchOutcome(result.observation?.location ?? '', result, renderOptions).stdout;
+        const renderOptions = options.id === undefined ? { ...options, limit: options.limit ?? PERCEIVE_DEFAULT_LIMIT } : options;
+        return renderPerceiveOutcome(result.observation?.location ?? '', result, renderOptions).stdout;
     })),
-    tool('history', 'Look back at what was said. Reading here takes nothing in: whatever waits for catch keeps waiting. Page with before or after.', {
+    tool('history', 'Look back at what was said. Reading here takes nothing in: whatever waits for perceive keeps waiting. Page with before or after.', {
         limit: z.number().int().min(1).optional().describe('How many per page (default 10, up to 100).'),
         order: z.enum(['asc', 'desc']).optional().describe('"asc" for oldest first (default), "desc" for newest first.'),
         before: activityId.optional().describe('The page just before this activity, like act/12.'),
@@ -199,7 +217,7 @@ export function squareToolFailureText(failure, context = {}) {
     if (context.draft !== undefined) {
         lines.push(`· draft kept in memory: ${context.draft}`);
         lines.push(report.code === 'behind'
-            ? '· catch the pending activity, then retry express with only:'
+            ? '· perceive the pending activity, then retry express with only:'
             : '· correct the problem above, then retry express with only:', `{ "draft": "${context.draft}" }`);
     }
     return lines.join('\n');

package/dist/views.d.ts

@@ -1,7 +1,7 @@
 import { type ActivityId } from './square-core.js';
 import { type HydratedAct } from './model.js';
 import type { ActivityFilter, SquareRead } from './ports.js';
-import type { Activity, ArchiveRecord, PerceivedActivity, HistoryQuery, HistoryContinuation, ParticipantsResult, EntryPresentation, StatusResult, SquareObservation, CatchPresence } from './square-facade.js';
+import type { Activity, ArchiveRecord, PerceivedActivity, HistoryQuery, HistoryContinuation, ParticipantsResult, EntryPresentation, StatusResult, SquareObservation, PerceivePresence, Owner } from './square-facade.js';
 export declare const HISTORY_DEFAULT_LIMIT = 10;
 export declare const HISTORY_MAX_LIMIT = 100;
 export declare const NON_READ: readonly ["join", "done", "say", "listen", "ignore", "unlisten"];
@@ -27,13 +27,17 @@ export declare function recoveryObservation(facts: SquareRead, name: string, now
 export declare function entryPresentation(facts: SquareRead, name: string, lastN?: number | null): EntryPresentation;
 type ParticipantQueryContext = Pick<SquareObservation, 'location' | 'now'>;
 export declare function queryParticipants(facts: SquareRead, context: ParticipantQueryContext, observe?: boolean): ParticipantsResult;
-export declare function listPresentation(facts: SquareRead): {
+export declare function listPresentation(facts: SquareRead, owner?: Owner): {
+    joined?: {
+        name: string;
+        pending: number;
+    }[] | undefined;
     context: readonly string[];
     participants: string[];
     activities: number;
 };
 export declare function queryStatus(facts: SquareRead, context: ParticipantQueryContext, viewer?: string, observe?: boolean): StatusResult;
-export declare function catchPresence(facts: SquareRead, now: number): CatchPresence;
+export declare function perceivePresence(facts: SquareRead, now: number): PerceivePresence;
 export declare function streamProjection(facts: SquareRead, cursor: number, recipient?: string): {
     activities: Activity[];
     cursor: number;