@yannelli/paseo-linear-plugin 1.0.1 → 1.1.0-alpha.0

package/index.client.tsx

@@ -1,33 +1,160 @@
 import type { PluginClientContext } from "@getpaseo/plugin/client";
 import { LinearPanel, LinearScreen } from "./client/browser";
 import { openPluginScreen, registerScreen } from "./client/compat";
+import { gateAgentPanel } from "./client/access";
+import { LivePanel } from "./client/live-panel";
+import { contributeComposerPills } from "./client/pill";
+import { onMenuIconChange, PluginIcon, startMenuIcon } from "./client/plugin-icon";
+import { AgentSettings } from "./client/settings-agents";
 import { ConnectionSettings } from "./client/settings-connection";
+import { IconSettingsScreen } from "./client/settings-icon";
+import { LiveSettings } from "./client/settings-live";
 import { ProjectSettings } from "./client/settings-projects";
 import { PromptSettings } from "./client/settings-prompts";
 import { focusIssue, panelScope, SCREEN_SCOPE, updateBrowser } from "./client/store";
 import { IssueCardRow } from "./client/timeline-card";
+import { BUILT_IN_ICON } from "./shared/custom-icon";
 import { issueAttachments } from "./shared/issues";
 import { ISSUE_CARD_KIND, IssueCardSchema, LINEAR_IDENTIFIER } from "./shared/linear";
 
 const SCREEN_ID = "linear";
 const PANEL_ID = "issues";
+const LIVE_PANEL_ID = "live";
+
+type Cleanup = () => void;
+
+// Panels and Command Center items take the menu icon when they register, so a new choice
+// registers the whole group again. One group keeps their order the same.
+function contributeMenus(client: PluginClientContext, icon: string): Cleanup {
+  const cleanups: Cleanup[] = [];
+  const removeAll = () => {
+    for (const cleanup of cleanups.splice(0).reverse()) cleanup();
+  };
+  try {
+    cleanups.push(
+      client.addWorkspacePanel({
+        id: PANEL_ID,
+        title: "Linear",
+        icon,
+        context: "workspace",
+        locations: ["workspace", "explorer"],
+        Component: LinearPanel,
+      }),
+      client.addWorkspacePanel({
+        id: LIVE_PANEL_ID,
+        title: "Linear Live",
+        icon: "Radar",
+        context: "agent",
+        Component: gateAgentPanel(LivePanel),
+      }),
+      client.addCommandCenterItem({
+        id: "open-issues",
+        title: "Linear: Open issues",
+        icon,
+        keywords: ["linear", "issues", "tickets"],
+        context: "global",
+        onSelect(context) {
+          openPluginScreen(context, SCREEN_ID);
+        },
+      }),
+      client.addCommandCenterItem({
+        id: "create-issue",
+        title: "Linear: Create issue",
+        icon: "Plus",
+        keywords: ["linear", "new", "ticket"],
+        context: "global",
+        onSelect(context) {
+          updateBrowser(SCREEN_SCOPE, { creating: true });
+          openPluginScreen(context, SCREEN_ID);
+        },
+      }),
+      client.addCommandCenterItem({
+        id: "workspace-issues",
+        title: "Linear: Show issues in this workspace",
+        icon,
+        keywords: ["linear", "panel"],
+        context: "workspace",
+        onSelect({ openPanel }) {
+          openPanel(PANEL_ID);
+        },
+      }),
+      client.addCommandCenterItem({
+        id: "open-live",
+        title: "Linear: Open Linear Live",
+        icon: "Radar",
+        keywords: ["linear", "live", "progress", "map"],
+        context: "agent",
+        onSelect({ openPanel }) {
+          openPanel(LIVE_PANEL_ID);
+        },
+      }),
+      client.addCommandCenterItem({
+        id: "setup-project",
+        title: "Linear: Set up project prompts",
+        icon: "Sparkles",
+        keywords: ["linear", "init", "setup", "agents.md", "guidelines"],
+        context: "global",
+        onSelect({ openSettings }) {
+          openSettings("projects");
+        },
+      }),
+      client.addCommandCenterItem({
+        id: "settings",
+        title: "Linear: Settings",
+        icon: "Settings",
+        keywords: ["linear", "api key", "prompts", "projects", "agents", "mcp", "tools"],
+        context: "global",
+        onSelect({ openSettings }) {
+          openSettings("connection");
+        },
+      }),
+    );
+  } catch (error) {
+    removeAll();
+    throw error;
+  }
+  return removeAll;
+}
+
+/** Registers the menus with the chosen icon, and again when it changes. */
+function contributeMenusWithIcon(client: PluginClientContext): Cleanup {
+  let icon = startMenuIcon();
+  let removeMenus: Cleanup;
+  try {
+    removeMenus = contributeMenus(client, icon);
+  } catch (error) {
+    console.error("Linear menu icon", error);
+    icon = BUILT_IN_ICON;
+    removeMenus = contributeMenus(client, icon);
+  }
+  const stop = onMenuIconChange((next) => {
+    if (next === icon) return;
+    removeMenus();
+    try {
+      removeMenus = contributeMenus(client, next);
+      icon = next;
+    } catch (error) {
+      // An icon this Paseo does not have: keep the built-in one.
+      console.error("Linear menu icon", error);
+      removeMenus = contributeMenus(client, BUILT_IN_ICON);
+      icon = BUILT_IN_ICON;
+    }
+  });
+  return () => {
+    stop();
+    removeMenus();
+  };
+}
 
 export default function contribute(client: PluginClientContext) {
   client.addAttachmentSource(issueAttachments);
   registerScreen(client, {
     id: SCREEN_ID,
     title: "Linear",
-    icon: "SquareKanban",
+    icon: BUILT_IN_ICON,
+    RowIcon: PluginIcon,
     Component: LinearScreen,
   });
-  client.addWorkspacePanel({
-    id: PANEL_ID,
-    title: "Linear",
-    icon: "SquareKanban",
-    context: "workspace",
-    locations: ["workspace", "explorer"],
-    Component: LinearPanel,
-  });
   client.addSettingsScreen({
     id: "connection",
     title: "Account",
@@ -40,53 +167,31 @@ export default function contribute(client: PluginClientContext) {
     icon: "MessageSquare",
     Component: PromptSettings,
   });
+  client.addSettingsScreen({
+    id: "agents",
+    title: "Agents",
+    icon: "Bot",
+    Component: AgentSettings,
+  });
+  client.addSettingsScreen({
+    id: "live",
+    title: "Live",
+    icon: "Radar",
+    Component: LiveSettings,
+  });
+  client.addSettingsScreen({
+    id: "icon",
+    title: "Icon",
+    icon: "Shapes",
+    Component: IconSettingsScreen,
+  });
   client.addSettingsScreen({
     id: "projects",
     title: "Projects",
     icon: "FolderGit2",
     Component: ProjectSettings,
   });
-  client.addCommandCenterItem({
-    id: "open-issues",
-    title: "Linear: Open issues",
-    icon: "SquareKanban",
-    keywords: ["linear", "issues", "tickets"],
-    context: "global",
-    onSelect(context) {
-      openPluginScreen(context, SCREEN_ID);
-    },
-  });
-  client.addCommandCenterItem({
-    id: "create-issue",
-    title: "Linear: Create issue",
-    icon: "Plus",
-    keywords: ["linear", "new", "ticket"],
-    context: "global",
-    onSelect(context) {
-      updateBrowser(SCREEN_SCOPE, { creating: true });
-      openPluginScreen(context, SCREEN_ID);
-    },
-  });
-  client.addCommandCenterItem({
-    id: "workspace-issues",
-    title: "Linear: Show issues in this workspace",
-    icon: "SquareKanban",
-    keywords: ["linear", "panel"],
-    context: "workspace",
-    onSelect({ openPanel }) {
-      openPanel(PANEL_ID);
-    },
-  });
-  client.addCommandCenterItem({
-    id: "settings",
-    title: "Linear: Settings",
-    icon: "Settings",
-    keywords: ["linear", "api key", "prompts", "projects"],
-    context: "global",
-    onSelect({ openSettings }) {
-      openSettings("connection");
-    },
-  });
+  const removeMenus = contributeMenusWithIcon(client);
   client.addSlashCommand({
     name: "linear",
     description: "Open Linear issues, or jump to one by key",
@@ -107,5 +212,9 @@ export default function contribute(client: PluginClientContext) {
     schema: IssueCardSchema,
     Component: IssueCardRow,
   });
-  return () => {};
+  const removePills = contributeComposerPills(client);
+  return () => {
+    removeMenus();
+    removePills();
+  };
 }

package/index.server.ts

@@ -1,12 +1,39 @@
+import path from "node:path";
 import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { registerAgentHooks } from "./server/agent-hooks";
+import { registerAgentTools } from "./server/agent-tools";
 import { createCredentialStore, defaultCredentialPath } from "./server/credentials";
 import { registerHandlers } from "./server/handlers";
-import { linearSettings } from "./shared/settings";
+import { registerInit } from "./server/init";
+import { createKnowledge, registerKnowledge } from "./server/knowledge";
+import { registerLive } from "./server/live";
+import { createLaunchQueue, createMapStore } from "./server/stores";
+import { registerSync } from "./server/sync";
+import { accessRpc, type LinearSettings, linearSettings } from "./shared/settings";
 
 export default function contribute(server: PluginServerContext) {
-  server.registerSettings(linearSettings);
-  registerHandlers(server, {
-    credentials: createCredentialStore({ file: defaultCredentialPath() }),
+  const settings = server.registerSettings(linearSettings);
+  const readSettings = async (): Promise<LinearSettings | null> => {
+    const state = await settings.read();
+    return state.status === "ready" ? state.values : null;
+  };
+  const credentialPath = defaultCredentialPath();
+  const access = registerHandlers(server, {
+    credentials: createCredentialStore({ file: credentialPath }),
   });
-  return () => {};
+  const dataDirectory = path.dirname(credentialPath);
+  const maps = createMapStore(path.join(dataDirectory, "live-maps.json"));
+  const launches = createLaunchQueue(path.join(dataDirectory, "pending-launches.json"));
+  const knowledge = createKnowledge(path.join(dataDirectory, "knowledge"));
+  registerKnowledge(server, knowledge);
+  registerLive(server, { access, maps, launches, knowledge, readSettings });
+  registerSync(server, { access, readSettings });
+  registerInit(server, { readSettings, knowledge });
+  registerAgentHooks(server, dataDirectory);
+  const closeTools = registerAgentTools(server, { access, dataDirectory, readSettings });
+  server.handle(accessRpc, async () => {
+    const values = await readSettings();
+    return values?.access ?? linearSettings.schema.parse({}).access;
+  });
+  return closeTools;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yannelli/paseo-linear-plugin",
-  "version": "1.0.1",
+  "version": "1.1.0-alpha.0",
   "description": "Browse and triage Linear issues in Paseo and start agents from them",
   "license": "Apache-2.0",
   "type": "module",

package/server/agent-hooks.ts

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto";
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { agentHooksRpc, claudeHooks, hookPluginName, IDENTIFIER } from "../shared/agent-hooks";
+
+// Writes one Claude Code plugin folder per issue under the plugin's data folder. A launch passes
+// the folder to Claude with --plugin-dir. The name holds a hash of the hooks, so a later launch
+// never changes the hooks of a running agent. Resumed agents keep using it, so it stays.
+
+async function writeAtomic(file: string, text: string) {
+  const temporary = `${file}.${process.pid}.tmp`;
+  await writeFile(temporary, text, { mode: 0o600 });
+  await rename(temporary, file);
+}
+
+export function registerAgentHooks(server: PluginServerContext, dataDirectory: string) {
+  server.handle(agentHooksRpc, async ({ issue, guidance }) => {
+    // The hooks run printf in a POSIX shell, which Windows hosts do not have.
+    if (process.platform === "win32" || !IDENTIFIER.test(issue.identifier)) return { pluginDir: null };
+    const hooks = claudeHooks(issue, guidance);
+    if (!hooks) return { pluginDir: null };
+    const text = `${JSON.stringify(hooks, null, 2)}\n`;
+    const hash = createHash("sha256").update(text).digest("hex").slice(0, 12);
+    const root = path.join(dataDirectory, "claude-hooks", `${issue.identifier.toUpperCase()}-${hash}`);
+    await mkdir(path.join(root, ".claude-plugin"), { recursive: true, mode: 0o700 });
+    await mkdir(path.join(root, "hooks"), { recursive: true, mode: 0o700 });
+    const manifest = {
+      name: hookPluginName(issue.identifier),
+      version: "1.0.0",
+      description: `Linear context for ${issue.identifier} from the Paseo Linear plugin`,
+    };
+    await writeAtomic(path.join(root, ".claude-plugin", "plugin.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    await writeAtomic(path.join(root, "hooks", "hooks.json"), text);
+    return { pluginDir: root };
+  });
+}

package/server/agent-runs.ts

@@ -0,0 +1,312 @@
+import { randomUUID } from "node:crypto";
+import type { PluginHandlerContext, PluginLifecycleEvents } from "@getpaseo/plugin/server";
+import { type ZodType, z } from "zod";
+import { relativePath } from "../shared/activity";
+import type { Job } from "../shared/live";
+import { lastJsonObject } from "../shared/live";
+
+// Explore and project setup run a read-only agent, wait for it in the background, and read a
+// JSON answer from its last message. Claude ignores outputSchema, so the prompt asks for JSON.
+
+export type Paseo = PluginHandlerContext["paseo"];
+type WorkspaceHandle = Awaited<ReturnType<Paseo["workspaces"]["open"]>>;
+type AgentHandle = ReturnType<Paseo["agents"]["ref"]>;
+export type PermissionRequest = PluginLifecycleEvents["agent.permission_requested"]["request"];
+export type PermissionAnswer = Parameters<AgentHandle["respondToPermission"]>[0]["response"];
+
+export interface InternalRun<T> {
+  paseo: Paseo;
+  workspace: WorkspaceHandle;
+  /** Folder the agent works in; its reads must stay inside. */
+  cwd: string;
+  provider: string;
+  /** Thinking option for the model in `provider`; ignored when another model runs. */
+  effort?: string;
+  title: string;
+  prompt: string;
+  labels: Record<string, string>;
+  schema: ZodType<T>;
+  timeoutMs: number;
+}
+
+interface SnapshotEntry {
+  provider: string;
+  status: string;
+  enabled?: boolean;
+  modes?: readonly { id: string; label?: string }[];
+}
+
+const SAFE_MODES = [/read.?only/i, /^default$/i, /ask/i];
+const UNSAFE_MODE = /bypass|full|yolo|danger/i;
+
+// Never inherit a provider default that skips approvals. Claude's "default" asks before
+// edits, so an edit attempt stops the run. Codex has no read-only mode; "auto" asks on request.
+export function safeModeId(modes: SnapshotEntry["modes"]): string | undefined {
+  for (const pattern of SAFE_MODES) {
+    const match = modes?.find((mode) => pattern.test(mode.id));
+    if (match) return match.id;
+  }
+  return modes?.find((mode) => !UNSAFE_MODE.test(`${mode.id} ${mode.label ?? ""}`))?.id;
+}
+
+const UNSUPPORTED_KEYWORDS = new Set([
+  "$schema",
+  "default",
+  "minLength",
+  "maxLength",
+  "minItems",
+  "maxItems",
+]);
+
+/** JSON schema for strict structured output: every property required, no extras. */
+export function strictJsonSchema(schema: ZodType): Record<string, unknown> {
+  const strip = (node: unknown): unknown => {
+    if (Array.isArray(node)) return node.map(strip);
+    if (!node || typeof node !== "object") return node;
+    return Object.fromEntries(
+      Object.entries(node)
+        .filter(([key]) => !UNSUPPORTED_KEYWORDS.has(key))
+        .map(([key, value]) => [key, strip(value)]),
+    );
+  };
+  return strip(z.toJSONSchema(schema, { io: "output" })) as Record<string, unknown>;
+}
+
+// Some Claude builds search only through the shell, so internal agents may run a short list of
+// commands that read. Anything that writes, runs other programs, or leaves the folder is denied.
+const READ_COMMAND = /^(?:ls|find|rg|grep|cat|head|tail|wc|pwd|git (?:ls-files|grep))(?:\s|$)/;
+const UNSAFE_SHELL =
+  /[`;&<>~$\n\r]|\.\.|\s-(?:exec|execdir|ok|okdir|delete|fprint\w*|fls|O)\b|\s--(?:pre|open-files-in-pager)\b/;
+/** Quoted text the shell does not expand: single quotes, or double quotes without $ or `. */
+const LITERAL = /'[^']*'|"[^"$`\\]*"/g;
+
+function insideFolder(filePath: string, cwd: string): boolean {
+  return filePath.replace(/\/+$/, "") === cwd.replace(/\/+$/, "") || relativePath(filePath, cwd) !== null;
+}
+
+export function readOnlyCommand(command: string, cwd: string): boolean {
+  const text = command.replace(/\s2>\s*\/dev\/null/g, " ").trim();
+  const bare = text.replace(LITERAL, "Q");
+  if (!bare || UNSAFE_SHELL.test(bare)) return false;
+  const outside = text.split(/\s+|=/).some((word) => {
+    const filePath = word.replace(/['"]/g, "");
+    return filePath.startsWith("/") && !insideFolder(filePath, cwd);
+  });
+  return !outside && bare.split("|").every((part) => READ_COMMAND.test(part.trim()));
+}
+
+/** Prompt lines that match what readOnlyAnswer allows. */
+export const READ_ONLY_RULES = [
+  "Read and search only. Do not create, edit, or delete files.",
+  "To find files, use your read and search tools, or these shell commands, one at a time and",
+  "without redirection: ls, find, rg, grep, cat, head, tail, wc, git ls-files, git grep.",
+  "Keep paths inside this folder. Other commands are denied.",
+  "Work alone: do not start subagents or background tasks.",
+];
+
+const DENIED =
+  "Not allowed in this read-only run. Read and search files in this repository only, one " +
+  "command at a time, without redirection.";
+
+/** No one watches internal agents, so the plugin answers their prompts: reads yes, else no. */
+export function readOnlyAnswer(request: PermissionRequest, cwd: string): PermissionAnswer {
+  if (request.kind === "question") {
+    return { behavior: "deny", message: "No one can answer here. Decide yourself and continue." };
+  }
+  const detail = request.detail;
+  const command =
+    detail?.type === "shell" ? detail.command : (request.input as { command?: unknown })?.command;
+  const allowed =
+    request.kind === "tool" &&
+    ((detail?.type === "read" && insideFolder(detail.filePath, cwd)) ||
+      (detail?.type === "search" && detail.toolName !== "web_search") ||
+      (typeof command === "string" && readOnlyCommand(command, cwd)));
+  return allowed ? { behavior: "allow" } : { behavior: "deny", message: DENIED };
+}
+
+function entriesOf(snapshot: unknown): readonly SnapshotEntry[] {
+  const value = snapshot as {
+    entries?: readonly SnapshotEntry[];
+    compactSnapshot?: { entries?: readonly SnapshotEntry[] } | null;
+  };
+  const entries = value.entries ?? [];
+  return entries.length > 0 ? entries : (value.compactSnapshot?.entries ?? []);
+}
+
+/** Uses `preferred` (`provider` or `provider/model`) when ready, else the first ready provider. */
+export async function agentConfigFor(paseo: Paseo, preferred: string) {
+  const entries = entriesOf(await paseo.providers.snapshot()).filter(
+    (entry) => entry.status === "ready" && entry.enabled !== false,
+  );
+  const wanted = preferred.split("/")[0] ?? "";
+  const entry = entries.find((candidate) => candidate.provider === wanted) ?? entries[0];
+  if (!entry) throw new Error("No agent provider is ready on this host");
+  const provider = entry.provider === wanted && preferred.includes("/") ? preferred : entry.provider;
+  const modeId = safeModeId(entry.modes);
+  return { provider, ...(modeId ? { modeId } : {}) };
+}
+
+export async function lastReply(handle: AgentHandle) {
+  const page = await handle.timeline.refetch({
+    direction: "tail",
+    limit: 60,
+    projection: "projected",
+  });
+  for (const entry of [...page.entries].reverse()) {
+    const item = entry.item as { type: string; text?: unknown };
+    if (item.type === "assistant_message" && typeof item.text === "string") return item.text;
+  }
+  return "";
+}
+
+const MAX_STALLS = 20;
+const STALL_DELAY_MS = 500;
+
+// waitForFinish also returns when the agent asks for permission, so answer and keep waiting.
+// A prompt is answered once; while the daemon applies an answer, the loop waits briefly.
+export async function waitUntilIdle(handle: AgentHandle, cwd: string, timeoutMs: number) {
+  const deadline = Date.now() + timeoutMs;
+  const answered = new Set<string>();
+  let stalls = 0;
+  for (;;) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw new Error("The agent did not finish in time");
+    const finish = await handle.waitForFinish(remaining);
+    if (finish.status === "idle") return;
+    if (finish.status !== "permission") {
+      throw new Error(finish.error ?? `The agent stopped with status ${finish.status}`);
+    }
+    const unanswered = (requests: readonly PermissionRequest[] | null | undefined) =>
+      (requests ?? []).filter((request) => !answered.has(request.id));
+    let pending = unanswered(finish.final?.pendingPermissions);
+    if (pending.length === 0) {
+      await handle.refresh();
+      pending = unanswered(handle.pendingPermissions);
+    }
+    if (pending.length === 0) {
+      stalls += 1;
+      if (answered.size === 0 || stalls > MAX_STALLS) {
+        throw new Error("The agent is waiting for input");
+      }
+      await new Promise((resolve) => setTimeout(resolve, STALL_DELAY_MS));
+      continue;
+    }
+    stalls = 0;
+    for (const request of pending) {
+      answered.add(request.id);
+      await handle
+        .respondToPermission({ requestId: request.id, response: readOnlyAnswer(request, cwd) })
+        .catch((error: unknown) => console.error("Linear could not answer a permission", error));
+    }
+  }
+}
+
+/** Waits for an internal agent, reads its JSON answer, and archives it either way. */
+export async function finishInternalRun<T>(
+  handle: AgentHandle,
+  cwd: string,
+  schema: ZodType<T>,
+  timeoutMs: number,
+): Promise<T> {
+  try {
+    await waitUntilIdle(handle, cwd, timeoutMs);
+    const parsed = schema.safeParse(lastJsonObject(await lastReply(handle)));
+    if (!parsed.success) throw new Error("The agent did not return the expected JSON");
+    return parsed.data;
+  } finally {
+    await handle.archive().catch(() => undefined);
+  }
+}
+
+export interface StartedRun<T> {
+  agentId: string;
+  result: Promise<T>;
+}
+
+/** Adds the chosen effort only when the chosen model runs, not a fallback provider. */
+export function withEffort<C extends { provider: string }>(config: C, chosen: string, effort?: string) {
+  const applies = Boolean(effort) && chosen.includes("/") && config.provider === chosen;
+  return applies ? { ...config, thinkingOptionId: effort as string } : config;
+}
+
+export async function startInternalRun<T>(run: InternalRun<T>): Promise<StartedRun<T>> {
+  const config = withEffort(await agentConfigFor(run.paseo, run.provider), run.provider, run.effort);
+  const handle = await run.workspace.agents.create({
+    config,
+    title: run.title,
+    prompt: run.prompt,
+    labels: run.labels,
+    outputSchema: strictJsonSchema(run.schema),
+  });
+  const result = finishInternalRun(handle, run.cwd, run.schema, run.timeoutMs);
+  return { agentId: handle.id, result };
+}
+
+export interface JobStore<T> {
+  get(id: string): { job: Job; value: T | null } | null;
+  start(id: string | null, begin: () => Promise<StartedRun<T>>): Promise<Job>;
+  /** Resolves with the job once it is done or failed; null for an unknown id. */
+  wait(id: string): Promise<Job | null>;
+  /** Drops a finished job, so the next start makes a new run. A running job is kept. */
+  forget(id: string): void;
+}
+
+interface JobRecord<T> {
+  job: Job;
+  value: T | null;
+  settled: Promise<void>;
+}
+
+export function createJobStore<T>(): JobStore<T> {
+  const jobs = new Map<string, JobRecord<T>>();
+  return {
+    get: (id) => {
+      const record = jobs.get(id);
+      return record ? { job: record.job, value: record.value } : null;
+    },
+    forget(id) {
+      if (jobs.get(id)?.job.status !== "running") jobs.delete(id);
+    },
+    async wait(id) {
+      const record = jobs.get(id);
+      if (!record) return null;
+      await record.settled;
+      return record.job;
+    },
+    async start(id, begin) {
+      const job: Job = {
+        id: id ?? randomUUID(),
+        status: "running",
+        agentId: null,
+        error: null,
+        startedAt: new Date().toISOString(),
+      };
+      let settle = () => {};
+      const settled = new Promise<void>((resolve) => {
+        settle = resolve;
+      });
+      const record: JobRecord<T> = { job, value: null, settled };
+      jobs.set(job.id, record);
+      const fail = (error: unknown) => {
+        record.job = {
+          ...record.job,
+          status: "failed",
+          error: error instanceof Error ? error.message : String(error),
+        };
+        settle();
+      };
+      try {
+        const started = await begin();
+        record.job = { ...record.job, agentId: started.agentId };
+        started.result.then((value) => {
+          record.value = value;
+          record.job = { ...record.job, status: "done" };
+          settle();
+        }, fail);
+      } catch (error) {
+        fail(error);
+      }
+      return record.job;
+    },
+  };
+}