eve-hub 0.0.0-stage → 0.4.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# eve-hub
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The bot-side code every hub agent shares (milestone M3 in [`docs/architecture`](../../docs/architecture/README.md#milestones); D0, D12). Bots live in a workspace (their own repo, [`docs/workspace.md`](../../docs/workspace.md)); each keeps a one-line stub per file and the code lives here once.
+
+| Module | What it is | Bots use it as |
+|---|---|---|
+| `tools/rename_thread.ts`, `list_threads.ts`, `read_thread.ts`, `react.ts`, `show.ts`, `attach_image.ts`, `browser.ts` | Registry and workspace tools (`defineTool`) | `agent/tools/<same name>.ts` |
+| `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"` |
+| `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()], turnPolicy: "queue" })`: queued mentions, 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 |
+| `tools/disabled.ts` | `disableTool()`: removes an eve default tool | the read-only preset's `agent/tools/write_file.ts` |
+| `host-sandbox.ts`, `host-browser.ts` | `HostSandbox` (the host machine is the sandbox) and each session's headless Chromium | `agent/sandbox.ts` imports `HostSandbox` |
+| `roster-model.mjs` | `bindRoster(workspace)`: `rosterModel(name, …)` (the dynamic `model` for agent.ts), `rosterLimits`, `agents` and `subagentCap`, for the `hub.workspace.json` the bot imports; `rosterModel` / `rosterLimits` read from disk for bots scaffolded before it; `createRosterModel({ agents, subagentCap })`: the same for a given roster | `bindRoster(workspace)` in agent.ts |
+| `session-limits.mjs` | `sessionLimits(roster, name)`: a bot's eve `limits` (no session timeout, per-session usage limits from `hub.workspace.json` over the default backstop) | `limits: rosterLimits("<name>")` from `eve-hub/roster-model` |
+| `workspace.mjs` | Reads and validates `hub.workspace.json`, assigns ports, finds a bot's workspace (`HUB_WORKSPACE`, else up from cwd) | the daemon (`lib/workspace-root.mjs`) and `roster-model.mjs` |
+| `workspace-roster.mjs` | `agents`, `humans`, `SUBAGENT_CAP` of the bot's workspace, read from disk | older subagents that resolve their capped model |
+| `bot-model.mjs`, `subagent-cap.mjs` | Model parsing/selection and the subagent cap | via `roster-model.mjs`; subagents import `subagent-cap.mjs` |
+
+The `hubChannel` from D0 isn't here yet. Turn lifecycle and replies are owned by the registry's eve stream consumer; agents do not report them through hooks.
+
+## How a bot uses it
+
+eve discovers tools, hooks, and channels by file under `agent/tools`, `agent/hooks`, and `agent/channels`. A tool's name is its file name, so the file has to exist in the bot. The stub just re-exports the kit's default:
+
+```ts
+// agents/<bot>/agent/tools/rename_thread.ts
+export { default } from "eve-hub/tools/rename_thread";
+```
+
+`sandbox.ts` stays a small module of its own, because each agent and subagent declares its own `environment`:
+
+```ts
+import { defineSandbox } from "eve/sandbox";
+import { HostSandbox } from "eve-hub/host-sandbox";
+export const environment = HostSandbox.environment();
+export default defineSandbox(() => environment.open());
+```
+
+`lib/agent-template.mjs` (`KIT_FILES`, `MAIN_KIT_FILES`, `PRESETS`, `kitStub`, `hostSandboxFile`) writes these files: `scaffoldMain` for `hub workspace init`, `scaffoldAgent` for `create_agent`. `test/agent-kit.test.mjs` checks that they match.
+
+A bot's role is enforced by its files as well as its prose. `create_agent`'s `preset` picks them: `builder` (the default) has every tool; `read-only` (planners, reviewers) adds `agent/tools/write_file.ts` → `tools/disabled.ts`, so it reads code, runs tests and delegates `agent` copies (which share its tool set) but can't edit files by tool. Its bash is the kit's regular bash, with no approval step.
+
+## The package import (D12)
+
+1. Before spawning the bots, the daemon links the kit (`lib/workspace-link.mjs`): `<workspace>/.hub/eve-hub` and `<workspace>/node_modules/eve-hub` → `<hub>/packages/agent-kit`. If the workspace has no `eve`/`zod` of its own, they are linked to hub's install too. The daemon only replaces links it created, never a real install.
+2. The workspace's `package.json` depends on `"eve-hub": "link:.hub/eve-hub"` (`workspace init` writes it), so a later `pnpm install` keeps resolving the kit the same way.
+3. The stubs use the specifiers the `exports` map serves (`eve-hub/tools/x`, `eve-hub/host-sandbox`, `eve-hub/roster-model`, …).
+4. `eve` and `zod` are peer dependencies. eve's bundler resolves the kit to its realpath, so the kit's own `eve` imports come from hub's install. When the workspace's eve is linked to hub's, that's one eve (verified with eve 0.69).
+
+Bump `version` when a tool's name, schema, or description, the hook's events, or the channel config changes. Hub records each agent's kit version and accepts N and N−1 (D0/D12).
+
+## 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.
+
+`.github/workflows/publish-eve-hub.yml` publishes it on every push to main whose kit `version` npm doesn't have yet, authenticated by the repo's `NPM_TOKEN` secret (an npm automation token). Bump `version` to ship a kit change to deployed workspaces; 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.
+
+## Vercel Kit connection
+
+An agent opts into the app's Kit connector with `agent/connections/vercel-kit.ts`:
+
+```ts
+export { default } from "eve-hub/connections/vercel-kit";
+```
+
+Set `KIT_CONNECTOR` to the returned Vercel Connect connector UID in Hub's
+`.env.local` (or its process environment). Hub's daemon loads that file before
+starting agents. This app uses `kit.vercel.sh/hub`, attached to
+`vercel-internal-playground/06-agents-only-one-project`.
+All agents importing this connection share the connector; Connect authorizes
+each authenticated roster user separately. Missing or blank configuration
+returns no connection. Connector configuration is re-read at each turn.
+
+Hub's local channel derives a user principal from the registry's `x-roster-user`
+header only during local development. Callers without an authenticated user
+cannot use this user-scoped connection. Each user completes Eve's sign-in
+challenge when first using Kit. Kit action approvals are separate from sign-in:
+when Kit returns `consent_required`, present its approval link and resume its
+saved run only after the user decides.
+
+For another Hub app, create and attach its own connector from its linked project:
+
+```sh
+vercel connect create kit.vercel.sh/api/mcp --name my-hub --yes
+vercel connect attach <returned-connector-uid> --yes
+```
+
+Use `vercel env pull` to refresh local project credentials when needed; preserve
+local settings before pulling because it replaces the destination file. Restart
+an idle agent after adding its connection stub or updating its environment.
+Validate by completing sign-in and asking for one read from a connected service.
+Compilation and mocked authorization tests do not prove a live service read.
+
+Reference: [Kit integration guide](https://app.notion.com/p/3dfe06b059c480778efaf967196764a8).

package/artifacts/core.mjs

@@ -0,0 +1,221 @@
+// Artifacts: a versioned static site a bot publishes and keeps current, such
+// as a change explainer. The core is type-agnostic. A type (artifacts/types/)
+// builds the site and its card from a source, and says whether a published
+// version is still current.
+//
+// The session that publishes an artifact owns it. Its record lives in that
+// session's state (the tools keep it in defineState("hub.artifacts")), and
+// every deployment also carries its own artifact.json with the full history.
+// The tool result carries the record, so the registry folds it into its
+// read-only index (GET /api/artifacts) and the thread's card.
+//
+// Publishing a version:
+//   1. the type builds the site, its card fields, and a thumbnail
+//   2. artifact.json (record + history) is written into the site
+//   3. `vercel deploy --prebuilt` to the hub-artifacts project, tagged with
+//      --meta artifact=<slug> --meta version=<n>
+//   4. the stable alias <slug>.<domain> moves to it, unless another session
+//      published a newer version meanwhile
+//   5. the site goes to the registry, which serves it at /artifacts/<id>/v<n>/
+//      for the hub's inline preview (no Vercel sign-in)
+//   6. deployments older than the last KEEP versions are removed
+import { execFile } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import changeExplainer from "./types/change-explainer.mjs";
+
+import { registryFetch } from "../registry-fetch.mjs";
+const SCOPE = process.env.HUB_ARTIFACTS_SCOPE ?? "vercel-internal-playground";
+const PROJECT = process.env.HUB_ARTIFACTS_PROJECT ?? "hub-artifacts";
+const DOMAIN = process.env.HUB_ARTIFACTS_DOMAIN ?? "playground-vercel.tools";
+const WORK = process.env.HUB_ARTIFACTS_WORK ?? join(process.env.HUB_HOME ?? join(homedir(), ".hub"), "artifacts");
+export const KEEP = 5;
+
+export const TYPES = { "change-explainer": changeExplainer };
+export const STATE_NAME = "hub.artifacts";
+
+export const artifactId = (type, key) => `${type}:${key}`;
+// A DNS label (at most 63 characters): the alias host and the --meta tag.
+export function slugOf(id) {
+  const slug = id.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug.length <= 63 ? slug : slug.slice(0, 63).replace(/-+$/, "");
+}
+export const aliasOf = (id) => `${slugOf(id)}.${DOMAIN}`;
+export const previewPath = (id, version) => `/artifacts/${encodeURIComponent(id)}/v${version}/`;
+
+export function typeOf(name) {
+  const type = TYPES[name];
+  if (!type) throw new Error(`unknown artifact type ${JSON.stringify(name)} (known: ${Object.keys(TYPES).join(", ")})`);
+  return type;
+}
+
+export function run(cmd, args, { cwd, input, timeoutMs = 600_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = execFile(cmd, args, { cwd, maxBuffer: 64 << 20, timeout: timeoutMs, env: { ...process.env, FORCE_COLOR: "0" } }, (error, stdout, stderr) => {
+      if (error) {
+        const tail = String(stderr || stdout || "").trim().split("\n").slice(-6).join("\n");
+        reject(new Error(`${cmd} ${args[0] ?? ""} failed: ${tail || error.message}`));
+      } else resolve(String(stdout));
+    });
+    if (input !== undefined) child.stdin.end(input);
+    else child.stdin.end();
+  });
+}
+
+// The registry's copy of an artifact (owner, latest version), or null.
+export async function registryRecord(id, fetchImpl = fetch) {
+  const res = await registryFetch(`/api/artifacts/${encodeURIComponent(id)}`, {}, { fetchImpl }).catch(() => null);
+  if (!res?.ok) return null;
+  return res.json().catch(() => null);
+}
+
+// The newest record this session can see: its own state or, for a fork or
+// another session picking an artifact up, the registry's index.
+export async function latestRecord(id, stateRecords, fetchImpl = fetch) {
+  const mine = stateRecords?.[id] ?? null;
+  const hub = await registryRecord(id, fetchImpl);
+  if (!hub) return mine;
+  if (!mine) return stripOwner(hub);
+  return (hub.version ?? 0) > (mine.version ?? 0) ? stripOwner(hub) : mine;
+}
+const stripOwner = ({ owner, ...record }) => record;
+
+function projectLink() {
+  const dir = join(WORK, "vercel-link");
+  const file = join(dir, ".vercel", "project.json");
+  return { dir, file };
+}
+
+async function ensureProject() {
+  const { dir, file } = projectLink();
+  if (existsSync(file)) return file;
+  mkdirSync(dir, { recursive: true });
+  await run("vercel", ["link", "--yes", "--project", PROJECT, "--scope", SCOPE], { cwd: dir });
+  if (!existsSync(file)) throw new Error(`vercel link didn't write ${file}`);
+  return file;
+}
+
+// A Build Output API v3 tree around the site: static files, no SPA fallback
+// (artifact sites route with the hash), the target pinned to preview.
+function stage(site, slug, version) {
+  const dir = mkdtempSync(join(tmpdir(), `artifact-${slug}-v${version}-`));
+  const output = join(dir, ".vercel", "output");
+  cpSync(site, join(output, "static"), { recursive: true });
+  writeFileSync(
+    join(output, "config.json"),
+    JSON.stringify({
+      version: 3,
+      routes: [{ src: "/(.*)", headers: { "x-robots-tag": "noindex", "referrer-policy": "no-referrer" }, continue: true }, { handle: "filesystem" }],
+    }),
+  );
+  writeFileSync(join(output, "builds.json"), JSON.stringify({ target: "preview", builds: [] }));
+  return dir;
+}
+
+async function deploy(site, slug, version) {
+  const link = await ensureProject();
+  const dir = stage(site, slug, version);
+  try {
+    cpSync(link, join(dir, ".vercel", "project.json"));
+    const out = await run("vercel", ["deploy", "--prebuilt", "--target", "preview", "--scope", SCOPE, "--yes", "--meta", `artifact=${slug}`, "--meta", `version=${version}`], { cwd: dir });
+    const url = out.trim().split(/\s+/).reverse().find((w) => /^https:\/\/\S+$/.test(w));
+    if (!url) throw new Error(`vercel deploy printed no URL: ${out.slice(-300)}`);
+    return url;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+async function uploadBundle(site, id, version, fetchImpl) {
+  const tar = await new Promise((resolve, reject) =>
+    execFile("tar", ["-czf", "-", "-C", site, "."], { encoding: "buffer", maxBuffer: 1 << 30 }, (error, stdout) => (error ? reject(error) : resolve(stdout))),
+  );
+  const res = await registryFetch(`/api/artifacts/${encodeURIComponent(id)}/v/${version}/bundle`, {
+    method: "POST",
+    headers: { "content-type": "application/gzip" },
+    body: tar,
+    signal: AbortSignal.timeout(120_000),
+  }, { fetchImpl });
+  if (!res.ok) throw new Error(`preview upload failed: ${(await res.json().catch(() => ({}))).error ?? res.status}`);
+  return previewPath(id, version);
+}
+
+async function uploadThumbnail(path, fetchImpl) {
+  if (!path || !existsSync(path)) return undefined;
+  const res = await registryFetch(`/api/uploads`, {
+    method: "POST",
+    headers: { "content-type": "application/octet-stream", "x-filename": "thumbnail.png" },
+    body: readFileSync(path),
+    signal: AbortSignal.timeout(30_000),
+  }, { fetchImpl }).catch(() => null);
+  if (!res?.ok) return undefined;
+  return (await res.json()).id;
+}
+
+// Removes deployments older than the last KEEP versions; best effort.
+async function prune(history) {
+  const old = history.slice(0, Math.max(0, history.length - KEEP)).filter((h) => h.url && !h.removed);
+  for (const h of old) {
+    await run("vercel", ["rm", h.url, "--yes", "--scope", SCOPE], { timeoutMs: 60_000 }).then(
+      () => (h.removed = true),
+      () => {},
+    );
+  }
+}
+
+/**
+ * Publishes the next version of `type:key` from `source`. `prior` is the
+ * newest record this session knows (latestRecord). Returns the new record.
+ * `deps` swaps the side effects out in tests.
+ */
+export async function publish({ type: typeName, key, source }, prior, deps = {}) {
+  const type = typeOf(typeName);
+  const id = artifactId(typeName, key);
+  const slug = slugOf(id);
+  const fetchImpl = deps.fetch ?? fetch;
+  const version = (prior?.version ?? 0) + 1;
+  const work = mkdtempSync(join(tmpdir(), `artifact-build-${slug}-`));
+  try {
+    const built = await (deps.build ?? type.build)(source, { work, id, version });
+    const now = new Date().toISOString();
+    const history = [...(prior?.history ?? []), { version, at: now, ...(built.meta?.head ? { head: built.meta.head } : {}) }];
+    const record = {
+      id,
+      type: typeName,
+      key,
+      version,
+      status: "fresh",
+      card: { ...built.card, updatedAt: now },
+      source,
+      meta: built.meta ?? {},
+      history,
+      updatedAt: now,
+    };
+    writeFileSync(join(built.site, "artifact.json"), JSON.stringify(record, null, 2));
+    const url = await (deps.deploy ?? deploy)(built.site, slug, version);
+    history.at(-1).url = url;
+    record.url = url;
+    // Another session may have moved the alias on while this one built.
+    const current = await registryRecord(id, fetchImpl);
+    if ((current?.version ?? 0) >= version) {
+      throw new Error(`${id} v${current.version} was published by ${current.owner?.bot ?? "another session"} while this one built v${version}; run artifact_status and publish again`);
+    }
+    const alias = aliasOf(id);
+    await (deps.alias ?? ((u, a) => run("vercel", ["alias", "set", u, a, "--scope", SCOPE])))(url, alias);
+    record.alias = `https://${alias}`;
+    record.preview = await (deps.uploadBundle ?? uploadBundle)(built.site, id, version, fetchImpl);
+    const thumbnail = await (deps.uploadThumbnail ?? uploadThumbnail)(built.thumbnail, fetchImpl);
+    if (thumbnail) record.card.thumbnail = thumbnail;
+    await (deps.prune ?? prune)(history);
+    return record;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** What the type says about a published record: { status, reasons[] }. */
+export async function status(record) {
+  const type = typeOf(record.type);
+  return type.status ? type.status(record) : { status: record.status ?? "fresh", reasons: [] };
+}

package/artifacts/state.d.ts

@@ -0,0 +1 @@
+export declare const artifacts: any;

package/artifacts/state.js

@@ -0,0 +1,5 @@
+// The owning session's artifact records, id -> latest record. Durable eve
+// session state: it survives restarts like the rest of the session.
+import { defineState } from "eve/context";
+import { STATE_NAME } from "./core.mjs";
+export const artifacts = defineState(STATE_NAME, () => ({}));

package/artifacts/types/change-explainer.mjs

@@ -0,0 +1,106 @@
+// The change-explainer artifact type: a narrated walkthrough of a PR or a
+// stack (packages/explainer), built from a fixture (fixture.json,
+// overview.json, sequence.json) and a read-only checkout of the repo.
+//
+// source: { fixture: <fixture dir>, repo: <git checkout>, scip?: <index.scip>, branch?: <ref the change lives on> }
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { hubPath } from "../../hub-path.mjs";
+
+// packages/explainer, resolved per call: eve bundles this module into the
+// workspace's module cache, so import.meta.dirname isn't in the hub checkout.
+const explainerDir = () => hubPath(join("packages", "explainer"), { probe: join("scripts", "build-data.mjs") });
+
+// packages/explainer has its own lockfile, outside the hub's pnpm workspace,
+// so the hub's install doesn't cover it. Say so up front rather than failing
+// halfway through build-data on a missing import.
+function explainerReady() {
+  const dir = explainerDir();
+  if (!existsSync(join(dir, "node_modules", "@sourcegraph", "scip-typescript"))) {
+    throw new Error(`the explainer's dependencies aren't installed: run \`pnpm install --ignore-workspace --frozen-lockfile\` in ${dir}`);
+  }
+  return dir;
+}
+
+const node = (script, args, dir = explainerDir()) => {
+  return new Promise((ok, fail) =>
+    execFile(process.execPath, [join(dir, "scripts", script), ...args], { cwd: dir, maxBuffer: 64 << 20, timeout: 900_000 }, (error, stdout, stderr) =>
+      error ? fail(new Error(`${script} failed: ${String(stderr || error.message).trim().split("\n").slice(-6).join("\n")}`)) : ok(String(stdout)),
+    ),
+  );
+};
+
+const git = (repo, ...args) =>
+  new Promise((ok, fail) => execFile("git", ["-C", repo, ...args], (error, stdout) => (error ? fail(error) : ok(String(stdout).trim()))));
+
+const readJson = (path) => JSON.parse(readFileSync(path, "utf8"));
+
+export function firstSentence(text = "") {
+  const sentence = String(text).trim().split(/(?<=[.!?])\s+(?=[A-Z"'`(])/, 1)[0] ?? "";
+  return sentence.length > 220 ? `${sentence.slice(0, 219).replace(/\s+\S*$/, "")}…` : sentence;
+}
+
+function checkSource(source) {
+  if (!source || typeof source !== "object") throw new Error("change-explainer source must be { fixture, repo, scip?, branch? }");
+  for (const key of ["fixture", "repo"]) if (typeof source[key] !== "string" || !existsSync(source[key])) throw new Error(`change-explainer source.${key}: no such path ${JSON.stringify(source[key])}`);
+  if (!existsSync(join(source.fixture, "fixture.json"))) throw new Error(`no fixture.json in ${source.fixture}`);
+  if (source.scip && !existsSync(source.scip)) throw new Error(`change-explainer source.scip: no such file ${source.scip}`);
+}
+
+// Card fields from the fixture: what the change is, and which commits.
+export function cardOf(fixture, overview) {
+  const short = (sha) => String(sha ?? "").slice(0, 9);
+  const prs = (fixture.prs ?? []).map((p) => `#${p.number}`);
+  return {
+    title: fixture.title ?? fixture.id,
+    gist: firstSentence(overview?.thesis),
+    subtitle: [fixture.repo, prs.join(" ")].filter(Boolean).join(" "),
+    ref: `${short(fixture.base)}..${short(fixture.head)}`,
+  };
+}
+
+async function build(source, { work }) {
+  checkSource(source);
+  const fixture = readJson(join(source.fixture, "fixture.json"));
+  const overviewPath = join(source.fixture, "overview.json");
+  const overview = existsSync(overviewPath) ? readJson(overviewPath) : null;
+  const data = join(work, "data");
+  const site = join(work, "site");
+  const dir = explainerReady();
+  await node("build-data.mjs", ["--fixture", source.fixture, "--repo", source.repo, ...(source.scip ? ["--scip", source.scip] : []), "--out", data], dir);
+  await node("build.mjs", ["--out", site, "--data", data, "--fixture", fixture.id], dir);
+  const thumbnail = join(work, "thumbnail.png");
+  await node("thumbnail.mjs", [site, thumbnail], dir).catch(() => {});
+  const [base, head] = await Promise.all([git(source.repo, "rev-parse", `${fixture.base}^{commit}`), git(source.repo, "rev-parse", `${fixture.head}^{commit}`)]);
+  return {
+    site,
+    thumbnail: existsSync(thumbnail) ? thumbnail : undefined,
+    card: cardOf(fixture, overview),
+    meta: { repo: fixture.repo, base, head, prs: (fixture.prs ?? []).map((p) => p.number) },
+  };
+}
+
+// Whether the published version still describes the change. This checks the
+// pinned range against the fixture and, with source.branch, the branch head;
+// which parts went stale (snippet hashes, re-anchoring) is the next step.
+async function status(record) {
+  const { source = {}, meta = {} } = record;
+  const reasons = [];
+  if (record.status === "merged" || record.status === "closed") return { status: record.status, reasons };
+  try {
+    const fixture = readJson(join(source.fixture, "fixture.json"));
+    const [base, head] = await Promise.all([git(source.repo, "rev-parse", `${fixture.base}^{commit}`), git(source.repo, "rev-parse", `${fixture.head}^{commit}`)]);
+    if (base !== meta.base) reasons.push(`the fixture's base is now ${base.slice(0, 9)} (published at ${String(meta.base).slice(0, 9)})`);
+    if (head !== meta.head) reasons.push(`the fixture's head is now ${head.slice(0, 9)} (published at ${String(meta.head).slice(0, 9)})`);
+    if (source.branch) {
+      const tip = await git(source.repo, "rev-parse", `${source.branch}^{commit}`);
+      if (tip !== meta.head) reasons.push(`${source.branch} is at ${tip.slice(0, 9)}, ahead of the published head ${String(meta.head).slice(0, 9)}`);
+    }
+  } catch (error) {
+    reasons.push(`couldn't read the source: ${error.message}`);
+  }
+  return { status: reasons.length ? "stale" : "fresh", reasons };
+}
+
+export default { name: "change-explainer", build, status };