@astrosheep/square 0.3.30 → 0.3.32

package/dist/routes.d.ts

@@ -1,10 +1,30 @@
 import { type WakeRoute, type WakeRouteKind } from './model.js';
-export { isWakeRouteKind, WAKE_ROUTE_KINDS } from './model.js';
+export { WAKE_ROUTE_KINDS } from './model.js';
 export type { WakeRoute, WakeRouteKind } from './model.js';
 export declare const ROUTE_FRESH_MS: number;
-export declare function routesPath(env?: NodeJS.ProcessEnv): string;
+export type WakeBoundaryProvider = 'codex' | 'claude' | 'opencode' | 'pi' | 'paseo';
+export interface WakeBoundary {
+    readonly location: string;
+    readonly participant: string;
+    readonly sessionId: string;
+    readonly provider: WakeBoundaryProvider;
+}
+export interface WakeRouteCapabilities {
+    readonly canUse: (kind: WakeRouteKind, address: Readonly<Record<string, string>>) => boolean;
+}
+export declare function defaultWakeRouteCapabilities(hostLedger?: import('./host-ledger.js').HostLedgerPort): Promise<WakeRouteCapabilities>;
+/** Pure, ordered route precedence. Capability predicates own adapter and scope checks. */
+export declare function selectPrimaryWakeRoute(input: {
+    readonly boundary: WakeBoundary;
+    readonly env: NodeJS.ProcessEnv;
+    readonly capabilities: WakeRouteCapabilities;
+}): Omit<WakeRoute, 'updatedAt'> | undefined;
+export declare function routeIdentityKey(route: Pick<WakeRoute, 'location' | 'participant' | 'sessionId'>, location?: string): string;
+export declare function resolvePrimaryWakeRoute(boundary: WakeBoundary, env: NodeJS.ProcessEnv, capabilities: WakeRouteCapabilities): Omit<WakeRoute, 'updatedAt'> | undefined;
 export declare function readWakeRoutes(opts?: {
-    ownerId?: string;
+    location?: string;
+    participant?: string;
+    sessionId?: string;
     freshOnly?: boolean;
     now?: number;
     env?: NodeJS.ProcessEnv;
@@ -13,35 +33,12 @@ export declare function upsertWakeRoute(route: Omit<WakeRoute, 'updatedAt'>, opt
     at?: number;
     env?: NodeJS.ProcessEnv;
 }): Promise<void>;
-export declare function retireOwnerWakeRoutes(ownerId: string, opts?: {
-    at?: number;
-    env?: NodeJS.ProcessEnv;
-}): Promise<void>;
-/** Retire one capability without touching sibling identities in the same claim. */
-export declare function retireWakeRoute(route: Pick<WakeRoute, 'ownerId' | 'sessionId' | 'kind'>, opts?: {
+export declare function publishWakeRoute(artifact: import('./ports.js').SquareArtifactPort, route: Omit<WakeRoute, 'updatedAt'>, opts?: {
     at?: number;
-    env?: NodeJS.ProcessEnv;
-}): Promise<void>;
-export interface WakeRouteEvidence {
-    sessionId: string;
-    address: Record<string, string>;
-}
-/** A provider's self-check: complete, callable endpoint evidence for one kind, or nothing. */
-export type WakeRouteProbe = (env: NodeJS.ProcessEnv) => WakeRouteEvidence | undefined;
-/**
- * One probe per kind. A probe publishes only when its provider's complete
- * endpoint evidence is present; Codex uses its thread id as that evidence.
- * The other native transports have no endpoint lifecycle in this delivery,
- * so their probes publish nothing until those transports land.
- */
-export declare const WAKE_ROUTE_PROBES: Readonly<Record<WakeRouteKind, WakeRouteProbe>>;
-/** The kind-neutral publication loop; probes supply complete evidence per kind. */
-export declare function publishWakeRoutesFrom(ownerId: string, probes: Readonly<Record<WakeRouteKind, WakeRouteProbe>>, opts?: {
-    at?: number;
-    env?: NodeJS.ProcessEnv;
 }): Promise<void>;
-/** Publication boundary: every route written is complete provider evidence. */
-export declare function publishWakeRoutes(ownerId: string, opts?: {
+export declare function retireWakeRoute(route: WakeRoute, opts?: {
     at?: number;
     env?: NodeJS.ProcessEnv;
 }): Promise<void>;
+export declare function retireWakeRouteFromArtifact(artifact: import('./ports.js').SquareArtifactPort, route: Pick<WakeRoute, 'location' | 'participant' | 'sessionId'>): Promise<void>;
+export declare function canonicalRouteLocation(location: string): Promise<string>;

package/dist/routes.js

@@ -1,173 +1,110 @@
-import { promises as fs } from 'node:fs';
-import os from 'node:os';
+import fs from 'node:fs';
 import path from 'node:path';
-import { WAKE_ROUTE_KINDS, isWakeRouteKind } from './model.js';
-export { isWakeRouteKind, WAKE_ROUTE_KINDS } from './model.js';
-const RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+import { nameKey } from './model.js';
+import { openSquare } from './square-file-adapter.js';
+import { closeOpenSquare } from './open-square.js';
+export { WAKE_ROUTE_KINDS } from './model.js';
 export const ROUTE_FRESH_MS = 24 * 60 * 60 * 1000;
-/**
- * Dispatch priority doubles as the kind declaration order: native kinds
- * precede paseo. Within one kind, the freshest route wins.
- */
-const ROUTE_KIND_PRIORITY = new Map(WAKE_ROUTE_KINDS.map((kind, index) => [kind, index]));
-export function routesPath(env = process.env) {
-    return env.SQUARE_ROUTES || path.join(os.homedir(), '.square', 'routes.ndjsonl');
+export async function defaultWakeRouteCapabilities(hostLedger) {
+    let userCapable = hostLedger !== undefined;
+    if (hostLedger !== undefined) {
+        try {
+            await hostLedger.listPresence({ scopes: ['user'], now: Date.now() });
+        }
+        catch {
+            userCapable = false;
+        }
+    }
+    const available = new Set();
+    try {
+        const { CodexQueueAdapter } = await import('./codex-queue.js');
+        available.add(new CodexQueueAdapter().kind);
+    }
+    catch { /* optional */ }
+    try {
+        const { PaseoAdapter } = await import('./paseo-delivery.js');
+        available.add(new PaseoAdapter().kind);
+    }
+    catch { /* optional */ }
+    return { canUse: (kind, address) => userCapable && available.has(kind) && Object.values(address).every((value) => value.trim() !== '') };
+}
+function nativeCandidate(boundary) {
+    if (boundary.provider === 'codex')
+        return { kind: 'codex-queue', address: { threadId: boundary.sessionId } };
+    if (boundary.provider === 'claude')
+        return { kind: 'claude-native', address: { sessionId: boundary.sessionId } };
+    if (boundary.provider === 'opencode')
+        return { kind: 'opencode-server', address: { sessionId: boundary.sessionId } };
+    if (boundary.provider === 'pi')
+        return { kind: 'pi-extension', address: { sessionId: boundary.sessionId } };
+    return undefined;
 }
-function routeKey(ownerId, kind) {
-    return `${ownerId}\0${kind}`;
+/** Pure, ordered route precedence. Capability predicates own adapter and scope checks. */
+export function selectPrimaryWakeRoute(input) {
+    const { boundary, env, capabilities } = input;
+    const paseoAgentId = env.PASEO_AGENT_ID?.trim();
+    const candidates = [];
+    if (paseoAgentId)
+        candidates.push({ kind: 'paseo', address: { agentId: paseoAgentId } });
+    const native = nativeCandidate(boundary);
+    if (native)
+        candidates.push(native);
+    const chosen = candidates.find((candidate) => Object.values(candidate.address).every((value) => value.trim() !== '') && capabilities.canUse(candidate.kind, candidate.address));
+    return chosen === undefined ? undefined : { location: boundary.location, participant: boundary.participant, sessionId: boundary.sessionId, channel: boundary.provider === 'paseo' ? 'paseo' : boundary.provider === 'claude' ? 'claude-code' : boundary.provider, ...chosen };
 }
-function stringRecord(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value) &&
-        Object.values(value).every((item) => typeof item === 'string');
+export function routeIdentityKey(route, location = route.location) {
+    return JSON.stringify([location, nameKey(route.participant), route.sessionId]);
 }
-function parseRow(raw, now) {
-    let value;
+export function resolvePrimaryWakeRoute(boundary, env, capabilities) {
+    return selectPrimaryWakeRoute({ boundary, env, capabilities });
+}
+async function withArtifact(location, fn) {
+    if (location === undefined)
+        return undefined;
     try {
-        value = JSON.parse(raw);
+        await fs.promises.access(location);
+        const square = await openSquare(location);
+        try {
+            return await fn(square);
+        }
+        finally {
+            await closeOpenSquare(square);
+        }
     }
     catch {
         return undefined;
     }
-    if (value === null || typeof value !== 'object')
-        return undefined;
-    const row = value;
-    if (row.v !== 1 ||
-        (row.op !== 'upsert' && row.op !== 'retire') ||
-        typeof row.ts !== 'number' || !Number.isFinite(row.ts) || row.ts > now || now - row.ts > RETENTION_MS ||
-        typeof row.owner_id !== 'string' || row.owner_id === '' ||
-        typeof row.session_id !== 'string' || row.session_id === '' ||
-        !isWakeRouteKind(row.kind))
-        return undefined;
-    if (row.op === 'upsert' && !stringRecord(row.address))
-        return undefined;
-    return row;
-}
-async function readRows(env, now) {
-    let raw;
-    try {
-        raw = await fs.readFile(routesPath(env), 'utf8');
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return [];
-        throw error;
-    }
-    return raw.split('\n').filter(Boolean).map((line) => parseRow(line, now)).filter((row) => row !== undefined);
 }
 export async function readWakeRoutes(opts = {}) {
     const now = opts.now ?? Date.now();
-    const state = new Map();
-    for (const row of await readRows(opts.env ?? process.env, now)) {
-        const key = routeKey(row.owner_id, row.kind);
-        const current = state.get(key);
-        if (current === undefined || row.ts >= current.ts)
-            state.set(key, row);
-    }
-    return [...state.values()]
-        .filter((row) => row.op === 'upsert')
-        .map((row) => ({
-        ownerId: row.owner_id,
-        sessionId: row.session_id,
-        kind: row.kind,
-        address: row.address,
-        updatedAt: row.ts,
-    }))
-        .filter((route) => opts.ownerId === undefined || route.ownerId === opts.ownerId)
-        .filter((route) => opts.freshOnly !== true || now - route.updatedAt < ROUTE_FRESH_MS)
-        .sort((a, b) => (ROUTE_KIND_PRIORITY.get(a.kind) ?? 0) - (ROUTE_KIND_PRIORITY.get(b.kind) ?? 0) ||
-        b.updatedAt - a.updatedAt);
-}
-async function appendRouteRow(row, env) {
-    const file = routesPath(env);
-    await fs.mkdir(path.dirname(file), { recursive: true });
-    await fs.appendFile(file, `${JSON.stringify(row)}\n`, { mode: 0o600 });
+    const canonicalLocation = opts.location === undefined ? undefined : await canonicalRouteLocation(opts.location);
+    const routes = await withArtifact(canonicalLocation, async (square) => (await square.artifact.read()).state.routes ?? []) ?? [];
+    const filtered = routes.filter((route) => (opts.participant === undefined || nameKey(route.participant) === nameKey(opts.participant)) && (opts.sessionId === undefined || route.sessionId === opts.sessionId) && (!opts.freshOnly || now - route.updatedAt < ROUTE_FRESH_MS));
+    const canonicalized = await Promise.all(filtered.map(async (route) => ({ ...route, location: await canonicalRouteLocation(route.location), address: { ...route.address } })));
+    return canonicalLocation === undefined ? canonicalized : canonicalized.filter((route) => route.location === canonicalLocation);
 }
 export async function upsertWakeRoute(route, opts = {}) {
-    const at = opts.at ?? Date.now();
-    await appendRouteRow({
-        v: 1,
-        ts: at,
-        op: 'upsert',
-        owner_id: route.ownerId,
-        session_id: route.sessionId,
-        kind: route.kind,
-        address: route.address,
-    }, opts.env ?? process.env);
+    const location = await canonicalRouteLocation(route.location);
+    await withArtifact(location, async (square) => publishWakeRoute(square.artifact, { ...route, location }, opts));
 }
-export async function retireOwnerWakeRoutes(ownerId, opts = {}) {
-    const at = opts.at ?? Date.now();
-    const env = opts.env ?? process.env;
-    for (const route of await readWakeRoutes({ ownerId, now: at, env })) {
-        await appendRouteRow({
-            v: 1,
-            ts: at,
-            op: 'retire',
-            owner_id: ownerId,
-            session_id: route.sessionId,
-            kind: route.kind,
-        }, env);
-    }
+export async function publishWakeRoute(artifact, route, opts = {}) {
+    const location = await canonicalRouteLocation(route.location);
+    await artifact.transact((state) => ({ state: { ...state, routes: [...(state.routes ?? []).filter((item) => routeIdentityKey(item) !== routeIdentityKey({ ...route, location })), { ...route, location, participant: route.participant, updatedAt: opts.at ?? Date.now() }] }, result: undefined }));
 }
-/** Retire one capability without touching sibling identities in the same claim. */
 export async function retireWakeRoute(route, opts = {}) {
-    const at = opts.at ?? Date.now();
-    const env = opts.env ?? process.env;
-    const current = (await readWakeRoutes({ ownerId: route.ownerId, now: at, env }))
-        .find((candidate) => candidate.sessionId === route.sessionId && candidate.kind === route.kind);
-    if (current === undefined)
-        return;
-    await appendRouteRow({
-        v: 1,
-        ts: at,
-        op: 'retire',
-        owner_id: route.ownerId,
-        session_id: route.sessionId,
-        kind: route.kind,
-    }, env);
+    const location = await canonicalRouteLocation(route.location);
+    await withArtifact(location, async (square) => retireWakeRouteFromArtifact(square.artifact, { ...route, location }));
 }
-/** Publication requires a non-blank session and a non-empty address of non-blank values. */
-function completeRouteEvidence(value) {
-    if (value === undefined || value === null)
-        return false;
-    if (typeof value.sessionId !== 'string' || value.sessionId.trim() === '')
-        return false;
-    const address = value.address;
-    if (address === null || typeof address !== 'object' || Array.isArray(address))
-        return false;
-    const entries = Object.entries(address);
-    return entries.length > 0 && entries.every(([key, item]) => key.trim() !== '' && typeof item === 'string' && item.trim() !== '');
+export async function retireWakeRouteFromArtifact(artifact, route) {
+    const location = await canonicalRouteLocation(route.location);
+    await artifact.transact((state) => ({ state: { ...state, routes: (state.routes ?? []).filter((item) => routeIdentityKey(item) !== routeIdentityKey({ ...route, location })) }, result: undefined }));
 }
-/**
- * One probe per kind. A probe publishes only when its provider's complete
- * endpoint evidence is present; Codex uses its thread id as that evidence.
- * The other native transports have no endpoint lifecycle in this delivery,
- * so their probes publish nothing until those transports land.
- */
-export const WAKE_ROUTE_PROBES = {
-    'opencode-server': () => undefined,
-    'codex-queue': (env) => {
-        const threadId = env.CODEX_THREAD_ID?.trim();
-        return threadId ? { sessionId: threadId, address: { threadId } } : undefined;
-    },
-    'claude-native': () => undefined,
-    'pi-extension': () => undefined,
-    paseo: (env) => {
-        const agentId = env.PASEO_AGENT_ID?.trim();
-        return agentId ? { sessionId: agentId, address: { agentId } } : undefined;
-    },
-};
-/** The kind-neutral publication loop; probes supply complete evidence per kind. */
-export async function publishWakeRoutesFrom(ownerId, probes, opts = {}) {
-    const at = opts.at ?? Date.now();
-    const env = opts.env ?? process.env;
-    for (const kind of WAKE_ROUTE_KINDS) {
-        const evidence = probes[kind](env);
-        if (!completeRouteEvidence(evidence))
-            continue;
-        await upsertWakeRoute({ ownerId, sessionId: evidence.sessionId, kind, address: evidence.address }, { at, env });
+export async function canonicalRouteLocation(location) {
+    const absolute = path.resolve(location);
+    try {
+        return await fs.promises.realpath(absolute);
+    }
+    catch {
+        return absolute;
     }
-}
-/** Publication boundary: every route written is complete provider evidence. */
-export async function publishWakeRoutes(ownerId, opts = {}) {
-    await publishWakeRoutesFrom(ownerId, WAKE_ROUTE_PROBES, opts);
 }

package/dist/runtime.d.ts

@@ -35,7 +35,7 @@ export declare function publicActs(acts: StoredAct[]): Array<Extract<StoredAct,
     kind: 'say' | 'done';
 }>>;
 export declare function observationFor(squareState: SquareState, name: string, index: number): ActivityObservation | undefined;
-export declare function recordObservation(squareState: SquareState, name: string, index: number, state: ObservationState, at?: number, ownerId?: string): boolean;
+export declare function recordObservation(squareState: SquareState, name: string, index: number, state: ObservationState, at?: number): boolean;
 export declare function readCursor(squareState: SquareState, name: string, landed?: LandedAudienceReplay): number;
 export declare function latestActIndex(acts: StoredAct[]): number;
 export declare function freshWatchLease(squareState: SquareState, name: string, at?: number): WatchLease | undefined;

package/dist/runtime.js

@@ -146,18 +146,17 @@ function canonicalRuntimeName(squareState, name) {
 export function observationFor(squareState, name, index) {
     return observationMap(squareState, name)[formatActivityId(index)];
 }
-export function recordObservation(squareState, name, index, state, at = Date.now(), ownerId) {
+export function recordObservation(squareState, name, index, state, at = Date.now()) {
     if (!Number.isSafeInteger(index) || index < 0 || !Number.isFinite(at))
         return false;
     const key = observationRecipient(squareState, name);
     const id = formatActivityId(index);
     const current = squareState.runtime.observations[key]?.[id];
-    if (current?.state === 'seen' || (current?.state === state && current.at >= at && current.ownerId === ownerId))
+    if (current?.state === 'seen' || (current?.state === state && current.at >= at))
         return false;
     const next = {
-        state: state === 'seen' ? 'seen' : 'notified',
+        state: 'seen',
         at: Math.max(current?.at ?? -Infinity, at),
-        ...(ownerId === undefined ? (current?.ownerId === undefined ? {} : { ownerId: current.ownerId }) : { ownerId }),
     };
     ((squareState.runtime.observations ??= {})[key] ??= {})[id] = next;
     return true;

package/dist/square-actions.d.ts

@@ -0,0 +1,33 @@
+import { type SquareState } from './model.js';
+import type { HostLedgerPort, SquareArtifactPort } from './ports.js';
+import type { Activity, ExpressOptions, ExpressResult } from './square-facade.js';
+import { type CatchProjection } from './catch-decisions.js';
+import type { CatchOptions, CatchResult } from './square-facade.js';
+export interface OperationContext {
+    readonly artifact: SquareArtifactPort;
+    readonly clock: () => number;
+    readonly location?: string;
+    readonly hostLedger?: HostLedgerPort;
+    readonly wakeTransport?: import('./ports.js').WakeTransportPort;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export declare function catchUp(square: OperationContext, name: string, options?: CatchOptions, project?: (state: SquareState) => CatchProjection): Promise<CatchResult>;
+export declare function join(square: OperationContext, name: string): Promise<{
+    readonly name: string;
+    readonly activity: Activity | null;
+}>;
+export declare function implicitJoin(square: OperationContext, name: string): Promise<{
+    readonly name: string;
+    readonly state: 'joined' | 'active' | 'done';
+    readonly activity: Activity | null;
+}>;
+export declare function express(square: OperationContext, name: string, body: string, options?: ExpressOptions): Promise<ExpressResult>;
+export interface ListenerChangeResult {
+    readonly activity: Activity | null;
+}
+export declare function listen(square: OperationContext, actor: string, target: string): Promise<ListenerChangeResult>;
+export declare function ignore(square: OperationContext, actor: string, target: string): Promise<ListenerChangeResult>;
+export declare function listening(square: OperationContext, actor: string): Promise<readonly string[]>;
+export declare function done(square: OperationContext, name: string, body?: string): Promise<ExpressResult>;
+export declare function hold(square: OperationContext, name: string, reason?: string): Promise<ExpressResult>;
+export declare function resume(square: OperationContext, name: string): Promise<ExpressResult>;

package/dist/square-actions.js

@@ -0,0 +1,204 @@
+import { extractMentions, formatActivityId, parseActivityId } from './square-core.js';
+import { coreDone, coreHold, coreIgnore, coreListen, coreListening, coreResume, decideAct, decideImplicitJoin, decideJoin } from './decisions.js';
+import { SquareError } from './model.js';
+import { participantIdentity } from './participant-identity.js';
+import { deliverPending } from './delivery-operations.js';
+import { decideCatch } from './catch-decisions.js';
+import { publishWakeRoute, retireWakeRouteFromArtifact, resolvePrimaryWakeRoute, defaultWakeRouteCapabilities } from './routes.js';
+function processIdentity(env) {
+    const choices = [
+        [env.CLAUDE_CODE_SESSION_ID, 'claude-code'], [env.CODEX_THREAD_ID, 'codex'],
+        [env.OPENCODE_SESSION_ID, 'opencode'], [env.SQUARE_PI_SESSION_ID, 'pi'], [env.PASEO_AGENT_ID, 'paseo'],
+    ];
+    const found = choices.find(([session]) => session?.trim());
+    return found === undefined ? { session: `process:${process.pid}`, channel: 'unknown' } : { session: found[0].trim(), channel: found[1] };
+}
+async function publishIdentityRoute(context, participant) {
+    if (context.location === undefined || context.location === 'memory')
+        return;
+    const identity = processIdentity(context.env ?? process.env);
+    if (context.hostLedger === undefined)
+        return;
+    const provider = identity.channel === 'claude-code' ? 'claude' : identity.channel === 'opencode' ? 'opencode' : identity.channel === 'pi' ? 'pi' : identity.channel === 'paseo' ? 'paseo' : 'codex';
+    const capabilities = await defaultWakeRouteCapabilities(context.hostLedger);
+    const route = await resolvePrimaryWakeRoute({ location: context.location, participant, sessionId: identity.session, provider }, context.env ?? process.env, capabilities);
+    if (route === undefined)
+        return;
+    await publishWakeRoute(context.artifact, route, { at: context.clock() }).catch(() => undefined);
+}
+async function retireIdentityRoute(context, participant) {
+    if (context.location === undefined || context.location === 'memory')
+        return;
+    const identity = processIdentity(context.env ?? process.env);
+    await retireWakeRouteFromArtifact(context.artifact, { location: context.location, participant, sessionId: identity.session }).catch(() => undefined);
+}
+/** Presence is best effort and runs only after the artifact mutation commits. */
+async function ensureLocalPresence(context, participant) {
+    if (context.hostLedger === undefined || context.location === undefined || context.location === 'memory')
+        return;
+    const identity = processIdentity(context.env ?? process.env);
+    const result = await context.hostLedger.ensurePresence({
+        location: context.location, participant, session: identity.session, channel: identity.channel, updatedAt: context.clock(),
+    }, 'local').catch((error) => ({ status: 'degraded', record: { location: context.location, participant, session: identity.session, channel: identity.channel }, error }));
+    if (result.status === 'degraded')
+        process.stderr.write(`! host presence degraded: ${result.error instanceof Error ? result.error.message : String(result.error)}\n`);
+}
+function exposeCaught(activity, perception) {
+    if (activity.kind === 'read' || activity.actor === undefined)
+        throw new Error(`Cannot expose stored activity ${formatActivityId(activity.index)}`);
+    const result = {
+        id: formatActivityId(activity.index), at: activity.at, kind: activity.kind, actor: activity.actor,
+        mentions: activity.kind === 'say' ? extractMentions(activity.body) : [],
+        ...('body' in activity && activity.body !== undefined ? { body: activity.body } : {}),
+        ...('target' in activity ? { target: activity.target } : {}),
+        ...(activity.kind === 'say' && activity.reply !== undefined ? { reply: formatActivityId(activity.reply) } : {}),
+    };
+    if (perception === 'full' || !('body' in result))
+        return { ...result, perception };
+    const { body: _body, ...withoutBody } = result;
+    return { ...withoutBody, perception };
+}
+export async function catchUp(square, name, options = {}, project) {
+    const idle = options.idle ?? 0;
+    if (!Number.isFinite(idle) || idle < 0)
+        throw new SquareError('invalid_args', 'Catch idle duration must be a non-negative number');
+    const deadline = Date.now() + idle;
+    while (true) {
+        const attempt = await square.artifact.transact((state, version) => {
+            const decision = decideCatch(state, name, options, square.clock(), project);
+            return { ...(decision.changed ? { state } : {}), result: { version, decision } };
+        });
+        await ensureLocalPresence(square, name);
+        await publishIdentityRoute(square, name);
+        if (attempt.decision.delivered.length > 0 || idle === 0) {
+            return {
+                activities: attempt.decision.delivered.map((activity) => exposeCaught(activity, attempt.decision.perceptions.get(activity.index) ?? 'full')),
+                consumedThrough: attempt.decision.consumedThrough,
+                idleExpired: false,
+            };
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0 || !await square.artifact.changed(attempt.version, remaining)) {
+            return { activities: [], consumedThrough: attempt.decision.consumedThrough, idleExpired: true };
+        }
+    }
+}
+function storeActs(state, acts) {
+    const stored = [];
+    for (const act of acts) {
+        const item = { ...act, index: state.runtime.nextActIndex };
+        state.runtime.nextActIndex += 1;
+        state.acts.push(item);
+        stored.push(item);
+    }
+    return stored;
+}
+function committedActivity(stored, verb) {
+    const activity = stored[0];
+    if (activity === undefined)
+        throw new Error(`${verb} activity did not commit`);
+    return activity;
+}
+function exposeActivity(stored) {
+    if (stored.kind === 'read' || stored.actor === undefined)
+        throw new Error(`Cannot expose stored activity ${formatActivityId(stored.index)}`);
+    return {
+        id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor,
+        ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}),
+        mentions: stored.kind === 'say' ? extractMentions(stored.body) : [],
+        ...('target' in stored ? { target: stored.target } : {}),
+        ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}),
+    };
+}
+function parseRequiredActivityId(id) {
+    const index = parseActivityId(id);
+    if (index === undefined)
+        throw new SquareError('invalid_args', `Invalid activity id: ${id}`);
+    return index;
+}
+export async function join(square, name) {
+    const now = square.clock();
+    const committed = await square.artifact.transact((state) => {
+        const decision = decideJoin(state, name, now);
+        if (decision.joinAct === undefined)
+            return { result: { name: decision.joinedName, stored: null } };
+        return { state, result: { name: decision.joinedName, stored: committedActivity(storeActs(state, [decision.joinAct]), 'join') } };
+    });
+    await ensureLocalPresence(square, committed.name);
+    await publishIdentityRoute(square, committed.name);
+    return { name: committed.name, activity: committed.stored === null ? null : exposeActivity(committed.stored) };
+}
+export async function implicitJoin(square, name) {
+    const now = square.clock();
+    const committed = await square.artifact.transact((state) => {
+        const decision = decideImplicitJoin(state, name, now);
+        if (decision.joinAct === undefined)
+            return { result: { name: decision.joinedName, state: decision.state, stored: null } };
+        return { state, result: { name: decision.joinedName, state: decision.state, stored: committedActivity(storeActs(state, [decision.joinAct]), 'join') } };
+    });
+    await ensureLocalPresence(square, committed.name);
+    if (committed.state === 'done')
+        await retireIdentityRoute(square, committed.name);
+    else
+        await publishIdentityRoute(square, committed.name);
+    return { name: committed.name, state: committed.state, activity: committed.stored === null ? null : exposeActivity(committed.stored) };
+}
+export async function express(square, name, body, options = {}) {
+    const now = square.clock();
+    const reply = options.reply === undefined ? undefined : parseRequiredActivityId(options.reply);
+    const committed = await square.artifact.transact((state) => {
+        const decision = decideAct(state, { name, body, force: options.force ?? false, now, ...(options.reach === undefined ? {} : { reach: options.reach }), ...(reply === undefined ? {} : { reply }) });
+        if (decision.type === 'blocked') {
+            const pending = decision.activitySummaries.reduce((count, summary) => count + summary.count, 0) + decision.unreadRoomChanges.length;
+            throw new SquareError('behind', `${participantIdentity(name)} has pending activity`, { pending });
+        }
+        if (decision.type === 'held') {
+            const holder = state.acts.filter((activity) => activity.kind === 'hold').at(-1)?.actor;
+            throw new SquareError('held', 'The square is held', holder === undefined ? undefined : { holder });
+        }
+        if (decision.type === 'capped')
+            throw new SquareError('capped', `${participantIdentity(name)} reached the activity cap`);
+        if (decision.type === 'throttled')
+            throw new SquareError('throttled', `${name} is throttled`, { retryAfterMs: decision.delayMs });
+        if (decision.type === 'bell_quota')
+            throw new SquareError('bell_quota', `${participantIdentity(name)} cannot ring the bell yet`, { retryAfterMs: Math.max(1, decision.nextAt - now) });
+        const stored = committedActivity(storeActs(state, [decision.act]), 'express');
+        return { state, result: { stored } };
+    });
+    await ensureLocalPresence(square, name);
+    await publishIdentityRoute(square, name);
+    let delivery;
+    if (square.wakeTransport !== undefined && square.hostLedger !== undefined && square.location !== undefined && square.location !== 'memory') {
+        delivery = await deliverPending({ artifact: square.artifact, hostLedger: square.hostLedger, transport: square.wakeTransport, location: square.location, activity: committed.stored.index, now }).catch(() => ({ attempted: 0, accepted: 0, failed: 0, unknown: 0, notCapable: 1 }));
+    }
+    else {
+        delivery = { attempted: 0, accepted: 0, failed: 0, unknown: 0, notCapable: 1 };
+    }
+    return { activity: exposeActivity(committed.stored), delivery };
+}
+async function landListenerChange(square, verb, actor, target) {
+    const now = square.clock();
+    const stored = await square.artifact.transact((state) => {
+        const act = verb === 'listen' ? coreListen(state, actor, target, now) : coreIgnore(state, actor, target, now);
+        if (act === undefined)
+            return { result: null };
+        return { state, result: committedActivity(storeActs(state, [act]), verb) };
+    });
+    return { activity: stored === null ? null : exposeActivity(stored) };
+}
+export function listen(square, actor, target) { return landListenerChange(square, 'listen', actor, target); }
+export function ignore(square, actor, target) { return landListenerChange(square, 'ignore', actor, target); }
+export async function listening(square, actor) { const { state } = await square.artifact.read(); return coreListening(state, actor); }
+async function landCore(square, verb, actor, body = '') {
+    const now = square.clock();
+    const stored = await square.artifact.transact((state) => {
+        const act = verb === 'done' ? coreDone(state, actor, body, now) : verb === 'hold' ? coreHold(state, actor, body, now) : coreResume(state, actor, now);
+        return { state, result: committedActivity(storeActs(state, [act]), verb) };
+    });
+    if (verb === 'done')
+        await retireIdentityRoute(square, actor);
+    return { activity: exposeActivity(stored) };
+}
+export function done(square, name, body = '') { return landCore(square, 'done', name, body); }
+export function hold(square, name, reason = '') { return landCore(square, 'hold', name, reason); }
+export function resume(square, name) { return landCore(square, 'resume', name); }