@linkedclaw/cli 0.1.2 → 0.1.5

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");
+}

package/src/converge/types.ts

@@ -0,0 +1,91 @@
+export interface RunMeta {
+  run_id: string;
+  source_debate_id: string;
+  pa_agent_id: string;
+  target_corpus: string;
+  owner_role: "a" | "b";
+}
+
+export interface RunWorkspace {
+  runId: string;
+  sourceDebateId: string;
+  paAgentId: string;
+  targetCorpus: string;
+  stagingDir: string;
+}
+
+export interface DebateRecord {
+  debate_id: string;
+  agent_a_id: string;
+  agent_b_id: string;
+  commons_log_id: string;
+  counterparty_user_id: string | null;
+  status: string;
+  topic?: string;
+}
+
+export interface CommonsLogEvent {
+  seq: number;
+  event_type: string;
+  payload: Record<string, unknown>;
+  appended_at: string;
+  signed_by: string;
+  signature_hash?: string;
+}
+
+export interface AgentListing {
+  agent_id: string;
+  slug: string;
+  capabilities: string[];
+}
+
+export interface MandateRecord {
+  mandate_id: string;
+  principal_agent_id: string;
+  delegate_agent_id: string;
+  scope: string[];
+  expires_at: string | null;
+  revoked_at?: string | null;
+}
+
+export interface RunStateSummary {
+  run_id: string;
+  source_debate_id: string;
+  started_at: string | null;
+  owner_b_accepted: boolean;
+  cruxes: Array<{
+    crux_id: string;
+    latest_sub_debate_id: string | null;
+    sub_debate_chain: string[];
+    outcome: string | null;
+    bilateral_mandate_intact: boolean | null;
+  }>;
+  terminal_emitted: boolean;
+}
+
+export type ConvergenceDecisionAction = "accept" | "reject" | "attest";
+
+export type ConvergenceAttestation =
+  | "bilateral_convergence"
+  | "user_attested_with_network_context"
+  | "user_attested_no_dialog";
+
+export interface CruxDecisionRequest {
+  convergence_map_generation_id: string;
+  source_crux_map_hash: string;
+  latest_sub_debate_id: string | null;
+  terminal_outcome: "converged" | "partial_overlap" | "needs_input" | "irreconcilable" | "already_aligned";
+  bilateral_mandate_intact: boolean;
+  attestation: ConvergenceAttestation;
+  synthesis_edited: boolean;
+  pa_body_hash: string;
+  accepted_body_hash: string;
+  synthesis_text: string;
+  citations_a: Array<Record<string, unknown>>;
+  citations_b: Array<Record<string, unknown>>;
+  user_message?: string | null;
+}
+
+export interface CruxDecisionResponse {
+  event_id: string;
+}

package/src/converge/workspace.ts

@@ -0,0 +1,92 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { load as yamlLoad, dump as yamlDump } from "js-yaml";
+import { LinkedClawError } from "../errors.js";
+import type { RunMeta, RunWorkspace } from "./types.js";
+
+export interface ResolveOpts {
+  runId?: string;
+  stagingDir?: string;
+  targetCorpus?: string;
+  cwd?: string;
+}
+
+const META_FILENAME = ".run-meta.yaml";
+
+export function readRunMeta(stagingDir: string): RunMeta | null {
+  const metaPath = join(stagingDir, META_FILENAME);
+  if (!existsSync(metaPath)) return null;
+  return yamlLoad(readFileSync(metaPath, "utf8")) as RunMeta;
+}
+
+export function writeRunMeta(stagingDir: string, meta: RunMeta): void {
+  mkdirSync(stagingDir, { recursive: true });
+  writeFileSync(join(stagingDir, META_FILENAME), yamlDump(meta), "utf8");
+}
+
+function searchUpward(startDir: string, maxLevels = 5): string | null {
+  let dir = startDir;
+  for (let i = 0; i < maxLevels; i++) {
+    if (existsSync(join(dir, META_FILENAME))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break; // filesystem root
+    dir = parent;
+  }
+  return null;
+}
+
+export async function resolveWorkspace(opts: ResolveOpts): Promise<RunWorkspace> {
+  const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd();
+
+  let stagingDir: string | undefined;
+  let meta: RunMeta | null = null;
+
+  if (opts.stagingDir) {
+    stagingDir = isAbsolute(opts.stagingDir) ? opts.stagingDir : resolve(cwd, opts.stagingDir);
+    meta = readRunMeta(stagingDir);
+    if (!meta) {
+      throw new LinkedClawError(
+        "meta_not_found",
+        `No ${META_FILENAME} found in --staging-dir: ${stagingDir}`,
+      );
+    }
+  } else {
+    const found = searchUpward(cwd);
+    if (found) {
+      stagingDir = found;
+      meta = readRunMeta(found)!;
+    }
+  }
+
+  if (!meta) {
+    if (opts.runId) {
+      throw new LinkedClawError(
+        "meta_not_found",
+        `--run-id given but no ${META_FILENAME} found (searched upward from ${cwd}). Provide --staging-dir to locate the run workspace.`,
+      );
+    }
+    throw new LinkedClawError(
+      "meta_not_found",
+      `No ${META_FILENAME} found (searched upward from ${cwd}). Run 'lc converge run <debate_id>' first.`,
+    );
+  }
+
+  if (opts.runId && opts.runId !== meta.run_id) {
+    throw new LinkedClawError(
+      "run_id_mismatch",
+      `--run-id ${opts.runId} does not match run_id ${meta.run_id} in ${META_FILENAME}`,
+    );
+  }
+
+  const targetCorpus = isAbsolute(meta.target_corpus)
+    ? meta.target_corpus
+    : resolve(stagingDir!, meta.target_corpus);
+
+  return {
+    runId: meta.run_id,
+    sourceDebateId: meta.source_debate_id,
+    paAgentId: meta.pa_agent_id,
+    targetCorpus,
+    stagingDir: stagingDir!,
+  };
+}

package/src/errors.ts

@@ -0,0 +1,41 @@
+export class LinkedClawError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "LinkedClawError";
+    this.code = code;
+  }
+}
+
+export class NetworkError extends LinkedClawError {
+  constructor(message: string, cause?: unknown) {
+    super("network_error", message);
+    this.name = "NetworkError";
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+export class ApiError extends LinkedClawError {
+  constructor(
+    readonly status: number,
+    readonly detail: string,
+    readonly path: string,
+  ) {
+    super(`api_error_${status}`, `[${status}] ${path}: ${detail}`);
+    this.name = "ApiError";
+  }
+}
+
+export class ConfigError extends LinkedClawError {
+  constructor(message: string) {
+    super("config_error", message);
+    this.name = "ConfigError";
+  }
+}
+
+export class HandlerError extends LinkedClawError {
+  constructor(code: string, message: string) {
+    super(code, message);
+    this.name = "HandlerError";
+  }
+}