eve-hub 0.5.6 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # eve-hub
 
+## 0.6.1
+
+### Patch Changes
+
+- Every bot gets an execution-context prompt (`agents/<bot>/agent/instructions/execution-context.ts`), chosen by its definition in `hub.workspace.json`: `runsOn` on the agent, else a workspace-wide `"runsOn"` (a local hub's workspace declares `"local"`; a deployable repo declares `"hosted"`), else hosted. A local bot's comes from the kit's templates; the Vercel build writes a hosted bot's from what it produced: the eve-hub version, the roster and which bots run on the Mac, the deployment, team and repo commit (or that the hub uploaded the files), the kit tools it removed, and the dashboard links to its logs. The shared prompts keep only what is true in both contexts: main's restart, team, memory and Dash-schedule paragraphs, and the image and local-file link rules, moved into the per-context pages. `hub workspace sync` declares `"runsOn": "local"` in a workspace file that declares nothing.
+
+## 0.6.0
+
+### Minor Changes
+
+- A workspace repo carries its bots, memory and workspace file; the Vercel build prepares it (eve-hub/vercel), including bots that run on the Mac (`runsOn: "local"`). The Mac runner downloads the deployed commit through the hub instead of reading a folder.
+
+## 0.5.7
+
+### Patch Changes
+
+- One `dash` schedule (every 8 minutes, and when a bot's turn ends) replaces `dash`, `classify` and `tracks`: one GitHub query, a model call per thread whose facts changed and a model call per track with news. The `classify.ts` and `tracks.ts` stubs are retired; the track-writer bot is no longer woken.
+- `post_message` takes a reviewer's `verdict` (ship, fix-first, rethink) and `decisions`; a ship without a change-explainer for the PR shows "no explainer" on the Dash.
+
 ## 0.5.6
 
 ### Patch Changes

package/README.md

@@ -8,8 +8,9 @@ The bot-side code every hub agent shares (milestone M3 in [`docs/architecture`](
 | `tools/create_thread.ts`, `post_message.ts`, `archive_thread.ts`, `unarchive_thread.ts`, `list_agents.ts`, `create_agent.ts`, `remove_agent.ts`, `restart_agent.ts`, `agent_send.ts`, `tag_threads.ts`, `apply_tags.ts` | The orchestrator's tools | `main`'s `agent/tools/<same name>.ts` |
 | `hooks/sandbox.ts` | Migrates legacy Docker sessions to the host sandbox (`defineHook`) | `agent/hooks/sandbox.ts` |
 | `instructions/main.ts`, `main-instructions.mjs` | main's instructions (`defineInstructions`), rendered at build time from the kit's `templates/main-instructions.md` + `workspace-protocol.md`, so no workspace carries a copy | `main`'s `agent/instructions.ts`; workspace-only additions in `agent/instructions/*.md` |
-| `instructions/protocol.ts` | The shared protocol alone, rendered from `templates/workspace-protocol.md` | every other bot's `agent/instructions/protocol.ts`, appended after its own `instructions.md` (who the bot is) |
-| `memory/workspace.ts`, `memory.mjs` | an eve memory slot (default export, constant `workspace` scope) whose provider recalls the workspace's `memory/<id>.md` entries, one message each, at every turn start and after compaction, only the ones whose text changed since the session last saw them, as new messages after the history; `validateMemory(root)` for a workspace's tests | every bot's (main too) `agent/memory/workspace.ts`: `export { default } from "eve-hub/memory/workspace"` |
+| `instructions/protocol.ts` | The shared protocol alone, rendered from `templates/workspace-protocol.md` followed by `templates/engineering.md` | every other bot's `agent/instructions/protocol.ts`, appended after its own `instructions.md` (who the bot is) |
+| `instructions/engineering.ts` | The engineering page alone (`templates/engineering.md`), for a subagent that doesn't carry the protocol | the subagent's `instructions/engineering.ts` |
+| `memory/workspace.ts`, `memory.mjs` | an eve memory slot (default export, constant `workspace` scope) whose provider recalls the workspace's `memory/<id>.md` entries (plus the `memory/<domain>/` folders the bot lists as `domains` in its roster entry), one message each, at every turn start and after compaction, only the ones whose text changed since the session last saw them, as new messages after the history; `validateMemory(root)` for a workspace's tests | every bot's (main too) `agent/memory/workspace.ts`: `export { default } from "eve-hub/memory/workspace"` |
 | `memory/bot.ts` | the same for the bot's own `agents/<bot>/memory/<id>.md` entries; the bot is found from its directory (`findBotDir`), scope is its name | every bot's `agent/memory/bot.ts`: `export { default } from "eve-hub/memory/bot"` |
 | `channels/eve-roster-user.ts` | `eveChannel({ auth: [rosterUser, localDev()] })`: eve's default steer policy, and the registry's `x-roster-user` human as a user principal | every bot's `agent/channels/eve.ts` |
 | `channels/eve.ts` | Re-exports `eve-roster-user.ts`, for stubs written before every bot shared one channel | older `agent/channels/eve.ts` stubs |
@@ -56,11 +57,11 @@ Add a changeset (`pnpm changeset`, pick `eve-hub`) when a tool's name, schema, o
 
 ## Published package (deployed workspaces)
 
-A deployed workspace (`node scripts/workspace-template.mjs <dir>`, lib/workspace-template.mjs) has no hub checkout to link, so it installs the kit from npm, published as [`eve-hub`](https://www.npmjs.com/package/eve-hub): `"eve-hub": "<version>"`. `node packages/agent-kit/scripts/pack.mjs <outDir>` builds the package: every `.ts` module compiled to `.js` + `.d.ts` in place (node won't strip types under `node_modules`), the `exports` map pointed at them, and `templates/` included.
+A deployed workspace (lib/workspace-template.mjs, staged by hosted-hub/scripts/stage-workspace.mjs) has no hub checkout to link, so it installs the kit from npm, published as [`eve-hub`](https://www.npmjs.com/package/eve-hub): `"eve-hub": "<version>"`. `node packages/agent-kit/scripts/pack.mjs <outDir>` builds the package: every `.ts` module compiled to `.js` + `.d.ts` in place (node won't strip types under `node_modules`), the `exports` map pointed at them, and `templates/` included.
 
 Releases go through Changesets, as in eve. A PR that changes the kit adds a changeset (`pnpm changeset`) and applies it (`pnpm changeset version`); when it merges, `.github/workflows/release.yml` runs `changeset publish` (no bot commits to main: its ruleset allows only PR merges): the kit's `prepack` stages the package into `dist/npm` (its `publishConfig.directory`), npm gets it, and the `eve-hub@<version>` GitHub release is created. 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 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` and, since the hosted hub keeps Vercel Authentication on, `x-vercel-protection-bypass: $HUB_PROTECTION_BYPASS` (the hub project's automation bypass secret), each when set.
+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. The bot uses `gh` and `git` from bash, whose GitHub token is the sandbox firewall's (`VERCEL_SANDBOX`), 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 both `eve/world-hub` and `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` and, since the hosted hub keeps Vercel Authentication on, `x-vercel-protection-bypass: $HUB_PROTECTION_BYPASS` (the hub project's automation bypass secret), each when set.
 
 ## Vercel Kit connection
 

package/execution-context.mjs

@@ -0,0 +1,79 @@
+// A bot's execution-context prompt. A bot is defined in hub.workspace.json
+// (`runsOn` on the agent, else the file's own default, else hosted:
+// workspace.mjs agentRunsOn), and the page it gets follows from that field
+// alone: the local page from the kit's templates (every bot's
+// instructions/execution-context.ts stub calls `executionContext`), or, for a
+// bot the Vercel build deploys, a hosted page the build writes over that stub
+// (prepare.mjs), because only the build knows the deployment. The shared
+// prompts (templates/main-instructions.md, workspace-protocol.md) hold only
+// what is true in both contexts.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { templatesDir } from "./main-instructions.mjs";
+import { agentRunsOn, parseWorkspace } from "./workspace.mjs";
+
+const page = (name, options) => readFileSync(join(templatesDir(options), `execution-context-${name}.md`), "utf8").trimEnd();
+
+// The build's Vercel facts. The team and project name come from the build's
+// OIDC token (its `owner` and `project` claims); anything the build doesn't
+// carry stays undefined and the page leaves it out. A malformed token fails
+// the build.
+const claims = (jwt) => JSON.parse(Buffer.from(jwt.split(".")[1], "base64url").toString());
+
+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;
+  return {
+    team: oidc.owner,
+    project: oidc.project,
+    projectId: env.VERCEL_PROJECT_ID,
+    deployment: env.VERCEL_DEPLOYMENT_ID,
+    url: env.VERCEL_URL,
+    environment: env.VERCEL_ENV,
+    repo,
+    branch: env.VERCEL_GIT_COMMIT_REF,
+    sha: env.VERCEL_GIT_COMMIT_SHA,
+  };
+}
+
+const list = (items) => items.map((item) => `\`${item}\``).join(", ");
+
+export function hostedContext({ bot, roster, kit, removed, deployment: d }, options) {
+  const mac = roster.filter((agent) => agent.runsOn === "local").map((agent) => agent.name);
+  const cloud = roster.filter((agent) => agent.runsOn !== "local").map((agent) => agent.name);
+  const dashboard = d.team && d.project ? `https://vercel.com/${d.team}/${d.project}` : undefined;
+  const lines = [
+    "## Execution context",
+    `You are \`${bot}\`, an eve agent deployed on Vercel, not on a laptop: \`hub.workspace.json\` defines you as hosted.`,
+    "",
+    `- **Workspace:** ${cloud.length ? `${list(cloud)} run on Vercel` : "no bot runs on Vercel"}${mac.length ? `; ${list(mac)} run on the owner's Mac through the hub runner` : ""}. One hosted hub holds the threads and routes messages to each.`,
+    `- **Package:** your tools, hooks, channel and instructions come from the \`eve-hub\` package, version ${kit}.`,
+    `- **Deployment:** ${[
+      (d.project ?? d.projectId) && `project \`${d.project ?? d.projectId}\``,
+      d.team && `team \`${d.team}\``,
+      d.deployment && `deployment \`${d.deployment}\``,
+      d.environment && `${d.environment} environment`,
+      d.url && `at \`https://${d.url}\``,
+    ].filter(Boolean).join(", ") || "no Vercel facts were available to this build"}. Each bot is its own service at \`/eve/<name>\` in that one project.`,
+    `- **Source:** ${d.repo ? `built from \`${d.repo}\`${d.branch ? ` on \`${d.branch}\`` : ""}${d.sha ? ` at commit \`${d.sha}\`` : ""}` : "no git repository: the hub uploaded these files"}. You are made of files in it: \`agents/${bot}/\`, \`memory/\` and \`hub.workspace.json\`.`,
+    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.",
+    "- **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.",
+    `- **Kit tools this build removed:** ${removed.length ? list(removed) : "none"}. They need the hub's machine, or change the roster, which a deployment does by commit.`,
+    `- **Logs:** ${dashboard ? `[runtime logs](${dashboard}/logs)${d.deployment ? ` and [this deployment](${dashboard}/${d.deployment.replace(/^dpl_/, "")})` : ""} in the Vercel dashboard` : "the Vercel project's runtime logs in the dashboard"}.`,
+    ...(bot === "main" ? [page("hosted-main", options)] : []),
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+// What a bot's instructions/execution-context.ts stub renders. Hosted is the
+// Vercel build's to write (hostedContext), never this process's guess.
+export function executionContext(bot, workspace, options) {
+  const parsed = parseWorkspace(workspace);
+  const runsOn = agentRunsOn(parsed, bot);
+  if (runsOn !== "local") {
+    throw new Error(`${bot} is defined as hosted in hub.workspace.json, and a hosted bot's execution context is written by its Vercel build (eve-hub/vercel). A bot on this machine needs "runsOn": "local", on the agent or at the top of hub.workspace.json.`);
+  }
+  return ["## Execution context", `You are \`${bot}\`: \`hub.workspace.json\` defines you as local.`, "", page("local", options), ...(bot === "main" ? [page("local-main", options)] : [])].join("\n") + "\n";
+}

package/fork-env.mjs

@@ -5,13 +5,14 @@
 // the fork brief only restate this; the sandbox enforces the defaults.
 // Short-lived either way: a fork can be retired (and an in-place fork's
 // thread go back to the shared root) while its session lives on.
-import { registryBase, registryFetch } from "./registry-fetch.mjs";
+import { registryFetch, sandboxRegistry } from "./registry-fetch.mjs";
 
 const TTL_MS = 3000;
 
-export function createForkEnv({ registry = registryBase(), fetchImpl = globalThis.fetch, now = Date.now } = {}) {
+export function createForkEnv({ registry = sandboxRegistry(), fetchImpl = globalThis.fetch, now = Date.now } = {}) {
   const cache = new Map(); // sessionId -> { config, at }
   return async function lookup(sessionId) {
+    if (registry === null) return null; // no local hub: no forks
     const hit = cache.get(sessionId);
     if (hit && now() - hit.at < TTL_MS) return hit.config;
     let config = null;

package/host-browser.js

@@ -11,7 +11,7 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
-import { registryFetch } from "./registry-fetch.mjs";
+import { registryFetch, sandboxRegistry } from "./registry-fetch.mjs";
 export const VIEWPORT = { width: 1280, height: 800 };
 const FRAME_MS = 200; // at most 5 frames/s leave for the registry
 const IDLE_MS = 10 * 60_000; // an unused browser is closed; the next use reopens its last URL
@@ -43,6 +43,8 @@ export function findChrome() {
     return existsSync(chrome) ? { path: chrome, shell: false } : null;
 }
 function reportScreen(body) {
+    if (!sandboxRegistry())
+        return;
     void registryFetch(`/api/sandbox/screen`, {
         method: "POST",
         headers: { "content-type": "application/json" },

package/host-sandbox.d.ts

@@ -104,11 +104,10 @@ export interface Fence {
     (what: string): Promise<void>;
     readonly sessionId: string;
     readonly root: string;
-    readonly registry: string;
     admit(kind: TicketKind, op: TicketOp, what: string, group?: TicketGroup): Promise<Ticket>;
 }
 export declare function ownershipGuard(sessionId: string, { registry, rootSessionId, agent }?: {
-    registry?: string;
+    registry?: string | null;
     rootSessionId?: string;
     agent?: string;
 }): Fence;

package/host-sandbox.js

@@ -15,7 +15,7 @@ import { promisify } from "node:util";
 import { defineSandboxProvider } from "eve/sandbox/provider";
 import { closeBrowser } from "./host-browser.js";
 import { createForkEnv } from "./fork-env.mjs";
-import { registryBase, registryFetch, registryHeaders } from "./registry-fetch.mjs";
+import { registryFetch, registryHeaders, sandboxRegistry } from "./registry-fetch.mjs";
 const execFileAsync = promisify(execFile);
 export const HOST_ROOT = resolve(process.env.ROSTER_HOST_ROOT ?? join(homedir(), "wrk"));
 // The provider's lifecycle, exported so tests drive start/resume directly.
@@ -145,11 +145,13 @@ export function killTree(child) {
 // Live terminal: every process's output is teed to the roster registry so the
 // UI can show each bot's sandbox as it works. Best-effort; never blocks.
 let procSeq = 0;
-const forkConfig = createForkEnv({ registry: registryBase() });
+const forkConfig = createForkEnv({ registry: sandboxRegistry() });
 // `retries`: the exit report is the one that must land (without it the
 // registry eventually marks the proc interrupted), so it rides out a registry
 // restart of a few seconds.
 function reportProc(body, retries = 0) {
+    if (!sandboxRegistry())
+        return;
     void registryFetch(`/api/sandbox/proc`, {
         method: "POST",
         headers: { "content-type": "application/json" },
@@ -233,7 +235,8 @@ function teeProcess(child, sessionId, command, cwd, rootSessionId) {
 // with identical parameters until a definite answer or a bounded deadline,
 // after which the op is not performed (a paused launcher is killed; a "not-run"
 // release is queued for the id) and SessionFenceError is thrown.
-// HUB_OWNERSHIP_GUARD=off disables tickets entirely.
+// HUB_OWNERSHIP_GUARD=off disables tickets entirely, as does having no local
+// registry (sandboxRegistry(): a laptop bot of the hosted hub).
 //
 // LIMITS of the guarantee: (1) unfenced work while the registry is unreachable
 // is outside it, by policy, and only reported after the fact; (2) descendants
@@ -402,8 +405,10 @@ export function stopRevocationPollers() {
         p.stop();
     pollers.clear();
 }
-export function ownershipGuard(sessionId, { registry = registryBase(), rootSessionId, agent = process.env.HUB_AGENT } = {}) {
+export function ownershipGuard(sessionId, { registry = sandboxRegistry(), rootSessionId, agent = process.env.HUB_AGENT } = {}) {
     const root = rootSessionId ?? sessionId;
+    if (registry === null)
+        return Object.assign(async () => { }, { sessionId, root, admit: async () => UNFENCED }); // no local hub: none to fence with
     let warned = false;
     const warnOnce = (message) => {
         if (!warned)
@@ -507,7 +512,7 @@ export function ownershipGuard(sessionId, { registry = registryBase(), rootSessi
         if (!ownership.owner)
             throw refusal(what, ownership);
     };
-    return Object.assign(check, { sessionId, root, registry, admit });
+    return Object.assign(check, { sessionId, root, admit });
 }
 // The paused launcher. /bin/sh runs this with fd 3 a socket to us and the
 // shell-startup variables moved to HUB_LAUNCH_* (so neither sh nor anything it

package/{schedules/classify.d.ts → instructions/engineering.d.ts}

@@ -1,5 +1,4 @@
 declare const _default: {
-    cron: string;
-    run(): Promise<void>;
+    content: any;
 };
 export default _default;

package/instructions/engineering.js

@@ -0,0 +1,6 @@
+import { defineInstructions } from "eve/instructions";
+import { engineeringPage } from "../main-instructions.mjs";
+// The engineering page alone, for a subagent that doesn't carry the workspace
+// protocol (the protocol ends with this same page). A subagent re-exports this as
+// its instructions/engineering.ts.
+export default defineInstructions({ content: engineeringPage() });

package/main-instructions.mjs

@@ -1,5 +1,6 @@
 // main's instructions, rendered from the kit's templates: templates/main-instructions.md,
-// then the shared protocol (templates/workspace-protocol.md). One source for
+// then the shared protocol (templates/workspace-protocol.md, then the engineering
+// page, templates/engineering.md). One source for
 // `hub workspace init` (lib/agent-template.mjs) and for every workspace's main,
 // which imports it (instructions/main.ts) instead of carrying a copy, so a
 // template edit reaches each workspace on main's next build. Every other bot
@@ -11,6 +12,7 @@ import { findWorkspaceRoot } from "./workspace.mjs";
 
 const HEAD = "main-instructions.md";
 const PROTOCOL = "workspace-protocol.md";
+const ENGINEERING = "engineering.md";
 const templatesOf = (kitDir) => join(kitDir, "templates");
 
 // The templates sit next to the kit in the hub checkout. Run by node, this
@@ -27,13 +29,18 @@ export function templatesDir({ env = process.env, cwd = process.cwd() } = {}) {
 }
 
 export function mainInstructions(options) {
-  const dir = templatesDir(options);
-  const read = (name) => readFileSync(join(dir, name), "utf8");
-  return `${read(HEAD).trimEnd()}\n\n${read(PROTOCOL)}`;
+  const head = readFileSync(join(templatesDir(options), HEAD), "utf8");
+  return `${head.trimEnd()}\n\n${workspaceProtocol(options)}`;
 }
 
-// The shared protocol alone: every bot but main appends it after its own
+// The engineering page alone: the protocol ends with it, and a subagent that
+// never sees the protocol includes it (instructions/engineering.ts).
+export function engineeringPage(options) {
+  return readFileSync(join(templatesDir(options), ENGINEERING), "utf8");
+}
+
+// The shared protocol: every bot but main appends it after its own
 // instructions.md (agent/instructions/protocol.ts re-exports instructions/protocol.ts).
 export function workspaceProtocol(options) {
-  return readFileSync(join(templatesDir(options), PROTOCOL), "utf8");
+  return `${readFileSync(join(templatesDir(options), PROTOCOL), "utf8")}\n${engineeringPage(options)}`;
 }

package/memory/workspace.js

@@ -1,13 +1,18 @@
 import { defineMemory, defineMemoryProvider } from "eve/memory";
-import { loadMemoryRecall } from "../memory.mjs";
+import { botDomains, findBotDir, loadMemoryRecall } from "../memory.mjs";
 import { findWorkspaceRoot } from "../workspace.mjs";
 // The workspace's memory/ entries as an eve memory slot (see ../memory.mjs).
 // Recall re-reads memory/ at the start of every turn and after compaction and
 // returns only the entries whose text changed since this session last saw
 // them; eve appends those as user-role messages after the history, so the
 // system prompt and the cached prefix stay put when an entry changes.
-// One constant scope and namespace: every bot, every session, the same entries.
-const recall = ({ messages }) => ({ messages: loadMemoryRecall(findWorkspaceRoot(), messages) });
+// One constant scope and namespace. The entries are memory/ (every bot) plus
+// the folders for the domains this bot lists in hub.workspace.json.
+const recall = ({ messages }) => {
+    const root = findWorkspaceRoot();
+    const dir = findBotDir();
+    return { messages: loadMemoryRecall(root, messages, { domains: dir ? botDomains(root, dir) : [] }) };
+};
 export default defineMemory({
     description: "The human's standing decisions for this workspace, from its memory/ directory.",
     namespace: "hub-workspace-memory",

package/memory.mjs

@@ -5,6 +5,12 @@
 // them at the start of every turn (memory/workspace.ts, memory/bot.ts), so an
 // added, edited or superseded entry reaches the bot's next turn with no
 // rebuild or restart, appended after the history. Node built-ins only.
+// A workspace may group entries into domains: folders under memory/, nestable
+// (memory/ui/, memory/ui/motion/), same entry format. memory/ itself is the
+// domain every bot shares. A bot lists its domains in its hub.workspace.json
+// entry (`domains: ["ui/motion"]`) and recalls memory/ plus each listed
+// folder and every folder above it. The kit names no domain; a workspace
+// defines its own.
 // Shared entries name no bot: bots pick who acts next from the live workspace
 // state, never from a name, and a rule for one role says so in its text. A
 // rule for one bot goes in that bot's memory/ (or its instructions.md).
@@ -24,7 +30,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
-import { isWorkspace } from "./workspace.mjs";
+import { isWorkspace, readWorkspaceFile } from "./workspace.mjs";
 
 export const MEMORY_DIR = "memory";
 export const MAX_RULE_LINES = 3;
@@ -82,28 +88,64 @@ export function parseEntry(text, file = "entry.md") {
   return { id: f.id, status: f.status, since: f.since, evidence: f.evidence, ...(supersededBy ? { supersededBy } : {}), rule: lines.join(" ") };
 }
 
-// Every entry under <dir>/memory, sorted by id, and one error string per file
-// that isn't a valid entry. No memory/ directory is an empty memory. `label`
-// names the directory in errors; `knownIds` are ids a superseded_by may also
-// point at (a bot's entries may hand over to a shared one).
-export function readMemory(root, { label = MEMORY_DIR, knownIds = new Set() } = {}) {
-  const dir = join(root, MEMORY_DIR);
-  if (!existsSync(dir)) return { entries: [], errors: [] };
+// The folders under <root>/memory a bot with these domains recalls, as paths
+// relative to memory/: "" (the shared root), then each domain and its ancestors.
+export function domainFolders(domains = []) {
+  const folders = new Set([""]);
+  for (const domain of domains) {
+    const parts = domain.split("/");
+    for (let i = 1; i <= parts.length; i++) folders.add(parts.slice(0, i).join("/"));
+  }
+  return [...folders].sort();
+}
+
+// Every folder under <root>/memory, "" included: what a workspace's tests validate.
+export function allMemoryFolders(root) {
+  const folders = [""];
+  const walk = (rel) => {
+    for (const d of readdirSync(join(root, MEMORY_DIR, rel), { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      if (!d.isDirectory() || d.name.startsWith(".")) continue;
+      folders.push(rel ? `${rel}/${d.name}` : d.name);
+      walk(rel ? `${rel}/${d.name}` : d.name);
+    }
+  };
+  if (existsSync(join(root, MEMORY_DIR))) walk("");
+  return folders;
+}
+
+// Every entry in the given folders of <dir>/memory (default: the root only),
+// sorted by id, and one error string per file that isn't a valid entry, per
+// listed folder that doesn't exist, and per id used twice. No memory/
+// directory is an empty memory. `label` names the directory in errors;
+// `knownIds` are ids a superseded_by may also point at (a bot's entries may
+// hand over to a shared one).
+export function readMemory(root, { label = MEMORY_DIR, knownIds = new Set(), folders = [""] } = {}) {
   const entries = [];
   const errors = [];
-  const files = readdirSync(dir).filter((name) => name.endsWith(".md") && !name.startsWith(".") && name.toLowerCase() !== "readme.md").sort();
-  for (const name of files) {
-    const file = `${label}/${name}`;
-    try {
-      const entry = parseEntry(readFileSync(join(dir, name), "utf8"), file);
-      if (`${entry.id}.md` !== name) throw new MemoryError(`${file}: id ${entry.id} doesn't match the file name; rename it ${entry.id}.md`);
-      entries.push(entry);
-    } catch (error) {
-      errors.push(error instanceof MemoryError ? error.message : `${file}: ${error.message}`);
+  const where = new Map();
+  for (const folder of folders) {
+    const dir = folder ? join(root, MEMORY_DIR, folder) : join(root, MEMORY_DIR);
+    const prefix = folder ? `${label}/${folder}` : label;
+    if (!existsSync(dir)) {
+      if (folder) errors.push(`${prefix}: domain folder doesn't exist`);
+      continue;
+    }
+    const files = readdirSync(dir, { withFileTypes: true }).filter((d) => d.isFile() && d.name.endsWith(".md") && !d.name.startsWith(".") && d.name.toLowerCase() !== "readme.md").map((d) => d.name).sort();
+    for (const name of files) {
+      const file = `${prefix}/${name}`;
+      try {
+        const entry = parseEntry(readFileSync(join(dir, name), "utf8"), file);
+        if (`${entry.id}.md` !== name) throw new MemoryError(`${file}: id ${entry.id} doesn't match the file name; rename it ${entry.id}.md`);
+        if (where.has(entry.id)) throw new MemoryError(`${file}: id ${entry.id} is also ${where.get(entry.id)}; an id is used once`);
+        where.set(entry.id, file);
+        entries.push(entry);
+      } catch (error) {
+        errors.push(error instanceof MemoryError ? error.message : `${file}: ${error.message}`);
+      }
     }
   }
   const ids = new Set(entries.map((e) => e.id));
-  for (const e of entries) if (e.supersededBy && !ids.has(e.supersededBy) && !knownIds.has(e.supersededBy)) errors.push(`${label}/${e.id}.md: superseded_by ${e.supersededBy} has no entry`);
+  for (const e of entries) if (e.supersededBy && !ids.has(e.supersededBy) && !knownIds.has(e.supersededBy)) errors.push(`${where.get(e.id)}: superseded_by ${e.supersededBy} has no entry`);
   entries.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
   return { entries, errors };
 }
@@ -190,10 +232,11 @@ const warnOnce = (msg) => {
   console.warn(`memory: ${msg}`);
 };
 
-const unreadableIds = (errors) => new Set(errors.map((e) => /(?:^|\/)memory\/([^/:]+)\.md:/.exec(e)?.[1]).filter(Boolean));
+const unreadableIds = (errors) => new Set(errors.map((e) => /(?:^|\/)memory\/(?:[^/:]+\/)*([^/:]+)\.md:/.exec(e)?.[1]).filter(Boolean));
 
-export function loadMemoryRecall(root, history = [], { warn = warnOnce } = {}) {
-  const { entries, errors } = readMemory(root);
+// `domains`: the bot's domains (hub.workspace.json), see the header.
+export function loadMemoryRecall(root, history = [], { warn = warnOnce, domains = [] } = {}) {
+  const { entries, errors } = readMemory(root, { folders: domainFolders(domains) });
   for (const error of errors) warn(error);
   return memoryRecall(entries, history, { unreadable: unreadableIds(errors) });
 }
@@ -203,7 +246,7 @@ export function loadMemoryRecall(root, history = [], { warn = warnOnce } = {}) {
 // never by shadowing it), so a clash is an error and that file is skipped.
 export function readBotMemory(root, botDir) {
   const label = `${relative(root, botDir).split(sep).join("/")}/${MEMORY_DIR}`;
-  const shared = new Set(readMemory(root).entries.map((e) => e.id));
+  const shared = new Set(readMemory(root, { folders: allMemoryFolders(root) }).entries.map((e) => e.id));
   const { entries, errors } = readMemory(botDir, { label, knownIds: shared });
   const clash = entries.filter((e) => shared.has(e.id));
   for (const e of clash) errors.push(`${label}/${e.id}.md: id ${e.id} is also ${MEMORY_DIR}/${e.id}.md; give it its own id and supersede the other explicitly`);
@@ -231,10 +274,21 @@ export function findBotDir({ env = process.env, cwd = process.cwd() } = {}) {
   return null;
 }
 
+// The domains the bot in `botDir` lists in its hub.workspace.json entry. The
+// bot is its directory name, as in findBotDir.
+export function botDomains(root, botDir) {
+  return readWorkspaceFile(root).agents.find((a) => a.name === basename(botDir))?.domains ?? [];
+}
+
 // For a workspace's tests: throws one MemoryError listing every bad file,
-// shared and per bot (agents/*/memory/). Returns the shared entries.
+// shared (every folder) and per bot (agents/*/memory/), and every domain a bot
+// lists that has no folder. Returns the shared entries.
 export function validateMemory(root) {
-  const { entries, errors } = readMemory(root);
+  const { entries, errors } = readMemory(root, { folders: allMemoryFolders(root) });
+  if (isWorkspace(root)) {
+    const folders = new Set(allMemoryFolders(root));
+    for (const { name, domains = [] } of readWorkspaceFile(root).agents) for (const d of domains) if (!folders.has(d)) errors.push(`hub.workspace.json: ${name} lists domain ${d}, which has no memory/${d}/ folder`);
+  }
   const agents = join(root, "agents");
   if (existsSync(agents)) for (const name of readdirSync(agents).sort()) if (existsSync(join(agents, name, MEMORY_DIR))) errors.push(...readBotMemory(root, join(agents, name)).errors);
   if (errors.length) throw new MemoryError(`${errors.length} bad memory entr${errors.length === 1 ? "y" : "ies"}:\n${errors.join("\n")}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-hub",
-  "version": "0.5.6",
+  "version": "0.6.1",
   "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",
@@ -23,13 +23,20 @@
     "./subagent-cap": "./subagent-cap.mjs",
     "./session-limits": "./session-limits.mjs",
     "./main-instructions": "./main-instructions.mjs",
+    "./execution-context": "./execution-context.mjs",
     "./connections/*": "./connections/*.js",
-    "./bot-token": "./bot-token.mjs"
+    "./bot-token": "./bot-token.mjs",
+    "./prepare": "./prepare.mjs",
+    "./vercel": "./vercel.mjs",
+    "./world": "./world.mjs"
   },
   "peerDependencies": {
     "eve": "*",
     "zod": "4.5.4",
     "@vercel/connect": "^2.4.1",
     "@vercel/oidc": "4.0.0"
+  },
+  "dependencies": {
+    "ai": "^7.0.122"
   }
 }