eve-hub 0.6.19 → 0.6.20

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # eve-hub
 
+## 0.6.20
+
+### Patch Changes
+
+- One syncKit decides every kit stub a bot gets or loses, by where the bot runs. A hub release deletes the stubs of kit modules it removed, in bots and subagents, from a hosted workspace's repo too, so a Mac bot no longer fails to resolve a removed kit tool. A customized file that imports a removed module is reported, not deleted.
+
 ## 0.6.19
 
 ### Patch Changes

package/kit-modules.json

@@ -0,0 +1,42 @@
+[
+  "channels/eve",
+  "channels/eve-roster-user",
+  "connections/vercel-kit",
+  "hooks/mention-gate",
+  "hooks/sandbox",
+  "instructions/engineering",
+  "instructions/main",
+  "instructions/protocol",
+  "memory/bot",
+  "memory/workspace",
+  "schedules/compact",
+  "schedules/dash",
+  "schedules/prune",
+  "skills/onboarding-profile",
+  "tools/agent_send",
+  "tools/apply_tags",
+  "tools/archive_thread",
+  "tools/attach_image",
+  "tools/bash",
+  "tools/browser",
+  "tools/create_agent",
+  "tools/create_thread",
+  "tools/dash_update",
+  "tools/disabled",
+  "tools/list_agents",
+  "tools/list_threads",
+  "tools/move_path",
+  "tools/onboarding_scripts",
+  "tools/post_message",
+  "tools/react",
+  "tools/read_thread",
+  "tools/remove_agent",
+  "tools/restart_agent",
+  "tools/restart_hub",
+  "tools/set_summary",
+  "tools/show",
+  "tools/tag_threads",
+  "tools/unarchive_thread",
+  "tools/update_thread",
+  "tools/view_image"
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-hub",
-  "version": "0.6.19",
+  "version": "0.6.20",
   "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

@@ -20,31 +20,14 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { GITHUB_PATH } from "./github-path.mjs";
-import { KIT_FILES, MAIN_KIT_FILES, REMOVED_KIT_FILES } from "./stubs.mjs";
+import { DEPLOYED_KIT_FILES, KIT_FILES, MAIN_KIT_FILES } from "./stubs.mjs";
+import KIT_MODULES from "./kit-modules.json" with { type: "json" };
+import { applyKit, readBotFiles, syncKit } from "./sync-kit.mjs";
+export { DEPLOYED_KIT_FILES };
 import { deploymentFacts, hostedContext } from "./execution-context.mjs";
 import { botDomains, domainFolders, readBotMemory, readMemory, validateMemory } from "./memory.mjs";
 import { agentRunsOn, readWorkspaceFile, removeWorkspaceAgent } from "./workspace.mjs";
 
-// The kit stubs a deployed main keeps: ones whose whole import closure in the
-// published kit runs in a Vercel function and talks to the hub over HTTP alone
-// (test/workspace-template.test.mjs walks it). Every other kit stub needs the
-// hub's machine: the sandbox hook (it migrates host sessions, and deletes any
-// sandbox that resolves /workspace as itself, which a Vercel Sandbox does),
-// the kit's bash (HostSandbox's root, the daemon's env; eve's own bash runs
-// instead), the browser and the screenshot paths of attach_image/view_image,
-// the mention gate (the
-// daemon's per-process HUB_AGENT and patched model credential), the tools that
-// remove or restart bots on the hub's disk (a deployment changes its roster by
-// commit; create_agent is that commit, made by the hosted hub), memory (the workspace's files), and main's schedules.
-export const DEPLOYED_KIT_FILES = new Set([
-  "channels/eve.ts",
-  "skills/onboarding-profile.ts",
-  "tools/onboarding_scripts.ts",
-  ...["react", "show", "update_thread", "list_threads", "read_thread", "post_message"].map((t) => `tools/${t}.ts`),
-  ...["create_thread", "set_summary", "move_path", "archive_thread", "unarchive_thread", "list_agents", "agent_send", "create_agent", "tag_threads", "dash_update", "apply_tags"].map((t) => `tools/${t}.ts`),
-]);
-
-
 // eve's git extension, for every bot: 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. It only guides: its `pr`
@@ -134,6 +117,11 @@ export function prepareDeployment(dir) {
   validateMemory(dir);
   const definition = readWorkspaceFile(dir);
   const resolved = { ...definition, agents: definition.agents.map((agent) => ({ ...agent, runsOn: agentRunsOn(definition, agent.name) })) };
+  const dirOf = (name) => join(dir, "agents", name, "agent");
+  const local = new Set(resolved.agents.filter((a) => a.runsOn === "local").map((a) => a.name));
+  const folders = readdirSync(join(dir, "agents")).filter((name) => !local.has(name) && existsSync(join(dirOf(name), "agent.ts")));
+  const change = syncKit({ bots: folders.map((name) => ({ name, runsOn: "hosted", files: readBotFiles(dirOf(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")}`);
   writeFileSync(join(dir, MANIFEST_FILE), `${JSON.stringify(resolved, null, 2)}\n`);
   for (const { name } of definition.agents) {
     if (agentRunsOn(definition, name) !== "local") continue;
@@ -142,13 +130,10 @@ 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);
   for (const file of readdirSync(join(dir, "agents"), { recursive: true })) {
     if (!file.endsWith("/agent.ts")) continue;
     const bot = dirname(join(dir, "agents", file));
-    for (const stub of Object.keys({ ...MAIN_KIT_FILES, "memory/workspace.ts": 0, "memory/bot.ts": 0 })) if (!DEPLOYED_KIT_FILES.has(stub) && existsSync(join(bot, stub))) removeStub(bot, stub);
-    for (const stub of REMOVED_KIT_FILES) if (existsSync(join(bot, stub))) removeStub(bot, stub);
-    // learning-review is not in MAIN_KIT_FILES, but also requires the host.
-    if (existsSync(join(bot, "schedules/learning-review.ts"))) removeStub(bot, "schedules/learning-review.ts");
     const name = basename(dirname(bot));
     const code = CODE_BOTS.includes(name);
     for (const [stub, content] of Object.entries({ ...gitExtensionFiles(), ...(code ? codeExtensionFiles(name) : {}) })) {

package/stubs.d.mts

@@ -0,0 +1,6 @@
+export const KIT_FILES: Record<string, string[]>;
+export const MAIN_KIT_FILES: Record<string, string[]>;
+export const DEPLOYED_KIT_FILES: Set<string>;
+export const PROTOCOL_STUB_FILE: string;
+export const PROTOCOL_STUB: string;
+export function kitStub(file: string, options?: { files?: Record<string, string[]> }): string;

package/stubs.mjs

@@ -1,10 +1,6 @@
 // eve finds tools, hooks, and channels by file (the tool name is the file
 // name), so each bot keeps a one-line stub per kit module. Bot file -> what it
 // is, and which kit module it re-exports (default: the same path).
-// Kit files whose module is gone. Sync retires them from every bot, and the
-// hosted deploy prunes them (the change-explainer: its skill and artifact tools).
-export const REMOVED_KIT_FILES = Object.freeze(["tools/artifact_publish.ts", "tools/artifact_status.ts", "tools/artifact_list.ts", "skills/change-explainer.ts"]);
-
 export const KIT_FILES = {
   "channels/eve.ts": ["Queued eve channel that resolves the registry's human as a user.", "channels/eve-roster-user.ts"],
   "hooks/sandbox.ts": ["Migrates legacy Docker sessions to the host sandbox."],
@@ -46,3 +42,106 @@ export const MAIN_KIT_FILES = {
   "schedules/dash.ts": ["When a bot's turn ends (fired by the hub), and every 8 minutes: the human's PRs, a Dash entry for each thread that changed, and a new summary for each track with news."],
   "schedules/prune.ts": ["Every 10 minutes: one prune pass over what archived or deleted threads leave on disk: worktrees, scratch, their-only uploads, idle bots' traces and workflow runs; unsaved work kept as refs/bundles."],
 };
+
+// The kit stubs a deployed main keeps: ones whose whole import closure in the
+// published kit runs in a Vercel function and talks to the hub over HTTP alone
+// (test/workspace-template.test.mjs walks it). Every other kit stub needs the
+// hub's machine: the sandbox hook (it migrates host sessions, and deletes any
+// sandbox that resolves /workspace as itself, which a Vercel Sandbox does),
+// the kit's bash (HostSandbox's root, the daemon's env; eve's own bash runs
+// instead), the browser and the screenshot paths of attach_image/view_image,
+// the mention gate (the
+// daemon's per-process HUB_AGENT and patched model credential), the tools that
+// remove or restart bots on the hub's disk (a deployment changes its roster by
+// commit; create_agent is that commit, made by the hosted hub), memory (the workspace's files), and main's schedules.
+export const DEPLOYED_KIT_FILES = new Set([
+  "channels/eve.ts",
+  "skills/onboarding-profile.ts",
+  "tools/onboarding_scripts.ts",
+  ...["react", "show", "update_thread", "list_threads", "read_thread", "post_message"].map((t) => `tools/${t}.ts`),
+  ...["create_thread", "set_summary", "move_path", "archive_thread", "unarchive_thread", "list_agents", "agent_send", "create_agent", "tag_threads", "dash_update", "apply_tags"].map((t) => `tools/${t}.ts`),
+]);
+
+// ---- stub text: what each kit stub file says ----
+
+export const kitPath = (kit) => `eve-hub/${kit.replace(/\.(ts|mjs|js)$/, "")}`;
+
+export function kitStub(file, { files = KIT_FILES, kit = files[file]?.[1] ?? file, what = files[file]?.[0] } = {}) {
+  return `// ${what} From eve-hub (packages/agent-kit/${kit}).\nexport { default } from "${kitPath(kit)}";\n`;
+}
+
+// Every bot but main: instructions.md says who the bot is (its head), and
+// instructions/protocol.ts re-exports the kit's protocol, which renders
+// packages/agent-kit/templates/workspace-protocol.md at build time. eve appends the
+// instructions/ entries after instructions.md, so the protocol follows the head
+// and is never copied into a bot.
+export const PROTOCOL_STUB_FILE = "instructions/protocol.ts";
+export const PROTOCOL_STUB = `// The workspace protocol every bot shares, from packages/agent-kit/templates/workspace-protocol.md,
+// through eve-hub (packages/agent-kit/instructions/protocol.ts). eve appends it after
+// instructions.md, which holds only who this bot is. Don't copy the protocol there.
+export { default } from "eve-hub/instructions/protocol";
+`;
+// Every bot (main too): instructions/execution-context.ts renders the bot's
+// execution context from its definition in hub.workspace.json
+// (packages/agent-kit/execution-context.mjs). A hosted bot's is replaced by
+// the Vercel build with the hosted page.
+export const EXECUTION_CONTEXT_STUB_FILE = "instructions/execution-context.ts";
+export const executionContextStub = (name) => `import { defineInstructions } from "eve/instructions";
+import { executionContext } from "eve-hub/execution-context";
+import workspace from "../../../../hub.workspace.json" with { type: "json" };
+
+// Where ${name} runs, from its definition in hub.workspace.json: local, from the kit's
+// templates (packages/agent-kit/templates/execution-context-*.md). The Vercel build writes a hosted bot's.
+export default defineInstructions({ content: executionContext(${JSON.stringify(name)}, workspace) });
+`;
+
+// Every bot (main too) has two memory slots: memory/workspace.ts recalls the
+// workspace's memory/ entries and memory/bot.ts the bot's own
+// agents/<bot>/memory/ entries, every turn (packages/agent-kit/memory/).
+const memoryStub = (slot, what) => `// ${what}, recalled every turn. From eve-hub
+// (packages/agent-kit/memory/${slot}.ts); add or supersede entries there, not here.
+export { default } from "eve-hub/memory/${slot}";
+`;
+export const MEMORY_STUBS = {
+  "memory/workspace.ts": memoryStub("workspace", "The workspace's memory/ entries"),
+  "memory/bot.ts": memoryStub("bot", "This bot's own agents/<bot>/memory/ entries"),
+};
+
+// main's instructions aren't copied into a workspace: agent/instructions.ts
+// re-exports the kit's, which renders packages/agent-kit/templates/main-instructions.md +
+// workspace-protocol.md at build time (packages/agent-kit/main-instructions.mjs).
+// Workspace-only additions go in agent/instructions/*.md; eve appends them.
+export const MAIN_INSTRUCTIONS = "instructions.ts";
+export const MAIN_INSTRUCTIONS_STUB = `// main's instructions, from packages/agent-kit/templates (main-instructions.md + workspace-protocol.md),
+// through eve-hub (packages/agent-kit/instructions/main.ts). Don't copy them here:
+// workspace-only additions go in instructions/*.md next to this file, appended after these.
+export { default } from "eve-hub/instructions/main";
+`;
+
+// True when the file's only code is `export { default } from "eve-hub/<module>"`
+// (main's instructions by default). Comments are stripped first, so a
+// commented-out import doesn't count, and anything else in the file (an
+// override, a second export) makes it custom.
+export function isKitReexport(source, module = "instructions/main") {
+  const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "").trim();
+  const escaped = module.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+  return new RegExp(`^export\\s*\\{\\s*default\\s*\\}\\s*from\\s*(["'])eve-hub\\/${escaped}\\1\\s*;?$`).test(code);
+}
+
+
+// Where a bot's instructions come from, given its files ({ "instructions.md": text, ... }):
+// main ("kit", "copy", "custom", "conflict", "missing"), or any other bot (the protocol:
+// "kit", "copy", "conflict", "custom", "missing").
+const PROTOCOL_HEADING = /^## How this workspace works\s*$/m;
+export function instructionsSource(files, main) {
+  const has = (file) => typeof files[file] === "string";
+  if (main) {
+    if (has(MAIN_INSTRUCTIONS) && has("instructions.md")) return "conflict";
+    if (has(MAIN_INSTRUCTIONS)) return isKitReexport(files[MAIN_INSTRUCTIONS]) ? "kit" : "custom";
+    return has("instructions.md") ? "copy" : "missing";
+  }
+  const copy = has("instructions.md") && PROTOCOL_HEADING.test(files["instructions.md"]);
+  if (!has(PROTOCOL_STUB_FILE)) return copy ? "copy" : "missing";
+  if (copy) return "conflict";
+  return isKitReexport(files[PROTOCOL_STUB_FILE], "instructions/protocol") ? "kit" : "custom";
+}

package/sync-kit.d.mts

@@ -0,0 +1,12 @@
+export type KitBot = { name: string; runsOn: 'local' | 'hosted'; files: Record<string, string> };
+export type KitChange = {
+  write: { bot: string; file: string; content: string }[];
+  delete: { bot: string; file: string }[];
+  report: { bot: string; file: string; reason: string }[];
+  instructions: Record<string, string>;
+};
+export function syncKit(input: { bots: KitBot[]; modules: Iterable<string> }): KitChange;
+export function isKitFile(file: string): boolean;
+export function readBotFiles(agentDir: string): Record<string, string>;
+export function applyKit(change: Pick<KitChange, 'write' | 'delete'>, dirOf: (bot: string) => string): void;
+export function kitModules(kitDir: string): string[];

package/sync-kit.mjs

@@ -0,0 +1,126 @@
+// The one place that decides which kit stub files a bot should have. Given each bot's files and the
+// kit's modules it returns the whole change (what to write, what to delete) and touches nothing.
+// The local sync (lib/agent-template.mjs), the hosted deploy (prepare.mjs) and the hosted kit bump
+// (hosted-hub/src/onboard/repo-bump.ts) apply what it returns; none keeps its own list.
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  DEPLOYED_KIT_FILES, EXECUTION_CONTEXT_STUB_FILE, KIT_FILES, MAIN_INSTRUCTIONS, MAIN_INSTRUCTIONS_STUB, MAIN_KIT_FILES, MEMORY_STUBS, PROTOCOL_STUB, PROTOCOL_STUB_FILE,
+  executionContextStub, instructionsSource, isKitReexport, kitPath, kitStub,
+} from "./stubs.mjs";
+
+const KIT_DIRS = ["tools", "skills", "hooks", "channels", "schedules", "instructions", "memory", "connections"];
+const SUBAGENT = /^(?:subagents\/[^/]+\/)+/;
+const STUB_FILE = new RegExp(`^(${KIT_DIRS.join("|")})/[^/]+\\.ts$`);
+const KIT_IMPORT = new RegExp(`^\\s*(?:import|export)\\b(?:[^;"']*?\\bfrom)?\\s*["']eve-hub/((?:${KIT_DIRS.join("|")})/[\\w-]+)["']`, "gm");
+const ALL_STUBS = { ...KIT_FILES, ...MAIN_KIT_FILES };
+const HOST_ONLY = [...Object.keys(ALL_STUBS), ...Object.keys(MEMORY_STUBS)].filter((file) => !DEPLOYED_KIT_FILES.has(file));
+const moduleOf = (file) => (MEMORY_STUBS[file] ? file.slice(0, -3) : kitPath(ALL_STUBS[file][1] ?? file).slice("eve-hub/".length));
+const HOST_ONLY_MODULES = new Set(HOST_ONLY.map(moduleOf));
+
+/** Whether `file` (relative to a bot's agent/ folder, subagents included) is one syncKit reads. */
+export const isKitFile = (file) => file === "instructions.md" || file === MAIN_INSTRUCTIONS || STUB_FILE.test(file.replace(SUBAGENT, ""));
+
+// Every kit module the file imports, from its import and export lines only.
+function kitImports(text) {
+  const code = text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
+  return [...code.matchAll(KIT_IMPORT)].map((m) => m[1]);
+}
+
+/**
+ * bots: [{ name, runsOn, files }], files being { "<path under agents/<name>/agent>": text } for the files
+ * isKitFile accepts (a subagent's are under "subagents/<x>/"). modules: every kit module a stub may import
+ * ("tools/post_message"). runsOn "local" gets the whole kit, execution-context and memory stubs included;
+ * "hosted" only the stubs a Vercel function can run (DEPLOYED_KIT_FILES) and loses the others, which the
+ * build writes itself (memory, execution context) or cannot use.
+ * Returns { write, delete, report, instructions }: write [{ bot, file, content }] (a file that exists is
+ * replaced), delete [{ bot, file }], report [{ bot, file, reason }] for a customized file that imports a
+ * module the kit lacks, or that a hosted bot can't run (never touched: a person's call; a caller
+ * that ships the result should refuse it), instructions { [bot]: source }.
+ * Only a plain kit re-export is deleted or replaced.
+ */
+export function syncKit({ bots, modules }) {
+  const kit = new Set(modules);
+  const change = { write: [], delete: [], report: [], instructions: {} };
+  for (const { name: bot, runsOn, files: found } of bots) {
+    if (runsOn !== "local" && runsOn !== "hosted") throw new Error(`${bot}: runsOn must be "local" or "hosted", not ${JSON.stringify(runsOn)}`);
+    const local = runsOn === "local";
+    const main = bot === "main";
+    const stubs = main ? MAIN_KIT_FILES : KIT_FILES;
+    const files = { ...found };
+    const write = (file, content) => {
+      files[file] = content;
+      change.write.push({ bot, file, content });
+    };
+    let source = instructionsSource(files, main);
+    if (source === "missing") {
+      write(main ? MAIN_INSTRUCTIONS : PROTOCOL_STUB_FILE, main ? MAIN_INSTRUCTIONS_STUB : PROTOCOL_STUB);
+      source = "kit";
+    }
+    change.instructions[bot] = source;
+    const wanted = new Set(Object.keys(stubs).filter((file) => local || DEPLOYED_KIT_FILES.has(file)));
+    if (local) {
+      wanted.add(EXECUTION_CONTEXT_STUB_FILE);
+      for (const file of Object.keys(MEMORY_STUBS)) wanted.add(file);
+    }
+    const content = (file) => (file === EXECUTION_CONTEXT_STUB_FILE ? executionContextStub(bot) : MEMORY_STUBS[file] ?? kitStub(file, { files: stubs }));
+    for (const file of Object.keys(files).sort()) {
+      const rel = file.replace(SUBAGENT, "");
+      if (!STUB_FILE.test(rel)) continue;
+      const imports = kitImports(files[file]);
+      const gone = imports.find((module) => !kit.has(module));
+      if (gone) {
+        if (!isKitReexport(files[file], gone)) change.report.push({ bot, file, reason: `imports eve-hub/${gone}, which the kit no longer has` });
+        else if (rel === file && wanted.has(file)) write(file, content(file));
+        else change.delete.push({ bot, file });
+      } else if (!local) {
+        const host = imports.find((module) => HOST_ONLY_MODULES.has(module));
+        if (!host) continue;
+        if (isKitReexport(files[file], host)) change.delete.push({ bot, file });
+        else change.report.push({ bot, file, reason: `imports eve-hub/${host}, which needs the hub's own machine` });
+      }
+    }
+    for (const file of wanted) if (files[file] === undefined) write(file, content(file));
+  }
+  return change;
+}
+
+/** The files syncKit looks at in one bot's agent/ folder, its subagents' too. */
+export function readBotFiles(agentDir, prefix = "") {
+  const files = {};
+  const read = (file) => {
+    if (existsSync(join(agentDir, file))) files[prefix + file] = readFileSync(join(agentDir, file), "utf8");
+  };
+  if (!prefix) {
+    read("instructions.md");
+    read(MAIN_INSTRUCTIONS);
+  }
+  for (const dir of KIT_DIRS) {
+    if (!existsSync(join(agentDir, dir))) continue;
+    for (const entry of readdirSync(join(agentDir, dir), { withFileTypes: true })) if (entry.isFile() && entry.name.endsWith(".ts")) read(`${dir}/${entry.name}`);
+  }
+  if (existsSync(join(agentDir, "subagents"))) {
+    for (const entry of readdirSync(join(agentDir, "subagents"), { withFileTypes: true })) {
+      if (entry.isDirectory()) Object.assign(files, readBotFiles(join(agentDir, "subagents", entry.name), `${prefix}subagents/${entry.name}/`));
+    }
+  }
+  return files;
+}
+
+/** Applies a change to disk; dirOf(bot) is the bot's agent/ folder. Deleting a stub removes the folders it leaves empty. */
+export function applyKit(change, dirOf) {
+  for (const { bot, file } of change.delete) {
+    const dir = dirOf(bot);
+    unlinkSync(join(dir, file));
+    for (let d = dirname(file); d !== "." && !readdirSync(join(dir, d)).length; d = dirname(d)) rmdirSync(join(dir, d));
+  }
+  for (const { bot, file, content } of change.write) {
+    mkdirSync(dirname(join(dirOf(bot), file)), { recursive: true });
+    writeFileSync(join(dirOf(bot), file), content);
+  }
+}
+
+/** Every module a stub may import, read from the kit folder; kit-modules.json is this list (test/sync-kit.test.mjs). */
+export function kitModules(kitDir) {
+  return KIT_DIRS.flatMap((dir) => (existsSync(join(kitDir, dir)) ? readdirSync(join(kitDir, dir)).filter((f) => f.endsWith(".ts")).map((f) => `${dir}/${f.slice(0, -3)}`) : [])).sort();
+}