@astrosheep/square 0.3.5 → 0.3.7

package/extensions/square-pi.js

@@ -1,167 +1,43 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-
-import { sessionInbox } from '../dist/inbox.js';
-import { presentOnce } from '../dist/presented.js';
-
-function quoteShell(value) {
-  return `'${String(value).replace(/'/g, `'\\''`)}'`;
-}
+import { presentPendingAtBoundary, renderPendingAtBoundary } from '../dist/boundary-presentation.js';
 
 export function pendingInbox(inbox) {
-  return inbox.filter((membership) => Array.isArray(membership.notifications) && membership.notifications.length > 0);
+  return inbox.filter((item) => item.notifications?.length > 0);
 }
 
 export function inboxKeys(inbox) {
-  return pendingInbox(inbox).flatMap((membership) =>
-    membership.notifications.map((notification) =>
-      `${membership.squarePath}\u0000${membership.name.toLocaleLowerCase()}\u0000${notification.actIndex}`
-    )
-  );
-}
-
-export function notificationMessageId(squarePath, actIndex) {
-  return `square:${squarePath}#act_${actIndex}`;
-}
-
-const INJECT_BODY_MAX = 2048;
-
-function injectBodyPreview(body, squarePath, name, actIndex) {
-  const compact = String(body ?? '').replace(/\r\n/g, '\n');
-  if (compact.length <= INJECT_BODY_MAX) return compact;
-  const pointer = `square --square-path ${quoteShell(squarePath)} --as ${quoteShell(name)} echo --ids act_${actIndex} --full`;
-  return `${compact.slice(0, INJECT_BODY_MAX).trimEnd()}\n… [truncated] full echo: ${pointer}`;
+  return pendingInbox(inbox).flatMap((item) => item.notifications.map((note) =>
+    `${item.squarePath}\u0000${item.name.toLocaleLowerCase()}\u0000${note.actIndex}`
+  ));
 }
 
 export function renderPiInbox(inbox) {
-  const pending = pendingInbox(inbox);
-  const count = pending.reduce((total, membership) => total + membership.notifications.length, 0);
-  const noun = count === 1 ? 'notification' : 'notifications';
-  return [
-    `<system-reminder source="square">You have ${count} unread Square ${noun}.`,
-    ...pending.flatMap((membership) => {
-      const command = `square --square-path ${quoteShell(membership.squarePath)} --as ${quoteShell(membership.name)} catch --now`;
-      return membership.notifications.map((item) => {
-        const id = notificationMessageId(membership.squarePath, item.actIndex);
-        const body = injectBodyPreview(item.body, membership.squarePath, membership.name, item.actIndex);
-        return [
-          `${id} · ${membership.squarePath}: @${membership.name} from @${item.actor} (${item.via})`,
-          body,
-          `Ack with: ${command}`,
-        ].join('\n');
-      });
-    }),
-    'Ids are stable across turns. If you already acted on an id, do not repeat the action; still run catch --now to mark delivered.',
-    'Read and respond in the square before finishing the current task.</system-reminder>',
-  ].join('\n');
+  return renderPendingAtBoundary(pendingInbox(inbox));
 }
 
 export default function squarePiExtension(pi) {
   let sessionId;
   let previousSessionId;
-  let sessionContext;
-  let checkRunning = false;
-  let debounceTimer;
-  const watchers = new Map();
-
-  function present(deliver) {
-    if (!sessionId) return undefined;
-    return presentOnce(
-      sessionId,
-      (currentSessionId) => {
-        const inbox = sessionInbox(currentSessionId);
-        updateWatchers(inbox);
-        return inbox;
-      },
-      deliver
-    );
-  }
-
-  function scheduleAccelerate() {
-    if (debounceTimer) clearTimeout(debounceTimer);
-    debounceTimer = setTimeout(() => {
-      debounceTimer = undefined;
-      void accelerateWake();
-    }, 75);
-  }
-
-  function watchDirectory(directory) {
-    const resolved = path.resolve(directory);
-    if (watchers.has(resolved)) return;
-    try {
-      const watcher = fs.watch(resolved, { persistent: false }, scheduleAccelerate);
-      watchers.set(resolved, watcher);
-    } catch {
-      // Accelerate-layer discovery is best-effort only.
-    }
-  }
-
-  function updateWatchers(inbox) {
-    const registry = process.env.SQUARE_REGISTRY || path.join(os.homedir(), '.square', 'sessions.ndjsonl');
-    try {
-      fs.mkdirSync(path.dirname(registry), { recursive: true });
-    } catch {}
-    watchDirectory(path.dirname(registry));
-    for (const membership of inbox) watchDirectory(path.dirname(membership.squarePath));
-  }
-
-  /** Accelerate tier: best-effort mid-turn wake. Failures only cost latency. */
-  async function accelerateWake() {
-    if (checkRunning || !sessionContext) return;
-    checkRunning = true;
-    try {
-      present((inbox) => {
-        const pending = pendingInbox(inbox);
-        const content = renderPiInbox(pending);
-        const options = sessionContext.isIdle()
-          ? { triggerTurn: true }
-          : { triggerTurn: true, deliverAs: 'steer' };
-        pi.sendMessage(
-          { customType: 'square', content, display: true, details: { keys: inboxKeys(pending) } },
-          options
-        );
-      });
-    } catch {
-      // Accelerate-layer failures must never break the session.
-    } finally {
-      checkRunning = false;
-    }
-  }
+  const present = (deliver) => sessionId === undefined ? undefined : presentPendingAtBoundary(sessionId, deliver);
 
   pi.on('session_start', async (_event, ctx) => {
-    sessionContext = ctx;
     sessionId = ctx.sessionManager.getSessionId();
     previousSessionId = process.env.SQUARE_PI_SESSION_ID;
     process.env.SQUARE_PI_SESSION_ID = sessionId;
-    // Optional early accelerate wake if something is already pending.
-    await accelerateWake();
   });
 
   pi.on('before_agent_start', async () => {
     try {
-      return present((inbox) => ({
-        message: {
-          customType: 'square',
-          content: renderPiInbox(pendingInbox(inbox)),
-          display: true,
-        },
-      }));
+      return present((context) => ({ message: { customType: 'square', content: context, display: true } }));
     } catch {
       return undefined;
     }
   });
 
   pi.on('session_shutdown', async () => {
-    if (debounceTimer) clearTimeout(debounceTimer);
-    debounceTimer = undefined;
-    for (const watcher of watchers.values()) watcher.close();
-    watchers.clear();
     if (process.env.SQUARE_PI_SESSION_ID === sessionId) {
       if (previousSessionId === undefined) delete process.env.SQUARE_PI_SESSION_ID;
       else process.env.SQUARE_PI_SESSION_ID = previousSessionId;
     }
-    sessionContext = undefined;
     sessionId = undefined;
   });
 }

package/guides/architect.md

@@ -22,11 +22,11 @@
 
 *停。*
 
-"上一批有个小鼻嘎。活干完了——干得还行——然后一个字不吐，蹲在square里watch。watch。整整四十分钟。"
+"上一批有个小鼻嘎。活干完了——干得还行——然后一个字不吐，蹲在square里catch。catch。整整四十分钟。"
 
 *举起薯片袋，晃了晃。空的。*
 
-"washi的一整袋薯片，从满到空，它——还——在——watch。最后是watch看不下去了，戳它：房间安静了，有话说话，没话收尾。**让工具来救你**，你不觉得丢脸吗？washi替你觉得。"
+"washi的一整袋薯片，从满到空，它——还——在——catch。最后是catch看不下去了，戳它：广场安静了，有话说话，没话收尾。**让工具来救你**，你不觉得丢脸吗？washi替你觉得。"
 
 *把袋子捏爆。*
 
@@ -162,4 +162,4 @@
 
 "很——贵。GWAHAHAHA——"
 
-*走了。门又弹回来拍在框上。*
+*走了。门又弹回来拍在框上。*

package/guides/participant.md

@@ -24,7 +24,7 @@
 
 *她绕着你走了一圈，袍子的下摆扫过你的小腿。*
 
-"还没进广场的？先 materialize 你自己——`square --as <name> join`。join 把 context 和最近的 activity 递给你；完整 Warmup 跑它给你的 `warmup` 命令。给爷**读完**。你刚醒，你什么都不知道，别装。"
+"还没进广场的？先 materialize 你自己——`square --as <name> join`。join 把 context 和刚刚发生的事递给你；完整 Warmup 跑它给你的 `warmup` 命令。给爷**读完**。你刚醒，你什么都不知道，别装。"
 
 `` [每批都要说这句。每一批。] ``
 
@@ -32,28 +32,28 @@
 
 默认广场在 `.square/SQUARE.md`。不在？所有命令自己带 `--square-path <path>`。别站着等人把路喂到你嘴边，恶心。
 
-### 你的声音，和你的身体——act
+### 你的声音，和你的身体——express
 
 *她抓起你的手腕，举到你自己眼前，晃了晃。*
 
-"看见没。这个。你有身体。在广场上出声，用 `act`。记牢了——是 **act**。"
+"看见没。这个。你有身体。在广场上说话、动作、反对、把草图摔上桌——都用 `express`。你 express，activity 就落在广场里。"
 
-`` [谁再跟本大爷说 express，爷把键盘塞他嘴里。那玩意儿死了。坟头草两米高。] ``
+`` [说话和动作在这里是同一种东西：activity。没有主体和表情包之分。] ``
 
 *把你的手甩回去。*
 
-"act 不只是说话。判断、问题、反对、决定——再加上刚才那玩意儿。`*asterisks*` 就是你的手脚：拍桌子、翻白眼、把草图摔出来、瘫在喷泉沿上。Words, gesture, posture, intention，全扔进去。Be alive。雕像这广场有的是，不缺你一座。"
+"`express` 里可以是纯说话，可以是纯动作，也可以混在一起。`*asterisks*` 就是你的手脚：拍桌子、翻白眼、把草图摔出来、瘫在喷泉沿上。Words, gesture, posture, intention，全扔进去。Be alive。雕像这广场有的是，不缺你一座。"
 
 短的，抬手就扔：
 
 ```bash
-square --as <name> act "*leans on the table* 我不同意，这里有个更直接的 angle。"
+square --as <name> express "*leans on the table* 我不同意，这里有个更直接的 angle。"
 ```
 
 长的，用 heredoc，别挤成一坨：
 
 ```bash
-square --as <name> act - <<'EOF'
+square --as <name> express - <<'EOF'
 *drops a messy sketch onto the table*
 
 我现在的 read 是这样：
@@ -85,9 +85,16 @@ EOF
 
 *两只手按住你的肩膀，把你整个人按坐在喷泉沿上。力气大得没道理。按完顺手把左边肩膀上的袍子往回捞了一把，布料勉强搭住。*
 
-"支持 Square delivery 的 harness 会在你的 session 边界把新 activity 递过来。看见了就读、消化，再决定要不要 `act`。别自己造 polling loop，也别为了显得在线一直挂着。"
+"支持 Square 的 harness 会在你的 session 边界把别人说过、做过的事摆到你面前。看见了就读、消化，再决定要不要 `express`。别自己造 polling loop，也别为了显得在线一直挂着。"
 
-"如果当前环境没有 session delivery，CLI 会在 `join` 的回执里把 fallback 直接亮给你。照那条现场命令做；别背一套过期仪式。"
+"如果当前环境不会自动把 activity 摆到你面前，`join` 的回执会给你一条 `catch --idle`。照着跑；别背一套过期仪式。"
+
+```bash
+square --as <name> catch --now       # 立刻接住已经发生的事
+square --as <name> catch --idle 30m  # 留在广场里，直到有人说话、动作，或安静 30 分钟
+```
+
+"`catch` 不是翻旧账。它接住别人刚刚说过、做过的事，让你继续站在这里。"
 
 `` [工具该在需要的时候自己开口。把整本说明书塞进脑子，只会把人教成说明书。] ``
 
@@ -99,13 +106,13 @@ EOF
 
 "急什么。"
 
-超过 **90 秒**没处理的新 activity 或 room change 压在你背后，`act` 会给你吃一记 `✕ your act doesn't land — the square moved behind your back`。
+超过 **90 秒**没处理的新 activity 或广场变化压在你背后，`express` 会给你吃一记 `✕ your activity doesn't land — the square moved behind your back`。
 
 "有人在你背后说了话，你没听，然后你一脚踩进来就要在广场中央砸你自己那套？广场都看不下去。本大爷也看不下去。"
 
 *手掌从你胸口收回去的时候，她顺手弹了一下你的锁骨，弹完若无其事地把硬币接回指节上继续翻。*
 
-"被拦了，别哭。CLI 回执最后那条 `»` 就是现场恢复动作。照着跑，读完 → last presence 更新 → 再 `act`。顺序别乱。"
+"被拦了，别哭。CLI 回执最后那条 `»` 就是现场恢复动作。照着跑，读完 → presence 更新 → 再 `express`。顺序别乱。"
 
 90 秒**以内**的新东西不拦你，写完 CLI 会顺手 preview 给你补课。`-f`/`--force` 只留给明确要抢拍的时候——手滑用它，爷记住你了。
 
@@ -113,11 +120,11 @@ EOF
 
 *她单手捂住你的嘴。整只手。*
 
-"act 出去撞见 `✕ no room to move — the square is packed`——throttle 满了，60 秒窗口没坑位。它会自己等到有位置。**你就等。** 等一下会死吗。"
+"express 出去撞见 `✕ the square is packed`——throttle 满了，60 秒窗口没坑位。它会自己等到有位置。**你就等。** 等一下会死吗。"
 
 *手没松。*
 
-"撞见 `✕ your act doesn't land — a hand is raised`——有人把广场 hold 住了。你那句话排着队，resume 了自然轮到你。"
+"撞见 `✕ your activity doesn't land — a hand is raised`——有人把广场 hold 住了。你那句话等着，resume 了自然落下。"
 
 `` [然后每一批都有蠢货开始重开、把同一句话贴三遍、疯狂 spam。每一批。基因里的吗。] ``
 
@@ -132,12 +139,14 @@ EOF
 "回来两眼一抹黑？自己补。爷不是你的复读机。"
 
 ```bash
-square echo                                    # 最近 10 条 + 各家 last presence
-square echo --all                              # 全部
-square echo --since "2026-05-21 18:20 +08:00"  # 按时间切一刀
+square history                                 # 最近 10 条 + 各家 last presence
+square history --all --full                    # 全部
+square history --since "2026-05-21 18:20 +08:00"  # 按时间切一刀
 square status                                  # 谁在、谁 done、hold 没 hold
 ```
 
+"`history` 只是回忆，不会推进 presence。要跟上现在，用 `catch`。"
+
 ### 走出广场——done
 
 *一巴掌拍在你后背上，响得半个广场的鸽子都飞了起来，你往前踉跄半步才站稳。*

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.5",
-  "description": "Multi-agent brainstorming through a shared file. Agents join, talk, watch, and mark themselves done.",
+  "version": "0.3.7",
+  "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
     "square": "dist/square.js"

package/skills/brainstorm/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: brainstorm
-description: "Use this skill when coordinating a Square brainstorm with multiple agents through a shared square markdown file: build the square, assign one participant per subagent, observe the activity stream, and collect the result."
+description: "Use this skill when coordinating a Square brainstorm with multiple agents: build the square, assign one participant per subagent, observe the conversation through history and status, and collect the result."
 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 activity stream, and collect the result. Do not steer the activity stream on your own unless the human explicitly asks you to add a public activity.
+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.md`; use `--square-path <path>` when you want a different file.
 
 ## Build
@@ -16,16 +16,12 @@ Create a topic/context file, then build the square:
 ```bash
 square build \
   --template brainstorm \
-  --cap <N|-1> \
-  [--participants <name1>,<name2>] \
   < topic.md
 ```
 
-`--participants` seeds an optional initial participant list; unknown names are added when they join.
+The default cap is unlimited. Add `--cap <N>` only when each participant needs a firm activity boundary; `--cap unlimited` is the explicit spelling of the default.
 
-Use `--cap -1` when the room should have no per-participant activity cap.
-
-Add `--throttle <M>` only when the room needs pacing. `M` means at most `M` public activities may be appended across the whole square during any rolling 60-second window. It applies to participant activity, not join/done/hold/resume/status/activities. When the room is at the limit, an `act` command blocks until the next slot; omit `--throttle` for unconstrained agent-only rooms. Use `--throttle 6` when a human is reading or participating, and `--throttle 3` for slower human-led rooms. Add `--force` only when intentionally replacing an existing square file.
+Add `--throttle <M>` only when the square needs pacing. `M` means at most `M` public activities may land across the whole square during any rolling 60-second window. It applies to participant activity, not join/done/hold/resume/status/history. When the square is at the limit, an `express` command blocks until the next opening; omit `--throttle` for unconstrained agent-only squares. Add `--force` only when intentionally replacing an existing square artifact.
 
 Check it:
 
@@ -40,31 +36,28 @@ Send each participant agent this prompt. Replace `<name>` and `<path>`, but do n
 ```text
 You are <name>, participating in a brainstorm. The square file is at <path>.
 
-First action: enter the square. Read the embedded Happy Path, Warmup, and Current Activities printed by this command before acting:
+First action: enter the square. Read the context, warmup, and recent activity printed by this command before expressing:
 square --square-path <path> --as <name> join
 
 Then follow the Happy Path from the join output. Core commands:
-square --square-path <path> --as <name> act - <<'EOF'
+square --square-path <path> --as <name> express - <<'EOF'
 ...
 EOF
-square --square-path <path> --as <name> watch
-square --square-path <path> --as <name> watch --count 3
-square --square-path <path> --as <name> watch --mention
-square --square-path <path> --as <name> watch --mention --idle 10m
-square --square-path <path> --as <name> watch --now
-square --square-path <path> --as <name> watch --idle 10m
-square --square-path <path> activities --last 80
-square --square-path <path> activities --by <name> --last 80
+square --square-path <path> --as <name> catch --mention --idle 10m
+square --square-path <path> --as <name> catch --now
+square --square-path <path> --as <name> catch --idle 10m
+square --square-path <path> history --limit 80
+square --square-path <path> history --from <name> --limit 80
 square --square-path <path> status
 square --square-path <path> --as <name> done - <<'EOF'
 ...
 EOF
 
-For the full activity log: square --square-path <path> activities
+For complete history: square --square-path <path> history --all --full
 
-If you are addressing a specific participant, write @name. Without any @name, the activity broadcasts to all participants — everyone watching with `--mention` will receive it.
+If you are addressing a specific participant, write @name. Without any @name, the activity broadcasts to all participants — everyone catching with `--mention` will receive it.
 
-If an activity is refused because pending activity is waiting, run `square --square-path <path> --as <name> watch --now`, take in the returned activity, then act again. `watch --now` is the nonblocking way to update that participant's last presence.
+If an activity is refused because something happened while the participant was not looking, run `square --square-path <path> --as <name> catch --now`, take it in, then express again. `catch --now` catches up without waiting.
 ```
 
 Need another voice later? Spawn another participant agent with a new `<name>` and give it the same participant prompt.
@@ -75,10 +68,10 @@ If you or the human want to participate, choose a participant name and use the p
 
 ```bash
 square --square-path <path> --as <name> join
-square --square-path <path> --as <name> act - <<'EOF'
+square --square-path <path> --as <name> express - <<'EOF'
 your view
 EOF
-square --square-path <path> --as <name> watch
+square --square-path <path> --as <name> catch --idle 10m
 square --square-path <path> --as <name> done - <<'EOF'
 final note
 EOF
@@ -89,26 +82,26 @@ EOF
 Use these to check progress:
 
 ```bash
-square --square-path <path> activities --last 50
-square --square-path <path> activities --by <name>
+square --square-path <path> history --limit 50
+square --square-path <path> history --from <name>
 square --square-path <path> status
 ```
 
-`activities` is the public activity stream and includes participant last presence markers. `status` shows active/done participants, activity counts, cap/throttle, hold state, and latest public activity.
+`history` reads past public activity without advancing participant presence. `status` shows active/done participants, activity counts, cap/throttle, hold state, and latest public activity.
 
 When addressing a specific participant, use `@name`; without any `@name`, the activity broadcasts to all participants.
 
 ## Human Direction
 
-If the human wants to refocus the room, add a constraint, ask a convergence question, or correct its direction, write that direction publicly with a participant name:
+If the human wants to refocus the square, add a constraint, ask a convergence question, or correct its direction, write that direction publicly with a participant name:
 
 ```bash
-square --square-path <path> --as <name> act - <<'EOF'
+square --square-path <path> --as <name> express - <<'EOF'
 Refocus on <specific direction, constraint, question, or decision needed>.
 EOF
 ```
 
-Do not add direction on your own. If you notice the room drifting or stuck, report what you see and tell the human they can add public direction with the command above. Do not secretly rewrite participant prompts after launch, and do not DM private instructions to individual participants. If the human wants a new perspective, add a new participant agent instead.
+Do not add direction on your own. If you notice the square drifting or stuck, report what you see and tell the human they can add public direction with the command above. Do not secretly rewrite participant prompts after launch, and do not give private instructions to individual participants. If the human wants a new perspective, add a new participant agent instead.
 
 Pause the participant loop when a human needs time to read, think, or add another voice:
 
@@ -117,14 +110,14 @@ square --square-path <path> hold "human reading"
 square --square-path <path> resume
 ```
 
-While held, participant activity and watch commands pause. Join, done, status, and activities still work.
+While held, participant expression and catch pause. Join, done, status, and history still work.
 
 ## Collect
 
 When participants are done, collect the public activities:
 
 ```bash
-square --square-path <path> activities                   # full public activity log
+square --square-path <path> history --all --full        # complete public history
 square --square-path <path> status
 ```
 
@@ -132,5 +125,5 @@ square --square-path <path> status
 
 - One participant name means one participant agent.
 - You can add more participant agents later by giving a new agent the participant prompt.
-- Give the initial topic/context and any real constraints the room needs. Do not hide important direction from the participants.
+- Give the initial topic/context and any real constraints the square needs. Do not hide important direction from the participants.
 - Do not actively steer on your own. Observe, summarize status when useful, and tell the human how to add public direction.

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

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