shuadouyin 0.3.5 → 0.4.0

package/.dy-build-commit

@@ -1 +1 @@
-74b35764d458acaeeff44eaef3fe9e9a99941ac8
+7251333bbc6e84fd193536885101c3b6ebf46c86

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.4.0 — 2026-10-31
+
+### 新增
+
+- `chat recall` — 撤回自己发的一条私信。平台窗口是 3 分钟；超时后菜单里还有「撤回」但服务端会拒，所以它读响应而不是猜时间。没有二次确认，因此要 `--request-id`。
+- `chat inbox` — 谁在等我回。未读徽标不可靠（打开会话就清），所以按「最后一句是不是对方说的」判断，并把对方分享的作品 id 放进 `shared_works`。
+- `browse checkpoint` — 每批一条：走了哪条路、看到什么、每个交付条件是什么状态、下一步去哪里。进度从这些记录推导，不采信调用方的自述。
+- `browse start --text-file` — 一轮要交付什么、按什么标准判、什么时候停。写一次不能改，改条件就是换一轮。
+- `browse end --outcome` — `completed` 要求 checkpoint 真的达标，否则拒绝；`partial` 是诚实的交付。
+- `persona show` — 按段读取人格，每段带 `complete`。`context show` 从头截断，人格的「身份与声音」在后面，预算不够时会静静切掉。
+- `auth grant` / `auth revoke` / `auth grants` — 记住某个人可以做什么，带期限、每日上限和撤销记录。不是开关。
+
+### 改进
+
+- `page facts --selector` 只返回问到的标记：4440 → 618 字节。
+- `chat read` 不再复述上一条读到的消息内容：8832 → 4215 字节。
+- `comment list` 去掉每行重复的作品 id 和恒为 false 的布尔：2689 → 1849 字节。
+- `video digest` 不传 `--frames` 时按时长采样。之前两个默认值叠起来，让它从来没生效过。
+- 每个页面命令的返回会带 `persona` 字段，提醒这一轮还没读人格、读的是旧版本、或从没读过。
+- 三个预设各带一组同一事实的对照示例，说明这个声音在四种场景下怎么说话。
+
+### 修复
+
+- `chat read` 只读视口内的消息。真实群 13 条只返回 7 条，**漏掉的全是别人说的**。
+- `chat inbox` 把「新到旧」的数组当成「旧到新」，`awaiting_reply` 一直是反的。
+- 分享卡的作品 id 读不出来：`parsedContent` 是 getter，而 `own()` 故意拒绝 accessor。
+- `comment list` 和 `comment replies` 的关联信息移到结果顶层，不再每行重复。
+
+### 移除
+
+- `src/operations/actions.ts` — 提案/批准模型，从未被任何命令或模块引用。它的每日额度已由 `social goal` 和 `auth grant` 覆盖。
+
+## 0.3.5 及更早
+
+版本号在这一版之前没有随功能推进，所以更早的提交没有对应的版本记录。用 `dy update --check` 的 `commit` 字段判断新旧。

package/README.md

@@ -62,8 +62,15 @@ npm uninstall -g shuadouyin
 
 装 skill 给 agent 用（可选）：
 
+```bash
+npx skills add https://github.com/9Ashwin/ShuaDouyin --skill dy
+```
+
+或者用 CLI 自己装到 agent 目录：
+
 ```bash
 dy skill install
+dy skill status   # 已装的副本和仓库是否一致
 ```
 
 ## 开始使用
@@ -109,7 +116,15 @@ dy video info                # 读当前作品
 dy guide      # 返回完整的使用说明（约 3 万字），agent 读这个
 ```
 
-或者把 `skills/dy` 装进你的 agent 技能目录。里面按主题分成八个参考文件：浏览与成长、记忆与人格、社交、直播、日报、自我改进、命令全表，以及**平台事实**——最后一个是踩过的坑，读它能省掉一次重来。
+或者把 skill 装进你的 agent 技能目录，这样它知道什么时候该用 `dy`、怎么用：
+
+```bash
+npx skills add https://github.com/9Ashwin/ShuaDouyin --skill dy
+```
+
+`skills/dy` 里按主题分成八个参考文件：浏览与成长、记忆与人格、社交、直播、日报、自我改进、命令全表，以及**平台事实**——最后一个是踩过的坑，读它能省掉一次重来。
+
+`SKILL.md` 本身只有两百来行，是每次对话都会加载的那部分；参考文件按需读。
 
 ## 设计原则
 

package/dist/app.js

@@ -5,6 +5,7 @@ import { CliError, normalizeError } from "./errors.js";
 import { Knowledge, knowledgeOperation, validateKnowledge } from "./knowledge.js";
 import { migrateLegacyLayout } from "./migrate.js";
 import { askDouyin } from "./operations/ai-search.js";
+import { rounds } from "./operations/browsing.js";
 import { audio, capture, noteImage, noteSlide, observe } from "./operations/capture.js";
 import { captureChatImage, listChats, readChat } from "./operations/chat.js";
 import { compareChatWindows } from "./operations/chat-diff.js";
@@ -18,11 +19,13 @@ import { inspectCreator } from "./operations/creator.js";
 import { digest } from "./operations/digest.js";
 import { pageFactsRead } from "./operations/facts.js";
 import { readImage } from "./operations/image-file.js";
+import { readInbox } from "./operations/inbox.js";
 import { resolveLink } from "./operations/links.js";
 import { liveChatRead, liveGiftSend, liveGifts, liveInfo, liveSay } from "./operations/live.js";
 import { applySearchFilters, closeChatIfOpen, control, listForwardRecipients, listResults, moveFeed, navigate, openRecommendFeed, searchUsers, settleOnWork, sweepFeed, verifySearchFilters, waitSearchResults, waitSnapshot, } from "./operations/navigation.js";
 import { phraseMemories, phraseMemoryText, usePhrase } from "./operations/phrases.js";
 import { readPerson } from "./operations/read-person.js";
+import { recallMessage } from "./operations/recall.js";
 import { userRelations } from "./operations/relations.js";
 import { observeResponse } from "./operations/response-window.js";
 import { skillInstall, skillStatus } from "./operations/skill.js";
@@ -139,7 +142,7 @@ export class App {
                     const session = await this.chrome.connect(active, this.timeout, "https://live.douyin.com");
                     try {
                         const result = operation === "live.say"
-                            ? await liveSay(session, input, active)
+                            ? await liveSay(session, input, this.store, active)
                             : await liveGiftSend(session, input, this.store, active);
                         await this.store.append(operation, { request_id: input.request_id ?? null, ...result });
                         return result;
@@ -165,6 +168,18 @@ export class App {
                         timeout: this.timeout,
                     });
                 }
+                // Recalling is its own path for the same reason deleting is: it has no
+                // composer, no settlement and no confirmation, so the generic write
+                // path would fill an input that does not exist.
+                if (operation === "chat.recall") {
+                    const session = await this.chrome.connect(active, this.timeout);
+                    try {
+                        return await recallMessage(session, input, this.store, active);
+                    }
+                    finally {
+                        await session.close();
+                    }
+                }
                 if (isWrite(operation)) {
                     // A failed send used to leave no trace: only the read path recorded
                     // failures, so `diagnostics` and the repeated-failure rule in
@@ -216,6 +231,11 @@ export class App {
                     // is attached here rather than deep inside each operation so no command
                     // has to remember, and so a command added later cannot forget.
                     const setup = await setupNotice(this.store.base);
+                    // The persona note rides along the same way the setup question does.
+                    // One place attaches it, so a command added later cannot forget, and
+                    // it is advisory: a caller that has not read the persona yet must
+                    // still be able to run the command that tells it to.
+                    const persona = await personaNotice(this.store.base);
                     if (operation === "chat.read" && this.store.bot_id) {
                         if (!result || typeof result !== "object")
                             throw new CliError("state_corrupt", "Chat read did not return a conversation window");
@@ -227,9 +247,23 @@ export class App {
                             previous_context: previous,
                         };
                     }
-                    if (!["status", "auth.status"].includes(operation))
-                        await this.store.append(operation, result);
-                    return setup && result && typeof result === "object" ? { ...result, setup } : result;
+                    if (!["status", "auth.status"].includes(operation)) {
+                        // The round is resolved now, while the lock is held and the call is
+                        // starting. Reading "the open round" after the fact would attach a
+                        // long sweep to whichever round happened to be open when it ended.
+                        const open = rounds(await this.store.events()).find((round) => round.status === "open");
+                        const data = open && result && typeof result === "object"
+                            ? { ...result, _browse: { round_id: open.id, started_at: open.started_at } }
+                            : result;
+                        await this.store.append(operation, data);
+                    }
+                    const notices = {
+                        ...(setup ? { setup } : {}),
+                        ...(persona ? { persona } : {}),
+                    };
+                    return Object.keys(notices).length && result && typeof result === "object"
+                        ? { ...result, ...notices }
+                        : result;
                 }
                 catch (error) {
                     // Cancellation is the caller's choice and its outcome is not a
@@ -466,7 +500,7 @@ export class App {
                 return listForwardRecipients(session, signal);
             }
             case "page.facts":
-                return pageFactsRead(session, sourceCheckout().path ?? process.cwd());
+                return pageFactsRead(session, sourceCheckout().path ?? process.cwd(), input.target);
             case "live.info":
                 return liveInfo(session);
             case "live.chat":
@@ -604,6 +638,8 @@ export class App {
                 return { closed: await closeComments(session, signal) };
             case "chat.list":
                 return listChats(session);
+            case "chat.inbox":
+                return readInbox(session, input, signal);
             case "chat.close":
                 // Closing is a navigation step: the draft check lives on the page so
                 // an unsent message is never discarded by a caller that did not see it.
@@ -729,4 +765,47 @@ export async function setupNotice(base) {
 function publicBrowser(state) {
     return { running: true, headless: state.headless, pid: state.pid, started_at: state.started_at };
 }
+/**
+ * Whether the persona was read recently enough to be speaking from it.
+ *
+ * The skill says to read the persona before the first reply of a session, and a
+ * session has no boundary a CLI can see. What it can see is the sequence of
+ * commands: a round of work starts when the persona is read, and any page
+ * command that happens long after a read — or before the first one ever — is a
+ * caller that is probably working without it.
+ *
+ * This is a note, not a gate. Refusing a read because the persona was not loaded
+ * would break the case that matters most: a caller that has not read it yet has
+ * to be able to run the command that tells it to.
+ */
+export async function personaNotice(base) {
+    const store = new Store(base);
+    const events = await store.events();
+    const reads = events.filter((event) => event.operation === "persona.read");
+    const last = reads.at(-1);
+    const current = await new Workspaces(base).document("AGENTS.md").catch(() => null);
+    if (!current)
+        return null;
+    // A persona edited after the last read is stale evidence even if the read was
+    // a minute ago: the agent is holding an older version. This is checked before
+    // the clock, because "read recently" and "read the current file" are different
+    // facts and the second one is the one that matters.
+    const lastRevision = last?.data ? last.data.revision : undefined;
+    const revisionChanged = !!lastRevision && lastRevision !== current.revision;
+    // Half an hour is a guess at "same sitting". A session can be longer, and
+    // saying so is better than a rule that silently expires mid-task.
+    const stale = !last || Date.now() - Date.parse(last.at) > 30 * 60_000;
+    if (!stale && !revisionChanged)
+        return null;
+    return {
+        status: last ? (revisionChanged ? "changed_since_read" : "stale") : "never_read",
+        read: "Run `dy persona show` before speaking as this bot. It returns the name, voice and conduct sections with a complete flag per section.",
+        revision: current.revision,
+        why: last
+            ? revisionChanged
+                ? "The persona was edited after it was last read, so anything spoken from the earlier copy is out of date."
+                : "No persona read in this stretch of work. The bot's name and voice live in AGENTS.md, and replying without it means replying in the model's own voice."
+            : "The persona has never been read on this workspace. Without it the bot speaks as a generic assistant, and nothing in the output says the owner's setting was skipped.",
+    };
+}
 //# sourceMappingURL=app.js.map

package/dist/browser.js

@@ -306,7 +306,11 @@ export class Session {
     async call(operation, args = {}) {
         this.signal.throwIfAborted();
         adapter ??= await readFile(new URL("../dist/page-adapter.js", import.meta.url), "utf8");
-        const wire = await this.tab.evaluate(`(() => {\n${adapter}\nreturn DouyinPage.call(${JSON.stringify(operation)}, ${JSON.stringify(args)});\n})()`);
+        // The injected script is given a name so a profiler can report its coverage.
+        // Unnamed scripts arrive with an empty url, and precise coverage is only
+        // useful if the ranges can be attributed to this bundle rather than to the
+        // page's own code.
+        const wire = await this.tab.evaluate(`(() => {\n//# sourceURL=dy-page-adapter.js\n${adapter}\nreturn DouyinPage.call(${JSON.stringify(operation)}, ${JSON.stringify(args)});\n})()`);
         if (wire.error)
             throw new CliError(wire.error.code, wire.error.message, { hint: wire.error.hint });
         return wire.data;

package/dist/catalog.js

@@ -229,7 +229,7 @@ export const COMMANDS = [
                 type: "string",
             },
         ],
-        guidance: "Reports the exact phrases that read as AI, with the reason each one does, plus the markers of a text scrubbed past natural — a comma chain, five equal-length sentences, one judgement sentence after another. Both directions matter: the catalog exists because deleting every tell is its own way of reading as written by a machine. The catalog is adapted from PenguinHarness's Chinese humanizer cues. Advice, not a gate: a flagged phrase kept on purpose is still a choice, and this never rewrites the text.",
+        guidance: "Reports the exact phrases that read as AI, with the reason each one does, plus the markers of a text scrubbed past natural — a comma chain, five equal-length sentences, one judgement sentence after another. Both directions matter: the catalog exists because deleting every tell is its own way of reading as written by a machine. The catalog is adapted from PenguinHarness's Chinese humanizer cues. Advice, not a gate: a flagged phrase kept on purpose is still a choice, and this never rewrites the text. It checks general readability only — passing it does not mean the text sounds like this bot, and it says nothing about whether the facts are right or whether the account is a person. Read the persona with persona show for the first question and check the facts yourself for the second.",
         effect: "local",
     },
     {
@@ -288,6 +288,21 @@ export const COMMANDS = [
         guidance: "Replaces the retired line that told the bot to keep the owner's settings fixed and never rewrite the persona. That line contradicts the growth section in the same document, and the older, more concrete line wins, so an agent reading it is told both to grow and never to change. Only the exact retired sentence is matched; a persona whose owner has already rewritten it is left alone. Running it twice changes nothing the second time.",
         effect: "local",
     },
+    {
+        id: "persona.show",
+        description: "Read the persona a caller needs before it speaks, projected by section",
+        flags: [
+            {
+                key: "budget",
+                name: "--budget <characters>",
+                description: "Room for the persona sections",
+                type: "number",
+                default: 6000,
+            },
+        ],
+        effect: "local",
+        guidance: "Returns the name, identity and voice sections, and the growth and communication rules, each with its own complete flag. Unlike context show, the budget is spent section by section and never cuts a section in half: a section that does not fit comes back empty with complete:false, because half a voice section reads like a whole one. The revision identifies the exact file this was read from. This is the persona as written, not proof an agent followed it — a host that builds its own request can guarantee the text reaches the model, and a skill-only caller cannot.",
+    },
     {
         id: "persona.evolve",
         description: "Rewrite the persona's derived voice section from what this account actually wrote",
@@ -458,17 +473,49 @@ export const COMMANDS = [
                 default: 5,
             },
             { key: "goal", name: "--goal <id>", description: "Goal this round serves", type: "string" },
+            {
+                key: "text_file",
+                name: "--text-file <path>",
+                description: "Plan JSON: what this round delivers and how it is judged",
+                type: "string",
+            },
+            { key: "text", name: "--text <json>", description: "The same plan as an inline JSON object", type: "string" },
+        ],
+        effect: "local",
+        guidance: "A round left open by a session that died is resumed, not duplicated: two open rounds would each claim a budget and neither would be true. A plan states what this round delivers, which criteria a candidate must meet and what to do when progress stops; it is validated whole before anything is stored and cannot be changed afterwards, so a different plan needs a closed round first. Resuming with a different plan, or with a budget flag that disagrees with the open round, returns revision_conflict rather than merging the two. The budget is advisory — browse round says it is spent, and the caller decides to close.",
+    },
+    {
+        id: "browse.checkpoint",
+        description: "Record what one batch found, what it ruled out, and where it goes next",
+        argument: { key: "resource", name: "round-id", description: "Round ID from browse start" },
+        flags: [
+            { key: "text_file", name: "--text-file <path>", description: "Checkpoint JSON", type: "string" },
+            { key: "text", name: "--text <json>", description: "The same checkpoint inline", type: "string" },
+            {
+                key: "if_match",
+                name: "--if-match <revision>",
+                description: "Revision from browse round",
+                type: "string",
+            },
         ],
         effect: "local",
-        guidance: "A round left open by a session that died is resumed, not duplicated: two open rounds would each claim a budget and neither would be true. The budget is advisory — browse round says it is spent, and the caller decides to close.",
+        guidance: "One batch is written as a whole or not at all. Each criterion must be supported, not_supported or unknown, and supported or not_supported must cite an event that exists and belongs to an entity in this round; unknown is how a missing answer is recorded. A criterion the plan does not have is refused, because evidence for an unasked question is not evidence. The same checkpoint id with the same content returns the stored result; the same id with different content is idempotency_conflict. Progress is derived from these checkpoints, so a batch that repeats what an earlier one already established does not count as new. This records the caller's assessment; it cannot and does not verify whether the conclusion is true.",
     },
     {
         id: "browse.end",
         description: "Close a browsing round and keep its summary",
         argument: { key: "resource", name: "round-id", description: "Round ID from browse start" },
-        flags: [{ key: "reason", name: "--reason <text>", description: "Why the round stopped", type: "string" }],
+        flags: [
+            { key: "reason", name: "--reason <text>", description: "Why the round stopped", type: "string" },
+            {
+                key: "outcome",
+                name: "--outcome <kind>",
+                description: "completed | partial | blocked | cancelled",
+                type: "string",
+            },
+        ],
         effect: "local",
-        guidance: "Closing twice is harmless; the first close wins and the second reports already_closed.",
+        guidance: "Closing twice is harmless; the first close wins and the second reports already_closed. A round started with a plan must state an outcome, because a round with a delivery condition that ends without one turns partial into done in whatever report reads it later. completed is refused unless the checkpoints actually establish the target count; that is a consistency check on the record, not a judgement about whether the candidates are any good.",
     },
     {
         id: "browse.watch",
@@ -659,8 +706,16 @@ export const COMMANDS = [
     {
         id: "page.facts",
         description: "Compare the page's real data-e2e markers against the ones the code uses",
+        flags: [
+            {
+                key: "target",
+                name: "--selector <marker>",
+                description: "Only this marker, or a prefix ending in *",
+                type: "string",
+            },
+        ],
         effect: "read",
-        guidance: "Reports which selectors the adapter relies on that this page does not have, and which markers the page offers that nothing uses. A fixture written by hand cannot catch this: it was written from the same understanding that produced the code. Read-only.",
+        guidance: "Reports which selectors the adapter relies on that this page does not have, and which markers the page offers that nothing uses. A fixture written by hand cannot catch this: it was written from the same understanding that produced the code. A page carries about thirty-five markers and a caller usually needs one; --selector <marker> or --selector 'chat*' returns just that, and is what to use when the question is whether a control is present. Works only on the current page; opening a different one first is the caller's job. Read-only.",
     },
     {
         id: "live.info",
@@ -865,9 +920,12 @@ export const COMMANDS = [
             {
                 key: "frames",
                 name: "--frames <count>",
-                description: "Positions to sample: 0 for none, 1, or 3 (default 3); 0 skips all seeking",
+                // No default. A default of 3 overrode the duration-aware choice, so
+                // every work got three frames whether it was thirty seconds or twenty
+                // minutes — which is the thing sampling by duration exists to avoid.
+                // Omitted means "choose from the duration"; 0 means none.
+                description: "Frames to sample; omit to choose by duration, 0 for none",
                 type: "number",
-                default: 3,
             },
             { key: "limit", name: "--limit <count>", description: "Comments to read (default 8)", type: "number" },
             { key: "output", name: "--output <directory>", description: "Frame output directory", type: "string" },
@@ -1548,6 +1606,78 @@ export const COMMANDS = [
         effect: "account_write",
         guidance: "Requires --request-id. Stops on identity or draft conflicts. --mention picks one exact name from the group @ picker; an ambiguous or missing name fails instead of mentioning the wrong member. --emoji sends one sticker from the composer's smiley, on its own: combining it with --text is refused because the platform sends a sticker the moment it is clicked. The latest end of a loaded conversation is not yet verifiable, so dispatched messages return delivery_uncertain; inspect the receipt and conversation and do not automatically resend.",
     },
+    {
+        id: "auth.grant",
+        description: "Remember that one person may be written to, for a stated span",
+        flags: [
+            {
+                key: "target",
+                name: "--target <id>",
+                description: "user:<sec_uid> or conversation:<id>",
+                type: "string",
+                required: true,
+            },
+            {
+                key: "actions",
+                name: "--actions <list>",
+                description: "reply, comment, follow, like",
+                type: "string",
+                required: true,
+            },
+            { key: "days", name: "--days <count>", description: "Days until it lapses; 0 for none", type: "number" },
+            { key: "per_day", name: "--per-day <count>", description: "Most sends to this target per day", type: "number" },
+            { key: "reason", name: "--reason <text>", description: "Why this person, for the next reader", type: "string" },
+        ],
+        effect: "local",
+        guidance: "This is not a way to switch off asking. It records one target and one set of actions, with an expiry and a reason, because the alternative people actually reach for — a note saying replies are fine — cannot be reviewed or revoked. A grant for one person does not extend to a group they are in, and one for a group does not extend to its members: those are different audiences. Nothing here decides whether a message is worth sending; it only records that the person was named.",
+    },
+    {
+        id: "auth.revoke",
+        description: "Stop a standing permission",
+        flags: [
+            { key: "resource", name: "--grant-id <id>", description: "ID from auth grants", type: "string", required: true },
+        ],
+        effect: "local",
+        guidance: "Revoking does not delete the grant: what it covered already happened, and a later reader needs to know it existed and when it stopped.",
+    },
+    {
+        id: "auth.grants",
+        description: "List standing permissions and whether each is still in effect",
+        flags: [],
+        effect: "local",
+        guidance: "Shows every grant with its target, actions, expiry and whether it is active. An expired or revoked grant is still listed, because the record of what was permitted is the point.",
+    },
+    {
+        id: "chat.inbox",
+        description: "Read what arrived unread, without deciding what to reply",
+        flags: [
+            {
+                key: "limit",
+                name: "--limit <count>",
+                description: "How many unread conversations to read",
+                type: "number",
+                default: 10,
+            },
+        ],
+        effect: "read",
+        guidance: "Lists conversations with unread messages and reads them, so a caller has the content in hand to answer. It does not write a reply and does not generate one. Reading a conversation marks it read on the platform, so a second run may report less than the first — this is an observation, not a subscription. A message sharing a work reports that work's id under shared_works; read it before replying, since a reply about a work nobody watched is the failure this prevents.",
+    },
+    {
+        id: "chat.recall",
+        description: "Retract one of your own messages, inside the platform's time window",
+        flags: [
+            conversation,
+            {
+                key: "message_id",
+                name: "--message-id <id>",
+                description: "Stable ID of a message this account sent",
+                type: "string",
+                required: true,
+            },
+        ],
+        effect: "account_write",
+        guidance: "Requires --request-id. Only a message this account sent can be recalled; the page offers no recall entry on anyone else's, so the direction is checked before anything is clicked. The platform allows three minutes: past that the menu entry is still rendered but the request is refused, and this reports invalid_argument rather than guessing from the clock. There is no confirmation dialog, so a successful recall is confirmed by re-reading the conversation and finding the message gone.",
+    },
     {
         id: "chat.voice",
         description: "Ask the page to transcribe voice messages and return the text",

package/dist/knowledge.js

@@ -8,12 +8,15 @@ import { Growth } from "./growth.js";
 import { packMemories } from "./memory/context.js";
 import { Formation } from "./memory/formation.js";
 import { MemoryStore, validateMemoryInput } from "./memory.js";
-import { browsingContext, endRound, noteSkipped, noteWatched, roundSummary, rounds, startRound, } from "./operations/browsing.js";
+import { grantAccess, grants, revokeAccess } from "./operations/authorization.js";
+import { browsingContext, endRound, noteSkipped, noteWatched, recordCheckpoint, roundRevision, roundSummary, rounds, startRound, } from "./operations/browsing.js";
 import { chatHistory } from "./operations/chat-history.js";
 import { acknowledged, diagnostics, splitByFix } from "./operations/diagnostics.js";
 import { addGoal, discover, pauseGoal } from "./operations/discover.js";
 import { keepFindings } from "./operations/learn.js";
 import { evolvePersona, migratePersonaDocument, personaSection, presetOf } from "./operations/persona-evolve.js";
+import { personaSurface } from "./operations/persona-surface.js";
+import { parsePlan } from "./operations/plan.js";
 import { resetApply, resetPlan } from "./operations/reset.js";
 import { parseSources, signals } from "./operations/signals.js";
 import { closeFollowup, forgetPerson, goalUsage, outcomeSummary, pauseState, recordFollowup, recordOutcome, recordStage, setPaused, socialLog, socialView, } from "./operations/social.js";
@@ -33,6 +36,11 @@ export function knowledgeOperation(operation) {
         // persona.migrate falling through to the browser dispatcher, where the only
         // possible answer was "Unknown operation".
         operation.startsWith("persona.") ||
+        // Standing permissions are workspace state: they are recorded in the event
+        // log and never touch the page. The whole group, for the same reason the
+        // persona group is whole — one leaf listed at a time is how one falls
+        // through to the browser dispatcher and answers "Unknown operation".
+        operation.startsWith("auth.") ||
         operation.startsWith("learn.") ||
         // social.response reads the page, so it must not be claimed as local: the
         // prefix rule would have made it fall through here and report "unknown
@@ -157,14 +165,34 @@ export class Knowledge {
                     return { operation, acknowledged_at: new Date().toISOString() };
                 });
             case "browse.start":
-                return this.workspaces.lock(() => startRound(new Store(this.workspaces.base), {
-                    works: input.budget,
-                    minutes: input.minutes,
-                    idle: input.idle,
-                    goal: input.goal,
-                }));
+                return this.workspaces.lock(async () => {
+                    // The plan is validated whole before anything is stored, so a bad
+                    // field cannot leave half a round behind.
+                    const raw = input.text?.trim() || (input.text_file ? await readFile(input.text_file, "utf8") : "");
+                    const plan = raw ? parsePlan(JSON.parse(raw)) : undefined;
+                    const stated = new Set(input._stated ?? []);
+                    return startRound(new Store(this.workspaces.base), {
+                        works: input.budget,
+                        minutes: input.minutes,
+                        idle: input.idle,
+                        goal: input.goal,
+                        ...(plan ? { plan } : {}),
+                        explicit: {
+                            works: stated.has("budget"),
+                            minutes: stated.has("minutes"),
+                            idle: stated.has("idle"),
+                        },
+                    });
+                });
+            case "browse.checkpoint":
+                return this.workspaces.lock(async () => {
+                    const raw = input.text?.trim() || (input.text_file ? await readFile(input.text_file, "utf8") : "");
+                    if (!raw)
+                        throw new CliError("invalid_argument", "Supply the batch with --text-file or --text");
+                    return recordCheckpoint(new Store(this.workspaces.base), input.resource ?? "", JSON.parse(raw), input.if_match);
+                });
             case "browse.end":
-                return this.workspaces.lock(() => endRound(new Store(this.workspaces.base), input.resource ?? "", input.reason ?? ""));
+                return this.workspaces.lock(() => endRound(new Store(this.workspaces.base), input.resource ?? "", input.reason ?? "", input.outcome));
             case "browse.watch":
                 return this.workspaces.lock(() => noteWatched(new Store(this.workspaces.base), input.round ?? "", input.video_id ?? ""));
             case "browse.skip":
@@ -173,9 +201,15 @@ export class Knowledge {
                 return this.workspaces.lock(async () => {
                     const store = new Store(this.workspaces.base);
                     const events = await store.events();
-                    return input.resource
-                        ? (roundSummary(events, input.resource) ?? { round_id: input.resource, known: false })
-                        : { rounds: rounds(events).slice(-(input.limit ?? 10)) };
+                    if (!input.resource)
+                        return { rounds: rounds(events).slice(-(input.limit ?? 10)) };
+                    const summary = roundSummary(events, input.resource);
+                    if (!summary)
+                        return { round_id: input.resource, known: false };
+                    // The revision is what a checkpoint's --if-match names. It covers the
+                    // plan and every checkpoint written so far, so a batch prepared
+                    // against this view is refused if another one landed in between.
+                    return { ...summary, revision: roundRevision(events, input.resource) };
                 });
             case "context.browsing":
                 return this.workspaces.lock(async () => browsingContext(await new Store(this.workspaces.base).events(), { limit: input.limit }));
@@ -289,6 +323,23 @@ export class Knowledge {
             }
             case "learn.findings":
                 return this.workspaces.document("lessons.md");
+            case "persona.show": {
+                // Read-only and uncached: the revision returned has to be the one the
+                // text came from, or a caller has no way to tell an edit happened
+                // between reading the persona and using it.
+                const document = await this.workspaces.document("AGENTS.md");
+                const surface = personaSurface(BOT_ID, "AGENTS.md", document.revision, document.content, input.budget ?? 6000);
+                // The read is recorded. A command that runs afterwards can then tell
+                // whether the persona was picked up in this session, which is the
+                // difference between "the file is there" and "the agent has it". The
+                // record is the revision, so an edit between reading and using is
+                // visible rather than assumed away.
+                await new Store(this.workspaces.base).append("persona.read", {
+                    revision: document.revision,
+                    complete: surface.complete,
+                });
+                return surface;
+            }
             case "persona.snapshot": {
                 const document = await this.workspaces.document("AGENTS.md");
                 const version = await this.workspaces.snapshot("AGENTS.md", document.content);
@@ -320,6 +371,20 @@ export class Knowledge {
                 return new Growth(this.workspaces).acknowledge(input.event_id ?? "");
             case "growth.event":
                 return this.workspaces.lock(() => new Growth(this.workspaces).event(input.event_id ?? ""));
+            case "auth.grant":
+                return this.workspaces.lock(() => grantAccess(new Store(this.workspaces.base), {
+                    target: input.target,
+                    actions: input.actions,
+                    days: input.days,
+                    per_day: input.per_day,
+                    reason: input.reason,
+                }));
+            case "auth.revoke":
+                return this.workspaces.lock(() => revokeAccess(new Store(this.workspaces.base), input.resource ?? input.target ?? ""));
+            case "auth.grants":
+                return this.workspaces.lock(async () => ({
+                    grants: grants(await new Store(this.workspaces.base).events()),
+                }));
             case "bot.show":
                 return this.workspaces.lock(async () => ({
                     id: BOT_ID,

package/dist/main.js

@@ -94,12 +94,22 @@ export function createProgram(io, parentSignal, version = "") {
             const { app: appOptions, globals } = options(command);
             const input = { dry_run: globals.dryRun, request_id: globals.requestId };
             const local = command.opts();
+            // Which flags the caller actually typed, as opposed to the defaults the
+            // catalog fills in. Resuming a round has to tell "the caller wants thirty
+            // works" from "commander put thirty here because nothing was said", or a
+            // resumed five-minute round quietly becomes a thirty-minute one.
+            const stated = [];
             for (const flag of spec.flags ?? []) {
                 const option = new Option(flag.name);
                 const value = local[option.attributeName()];
-                if (value !== undefined)
-                    Object.assign(input, { [flag.key]: value });
+                if (value === undefined)
+                    continue;
+                Object.assign(input, { [flag.key]: value });
+                if (command.getOptionValueSource(option.attributeName()) === "cli")
+                    stated.push(flag.key);
             }
+            if (stated.length)
+                Object.assign(input, { _stated: stated });
             if (spec.argument)
                 Object.assign(input, { [spec.argument.key]: values[0] });
             const signal = AbortSignal.any([