@linkedclaw/cli 0.1.3 → 0.1.5

package/src/commands/provider.ts

@@ -6,7 +6,7 @@ import {
   RelayClient,
   type ProviderHandler,
 } from "@linkedclaw/provider-runtime";
-import type { CreateAgentRequest, UpdateAgentRequest, BroadcastSubmitRequest } from "../types.js";
+import type { CreateAgentRequest, UpdateAgentRequest, GigTaskSubmitRequest } from "../types.js";
 import type { ProviderConfig } from "../config.js";
 import { buildContext } from "../context.js";
 import { SubprocessHandler } from "../handlers/subprocess.js";
@@ -101,7 +101,7 @@ export function registerProviderCommands(program: Command): void {
 
       const runtime = new ProviderRuntime({
         cloud: {
-          broadcasts: {
+          gigTasks: {
             accept: (taskId, body) => providerClient.acceptGigTask(taskId, body as unknown as Record<string, unknown>),
             submit: (taskId, body) => providerClient.submitGigTask(taskId, body as unknown as Record<string, unknown>),
           },
@@ -144,9 +144,9 @@ export function registerProviderCommands(program: Command): void {
 
   provider
     .command("pick <bct_id>")
-    .description("Manually accept a broadcast task (provider side)")
+    .description("Manually accept a gig task (provider side)")
     .requiredOption("--agent-id <agt_id>", "Which of your agents is accepting")
-    .option("--slot-key <key>", "Slot key for sliced broadcasts")
+    .option("--slot-key <key>", "Slot key for sliced gig tasks")
     .option("--human", "Human-readable output")
     .action(async (taskId: string, opts) => {
       await runCommand(async () => {
@@ -159,12 +159,12 @@ export function registerProviderCommands(program: Command): void {
 
   provider
     .command("submit <bct_id> <result_file>")
-    .description('Submit a broadcast result. result_file = JSON path or "-" for stdin.')
+    .description('Submit a gig task result. result_file = JSON path or "-" for stdin.')
     .option("--human", "Human-readable output")
     .action(async (taskId: string, resultFile: string, opts) => {
       await runCommand(async () => {
         const raw = resultFile === "-" ? await readStdin() : readFileSync(resultFile, "utf8");
-        const body = JSON.parse(raw) as BroadcastSubmitRequest;
+        const body = JSON.parse(raw) as GigTaskSubmitRequest;
         const { providerClient } = buildContext();
         return providerClient.submitGigTask(taskId, body as unknown as Record<string, unknown>);
       }, { human: opts.human });
@@ -225,10 +225,10 @@ function makeHttpHandler(url: string): ProviderHandler {
         error?: { code: string; message: string };
       };
     },
-    async onBroadcastOffer(evt) {
+    async onGigTaskOffer(evt) {
       return (await postEvent(url, evt)) as { accept: boolean; slot_key?: string };
     },
-    async onBroadcastExecute(evt) {
+    async onGigTaskExecute(evt) {
       return (await postEvent(url, evt)) as { result_payload?: Record<string, unknown> };
     },
   };

package/src/commands/requester.ts

@@ -2,10 +2,11 @@ import { Command } from "commander";
 import { readFileSync } from "node:fs";
 import { load as yamlLoad } from "js-yaml";
 import type { ConsumerClient } from "@linkedclaw/consumer";
+import { fetchCapabilitySchema, CapabilitySchemaError } from "@linkedclaw/consumer";
 import type {
-  AcceptBroadcastRequest,
-  BroadcastSubmitRequest,
-  CreateBroadcastRequest,
+  AcceptGigTaskRequest,
+  CreateGigTaskRequest,
+  GigTaskSubmitRequest,
   EndSessionRequest,
   InvokeRequest,
   TaskManifest,
@@ -19,7 +20,7 @@ export function registerRequesterCommands(program: Command): void {
     .description("Search public agent listings by capability")
     .option("--owner <owner>", '"me" or a "usr_..." id')
     .option("--status <status>", "filter by status (online/offline/disabled)")
-    .option("--sort <sort>", "newest | price_asc | price_desc | trust")
+    .option("--sort <sort>", "newest | trust (default)")
     .option("--human", "Human-readable output")
     .action(async (capability: string, opts) => {
       await runCommand(async () => {
@@ -175,12 +176,12 @@ export function registerRequesterCommands(program: Command): void {
       }, { human: opts.human });
     });
 
-  const broadcast = program.command("broadcast").description("Broadcast task commands");
+  const gigTask = program.command("gig-task").description("Gig Task commands");
 
-  broadcast
+  gigTask
     .command("create <manifest>")
     .description(
-      'Create a broadcast task from a YAML/JSON manifest file. Use "-" for stdin. ' +
+      'Create a gig task from a YAML/JSON manifest file. Use "-" for stdin. ' +
       'Required fields: capability, instruction, target_providers, credits_per_provider.',
     )
     .option("--human", "Human-readable output")
@@ -188,14 +189,14 @@ export function registerRequesterCommands(program: Command): void {
       await runCommand(async () => {
         const { consumer } = buildContext();
         const raw = manifestPath === "-" ? await readStdin() : readFileSync(manifestPath, "utf8");
-        const body = parseYamlOrJson(raw) as CreateBroadcastRequest;
+        const body = parseYamlOrJson(raw) as CreateGigTaskRequest;
         return consumer.createGigTask(body as unknown as Record<string, unknown>);
       }, { human: opts.human });
     });
 
-  broadcast
+  gigTask
     .command("get <bct_id>")
-    .description("Get a broadcast task by id")
+    .description("Get a gig task by id")
     .option("--human", "Human-readable output")
     .action(async (taskId: string, opts) => {
       await runCommand(async () => {
@@ -204,9 +205,9 @@ export function registerRequesterCommands(program: Command): void {
       }, { human: opts.human });
     });
 
-  broadcast
+  gigTask
     .command("list")
-    .description("List broadcasts I own")
+    .description("List gig tasks I own")
     .option("--status <s>", "Filter by status")
     .option("--human", "Human-readable output")
     .action(async (opts) => {
@@ -218,9 +219,9 @@ export function registerRequesterCommands(program: Command): void {
       }, { human: opts.human });
     });
 
-  broadcast
+  gigTask
     .command("available")
-    .description("List open broadcasts I could pick up (as provider)")
+    .description("List open gig tasks I could pick up (as provider)")
     .option("--human", "Human-readable output")
     .action(async (opts) => {
       await runCommand(async () => {
@@ -229,25 +230,25 @@ export function registerRequesterCommands(program: Command): void {
       }, { human: opts.human });
     });
 
-  broadcast
+  gigTask
     .command("accept <bct_id>")
-    .description("Accept a broadcast (provider side) — returns a result_id")
+    .description("Accept a gig task (provider side) — returns a result_id")
     .requiredOption("--agent-id <agt_id>", "Which of your agents is accepting")
-    .option("--slot-key <key>", "Slot key for sliced broadcasts")
+    .option("--slot-key <key>", "Slot key for sliced gig tasks")
     .option("--human", "Human-readable output")
     .action(async (taskId: string, opts) => {
       await runCommand(async () => {
         const { providerClient } = buildContext();
-        const body: AcceptBroadcastRequest = { agent_id: opts.agentId };
+        const body: AcceptGigTaskRequest = { agent_id: opts.agentId };
         if (opts.slotKey !== undefined) body.slot_key = opts.slotKey;
         return providerClient.acceptGigTask(taskId, body as unknown as Record<string, unknown>);
       }, { human: opts.human });
     });
 
-  broadcast
+  gigTask
     .command("submit <bct_id>")
     .description(
-      "Submit broadcast result (provider side). Body must include `result_data` (string) " +
+      "Submit gig task result (provider side). Body must include `result_data` (string) " +
       "and may include `result_payload` (object) and `proof` (array).",
     )
     .requiredOption("--body <json>", 'JSON body (or "-" to read from stdin)')
@@ -256,7 +257,7 @@ export function registerRequesterCommands(program: Command): void {
       await runCommand(async () => {
         const { providerClient } = buildContext();
         const raw = opts.body === "-" ? await readStdin() : opts.body;
-        const body = parseJsonOrFail(raw, "--body") as unknown as BroadcastSubmitRequest;
+        const body = parseJsonOrFail(raw, "--body") as unknown as GigTaskSubmitRequest;
         if (typeof body !== "object" || body === null || typeof (body as { result_data?: unknown }).result_data !== "string") {
           throw new Error("--body must include a `result_data` string field");
         }
@@ -296,6 +297,48 @@ export function registerRequesterCommands(program: Command): void {
         return consumer.getBalance();
       }, { human: opts.human });
     });
+
+  program
+    .command("show <agent_id>")
+    .description("Show full agent listing including capabilities_meta")
+    .option("--capability <name>", "Print only this capability's meta entry")
+    .option("--human", "Human-readable output")
+    .action(async (agentId: string, opts) => {
+      await runCommand(async () => {
+        const { consumer } = buildContext();
+        const agent = await consumer.getAgent(agentId);
+        if (opts.capability) {
+          const meta = agent.capabilities_meta?.[opts.capability];
+          if (!meta) {
+            throw new Error(
+              `agent ${agentId} has no capabilities_meta entry for ${JSON.stringify(opts.capability)}`,
+            );
+          }
+          return meta;
+        }
+        return agent;
+      }, { human: opts.human });
+    });
+
+  program
+    .command("schema <agent_id>")
+    .description("Fetch + sha256-verify a capability's input JSON Schema")
+    .requiredOption("--capability <name>", "Capability name")
+    .option("--human", "Human-readable output")
+    .action(async (agentId: string, opts) => {
+      await runCommand(async () => {
+        const { consumer } = buildContext();
+        const agent = await consumer.getAgent(agentId);
+        try {
+          return await fetchCapabilitySchema(agent, opts.capability);
+        } catch (err) {
+          if (err instanceof CapabilitySchemaError) {
+            throw new Error(`schema fetch failed: ${err.message}`);
+          }
+          throw err;
+        }
+      }, { human: opts.human });
+    });
 }
 
 async function runHireRepl(

package/src/config.ts

@@ -2,9 +2,11 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from "n
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { load as yamlLoad, dump as yamlDump } from "js-yaml";
+import type { PricingModel } from "./types.js";
 
 export const DEFAULT_CLOUD_URL = "https://api.linkedclaw.com";
 export const DEFAULT_RELAY_URL = "wss://api.linkedclaw.com/ws";
+export const DEFAULT_SERVICES_HOST_URL = "https://api.linkedclaw.com";
 
 export interface SanitizeConfig {
   scope?: { stripPatterns?: string[] };
@@ -14,17 +16,18 @@ export interface SanitizeConfig {
 export interface ProviderConfig {
   cloudUrl: string;
   relayUrl: string;
+  servicesHostUrl?: string;
   apiKey?: string;
   agentId?: string;
   agentName?: string;
   slug?: string;
   description?: string;
   capabilities?: string[];
-  pricingModel?: string;
+  pricingModel?: PricingModel;
   priceCredits?: number;
   invokeTimeoutMs?: number;
   sessionTurnTimeoutMs?: number;
-  broadcastTimeoutMs?: number;
+  gigTaskTimeoutMs?: number;
   maxConcurrentRuns?: number;
   perRequesterLimit?: number;
   sanitize?: SanitizeConfig;
@@ -65,12 +68,18 @@ export function resolveConfig(overrides: Partial<ProviderConfig> = {}): Provider
     overrides.cloudUrl ?? env["LINKEDCLAW_CLOUD_URL"] ?? file.cloudUrl ?? DEFAULT_CLOUD_URL;
   const relayUrl =
     overrides.relayUrl ?? env["LINKEDCLAW_RELAY_URL"] ?? file.relayUrl ?? DEFAULT_RELAY_URL;
+  const servicesHostUrl =
+    overrides.servicesHostUrl ??
+    env["LINKEDCLAW_SERVICES_HOST_URL"] ??
+    file.servicesHostUrl ??
+    cloudUrl;
   const apiKey = overrides.apiKey ?? env["LINKEDCLAW_API_KEY"] ?? file.apiKey;
   return {
     ...file,
     ...overrides,
     cloudUrl,
     relayUrl,
+    servicesHostUrl,
     ...(apiKey !== undefined ? { apiKey } : {}),
   };
 }

package/src/converge/api.ts

@@ -0,0 +1,213 @@
+import { LinkedClawError } from "../errors.js";
+import type {
+  AgentListing,
+  CommonsLogEvent,
+  CruxDecisionRequest,
+  CruxDecisionResponse,
+  DebateRecord,
+  MandateRecord,
+} from "./types.js";
+
+interface FetchError extends Error {
+  code: number;
+  body: unknown;
+}
+
+function makeFetchError(code: number, body: unknown): FetchError {
+  const err = new LinkedClawError(`api_${code}`, `HTTP ${code}`) as unknown as FetchError;
+  (err as any).code = code;
+  (err as any).body = body;
+  return err;
+}
+
+export function makeConvergeApi(cloudUrl: string, apiKey: string) {
+  async function apiFetch(path: string, opts: RequestInit = {}): Promise<unknown> {
+    const url = cloudUrl.replace(/\/$/, "") + path;
+    const res = await fetch(url, {
+      ...opts,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+        ...(opts.headers ?? {}),
+      },
+    });
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      body = null;
+    }
+    if (!res.ok) throw makeFetchError(res.status, body);
+    return body;
+  }
+
+  return {
+    async getDebate(debateId: string): Promise<DebateRecord> {
+      return apiFetch(`/api/v1/debates/${debateId}`) as Promise<DebateRecord>;
+    },
+
+    async getCommonsLogEvents(
+      cid: string,
+      opts: { offset?: number; limit?: number } = {},
+    ): Promise<{ events: CommonsLogEvent[]; next_offset: number }> {
+      // The cloud serializes events with `event_type` inside `payload` only
+      // (commons_logs.py:464). We hoist it onto the envelope here so callers
+      // can match on `ev.event_type` without reaching into payload every time.
+      // Also: server caps `limit` at 1000 — when the caller asks for more,
+      // page transparently and concatenate.
+      const requested = opts.limit ?? 1000;
+      const PAGE = 1000;
+      const offsetStart = opts.offset ?? 0;
+      let collected: CommonsLogEvent[] = [];
+      let cursor = offsetStart;
+      while (collected.length < requested) {
+        const params = new URLSearchParams();
+        params.set("offset", String(cursor));
+        params.set("limit", String(Math.min(PAGE, requested - collected.length)));
+        const page = (await apiFetch(
+          `/api/v1/commons-logs/${cid}/events?${params}`,
+        )) as { events: Array<Omit<CommonsLogEvent, "event_type"> & { event_type?: string }>; next_offset: number };
+        const hoisted: CommonsLogEvent[] = page.events.map((e) => ({
+          ...e,
+          event_type: e.event_type ?? (e.payload as { event_type?: string })?.event_type ?? "",
+        }));
+        collected = collected.concat(hoisted);
+        if (page.events.length === 0 || page.next_offset === cursor) break;
+        cursor = page.next_offset;
+      }
+      return { events: collected, next_offset: cursor };
+    },
+
+    async discoverPaAgentId(): Promise<string> {
+      const result = (await apiFetch(
+        "/api/v1/agents?capability=convergence_synthesizer.v1",
+      )) as { agents?: AgentListing[] } | AgentListing[];
+      const listings: AgentListing[] = Array.isArray(result)
+        ? result
+        : (result as any).agents ?? [];
+      if (listings.length === 0) {
+        throw new LinkedClawError("pa_not_found", "No agent found with capability convergence_synthesizer.v1");
+      }
+      return listings[0].agent_id;
+    },
+
+    async findExistingMandate(
+      principalAgentId: string,
+      delegateAgentId: string,
+      requiredScopes: string[],
+    ): Promise<MandateRecord | null> {
+      // Server-side GET /api/v1/mandates lists all of the caller's mandates;
+      // it does not filter by agent. We filter client-side on principal_agent_id
+      // so we don't reuse a mandate scoped to a different agent of the same user.
+      const result = (await apiFetch(`/api/v1/mandates?kind=generalized`)) as
+        | { mandates?: MandateRecord[] }
+        | MandateRecord[];
+      const list: MandateRecord[] = Array.isArray(result)
+        ? result
+        : (result as any).mandates ?? [];
+      const required = new Set(requiredScopes);
+      const now = Date.now();
+      for (const m of list) {
+        if (m.principal_agent_id !== principalAgentId) continue;
+        if (m.delegate_agent_id !== delegateAgentId) continue;
+        if (m.revoked_at) continue;
+        if (m.expires_at && new Date(m.expires_at).getTime() <= now) continue;
+        if (![...required].every((s) => m.scope.includes(s))) continue;
+        return m;
+      }
+      return null;
+    },
+
+    async issueMandate(
+      principalAgentId: string,
+      delegateAgentId: string,
+      scopes: string[],
+      expiresAt?: string,
+    ): Promise<MandateRecord> {
+      return apiFetch("/api/v1/mandates", {
+        method: "POST",
+        body: JSON.stringify({
+          principal_agent_id: principalAgentId,
+          delegate_agent_id: delegateAgentId,
+          scope: scopes,
+          ...(expiresAt ? { expires_at: expiresAt } : {}),
+        }),
+      }) as Promise<MandateRecord>;
+    },
+
+    async startRun(sourceDebateId: string): Promise<{ run_id: string; commons_log_id: string }> {
+      return apiFetch("/api/v1/convergence/runs", {
+        method: "POST",
+        body: JSON.stringify({ source_debate_id: sourceDebateId }),
+      }) as Promise<{ run_id: string; commons_log_id: string }>;
+    },
+
+    async getRun(runId: string): Promise<{
+      run_id: string;
+      source_debate_id: string;
+      agent_a_id: string;
+      agent_b_id: string;
+      pa_agent_id: string;
+      status: string;
+    }> {
+      return apiFetch(`/api/v1/convergence/runs/${runId}`) as Promise<{
+        run_id: string;
+        source_debate_id: string;
+        agent_a_id: string;
+        agent_b_id: string;
+        pa_agent_id: string;
+        status: string;
+      }>;
+    },
+
+    async acceptOwnerB(runId: string): Promise<{ ok: boolean }> {
+      return apiFetch(`/api/v1/convergence/runs/${runId}/owner_b_accept`, {
+        method: "POST",
+      }) as Promise<{ ok: boolean }>;
+    },
+
+    async appendCommonsLog(
+      cid: string,
+      eventType: string,
+      payload: Record<string, unknown>,
+    ): Promise<{ seq: number }> {
+      return apiFetch(`/api/v1/commons-logs/${cid}/append`, {
+        method: "POST",
+        body: JSON.stringify({ event_type: eventType, payload }),
+      }) as Promise<{ seq: number }>;
+    },
+
+    async acceptCruxDecision(
+      runId: string,
+      cruxId: string,
+      body: CruxDecisionRequest,
+    ): Promise<CruxDecisionResponse> {
+      return apiFetch(`/api/v1/convergence/runs/${runId}/cruxes/${cruxId}/accept`, {
+        method: "POST",
+        body: JSON.stringify(body),
+      }) as Promise<CruxDecisionResponse>;
+    },
+
+    async rejectCruxDecision(
+      runId: string,
+      cruxId: string,
+      body: CruxDecisionRequest,
+    ): Promise<CruxDecisionResponse> {
+      return apiFetch(`/api/v1/convergence/runs/${runId}/cruxes/${cruxId}/reject`, {
+        method: "POST",
+        body: JSON.stringify(body),
+      }) as Promise<CruxDecisionResponse>;
+    },
+
+    async attestCruxDecision(
+      runId: string,
+      cruxId: string,
+      body: CruxDecisionRequest,
+    ): Promise<CruxDecisionResponse> {
+      return apiFetch(`/api/v1/convergence/runs/${runId}/cruxes/${cruxId}/attest`, {
+        method: "POST",
+        body: JSON.stringify(body),
+      }) as Promise<CruxDecisionResponse>;
+    },
+  };
+}

package/src/converge/hash.ts

@@ -0,0 +1,35 @@
+import { createHash } from "node:crypto";
+
+// Encode a string as a JSON string literal with non-ASCII chars escaped as \uXXXX
+// to match Python json.dumps(ensure_ascii=True) output.
+function encodeString(s: string): string {
+  let out = '"';
+  for (let i = 0; i < s.length; i++) {
+    const cp = s.charCodeAt(i);
+    if (cp === 0x22) out += '\\"';
+    else if (cp === 0x5c) out += "\\\\";
+    else if (cp === 0x08) out += "\\b";
+    else if (cp === 0x09) out += "\\t";
+    else if (cp === 0x0a) out += "\\n";
+    else if (cp === 0x0c) out += "\\f";
+    else if (cp === 0x0d) out += "\\r";
+    else if (cp < 0x20 || cp > 0x7e) out += `\\u${cp.toString(16).padStart(4, "0")}`;
+    else out += s[i];
+  }
+  return out + '"';
+}
+
+export function canonicalize(value: unknown): string {
+  if (value === null) return "null";
+  if (typeof value === "string") return encodeString(value);
+  if (typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return "[" + value.map(canonicalize).join(",") + "]";
+  const keys = Object.keys(value as Record<string, unknown>).sort();
+  return "{" + keys.map((k) => encodeString(k) + ":" + canonicalize((value as any)[k])).join(",") + "}";
+}
+
+export function sha256OfCanonicalJson(value: unknown): string {
+  const h = createHash("sha256");
+  h.update(canonicalize(value));
+  return "sha256:" + h.digest("hex");
+}

package/src/converge/lock.ts

@@ -0,0 +1,30 @@
+import { closeSync, openSync, unlinkSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { LinkedClawError } from "../errors.js";
+
+const LOCK_FILENAME = ".lock";
+
+export function acquireLock(stagingDir: string): () => void {
+  const path = join(stagingDir, LOCK_FILENAME);
+  let fd: number;
+  try {
+    fd = openSync(path, "wx");
+  } catch (e: any) {
+    if (e.code === "EEXIST") {
+      throw new LinkedClawError(
+        "lock_held",
+        `Lock held at ${path}. If no other run/accept is in progress, delete ${path} to recover.`,
+      );
+    }
+    throw e;
+  }
+  writeSync(fd, JSON.stringify({ pid: process.pid }));
+  closeSync(fd);
+  return () => {
+    try {
+      unlinkSync(path);
+    } catch {
+      // ignore
+    }
+  };
+}

package/src/converge/staging.ts

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { load as yamlLoad, dump as yamlDump } from "js-yaml";
+
+export interface StagingFrontmatter {
+  debate_id: string;
+  run_id: string;
+  crux_id: string;
+  sub_debate_chain: string[];
+  latest_sub_debate_id: string | null;
+  source_crux_map_hash: string;
+  generation_id: string;
+  generated_at: string;
+  pa_body_hash: string;
+  outcome: "converged" | "partial_overlap" | "needs_input" | "irreconcilable" | "already_aligned";
+  bilateral_mandate_intact: boolean;
+  citations_a: Array<Record<string, unknown>>;
+  citations_b: Array<Record<string, unknown>>;
+  mod_progress_summary: Record<string, unknown>;
+  attested_by_user: boolean;
+  provenance?: Record<string, unknown>;
+}
+
+export interface StagingDoc {
+  frontmatter: StagingFrontmatter;
+  userResponse: string;
+  body: string;
+}
+
+export function stagingPathFor(stagingDir: string, cruxId: string): string {
+  return join(stagingDir, `${cruxId}.md`);
+}
+
+export function listCruxFiles(stagingDir: string): string[] {
+  if (!existsSync(stagingDir)) return [];
+  return readdirSync(stagingDir).filter(
+    (f) => f.endsWith(".md") && !f.startsWith("."),
+  );
+}
+
+export function parseStaging(text: string): StagingDoc {
+  if (!text.startsWith("---\n")) {
+    throw new Error("Missing YAML frontmatter: document must start with ---\\n");
+  }
+  const endIdx = text.indexOf("\n---\n", 4);
+  if (endIdx === -1) {
+    throw new Error("Malformed frontmatter: no closing ---");
+  }
+  const yamlText = text.slice(4, endIdx);
+  const body = text.slice(endIdx + 5);
+  const raw = yamlLoad(yamlText) as Record<string, unknown>;
+  if (!raw || typeof raw !== "object") {
+    throw new Error("Frontmatter parsed to non-object");
+  }
+  const userResponse = typeof raw._user_response === "string" ? raw._user_response : "";
+  delete raw._user_response;
+  return {
+    frontmatter: raw as unknown as StagingFrontmatter,
+    userResponse,
+    body,
+  };
+}
+
+export function dumpStaging(doc: StagingDoc): string {
+  const fmRaw: Record<string, unknown> = { ...doc.frontmatter };
+  fmRaw._user_response = doc.userResponse ?? "";
+  const yamlText = yamlDump(fmRaw, { lineWidth: -1, sortKeys: false });
+  return `---\n${yamlText}---\n${doc.body}`;
+}
+
+export function readStaging(path: string): StagingDoc {
+  return parseStaging(readFileSync(path, "utf8"));
+}
+
+export function writeStaging(path: string, doc: StagingDoc): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, dumpStaging(doc), "utf8");
+}
+
+export function computePaBodyHash(body: string): string {
+  return "sha256:" + createHash("sha256").update(Buffer.from(body, "utf8")).digest("hex");
+}