eve-hub 0.16.3 → 0.16.4

package/README.md

@@ -61,7 +61,7 @@ A deployed workspace (lib/workspace-template.mjs, staged by hosted-hub/scripts/s
 
 eve-hub's version is `package.json`'s `version` (the base) plus one patch per `.changeset/*.md` naming `eve-hub` (`lib/kit-version.mjs`). A PR that changes the kit only adds its changeset (`pnpm changeset`), so two open kit PRs never edit the same file. When it merges, `ci.yml`'s `deploy-hub` job runs `scripts/publish.mjs`, which stages the package into `dist/npm` with the computed version, publishes it when npm lacks it, and the `eve-hub@<version>` GitHub release is created; nothing is committed (main's ruleset allows only PR merges). A minor or major release raises the base and deletes the pending changesets in one PR; a kit change must raise the version, and it never goes down (`test/kit-version-bumped.test.mjs`). CHANGELOG.md stops at 0.14.x; the release notes and changesets carry later changes. npm auth is the repo's `NPM_TOKEN` secret (an npm automation token). The template pins the version this checkout carries.
 
-The template's main gets a Vercel Sandbox and only the kit stubs that run without the hub's machine (lib/workspace-template.mjs `DEPLOYED_KIT_FILES`; eve's own bash replaces the kit's). The template's builder also mounts eve-code (`eve/extensions/code`: `apply_patch`, `grep`, the review skills, a read-only worker) and `eve/extensions/git` (`git({})`), both with no `github` option. Every bot of a build with the project's `GITHUB_TOKEN` mounts `eve/extensions/git`; a build without one mounts it nowhere, and the execution context points the bot to the `vercel-kit` connection instead (packages/agent-kit/prepare.mjs, execution-context.mjs; the rendered prompts are snapshotted in hosted-hub/test/prompts). The bot uses `gh` and `git` from bash, whose GitHub token is the sandbox firewall's (the Vercel sandbox `create_agent` writes, lib/agent-template.mjs `sandboxFile`), and no `gh` tool is contributed. A deployed workspace's eve is the one pin in `hosted-hub/bots/package.json`, which staging copies over the template's (an eve snapshot with `eve/extensions/git`; `hosted-hub/test/stage-workspace.test.mjs` checks the staged imports resolve against it). The hub and local bots stay on the hub's eve. The published tarball (`scripts/pack.mjs`) leaves out the kit__worker extension, which mounts only on the hub's machine. The hub reaches each bot's eve channel with `Authorization: Bearer $BOT_TOKEN` (`bot-token.mjs`); the kit's calls to the hub (`registry-fetch.mjs`, at `ROSTER_REGISTRY_URL`) carry `Authorization: Bearer $HUB_TOKEN` when set. The hosted hub keeps Vercel Authentication on: a deployed bot sends its project's OIDC token in `x-vercel-trusted-oidc-idp-token` too (the hub project lists each bots project in its Trusted Sources, `hosted-hub/src/onboard/trust.ts` `trustBots`, and never the bypass secret, even while its deployment still holds the env), and a bot on a Mac sends `x-vercel-protection-bypass: $HUB_PROTECTION_BYPASS` (the hub project's automation bypass secret) when it has one.
+The template's main gets a Vercel Sandbox and only the kit stubs that run without the hub's machine (lib/workspace-template.mjs `DEPLOYED_KIT_FILES`; eve's own bash replaces the kit's). Every hosted bot's sandbox (lib/agent-template.mjs `sandboxFile`, written at `create_agent`) installs eve-code's tooling (`installCodeTooling`: `gh` and `gh-signed-commit` under `/usr/local/lib/eve-code`), sets no network policy and holds no credential. The template's builder also mounts eve-code (`eve/extensions/code`: `apply_patch`, `grep`, the review skills, a read-only worker) with no `github` option. Every bot that edits files, in a build from a workspace repo, mounts `eve/extensions/git` as `extensions/git.ts` with a `github` option: connector `github/eve-hub-github` (the hub's GitHub App, which `attachHub` links to the bots project for every environment at onboarding), `principalType: "user"` (each `git__gh` command runs with the human's own GitHub token, which Vercel Connect resolves through that App; every hub turn, wake-ups and bot handoffs included, runs as the workspace's human, so pushes, PRs and commits are theirs; the first command raises a sign-in card), `authorize` limiting commands to the repo owner's org (`VERCEL_GIT_REPO_OWNER`), and a broker that puts the token into the Vercel Sandbox's firewall (`setNetworkPolicy`) for that command alone. The bot runs `git`, `gh` and `gh-signed-commit` through `git__gh`; plain `git` and `gh` in bash have no credential. A read-only bot (eve's `write_file` disabled) gets none, since the user token can't be narrowed below the human's own write access; a bot's own committed `extensions/git.ts` is kept as the workspace's. A build without a repo (an uploaded deployment) mounts no git extension, removes one the tree carries (the legacy `extensions/git/extension.ts` stub too), and the execution context points the bot to the `vercel-kit` connection instead (packages/agent-kit/prepare.mjs, execution-context.mjs; the rendered prompts are snapshotted in hosted-hub/test/prompts). A deployed workspace's eve is the one pin in `hosted-hub/bots/package.json`, which staging copies over the template's (an eve snapshot with `eve/extensions/git`; `hosted-hub/test/stage-workspace.test.mjs` checks the staged imports resolve against it). The hub and local bots stay on the hub's eve. The published tarball (`scripts/pack.mjs`) leaves out the kit__worker extension, which mounts only on the hub's machine. A hosted bot's `sandbox.ts` from an earlier template (the `GITHUB_TOKEN` policy, no eve-code tooling) is moved by the hosted kit update (`sandbox-migrate.mjs`, from `hosted-hub/src/onboard/repo-bump.ts` `kitChange`), keeping the bot's own `prepare` steps; a build from a repo refuses a hosted sandbox `git__gh` can't run in. The hub reaches each bot's eve channel with `Authorization: Bearer $BOT_TOKEN` (`bot-token.mjs`); the kit's calls to the hub (`registry-fetch.mjs`, at `ROSTER_REGISTRY_URL`) carry `Authorization: Bearer $HUB_TOKEN` when set. The hosted hub keeps Vercel Authentication on: a deployed bot sends its project's OIDC token in `x-vercel-trusted-oidc-idp-token` too (the hub project lists each bots project in its Trusted Sources, `hosted-hub/src/onboard/trust.ts` `trustBots`, and never the bypass secret, even while its deployment still holds the env), and a bot on a Mac sends `x-vercel-protection-bypass: $HUB_PROTECTION_BYPASS` (the hub project's automation bypass secret) when it has one.
 
 ## Vercel Kit connection
 

package/execution-context.mjs

@@ -22,7 +22,8 @@ const claims = (jwt) => JSON.parse(Buffer.from(jwt.split(".")[1], "base64url").t
 
 export function deploymentFacts(env = process.env) {
   const oidc = env.VERCEL_OIDC_TOKEN ? claims(env.VERCEL_OIDC_TOKEN) : {};
-  const repo = env.VERCEL_GIT_REPO_OWNER && env.VERCEL_GIT_REPO_SLUG ? `${env.VERCEL_GIT_REPO_OWNER}/${env.VERCEL_GIT_REPO_SLUG}` : undefined;
+  const repoOwner = env.VERCEL_GIT_REPO_OWNER && env.VERCEL_GIT_REPO_SLUG ? env.VERCEL_GIT_REPO_OWNER : undefined;
+  const repo = repoOwner ? `${repoOwner}/${env.VERCEL_GIT_REPO_SLUG}` : undefined;
   return {
     team: oidc.owner,
     project: oidc.project,
@@ -31,15 +32,15 @@ export function deploymentFacts(env = process.env) {
     url: env.VERCEL_URL,
     environment: env.VERCEL_ENV,
     repo,
+    repoOwner,
     branch: env.VERCEL_GIT_COMMIT_REF,
     sha: env.VERCEL_GIT_COMMIT_SHA,
-    githubToken: Boolean(env.GITHUB_TOKEN),
   };
 }
 
 const list = (items) => items.map((item) => `\`${item}\``).join(", ");
 
-export function hostedContext({ bot, kit, removed, deployment: d }, options) {
+export function hostedContext({ bot, kit, removed, deployment: d, git = false }, options) {
   const dashboard = d.team && d.project ? `https://vercel.com/${d.team}/${d.project}` : undefined;
   const lines = [
     `You are \`${bot}\`, an eve agent deployed on Vercel, not on a laptop: \`hub.workspace.json\` defines you as hosted.`,
@@ -57,8 +58,8 @@ export function hostedContext({ bot, kit, removed, deployment: d }, options) {
     d.repo
       ? "- **Changing it:** commit to that repository; Vercel builds and deploys the commit."
       : "- **Changing it:** there is no repository to commit to. The hub replaces these files on its next deploy, so an edit made only in this deployment does not last.",
-    d.githubToken
-      ? "- **GitHub:** `git` and `gh` in your shell are already signed in and set to sign commits as the owner; do not set your own author or identity, or GitHub rejects the push."
+    git
+      ? "- **GitHub:** goes through the `git__gh` tool (`git`, `gh`, `gh-signed-commit`), which runs each command with the human's own GitHub token, swapped in at the sandbox firewall for that command, so pushes, pull requests and commits are theirs. The shell itself holds no credential, so plain `git` and `gh` in bash cannot authenticate."
       : "- **GitHub:** your shell has no GitHub credential: `git` cannot authenticate, so a private repository won't clone and nothing can be pushed. When a `vercel-kit` connection is listed, reach GitHub through it (eve__search, then eve__tool); otherwise tell the human this deployment has no GitHub access.",
     "- **Memory:** the standing decisions you recall are the `memory/` and `agents/<bot>/memory/` files, built into each deployment. An entry takes effect when the deployment that contains it is live, not on your next turn; with no repository it cannot last.",
     "- **Limits:** there is no `hub` CLI, you cannot restart yourself or any bot, and there are no host paths: your shell is a Vercel Sandbox with its own filesystem, not the owner's machine.",

package/local-onboarding/SKILL.md

@@ -62,7 +62,7 @@ Mapping each fact to a setup is your judgment, not a lookup table. Decide, for e
   - `localhost` services and the keychain.
 
   Everything else can be hosted.
-- **Already there, or add it.** A hosted bot's sandbox is eve's Ubuntu image with git only, 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.
+- **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.
 
 MCP 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.
 
@@ -84,6 +84,6 @@ Main's handoff names the workspace repo. Clone it into a scratch folder, branch,
 node {{scripts}}/prepare-edit.mjs "$TMPDIR/prepare.json" agents/builder/agent/sandbox.ts
 ```
 
-Commit, push and open the PR with `gh pr create`. The body lists the programs, why each one is there, and the usage counts behind them. Never name the owner's other repos.
+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.
 
 The 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.

package/local-onboarding/prepare-edit.mjs

@@ -2,24 +2,39 @@
 // Adds the sandbox setup local-onboarding proposed to hosted bots' sandbox.ts, in place:
 //   node prepare-edit.mjs proposal.json agents/<bot>/agent/sandbox.ts [...]
 // proposal.json is {"commands": [{"command": "<shell>", "what": "<short name for the error>"}]}, the one source of
-// the steps: they are written as `await run(...)` calls into `prepare`, before its `if (!token) return;`, so every new
-// session's snapshot has them. A step already in the file is not added twice. A sandbox.ts without the scaffold's
-// `run` helper and token line (lib/agent-template.mjs) is refused: edit that one by hand.
+// the steps: they are written as `await run(...)` calls into `prepare`, after eve-code's tooling install, so every
+// new session's snapshot has them. The scaffold's one-line `prepare` (lib/agent-template.mjs) is opened into a block
+// with the `run` helper the first time; a step already in the file is not added twice. A sandbox.ts with neither
+// form is refused: edit that one by hand. One an earlier template wrote is moved first (sandbox-migrate.mjs), so no
+// step lands after its `if (!token) return;`.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
+import { migrateSandbox } from '../sandbox-migrate.mjs';
 
+const ONE_LINE = 'VercelSandbox.environment({ prepare: (sandbox) => installCodeTooling(sandbox) });\n';
+const OPENED = `VercelSandbox.environment({ prepare: async (sandbox) => {
+  await installCodeTooling(sandbox);
+  const run = async (command, what) => {
+    if ((await sandbox.run({ command })).exitCode !== 0) throw new Error(what + " failed");
+  };
+  // The programs the owner's coding agents use (local-onboarding).
+} });
+`;
 const RUN = /^  const run = async \(command, what\) => \{$/m;
-const ANCHOR = '  if (!token) return;\n';
+const END = '} });\n';
 
 export function addPrepareSteps(source, commands) {
   if (!Array.isArray(commands) || !commands.every((c) => typeof c?.command === 'string' && c.command.trim() && typeof c?.what === 'string' && c.what.trim())) {
     throw new Error('commands must be [{ command, what }] with both non-empty');
   }
-  if (!RUN.test(source) || !source.includes(ANCHOR)) throw new Error("this sandbox.ts isn't the scaffold's (no `run` helper or `if (!token) return;`): add the steps by hand");
-  const lines = commands.map(({ command, what }) => `  await run(${JSON.stringify(command)}, ${JSON.stringify(what)});\n`).filter((line) => !source.includes(line));
-  if (!lines.length) return source;
-  const steps = `  // The programs the owner's coding agents use (local-onboarding).\n${lines.join('')}${ANCHOR}`;
-  return source.replace(ANCHOR, () => steps);
+  const moved = migrateSandbox(source);
+  if (moved.reason) throw new Error(`this sandbox.ts ${moved.reason}; add the steps by hand`);
+  const current = moved.source;
+  const opened = current.includes(ONE_LINE) ? current.replace(ONE_LINE, () => OPENED) : current;
+  if (!RUN.test(opened) || !opened.includes(END)) throw new Error("this sandbox.ts isn't the scaffold's (no `prepare` to open or `run` helper): add the steps by hand");
+  const lines = commands.map(({ command, what }) => `  await run(${JSON.stringify(command)}, ${JSON.stringify(what)});\n`).filter((line) => !opened.includes(line));
+  if (!lines.length) return current;
+  return opened.replace(END, () => `${lines.join('')}${END}`);
 }
 
 if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-hub",
-  "version": "0.16.3",
+  "version": "0.16.4",
   "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",
@@ -35,7 +35,7 @@
   "peerDependencies": {
     "@vercel/connect": "^2.4.1",
     "@vercel/oidc": "4.0.0",
-    "eve": ">=0.88.0",
+    "eve": "~0.88.0",
     "zod": "4.5.4"
   },
   "dependencies": {

package/prepare.mjs

@@ -10,7 +10,7 @@
 //   off the hub's machine (DEPLOYED_KIT_FILES); a hosted bot whose sandbox.ts
 //   is the host's fails the build, and the build never writes a sandbox;
 // - the kit extension, host-only workers and kit stubs are dropped, the
-//   Vercel Kit connection is wired in, every bot gets eve's git extension, and the
+//   Vercel Kit connection is wired in, every bot of a build from a repo gets eve's git extension, and the
 //   workspace's memory and each bot's team architecture are embedded in the bots' memory providers (a function
 //   has no workspace cwd);
 // - /hub/manifest: the roster and the commit sha the deployment was built
@@ -26,14 +26,47 @@ import { deploymentFacts, hostedContext } from "./execution-context.mjs";
 import { botDomains, domainFolders, readBotMemory, readMemory, validateMemory } from "./memory.mjs";
 import { agentRunsOn, readWorkspaceFile, removeWorkspaceAgent } from "./workspace.mjs";
 import { architectureText } from "./team.mjs";
+import { sandboxReady } from "./sandbox-migrate.mjs";
 
-// eve's git extension, for every bot of a build with a GITHUB_TOKEN: it points
-// the bot at `gh` and `git` in bash, whose GitHub credential is the sandbox
-// firewall's (the Vercel sandbox lib/agent-template.mjs writes). With no
-// `github` option it brokers no credential and says the shell has one, so a
-// build without the token mounts none. It only guides: its `pr` skill (commit,
-// push, draft PR) loads when a bot publishes.
-export const gitExtensionFiles = () => ({ "extensions/git/extension.ts": `import git from "eve/extensions/git";\n\nexport default git({});\n` });
+// 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,
+// resolved by Vercel Connect through the GITHUB_CONNECTOR app (the hub links the connector to the
+// bots project at onboarding) and swapped in at the sandbox firewall for that command alone. Every
+// 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";
+// The stub an earlier kit wrote, with no `github` option; two git extensions would collide.
+export const LEGACY_GIT_EXTENSION_FILE = "extensions/git/extension.ts";
+export const gitExtensionFiles = (org) => ({ [GIT_EXTENSION_FILE]: `import git from "eve/extensions/git";
+import type { GitHubLeaseBroker } from "eve/extensions/git";
+import type { SandboxNetworkPolicy } from "eve/sandbox";
+import type { VercelSandboxSession } from "eve/sandbox/vercel";
+
+// Each \`git__gh\` command runs with the caller's own GitHub token, resolved by Vercel Connect
+// through the eve-hub-github App, so pushes, PRs and commits are the human's. Every hub turn,
+// wake-ups and bot handoffs included, runs as the workspace's human (channels/eve-roster-user).
+// The sandbox only sees a placeholder; this swaps the real token in at the sandbox firewall for
+// that command and removes it afterwards. All other egress stays open.
+const broker: GitHubLeaseBroker = async (sandbox, rules) => {
+  if (!("setNetworkPolicy" in sandbox)) throw new Error("GitHub credential leases need a Vercel Sandbox");
+  await (sandbox as VercelSandboxSession).setNetworkPolicy({ allow: { "*": [], ...rules } } as SandboxNetworkPolicy);
+};
+
+const ORG = ${JSON.stringify(org.toLowerCase())};
+
+export default git({
+  github: {
+    connector: ${JSON.stringify(GITHUB_CONNECTOR)},
+    broker,
+    authorize: ({ repository }) => repository.toLowerCase().startsWith(\`\${ORG}/\`),
+    principalType: "user",
+  },
+});
+` });
 
 // Bots that edit code: eve-code (apply_patch, grep, the review skills and its
 // read-only worker), with no `github` option. The worker runs on the roster's
@@ -109,7 +142,7 @@ export default defineMemory({ namespace: "hub-team-memory", scope: "workspace",
 function writeExecutionContext(bot, { bot: name, deployment }) {
   const kitTools = Object.keys(name === "main" ? MAIN_KIT_FILES : KIT_FILES).filter((file) => file.startsWith("tools/") && file !== "tools/bash.ts").map((file) => basename(file, ".ts"));
   const removed = kitTools.filter((tool) => !existsSync(join(bot, "tools", `${tool}.ts`)));
-  const section = hostedContext({ bot: name, kit: KIT_VERSION, removed, deployment });
+  const section = hostedContext({ bot: name, kit: KIT_VERSION, removed, deployment, git: existsSync(join(bot, GIT_EXTENSION_FILE)) });
   mkdirSync(join(bot, "instructions"), { recursive: true });
   writeFileSync(join(bot, "instructions", "execution-context.ts"), `import { defineInstructions } from "eve/instructions";\n\nexport default defineInstructions({ content: ${JSON.stringify(section)} });\n`);
 }
@@ -128,6 +161,10 @@ export function prepareDeployment(dir) {
   const tiersOf = (name) => Object.keys(definition.agents.find((a) => a.name === name)?.subagents ?? {});
   const change = syncKit({ bots: folders.map((name) => ({ name, runsOn: "hosted", files: readBotFiles(dirOf(name)), subagents: tiersOf(name) })), modules: KIT_MODULES });
   if (change.report.length) throw new Error(`these files can't ship to a hosted deployment; update or delete them:\n${change.report.map((r) => `  agents/${r.bot}/agent/${r.file} ${r.reason}`).join("\n")}`);
+  const deployment = deploymentFacts();
+  // The git extension's `git__gh` runs eve-code's gh; a sandbox an earlier template wrote has none. The hub's kit update moves it (sandbox-migrate.mjs).
+  const unready = deployment.repoOwner ? folders.filter((name) => existsSync(join(dirOf(name), "sandbox.ts")) && !sandboxReady(readFileSync(join(dirOf(name), "sandbox.ts"), "utf8"))) : [];
+  if (unready.length) throw new Error(`these sandboxes can't run the git__gh tool: add \`await installCodeTooling(sandbox);\` (from eve/extensions/code/sandbox) to prepare and remove the GITHUB_TOKEN policy, or let the hub's workspace update move them:\n${unready.map((name) => `  agents/${name}/agent/sandbox.ts`).join("\n")}`);
   writeFileSync(join(dir, MANIFEST_FILE), `${JSON.stringify(resolved, null, 2)}\n`);
   for (const { name } of definition.agents) {
     if (agentRunsOn(definition, name) !== "local") continue;
@@ -137,18 +174,20 @@ export function prepareDeployment(dir) {
   mkdirSync(join(dir, "agents", "main", "agent", "channels"), { recursive: true });
   writeFileSync(join(dir, "agents", "main", "agent", "channels", "manifest.ts"), MANIFEST_CHANNEL);
   applyKit(change, dirOf);
-  const deployment = deploymentFacts();
   // Bots only: a declared subagent's agent.ts (agent/subagents/<tier>/) is not a bot and mounts none of these.
   for (const name of readdirSync(join(dir, "agents"))) {
     const bot = dirOf(name);
     if (!existsSync(join(bot, "agent.ts"))) continue;
     const code = CODE_BOTS.includes(name);
-    for (const [stub, content] of Object.entries({ ...(deployment.githubToken ? gitExtensionFiles() : {}), ...(code ? codeExtensionFiles(name) : {}) })) {
+    // A user token carries all of the human's write access and can't be narrowed, so a read-only bot
+    // gets none. A bot's own committed git.ts (a wider org list, say) is the workspace's and stays.
+    const git = deployment.repoOwner && !existsSync(join(bot, READ_ONLY_FILE)) && !existsSync(join(bot, GIT_EXTENSION_FILE));
+    for (const [stub, content] of Object.entries({ ...(git ? gitExtensionFiles(deployment.repoOwner) : {}), ...(code ? codeExtensionFiles(name) : {}) })) {
       mkdirSync(dirname(join(bot, stub)), { recursive: true });
       writeFileSync(join(bot, stub), content);
     }
-    // A workspace repo may carry the stub from an earlier build.
-    if (!deployment.githubToken) for (const stub of Object.keys(gitExtensionFiles())) if (existsSync(join(bot, stub))) removeStub(bot, stub);
+    if (existsSync(join(bot, LEGACY_GIT_EXTENSION_FILE))) removeStub(bot, LEGACY_GIT_EXTENSION_FILE);
+    if (!deployment.repoOwner && existsSync(join(bot, GIT_EXTENSION_FILE))) removeStub(bot, GIT_EXTENSION_FILE);
   }
   for (const name of readdirSync(join(dir, "agents"))) {
     const bot = join(dir, "agents", name, "agent");

package/sandbox-migrate.d.mts

@@ -0,0 +1,2 @@
+export declare function sandboxReady(source: string): boolean;
+export declare function migrateSandbox(source: string): { source: string; reason?: undefined } | { reason: string; source?: undefined };

package/sandbox-migrate.mjs

@@ -0,0 +1,39 @@
+// Moves a hosted bot's sandbox.ts, as an earlier template wrote it, to the current one: eve-git's `git__gh` tool
+// (prepare.mjs mounts it on every hosted bot) runs the `gh` and `gh-signed-commit` that eve-code's
+// `installCodeTooling` installs, and its GitHub token comes per command, so the TEMPORARY `GITHUB_TOKEN` firewall
+// policy and the token-only prepare steps go. Steps a person or local-onboarding added stay where they are: the
+// earlier template put them before `if (!token) return;`. Only the template's own lines after it are removed; a
+// sandbox with anything else there is refused, for a person to edit.
+// The hosted kit bump (hosted-hub/src/onboard/repo-bump.ts) commits what this returns; the build (prepare.mjs)
+// refuses a hosted sandbox.ts this hasn't moved.
+
+const TOOLING_IMPORT = 'import { installCodeTooling } from "eve/extensions/code/sandbox";\n';
+const VERCEL_IMPORT = 'import { VercelSandbox } from "eve/sandbox/vercel";\n';
+const TOOLING_CALL = /\binstallCodeTooling\(sandbox\)/;
+// From the TEMPORARY comment through the policy's end, and the blank line after it.
+const TOKEN_POLICY = /^\/\/ TEMPORARY \(until the Vercel Connect GitHub connector replaces it\)[\s\S]*?^\} \} : undefined;\n\n?/m;
+// The token line and the token-only steps after it (apt gh, placeholder login, signing key), exactly as the template
+// wrote them, up to the end of `prepare`. With any other line among or after them the token line stays, and the
+// sandbox is refused rather than losing that line.
+const TOKEN_STEPS = "  if (!token) return;\n  // eve's sandbox image is Ubuntu with git only; gh and ssh-keygen come from apt.\n  await run(\"sudo apt-get update -qq && sudo apt-get install -y -qq gh openssh-client\", \"gh and ssh installation\");\n  // gh refuses to run without a login; this one is a placeholder the firewall overwrites.\n  await run(\"mkdir -p ~/.config/gh && printf 'github.com:\\n  user: hub\\n  oauth_token: placeholder\\n  git_protocol: https\\n' > ~/.config/gh/hosts.yml\", \"gh login\");\n  // The org requires signed commits. Eve reuses a named template sandbox after a failed prepare, so\n  // this step starts by clearing an earlier key. A key made here, registered as a signing key on\n  // the token's user, never leaves the sandbox; commits carry that user's noreply email.\n  await run([\n    \"mkdir -p ~/.ssh && rm -f ~/.ssh/signing ~/.ssh/signing.pub && ssh-keygen -q -t ed25519 -N '' -C hub-bot -f ~/.ssh/signing\",\n    \"gh api user/ssh_signing_keys -f title=\\\"hub bot sandbox $(date -u +%FT%TZ)\\\" -f key=\\\"$(cat ~/.ssh/signing.pub)\\\" --silent\",\n    \"login=$(gh api user --jq .login) && id=$(gh api user --jq .id)\",\n    \"git config --global user.name \\\"$login\\\" && git config --global user.email \\\"$id+$login@users.noreply.github.com\\\"\",\n    \"git config --global gpg.format ssh && git config --global user.signingkey ~/.ssh/signing && git config --global commit.gpgsign true\",\n  ].join(\" && \"), \"git signing setup\");\n";
+const PREPARE_END = "} });\n";
+const PREPARE_OPEN = "VercelSandbox.environment({ prepare: async (sandbox) => {\n";
+const LEFTOVER = /\bGITHUB_TOKEN\b|\bnetworkPolicy\b|\bif \(!token\)/;
+
+/** Whether a hosted sandbox.ts is one `git__gh` can run in: it installs eve-code's tooling and keeps no `GITHUB_TOKEN` policy. */
+export const sandboxReady = (source) => TOOLING_CALL.test(source) && !LEFTOVER.test(source.replace(/\/\/.*$/gm, ""));
+
+/**
+ * `{ source }`: the sandbox.ts moved (the same text when it is ready already), or `{ reason }` when it isn't a form
+ * this knows, for a person to edit by hand.
+ */
+export function migrateSandbox(source) {
+  if (sandboxReady(source)) return { source };
+  let out = source.replace(TOKEN_POLICY, "").replace(TOKEN_STEPS + PREPARE_END, () => PREPARE_END).replace("VercelSandbox.environment({ networkPolicy, prepare:", "VercelSandbox.environment({ prepare:");
+  if (!TOOLING_CALL.test(out)) {
+    if (!out.includes(PREPARE_OPEN) || !out.includes(VERCEL_IMPORT)) return { reason: "doesn't install eve-code's tooling, which the git__gh tool needs: add `await installCodeTooling(sandbox);` (from eve/extensions/code/sandbox) to its prepare" };
+    out = out.replace(VERCEL_IMPORT, () => VERCEL_IMPORT + TOOLING_IMPORT).replace(PREPARE_OPEN, () => `${PREPARE_OPEN}  await installCodeTooling(sandbox);\n`);
+  }
+  if (!sandboxReady(out)) return { reason: "still uses GITHUB_TOKEN, a networkPolicy or steps after `if (!token) return;` that the template didn't write, which the git__gh tool replaces: move those steps before that line or remove them, then remove the token policy" };
+  return { source: out };
+}

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 only, 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`. 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. 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"};