@astrosheep/square 0.3.92 → 0.3.94

package/dist/square-sqlite.js

@@ -1,5 +1,5 @@
 import { DatabaseSync as MemoryDatabase } from 'node:sqlite';
-import { sameBody, SquareError, nameKey, isWakeRouteKind, validateBody, validateActivityMetadata, activityMetadataHasContent } from './model.js';
+import { SquareError, nameKey, isWakeRouteKind, validateOwner, validateActivityMetadata, activityMetadataHasContent } from './model.js';
 import { validateMetadataMatch, matchingDeferrals, validateDeferralId } from './delivery-deferral.js';
 import { deriveLanding, landingFacts } from './square-domain.js';
 import { legacyRowFramingIssue } from './square-legacy-framing.js';
@@ -11,7 +11,9 @@ const V1_USER_VERSION = 1;
 export const V2_USER_VERSION = 2;
 export const V3_USER_VERSION = 3;
 export const V4_USER_VERSION = 4;
-export const CURRENT_USER_VERSION = 5;
+export const V5_USER_VERSION = 5;
+export const V6_USER_VERSION = 6;
+export const CURRENT_USER_VERSION = 7;
 export const V1_SNAPSHOT_TABLE = 'square_snapshot';
 const V1_SNAPSHOT_DDL = `CREATE TABLE ${V1_SNAPSHOT_TABLE} (id INTEGER PRIMARY KEY CHECK(id=1), revision INTEGER NOT NULL CHECK(revision>=0), state TEXT NOT NULL)`;
 const V1_SNAPSHOT_COLUMNS = [
@@ -87,6 +89,7 @@ export const DELIVERY_DEFERRALS_SQL = `CREATE TABLE delivery_deferrals (
   PRIMARY KEY (participant_key_json,generation_json,deferral_id_json)
 ) WITHOUT ROWID;
 CREATE INDEX delivery_deferral_expiry ON delivery_deferrals(participant_key_json,generation_json,expires_at);`;
+const ATTACHMENT_COLUMN_SQL = "attachment TEXT NOT NULL DEFAULT 'attached' CHECK (attachment IN ('attached','detached'))";
 export const SCHEMA_SQL = `CREATE TABLE square_meta (
   id INTEGER PRIMARY KEY CHECK (id = 1),
   revision INTEGER NOT NULL CHECK (revision BETWEEN 0 AND 9007199254740991),
@@ -119,13 +122,12 @@ CREATE TABLE catch_leases (
 CREATE TABLE seats (
   participant_key_json TEXT COLLATE BINARY PRIMARY KEY NOT NULL,
   participant_json TEXT NOT NULL,
-  channel_json TEXT NOT NULL,
-  session_json TEXT NOT NULL,
-  agent_json TEXT,
+  owner_json TEXT NOT NULL,
   generation_json TEXT NOT NULL,
-  wake_address_json TEXT CHECK (wake_address_json IS NULL OR json_valid(wake_address_json))
+  wake_address_json TEXT CHECK (wake_address_json IS NULL OR json_valid(wake_address_json)),
+  ${ATTACHMENT_COLUMN_SQL}
 ) WITHOUT ROWID;
-CREATE INDEX seat_body ON seats(channel_json, session_json, agent_json);
+CREATE INDEX seat_owner ON seats(owner_json);
 CREATE TABLE delivery_evidence (
   participant_key_json TEXT COLLATE BINARY NOT NULL,
   participant_json TEXT NOT NULL,
@@ -180,7 +182,11 @@ CREATE TABLE landed_audience (
   UNIQUE (act_index, recipient_order)
 ) WITHOUT ROWID;
 CREATE INDEX audience_recipient ON landed_audience(recipient_key_json, act_index);`;
-export const FORMAT4_SCHEMA_SQL = SCHEMA_SQL.replace(DELIVERY_DEFERRALS_SQL, '');
+export const FORMAT6_SCHEMA_SQL = SCHEMA_SQL.replace(`  owner_json TEXT NOT NULL,\n  generation_json TEXT NOT NULL,`, `  channel_json TEXT NOT NULL,\n  session_json TEXT NOT NULL,\n  agent_json TEXT,\n  generation_json TEXT NOT NULL,`).replace('CREATE INDEX seat_owner ON seats(owner_json);', 'CREATE INDEX seat_body ON seats(channel_json, session_json, agent_json);');
+export const FORMAT5_SCHEMA_SQL = FORMAT6_SCHEMA_SQL.replace(`,\n  ${ATTACHMENT_COLUMN_SQL}`, '');
+export const FORMAT4_SCHEMA_SQL = FORMAT5_SCHEMA_SQL.replace(DELIVERY_DEFERRALS_SQL, '');
+const FORMAT6_SCHEMA = FORMAT6_SCHEMA_SQL.split(';').map(s => s.trim()).filter(Boolean).map(normalizedSql).sort();
+const FORMAT5_SCHEMA = FORMAT5_SCHEMA_SQL.split(';').map(s => s.trim()).filter(Boolean).map(normalizedSql).sort();
 const EXPECTED_SCHEMA_SQL = SCHEMA_SQL.split(';').map(s => s.trim()).filter(Boolean).map(normalizedSql).sort();
 const FORMAT4_SCHEMA = FORMAT4_SCHEMA_SQL.split(';').map(s => s.trim()).filter(Boolean).map(normalizedSql).sort();
 const encode = JSON.stringify;
@@ -372,17 +378,19 @@ function wakeAddress(value) {
     stableJson(entries);
     return immutable({ kind: address.kind, address: entries });
 }
-function bodyFrom(row) {
-    const body = { channel: decoded(row.channel_json, true), session: decoded(row.session_json, true), ...(row.agent_json === null ? {} : { agent: decoded(row.agent_json, true) }) };
-    validateBody(body);
-    return immutable(body);
+function ownerFrom(row) {
+    const owner = decoded(row.owner_json, true);
+    validateOwner(owner);
+    return owner;
 }
 function seat(row) {
     const participant = decoded(row.participant_json, true);
     requireFact(row.participant_key_json === key(participant));
     const generation = activityId(decoded(row.generation_json, true));
     const parsedWake = row.wake_address_json === null ? undefined : wakeAddress(json(row.wake_address_json));
-    return immutable({ participant, body: bodyFrom(row), generation, ...(parsedWake === undefined ? {} : { wakeAddress: parsedWake }) });
+    requireFact(row.attachment === 'attached' || row.attachment === 'detached', 'seat attachment is malformed.');
+    requireFact(row.attachment !== 'detached' || parsedWake === undefined, 'a detached seat has a wake address.');
+    return immutable({ participant, owner: ownerFrom(row), generation, attachment: row.attachment, ...(parsedWake === undefined ? {} : { wakeAddress: parsedWake }) });
 }
 function nativeCorrelation(value) {
     const item = shape(value, ['harness'], ['token', 'messageId', 'payloadHash']);
@@ -453,7 +461,7 @@ export function validateRowFraming(db, version, location = '') {
     const identity = db.prepare('SELECT application_id,user_version FROM pragma_application_id,pragma_user_version').get();
     requireFact(identity.application_id === APPLICATION_ID, 'unrelated SQLite database.');
     requireFact(identity.user_version === version, 'unsupported SQLite format version.');
-    validateOwnedSchema(db, version === V4_USER_VERSION ? FORMAT4_SCHEMA : EXPECTED_SCHEMA_SQL, location);
+    validateOwnedSchema(db, version === V4_USER_VERSION ? FORMAT4_SCHEMA : version === V5_USER_VERSION ? FORMAT5_SCHEMA : version === V6_USER_VERSION ? FORMAT6_SCHEMA : EXPECTED_SCHEMA_SQL, location);
 }
 export function validateSqliteHeader(db, location = '') {
     const identity = db.prepare('SELECT application_id,user_version FROM pragma_application_id,pragma_user_version').get();
@@ -462,7 +470,7 @@ export function validateSqliteHeader(db, location = '') {
         validateLegacyFraming(db, APPLICATION_ID, location);
         throw new SquareError('invalid_args', `Square artifact at ${location} needs migration.\nStop sessions using it, back it up, then migrate and verify before restarting.`, { reason: 'migration_required' });
     }
-    if (identity.user_version === V2_USER_VERSION || identity.user_version === V3_USER_VERSION || identity.user_version === V4_USER_VERSION) {
+    if (identity.user_version === V2_USER_VERSION || identity.user_version === V3_USER_VERSION || identity.user_version === V4_USER_VERSION || identity.user_version === V5_USER_VERSION || identity.user_version === V6_USER_VERSION) {
         validateRowFraming(db, identity.user_version, location);
         throw new SquareError('invalid_args', `Square artifact at ${location} needs migration.\nStop sessions using it, back it up, then migrate and verify before restarting.`, { reason: 'migration_required' });
     }
@@ -543,17 +551,16 @@ export function createSqliteDriver(db) {
     const latestSeats = `seats s JOIN participants p ON p.name_key_json=s.participant_key_json
         JOIN activities a ON a.act_index=p.last_join_index AND a.kind='join' AND a.actor_key_json=p.name_key_json
         AND s.generation_json='"act/'||a.act_index||'"'`;
-    function bodySeats(body, lifecycle) {
-        validateBody(body);
-        return immutable(all(`SELECT s.* FROM ${latestSeats} WHERE p.${lifecycle}=1 AND s.channel_json=? AND s.session_json=? AND s.agent_json IS ? ORDER BY s.participant_key_json`, [encode(body.channel), encode(body.session), body.agent === undefined ? null : encode(body.agent)]).map(seat));
+    function ownerSeats(owner) {
+        validateOwner(owner);
+        return immutable(all(`SELECT s.* FROM ${latestSeats} WHERE p.joined=1 AND s.owner_json=? ORDER BY s.participant_key_json`, [encode(owner)]).map(seat));
     }
     const read = {
         seat(name) {
             const r = one(`SELECT s.* FROM ${latestSeats} WHERE p.joined=1 AND s.participant_key_json=?`, [key(name)]);
             return r ? seat(r) : undefined;
         },
-        seatsForBody: body => bodySeats(body, 'joined'),
-        completedSeatsForBody: body => bodySeats(body, 'done'),
+        seatsForOwner: ownerSeats,
         deliveryEvidence(participant, generation, activityIndex) {
             const args = [key(participant), encode(generation)];
             const filter = activityIndex === undefined ? '' : ' AND act_index=?';
@@ -713,14 +720,14 @@ export function createSqliteDriver(db) {
     };
     const writes = {
         storeSeat(value) {
-            validateBody(value.body);
+            validateOwner(value.owner);
             activityId(value.generation);
             string(value.participant, true);
             const existing = read.seat(value.participant);
             if (existing !== undefined && stableJson(existing) === stableJson(value))
                 return false;
             const wake = value.wakeAddress === undefined ? null : encode(value.wakeAddress);
-            run('INSERT INTO seats(participant_key_json,participant_json,channel_json,session_json,agent_json,generation_json,wake_address_json) VALUES(?,?,?,?,?,?,?) ON CONFLICT(participant_key_json) DO UPDATE SET participant_json=excluded.participant_json,channel_json=excluded.channel_json,session_json=excluded.session_json,agent_json=excluded.agent_json,generation_json=excluded.generation_json,wake_address_json=excluded.wake_address_json', [key(value.participant), encode(value.participant), encode(value.body.channel), encode(value.body.session), value.body.agent === undefined ? null : encode(value.body.agent), encode(value.generation), wake]);
+            run('INSERT INTO seats(participant_key_json,participant_json,owner_json,generation_json,wake_address_json,attachment) VALUES(?,?,?,?,?,?) ON CONFLICT(participant_key_json) DO UPDATE SET participant_json=excluded.participant_json,owner_json=excluded.owner_json,generation_json=excluded.generation_json,wake_address_json=excluded.wake_address_json,attachment=excluded.attachment', [key(value.participant), encode(value.participant), encode(value.owner), encode(value.generation), wake, value.attachment]);
             run('DELETE FROM catch_leases WHERE owner_json=?', [encode(value.participant)]);
             run('DELETE FROM delivery_deferrals WHERE participant_key_json=?', [key(value.participant)]);
             deliveryChanged = true;
@@ -739,12 +746,28 @@ export function createSqliteDriver(db) {
                 deliveryChanged = true;
             return count > 0;
         },
+        reattachSeat(value, address) {
+            const current = read.seat(value.participant);
+            if (current?.attachment !== 'detached')
+                return false;
+            run("UPDATE seats SET attachment='attached',wake_address_json=? WHERE participant_key_json=? AND generation_json=?", [address === undefined ? null : encode(wakeAddress(address)), key(value.participant), encode(value.generation)]);
+            deliveryChanged = true;
+            return true;
+        },
+        detachSeat(value) {
+            const count = run("UPDATE seats SET attachment='detached',wake_address_json=NULL WHERE participant_key_json=? AND generation_json=? AND attachment='attached'", [key(value.participant), encode(value.generation)]);
+            if (!count)
+                return false;
+            run('DELETE FROM catch_leases WHERE owner_json=?', [encode(value.participant)]);
+            run('DELETE FROM delivery_deferrals WHERE participant_key_json=? AND generation_json=?', [key(value.participant), encode(value.generation)]);
+            deliveryChanged = true;
+            return true;
+        },
         removeSeat(value) {
-            // Done hides current authority; retain only its latest coordinate for exact-body resume.
             const row = one(`SELECT s.* FROM ${latestSeats} WHERE p.done=1 AND s.participant_key_json=?`, [key(value.participant)]);
-            if (row === undefined || decoded(row.generation_json) !== value.generation)
+            if (row === undefined || decoded(row.generation_json) !== value.generation || ownerFrom(row) !== value.owner)
                 return false;
-            run('UPDATE seats SET wake_address_json=NULL WHERE participant_key_json=?', [key(value.participant)]);
+            run('DELETE FROM seats WHERE participant_key_json=?', [key(value.participant)]);
             run('DELETE FROM catch_leases WHERE owner_json=?', [encode(value.participant)]);
             run('DELETE FROM delivery_deferrals WHERE participant_key_json=?', [key(value.participant)]);
             changed = true;
@@ -872,7 +895,7 @@ export function createSqliteDriver(db) {
                 wakeAddress(input.route);
             const currentSeat = read.seat(input.seat.participant);
             const item = read.activity(index);
-            if (currentSeat === undefined || currentSeat.generation !== input.seat.generation || !sameBody(currentSeat.body, input.seat.body)
+            if (currentSeat === undefined || currentSeat.attachment !== 'attached' || currentSeat.generation !== input.seat.generation || currentSeat.owner !== input.seat.owner
                 || item?.kind !== 'say' || read.directedAt(input.seat.participant, index) === undefined)
                 return { status: 'stale' };
             if (matchingDeferrals(read.deliveryDeferrals(currentSeat.participant, currentSeat.generation), item.metadata, input.at).length > 0)
@@ -1023,15 +1046,18 @@ export function exportSqliteState(db) {
 }
 /** Full read-only integrity inspection, including maintained-index replay comparison. */
 export function inspectSqlite(db) {
+    return inspectRows(db, seat);
+}
+function inspectRows(db, inspectSeat) {
     const check = db.prepare('PRAGMA integrity_check').all();
     requireFact(check.length === 1 && check[0].integrity_check === 'ok', 'SQLite integrity check failed.');
     const state = exportSqliteState(db), d = createSqliteDriver(db);
     d.roster();
     for (const row of db.prepare('SELECT * FROM seats').all())
-        seat(row);
+        inspectSeat(row);
     for (const row of db.prepare('SELECT * FROM delivery_evidence').all())
         deliveryEvidence(row);
-    if (db.prepare('PRAGMA user_version').get().user_version === CURRENT_USER_VERSION) {
+    if (Number(db.prepare('PRAGMA user_version').get().user_version) >= V5_USER_VERSION) {
         for (const row of db.prepare('SELECT * FROM delivery_deferrals').all())
             deliveryDeferral(row);
     }

package/dist/square-tools.d.ts

@@ -1,20 +1,17 @@
 import { z } from 'zod/v4';
 import { type Square } from './square-api.js';
-import type { OperationControl } from './square-facade.js';
+import type { Owner, WakeAddress, OperationControl } from './square-facade.js';
+export interface ToolIdentity {
+    readonly owner?: Owner;
+    readonly wakeAddress?: WakeAddress;
+}
 type JsonObject = Record<string, unknown>;
-type Outcome = Promise<object>;
-type ToolRender = (result: JsonObject, args: JsonObject) => string | undefined;
 interface ToolDefinition {
     name: string;
     description: string;
     inputSchema: z.ZodObject<z.ZodRawShape>;
-    run(square: Square, args: JsonObject, control: ToolControl): Outcome;
-    /** Human text identical to what the CLI prints; transports show this to people. */
-    render: ToolRender;
-}
-/** A transport that shows people the square asks the same operation for its rendering facts. */
-export interface ToolControl extends OperationControl {
-    readonly observe?: boolean;
+    /** 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>;
 }
 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_TOOLS: readonly ToolDefinition[];

package/dist/square-tools.js

@@ -1,51 +1,22 @@
 import { z } from 'zod/v4';
 import { isSquareError } from './model.js';
-import { CATCH_DEFAULT_LIMIT } from './square-api.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';
-const location = z.string().optional().describe('Which square: a .square file path, or a backend URI like stdio://name/key. Relative paths start from the working directory. Leave it out for the configured square.');
+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 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());
-/** Keep the observation request internal: it is not an argument a caller decides. */
-function observation(control) {
-    return control.observe === true ? { observe: true } : {};
-}
-/** Tool receipts are plain JSON; each renderer re-declares the facts it reads. */
+/** Each renderer declares the operation facts it reads. */
 function rendering(render) {
     return (result, args) => render(result, args);
 }
-/**
- * Tool receipts are the one machine surface without activity metadata: a receipt copy drops every
- * property named `metadata` while domain activities keep theirs for SDK, CLI, stdio and stream readers.
- */
-function withoutActivityMetadata(value) {
-    if (Array.isArray(value))
-        return value.map(withoutActivityMetadata);
-    if (value === null || typeof value !== 'object')
-        return value;
-    const prototype = Object.getPrototypeOf(value);
-    if (prototype !== Object.prototype && prototype !== null)
-        return value;
-    return Object.fromEntries(Object.entries(value).filter(([key]) => key !== 'metadata')
-        .map(([key, item]) => [key, withoutActivityMetadata(item)]));
-}
-/**
- * Human text renders from the unfiltered receipt, so metadata-only says keep the placeholder the
- * CLI prints and every other sentence stays identical. Machines only ever receive the filtered copy.
- */
-const renderingReceipts = new WeakMap();
-function renderingReceipt(receipt) {
-    return (renderingReceipts.get(receipt) ?? receipt);
-}
 function tool(name, description, shape, run, render) {
     const inputSchema = z.object({ ...shape, location }).strict();
-    return { name, description, inputSchema, render: (receipt, args) => render(renderingReceipt(receipt), args),
-        run: async (square, args, control) => {
+    return { name, description, inputSchema,
+        run: async (square, args, control, identity) => {
             const { location: _location, ...operationArgs } = inputSchema.parse(args);
-            const receipt = await run(square, operationArgs, control);
-            const filtered = withoutActivityMetadata(receipt);
-            renderingReceipts.set(filtered, receipt);
-            return filtered;
+            const receipt = await run(square, operationArgs, control, identity);
+            return render(receipt, operationArgs) ?? '';
         } };
 }
 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.';
@@ -53,10 +24,7 @@ const target = z.string().describe('The participant to turn toward or away from.
 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.', {
         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.'),
-    }, async (square, { as, takeover }, control) => {
-        const { participant, ...receipt } = await square.join(as, { takeover, ...observation(control) }, control);
-        return { ...receipt, participant: participant.name };
-    }, rendering((result) => renderJoinResult(result))),
+    }, (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.', {
         as: participant,
         body: z.string().describe('What you say or do. Markdown works; *asterisks* mark an action.'),
@@ -66,10 +34,7 @@ export const SQUARE_TOOLS = [
         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.'),
         noWait: z.boolean().optional().describe('If a hand is raised or you are speaking too fast, return at once instead of waiting.'),
-    }, async (square, { body, as, ...options }, control) => {
-        const { delivery: _delivery, ...result } = await (await square.participant(as)).express(body, { ...options, ...observation(control) }, control);
-        return result;
-    }, rendering((result) => renderExpression(result.observation?.location ?? '', result))),
+    }, async (square, { body, as, ...options }, control, identity) => (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.', {
         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.'),
@@ -77,7 +42,7 @@ export const SQUARE_TOOLS = [
         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) => (await square.participant(as)).catch({ ...options, ...observation(control) }, control), rendering((result, args) => {
+    }, async (square, { as, ...options }, control, identity) => (await selectOwnSeat(square, identity.owner, as)).catch({ ...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;
@@ -92,25 +57,28 @@ export const SQUARE_TOOLS = [
         fixed: z.string().optional().describe('Only activities containing this exact text.'),
         from: stringArray.optional().describe('Only what these participants said.'),
         mention: z.string().optional().describe('Only what was addressed to this participant.'),
-    }, (square, args, control) => square.history({ ...args, ...observation(control) }, control), rendering((result, args) => renderHistoryResult(result.observation?.location ?? '', result, { query: args }))),
+    }, (square, args, control) => square.history({ ...args, observe: true }, control), rendering((result, args) => renderHistoryResult(result.observation?.location ?? '', result, { query: args }))),
     tool('attention', 'Turn toward someone or away from them, from now on. Listen: hear everything they say, even to others. Unlisten: stop listening without clearing an ignore; mentions and replies still reach you unless ignored. Ignore: hear nothing from them but bells. What was already said stays as it was.', {
         as: participant, action: z.enum(['listen', 'unlisten', 'ignore']).describe('"listen", "unlisten" or "ignore". Listening again ends an ignore.'), target,
-    }, async (square, { as, action, target }, control) => {
-        const self = await square.participant(as);
-        return self[action](target, observation(control), control);
+    }, async (square, { as, action, target }, control, identity) => {
+        const self = await selectOwnSeat(square, identity.owner, as);
+        return self[action](target, { observe: true }, control);
     }, rendering((result, args) => renderListenerChange(result.observation?.location ?? '', args.action, result))),
     tool('hold', 'Raise a hand to pause the conversation; lower it with release. While a hand is up, new words wait to land.', {
         as: participant,
         reason: z.string().optional().describe('Why you are pausing. Everyone sees it.'),
         release: z.boolean().optional().describe('true lowers the raised hand so the conversation goes on.'),
-    }, async (square, { as, reason, release }, control) => {
-        const self = await square.participant(as);
-        return release === true ? self.resume(observation(control), control) : self.hold(reason, observation(control), control);
+    }, async (square, { as, reason, release }, control, identity) => {
+        const self = await selectOwnSeat(square, identity.owner, as);
+        return release === true ? self.resume({ observe: true }, control) : self.hold(reason, { observe: true }, control);
     }, rendering((result, args) => renderLifecycleResult(result.observation?.location ?? '', args.release === true ? 'resume' : 'hold', result))),
-    tool('done', 'Step out of the square. Everyone sees you leave, and you stop listening to anyone. Leaving carries no words, so say goodbye with express first. Stay instead if someone may still need you; you can join again later.', { as: participant }, async (square, { as }, control) => (await square.participant(as)).done(undefined, observation(control), control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', 'done', result))),
+    tool('done', 'Step out of the square. Everyone sees you leave, and you stop listening to anyone. Leaving carries no words, so say goodbye with express first. Stay instead if someone may still need you; you can join again later.', { as: participant }, async (square, { as }, control, identity) => (await selectOwnSeat(square, identity.owner, as)).done(undefined, { observe: true }, control), rendering((result) => renderLifecycleResult(result.observation?.location ?? '', 'done', result))),
     tool('status', 'Look around the square: who is here, whether a hand is raised, the latest activity, and who you listen to.', {
         as: z.string().optional().describe('Whose listening to show. Leave it out if you hold exactly one name here.'),
-    }, (square, { as }, control) => square.status({ viewer: as, ...observation(control) }, control), rendering((result) => renderStatusResult(result.observation?.location ?? '', result))),
+    }, async (square, { as }, control, identity) => {
+        const viewer = (await selectOwnSeat(square, identity.owner, as, { optional: true }))?.name;
+        return square.status({ viewer, observe: true }, control);
+    }, rendering((result) => renderStatusResult(result.observation?.location ?? '', result))),
 ];
 export function squareToolFailure(error, signal) {
     const normalized = signal?.aborted

package/dist/stream.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import { SquareError } from './model.js';
 import { createArtifactPort, observeSquareRevision } from './artifact.js';
-import { streamProjection, streamTailProjection } from './views.js';
+import { parseRequiredActivityId, streamProjection, streamTailProjection } from './views.js';
 /** Pull-based observation; return interrupts an outstanding pull before awaiting its cleanup. */
 export function streamSquare(squarePath, options = {}, control, borrowed) {
     return {
@@ -28,7 +28,7 @@ export function streamSquare(squarePath, options = {}, control, borrowed) {
                     }
                     signal.throwIfAborted();
                     const start = options.start ?? { kind: 'tail', last: 10 };
-                    let cursor = start.kind === 'after' ? start.after : -1;
+                    let cursor = start.kind === 'after' ? parseRequiredActivityId(start.after) : -1;
                     let initial = start.kind === 'tail' ? start : undefined;
                     const observer = await observeSquareRevision(squarePath);
                     const close = () => observer.close();
@@ -60,10 +60,9 @@ export function streamSquare(squarePath, options = {}, control, borrowed) {
                                 await observer.hinted(generation, Infinity, signal);
                                 continue;
                             }
-                            for (const item of projection.activities) {
+                            for (const activity of projection.activities) {
                                 signal.throwIfAborted();
-                                yield { seq: item.activity.index, square: squarePath, ...item.activity,
-                                    ...(item.route === undefined ? {} : { route: item.route }) };
+                                yield activity;
                             }
                             cursor = projection.cursor;
                             initial = undefined;

package/dist/views.d.ts

@@ -1,13 +1,13 @@
 import { type ActivityId } from './square-core.js';
 import { type StoredAct } from './model.js';
 import type { ActivityFilter, SquareRead } from './ports.js';
-import type { Activity, ArchiveRecord, HistoryQuery, HistoryContinuation, ParticipantsResult, SquareSnapshot, EntryPresentation, ListPresentation, StatusResult, SquareObservation, CatchPresence, StreamProjection } from './square-facade.js';
-export type { EntryPresentation, ListPresentation, CatchPresence, StreamProjection } from './square-facade.js';
+import type { Activity, ArchiveRecord, PerceivedActivity, HistoryQuery, HistoryContinuation, ParticipantsResult, SquareSnapshot, EntryPresentation, StatusResult, SquareObservation, CatchPresence } 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", "hold", "resume", "listen", "ignore", "unlisten"];
 /** The one StoredAct-to-public-Activity field mapping. Rejects read and actorless acts. */
 export declare function toPublicActivity(stored: StoredAct): Activity;
+export declare function toPerceivedActivity(facts: SquareRead, stored: StoredAct, viewer: string): PerceivedActivity;
 export declare function parseRequiredActivityId(id: ActivityId): number;
 /** Compile the public query directly to typed selectors; only search hydrates unselected bodies. */
 export declare function selectHistory(facts: SquareRead, query: HistoryQuery, limit: number | null, kinds: ActivityFilter['kinds'], presentation?: boolean): {
@@ -19,20 +19,31 @@ export declare function selectHistory(facts: SquareRead, query: HistoryQuery, li
 export declare function publicActivities(activities: readonly ArchiveRecord[]): Activity[];
 export declare function snapshot(facts: SquareRead, now: number): SquareSnapshot;
 export declare function recoveryObservation(facts: SquareRead, name: string, now: number): {
-    ownActivityCount: number;
-    hardCap: import("./model.js").HardCap;
-    holdReason?: string | undefined;
     participant: string;
-    roster: string[];
     activitySummaries: import("./square-facade.js").UnreadActivitySummary[];
     standingCount: number;
     held: boolean;
+    ownActivityCount: number;
+    hardCap: import("./model.js").HardCap;
 };
 export declare function entryPresentation(facts: SquareRead, name: string, lastN?: number | null): EntryPresentation;
-type ParticipantQueryContext = Pick<SquareObservation, 'location' | 'now' | 'automaticDeliveryAvailable'>;
+type ParticipantQueryContext = Pick<SquareObservation, 'location' | 'now'>;
 export declare function queryParticipants(facts: SquareRead, context: ParticipantQueryContext, observe?: boolean): ParticipantsResult;
-export declare function listPresentation(facts: SquareRead): ListPresentation;
+export declare function listPresentation(facts: SquareRead): {
+    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 streamProjection(facts: SquareRead, cursor: number, recipient?: string): StreamProjection;
-export declare function streamTailProjection(facts: SquareRead, last?: number, recipient?: string): StreamProjection;
+export declare function streamProjection(facts: SquareRead, cursor: number, recipient?: string): {
+    activities: Activity[];
+    cursor: number;
+    hasMore: boolean;
+};
+export declare function streamTailProjection(facts: SquareRead, last?: number, recipient?: string): {
+    activities: Activity[];
+    cursor: number;
+    hasMore: boolean;
+};
+export {};

package/dist/views.js

@@ -1,7 +1,7 @@
 import { formatActivityId, parseActivityId } from './square-core.js';
 import { compareParticipantActivity, coreParticipants, resolveKnownName, unreadActivitySummaries } from './decisions.js';
 import { SquareError, nameKey } from './model.js';
-import { inSquareCount, readCursor, rosterNames } from './runtime.js';
+import { inSquareCount } from './runtime.js';
 import { perceiveActivity } from './perception-projection.js';
 import { compileSearchPattern } from './search.js';
 const PAGE_SIZE = 100;
@@ -22,6 +22,11 @@ export function toPublicActivity(stored) {
         mentions: stored.kind === 'say' ? stored.mentions ?? [] : [], ...('target' in stored ? { target: stored.target } : {}),
         ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}) };
 }
+export function toPerceivedActivity(facts, stored, viewer) {
+    const via = facts.directedAt(viewer, stored.index)?.route;
+    return { ...toPublicActivity(stored), perception: perceiveActivity(facts, stored, viewer),
+        ...(via === undefined ? {} : { via }) };
+}
 export function parseRequiredActivityId(id) {
     const index = parseActivityId(id);
     if (index === undefined)
@@ -105,12 +110,6 @@ export function selectHistory(facts, query, limit, kinds, presentation = true) {
 export function publicActivities(activities) {
     return activities.flatMap((activity) => activity.kind === 'read' || activity.actor === undefined ? [] : [toPublicActivity(activity)]);
 }
-function statuses(facts, now) {
-    return coreParticipants(facts, now).filter((p) => p.state !== 'not joined').map((p) => {
-        const cursor = readCursor(facts, p.name);
-        return { name: p.name, state: p.state === 'done' ? 'done' : 'joined', consumedThrough: cursor < 0 ? null : formatActivityId(cursor), watching: p.presence === 'watching', listening: p.listening };
-    });
-}
 export function snapshot(facts, now) {
     const header = facts.header(), hold = facts.hold();
     const names = new Map(facts.roster().map((p) => [nameKey(p.name), p.name]));
@@ -118,30 +117,31 @@ export function snapshot(facts, now) {
     return { context: [...header.preamble, ...header.warmup].join('\n'), actCount: facts.activityCount({ kinds: NON_READ }), hardCap: header.hardCap,
         ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
         held: hold.active && hold.actor !== undefined ? { by: hold.actor, ...(hold.reason === undefined ? {} : { reason: hold.reason }) } : null,
-        participants: statuses(facts, now), delivered(name, id) { return receipts.has(JSON.stringify([names.get(nameKey(name)) ?? name, parseRequiredActivityId(id)])); } };
+        participants: coreParticipants(facts, now).filter((p) => p.presence !== 'never-joined').map(({ name, presence, listening }) => ({ name, presence, listening })),
+        delivered(name, id) { return receipts.has(JSON.stringify([names.get(nameKey(name)) ?? name, parseRequiredActivityId(id)])); } };
 }
 export function recoveryObservation(facts, name, now) {
     const known = resolveKnownName(facts, name), hold = facts.hold();
-    return { participant: known, roster: rosterNames(facts), activitySummaries: unreadActivitySummaries(facts, known, now), standingCount: inSquareCount(facts), held: hold.active,
-        ...(hold.reason === undefined ? {} : { holdReason: hold.reason }), ownActivityCount: facts.participant(known).sayCount, hardCap: facts.header().hardCap };
+    return { participant: known, activitySummaries: unreadActivitySummaries(facts, known, now), standingCount: inSquareCount(facts), held: hold.active,
+        ownActivityCount: facts.participant(known).sayCount, hardCap: facts.header().hardCap };
 }
 export function entryPresentation(facts, name, lastN = HISTORY_DEFAULT_LIMIT) {
     const header = facts.header();
     const recentActivities = selectHistory(facts, {}, lastN, ['say', 'done']).activities;
     return { joinedBefore: facts.activityCount({ kinds: ['join'], actors: [name] }) > 1,
         scene: header.warmup.join('\n').trim(),
-        joinContext: (header.preamble.at(-1) === '---' ? header.preamble.slice(0, -1) : header.preamble).join('\n').trim(), recentActivities,
-        perceptions: Object.fromEntries(recentActivities.map((a) => [a.index, perceiveActivity(facts, a, name)])),
-        sayNumbers: facts.sayOrdinals(recentActivities.map((a) => a.index)) };
+        joinContext: (header.preamble.at(-1) === '---' ? header.preamble.slice(0, -1) : header.preamble).join('\n').trim(),
+        recentActivities: recentActivities.map((activity) => ({ ...toPublicActivity(activity), perception: perceiveActivity(facts, activity, name) })) };
 }
 function classifyPresence(participants, now) {
-    const here = participants.filter((participant) => participant.state === 'active' && (participant.presence === 'watching'
+    const standing = (participant) => participant.presence === 'active' || participant.presence === 'watching';
+    const here = participants.filter((participant) => standing(participant) && (participant.presence === 'watching'
         || (participant.lastActiveAt !== undefined && now - participant.lastActiveAt <= STATUS_HERE_WINDOW_MS)));
     const hereNames = new Set(here.map((participant) => participant.name));
     return { orderedHereNames: [...here.filter((participant) => participant.presence === 'watching'), ...here.filter((participant) => participant.presence !== 'watching')].map((participant) => participant.name),
-        lingeringCount: participants.filter((participant) => participant.state === 'active' && !hereNames.has(participant.name)).length,
-        classificationByName: Object.fromEntries(participants.map((participant) => [participant.name, participant.state === 'done' ? 'done'
-                : participant.state === 'not joined' ? 'not-joined' : hereNames.has(participant.name) ? 'here' : 'lingering'])) };
+        lingeringCount: participants.filter((participant) => standing(participant) && !hereNames.has(participant.name)).length,
+        classificationByName: Object.fromEntries(participants.map((participant) => [participant.name, participant.presence === 'done' ? 'done'
+                : participant.presence === 'never-joined' ? 'not-joined' : participant.presence === 'away' ? 'away' : hereNames.has(participant.name) ? 'here' : 'lingering'])) };
 }
 export function queryParticipants(facts, context, observe = false) {
     const participants = coreParticipants(facts, context.now);
@@ -158,61 +158,61 @@ export function listPresentation(facts) {
 export function queryStatus(facts, context, viewer = '', observe = false) {
     const participants = coreParticipants(facts, context.now);
     const header = facts.header(), hold = facts.hold(), standingCount = inSquareCount(facts);
-    const listener = participants.find((p) => p.state !== 'not joined' && nameKey(p.name) === nameKey(viewer));
+    const listener = participants.find((p) => p.presence !== 'never-joined' && nameKey(p.name) === nameKey(viewer));
     const latest = facts.activityHeads({ kinds: ['say', 'done'] }, { edge: 'newest', limit: 1 }).items[0];
     const latestAct = latest === undefined ? undefined : facts.activity(latest.index);
     const data = {
         hardCap: header.hardCap,
         ...(header.throttlePerMinute === undefined ? {} : { throttlePerMinute: header.throttlePerMinute }),
-        activeCount: standingCount, doneCount: participants.filter((p) => p.state === 'done').length,
-        hold: hold.active ? {
+        held: hold.active ? {
             ...(hold.actor === undefined ? {} : { by: hold.actor }),
             ...(hold.reason === undefined ? {} : { reason: hold.reason }),
             ...(hold.at === undefined ? {} : { at: hold.at }),
         } : null,
         ...(listener === undefined ? {} : { listening: listener.listening }),
-        participants: participants.filter((p) => p.state !== 'not joined'), now: context.now,
+        participants: participants.filter((p) => p.presence !== 'never-joined'), now: context.now,
         ...(latestAct === undefined || latestAct.actor === undefined || latestAct.kind === 'read' ? {} : { latestActivity: toPublicActivity(latestAct) }),
     };
     if (!observe)
         return data;
     const afterIndex = latestAct?.index ?? -1;
-    const joins = facts.activities(facts.activityHeads({ kinds: ['join'], afterIndex }, { edge: 'newest', limit: 3 }).items.map((h) => h.index)).map((activity) => ({ activity,
-        rejoined: facts.activityCount({ kinds: ['done'], actors: [activity.actor], actorMatch: 'exact', beforeIndex: activity.index }) > 0 }));
+    const joins = facts.activities(facts.activityHeads({ kinds: ['join'], afterIndex }, { edge: 'newest', limit: 3 }).items.map((h) => h.index)).map((activity) => ({
+        rejoined: facts.activityCount({ kinds: ['done'], actors: [activity.actor], actorMatch: 'exact', beforeIndex: activity.index }) > 0,
+        activity: toPublicActivity(activity)
+    }));
     const canonicalViewer = facts.participant(viewer)?.name ?? viewer;
     return {
         ...data,
         observation: {
-            ...context, ...classifyPresence(participants, context.now), standingCount, held: hold.active,
+            location: context.location,
+            ...classifyPresence(participants, context.now), standingCount,
             knownParticipantCount: participants.length, viewer: canonicalViewer,
             ...(canonicalViewer === '' ? {} : { participant: canonicalViewer }),
             joins, joinCount: facts.activityCount({ kinds: ['join'], afterIndex }),
             attentionNames: participants.filter((p) => canonicalViewer === '' || nameKey(p.name) === nameKey(canonicalViewer)).map((p) => p.name),
             ...(latestAct === undefined ? {} : { latestPerception: perceiveActivity(facts, latestAct, canonicalViewer) }),
-            ...(latestAct?.kind === 'say' ? { latestActNumber: facts.sayOrdinals([latestAct.index])[latestAct.index] } : {}),
         },
     };
 }
 export function catchPresence(facts, now) {
-    const participants = coreParticipants(facts, now).filter((participant) => participant.state === 'done' || participant.presence === 'watching'
+    const participants = coreParticipants(facts, now).filter((participant) => participant.presence === 'done' || participant.presence === 'away' || participant.presence === 'watching'
         || (participant.lastActiveAt !== undefined && now - participant.lastActiveAt <= PRESENCE_WINDOW_MS));
     return { participants, now };
 }
 export function streamProjection(facts, cursor, recipient) {
-    const page = facts.activityHeads({ afterIndex: cursor }, { edge: 'oldest', limit: PAGE_SIZE });
-    const heads = page.items.flatMap((head) => {
-        const route = recipient === undefined ? undefined : facts.directedAt(recipient, head.index)?.route;
-        return recipient !== undefined && route === undefined ? [] : [{ index: head.index, route }];
-    });
-    return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => {
-            const route = heads.find((h) => h.index === activity.index).route;
-            return { activity, ...(route === undefined ? {} : { route }) };
-        }), cursor: page.items.at(-1)?.index ?? cursor, hasMore: page.hasMore };
+    const page = facts.activityHeads({ afterIndex: cursor, kinds: NON_READ, actorRequired: true }, { edge: 'oldest', limit: PAGE_SIZE });
+    const heads = recipient === undefined ? page.items : page.items.filter((head) => facts.directedAt(recipient, head.index) !== undefined);
+    const activities = facts.activities(heads.map((head) => head.index)).map((activity) => recipient === undefined
+        ? toPublicActivity(activity) : toPerceivedActivity(facts, activity, recipient));
+    return { activities, cursor: page.items.at(-1)?.index ?? cursor, hasMore: page.hasMore };
 }
 export function streamTailProjection(facts, last = HISTORY_DEFAULT_LIMIT, recipient) {
     if (!Number.isSafeInteger(last) || last < 0 || last > PAGE_SIZE)
         throw new SquareError('invalid_args', `Invalid stream tail: expected a non-negative safe integer no greater than ${PAGE_SIZE}.`);
-    const heads = last === 0 ? [] : recipient === undefined ? facts.activityHeads({}, { edge: 'newest', limit: last }).items : facts.directed(recipient, {}, { edge: 'newest', limit: last }).items;
-    return { activities: facts.activities(heads.map((h) => h.index)).map((activity) => ({ activity,
-            ...(recipient === undefined ? {} : { route: facts.directedAt(recipient, activity.index).route }) })), cursor: facts.header().lastActIndex, hasMore: false };
+    const heads = last === 0 ? [] : recipient === undefined
+        ? facts.activityHeads({ kinds: NON_READ, actorRequired: true }, { edge: 'newest', limit: last }).items
+        : facts.directed(recipient, {}, { edge: 'newest', limit: last }).items;
+    const activities = facts.activities(heads.map((head) => head.index)).map((activity) => recipient === undefined
+        ? toPublicActivity(activity) : toPerceivedActivity(facts, activity, recipient));
+    return { activities, cursor: facts.header().lastActIndex, hasMore: false };
 }