@vimhead.dev/norn-cli 0.1.0-tip.0

package/dist/internal/agents.js

@@ -0,0 +1,336 @@
+// src/internal/agents.ts
+import {
+  SessionManager,
+  createAgentSessionServices,
+  createAgentSessionFromServices,
+  createEventBus
+} from "@earendil-works/pi-coding-agent";
+import { randomUUID } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+
+// ../core/src/agent-protocol.ts
+var AGENT_RESPONSE_TOOL_NAME = "pi_workflows_agent_response";
+
+// src/internal/agents.ts
+import {
+  NornAgentResponseToolFactory
+} from "./agent-response-tool.js";
+import { resolveNornAgentDirectory } from "./agent-directory.js";
+import { errorMessage } from "./errors.js";
+import { safeFileName } from "./file-names.js";
+import { NornSessionResourceBindings } from "./resource-bindings.js";
+import { agentUsageFromValue, emptyAgentUsage, totalAgentUsage } from "./usage.js";
+var DEFAULT_AGENT_ATTEMPTS = 3;
+var DEFAULT_AGENT_TOOL_ALLOWLIST = ["read", "bash", "edit", "write", AGENT_RESPONSE_TOOL_NAME];
+var NornAgentRunner = class {
+  constructor(input) {
+    this.input = input;
+    this.responseToolFactory = new NornAgentResponseToolFactory(input.responseCollector);
+  }
+  input;
+  responseToolFactory;
+  async createSession(agentInput) {
+    const cwd = agentInput.cwd ? this.resolveFromCwd(agentInput.cwd) : this.input.cwd;
+    const sessionDir = resolve(this.input.runRoot, "sessions");
+    await mkdir(sessionDir, { recursive: true });
+    const eventBus = createEventBus();
+    const agentDir = this.input.agentDir ?? resolveNornAgentDirectory({ home: homedir(), environment: process.env });
+    const services = await createAgentSessionServices({
+      cwd,
+      agentDir,
+      resourceLoaderOptions: {
+        eventBus,
+        systemPromptOverride: systemPromptOverride(agentInput),
+        appendSystemPromptOverride: appendSystemPromptOverride(agentInput)
+      }
+    });
+    const loader = services.resourceLoader;
+    const errors = [
+      ...services.diagnostics.filter((diagnostic) => diagnostic.type === "error").map((diagnostic) => diagnostic.message),
+      ...loader.getExtensions().errors.map((error) => `Failed to load extension ${error.path}: ${error.error}`)
+    ];
+    if (errors.length > 0) throw new Error(errors.join("\n"));
+    const resourceBindings = new NornSessionResourceBindings();
+    let session;
+    try {
+      await resourceBindings.bind({
+        adapters: agentInput.resourceAdapters ?? [],
+        runId: this.input.id,
+        label: agentInput.label,
+        reservedTools: [
+          "read",
+          "bash",
+          "edit",
+          "write",
+          "grep",
+          "find",
+          "ls",
+          "powershell",
+          AGENT_RESPONSE_TOOL_NAME,
+          ...loader.getExtensions().extensions.flatMap((extension) => [...extension.tools.keys()])
+        ]
+      });
+      ({ session } = await createAgentSessionFromServices({
+        services,
+        sessionManager: SessionManager.create(cwd, sessionDir),
+        tools: [...withAgentResponseTool(agentInput.tools), ...resourceBindings.tools.map((tool) => tool.name)],
+        customTools: [this.responseToolFactory.create(), ...resourceBindings.tools],
+        model: agentInput.model ?? this.input.model,
+        thinkingLevel: agentInput.thinkingLevel ?? this.input.thinkingLevel
+      }));
+      await agentInput.beforeSessionStart?.({ events: eventBus });
+      await session.bindExtensions({});
+      await this.input.logger.record({ type: "agent.spawned", label: agentInput.label, cwd });
+      return new CreatedNornAgentSession({
+        ...this.input,
+        label: agentInput.label,
+        cwd,
+        session,
+        resourceBindings,
+        events: eventBus
+      });
+    } catch (error) {
+      const errors2 = [error];
+      try {
+        session?.dispose();
+      } catch (cleanupError) {
+        errors2.push(cleanupError);
+      }
+      try {
+        await resourceBindings.dispose();
+      } catch (cleanupError) {
+        errors2.push(cleanupError);
+      }
+      if (errors2.length > 1) throw new AggregateError(errors2, "Agent creation and resource cleanup failed");
+      throw error;
+    }
+  }
+  async prompt(agentInput) {
+    const agent = await this.createSession(agentInput);
+    try {
+      return await agent.prompt(agentInput);
+    } finally {
+      await agent.dispose();
+    }
+  }
+  resolveFromCwd(path) {
+    const resolvedPath = isAbsolute(path) ? path : resolve(this.input.cwd, path);
+    const pathFromBoundary = relative(this.input.boundaryRoot, resolvedPath);
+    if (pathFromBoundary === ".." || pathFromBoundary.startsWith(`..${sep}`) || isAbsolute(pathFromBoundary)) {
+      throw new Error(`Agent cwd escapes ${this.input.boundaryName} isolation: ${path}`);
+    }
+    return resolvedPath;
+  }
+};
+function systemPromptOverride(agentInput) {
+  const systemPrompt = agentInput.systemPrompt;
+  return systemPrompt === void 0 ? void 0 : () => systemPrompt;
+}
+function appendSystemPromptOverride(agentInput) {
+  const appendSystemPrompt = agentInput.appendSystemPrompt;
+  return appendSystemPrompt === void 0 ? void 0 : (base) => [...base, ...appendSystemPrompt];
+}
+var CreatedNornAgentSession = class {
+  constructor(input) {
+    this.input = input;
+    this.label = input.label;
+    this.cwd = input.cwd;
+    this.events = input.events;
+  }
+  input;
+  label;
+  cwd;
+  events;
+  isDisposed = false;
+  async prompt(agentInput) {
+    return (await this.promptWithResult(agentInput)).response;
+  }
+  async promptWithResult(agentInput) {
+    if (this.isDisposed) throw new Error(`Workflow agent session is disposed: ${this.label}`);
+    const maxAttempts = Math.max(1, Math.floor(agentInput.maxAttempts ?? DEFAULT_AGENT_ATTEMPTS));
+    const attempts = [];
+    const startedAtMs = Date.now();
+    let isTerminalEventRecorded = false;
+    await this.input.logger.record({ type: "agent.started", label: this.label, cwd: this.cwd, maxAttempts });
+    try {
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        await this.input.logger.record({ type: "agent.attempt.started", label: this.label, attempt });
+        const raw = await this.runAttempt(agentInput, attempt, attempts.at(-1)?.error);
+        const rawAttempt = { attempt, ...raw };
+        attempts.push(rawAttempt);
+        try {
+          if (!raw.responseToolCalled) throw new Error(`Agent did not call ${AGENT_RESPONSE_TOOL_NAME}`);
+          const response = agentInput.response.parse(raw.toolResponse);
+          const usage = totalAgentUsage(attempts.map((candidate) => candidate.usage));
+          const result = {
+            label: this.label,
+            cwd: this.cwd,
+            response,
+            usage,
+            raw: { ...raw, usage, attempts }
+          };
+          await this.input.logs.write(`agents/${safeFileName(this.label)}.json`, JSON.stringify(result, null, 2));
+          isTerminalEventRecorded = true;
+          await this.input.logger.record({ type: "agent.completed", label: this.label, attempts: attempt, durationMs: Date.now() - startedAtMs, usage });
+          return result;
+        } catch (error) {
+          const message = errorMessage(error);
+          attempts[attempts.length - 1] = { ...rawAttempt, error: message };
+          await this.input.logs.write(
+            `agents/${safeFileName(this.label)}.attempt-${attempt}.raw.json`,
+            JSON.stringify({ label: this.label, cwd: this.cwd, raw: attempts.at(-1) }, null, 2)
+          );
+          await this.input.logger.record({ type: "agent.attempt.failed", label: this.label, attempt, error: message });
+          if (attempt === maxAttempts) {
+            const usage = totalAgentUsage(attempts.map((candidate) => candidate.usage));
+            isTerminalEventRecorded = true;
+            await this.input.logger.record({ type: "agent.failed", label: this.label, attempts: attempt, durationMs: Date.now() - startedAtMs, usage, error: message });
+            throw new Error(
+              `Agent ${this.label} did not return a valid structured response after ${attempt} attempt(s). Raw output saved to logs/agents/${safeFileName(this.label)}.attempt-${attempt}.raw.json: ${message}`
+            );
+          }
+        }
+      }
+      throw new Error(`Agent ${this.label} did not run`);
+    } catch (error) {
+      if (!isTerminalEventRecorded) {
+        await this.input.logger.record({
+          type: "agent.failed",
+          label: this.label,
+          attempts: attempts.length,
+          durationMs: Date.now() - startedAtMs,
+          usage: totalAgentUsage(attempts.map((candidate) => candidate.usage)),
+          error: errorMessage(error)
+        });
+      }
+      throw error;
+    }
+  }
+  async dispose() {
+    if (this.isDisposed) return;
+    this.isDisposed = true;
+    const errors = [];
+    try {
+      await this.input.session.abort();
+    } catch (error) {
+      errors.push(error);
+    }
+    try {
+      this.input.session.dispose();
+    } catch (error) {
+      errors.push(error);
+    }
+    try {
+      await this.input.resourceBindings.dispose();
+    } catch (error) {
+      errors.push(error);
+    }
+    if (errors.length) throw new AggregateError(errors, "Agent disposal failed");
+    await this.input.logger.record({ type: "agent.disposed", label: this.label });
+  }
+  async runAttempt(agentInput, attempt, previousError) {
+    const responseRunId = `${this.input.id}:${attempt}:${randomUUID()}`;
+    const messages = [];
+    let text = "";
+    const releaseResponseSlot = this.input.responseCollector.begin(responseRunId, this.label, agentInput.response);
+    const unsubscribe = this.input.session.subscribe((event) => {
+      if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+        text += event.assistantMessageEvent.delta;
+      }
+      if (event.type === "message_end" && event.message) messages.push(event.message);
+    });
+    const abortNestedSession = () => {
+      void this.input.session.abort();
+    };
+    this.input.signal?.addEventListener("abort", abortNestedSession, { once: true });
+    let capturedResponse = { called: false };
+    try {
+      this.input.signal?.throwIfAborted();
+      await this.input.session.prompt(withResponseToolInstruction(agentInput.prompt, agentInput.response, this.label, responseRunId, attempt, previousError), {
+        ...agentInput.options,
+        source: agentInput.options?.source ?? "extension"
+      });
+      this.input.signal?.throwIfAborted();
+      capturedResponse = this.input.responseCollector.get(responseRunId);
+      if (!capturedResponse.called) {
+        await this.promptForStructuredResponse(agentInput, responseRunId, attempt, previousError);
+        this.input.signal?.throwIfAborted();
+        capturedResponse = this.input.responseCollector.get(responseRunId);
+      }
+    } finally {
+      this.input.signal?.removeEventListener("abort", abortNestedSession);
+      releaseResponseSlot();
+      unsubscribe();
+    }
+    return {
+      text: text.trim(),
+      messages,
+      responseToolCalled: capturedResponse.called,
+      usage: usageFromMessages(messages),
+      toolResponse: capturedResponse.response,
+      sessionFile: this.input.session.sessionFile
+    };
+  }
+  async promptForStructuredResponse(agentInput, responseRunId, attempt, previousError) {
+    const activeToolNames = this.input.session.getActiveToolNames();
+    await this.input.logger.record({ type: "agent.response-finalization.started", label: this.label, attempt });
+    this.input.session.setActiveToolsByName([AGENT_RESPONSE_TOOL_NAME]);
+    try {
+      await this.input.session.prompt(withResponseToolFinalizationInstruction(agentInput.response, this.label, responseRunId, attempt, previousError), {
+        ...agentInput.options,
+        source: agentInput.options?.source ?? "extension"
+      });
+      await this.input.logger.record({ type: "agent.response-finalization.completed", label: this.label, attempt });
+    } catch (error) {
+      await this.input.logger.record({ type: "agent.response-finalization.failed", label: this.label, attempt, error: errorMessage(error) });
+      throw error;
+    } finally {
+      this.input.session.setActiveToolsByName(activeToolNames);
+    }
+  }
+};
+function usageFromMessages(messages) {
+  return totalAgentUsage(messages.map(usageFromMessage).filter((usage) => usage !== void 0));
+}
+function usageFromMessage(message) {
+  if (!message || typeof message !== "object" || !("usage" in message)) return void 0;
+  return agentUsageFromValue(message.usage) ?? emptyAgentUsage();
+}
+function withResponseToolInstruction(prompt, responseSchema, label, responseRunId, attempt, previousError) {
+  return [
+    prompt,
+    "",
+    "Structured workflow response:",
+    `Use the ${AGENT_RESPONSE_TOOL_NAME} tool as your final action to record the workflow response.`,
+    "Do not emit the workflow response as assistant text or Markdown.",
+    `Pass runId exactly as: ${responseRunId}`,
+    `Pass label exactly as: ${label}`,
+    "Pass the structured workflow response in the tool's response argument.",
+    "The response argument must match this JSON Schema:",
+    JSON.stringify(z.toJSONSchema(responseSchema), null, 2),
+    ...attempt > 1 && previousError ? ["", `Previous structured response attempt failed: ${previousError}`] : []
+  ].join("\n");
+}
+function withResponseToolFinalizationInstruction(responseSchema, label, responseRunId, attempt, previousError) {
+  return [
+    "Your previous workflow response turn ended without recording the structured response.",
+    `Use the ${AGENT_RESPONSE_TOOL_NAME} tool now. It is the only active tool for this turn.`,
+    "Do not answer in assistant text or Markdown.",
+    `Pass runId exactly as: ${responseRunId}`,
+    `Pass label exactly as: ${label}`,
+    "Pass the structured workflow response in the tool's response argument, based on the work you already completed in this session.",
+    "The response argument must match this JSON Schema:",
+    JSON.stringify(z.toJSONSchema(responseSchema), null, 2),
+    ...attempt > 1 && previousError ? ["", `Previous structured response attempt failed: ${previousError}`] : []
+  ].join("\n");
+}
+function withAgentResponseTool(tools) {
+  if (!tools) return [...DEFAULT_AGENT_TOOL_ALLOWLIST];
+  return Array.from(/* @__PURE__ */ new Set([...tools, AGENT_RESPONSE_TOOL_NAME]));
+}
+export {
+  NornAgentRunner
+};

package/dist/internal/artifacts.d.ts

@@ -0,0 +1,10 @@
+import type { NornFileCoordinator } from "@vimhead.dev/norn/files";
+import type { NornArtifactRef } from "@vimhead.dev/norn";
+export declare class NornArtifacts {
+    private readonly artifactsRoot;
+    private readonly files;
+    constructor(artifactsRoot: string, files: NornFileCoordinator);
+    write(path: string, content: string): Promise<NornArtifactRef>;
+    read(ref: NornArtifactRef): Promise<string>;
+    private resolveArtifactPath;
+}

package/dist/internal/artifacts.js

@@ -0,0 +1,29 @@
+// src/internal/artifacts.ts
+import { isAbsolute, relative, resolve, sep } from "node:path";
+var NornArtifacts = class {
+  constructor(artifactsRoot, files) {
+    this.artifactsRoot = artifactsRoot;
+    this.files = files;
+  }
+  artifactsRoot;
+  files;
+  async write(path, content) {
+    await this.files.writeText(this.resolveArtifactPath(path), content);
+    return { path };
+  }
+  async read(ref) {
+    return this.files.readText(this.resolveArtifactPath(ref.path));
+  }
+  resolveArtifactPath(path) {
+    if (isAbsolute(path)) throw new Error(`Artifact path must be relative: ${path}`);
+    const resolvedPath = resolve(this.artifactsRoot, path);
+    const relativePath = relative(this.artifactsRoot, resolvedPath);
+    if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
+      throw new Error(`Artifact path escapes artifacts directory: ${path}`);
+    }
+    return resolvedPath;
+  }
+};
+export {
+  NornArtifacts
+};

package/dist/internal/commands.d.ts

@@ -0,0 +1,18 @@
+import type { NornCommandRunInput, NornCommandRunResult } from "@vimhead.dev/norn";
+import type { NornRunLogs } from "./logs.ts";
+import type { NornRunLogger } from "./run-log.ts";
+type NornCommandRunnerInput = {
+    readonly boundaryRoot: string;
+    readonly boundaryName: string;
+    readonly cwd: string;
+    readonly signal?: AbortSignal;
+    readonly logs: NornRunLogs;
+    readonly logger: NornRunLogger;
+};
+export declare class NornCommandRunner {
+    private readonly input;
+    constructor(input: NornCommandRunnerInput);
+    run(commandInput: NornCommandRunInput): Promise<NornCommandRunResult>;
+    private resolveFromCwd;
+}
+export {};

package/dist/internal/commands.js

@@ -0,0 +1,147 @@
+// src/internal/commands.ts
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { errorMessage } from "./errors.js";
+import { safeFileName } from "./file-names.js";
+var NornCommandRunner = class {
+  constructor(input) {
+    this.input = input;
+  }
+  input;
+  async run(commandInput) {
+    const cwd = this.resolveFromCwd(commandInput.cwd ?? this.input.cwd);
+    const startedAtMs = Date.now();
+    const invocationId = randomUUID();
+    const stdoutRef = commandLog({ label: commandInput.label, invocationId, stream: "stdout" });
+    const stderrRef = commandLog({ label: commandInput.label, invocationId, stream: "stderr" });
+    await this.input.logger.record({ type: "command.started", invocationId, label: commandInput.label, command: commandInput.command, cwd, stdoutLogId: stdoutRef.id, stderrLogId: stderrRef.id });
+    let result;
+    const stdoutLog = await this.input.logs.createWriteStream(stdoutRef);
+    const stderrLog = await this.input.logs.createWriteStream(stderrRef);
+    try {
+      result = await spawnCommand({
+        command: commandInput.command,
+        cwd,
+        env: { ...process.env, ...commandInput.env ?? {} },
+        timeoutMs: commandInput.timeoutMs,
+        signal: this.input.signal,
+        stdoutStream: stdoutLog.stream,
+        stderrStream: stderrLog.stream
+      });
+    } catch (error) {
+      await this.input.logger.record({ type: "command.failed", invocationId, label: commandInput.label, durationMs: Date.now() - startedAtMs, error: errorMessage(error) });
+      throw error;
+    }
+    const commandResult = {
+      label: commandInput.label,
+      command: commandInput.command,
+      cwd,
+      exitCode: result.exitCode,
+      stdoutTail: result.stdoutTail,
+      stderrTail: result.stderrTail,
+      killed: result.killed,
+      stdoutLog: stdoutLog.log,
+      stderrLog: stderrLog.log
+    };
+    await this.input.logger.record({
+      type: "command.completed",
+      invocationId,
+      label: commandInput.label,
+      durationMs: Date.now() - startedAtMs,
+      exitCode: result.exitCode,
+      killed: result.killed,
+      stdoutLogId: commandResult.stdoutLog.id,
+      stderrLogId: commandResult.stderrLog.id
+    });
+    return commandResult;
+  }
+  resolveFromCwd(path) {
+    const resolvedPath = isAbsolute(path) ? path : resolve(this.input.cwd, path);
+    const pathFromBoundary = relative(this.input.boundaryRoot, resolvedPath);
+    if (pathFromBoundary === ".." || pathFromBoundary.startsWith(`..${sep}`) || isAbsolute(pathFromBoundary)) {
+      throw new Error(`Command cwd escapes ${this.input.boundaryName} isolation: ${path}`);
+    }
+    return resolvedPath;
+  }
+};
+async function spawnCommand(input) {
+  const command = typeof input.command === "string" ? "bash" : input.command[0];
+  const args = typeof input.command === "string" ? ["-c", input.command] : input.command.slice(1);
+  let killed = false;
+  const stdout = new BoundedTextBuffer();
+  const stderr = new BoundedTextBuffer();
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(command, args, { cwd: input.cwd, env: input.env, shell: false });
+    let timeout;
+    let escalation;
+    let isSettled = false;
+    const cleanup = () => {
+      if (timeout) clearTimeout(timeout);
+      if (escalation) clearTimeout(escalation);
+      input.signal?.removeEventListener("abort", killChild);
+    };
+    const finish = (result) => {
+      if (isSettled) return;
+      isSettled = true;
+      cleanup();
+      void closeStreams(input.stdoutStream, input.stderrStream).then(() => resolvePromise(result), reject);
+    };
+    const fail = (error) => {
+      if (isSettled) return;
+      isSettled = true;
+      cleanup();
+      void closeStreams(input.stdoutStream, input.stderrStream).then(() => reject(error), reject);
+    };
+    const killChild = () => {
+      if (isSettled || killed) return;
+      killed = true;
+      child.kill("SIGTERM");
+      escalation = setTimeout(() => {
+        if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+      }, 5e3);
+      escalation.unref?.();
+    };
+    if (input.timeoutMs !== void 0) timeout = setTimeout(killChild, input.timeoutMs);
+    if (input.signal?.aborted) killChild();
+    input.signal?.addEventListener("abort", killChild, { once: true });
+    child.stdout?.on("data", (chunk) => {
+      const text = chunk.toString();
+      stdout.append(text);
+      input.stdoutStream.write(text);
+    });
+    child.stderr?.on("data", (chunk) => {
+      const text = chunk.toString();
+      stderr.append(text);
+      input.stderrStream.write(text);
+    });
+    child.on("error", fail);
+    child.on("close", (code) => finish({ exitCode: code, stdoutTail: stdout.value(), stderrTail: stderr.value(), killed }));
+  });
+}
+function commandLog(input) {
+  return { id: `commands/${safeFileName(input.label)}-${input.invocationId}.${input.stream}` };
+}
+var BoundedTextBuffer = class {
+  constructor(maxChars = 128e3) {
+    this.maxChars = maxChars;
+  }
+  maxChars;
+  text = "";
+  append(value) {
+    this.text += value;
+    if (this.text.length > this.maxChars) this.text = this.text.slice(this.text.length - this.maxChars);
+  }
+  value() {
+    return this.text;
+  }
+};
+async function closeStreams(...streams) {
+  await Promise.all(streams.map((stream) => new Promise((resolvePromise, reject) => {
+    stream.on("error", reject);
+    stream.end(resolvePromise);
+  })));
+}
+export {
+  NornCommandRunner
+};

package/dist/internal/documentation-bundle.d.ts

@@ -0,0 +1,16 @@
+export type NornDocumentationFile = {
+    readonly path: string;
+    readonly content: string;
+};
+export type NornDocumentationBundle = {
+    readonly version: string;
+    readonly files: readonly NornDocumentationFile[];
+};
+export declare const DOCUMENTATION_PATHS: {
+    readonly readme: "README.md";
+    readonly index: "docs/README.md";
+    readonly docs: "docs";
+    readonly examples: "examples";
+};
+export declare function validateDocumentationBundle(bundle: NornDocumentationBundle): void;
+export declare function hashDocumentationBundle(bundle: NornDocumentationBundle): string;

package/dist/internal/documentation-bundle.js

@@ -0,0 +1,42 @@
+// src/internal/documentation-bundle.ts
+import { createHash } from "node:crypto";
+var DOCUMENTATION_PATHS = {
+  readme: "README.md",
+  index: "docs/README.md",
+  docs: "docs",
+  examples: "examples"
+};
+function validateDocumentationBundle(bundle) {
+  if (typeof bundle.version !== "string" || bundle.version.length === 0) throw new Error("Documentation bundle version must not be empty");
+  const paths = /* @__PURE__ */ new Set();
+  for (const file of bundle.files) {
+    if (typeof file.content !== "string") throw new Error(`Documentation asset must contain text: ${file.path}`);
+    if (typeof file.path !== "string" || !/^[a-zA-Z0-9._/-]+$/.test(file.path) || file.path.split("/").some((part) => part === "" || part === "." || part === ".." || part.endsWith(".") || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))) {
+      throw new Error(`Invalid documentation asset path: ${file.path}`);
+    }
+    const portablePath = file.path.toLowerCase();
+    if (paths.has(portablePath)) throw new Error(`Duplicate documentation asset path: ${file.path}`);
+    paths.add(portablePath);
+  }
+  for (const path of paths) {
+    const parts = path.split("/");
+    while (parts.pop() && parts.length > 0) {
+      if (paths.has(parts.join("/"))) throw new Error(`Documentation file/directory collision: ${path}`);
+    }
+  }
+  for (const path of [DOCUMENTATION_PATHS.readme, DOCUMENTATION_PATHS.index]) {
+    if (!bundle.files.some((file) => file.path === path)) throw new Error(`Missing documentation asset: ${path}`);
+  }
+  if (!bundle.files.some((file) => file.path.startsWith("examples/"))) throw new Error("Missing documentation examples");
+}
+function hashDocumentationBundle(bundle) {
+  return createHash("sha256").update(JSON.stringify({
+    version: bundle.version,
+    files: bundle.files.map((file) => ({ path: file.path, content: file.content })).sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0)
+  })).digest("hex");
+}
+export {
+  DOCUMENTATION_PATHS,
+  hashDocumentationBundle,
+  validateDocumentationBundle
+};

package/dist/internal/engine.d.ts

@@ -0,0 +1,44 @@
+import { type NornAnyWorkflowDeclaration, type NornAnyWorkflowPluginManifest, type NornDispose, type NornRunStartOptions, type NornRunResult, type NornRunCheckpoint, type NornRunInfo, type NornWorkflowPlugin } from "@vimhead.dev/norn";
+import { NornAgentResponseCollector } from "./agent-response-tool.ts";
+import { type NornRunResumeRequest } from "./launch-request.ts";
+import { type NornRegisteredWorkflow } from "./workflow-registry.ts";
+export type NornEngineInput = {
+    readonly cwd: string;
+    readonly agentDir?: string;
+    readonly signal?: AbortSignal;
+    readonly responseCollector?: NornAgentResponseCollector;
+    readonly gateMode?: "auto" | "pause";
+    readonly config?: Record<string, unknown>;
+};
+export declare class NornEngine {
+    private readonly input;
+    private readonly registry;
+    private readonly registrarState;
+    private readonly disposersByPlugin;
+    private readonly responseCollector;
+    private readonly activeRuns;
+    constructor(input: NornEngineInput);
+    registerPlugin<TManifest extends NornAnyWorkflowPluginManifest>(plugin: NornWorkflowPlugin<TManifest>): NornDispose;
+    listWorkflows(): import("@vimhead.dev/norn").NornRegisteredWorkflowInfo[];
+    visibleWorkflowEntries(): NornRegisteredWorkflow[];
+    private resolvePluginImplementation;
+    runWorkflow<TWorkflow extends NornAnyWorkflowDeclaration>(workflow: TWorkflow, params: unknown, options: NornRunStartOptions | undefined): Promise<NornRunResult>;
+    listRunCheckpoints(path: string): Promise<NornRunCheckpoint[]>;
+    rollbackRun(path: string, checkpointId: string): Promise<NornRunInfo>;
+    resumeWorkflow(path: string, params?: unknown): Promise<NornRunResult>;
+    resumeRequestedWorkflow(input: {
+        readonly runRoot: string;
+        readonly request: NornRunResumeRequest;
+    }): Promise<NornRunResult>;
+    private resumeWorkflowExecution;
+    private runScheduler;
+    private executeWorkflowStep;
+    private nextWorkflowStep;
+    private createRunSession;
+    private openRunSession;
+    private buildRun;
+    private startActiveRun;
+    private finishActiveRun;
+    private failActiveRun;
+    private disposePlugin;
+}