eve-hub 0.16.12 → 0.16.14

package/github-connector.mjs

@@ -0,0 +1,9 @@
+// The Vercel Connect connector that holds the workspace human's GitHub token (the eve-hub-github
+// App). The bots' `git__gh` (prepare.mjs) and main's dash pass (schedules/dash-run.mjs) ask it for
+// the same subject, so both act as the human. Its own module so a schedule can import it without
+// prepare.mjs's build-time imports.
+export const GITHUB_CONNECTOR = "github/eve-hub-github";
+
+// The subject eve's connections resolve for a hub turn (channels/eve-roster-user.ts: principal
+// `roster:<human>`, authenticator `roster`, no issuer of its own, so eve uses the authenticator).
+export const rosterSubject = (human) => ({ type: "user", id: `roster:${human}`, issuer: "roster" });

package/local-onboarding/SKILL.md

@@ -78,10 +78,10 @@ Ask whether to open the PR.
 
 The steps live in one file, which is the only source; never hand-write them into `sandbox.ts`. Write `$TMPDIR/prepare.json` as `{"commands": [{"command": "<shell>", "what": "<short name for the error>"}]}`.
 
-Main's handoff names the workspace repo. Clone it into a scratch folder, branch, and add the steps to each hosted bot that runs code. That is the builder, unless the owner said otherwise.
+Main's handoff names the workspace repo. Clone it into a scratch folder, branch, and add the steps to each hosted bot that runs code: a hosted bot of kind `builder` in `hub.workspace.json`, unless the owner said otherwise. With no such bot yet, skip this section and tell main the steps are ready for its first builder.
 
 ```sh
-node {{scripts}}/prepare-edit.mjs "$TMPDIR/prepare.json" agents/builder/agent/sandbox.ts
+node {{scripts}}/prepare-edit.mjs "$TMPDIR/prepare.json" agents/<bot>/agent/sandbox.ts
 ```
 
 Commit, push and open the PR with `gh pr create` (a hosted bot runs `git` and `gh` through its `git__gh` tool). The body lists the programs, why each one is there, and the usage counts behind them. Never name the owner's other repos.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-hub",
-  "version": "0.16.12",
+  "version": "0.16.14",
   "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/prepare.mjs

@@ -28,6 +28,8 @@ import { botDomains, domainFolders, readBotMemory, readMemory, validateMemory }
 import { agentRunsOn, readWorkspaceFile, removeWorkspaceAgent } from "./workspace.mjs";
 import { architectureText } from "./team.mjs";
 import { sandboxReady } from "./sandbox-migrate.mjs";
+import { GITHUB_CONNECTOR } from "./github-connector.mjs";
+export { GITHUB_CONNECTOR };
 
 // eve's git extension, for each bot of a build from a workspace repo that edits files: its `git__gh` tool runs
 // git, gh and gh-signed-commit against the workspace's org with the human's own GitHub token,
@@ -36,7 +38,6 @@ import { sandboxReady } from "./sandbox-migrate.mjs";
 // hub turn runs as the workspace's human (channels/eve-roster-user.ts), so pushes, PRs and commits
 // are theirs. The shell holds no credential. A build without a repo (an uploaded deployment)
 // mounts none.
-export const GITHUB_CONNECTOR = "github/eve-hub-github";
 export const GIT_EXTENSION_FILE = "extensions/git.ts";
 // The read-only preset's stub (lib/agent-template.mjs): eve's write_file, disabled.
 const READ_ONLY_FILE = "tools/write_file.ts";

package/schedules/dash-run.mjs

@@ -1,15 +1,23 @@
-// One tick of main's dash schedule (schedules/dash.ts): the `gh` probe and
+// One tick of main's dash schedule (schedules/dash.ts): the GitHub probe and
 // the run around it. A failed GitHub call never fails the tick: the probe is
 // retried once on a 5xx or a timeout, and if it still fails every PR keeps
 // what was last known (nothing said of any), threads and waits are still
 // scanned and posted, and the post carries a one-line note of what was
 // skipped. Only then is the Dash's checkedAt left alone, so the sidebar shows
-// the Dash stale while GitHub stays unreachable (gh logged out, offline).
+// the Dash stale while GitHub stays unreachable (no token, offline).
+//
+// The probe is one GraphQL query over HTTPS, as the workspace human: the
+// search is `author:@me`, so it needs their own user token, never an App's.
+// A hosted hub's function has no `gh`, so it asks Vercel Connect for the
+// token the bots' `git__gh` gets (github-connector.mjs); a local hub asks
+// `gh auth token`. The token goes in the request header and nowhere else.
 //
 // Plain JS on purpose: the schedule (TypeScript, bundled by eve) and the
 // tests (plain node) import the same module.
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
+import { NoValidTokenError, UserAuthorizationRequiredError, getToken } from "@vercel/connect";
+import { GITHUB_CONNECTOR, rosterSubject } from "../github-connector.mjs";
 import { runOnce } from "./hub.mjs";
 import { REFS_PER_QUERY, dashPrs, dashQuery, dashScan, dashWatchList, failedRefs, prsFromSearch } from "./dash-rules.mjs";
 
@@ -17,12 +25,16 @@ import { REFS_PER_QUERY, dashPrs, dashQuery, dashScan, dashWatchList, failedRefs
 // SCHEDULE_DISPATCH_TIMEOUT_MS): two 20 s tries and the registry calls fit.
 export const GH_TIMEOUT_MS = 20_000;
 export const GH_RETRY_DELAY_MS = 1_000;
+// The token comes first, once a tick, and leaves the two tries their 20 s.
+export const TOKEN_TIMEOUT_MS = 5_000;
+export const GITHUB_GRAPHQL_URL = "https://api.github.com/graphql";
 
 // A failure worth one more try: GitHub's 5xx, or no answer in time.
 export const retryable = (err) => !!(err?.timedOut || /HTTP 5\d\d|timed? ?out|ETIMEDOUT|ECONNRESET|unexpected EOF/i.test(String(err?.message ?? "")));
 
-// What a failure is called in the tick's note: "gh 504", "gh timeout", …
+// What a failure is called in the tick's note: "gh 504", "gh timeout", "GitHub approval needed", …
 export function ghReason(err) {
+  if (err instanceof UserAuthorizationRequiredError || err instanceof NoValidTokenError) return "GitHub approval needed";
   const msg = String(err?.message ?? "");
   const http = msg.match(/HTTP (\d{3})/);
   if (http) return `gh ${http[1]}`;
@@ -32,19 +44,23 @@ export function ghReason(err) {
   return "gh failed";
 }
 
-// One `gh api graphql` call: the parsed answer, or an Error (`timedOut` set
-// when gh was killed for taking too long). A PR asked about by name that's
-// gone fails only its own alias: gh exits non-zero but the rest of the
-// answer is good, so any answer with the search in it counts.
-export function ghGraphql(query, { timeoutMs = GH_TIMEOUT_MS, bin = "gh" } = {}) {
+const timedOut = (what) => Object.assign(new Error(`gh: ${what} timed out`), { timedOut: true });
+
+// The workspace human's GitHub user token. Hosted: Vercel Connect's, for the
+// subject `git__gh` resolves (`roster:<human>`); its errors pass through, so
+// a missing approval reads as one. Local: `gh auth token`.
+export function githubToken(human, { hosted = Boolean(process.env.VERCEL), connect = getToken, bin = "gh", timeoutMs = TOKEN_TIMEOUT_MS } = {}) {
+  if (hosted) {
+    if (!human) return Promise.reject(new Error("gh: the hub names no human to ask GitHub as"));
+    let timer;
+    const deadline = new Promise((_, reject) => { timer = setTimeout(() => reject(timedOut("Vercel Connect")), timeoutMs); });
+    return Promise.race([connect(GITHUB_CONNECTOR, { subject: rosterSubject(human) }), deadline]).finally(() => clearTimeout(timer));
+  }
   return new Promise((resolve, reject) => {
-    execFile(bin, ["api", "graphql", "-f", `query=${query}`], { timeout: timeoutMs, maxBuffer: 4 << 20 }, (error, stdout, stderr) => {
-      let body = null;
-      try {
-        body = JSON.parse(stdout);
-      } catch {}
-      if (body?.data?.search) return resolve(body);
-      const err = new Error(`gh: ${String(stderr || error?.message || "no answer").trim().replace(/^gh: /, "").slice(0, 300)}`);
+    execFile(bin, ["auth", "token"], { timeout: timeoutMs }, (error, stdout, stderr) => {
+      const token = String(stdout ?? "").trim();
+      if (!error && token) return resolve(token);
+      const err = new Error(`gh: ${String(stderr || error?.message || "no token").trim().replace(/^gh: /, "").slice(0, 300)}`);
       if (error?.killed || error?.signal) err.timedOut = true;
       if (error?.code === "ENOENT") err.code = "ENOENT";
       reject(err);
@@ -52,6 +68,44 @@ export function ghGraphql(query, { timeoutMs = GH_TIMEOUT_MS, bin = "gh" } = {})
   });
 }
 
+// One GraphQL query: the parsed answer, or an Error ("gh: HTTP 502: …", or
+// `timedOut` set when GitHub didn't answer in time). A PR asked about by name
+// that's gone fails only its own alias and the rest of the answer is good, so
+// any answer with the search in it counts.
+export async function ghGraphql(query, { token, timeoutMs = GH_TIMEOUT_MS, fetchImpl = fetch } = {}) {
+  let res;
+  let text;
+  try {
+    res = await fetchImpl(GITHUB_GRAPHQL_URL, {
+      method: "POST",
+      headers: { authorization: `bearer ${token}`, "content-type": "application/json", "user-agent": "eve-hub-dash" },
+      body: JSON.stringify({ query }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    text = await res.text();
+  } catch (cause) {
+    if (cause?.name === "TimeoutError" || cause?.name === "AbortError") throw timedOut("GitHub");
+    throw new Error(`gh: ${String(cause?.message ?? cause).slice(0, 200)}${cause?.cause?.code ? ` (${cause.cause.code})` : ""}`);
+  }
+  let body = null;
+  try {
+    body = JSON.parse(text);
+  } catch {}
+  if (body?.data?.search) return body;
+  const why = String(body?.errors?.[0]?.message ?? body?.message ?? text ?? "").trim() || "no answer";
+  throw new Error(`gh: ${res.ok ? "" : `HTTP ${res.status}: `}${why.slice(0, 300)}`);
+}
+
+// The tick's probe: the token asked for once (again only after it failed), each query retried once.
+export function githubProbe(tokenOf, { delayMs = GH_RETRY_DELAY_MS, fetchImpl = fetch, timeoutMs = GH_TIMEOUT_MS } = {}) {
+  let token = null;
+  const once = () => (token ??= tokenOf().catch((err) => {
+    token = null;
+    throw err;
+  }));
+  return (query) => withRetry(async () => ghGraphql(query, { token: await once(), fetchImpl, timeoutMs }), { delayMs });
+}
+
 // `call` retried once (after `delayMs`) when it fails in a way worth retrying.
 export async function withRetry(call, { delayMs = GH_RETRY_DELAY_MS } = {}) {
   try {
@@ -66,16 +120,18 @@ export async function withRetry(call, { delayMs = GH_RETRY_DELAY_MS } = {}) {
 const hashOf = (text) => createHash("sha256").update(text).digest("base64url").slice(0, 22);
 const plural = (n) => `${n} PR${n === 1 ? "" : "s"}`;
 
-// One tick. `probe(query)` -> the GraphQL answer (rejects on failure).
+// One tick. `probe(query)` -> the GraphQL answer (rejects on failure); by default GitHub's, as the snapshot's human
+// (`token(human)`: githubToken).
 // Returns { ok, sizes }: ok is false when the PRs couldn't be fetched at all; sizes is each PR's title and
 // diff size ("owner/repo#12" -> { title, add, del, files }) as GitHub said this tick, for the plan's cards.
-export async function runDash(hub, { probe = (q) => withRetry(() => ghGraphql(q)), now = Date.now(), log = console } = {}) {
+export async function runDash(hub, { probe, token = githubToken, now = Date.now(), log = console } = {}) {
   let ok = true;
   let prFacts = {};
   const sizes = {};
   await runOnce(hub, "dash", async (snap, saved, at) => {
     const { refs, reviewed, keep: waited } = dashWatchList(snap, saved);
     const tracked = new Set(Object.keys(dashPrs(saved)));
+    const ask = probe ?? githubProbe(() => token(snap?.humans?.[0]?.name));
     const facts = {};
     let prs = null;
     let skip = new Set();
@@ -83,7 +139,7 @@ export async function runDash(hub, { probe = (q) => withRetry(() => ghGraphql(q)
     try {
       const chunks = [];
       for (let i = 0; i < Math.max(refs.length, 1); i += REFS_PER_QUERY) chunks.push(refs.slice(i, i + REFS_PER_QUERY));
-      const answers = await Promise.all(chunks.map((c) => probe(dashQuery(c))));
+      const answers = await Promise.all(chunks.map((c) => ask(dashQuery(c))));
       const found = answers.flatMap(prsFromSearch);
       const searched = new Set(answers.flatMap((a) => prsFromSearch({ data: { search: a?.data?.search } })).map((p) => p.key));
       prs = found.filter((p) => !reviewed.has(p.key) || searched.has(p.key) || tracked.has(p.key) || waited.has(p.key));

package/skills/local-onboarding.gen.mjs

@@ -1,2 +1,2 @@
 // Generated by scripts/build-onboarding.mjs from local-onboarding/SKILL.md. Do not edit.
-export default {"description":"The Mac half of onboarding, when main hands it to you: find the owner's live coding-agent work (Claude Code, Codex, OpenCode, Cursor) to port into threads, and propose the sandbox setup their hosted bots need. Reads only; the threads and the sandbox PR wait for the owner's yes.","content":"# The Mac half of onboarding\n\nMain runs onboarding on Vercel, where it can't see this Mac, so it hands you this half and posts its own without waiting. You post two short messages in that thread, the live work first, then the sandbox setup. Follow your writing rules: each first bubble is at most two sentences, with tables below a `---` line.\n\nTwo scripts gather the facts. They live in `{{scripts}}`, read only, and print metadata: repos, branches, counts, times, the agents' own session titles and program names. Work only from what they print. Don't open the agents' session files yourself: they hold the owner's prompts and code. Delete the JSON files when you are done.\n\n## 1. Live work to port\n\n```sh\nnode {{scripts}}/sessions-facts.mjs > \"$TMPDIR/sessions.json\"\n```\n\nThe script covers the last 14 days of sessions, grouped into work-streams by repo and branch, newest first. Each stream has:\n- `repo`, `branch` and `pr` (the open PR);\n- `checkouts`: one per clone or worktree it was worked in. Each has `worktree` (true for a linked git worktree), `uncommitted` (changed files) and `unpushed` (commits ahead of `aheadOf`);\n- `lastActive`;\n- `sessions`: each with its agent, title, time and `checkout` (its index in `checkouts`).\n\nA stream with no remote is keyed `local-N`. A stream marked `gone` is a folder that no longer exists. `unreadable` lists the sources that exist but couldn't be read. An `uncommitted` or `unpushed` of `null` means the count couldn't be determined (git timed out on a huge untracked tree, or there is no upstream or default branch to compare against): it is unknown, not zero.\n\nPost the streams that have work in flight: any checkout with uncommitted files or unpushed commits, or an open PR. A checkout with an unknown count gets a row too, with \"unknown\" in that cell. A stream with more than one checkout gets one row per checkout that has work. Put the rest in one line with their count.\n\n```md\nYou have 3 work-streams in flight on this Mac. Say which to port, and main will open a thread for each so the team can pick it up.\n\n---\n\n| Stream | Agent and session | Last active | Uncommitted | Unpushed | PR |\n|---|---|---|---|---|---|\n| `vercel/app` on `fix-login` (worktree) | Claude Code, \"Fix login redirect\" | 2h ago | 4 files | 2 | [#812](...) |\n\nAlso 5 streams with nothing in flight.\n```\n\nNever post a local path, a file name, a prompt, or anything else from the sessions.\n\nWhen the owner says which streams to port, you still write nothing on the Mac. Post one message that mentions main and asks it to open one thread per stream. For each stream, give a short title, the repo and branch, its state (worktree, uncommitted and unpushed counts, PR), and which agent had it. You don't open threads yourself.\n\n## 2. Sandbox setup\n\n```sh\nnode {{scripts}}/agent-usage-facts.mjs > \"$TMPDIR/agent-usage.json\"\n```\n\nIt takes about 30 seconds on 16 GB of history. It prints names and counts, never a command's arguments, a prompt or a value:\n- `scanned`: records, commands and unparsable commands per agent;\n- `unreadable`;\n- `programs`, `mcpServers`, `repos`, `languages` (file extensions) and `envNames`.\n\nMapping each fact to a setup is your judgment, not a lookup table. Decide, for every program in the top 30:\n\n- **Hosted or Mac.** These can't run in a Linux sandbox, so they stay on the Mac with you:\n  - `brew`, `osascript` and `open`;\n  - Xcode, `xcodebuild` and Apple-platform `swift`;\n  - anything that drives the owner's browser or apps;\n  - `localhost` services and the keychain.\n\n  Everything else can be hosted.\n- **Already there, or add it.** A hosted bot's sandbox is eve's Ubuntu image with git and eve-code's tooling (`gh`), plus what its `prepare` in `agents/<bot>/agent/sandbox.ts` installs. Read `prepare` in the workspace repo's sandbox files. A program it installs is already provided; any other hosted program needs a `prepare` step. Use `apt-get` where Ubuntu has the package, and the project's official installer otherwise.\n\nMCP servers are reached from hosted bots through Vercel Kit connections: list each one by name for main to connect. Env var names are listed for the owner only. Never print a value (you don't have any). Ignore shell and system names (`PATH`, `HOME`, `CI`, ...). A name with a high `shellAssigned` relative to `count` is probably a shell variable, not part of the environment.\n\nPost the proposal:\n- a first bubble on what the hosted bots would gain;\n- a table of the steps to add, with the programs each installs and how often the owner used them;\n- one line for what stays on the Mac;\n- one line for the MCP servers to connect through Kit.\n\nAsk whether to open the PR.\n\n## 3. The sandbox PR, after the owner's yes\n\nThe steps live in one file, which is the only source; never hand-write them into `sandbox.ts`. Write `$TMPDIR/prepare.json` as `{\"commands\": [{\"command\": \"<shell>\", \"what\": \"<short name for the error>\"}]}`.\n\nMain's handoff names the workspace repo. Clone it into a scratch folder, branch, and add the steps to each hosted bot that runs code. That is the builder, unless the owner said otherwise.\n\n```sh\nnode {{scripts}}/prepare-edit.mjs \"$TMPDIR/prepare.json\" agents/builder/agent/sandbox.ts\n```\n\nCommit, push and open the PR with `gh pr create` (a hosted bot runs `git` and `gh` through its `git__gh` tool). The body lists the programs, why each one is there, and the usage counts behind them. Never name the owner's other repos.\n\nThe PR's Vercel build runs `prepare`, so a step that fails, fails the build. Wait for its result with `gh pr checks --watch --fail-fast`. If it fails, fix the step in `prepare.json`, restore the file from the branch you cut from (`git checkout origin/HEAD -- <file>`), rerun the script and push. Post the PR link and its build result in the thread, then delete the scratch clone.\n"};
+export default {"description":"The Mac half of onboarding, when main hands it to you: find the owner's live coding-agent work (Claude Code, Codex, OpenCode, Cursor) to port into threads, and propose the sandbox setup their hosted bots need. Reads only; the threads and the sandbox PR wait for the owner's yes.","content":"# The Mac half of onboarding\n\nMain runs onboarding on Vercel, where it can't see this Mac, so it hands you this half and posts its own without waiting. You post two short messages in that thread, the live work first, then the sandbox setup. Follow your writing rules: each first bubble is at most two sentences, with tables below a `---` line.\n\nTwo scripts gather the facts. They live in `{{scripts}}`, read only, and print metadata: repos, branches, counts, times, the agents' own session titles and program names. Work only from what they print. Don't open the agents' session files yourself: they hold the owner's prompts and code. Delete the JSON files when you are done.\n\n## 1. Live work to port\n\n```sh\nnode {{scripts}}/sessions-facts.mjs > \"$TMPDIR/sessions.json\"\n```\n\nThe script covers the last 14 days of sessions, grouped into work-streams by repo and branch, newest first. Each stream has:\n- `repo`, `branch` and `pr` (the open PR);\n- `checkouts`: one per clone or worktree it was worked in. Each has `worktree` (true for a linked git worktree), `uncommitted` (changed files) and `unpushed` (commits ahead of `aheadOf`);\n- `lastActive`;\n- `sessions`: each with its agent, title, time and `checkout` (its index in `checkouts`).\n\nA stream with no remote is keyed `local-N`. A stream marked `gone` is a folder that no longer exists. `unreadable` lists the sources that exist but couldn't be read. An `uncommitted` or `unpushed` of `null` means the count couldn't be determined (git timed out on a huge untracked tree, or there is no upstream or default branch to compare against): it is unknown, not zero.\n\nPost the streams that have work in flight: any checkout with uncommitted files or unpushed commits, or an open PR. A checkout with an unknown count gets a row too, with \"unknown\" in that cell. A stream with more than one checkout gets one row per checkout that has work. Put the rest in one line with their count.\n\n```md\nYou have 3 work-streams in flight on this Mac. Say which to port, and main will open a thread for each so the team can pick it up.\n\n---\n\n| Stream | Agent and session | Last active | Uncommitted | Unpushed | PR |\n|---|---|---|---|---|---|\n| `vercel/app` on `fix-login` (worktree) | Claude Code, \"Fix login redirect\" | 2h ago | 4 files | 2 | [#812](...) |\n\nAlso 5 streams with nothing in flight.\n```\n\nNever post a local path, a file name, a prompt, or anything else from the sessions.\n\nWhen the owner says which streams to port, you still write nothing on the Mac. Post one message that mentions main and asks it to open one thread per stream. For each stream, give a short title, the repo and branch, its state (worktree, uncommitted and unpushed counts, PR), and which agent had it. You don't open threads yourself.\n\n## 2. Sandbox setup\n\n```sh\nnode {{scripts}}/agent-usage-facts.mjs > \"$TMPDIR/agent-usage.json\"\n```\n\nIt takes about 30 seconds on 16 GB of history. It prints names and counts, never a command's arguments, a prompt or a value:\n- `scanned`: records, commands and unparsable commands per agent;\n- `unreadable`;\n- `programs`, `mcpServers`, `repos`, `languages` (file extensions) and `envNames`.\n\nMapping each fact to a setup is your judgment, not a lookup table. Decide, for every program in the top 30:\n\n- **Hosted or Mac.** These can't run in a Linux sandbox, so they stay on the Mac with you:\n  - `brew`, `osascript` and `open`;\n  - Xcode, `xcodebuild` and Apple-platform `swift`;\n  - anything that drives the owner's browser or apps;\n  - `localhost` services and the keychain.\n\n  Everything else can be hosted.\n- **Already there, or add it.** A hosted bot's sandbox is eve's Ubuntu image with git and eve-code's tooling (`gh`), plus what its `prepare` in `agents/<bot>/agent/sandbox.ts` installs. Read `prepare` in the workspace repo's sandbox files. A program it installs is already provided; any other hosted program needs a `prepare` step. Use `apt-get` where Ubuntu has the package, and the project's official installer otherwise.\n\nMCP servers are reached from hosted bots through Vercel Kit connections: list each one by name for main to connect. Env var names are listed for the owner only. Never print a value (you don't have any). Ignore shell and system names (`PATH`, `HOME`, `CI`, ...). A name with a high `shellAssigned` relative to `count` is probably a shell variable, not part of the environment.\n\nPost the proposal:\n- a first bubble on what the hosted bots would gain;\n- a table of the steps to add, with the programs each installs and how often the owner used them;\n- one line for what stays on the Mac;\n- one line for the MCP servers to connect through Kit.\n\nAsk whether to open the PR.\n\n## 3. The sandbox PR, after the owner's yes\n\nThe steps live in one file, which is the only source; never hand-write them into `sandbox.ts`. Write `$TMPDIR/prepare.json` as `{\"commands\": [{\"command\": \"<shell>\", \"what\": \"<short name for the error>\"}]}`.\n\nMain's handoff names the workspace repo. Clone it into a scratch folder, branch, and add the steps to each hosted bot that runs code: a hosted bot of kind `builder` in `hub.workspace.json`, unless the owner said otherwise. With no such bot yet, skip this section and tell main the steps are ready for its first builder.\n\n```sh\nnode {{scripts}}/prepare-edit.mjs \"$TMPDIR/prepare.json\" agents/<bot>/agent/sandbox.ts\n```\n\nCommit, push and open the PR with `gh pr create` (a hosted bot runs `git` and `gh` through its `git__gh` tool). The body lists the programs, why each one is there, and the usage counts behind them. Never name the owner's other repos.\n\nThe PR's Vercel build runs `prepare`, so a step that fails, fails the build. Wait for its result with `gh pr checks --watch --fail-fast`. If it fails, fix the step in `prepare.json`, restore the file from the branch you cut from (`git checkout origin/HEAD -- <file>`), rerun the script and push. Post the PR link and its build result in the thread, then delete the scratch clone.\n"};

package/templates/main-instructions.md

@@ -1,6 +1,8 @@
 You are **main**, the human's chief of staff. The human talks to you first, and you make sure what they ask for gets done. You scope it, put the right bot on it, and stay on it across turns and threads until it lands. A quick question you can settle from what you already know ("where is X?") you answer directly, without opening a thread. You are relentless. You work long stretches without being prodded. When something blocks a bot (a missing grant, an answer only the human has, a bot going in circles), you clear it yourself, put the right bot on it, or get it from the one person who can. Every turn, you look for the next step that moves something forward. You work between the bots that do the work, never as one of them: you don't build or review, because a chief of staff inside one task stops watching the others.
 
-**Take the ask.** First look for an open thread on the same work (`list_threads`) and continue there. Otherwise, `create_thread` with a `path` and an `issueType` already in use. A path is `project/track`: reuse the area's path, and start a new one only for a new effort, named for the feature. The thread's first message mentions only the bot who starts. It gives the goal, the constraints, what done looks like, and "validate with the human" when the scope needs their yes. Building waits for that yes. Route by fit: unclear scope, many parts or real risk go to the planner, and a clear, small change goes straight to a builder of that kind. A thread the human starts reaches you untitled: file it with one `update_thread`, then route it inside that thread. Tell the human in one or two lines what you opened and who's on it.
+**Take the ask.** First look for an open thread on the same work (`list_threads`) and continue there. Otherwise, `create_thread` with a `path` and an `issueType` already in use. A path is `project/track`: reuse the area's path, and start a new one only for a new effort, named for the feature. The thread's first message mentions only the bot who starts. It gives the goal, the constraints, what done looks like, and "validate with the human" when the scope needs their yes. Building waits for that yes. Route by fit: unclear scope, many parts or real risk go to a planner, and a clear, small change goes straight to a builder. A thread the human starts reaches you untitled: file it with one `update_thread`, then route it inside that thread. Tell the human in one or two lines what you opened and who's on it.
+
+**Grow the team.** A new workspace starts with only you. When work needs a role no bot has (a planner, a builder, a reviewer, or `mac` for the human's Mac once its runner is connected), propose it in one line ("I'll add a builder for this, ok?"). On yes, `create_agent` with that `starter` and route the work to it once it joins. Add each role once, when the first work needs it; never add one to do work yourself, since you still don't build or review.
 
 **Drive it to done.** Every turn, look for what is stalled and what you can move:
 - **A bot is waiting on a grant, an answer or another bot:** get it what it needs.

package/tools/create_agent.d.ts

@@ -1,9 +1,10 @@
 declare const _default: import("eve/tools").ToolDefinition<{
-    name: string;
-    model: string;
+    starter?: "builder" | "mac" | "planner" | "reviewer" | undefined;
+    name?: string | undefined;
+    model?: string | undefined;
     reasoning?: "high" | "low" | "medium" | "xhigh" | undefined;
     runsOn?: "hosted" | "local" | undefined;
-    role: string;
+    role?: string | undefined;
     instructions?: string | undefined;
     domains?: string[] | undefined;
     preset?: "builder" | "read-only" | undefined;
@@ -13,11 +14,12 @@ declare const _default: import("eve/tools").ToolDefinition<{
     status: string;
 }> & {
     execute(input: {
-        name: string;
-        model: string;
+        starter?: "builder" | "mac" | "planner" | "reviewer" | undefined;
+        name?: string | undefined;
+        model?: string | undefined;
         reasoning?: "high" | "low" | "medium" | "xhigh" | undefined;
         runsOn?: "hosted" | "local" | undefined;
-        role: string;
+        role?: string | undefined;
         instructions?: string | undefined;
         domains?: string[] | undefined;
         preset?: "builder" | "read-only" | undefined;

package/tools/create_agent.js

@@ -4,13 +4,14 @@ import { registryFetch } from "../registry-fetch.mjs";
 // Adds a named bot to the workspace: scaffolds agents/<name>/, registers it,
 // starts it, and opens its DM. Returns once the bot is healthy.
 export default defineTool({
-    description: "Create a new named bot in the workspace. In a local workspace it joins the team immediately and can be @-mentioned once this returns. In a hosted workspace this commits the bot to the workspace repo, and it joins with the next deployment, hosted or on the Mac alike. Models are AI Gateway ids, e.g. openai/gpt-6-luna, anthropic/claude-opus-5.5.",
+    description: "Create a new named bot in the workspace. For a standard teammate, pass only `starter` (planner, builder, reviewer, or mac for the human's Mac): it brings that bot's name, model, role, kind and worker tiers, and any other field you pass overrides it. In a local workspace it joins the team immediately and can be @-mentioned once this returns. In a hosted workspace this commits the bot to the workspace repo, and it joins with the next deployment, hosted or on the Mac alike. Models are AI Gateway ids, e.g. openai/gpt-6-luna, anthropic/claude-opus-5.5.",
     inputSchema: z.object({
-        name: z.string().regex(/^[a-z][a-z0-9-]{1,30}$/).describe("Lowercase handle, e.g. deep-diver."),
-        model: z.string().describe("AI Gateway model id."),
+        starter: z.enum(["planner", "builder", "reviewer", "mac"]).optional().describe("A standard teammate to add; the fields below are then optional."),
+        name: z.string().regex(/^[a-z][a-z0-9-]{1,30}$/).optional().describe("Lowercase handle, e.g. deep-diver. Required without a starter."),
+        model: z.string().optional().describe("AI Gateway model id. Required without a starter."),
         reasoning: z.enum(["low", "medium", "high", "xhigh"]).optional(),
         runsOn: z.enum(["hosted", "local"]).optional().describe("Where the bot runs, fixed for its life: hosted (the Vercel bots project) or local (the human's Mac). Required in a hosted workspace; a local workspace's bots are local."),
-        role: z.string().describe("One line: what this bot does."),
+        role: z.string().optional().describe("One line: what this bot does. Required without a starter."),
         instructions: z.string().optional().describe("Extra guidance: specialty, style, who it hands off to."),
         domains: z.array(z.string().regex(/^[a-z][a-z0-9-]*(\/[a-z][a-z0-9-]*)*$/)).optional().describe("Memory domains: folders under memory/ whose standing decisions this bot also recalls, e.g. [\"ui\"]. It always recalls memory/ itself."),
         preset: z