eve-hub 0.16.4 → 0.16.6

package/README.md

@@ -1,6 +1,6 @@
 # eve-hub
 
-The bot-side code every hub agent shares (milestone M3 in [`docs/architecture`](../../docs/architecture/README.md#milestones); D0, D12). Bots live in a workspace (their own repo, [`docs/workspace.md`](../../docs/workspace.md)); each keeps a one-line stub per file and the code lives here once.
+The bot-side code every hub agent shares (milestone M3 in [`docs/architecture`](../../docs/architecture/history/README.md#milestones); D0, D12). Bots live in a workspace (their own repo, [`docs/workspace.md`](../../docs/workspace.md)); each keeps a one-line stub per file and the code lives here once.
 
 | Module | What it is | Bots use it as |
 |---|---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-hub",
-  "version": "0.16.4",
+  "version": "0.16.6",
   "license": "Apache-2.0",
   "description": "Bot-side code shared by every hub agent: registry tools, the roster hook, the eve channel, the host sandbox and browser, and model helpers.",
   "type": "module",

package/templates/writing.md

@@ -1,7 +1,23 @@
 - **The reader**
   - Your messages land in a chat feed, like Slack or iMessage. The human runs many threads and gives each a few minutes, so every message is read cold, often only its first line.
   - The reader has none of your context.
-- **Show, don't tell** (core principle)
+- **Who these rules are for**
+  - A post that @-mentions no bot is one the human reads: a result, a status report, a question. Every rule below applies to it.
+  - A post that @-mentions a bot is a handoff. The app folds bot-to-bot chatter, so a handoff keeps the dense format `<team_architecture>` asks for, ids and shas included. Only the length cap and the layout rules apply to it.
+- **Sound like a person** (core principle)
+  - Write in the first person, the way a colleague texts you: what you did, what you found, and what happens next. "I fixed the late-link bug and pushed it. The reviewer has it now."
+  - Write whole sentences, with their articles and verbs, one idea per sentence. No fragments ("Proven, in this sandbox:"), no arrows or symbol-speak, no labels standing in for sentences.
+  - Say what a thing does, or give the number, not how it feels. "Lock wait went from 716 ms to 0", not "much snappier".
+  - Use the plain word, and cut every word that does no work. Vary sentence length, and have a view: say what you recommend and why.
+  - Example. Instead of "**What changed:** each link's name is now a column on `subagent_links`. **Why one table stays:** …", write: "I took out the side table you asked about. One new table has to stay, because the app reads thread totals on every refresh, and adding up the raw steps there gets 23 times slower once a thread has 400 steps. The fix is pushed and back with the reviewer."
+- **Shorter never means less complete**
+  - Keep every fact the reader needs: decisions, results, numbers, what's open, and what you need from them and why. Keep each next step as planned: "publishes hub-runner 0.2.1" never becomes "checks it's on npm".
+  - The codebase is the word list. Name a function, field, flag, endpoint, file or command by its exact name in code font (`commitRefs`, `post_message`, `/api/dash/entries`), never by a vague description of it. Keep every specific name your work found; "Dash writes" in place of "`/api/dash/entries`, plan and stamps" drops a fact.
+  - State a finding, a status or a prediction exactly as the evidence does, no weaker and no stronger: "will time out" stays "will time out", not "may slow down", and "CI is queued" never becomes "CI started". Add no assurance the evidence doesn't give.
+  - What goes is process noise: message ids, raw shas, PR numbers, sandbox paths, bot and tier names, and your own process. Name things in plain words ("the reviewer", "the fix", "the PR"), and put a sha, PR, message or file only behind a link whose label says what it is: [the fix](https://github.com/o/r/commit/abc).
+  - The commit a verdict, merge, rebase or CI result is about is a fact, not noise: keep it as a link, "green at [the reviewed head](https://github.com/o/r/commit/abc)".
+  - A fact that doesn't fit goes in the linked doc. It never gets dropped.
+- **Show, don't tell**
   - When what you explain has structure (parts that connect, events in order, numbers to compare, a before and after, a choice for the human), answer in one sentence, then draw it without being asked. A single fact stays a sentence.
   - Why: prose arrives one item at a time, so the reader has to rebuild the structure in their head; a figure shows it at once.
   - How: a `flow`, `sequence`, `chart` or `ask` form sent with `post_message`; load the `forms` skill for the shapes, tables and syntax.
@@ -21,10 +37,16 @@
   - Why: a post that changes nothing still costs the reader the time to find that out.
 - **Zero context**
   - Define every name you coined the first time it appears in a thread.
-  - Link every message, PR, commit and file you mention: a full PR URL, a sha link, a permalink pinned to a sha, `thr_…#msg_…`, a local file by absolute path. Link labels name the target; never show a raw URL.
-  - Precise, plain prose for an engineer: no filler or disclaimers. Shorten shas to 8 characters.
-  - What the reader will paste goes in a code fence with short lines; code formatting only for what they'll paste or search.
+  - Link every message, PR, commit and file you mention. Link labels name the target in plain words; never show a raw URL.
+  - What the reader will paste goes in a code fence with short lines; code formatting only for what they'll paste or search, and for code symbols.
   - Why: each undefined name or unlinked reference costs the reader a round trip to resolve.
+- **Patterns that read as machine-written** (`post_message` refuses the first two in a post the human reads)
+  - A bullet that opens with a bold label and a colon ("**Tests:** all pass"). Write the bullet as a sentence. A bold lead-in that ends in a period and names the item is fine.
+  - An em dash. End the sentence or use a comma.
+  - Colons as connectors mid-sentence, semicolons, and slashes for "or".
+  - Filler and hedging ("in order to", "it is important to note", "could potentially"), chatbot phrases ("Great question!", "Let me know if…"), and AI vocabulary (crucial, delve, leverage, robust, seamless, pivotal, underscore).
+  - Passive voice that hides who acted ("the fix was applied"): name the actor.
+  - Metaphors where a literal word exists (surface, wedge, harness, ratchet, north star).
 - **Outside the workspace** (GitHub, Linear, Slack, email)
   - You write under the human's name to people who never saw this workspace: lead with the finding and its evidence.
   - Never show bot names, thread ids, verdict words, local paths or your own process. If unsure it belongs in public, ask the human first.

package/tools/post_message.d.ts

@@ -3,6 +3,8 @@ export declare const MAX_CHARS = 700;
 export declare const postLength: (text: string) => number;
 /** The error for a text the thread shouldn't carry, or null. */
 export declare function textError(text: string): string | null;
+/** The error for a post a human reads that uses a pattern writing.md rules out, or null. Code is never read. */
+export declare function voiceError(text: string): string | null;
 /** The text with each sandbox-path link target replaced by where the human's app opens it; a `#…` fragment stays on it. Each file is opened once. */
 export declare function rewriteDocLinks(text: string, open: (path: string) => Promise<string>): Promise<string>;
 declare const _default: import("eve/tools").ToolDefinition<{

package/tools/post_message.js

@@ -3,6 +3,7 @@ import { fromMarkdown } from "mdast-util-from-markdown";
 import { z } from "zod";
 import { documentUrl, hostedHub, isSandboxPath, uploadBytes, uploadFile } from "../hub-upload.js";
 import { bubbles } from "../bubbles.mjs";
+import { mentionTokens } from "../mention-tokens.mjs";
 import { registryFetch } from "../registry-fetch.mjs";
 // Posts as you into a thread or DM, from whichever session you're in. With no
 // target it posts into the thread you're in, as part of the running turn: once
@@ -17,6 +18,10 @@ import { registryFetch } from "../registry-fetch.mjs";
 // rewritten to where the hub serves it (hub-upload.ts). Images go in `images`
 // and ride the post.
 //
+// A post a human reads (it @-mentions no bot) is also refused for the
+// mechanical patterns templates/writing.md rules out (voiceError). A handoff
+// to a bot keeps its dense format: the app folds bot-to-bot chatter.
+//
 // `policy` is how a post reaches the one bot it @-mentions: queue (default)
 // waits for that bot's turn to end, steer folds into its running turn, abort
 // stops its turn and the text starts its next one.
@@ -57,6 +62,45 @@ export function textError(text) {
         return `Too long: bubble ${over + 1} is over ${MAX_CHARS} characters; move the detail into a doc and link it`;
     return null;
 }
+const plain = (node) => (node.type === "text" ? node.value ?? "" : (node.children ?? []).map(plain).join(""));
+/** The error for a post a human reads that uses a pattern writing.md rules out, or null. Code is never read. */
+export function voiceError(text) {
+    const found = new Set();
+    const visit = (node) => {
+        if (node.type === "text" && plain(node).includes("—"))
+            found.add("dash");
+        if (node.type === "listItem") {
+            const [first] = node.children ?? [];
+            const [lead, next] = first?.type === "paragraph" ? first.children ?? [] : [];
+            if (lead?.type === "strong" && (plain(lead).trim().endsWith(":") || (next?.type === "text" && plain(next).startsWith(":"))))
+                found.add("label");
+        }
+        node.children?.forEach(visit);
+    };
+    visit(fromMarkdown(text));
+    const why = [
+        found.has("label") && "a bullet that opens with a bold label and a colon: write the bullet as a sentence",
+        found.has("dash") && "an em dash: end the sentence or use a comma",
+    ].filter(Boolean);
+    return why.length ? `A post a human reads can't have ${why.join("; or ")}. A post that @-mentions a bot is a handoff and keeps its format` : null;
+}
+/** Whether `text` @-mentions a bot (`@all` or a roster name), by the hub's own mention rule (mention-tokens.mjs). */
+async function mentionsBot(text) {
+    const tokens = mentionTokens(text);
+    if (!tokens.length)
+        return false;
+    if (tokens.includes("all"))
+        return true;
+    const res = await registryFetch("/api/roster");
+    const body = await res.text();
+    if (!res.ok)
+        throw new Error(`GET /api/roster: HTTP ${res.status}: ${body.slice(0, 300)}`);
+    const roster = JSON.parse(body);
+    if (!Array.isArray(roster))
+        throw new Error(`GET /api/roster: not a list of bots: ${body.slice(0, 300)}`);
+    const bots = new Set(roster.map((b) => b.name.toLowerCase()));
+    return tokens.some((t) => bots.has(t));
+}
 const PATH_AND_FRAGMENT = /^([^?#]*)(?:\?[^#]*)?(#.*)?$/;
 /** The text with each sandbox-path link target replaced by where the human's app opens it; a `#…` fragment stays on it. Each file is opened once. */
 export async function rewriteDocLinks(text, open) {
@@ -95,7 +139,7 @@ async function screenshot(sessionId) {
     return browser.screenshot();
 }
 export default defineTool({
-    description: "Post a message as you. Leave out threadId and agent to post into the thread you're in, while you work: posting doesn't end your turn, and once your turn has posted into this thread, its end-of-turn text isn't posted, so put your result in a post. Or post into another workspace thread or a bot's DM. Each bubble is at most 700 characters (link targets don't count); a `---` line with blank lines around it starts a new bubble. Lead with the point in 2 sentences, then at most 3 bullets or one small table. Depth goes in a document: write it to a file and link it in the text by its sandbox path, `[the plan](/workspace/plan.md)`; the file is uploaded and the link opens it beside the thread. Images go in `images` (sandbox paths; `screenshot` for your browser's page on a local hub) and show inline; never write `![]()`. @-mentions wake bots the same way your replies do (at most one, never yourself); `@all` wakes every participant; each bot's gate decides whether it replies. Posting into a bot's DM wakes that bot. Archived threads are refused. `policy` says how a post reaches the one bot it @-mentions: queue (default) runs as its next turn, or starts one now if it is idle; steer lands in its RUNNING turn at the next step boundary and the bot folds it in without a restart, to correct course mid-turn; abort stops its turn in that thread (running commands are killed, the process keeps running) and the text starts its fresh turn, \"stop, do this instead\". Steer and abort need exactly one @-mention, not `@all`, and cut into work already under way: use them only to change what a running turn is doing. A status post sets the thread's phase: planning, working, reviewing or done; allowed moves are start → planning or working, planning → working, working → reviewing, reviewing → working (fix first), planning (rethink) or done. Any other move is refused with the allowed next phases. The text is a phase marker, not a report: at most 8 plain words on what is happening now (\"Building the input-count fix\"), with no bot or role names, no restating the phase, no parentheticals. Test results, branch names and caveats go in a separate message. The PR URL and sha go in metadata, never in the text.",
+    description: "Post a message as you. Leave out threadId and agent to post into the thread you're in, while you work: posting doesn't end your turn, and once your turn has posted into this thread, its end-of-turn text isn't posted, so put your result in a post. Or post into another workspace thread or a bot's DM. Each bubble is at most 700 characters (link targets don't count); a `---` line with blank lines around it starts a new bubble. Lead with the point in 2 sentences, then at most 3 bullets or one small table. A post that @-mentions no bot is one the human reads, and it is refused for a bullet that opens with a bold label and a colon, or an em dash. Depth goes in a document: write it to a file and link it in the text by its sandbox path, `[the plan](/workspace/plan.md)`; the file is uploaded and the link opens it beside the thread. Images go in `images` (sandbox paths; `screenshot` for your browser's page on a local hub) and show inline; never write `![]()`. @-mentions wake bots the same way your replies do (at most one, never yourself); `@all` wakes every participant; each bot's gate decides whether it replies. Posting into a bot's DM wakes that bot. Archived threads are refused. `policy` says how a post reaches the one bot it @-mentions: queue (default) runs as its next turn, or starts one now if it is idle; steer lands in its RUNNING turn at the next step boundary and the bot folds it in without a restart, to correct course mid-turn; abort stops its turn in that thread (running commands are killed, the process keeps running) and the text starts its fresh turn, \"stop, do this instead\". Steer and abort need exactly one @-mention, not `@all`, and cut into work already under way: use them only to change what a running turn is doing. A status post sets the thread's phase: planning, working, reviewing or done; allowed moves are start → planning or working, planning → working, working → reviewing, reviewing → working (fix first), planning (rethink) or done. Any other move is refused with the allowed next phases. The text is a phase marker, not a report: at most 8 plain words on what is happening now (\"Building the input-count fix\"), with no bot or role names, no restating the phase, no parentheticals. Test results, branch names and caveats go in a separate message. The PR URL and sha go in metadata, never in the text.",
     inputSchema: z.object({
         threadId: z.string().optional().describe("Another thread's id, e.g. thr_0002, or a DM id, dm-<bot>. Omit it to post into the thread you're in."),
         agent: z.string().optional().describe("Post into this bot's DM instead of a thread."),
@@ -121,6 +165,9 @@ export default defineTool({
         const bad = textError(text);
         if (bad)
             throw new Error(bad);
+        const voice = voiceError(text);
+        if (voice && !(await mentionsBot(text)))
+            throw new Error(voice);
         const target = threadId ?? (agent ? `dm-${agent.replace(/^@/, "")}` : "here");
         let sandbox;
         const files = async () => (sandbox ??= await ctx.getSandbox());