@astrosheep/square 0.3.78 → 0.3.80

package/dist/square-facade.d.ts

@@ -1,10 +1,8 @@
 import type { ActivityId, Perception, Reach } from './square-core.js';
 import type { StoredAct } from './model.js';
 import type { HostLedgerPort, WakeTransportPort, DeliveryResult, SquareResourceOwner } from './ports.js';
-import type { DiagnoseResult } from './artifact.js';
-import type { MigrationOutcome } from './square-migration.js';
 export type { ActivityId, Perception, Reach } from './square-core.js';
-/** The existing indexed domain event, including read and historical actorless lifecycle records. */
+/** Indexed archive event, including read and historical actorless lifecycle records. */
 export type ArchiveRecord = Readonly<StoredAct>;
 export interface Activity {
     readonly id: ActivityId;
@@ -20,35 +18,56 @@ export interface Activity {
 export interface PerceivedActivity extends Activity {
     readonly perception: Perception;
 }
-export interface ExpressOptions {
+/** Request extra facts for rendering, without changing operation semantics. */
+export interface ObservationOptions {
+    readonly observe?: boolean;
+}
+export interface ExpressOptions extends ObservationOptions {
     readonly force?: boolean;
     readonly mentions?: readonly string[];
     readonly reach?: Reach;
     readonly reply?: ActivityId;
     readonly noMention?: boolean;
+    readonly noWait?: boolean;
 }
-export interface ExpressResult {
+export interface ActivityResult {
     readonly activity: Activity;
     readonly delivery?: DeliveryResult;
+}
+export interface ExpressResult extends ActivityResult {
+    readonly waited: boolean;
     /** The replied-to author was not standing when the reply landed. */
     readonly replyAuthorNotHere?: string;
+    /** Body @name tokens with no standing match at landing; never stored on the activity. */
+    readonly unmatchedMentions?: readonly string[];
+    readonly observation?: ExpressObservation;
 }
-export interface ListenerChangeData {
+export interface ListenerChangeResult {
     readonly activity: Activity | null;
+    readonly observation?: ListenerObservation;
 }
-export type ListenerChangeResult = ListenerChangeData;
-export interface CatchOptions {
+export interface ListeningResult {
+    readonly listening: readonly string[];
+    readonly observation?: SquareObservation;
+}
+export interface LifecycleResult extends ActivityResult {
+    readonly observation?: LifecycleObservation;
+}
+export interface CatchOptions extends ObservationOptions {
     readonly id?: ActivityId;
     readonly idle?: number;
     readonly from?: readonly string[];
     readonly mention?: boolean;
     readonly limit?: number;
+    readonly replace?: boolean;
 }
 export interface CatchResult {
     readonly activities: readonly PerceivedActivity[];
     readonly consumedThrough: ActivityId | null;
     readonly idleExpired: boolean;
     readonly remaining: number;
+    readonly status?: CatchTerminalStatus;
+    readonly observation?: CatchObservation;
 }
 export interface CatchWaitStart {
     readonly idleMs: number;
@@ -69,8 +88,23 @@ export interface OperationControl {
     readonly signal?: AbortSignal;
     readonly onProgress?: (progress: OperationProgress) => void;
 }
-export interface HistoryQuery {
-    readonly limit?: number;
+export interface OperationFailureDetail {
+    readonly operation: 'express' | 'join' | 'catch' | 'history' | 'other';
+    readonly subject?: 'caller' | 'filter' | 'recipient';
+    readonly participant?: string;
+    readonly expressEffect?: 'unsent' | 'landed' | 'unknown';
+    readonly landedId?: ActivityId;
+    readonly historyBounds?: {
+        readonly maxLimit: number;
+        readonly totalMatches: number;
+    };
+}
+export interface OperationError extends Error {
+    readonly operation?: OperationFailureDetail;
+}
+export interface HistoryQuery extends ObservationOptions {
+    /** Ten by default; null explicitly reads the full archive. */
+    readonly limit?: number | null;
     readonly order?: 'asc' | 'desc';
     readonly before?: ActivityId;
     readonly after?: ActivityId;
@@ -78,6 +112,14 @@ export interface HistoryQuery {
     readonly fixed?: string;
     readonly from?: readonly string[];
     readonly mention?: string;
+    readonly since?: number;
+    readonly at?: readonly ActivityId[];
+    readonly contextBefore?: number;
+    readonly contextAfter?: number;
+}
+export interface HistoryResult {
+    readonly activities: readonly Activity[];
+    readonly observation?: HistoryObservation;
 }
 export interface ParticipantStatus {
     readonly name: string;
@@ -98,132 +140,61 @@ export interface SquareSnapshot {
     readonly participants: readonly ParticipantStatus[];
     delivered(name: string, id: ActivityId): boolean;
 }
-export type SquareSource = {
-    path: string;
-};
 export interface OpenOptions {
-    clock?: () => number;
-    hostLedger?: HostLedgerPort;
-    wakeTransport?: WakeTransportPort;
-    env?: NodeJS.ProcessEnv;
-}
-export interface SquareAtInput extends SquareSource, OpenOptions {
-}
-export interface SquareBuildInput extends SquareSource, OpenOptions {
-    markdown: string;
-    hardCap?: number | null;
-    throttlePerMinute?: number;
-}
-/** Optional fence for owner-scoped lifecycle actions. */
-export interface OwnershipFenceOptions {
-    readonly expectedEpoch?: number;
+    readonly clock?: () => number;
+    readonly hostLedger?: HostLedgerPort;
+    readonly wakeTransport?: WakeTransportPort;
+    readonly env?: NodeJS.ProcessEnv;
 }
-export interface Participant {
-    readonly name: string;
-    express(body: string, options?: ExpressOptions, control?: OperationControl): Promise<ExpressResult>;
-    listen(target: string, control?: OperationControl): Promise<ListenerChangeResult>;
-    ignore(target: string, control?: OperationControl): Promise<ListenerChangeResult>;
-    listening(control?: OperationControl): Promise<readonly string[]>;
-    catch(options?: CatchOptions, control?: OperationControl): Promise<CatchResult>;
-    history(query?: HistoryQuery, control?: OperationControl): Promise<Activity[]>;
-    hold(reason?: string, control?: OperationControl): Promise<ExpressResult>;
-    resume(control?: OperationControl): Promise<ExpressResult>;
-    /** Leave without a message. Only an omitted or empty body is accepted. */
-    done(body?: string, control?: OperationControl): Promise<ExpressResult>;
+export interface SquareLocation {
+    readonly path?: string;
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
 }
-export interface SquareApplicationContext extends Readonly<OpenOptions> {
-    readonly cwd: string;
-    readonly env: NodeJS.ProcessEnv;
-    readonly squarePath?: string;
+export interface SquareAtInput extends SquareLocation, OpenOptions {
     readonly participant?: string;
-    /** Borrow the owner's connection for the configured square. The caller owns its lifetime;
-     *  without an owner, each operation opens and closes its own connection. */
+    /** A caller-owned connection; closing this Square never closes its owner. */
     readonly resources?: SquareResourceOwner;
 }
-/** Data-only callers do not request or pay for presentation work. */
-export interface ApplicationOutcome<Data, Projection, Presentation extends boolean = true> {
-    readonly data: Data;
-    readonly projection: Presentation extends true ? Projection : undefined;
-}
-export interface ApplicationFailureDetail {
-    readonly operation: 'express' | 'join' | 'catch' | 'history' | 'other';
-    readonly subject?: 'caller' | 'filter' | 'recipient';
-    readonly participant?: string;
-    readonly expressEffect?: 'unsent' | 'landed' | 'unknown';
-    readonly landedId?: ActivityId;
-    readonly historyBounds?: {
-        readonly maxLimit: number;
-        readonly totalMatches: number;
-    };
-}
-export interface ApplicationError extends Error {
-    readonly operation?: ApplicationFailureDetail;
-}
-export interface SquareContextProjection {
-    readonly location: string;
-    readonly standingCount: number;
-    readonly held: boolean;
-    readonly now: number;
-    readonly participant?: string;
-    readonly automaticDeliveryAvailable: boolean;
-}
-export interface BuildApplicationInput {
+export interface SquareBuildInput extends SquareAtInput {
     readonly markdown: string;
     readonly hardCap?: number | null;
     readonly throttlePerMinute?: number;
     readonly template?: string;
     readonly force?: boolean;
 }
-export interface BuildApplicationData {
-    readonly location: string;
-    readonly hardCap: number | null;
-    readonly throttlePerMinute?: number;
-}
-export interface JoinApplicationOptions {
+export interface JoinOptions extends ObservationOptions {
     readonly takeover?: boolean;
     readonly last?: number;
 }
-export interface JoinApplicationData {
-    readonly participant: string;
+export interface JoinResult {
+    readonly participant: Participant;
     readonly activity: Activity | null;
     readonly kind: 'joined' | 'reconnected' | 'taken-over';
-    /** Known joined-or-done participants, NOT the current standing count. */
+    /** Known joined-or-done participants, not the current standing count. */
     readonly participantCount: number;
+    readonly observation?: JoinObservation;
 }
-export interface ExpressApplicationOptions extends ExpressOptions {
-    readonly noWait?: boolean;
-    readonly requireExplicitReach?: boolean;
-}
-export interface ExpressApplicationData {
-    readonly activity: Activity;
-    readonly waited: boolean;
-    readonly replyAuthorNotHere?: string;
+/** Optional fence for owner-scoped lifecycle actions. */
+export interface OwnershipFenceOptions {
+    readonly expectedEpoch?: number;
 }
-export interface CatchApplicationOptions extends CatchOptions {
-    readonly replace?: boolean;
+export interface Participant {
+    readonly name: string;
+    express(body: string, options?: ExpressOptions, control?: OperationControl): Promise<ExpressResult>;
+    listen(target: string, options?: ObservationOptions, control?: OperationControl): Promise<ListenerChangeResult>;
+    ignore(target: string, options?: ObservationOptions, control?: OperationControl): Promise<ListenerChangeResult>;
+    listening(options?: ObservationOptions, control?: OperationControl): Promise<ListeningResult>;
+    catch(options?: CatchOptions, control?: OperationControl): Promise<CatchResult>;
+    history(query?: HistoryQuery, control?: OperationControl): Promise<HistoryResult>;
+    hold(reason?: string, options?: ObservationOptions, control?: OperationControl): Promise<LifecycleResult>;
+    resume(options?: ObservationOptions, control?: OperationControl): Promise<LifecycleResult>;
+    /** Leave without a message. Only an omitted or empty body is accepted. */
+    done(body?: string, options?: ObservationOptions, control?: OperationControl): Promise<LifecycleResult>;
 }
 export type CatchTerminalStatus = 'already-active' | 'replaced' | 'capped' | 'quorum';
 export type CatchStopStatus = CatchTerminalStatus | 'empty-now' | 'stale';
-export interface CatchApplicationData extends CatchResult {
-    readonly status?: CatchTerminalStatus;
-}
-export interface HistoryApplicationQuery extends HistoryQuery {
-    readonly since?: number;
-    readonly at?: readonly ActivityId[];
-    readonly contextBefore?: number;
-    readonly contextAfter?: number;
-}
-export interface HistoryApplicationData {
-    readonly activities: readonly Activity[];
-}
-export interface ListeningData {
-    readonly listening: readonly string[];
-}
-export interface LifecycleData {
-    readonly activity: Activity;
-}
 export type ParticipantPresence = 'never-joined' | 'active' | 'watching' | 'done';
-/** Canonical public participant fields; status excludes never-joined roster entries. */
 export interface ParticipantSummary {
     readonly name: string;
     readonly state: 'active' | 'done' | 'not joined';
@@ -234,7 +205,10 @@ export interface ParticipantSummary {
     readonly unreadActivityCount: number;
     readonly pendingMentionCount: number;
 }
-export interface StatusApplicationData {
+export interface StatusOptions extends ObservationOptions {
+    readonly viewer?: string;
+}
+export interface StatusResult {
     readonly hardCap: number | null;
     readonly activeCount: number;
     readonly doneCount: number;
@@ -247,13 +221,13 @@ export interface StatusApplicationData {
         readonly at?: number;
     } | null;
     readonly latestActivity?: Activity;
+    readonly observation?: StatusObservation;
 }
-export interface ParticipantsApplicationData {
+export interface ParticipantsResult {
     readonly participants: readonly ParticipantSummary[];
+    readonly observation?: ParticipantsObservation;
 }
-export type DiagnosisApplicationData = DiagnoseResult;
-export type MigrationApplicationData = MigrationOutcome;
-export interface DiscoveryApplicationOptions {
+export interface DiscoveryOptions {
     readonly depth?: number;
     readonly limit?: number;
     readonly after?: string;
@@ -265,21 +239,14 @@ export interface SquareListItem {
     readonly participants: readonly string[];
     readonly activities: number;
 }
-export interface DiscoveryApplicationData {
+export interface DiscoveryResult {
     readonly items: readonly SquareListItem[];
     readonly stopped: boolean;
-    /** All discovered squares before applying the cursor or page limit. */
     readonly total: number;
     readonly remaining: number;
     readonly next?: string;
 }
-export interface DiscoveryProjection {
-    readonly cwd: string;
-    readonly now: number;
-    readonly depth: number;
-    readonly limit: number;
-}
-export interface InboxApplicationOptions {
+export interface InboxOptions {
     readonly limit?: number;
 }
 export interface InboxMembershipSummary {
@@ -287,16 +254,11 @@ export interface InboxMembershipSummary {
     readonly squarePath: string;
     readonly pending: number;
 }
-export interface InboxApplicationData {
+export interface InboxResult {
     readonly rows: readonly InboxMembershipSummary[];
     readonly total: number;
 }
-export interface InboxProjection {
-    readonly sessionId: string;
-    readonly now: number;
-    readonly limit: number;
-}
-export interface RecoveryApplicationData {
+export interface RecoveryResult {
     readonly participant?: string;
     readonly standingCount?: number;
     readonly held?: boolean;
@@ -306,7 +268,6 @@ export interface RecoveryApplicationData {
     readonly roster?: readonly string[];
     readonly activitySummaries?: readonly UnreadActivitySummary[];
 }
-export type RecoveryProjection = RecoveryApplicationData & Partial<SquareContextProjection>;
 export type StreamStart = {
     readonly kind: 'tail';
     readonly last: number;
@@ -314,11 +275,11 @@ export type StreamStart = {
     readonly kind: 'after';
     readonly after: number;
 };
-export interface StreamApplicationOptions {
+export interface StreamOptions {
     readonly recipient?: string;
     readonly start?: StreamStart;
 }
-export type StreamApplicationRecord = ArchiveRecord & {
+export type StreamRecord = ArchiveRecord & {
     readonly seq: number;
     readonly square: string;
     readonly route?: string;
@@ -336,33 +297,13 @@ export interface UnreadActivitySummary {
     readonly latestActivityAgeMs: number;
     readonly previews: readonly UnreadActivityPreview[];
 }
-/** Selected-row observations. participantCount in these existing concern DTOs is a standing count. */
-export interface RecoveryObservation {
-    readonly name: string;
-    readonly roster: readonly string[];
-    readonly activitySummaries: readonly UnreadActivitySummary[];
-    readonly participantCount: number;
-    readonly held: boolean;
-    readonly holdReason?: string;
-    readonly ownActivityCount: number;
-    readonly hardCap: number | null;
-}
 export interface EntryPresentation {
-    readonly joined: boolean;
     readonly joinedBefore: boolean;
     readonly scene: string;
-    readonly context: string;
     readonly joinContext: string;
     readonly recentActivities: readonly ArchiveRecord[];
     readonly perceptions: Readonly<Record<number, Perception>>;
     readonly sayNumbers: Readonly<Record<number, number>>;
-    readonly participantCount: number;
-    readonly held: boolean;
-}
-export interface HistoryContinuation {
-    readonly direction: 'before' | 'after';
-    readonly cursor: ActivityId;
-    readonly limit: number;
 }
 export interface ListPresentation {
     readonly context: readonly string[];
@@ -370,7 +311,6 @@ export interface ListPresentation {
     readonly activities: number;
 }
 export interface PresenceClassification {
-    /** Names in canonical data, watching first, then recent signs of life; no presentation clipping. */
     readonly orderedHereNames: readonly string[];
     readonly lingeringCount: number;
     readonly classificationByName: Readonly<Record<string, 'here' | 'lingering' | 'done' | 'not-joined'>>;
@@ -387,54 +327,61 @@ export interface StreamProjection {
     readonly cursor: number;
     readonly hasMore: boolean;
 }
-export interface EntryProjection extends SquareContextProjection, EntryPresentation {
+export interface SquareObservation {
+    readonly location: string;
+    readonly standingCount: number;
+    readonly held: boolean;
+    readonly now: number;
+    readonly participant?: string;
+    readonly automaticDeliveryAvailable: boolean;
+}
+export interface JoinObservation extends SquareObservation {
+    readonly entry?: EntryPresentation;
+    /** The receipt succeeded, but optional recent-history/context enrichment was unavailable. */
+    readonly enrichmentUnavailable?: true;
 }
-export interface ExpressionObservation extends Pick<SquareContextProjection, 'standingCount' | 'held' | 'now'> {
+export interface ExpressionObservation extends Pick<SquareObservation, 'standingCount' | 'held' | 'now'> {
     readonly ownActivityCount: number;
     readonly hardCap: number | null;
 }
-export interface ExpressProjection extends SquareContextProjection, ExpressionObservation {
+export interface ExpressObservation extends SquareObservation, ExpressionObservation {
     readonly participant: string;
     readonly pendingPublic: readonly ArchiveRecord[];
     readonly sayNumbers: Readonly<Record<number, number>>;
     readonly perceptions: Readonly<Record<number, Perception>>;
     readonly reentry?: Activity;
-    readonly delivery?: DeliveryResult;
 }
-export interface CatchProjection extends SquareContextProjection, ExpressionObservation {
+export interface CatchObservation extends SquareObservation, ExpressionObservation {
     readonly participant: string;
     readonly sayNumbers: Readonly<Record<number, number>>;
-    /** Optional nearby presence is not a commit-time selection fact. */
     readonly presence?: CatchPresence;
     readonly stop?: CatchStopStatus;
     readonly waitStarted?: boolean;
     readonly replaced?: boolean;
     readonly enrichmentUnavailable?: true;
 }
-export interface HistoryProjection extends SquareContextProjection {
+export interface HistoryContinuation {
+    readonly direction: 'before' | 'after';
+    readonly cursor: ActivityId;
+    readonly limit: number;
+}
+export interface HistoryObservation extends SquareObservation {
     readonly activities: readonly ArchiveRecord[];
     readonly sayNumbers: Readonly<Record<number, number>>;
     readonly presenceAnchors: Readonly<Record<number, readonly string[]>>;
     readonly totalMatches: number;
-    /** Ordinary terminal history visibility and stable continuation are owner policy. */
     readonly visibleActivities: readonly ArchiveRecord[];
     readonly continuation?: HistoryContinuation;
 }
-export interface ListenerProjection extends SquareContextProjection {
+export interface ListenerObservation extends SquareObservation {
     readonly participant: string;
     readonly target: string;
     readonly requestedTarget: string;
 }
-export interface EventPresentation {
+export interface LifecycleObservation extends SquareObservation {
     readonly activity: ArchiveRecord;
-    readonly participantCount: number;
-    readonly held: boolean;
-}
-export interface LifecycleProjection extends SquareContextProjection, EventPresentation {
-    readonly delivery?: DeliveryResult;
 }
-export interface StatusProjection extends SquareContextProjection, PresenceClassification {
-    /** Full roster size, including never-joined names omitted from status data. */
+export interface StatusObservation extends SquareObservation, PresenceClassification {
     readonly knownParticipantCount: number;
     readonly latestActNumber?: number;
     readonly latestPerception?: Perception;
@@ -446,32 +393,5 @@ export interface StatusProjection extends SquareContextProjection, PresenceClass
     readonly attentionNames: readonly string[];
     readonly viewer: string;
 }
-export interface ParticipantsProjection extends SquareContextProjection, PresenceClassification {
-}
-export interface SquareApplication<Presentation extends boolean = true> {
-    now(): number;
-    build(input: BuildApplicationInput, control?: OperationControl): Promise<ApplicationOutcome<BuildApplicationData, SquareContextProjection, Presentation>>;
-    join(options?: JoinApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<JoinApplicationData, EntryProjection, Presentation>>;
-    express(body: string, options?: ExpressApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<ExpressApplicationData, ExpressProjection, Presentation>>;
-    catch(options?: CatchApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<CatchApplicationData, CatchProjection, Presentation>>;
-    history(query?: HistoryApplicationQuery, control?: OperationControl): Promise<ApplicationOutcome<HistoryApplicationData, HistoryProjection, Presentation>>;
-    listen(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection, Presentation>>;
-    ignore(target: string, control?: OperationControl): Promise<ApplicationOutcome<ListenerChangeData, ListenerProjection, Presentation>>;
-    listening(control?: OperationControl): Promise<ApplicationOutcome<ListeningData, SquareContextProjection, Presentation>>;
-    hold(reason?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
-    resume(control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
-    done(body?: string, control?: OperationControl): Promise<ApplicationOutcome<LifecycleData, LifecycleProjection, Presentation>>;
-    status(viewer?: string, control?: OperationControl): Promise<ApplicationOutcome<StatusApplicationData, StatusProjection, Presentation>>;
-    participants(control?: OperationControl): Promise<ApplicationOutcome<ParticipantsApplicationData, ParticipantsProjection, Presentation>>;
-    diagnose(control?: OperationControl): Promise<ApplicationOutcome<DiagnosisApplicationData, Partial<SquareContextProjection>, Presentation>>;
-    migrate(control?: OperationControl): Promise<ApplicationOutcome<MigrationApplicationData, Partial<SquareContextProjection>, Presentation>>;
-    discover(options: DiscoveryApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<DiscoveryApplicationData, DiscoveryProjection, Presentation>>;
-    inbox(sessionId: string, options?: InboxApplicationOptions, control?: OperationControl): Promise<ApplicationOutcome<InboxApplicationData, InboxProjection, Presentation>>;
-    recovery(control?: OperationControl): Promise<ApplicationOutcome<RecoveryApplicationData, RecoveryProjection, Presentation>>;
-    stream(options: StreamApplicationOptions, control?: OperationControl): AsyncIterable<StreamApplicationRecord>;
-}
-export type JoinApplicationResult = JoinApplicationData;
-export type ExpressApplicationResult = ExpressApplicationData;
-export type ApplicationStatus = StatusApplicationData;
-export type ApplicationStatusProjection = StatusProjection;
-export type ApplicationParticipants = ParticipantsApplicationData;
+export interface ParticipantsObservation extends SquareObservation, PresenceClassification {
+}

package/dist/square-tools.d.ts

@@ -1,12 +1,13 @@
 import { z } from 'zod/v4';
-import type { ApplicationOutcome, OperationControl, SquareApplication } from './square-facade.js';
+import type { Square } from './square-api.js';
+import type { OperationControl } from './square-facade.js';
 type JsonObject = Record<string, unknown>;
-type Outcome = Promise<ApplicationOutcome<object, unknown, false>>;
+type Outcome = Promise<object>;
 interface ToolDefinition {
     name: string;
     description: string;
     inputSchema: z.ZodObject<z.ZodRawShape>;
-    run(app: SquareApplication<false>, args: JsonObject, control: OperationControl): Outcome;
+    run(square: Square, args: JsonObject, control: OperationControl): Outcome;
 }
 export declare const SQUARE_TOOL_INSTRUCTIONS = "The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.";
 export declare const SQUARE_TOOLS: readonly ToolDefinition[];

package/dist/square-tools.js

@@ -6,36 +6,42 @@ const activityId = z.string().regex(/^act\/(0|[1-9][0-9]*)$/);
 const stringArray = z.array(z.string());
 function tool(name, description, shape, run) {
     const inputSchema = z.object({ ...shape, location }).strict();
-    return { name, description, inputSchema, run: (app, args, control) => {
+    return { name, description, inputSchema, run: (square, args, control) => {
             const { location: _location, ...operationArgs } = inputSchema.parse(args);
-            return run(app, operationArgs, control);
+            return run(square, operationArgs, control);
         } };
 }
 export const SQUARE_TOOL_INSTRUCTIONS = 'The catch tool consumes activities. Use history with act/<index> cursors for read-only archive access.';
 export const SQUARE_TOOLS = [
-    tool('join', 'Join the square as a participant.', { as: participant, takeover: z.boolean().optional().describe('Take the name from its current session owner.') }, (app, { takeover }, control) => app.join({ takeover }, control)),
-    tool('express', 'Express a message or embodied action in the square. Mentions and replies direct attention; bell reaches everyone. Bare activity is valid even with no listeners.', {
+    tool('join', 'Join the square as a participant.', { as: participant, takeover: z.boolean().optional().describe('Take the name from its current session owner.') }, async (square, { as, takeover }, control) => {
+        const { participant, ...receipt } = await square.join(as, { takeover }, control);
+        return { ...receipt, participant: participant.name };
+    }),
+    tool('express', 'Express a message or embodied action in the square. Mentions and replies direct attention; bell reaches everyone and keeps body @names literal. Bell cannot combine with explicit mentions. Bare activity is valid even with no listeners.', {
         as: participant, body: z.string(), mentions: stringArray.optional(), reach: z.enum(['bell']).optional(),
         reply: activityId.optional(), noMention: z.boolean().optional().describe('Disable body @name scanning; explicit mentions and reply still apply.'),
         force: z.boolean().optional().describe('Speak without first catching unread activity or satisfying attention etiquette.'),
         noWait: z.boolean().optional().describe('Return an error rather than waiting when held or throttled.'),
-    }, (app, { body, as: _participant, ...options }, control) => app.express(body, options, control)),
+    }, async (square, { body, as, ...options }, control) => {
+        const { delivery: _delivery, ...result } = await (await square.participant(as)).express(body, options, control);
+        return result;
+    }),
     tool('catch', 'Catch and consume activities perceptible to the participant. idle waits for relevant activity or this many milliseconds of quiet; omitted means immediate. id catches one activity and cannot be combined with filters, idle or limit.', {
         as: participant, id: activityId.optional(), idle: z.number().finite().min(0).optional(), from: stringArray.optional(),
         mention: z.boolean().optional(), limit: z.number().int().min(1).optional(),
-    }, (app, { as: _participant, ...options }, control) => app.catch(options, control)),
+    }, async (square, { as, ...options }, control) => (await square.participant(as)).catch(options, control)),
     tool('history', 'Read the activity stream without consuming it, using stable activity-id cursors. Default page size is 10, maximum 100. grep is a regex; fixed is literal text; use only one.', {
         limit: z.number().int().min(1).optional(), order: z.enum(['asc', 'desc']).optional(), before: activityId.optional(), after: activityId.optional(),
         grep: z.string().optional(), fixed: z.string().optional(), from: stringArray.optional(), mention: z.string().optional(),
-    }, (app, args, control) => app.history(args, control)),
-    tool('listen', 'Listen for future bare activity from a participant, clearing any ignore of them.', { as: participant, target: z.string() }, (app, { target }, control) => app.listen(target, control)),
-    tool('ignore', 'Block a participant’s future mentions and bare activity. Listening again clears the ignore; already landed activity is unchanged.', { as: participant, target: z.string() }, (app, { target }, control) => app.ignore(target, control)),
-    tool('listening', 'List participants this participant is listening to.', { as: participant }, (app, _args, control) => app.listening(control)),
-    tool('hold', 'Raise a hand to hold the square.', { as: participant, reason: z.string().optional() }, (app, { reason }, control) => app.hold(reason, control)),
-    tool('resume', 'Release the current hold.', { as: participant }, (app, _args, control) => app.resume(control)),
-    tool('done', 'Leave the square without adding a message.', { as: participant }, (app, _args, control) => app.done(undefined, control)),
-    tool('status', 'Read the public status of the square.', {}, (app, _args, control) => app.status(undefined, control)),
-    tool('participants', 'List participants standing in or done with the square.', {}, (app, _args, control) => app.participants(control)),
+    }, (square, args, control) => square.history(args, control)),
+    tool('listen', 'Listen for future bare activity from a participant, clearing any ignore of them.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).listen(target, {}, control)),
+    tool('ignore', 'Block a participant’s future mentions and bare activity. Listening again clears the ignore; already landed activity is unchanged.', { as: participant, target: z.string() }, async (square, { as, target }, control) => (await square.participant(as)).ignore(target, {}, control)),
+    tool('listening', 'List participants this participant is listening to.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).listening({}, control)),
+    tool('hold', 'Raise a hand to hold the square.', { as: participant, reason: z.string().optional() }, async (square, { as, reason }, control) => (await square.participant(as)).hold(reason, {}, control)),
+    tool('resume', 'Release the current hold.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).resume({}, control)),
+    tool('done', 'Leave the square without adding a message.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).done(undefined, {}, control)),
+    tool('status', 'Read the public status of the square.', {}, (square, _args, control) => square.status({}, control)),
+    tool('participants', 'List participants standing in or done with the square.', {}, (square, _args, control) => square.participants({}, control)),
 ];
 export function squareToolFailure(error, signal) {
     const normalized = signal?.aborted

package/dist/stream.d.ts

@@ -1,3 +1,3 @@
-import type { OpenOptions, OperationControl, StreamApplicationOptions, StreamApplicationRecord } from './square-facade.js';
+import type { OpenOptions, OperationControl, StreamOptions, StreamRecord } from './square-facade.js';
 /** Pull-based observation; return interrupts an outstanding pull before awaiting its cleanup. */
-export declare function streamSquare(squarePath: string, options?: StreamApplicationOptions, control?: OperationControl, openOptions?: OpenOptions): AsyncIterable<StreamApplicationRecord>;
+export declare function streamSquare(squarePath: string, options?: StreamOptions, control?: OperationControl, openOptions?: OpenOptions): AsyncIterable<StreamRecord>;