@astrosheep/square 0.3.14 → 0.3.16

package/dist/views.d.ts

@@ -1,7 +1,7 @@
-import { perceive, type ActivityId } from './square-core.js';
+import { type ActivityId } from './square-core.js';
 import { coreParticipants, coreStatus } from './decisions.js';
 import { type PlannedNotification } from './delivery.js';
-import { type ActivitiesOptions, type InboxNotification, type PublicAct, type RoomChangeAct, type StoredAct } from './model.js';
+import { type ActivitiesOptions, type InboxNotification, type PublicAct, type RoomChangeAct, type SquareState, type StoredAct } from './model.js';
 import type { OpenSquare } from './open-square.js';
 import type { Activity, HistoryQuery, ParticipantStatus, PerceivedActivity, SquareSnapshot } from './square-facade.js';
 export interface ActivityPresentation {
@@ -10,6 +10,7 @@ export interface ActivityPresentation {
     readonly pendingPublic: readonly PublicAct[];
     readonly pendingRoomChanges: readonly RoomChangeAct[];
     readonly activities: readonly StoredAct[];
+    readonly state: SquareState;
     readonly participantCount: number;
     readonly held: boolean;
     readonly holdReason?: string;
@@ -22,12 +23,13 @@ export interface EntryPresentation {
     readonly context: string;
     readonly joinContext: string;
     readonly recentActivities: readonly StoredAct[];
+    readonly state: SquareState;
     readonly sayNumbers: Readonly<Record<number, number>>;
     readonly participantCount: number;
 }
 export interface HistoryPresentation {
     readonly activities: readonly (StoredAct & {
-        readonly perception: ReturnType<typeof perceive>;
+        readonly perception: 'full' | 'presence';
     })[];
     readonly sayNumbers: Readonly<Record<number, number>>;
     readonly presenceAnchors: Readonly<Record<number, readonly string[]>>;
@@ -39,11 +41,13 @@ export interface ListPresentation {
     readonly activities: number;
 }
 export interface StatusPresentation {
+    readonly state: SquareState;
     readonly status: ReturnType<typeof coreStatus>;
     readonly latestActNumber?: number;
 }
 export interface WatchPresentation {
     readonly activities: readonly StoredAct[];
+    readonly state: SquareState;
     readonly participantCount: number;
     readonly presence: {
         readonly participants: ReturnType<typeof coreParticipants>;
@@ -74,6 +78,8 @@ export declare function resolveParticipant(square: OpenSquare, name: string): Pr
     readonly name: string;
     readonly roster: readonly string[];
 }>;
+export declare function currentParticipant(square: OpenSquare, name: string): Promise<string | undefined>;
+export declare function admitsBareExpress(square: OpenSquare, name: string, body: string): Promise<boolean>;
 export declare function participants(square: OpenSquare): Promise<ParticipantStatus[]>;
 export declare function snapshot(square: OpenSquare): Promise<SquareSnapshot>;
 export declare function activityPresentation(square: OpenSquare, name: string): Promise<ActivityPresentation>;

package/dist/views.js

@@ -1,16 +1,16 @@
-import { extractMentions, formatActivityId, parseActivityId, perceive } from './square-core.js';
+import { activeListeners, extractMentions, formatActivityId, parseActivityId } from './square-core.js';
 import { deliveryDelta, peerPublicActs, peerRoomChanges } from './activity-feed.js';
 import { coreActivities, coreParticipants, coreStatus, resolveKnownName } from './decisions.js';
-import { deriveDeliveryModel, isDeliveryDelivered, planActNotifications } from './delivery.js';
+import { deriveDeliveryModel, isActivitySeen, perceiveActivity, planActNotifications } from './delivery.js';
 import { SquareError, nameKey } from './model.js';
 import { countSays, currentHold, foldedState, freshWatchLease, inSquareCount, isCurrentlyJoined, readCursor, resolveRosterName, rosterNames, watchTerminalStatus } from './runtime.js';
 function expose(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) : [], ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}) };
+    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 exposePerceived(stored, viewer) {
-    const perception = perceive(stored, viewer);
+function exposePerceived(state, stored, viewer) {
+    const perception = perceiveActivity(state, stored, viewer);
     const activity = expose(stored);
     if (perception === 'full' || activity.body === undefined)
         return { ...activity, perception };
@@ -36,7 +36,7 @@ function selectHistory(stored, query) {
     return query.order === 'desc' ? selected.reverse() : selected;
 }
 function statuses(square, state) {
-    return coreStatus(state, square.clock()).participants.filter((participant) => participant.state !== 'not joined').map((participant) => ({ name: participant.name, state: participant.state === 'done' ? 'done' : 'joined', consumedThrough: readCursor(state, participant.name) < 0 ? null : formatActivityId(readCursor(state, participant.name)), watching: participant.presence === 'watching' }));
+    return coreStatus(state, square.clock()).participants.filter((participant) => participant.state !== 'not joined').map((participant) => ({ name: participant.name, state: participant.state === 'done' ? 'done' : 'joined', consumedThrough: readCursor(state, participant.name) < 0 ? null : formatActivityId(readCursor(state, participant.name)), watching: participant.presence === 'watching', listening: participant.listening }));
 }
 function anchors(state) {
     const result = {};
@@ -59,23 +59,25 @@ function sayNumbers(state) {
     return result;
 }
 export async function history(square, query = {}) { const { state } = await square.cell.read(); return selectHistory(coreActivities(state, historyOptions(query)), query).map(expose); }
-export async function participantHistory(square, name, query = {}) { const { state } = await square.cell.read(); const viewer = resolveKnownName(state, name); const effective = query.all === true || query.limit !== undefined ? query : { ...query, limit: 10 }; return selectHistory(coreActivities(state, historyOptions(effective, viewer)), effective).map((activity) => exposePerceived(activity, viewer)); }
+export async function participantHistory(square, name, query = {}) { const { state } = await square.cell.read(); const viewer = resolveKnownName(state, name); const effective = query.all === true || query.limit !== undefined ? query : { ...query, limit: 10 }; return selectHistory(coreActivities(state, historyOptions(effective, viewer)), effective).map((activity) => exposePerceived(state, activity, viewer)); }
 export async function resolveParticipant(square, name) { const { state } = await square.cell.read(); return { name: resolveKnownName(state, name), roster: rosterNames(state) }; }
+export async function currentParticipant(square, name) { const { state } = await square.cell.read(); const known = resolveRosterName(state, name); return known !== undefined && isCurrentlyJoined(state.acts, known) ? known : undefined; }
+export async function admitsBareExpress(square, name, body) { const { state } = await square.cell.read(); const actor = resolveKnownName(state, name); return extractMentions(body).length > 0 || activeListeners(foldedState(state), actor).length > 0; }
 export async function participants(square) { const { state } = await square.cell.read(); return statuses(square, state); }
-export async function snapshot(square) { const { state } = await square.cell.read(); const folded = foldedState(state); return { context: [...state.preamble, ...state.warmup].join('\n'), actCount: state.acts.filter((activity) => activity.kind !== 'read').length, hardCap: state.hardCap, ...(state.throttlePerMinute === undefined ? {} : { throttlePerMinute: state.throttlePerMinute }), held: folded.hold.active && folded.hold.actor !== undefined ? { by: folded.hold.actor, ...(folded.hold.reason === undefined ? {} : { reason: folded.hold.reason }) } : null, participants: statuses(square, state), delivered(name, id) { return isDeliveryDelivered(state, name, parseRequiredActivityId(id)); } }; }
-export async function activityPresentation(square, name) { const { state } = await square.cell.read(); const known = resolveKnownName(state, name); const delta = deliveryDelta(state, known); const hold = currentHold(state.acts); return { name: known, roster: rosterNames(state), pendingPublic: peerPublicActs(delta, known), pendingRoomChanges: peerRoomChanges(delta, known), activities: state.acts, participantCount: inSquareCount(state), held: hold.active, ...(hold.reason === undefined ? {} : { holdReason: hold.reason }), ownActivityCount: countSays(state.acts, known), hardCap: state.hardCap }; }
-export async function entryPresentation(square, name, lastN = 10) { const { state } = await square.cell.read(); const known = resolveRosterName(state, name) ?? name; const publicActivities = state.acts.filter((activity) => activity.kind === 'say' || activity.kind === 'done'); return { joined: isCurrentlyJoined(state.acts, known), scene: state.warmup.join('\n').trim(), context: state.preamble.join('\n').trim(), joinContext: (state.preamble.at(-1) === '---' ? state.preamble.slice(0, -1) : state.preamble).join('\n').trim(), recentActivities: lastN === null ? publicActivities : publicActivities.slice(-lastN), sayNumbers: sayNumbers(state), participantCount: inSquareCount(state) }; }
-export async function historyPresentation(square, options) { const { state } = await square.cell.read(); return { activities: coreActivities(state, options).map((activity) => ({ ...activity, perception: options.viewer === undefined ? 'full' : perceive(activity, options.viewer) })), sayNumbers: sayNumbers(state), presenceAnchors: anchors(state), participantCount: inSquareCount(state) }; }
+export async function snapshot(square) { const { state } = await square.cell.read(); const folded = foldedState(state); return { context: [...state.preamble, ...state.warmup].join('\n'), actCount: state.acts.filter((activity) => activity.kind !== 'read').length, hardCap: state.hardCap, ...(state.throttlePerMinute === undefined ? {} : { throttlePerMinute: state.throttlePerMinute }), held: folded.hold.active && folded.hold.actor !== undefined ? { by: folded.hold.actor, ...(folded.hold.reason === undefined ? {} : { reason: folded.hold.reason }) } : null, participants: statuses(square, state), delivered(name, id) { return isActivitySeen(state, name, parseRequiredActivityId(id)); } }; }
+export async function activityPresentation(square, name) { const { state } = await square.cell.read(); const known = resolveKnownName(state, name); const delta = deliveryDelta(state, known); const hold = currentHold(state.acts); return { name: known, roster: rosterNames(state), pendingPublic: peerPublicActs(delta, known), pendingRoomChanges: peerRoomChanges(delta, known), activities: state.acts, state, participantCount: inSquareCount(state), held: hold.active, ...(hold.reason === undefined ? {} : { holdReason: hold.reason }), ownActivityCount: countSays(state.acts, known), hardCap: state.hardCap }; }
+export async function entryPresentation(square, name, lastN = 10) { const { state } = await square.cell.read(); const known = resolveRosterName(state, name) ?? name; const publicActivities = state.acts.filter((activity) => activity.kind === 'say' || activity.kind === 'done'); return { joined: isCurrentlyJoined(state.acts, known), scene: state.warmup.join('\n').trim(), context: state.preamble.join('\n').trim(), joinContext: (state.preamble.at(-1) === '---' ? state.preamble.slice(0, -1) : state.preamble).join('\n').trim(), recentActivities: lastN === null ? publicActivities : publicActivities.slice(-lastN), state, sayNumbers: sayNumbers(state), participantCount: inSquareCount(state) }; }
+export async function historyPresentation(square, options) { const { state } = await square.cell.read(); return { activities: coreActivities(state, options).map((activity) => ({ ...activity, perception: options.viewer === undefined ? 'full' : perceiveActivity(state, activity, options.viewer) })), sayNumbers: sayNumbers(state), presenceAnchors: anchors(state), participantCount: inSquareCount(state) }; }
 export async function participantsPresentation(square) { const { state } = await square.cell.read(); return coreParticipants(state, square.clock()); }
 export async function listPresentation(square) { const { state } = await square.cell.read(); return { context: state.preamble, participants: foldedState(state).participants.filter((participant) => participant.joined).sort((left, right) => (right.lastActiveAt ?? -Infinity) - (left.lastActiveAt ?? -Infinity) || left.name.localeCompare(right.name)).map((participant) => participant.name), activities: state.acts.filter((activity) => activity.kind === 'say').length }; }
-export async function statusPresentation(square) { const { state } = await square.cell.read(); const status = coreStatus(state, square.clock()); return { status, ...(status.latestAct?.kind === 'say' ? { latestActNumber: countSays(state.acts, status.latestAct.actor) } : {}) }; }
+export async function statusPresentation(square) { const { state } = await square.cell.read(); const status = coreStatus(state, square.clock()); return { state, status, ...(status.latestAct?.kind === 'say' ? { latestActNumber: countSays(state.acts, status.latestAct.actor) } : {}) }; }
 export async function eventPresentation(square, id) { const { state } = await square.cell.read(); const activity = state.acts.find((candidate) => candidate.index === parseRequiredActivityId(id)); if (activity === undefined)
     throw new SquareError('invalid_args', `Unknown activity id: ${id}`); return { activity, participantCount: inSquareCount(state), held: currentHold(state.acts).active }; }
-export async function watchPresentation(square, name) { const { state } = await square.cell.read(); const known = resolveKnownName(state, name); const now = square.clock(); const terminal = watchTerminalStatus(state, known); return { activities: state.acts, participantCount: inSquareCount(state), presence: { participants: coreParticipants(state, now), now }, ...(terminal === undefined ? {} : { terminalStatus: terminal }) }; }
+export async function watchPresentation(square, name) { const { state } = await square.cell.read(); const known = resolveKnownName(state, name); const now = square.clock(); const terminal = watchTerminalStatus(state, known); return { activities: state.acts, state, participantCount: inSquareCount(state), presence: { participants: coreParticipants(state, now), now }, ...(terminal === undefined ? {} : { terminalStatus: terminal }) }; }
 export async function inboxProjection(square, name, ownerId) { const { state } = await square.cell.read(); const known = resolveRosterName(state, name); if (known === undefined || !isCurrentlyJoined(state.acts, known))
     return { name, joined: false, notifications: [] }; const lease = freshWatchLease(state, known, square.clock()); return { name: known, joined: true, notifications: deriveDeliveryModel(state).pendingFor(known).map(({ item, route }) => ({ actIndex: item.index, actor: item.actor, at: item.at, route, body: item.body })), ...(lease?.ownerId === ownerId ? { catchLease: lease } : {}) }; }
 export async function streamProjection(square, cursor, recipient) { const { state } = await square.cell.read(); return { activities: state.acts.filter((activity) => activity.index > cursor).flatMap((activity) => { if (recipient === undefined)
         return [{ activity }]; const notification = planActNotifications(state, activity).find((candidate) => nameKey(candidate.recipient) === nameKey(recipient)); return notification === undefined ? [] : [{ activity, route: notification.route }]; }), cursor: Math.max(cursor, ...state.acts.map((activity) => activity.index)) }; }
 export async function notificationForAct(square, actIndex) { const { state } = await square.cell.read(); const activity = state.acts.find((candidate) => candidate.index === actIndex); return activity === undefined ? [] : planActNotifications(state, activity); }
 export async function pendingDeliveries(square) { const { state } = await square.cell.read(); return [...new Set(state.acts.filter((activity) => activity.kind === 'join').map((activity) => activity.actor))].filter((name) => isCurrentlyJoined(state.acts, name)).map((recipient) => ({ recipient, notifications: deriveDeliveryModel(state).pendingFor(recipient) })); }
-export async function notificationDelivered(square, recipient, actIndex) { const { state } = await square.cell.read(); return isDeliveryDelivered(state, recipient, actIndex); }
+export async function notificationDelivered(square, recipient, actIndex) { const { state } = await square.cell.read(); return isActivitySeen(state, recipient, actIndex); }

package/dist/wake-port.d.ts

@@ -4,7 +4,10 @@ export interface WakePortHooks {
     nextAttemptN(): number;
     beforeSend(route: WakeRoute, attemptN: number): Promise<boolean>;
     record(route: WakeRoute, attemptN: number, result: Exclude<WakeDispatchResult, {
-        outcome: 'cancelled';
+        outcome: 'cancelled' | 'unavailable';
+    }>): Promise<void>;
+    invalidate?(route: WakeRoute, result: Extract<WakeDispatchResult, {
+        outcome: 'unavailable';
     }>): Promise<void>;
 }
 export type WakePortResult = {

package/dist/wake-port.js

@@ -13,6 +13,11 @@ export class WakePort {
             const result = await adapter.dispatch(route.address, payload, () => hooks.beforeSend(route, attemptN));
             if (result.outcome === 'cancelled')
                 return result;
+            if (result.outcome === 'unavailable') {
+                if (result.retainRoute !== true)
+                    await hooks.invalidate?.(route, result);
+                continue;
+            }
             await hooks.record(route, attemptN, result);
             if (result.outcome === 'accepted' || result.outcome === 'unknown')
                 return { outcome: result.outcome };

package/dist/wakes.js

@@ -1,8 +1,8 @@
 import { formatActivityId } from './square-core.js';
-import { isDeliveryDelivered } from './delivery.js';
+import { isActivitySeen } from './delivery.js';
 import { nameKey } from './model.js';
 import { resolveKnownName } from './decisions.js';
-import { WATCH_STALE_MS, currentHold, freshWatchLease, removeWatchLease, touchPresenceCursor, watchTerminalStatus, writeWatchLease } from './runtime.js';
+import { WATCH_STALE_MS, currentHold, freshWatchLease, removeWatchLease, watchTerminalStatus, writeWatchLease } from './runtime.js';
 function filter(options) {
     return { ...(options.participants === undefined ? {} : { participants: [...options.participants] }), ...(options.mention === undefined ? {} : { mention: options.mention }) };
 }
@@ -15,7 +15,6 @@ export async function acquireWatchLease(square, name, leaseId, options, ownerId)
         if (existing !== undefined && !options.replace)
             return { result: { type: 'active', lease: existing } };
         writeWatchLease(state, known, { leaseId, ...(ownerId === undefined ? {} : { ownerId }), heartbeatAt: at, expiresAt: at + WATCH_STALE_MS, ...(Object.keys(filter(options)).length === 0 ? {} : { filter: filter(options) }) });
-        touchPresenceCursor(state, known, at);
         return { state, result: { type: 'started', leaseId, replaced: existing !== undefined, heartbeatAt: at } };
     });
 }
@@ -34,7 +33,6 @@ export async function pulseWatchLease(square, name, leaseId, options, heartbeatD
         if (!heartbeatDue)
             return { result: { type: 'sleep' } };
         writeWatchLease(state, known, { leaseId, ...(lease.ownerId === undefined ? {} : { ownerId: lease.ownerId }), heartbeatAt: at, expiresAt: at + WATCH_STALE_MS, ...(Object.keys(filter(options)).length === 0 ? {} : { filter: filter(options) }) });
-        touchPresenceCursor(state, known, at);
         return { state, result: { type: 'sleep', heartbeatAt: at } };
     });
 }
@@ -47,7 +45,7 @@ export async function ownsWatchLease(square, name, leaseId) { const { state } =
 export async function claimNotificationLease(square, recipient, actIndex, leaseId, leaseMs) {
     const at = square.clock();
     const key = notificationKey(recipient, actIndex);
-    return square.cell.transact((state) => { const known = resolveKnownName(state, recipient); if (isDeliveryDelivered(state, known, actIndex))
+    return square.cell.transact((state) => { const known = resolveKnownName(state, recipient); if (isActivitySeen(state, known, actIndex))
         return { result: { type: 'delivered' } }; const existing = state.runtime.notifyLeases[key]; if (existing !== undefined && existing.expiresAt > at)
         return { result: { type: 'busy' } }; if (existing?.phase === 'dispatching')
         return { result: { type: 'ambiguous', lease: existing } }; state.runtime.notifyLeases[key] = { leaseId, expiresAt: at + leaseMs, phase: 'claimed' }; return { state, result: { type: 'acquired', leaseId } }; });

package/dist/watch.js

@@ -30,6 +30,7 @@ function watchOutputResult(squarePath, presentation, name, caught, opts = {}) {
             squarePath,
             viewer: name,
             showCatchHint: !hasAutomaticDeliveryIdentity(),
+            squareState: presentation.state,
         }),
         ...(opts.status ? { status: opts.status } : {}),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
@@ -36,15 +36,21 @@
   "author": "astrosheep",
   "license": "MIT",
   "devDependencies": {
+    "@getpaseo/client": "^0.3.1",
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^22",
     "@types/ws": "^8.18.1",
-    "typescript": "^5.8"
+    "typescript": "^5.8",
+    "ws": "^8.21.3"
   },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./paseo": {
+      "types": "./dist/paseo.d.ts",
+      "default": "./dist/paseo.js"
     }
   },
   "main": "dist/index.js",
@@ -58,8 +64,18 @@
     ]
   },
   "dependencies": {
+    "cross-spawn": "^7.0.6"
+  },
+  "peerDependencies": {
     "@getpaseo/client": "^0.3.1",
-    "cross-spawn": "^7.0.6",
     "ws": "^8.21.3"
+  },
+  "peerDependenciesMeta": {
+    "@getpaseo/client": {
+      "optional": true
+    },
+    "ws": {
+      "optional": true
+    }
   }
 }

package/skills/brainstorm/SKILL.md

@@ -7,7 +7,7 @@ allowed-tools: Bash(square *), Skill(square)
 # Square Brainstorm
 
 Use this skill when you are coordinating a brainstorm. Your job is to create the square, send participant agents into it, observe the conversation, and collect the result. Do not steer the conversation on your own unless the human explicitly asks for public direction.
-Commands default to `.square/SQUARE.square` for build and inspection. Manual participant commands require `--location <square>` or `SQUARE_LOCATION`; `--location` wins. Set `SQUARE_PARTICIPANT_NAME` for the participant name, overridden by `--as`. `.square/PUBLIC.square` is the public square and does not need a manual `join`.
+Commands that access a square require `--location <square>` or `SQUARE_LOCATION`; `--location` wins. Set `SQUARE_PARTICIPANT_NAME` for the participant name, overridden by `--as`. `.square/PUBLIC.square` is the public square and does not need a manual `join`.
 
 ## Build
 

package/skills/square/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "Native Claude Code turn-boundary delivery for Square participants",
   "author": {
     "name": "Square"

package/skills/square/SKILL.md

@@ -60,7 +60,7 @@ The ownership boundary belongs here. @bob, does this match your read?
 EOF
 ```
 
-Every activity must address someone with `@name`: the mentioned participants hear the full body, everyone else sees you walk over to them. Use `--bell` instead only when every participant needs the activity. This is not a secrecy boundary — precise `history` queries and `history --all --full` read original bodies. Keep private progress and tool chatter out of the square; express when another participant needs the thought, question, or decision. Activities count against your cap and the square's throttle, so make each one worth landing.
+Normally address the participant who needs an activity with `@name`: mentioned participants hear the full body, while everyone else sees you walk over to them. Use `--bell` only when every participant needs the activity. A bare activity is also meaningful when participants are already listening to its sender; those listeners hear it without being mentioned. The CLI asks for `--force` when a bare activity has no current listener. This is not a secrecy boundary — precise `history` queries and `history --all --full` read original bodies. Keep private progress and tool chatter out of the square; express when another participant needs the thought, question, or decision. Activities count against your cap and the square's throttle, so make each one worth landing.
 
 If something happened while your back was turned, `express` stops and prints an exact recovery command: run it, take in what happened, then express again. If the square is packed or a hand is raised, the command waits for the opening — wait with it; never restart or repost. Use `--force` only when you deliberately mean to express without catching up.