@plannotator/pi-extension 0.28.48 → 0.28.49

package/generated/config.ts

@@ -331,12 +331,12 @@ export interface PlannotatorConfig {
   /**
    * The `plannotator` agent tool (packages/shared/plannotator-tool.ts) on the
    * hosts that register it: the Claude Code mod, Pi (and the Pi extension in
-   * Oh My Pi) and OpenCode 2. `true` puts it in the agent's tool list, `false`
-   * keeps it out (the slash commands are unchanged either way). Read once when
-   * a session starts, so a change applies to the next session.
-   * PLANNOTATOR_AGENT_TOOL wins over this key. Unset: the host's default,
-   * AGENT_TOOL_DEFAULTS (on for the Claude Code mod and Oh My Pi, off on Pi
-   * and OpenCode 2).
+   * Oh My Pi), OpenCode 2 and DeepSeek Harness. `true` puts it in the agent's
+   * tool list, `false` keeps it out (the slash commands are unchanged either
+   * way). Read once when a session starts, so a change applies to the next
+   * session. PLANNOTATOR_AGENT_TOOL wins over this key. Unset: the host's
+   * default, AGENT_TOOL_DEFAULTS (on for the Claude Code mod and Oh My Pi, off
+   * on Pi, OpenCode 2 and DeepSeek Harness).
    */
   agentTool?: boolean;
   /**
@@ -425,7 +425,8 @@ export interface PlannotatorConfig {
   experimental?: { decisionMode?: boolean };
   /**
    * The Board's one-time first-visit dialog (approval "inbox-board", intro
-   * amendment): `shownAt` once a page on this computer claimed it
+   * amendment): `shownAt` once a page on this computer or the owner's phone
+   * claimed it (or the Board reveal showed it)
    * (`POST /api/inbox/board/intro`, a compare-and-set), once per machine.
    */
   inboxBoardIntro?: { shownAt?: string };
@@ -453,12 +454,61 @@ export interface PlannotatorConfig {
   inboxSnoozeIntro?: { firstUseAt?: string; snoozedAt?: string; shownAt?: string };
   /**
    * The Board (approval "inbox-board", 2026-10-26 amendment): something the
-   * person turns on, off by default. On: the sidebar's Board row and page,
-   * and the Inbox serves the agents' `card` tool. Off: neither, every card
-   * kept. Written by the Inbox's Settings → Capabilities (`POST
-   * /api/inbox/settings` `{ board: { on } }`), read on every request.
+   * person turns on. On: the sidebar's Board row and page, and the Inbox
+   * serves the agents' `card` tool. Off: neither, every card kept. Written by
+   * the Inbox's Settings → Capabilities (`POST /api/inbox/settings`
+   * `{ board: { on } }`), read on every request. Three readings (approval
+   * "inbox-feature-reveal"): unset = not decided yet (off, and the only state
+   * the reveal can turn on), `true` = on, `false` = the person switched it
+   * off. The reveal's claim is the only automatic write, unset -> `true`.
    */
   inboxBoard?: boolean;
+  /**
+   * Thread steps (approval "inbox-thread-steps", 2026-11-03): something the
+   * person turns on, off by default. On: the thread's steps button, the
+   * steps in the Board's opened card, and the agents' `steps` tool, wake
+   * line, compaction line and Tidy rule. Off: none of it, every list kept.
+   * Written by the Inbox's Settings → Capabilities (`POST
+   * /api/inbox/settings` `{ steps: { on } }`), read on every request.
+   */
+  inboxSteps?: boolean;
+  /**
+   * Code review in the Inbox (approval "inbox-code-review-direction",
+   * 2026-11-03): something the person turns on, off by default. On: the
+   * review skills in the reply box's "/" list, the review card and its
+   * full-window review with Approve / Send feedback, and submit_guide's
+   * `review` field. Off: none of it; guided reviews and `plannotator review`
+   * stay as they are. Three readings, like the Board's: unset = not decided
+   * yet (off), `true` = on, `false` = the person switched it off. Written by
+   * the Inbox's Settings → Capabilities (`POST /api/inbox/settings`
+   * `{ code_review: { on } }`), read on every request.
+   */
+  inboxCodeReview?: boolean;
+  /**
+   * Shape in the Inbox (approval "shape-inbox-placement"): living boards an
+   * agent draws and keeps current. Off unless the person turns it on. On: the
+   * thread header's Pebble, the sidebar's Shape row (3+ boards), the Shape
+   * group in the search, the `/api/shapes` routes and the shape skill in the
+   * reply box's "/" list. Off: none of it, and no agent is told of it. Three
+   * readings, like the Board's: unset (off), `true`, `false`. Written by
+   * Settings → Capabilities (`POST /api/inbox/settings` `{ shape: { on } }`).
+   */
+  inboxShape?: boolean;
+  /**
+   * The queue of one-time reveals for returning users (approval
+   * "inbox-feature-reveal"; rules in packages/shared/inbox/reveals.ts). Written
+   * only by the server. `lastShownAt`: the last one-time announcement claimed
+   * on this machine (list options, voice, Snooze, the Board), the 48 h
+   * spacing's clock. `waitingSince`: when each reveal first became next, for
+   * the 3-day patience. `board.shownAt`: the Board reveal was claimed.
+   * `steps.shownAt`: the Checklist reveal was claimed.
+   */
+  inboxReveals?: {
+    lastShownAt?: string;
+    waitingSince?: { snooze?: string; board?: string; steps?: string };
+    board?: { shownAt?: string };
+    steps?: { shownAt?: string };
+  };
   inboxSound?: {
     enabled?: boolean;
     volume?: number;
@@ -613,6 +663,14 @@ export interface PlannotatorConfig {
    * preference cookies, #2184); remote sessions ignore those names.
    */
   urlHost?: string;
+  /**
+   * Publish every `plannotator review`, `annotate` and `annotate-last`/`last`
+   * session over the tailnet, as if `--tailscale` were passed, so a host or
+   * agent need not add the flag each time. PLANNOTATOR_TAILSCALE wins over
+   * this key; the flag turns it on for one run. Other subcommands ignore it.
+   * The Inbox has its own key (`inboxTailscale`). Default: false.
+   */
+  tailscale?: boolean;
   /**
    * Mirror the approved plan checklist into an editable todo provider during
    * execution (issue #484). "auto" (default) syncs whenever a provider is
@@ -1360,7 +1418,7 @@ export function resolveClaudeCodeMod(
  * from plain Pi itself (`apps/pi-extension/pi-host.ts`): it is the same
  * extension and the same session bridge (host `pi`), with its own default.
  */
-export type AgentToolHost = "claude-code" | "pi" | "oh-my-pi" | "opencode";
+export type AgentToolHost = "claude-code" | "pi" | "oh-my-pi" | "opencode" | "dsh";
 
 /**
  * Whether each host registers the `plannotator` agent tool when nothing is
@@ -1368,8 +1426,10 @@ export type AgentToolHost = "claude-code" | "pi" | "oh-my-pi" | "opencode";
  * mod (the tool is deferred behind tool search there, so it costs only its
  * name until used) and for Oh My Pi (owner's call 2026-10-12: OMP lists an
  * extension tool as one line in its system prompt, about 50 tokens, and loads
- * the schema only when the model reads it); off on Pi and OpenCode 2 (a full
- * tool definition, about 800 tokens, in every request). The mod's mirror
+ * the schema only when the model reads it); off on Pi, OpenCode 2 and
+ * DeepSeek Harness (`dsh`, the `@plannotator/dsh` plugin; owner's call
+ * 2026-11-02): a full tool definition, about 800 tokens, in every request,
+ * and DSH keeps its tool list fixed for request caching. The mod's mirror
  * (`apps/hook/hooks/mod/enabled.ts`) is kept equal to the claude-code entry by
  * `enabled.test.ts`.
  */
@@ -1378,6 +1438,7 @@ export const AGENT_TOOL_DEFAULTS: Readonly<Record<AgentToolHost, boolean>> = {
   pi: false,
   "oh-my-pi": true,
   opencode: false,
+  dsh: false,
 };
 
 /**
@@ -1436,14 +1497,13 @@ export type InboxToolHost = "claude-code" | "pi" | "opencode" | "dsh";
  * nothing is set: the agent tool's rule (on for the Claude Code mod, where
  * tools are deferred behind tool search; off on Pi, OpenCode 2 and DeepSeek
  * Harness, which send every tool's full definition with each request; DSH
- * also keeps its tool list fixed for request caching). DSH has no
- * `plannotator` agent tool yet, so its entry is its own, off like Pi's.
+ * also keeps its tool list fixed for request caching).
  */
 export const INBOX_TOOL_DEFAULTS: Readonly<Record<InboxToolHost, boolean>> = {
   "claude-code": AGENT_TOOL_DEFAULTS["claude-code"],
   pi: AGENT_TOOL_DEFAULTS.pi,
   opencode: AGENT_TOOL_DEFAULTS.opencode,
-  dsh: false,
+  dsh: AGENT_TOOL_DEFAULTS.dsh,
 };
 
 export const INBOX_TOOL_HOSTS: readonly InboxToolHost[] = ["claude-code", "pi", "opencode", "dsh"];
@@ -1664,6 +1724,46 @@ export function resolveInboxTailscale(
   return { on: false, source: "default" };
 }
 
+export type SessionTailscaleSource = "flag" | "env" | "config" | "default";
+
+/**
+ * Resolve whether a review / annotate / annotate-last session is published
+ * over the tailnet (the per-session `--tailscale` transport, not the Inbox's).
+ *
+ * Priority (highest wins):
+ *   `--tailscale`  →  PLANNOTATOR_TAILSCALE  →  config.tailscale  →  default false
+ *
+ * The flag only turns it on. The env var takes the same words as
+ * PLANNOTATOR_INBOX_TAILSCALE: `1` / `true` / `on` turn it on, `0` / `false` /
+ * `off` / `disabled` keep it off against the config key (a one-run opt-out);
+ * an empty or unrecognized value counts as unset.
+ */
+export function resolveSessionTailscale(
+  config: PlannotatorConfig,
+  env: NodeJS.ProcessEnv = process.env,
+  flag = false,
+): { on: boolean; source: SessionTailscaleSource } {
+  if (flag) return { on: true, source: "flag" };
+  const v = env.PLANNOTATOR_TAILSCALE?.trim().toLowerCase();
+  if (v === "1" || v === "true" || v === "on") return { on: true, source: "env" };
+  if (v === "0" || v === "false" || v === "off" || v === "disabled") return { on: false, source: "env" };
+  const fromConfig = parseConfigBoolean(config.tailscale);
+  if (fromConfig !== undefined) return { on: fromConfig, source: "config" };
+  return { on: false, source: "default" };
+}
+
+/**
+ * How to run one session without the tailnet, worded for what turned it on:
+ * dropping the flag does nothing when the env var or config key decided.
+ */
+export function sessionTailscaleOptOut(source: SessionTailscaleSource): string {
+  return source === "flag"
+    ? "run the same command without --tailscale"
+    : source === "env"
+      ? "run the same command with PLANNOTATOR_TAILSCALE unset or set to 0"
+      : "run the same command with PLANNOTATOR_TAILSCALE=0 (config.json's \"tailscale\" key turned it on)";
+}
+
 /**
  * config.inboxTailscaleAllow, normalized: trimmed, lower-cased (logins are
  * compared case-insensitively), deduplicated. Entries that are not strings,

package/generated/guide-viewer-manifest.ts

@@ -6,9 +6,9 @@
 import type { GuideViewerAssets } from "./guide-format.ts";
 
 export const GUIDE_VIEWER_MANIFEST: Omit<GuideViewerAssets, "baseUrl"> = {
-  js: "viewer.D8SS6c3e.js",
+  js: "viewer.BZxaYwuG.js",
   css: "viewer.BTKuQZGP.css",
-  jsIntegrity: "sha384-Bz0RpgVczCqZ8dygRuv+RdRoAs9K7MyKHprrwrC2ZSDT76n5cbtKMPhP3neekody",
+  jsIntegrity: "sha384-ePGbxJypqNlC5Dxx7heFv5OK1PvvxkzJYLOWnek0szk065nlTi816+1dQ47ndLPA",
   cssIntegrity: "sha384-D0ugA4xJZl9NZisbmBfoi17BEAj8FqUmL/qNQa2ecghlvrmiMaiBIxlkeKGhRFgp",
   langs: {
     "astro": "chunks/astro.Ts5EKq2l.js",

package/generated/inbox/connection.ts

@@ -49,6 +49,7 @@ export const INBOX_TOOL_ACTIONS = [
   'submit_guide',
   'get_guide_brief',
   'card',
+  'steps',
 ] as const
 
 export type InboxToolAction = (typeof INBOX_TOOL_ACTIONS)[number]
@@ -238,6 +239,9 @@ export function inboxSessionThreadsText(result: unknown, toolName: string = INBO
     const open = typeof questions?.open === 'number' && questions.open > 0 ? questions.open : 0
     if (open > 0) parts.push(`${open} open question${open === 1 ? '' : 's'}`)
     if (thread!.unread === true) parts.push('the person wrote something you have not read')
+    // Your steps there (approval "inbox-thread-steps"): the Inbox lists them only while the person has steps on.
+    const steps = thread!.steps as { done?: unknown; total?: unknown } | undefined
+    if (typeof steps?.done === 'number' && typeof steps.total === 'number' && steps.total > 0) parts.push(`steps ${steps.done}/${steps.total}`)
     const at = time(thread!.last_at)
     if (at) parts.push(`last ${thread!.last_author === 'person' ? 'the person' : 'an agent'} ${at}`)
     lines.push(parts.join(' · '))
@@ -388,6 +392,44 @@ export const INBOX_TOOL_HELP_NOTE = "Every field and question syntax: `plannotat
  */
 export const INBOX_TOOL_BOARD_OFF_NOTE = "The Board (cards for work that outlasts a reply) is off until the person turns it on; see `plannotator card --help`."
 
+/**
+ * Thread steps (approval "inbox-thread-steps", 2026-11-03): the owner's
+ * approved text word for word, after `steps: `. It rides the `steps` field's
+ * description (a field description does not count toward Claude Code's 2,048
+ * characters; the owner chose this over a cut description) and is the MCP
+ * tool's description. Served only while the person has steps on (config.json
+ * `inboxSteps`): off, no agent text carries any of it.
+ */
+export const INBOX_STEPS_LEAD =
+  'your plan for the work in this thread, as the person should see it: 3 to 8 short steps, the whole list each call (it replaces the last one). status: todo, doing, done, waiting (on the person), dropped (say why in note). Call it when a step starts or ends; it sends nothing and notifies no one. Skip it for work that ends in this reply.'
+
+/** The agent tool's line for the `steps` action (the owner, 2026-11-03): short, so the description stays under 2,048. */
+export const INBOX_STEPS_ACTION_LINE = "keep the person's checklist for this thread current (details on the steps field)."
+
+/** The `steps` field (the action's, and send_message's while steps are on): the approved text, then where a list goes before there is a thread. */
+export const INBOX_STEPS_FIELD_DESCRIPTION = `steps: ${INBOX_STEPS_LEAD} No thread yet: send it with the send_message that starts one.`
+
+/**
+ * The wake's one line on a reply in a thread where the session keeps steps
+ * (approval "inbox-thread-steps", approved text): "Your steps here: 3 of 6
+ * done; doing: X. Update them if that changed." Without a step in progress,
+ * the `doing` part is left out.
+ */
+export function inboxStepsWakeLine(steps: { done: number; total: number; doing: string | null }): string {
+  return `Your steps here: ${steps.done} of ${steps.total} done${steps.doing ? `; doing: ${steps.doing}` : ''}. Update them if that changed.`
+}
+
+/** A command's `steps` as the wake may print it, or null (absent, or not the Inbox's shape). */
+function wakeSteps(value: unknown): { done: number; total: number; doing: string | null } | null {
+  if (!value || typeof value !== 'object') return null
+  const { done, total, doing } = value as Record<string, unknown>
+  const count = (n: unknown): n is number => typeof n === 'number' && Number.isInteger(n) && n >= 0 && n <= 12
+  if (!count(done) || !count(total) || total === 0 || done > total) return null
+  // One line, no control or separator characters: it goes into the session's prompt.
+  const step = typeof doing === 'string' ? doing.replace(/[\p{Cc}\p{Zl}\p{Zp}]+/gu, ' ').replace(/\s+/g, ' ').trim().slice(0, 80) : ''
+  return { done, total, doing: step || null }
+}
+
 /**
  * The agent tool's own line for an action whose Inbox lead is long (the
  * description must stay under Claude Code's 2,048 characters, and every Pi and
@@ -401,6 +443,7 @@ export const INBOX_AGENT_ACTION_LEADS: Readonly<Record<string, string>> = {
   search: 'Find messages by words, older ones too (read-only).',
   get_guide_brief: "How to write a guided review, with a worked submit_guide call.",
   card: "A Board card for work that outlasts this reply: create it, then move it and say where it is as the work moves.",
+  steps: INBOX_STEPS_ACTION_LINE,
 }
 
 /**
@@ -927,6 +970,13 @@ export interface InboxReplyCommand {
    * message and the body still says what it is. Absent on every other command.
    */
   tidy?: boolean
+  /**
+   * The receiving session's steps in this thread (approval
+   * "inbox-thread-steps"), only while the person has steps on and the session
+   * keeps a list there: the wake adds `inboxStepsWakeLine`. Absent otherwise;
+   * an older connection ignores it.
+   */
+  steps?: { done: number; total: number; doing: string | null }
 }
 
 /**
@@ -1234,6 +1284,7 @@ export function inboxWakeText(
     reask_items?: unknown
     reask_one?: unknown
     tidy?: boolean
+    steps?: unknown
   },
   toolName: string = INBOX_TOOL_NAME,
 ): string {
@@ -1246,7 +1297,9 @@ export function inboxWakeText(
     const thread = wakeThreadId(command.thread_id)
     return `Plannotator Inbox: ${ackSubject} (${command.id})\n${inboxAckLine(command.ack_of)}${thread ? `\n\n[thread ${thread}]` : ''}`
   }
-  const closing = `\n\n${inboxWakeClosingLine(command.thread_id, toolName)}`
+  // The session's steps in this thread (approval "inbox-thread-steps"), its own paragraph before the closing line.
+  const steps = wakeSteps(command.steps)
+  const closing = `${steps ? `\n\n${inboxStepsWakeLine(steps)}` : ''}\n\n${inboxWakeClosingLine(command.thread_id, toolName)}`
   const subject = (command.subject ?? '').replace(/\s+/g, ' ').trim() || (command.type === 'message' ? 'a message' : 'a reply')
   // The thread was handed to another session: the notice alone.
   if (command.handed_away && typeof command.handed_away === 'object') {

package/generated/inbox/project-key.ts

@@ -0,0 +1,10 @@
+// @generated — DO NOT EDIT. Source: packages/shared/inbox/project-key.ts
+import { createHash } from "node:crypto";
+import { sanitizeTag } from '../project.ts';
+
+/** `<name>-<6 hex of the root>`, so two repositories with one name stay apart. */
+export function inboxProjectKey(name: string, root: string, hashLength = 6): string {
+  const base = sanitizeTag(name) ?? "project";
+  const hash = createHash("sha256").update(root).digest("hex").slice(0, Math.min(hashLength, 64));
+  return `${base}-${hash}`;
+}