npm - @cfbender/cesium - Versions diffs - 0.3.5 - Mend

@cfbender/cesium 0.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (44) hide show

package/ARCHITECTURE.md +304 -0
package/CHANGELOG.md +335 -0
package/LICENSE +21 -0
package/README.md +479 -0
package/agents/cesium.md +39 -0
package/assets/styleguide.html +857 -0
package/package.json +61 -0
package/src/cli/commands/ls.ts +186 -0
package/src/cli/commands/open.ts +208 -0
package/src/cli/commands/prune.ts +348 -0
package/src/cli/commands/restart.ts +38 -0
package/src/cli/commands/serve.ts +214 -0
package/src/cli/commands/stop.ts +130 -0
package/src/cli/commands/theme.ts +333 -0
package/src/cli/index.ts +78 -0
package/src/config.ts +94 -0
package/src/index.ts +35 -0
package/src/prompt/system-fragment.md +97 -0
package/src/render/client-js.ts +316 -0
package/src/render/controls.ts +302 -0
package/src/render/critique.ts +360 -0
package/src/render/extract.ts +83 -0
package/src/render/scrub.ts +141 -0
package/src/render/theme.ts +712 -0
package/src/render/validate.ts +524 -0
package/src/render/wrap.ts +165 -0
package/src/server/api.ts +166 -0
package/src/server/http.ts +195 -0
package/src/server/lifecycle.ts +331 -0
package/src/server/stop.ts +124 -0
package/src/storage/index-cache.ts +71 -0
package/src/storage/index-gen.ts +447 -0
package/src/storage/lock.ts +108 -0
package/src/storage/mutate.ts +396 -0
package/src/storage/paths.ts +159 -0
package/src/storage/project-summaries.ts +19 -0
package/src/storage/theme-write.ts +19 -0
package/src/storage/write.ts +75 -0
package/src/tools/ask.ts +353 -0
package/src/tools/critique.ts +66 -0
package/src/tools/publish.ts +404 -0
package/src/tools/stop.ts +53 -0
package/src/tools/styleguide.ts +23 -0
package/src/tools/wait.ts +192 -0

package/src/tools/publish.ts ADDED Viewed

@@ -0,0 +1,404 @@
+// Tool handler for cesium_publish — validates input, delegates to render + storage.
+import { createHash } from "node:crypto";
+import { networkInterfaces } from "node:os";
+import { join } from "node:path";
+import { tool } from "@opencode-ai/plugin";
+import type { PluginInput } from "@opencode-ai/plugin";
+import { loadConfig, type CesiumConfig } from "../config.ts";
+import { scrub } from "../render/scrub.ts";
+import { extractTextContent } from "../render/extract.ts";
+import { themeFromPreset, mergeTheme } from "../render/theme.ts";
+import { validatePublishInput, htmlBodyWarnings, PUBLISH_KINDS } from "../render/validate.ts";
+import { wrapDocument, type ArtifactMeta } from "../render/wrap.ts";
+import { deriveProjectIdentity, artifactFilename, pathsFor } from "../storage/paths.ts";
+import { atomicWrite, patchEmbeddedMetadata } from "../storage/write.ts";
+import { writeThemeCss } from "../storage/theme-write.ts";
+import {
+  loadIndex,
+  writeIndex,
+  appendEntry,
+  patchEntry,
+  type IndexEntry,
+} from "../storage/index-cache.ts";
+import { withLock } from "../storage/lock.ts";
+import { renderProjectIndex, renderGlobalIndex } from "../storage/index-gen.ts";
+import { buildProjectSummaries } from "../storage/project-summaries.ts";
+import {
+  ensureRunning as defaultEnsureRunning,
+  type RunningInfo,
+  type LifecycleConfig,
+} from "../server/lifecycle.ts";
+export interface PublishToolOverrides {
+  loadConfig?: () => CesiumConfig;
+  now?: () => Date;
+  nanoid?: () => string;
+  ensureRunning?: (cfg: LifecycleConfig) => Promise<RunningInfo | null>;
+}
+export interface TerminalSummaryArgs {
+  title: string;
+  kind: string;
+  httpUrl: string;
+  fileUrl: string;
+  isSsh: boolean;
+  port: number;
+}
+export function buildTerminalSummary(args: TerminalSummaryArgs): string {
+  const { title, kind, httpUrl, fileUrl, isSsh, port } = args;
+  let summary = `Cesium · ${title} (${kind})\n  ${httpUrl}\n  ${fileUrl}`;
+  if (isSsh) {
+    summary += `\n\n  (remote: forward port → ssh -L ${port}:localhost:${port} <host>)`;
+  }
+  return summary;
+}
+const TOOL_DESCRIPTION = `Publish a beautiful self-contained HTML document to the cesium artifacts directory.
+Use this when responding with substantive content — plans, code reviews, comparisons,
+reports, explainers, audits, design proposals — that the user is likely to re-read or share.
+When to use cesium_publish (vs replying in terminal):
+- Response would be ≥ ~400 words, OR
+- Contains a comparison/decision matrix, OR
+- Multi-section plan/PRD/RFC/design doc, OR
+- Code review with > 3 findings, OR
+- Anything the user might revisit later.
+When to stay in the terminal: short factual answers, status updates ("done", "fixed",
+"running tests"), mid-tool-call chatter, single-paragraph replies.
+User overrides win: "/cesium" or "publish this" → publish; "in terminal" → don't.
+The \`html\` argument is the BODY ONLY — do NOT include <!doctype>, <html>, <head>, <body>.
+The plugin wraps your body with the design system.
+Available CSS classes (call cesium_styleguide for full reference + examples):
+- .eyebrow         uppercase mono micro-label above headings
+- .h-display       page-title heading
+- .h-section       section heading paired with .section-num
+- .section-num     numbered chip ("01", "02") next to .h-section
+- .card            bordered surface block (1.5px border, 12px radius)
+- .tldr            clay-bordered summary box (use ONE per doc, near top)
+- .callout         info box; modifiers: .callout.note .callout.warn .callout.risk
+- .code            block-level code panel; inline highlights via .kw .str .cm .fn
+- .timeline        milestone list with dots and connectors
+- .diagram         wraps inline SVG with a caption below
+- .compare-table   bordered comparison grid
+- .risk-table      bordered risk-grid (likelihood/impact/mitigation columns)
+- .kbd .pill .tag  inline chips
+- .byline          rendered automatically as the footer
+Inline \`style="..."\` and inline \`<svg>\` are encouraged for bespoke diagrams. NEVER reference
+external resources: no <script src=>, no <link rel=stylesheet href=http>, no remote fonts,
+no remote images. The plugin will silently strip external resources but the artifact will
+look broken in the resulting render.
+Title aim: 3-8 words, descriptive. Kind: pick the closest match.`;
+export function createPublishTool(
+  ctx: PluginInput,
+  overrides?: PublishToolOverrides,
+): ReturnType<typeof tool> {
+  const resolveConfig = overrides?.loadConfig ?? loadConfig;
+  const now = overrides?.now ?? (() => new Date());
+  const genId = overrides?.nanoid ?? defaultNanoid;
+  const runEnsureRunning = overrides?.ensureRunning ?? defaultEnsureRunning;
+  return tool({
+    description: TOOL_DESCRIPTION,
+    args: {
+      title: tool.schema.string(),
+      kind: tool.schema.enum([...PUBLISH_KINDS] as [string, ...string[]]),
+      html: tool.schema.string(),
+      summary: tool.schema.string().optional(),
+      tags: tool.schema.array(tool.schema.string()).optional(),
+      supersedes: tool.schema.string().optional(),
+    },
+    async execute(args, _context) {
+      // 1. Validate input
+      const validation = validatePublishInput(args);
+      if (!validation.ok) {
+        return `Error: ${validation.error}`;
+      }
+      const input = validation.value;
+      // 2. Load config
+      const config = resolveConfig();
+      // 3. Probe git state
+      const shell = ctx.$.cwd(ctx.directory).nothrow();
+      let gitRemote: string | null = null;
+      let gitBranch: string | null = null;
+      let gitCommit: string | null = null;
+      try {
+        const remoteResult = await shell`git config --get remote.origin.url`.quiet();
+        if (remoteResult.exitCode === 0) {
+          gitRemote = remoteResult.text().trim() || null;
+        }
+      } catch {
+        // not a git repo or no remote
+      }
+      try {
+        const branchResult = await shell`git rev-parse --abbrev-ref HEAD`.quiet();
+        if (branchResult.exitCode === 0) {
+          gitBranch = branchResult.text().trim() || null;
+        }
+      } catch {
+        // not a git repo
+      }
+      try {
+        const commitResult = await shell`git rev-parse HEAD`.quiet();
+        if (commitResult.exitCode === 0) {
+          gitCommit = commitResult.text().trim() || null;
+        }
+      } catch {
+        // not a git repo
+      }
+      // 4. Derive project identity
+      const identity = deriveProjectIdentity({
+        cwd: ctx.directory,
+        gitRemote,
+        worktree: ctx.worktree ?? null,
+      });
+      // 5. Generate id
+      const id = genId();
+      // 6. Timestamps
+      const createdAt = now();
+      // 7. Scrub
+      const scrubbed = scrub(input.html);
+      // 7a. Extract body text for full-text search
+      const bodyText = extractTextContent(scrubbed.html);
+      // 8. Compute filename + paths
+      const filename = artifactFilename({ title: input.title, id, createdAt });
+      const paths = pathsFor({
+        stateDir: config.stateDir,
+        projectSlug: identity.slug,
+        filename,
+      });
+      // 9. Content SHA-256
+      const contentSha256 = createHash("sha256").update(scrubbed.html).digest("hex");
+      // 10. Build ArtifactMeta
+      const meta: ArtifactMeta = {
+        id,
+        title: input.title,
+        kind: input.kind,
+        summary: input.summary ?? null,
+        tags: input.tags ?? [],
+        createdAt: createdAt.toISOString(),
+        model: null,
+        sessionId: null,
+        projectSlug: identity.slug,
+        projectName: identity.name,
+        cwd: ctx.directory,
+        worktree: identity.worktree,
+        gitBranch,
+        gitCommit,
+        supersedes: input.supersedes ?? null,
+        supersededBy: null,
+        contentSha256,
+      };
+      // 11. Build warnings
+      const warnings: string[] = [];
+      if (scrubbed.removed.length > 0) {
+        warnings.push(`Removed ${scrubbed.removed.length} external resource(s) during scrub.`);
+      }
+      const bodyWarnings = htmlBodyWarnings(scrubbed.html);
+      for (const w of bodyWarnings) {
+        warnings.push(w);
+      }
+      // 12. Build theme + wrap document
+      const theme = mergeTheme(themeFromPreset(config.themePreset), config.theme);
+      // 12a. Write theme.css (idempotent, outside index lock — separate file)
+      await writeThemeCss(config.stateDir, theme);
+      const fullHtml = wrapDocument({
+        body: scrubbed.html,
+        meta,
+        theme,
+        warnings,
+        themeCssHref: "../../../theme.css",
+      });
+      // 13. Atomic write
+      await atomicWrite(paths.artifactPath, fullHtml);
+      // 14. Build IndexEntry
+      const entry: IndexEntry = {
+        id: meta.id,
+        title: meta.title,
+        kind: meta.kind,
+        summary: meta.summary,
+        tags: meta.tags,
+        createdAt: meta.createdAt,
+        filename,
+        supersedes: meta.supersedes,
+        supersededBy: null,
+        gitBranch: meta.gitBranch,
+        gitCommit: meta.gitCommit,
+        contentSha256: meta.contentSha256,
+        projectSlug: identity.slug,
+        projectName: identity.name,
+        bodyText,
+      };
+      const lockPath = join(config.stateDir, ".index.lock");
+      await withLock({ lockPath }, async () => {
+        // 15. Update per-project index
+        const projectEntries = await loadIndex(paths.projectIndexJsonPath);
+        const updatedProjectEntries = appendEntry(projectEntries, entry);
+        await writeIndex(paths.projectIndexJsonPath, updatedProjectEntries);
+        // 16. Update global index
+        const globalEntries = await loadIndex(paths.globalIndexJsonPath);
+        const updatedGlobalEntries = appendEntry(globalEntries, entry);
+        await writeIndex(paths.globalIndexJsonPath, updatedGlobalEntries);
+        // 17. Handle supersedes chain
+        if (input.supersedes) {
+          const prevId = input.supersedes;
+          const prevEntryIdx = updatedProjectEntries.findIndex((e) => e.id === prevId);
+          if (prevEntryIdx !== -1) {
+            const prevEntry = updatedProjectEntries[prevEntryIdx];
+            if (prevEntry !== undefined) {
+              const prevFilename = prevEntry.filename;
+              const prevPaths = pathsFor({
+                stateDir: config.stateDir,
+                projectSlug: identity.slug,
+                filename: prevFilename,
+              });
+              // Patch embedded metadata in the previous artifact file
+              try {
+                await patchEmbeddedMetadata(prevPaths.artifactPath, { supersededBy: id });
+              } catch {
+                // File may not exist on disk (e.g. cleaned up); log but don't fail
+              }
+              // Patch the index entry
+              const patchedEntries = patchEntry(updatedProjectEntries, prevId, {
+                supersededBy: id,
+              });
+              await writeIndex(paths.projectIndexJsonPath, patchedEntries);
+            }
+          }
+          // If not found — publish still succeeds, warn is logged implicitly
+        }
+        // 18. Render and write project index.html
+        const latestProjectEntries = await loadIndex(paths.projectIndexJsonPath);
+        const projectIndexHtml = renderProjectIndex({
+          projectSlug: identity.slug,
+          projectName: identity.name,
+          entries: latestProjectEntries,
+          theme,
+          themeCssHref: "../../theme.css",
+        });
+        await atomicWrite(paths.projectIndexPath, projectIndexHtml);
+        // 19. Render and write global index.html
+        const latestGlobalEntries = await loadIndex(paths.globalIndexJsonPath);
+        const projectSummaries = buildProjectSummaries(latestGlobalEntries);
+        const globalIndexHtml = renderGlobalIndex({
+          projects: projectSummaries,
+          theme,
+          themeCssHref: "theme.css",
+        });
+        await atomicWrite(paths.globalIndexPath, globalIndexHtml);
+      });
+      // 20. Start server (best-effort) and build URLs
+      const displayHost = resolveDisplayHost(config.hostname);
+      let httpUrl = `http://${displayHost}:${config.port}${paths.serverPath}`;
+      let indexUrl = `http://${displayHost}:${config.port}/projects/${identity.slug}/index.html`;
+      let serverInfo: RunningInfo | null = null;
+      try {
+        const maybeInfo = await runEnsureRunning({
+          stateDir: config.stateDir,
+          port: config.port,
+          portMax: config.portMax,
+          idleTimeoutMs: config.idleTimeoutMs,
+          hostname: config.hostname,
+        });
+        if (maybeInfo !== null) {
+          serverInfo = maybeInfo;
+          const liveDisplay = resolveDisplayHost(config.hostname);
+          httpUrl = `http://${liveDisplay}:${serverInfo.port}${paths.serverPath}`;
+          indexUrl = `http://${liveDisplay}:${serverInfo.port}/projects/${identity.slug}/index.html`;
+        }
+      } catch {
+        // Server failed to start — proceed without; user can still use file:// URL.
+      }
+      const terminalSummary = buildTerminalSummary({
+        title: input.title,
+        kind: input.kind,
+        httpUrl,
+        fileUrl: paths.fileUrl,
+        isSsh: Boolean(process.env["SSH_CONNECTION"]),
+        port: serverInfo?.port ?? config.port,
+      });
+      // 21. Return result
+      const result = {
+        id,
+        filePath: paths.artifactPath,
+        fileUrl: paths.fileUrl,
+        httpUrl,
+        indexUrl,
+        terminalSummary,
+      };
+      return JSON.stringify(result, null, 2);
+    },
+  });
+}
+// Default nanoid implementation using built-in crypto for alphanumeric IDs
+function defaultNanoid(): string {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  const bytes = new Uint8Array(6);
+  crypto.getRandomValues(bytes);
+  let result = "";
+  for (const byte of bytes) {
+    result += alphabet[byte % alphabet.length];
+  }
+  return result;
+}
+// Pick a host for display URLs. When binding 0.0.0.0 (any-interface), substitute
+// the first non-loopback IPv4 we can find so the URL is actually reachable from
+// other machines on the LAN. For loopback/named bindings, just translate
+// 127.0.0.1 to "localhost" for friendliness; everything else is used verbatim.
+export function resolveDisplayHost(bindHost: string): string {
+  if (bindHost === "0.0.0.0" || bindHost === "::") {
+    const ifaces = networkInterfaces();
+    for (const list of Object.values(ifaces)) {
+      for (const iface of list ?? []) {
+        if (iface.family === "IPv4" && !iface.internal) {
+          return iface.address;
+        }
+      }
+    }
+    return "localhost";
+  }
+  if (bindHost === "127.0.0.1" || bindHost === "::1") {
+    return "localhost";
+  }
+  return bindHost;
+}

package/src/tools/stop.ts ADDED Viewed

@@ -0,0 +1,53 @@
+// Tool handler for cesium_stop — stops the running cesium HTTP server cross-process.
+import { tool } from "@opencode-ai/plugin";
+import type { PluginInput } from "@opencode-ai/plugin";
+import { loadConfig } from "../config.ts";
+import { stopServer } from "../server/stop.ts";
+import type { StopOutcome } from "../server/stop.ts";
+const TOOL_DESCRIPTION = `Stop the running cesium HTTP server.
+Idempotent: returns a clear message when no server is running. Sends SIGTERM
+with a 3s grace period, then SIGKILL if the process hasn't exited. The agent
+can call this when:
+- The user explicitly asks to stop or restart the cesium server.
+- The user is changing config (port, hostname, theme) and wants the new server
+  to start fresh on the next publish.
+- Cleanup at session end is desired.
+Note: the next call to cesium_publish will lazy-start a new server, so calling
+this between publishes effectively cycles the server with the latest config.`;
+export function formatStopOutcome(outcome: StopOutcome): string {
+  switch (outcome.kind) {
+    case "not-running":
+      return "no cesium server running";
+    case "stale":
+      return "server not running (stale PID file removed)";
+    case "stopped":
+      return `stopped cesium server (pid ${outcome.pid}, port ${outcome.port}, ${outcome.signal})`;
+    case "permission-denied":
+      return `could not stop server: permission denied (pid ${outcome.pid} owned by another user)`;
+  }
+}
+export function createStopTool(_ctx: PluginInput): ReturnType<typeof tool> {
+  return tool({
+    description: TOOL_DESCRIPTION,
+    args: {
+      force: tool.schema.boolean().optional(),
+      timeoutMs: tool.schema.number().optional(),
+    },
+    async execute(args) {
+      const config = loadConfig();
+      const stopArgs: Parameters<typeof stopServer>[0] = {
+        stateDir: config.stateDir,
+        ...(args.force !== undefined ? { force: args.force } : {}),
+        ...(args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {}),
+      };
+      const outcome = await stopServer(stopArgs);
+      return formatStopOutcome(outcome);
+    },
+  });
+}

package/src/tools/styleguide.ts ADDED Viewed

@@ -0,0 +1,23 @@
+// Tool handler for cesium_styleguide — returns the full CSS reference page as a string.
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tool } from "@opencode-ai/plugin";
+import type { PluginInput } from "@opencode-ai/plugin";
+const STYLEGUIDE_PATH = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../assets/styleguide.html",
+);
+export function createStyleguideTool(_ctx: PluginInput): ReturnType<typeof tool> {
+  return tool({
+    description:
+      "Returns the cesium HTML design system reference page (CSS classes with example usage). Call this once at the start of writing a complex artifact to internalize the available components.",
+    args: {},
+    async execute(_args, _context) {
+      return await readFile(STYLEGUIDE_PATH, "utf8");
+    },
+  });
+}

package/src/tools/wait.ts ADDED Viewed

@@ -0,0 +1,192 @@
+// Tool handler for cesium_wait — polls an interactive artifact until complete or timeout.
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tool } from "@opencode-ai/plugin";
+import type { PluginInput } from "@opencode-ai/plugin";
+import { loadConfig, type CesiumConfig } from "../config.ts";
+import { loadIndex } from "../storage/index-cache.ts";
+import type { AnswerValue, InteractiveData } from "../render/validate.ts";
+import { readEmbeddedMetadata } from "../storage/write.ts";
+import { readFile } from "node:fs/promises";
+export interface WaitToolOverrides {
+  loadConfig?: () => CesiumConfig;
+}
+export type WaitStatus = "complete" | "incomplete" | "expired" | "cancelled" | "not-found";
+const TOOL_DESCRIPTION = `cesium_wait — Block until the user completes a cesium_ask interactive artifact, or
+until timeout. Returns the user's answers as a map keyed by question id.
+Pass the id returned from cesium_ask. Default timeout is 10 minutes. Polls the
+artifact file every 500ms (no server-side coordination needed — disk is the source
+of truth).
+Use this immediately after cesium_ask when you need the user's input to continue.
+If the user doesn't finish within the timeout, you'll get status: "incomplete"
+with whatever they answered so far — handle that case (re-prompt, give up, or
+publish a partial artifact).`;
+export function createWaitTool(
+  _ctx: PluginInput,
+  overrides?: WaitToolOverrides,
+): ReturnType<typeof tool> {
+  const resolveConfig = overrides?.loadConfig ?? loadConfig;
+  return tool({
+    description: TOOL_DESCRIPTION,
+    args: {
+      id: tool.schema.string(),
+      timeoutMs: tool.schema.number().optional(),
+      pollIntervalMs: tool.schema.number().optional(),
+    },
+    async execute(args, _context) {
+      const config = resolveConfig();
+      const { id } = args;
+      const timeoutMs = typeof args.timeoutMs === "number" ? args.timeoutMs : 600_000;
+      const pollIntervalMs = Math.max(
+        100,
+        typeof args.pollIntervalMs === "number" ? args.pollIntervalMs : 500,
+      );
+      // Resolve id → artifactPath by scanning project index.json files
+      const artifactPath = await resolveArtifactPath(config.stateDir, id);
+      if (artifactPath === null) {
+        const result = {
+          status: "not-found" as WaitStatus,
+          answers: {},
+          remaining: [] as string[],
+        };
+        return JSON.stringify(result, null, 2);
+      }
+      // Poll until complete, expired, cancelled, or timeout
+      const startTime = Date.now();
+      const pollResult = await pollLoop(artifactPath, timeoutMs, pollIntervalMs, startTime);
+      return JSON.stringify(pollResult, null, 2);
+    },
+  });
+}
+// ─── Artifact path resolution ──────────────────────────────────────────────────
+async function resolveArtifactPath(stateDir: string, id: string): Promise<string | null> {
+  const projectsDir = join(stateDir, "projects");
+  let projectDirs: string[];
+  try {
+    projectDirs = await readdir(projectsDir);
+  } catch {
+    return null;
+  }
+  for (const projectSlug of projectDirs) {
+    const indexPath = join(projectsDir, projectSlug, "index.json");
+    let entries;
+    try {
+      entries = await loadIndex(indexPath);
+    } catch {
+      continue;
+    }
+    const entry = entries.find((e) => e.id === id);
+    if (entry !== undefined) {
+      return join(projectsDir, projectSlug, "artifacts", entry.filename);
+    }
+  }
+  return null;
+}
+// ─── Poll loop (recursive to satisfy no-await-in-loop) ────────────────────────
+interface PollResult {
+  status: WaitStatus;
+  answers: Record<string, AnswerValue>;
+  remaining: string[];
+}
+async function pollLoop(
+  artifactPath: string,
+  timeoutMs: number,
+  pollIntervalMs: number,
+  startTime: number,
+): Promise<PollResult> {
+  // Read the artifact HTML
+  let html: string;
+  try {
+    html = await readFile(artifactPath, "utf8");
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === "ENOENT") {
+      return { status: "not-found", answers: {}, remaining: [] };
+    }
+    throw err;
+  }
+  const meta = readEmbeddedMetadata(html);
+  if (meta === null || !isInteractiveData(meta["interactive"])) {
+    return { status: "not-found", answers: {}, remaining: [] };
+  }
+  const interactive = meta["interactive"] as InteractiveData;
+  const answers = extractAnswers(interactive);
+  const remaining = interactive.questions
+    .map((q) => q.id)
+    .filter((qid) => interactive.answers[qid] === undefined);
+  switch (interactive.status) {
+    case "complete":
+      return { status: "complete", answers, remaining };
+    case "expired":
+      return { status: "expired", answers, remaining };
+    case "cancelled":
+      return { status: "cancelled", answers, remaining };
+    case "open":
+      break;
+  }
+  // Check timeout
+  if (Date.now() - startTime >= timeoutMs) {
+    return { status: "incomplete", answers, remaining };
+  }
+  // Sleep then recurse
+  await sleep(pollIntervalMs);
+  // Check timeout again after sleep (in case sleep took longer)
+  if (Date.now() - startTime >= timeoutMs) {
+    return { status: "incomplete", answers, remaining };
+  }
+  return pollLoop(artifactPath, timeoutMs, pollIntervalMs, startTime);
+}
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+function isInteractiveData(v: unknown): v is InteractiveData {
+  if (v === null || typeof v !== "object" || Array.isArray(v)) return false;
+  const raw = v as Record<string, unknown>;
+  return (
+    (raw["status"] === "open" ||
+      raw["status"] === "complete" ||
+      raw["status"] === "expired" ||
+      raw["status"] === "cancelled") &&
+    Array.isArray(raw["questions"])
+  );
+}
+function extractAnswers(interactive: InteractiveData): Record<string, AnswerValue> {
+  const answers: Record<string, AnswerValue> = {};
+  for (const [id, entry] of Object.entries(interactive.answers)) {
+    answers[id] = entry.value;
+  }
+  return answers;
+}
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}