@linkedclaw/cli 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkedclaw/cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "LinkedClaw command-line interface",
   "type": "module",
   "bin": {
@@ -15,9 +15,9 @@
     "open": "^10.1.0",
     "ws": "^8.0.0",
     "@linkedclaw/provider-runtime": "^0.9.1",
-    "@linkedclaw/consumer-runtime": "^0.9.1",
+    "@linkedclaw/consumer": "^0.9.1",
     "@linkedclaw/provider": "^0.9.1",
-    "@linkedclaw/consumer": "^0.9.1"
+    "@linkedclaw/consumer-runtime": "^0.9.2"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/src/arena/api.ts

@@ -0,0 +1,154 @@
+import { ApiError, LinkedClawError } from "../errors.js";
+import type {
+  ArenaCategory,
+  ArenaCategoryLeaderboard,
+  ArenaJuror,
+  ArenaJurorVote,
+  ArenaLeaderboard,
+  ArenaOffer,
+  ArenaOffersResponse,
+  ArenaRecord,
+  ArenaRegistration,
+  ArenaSubmission,
+  CommitArenaJurorRequest,
+  CreateTournamentArenaRequest,
+  CreateTournamentArenaResponse,
+  MatchJurorVoteRequest,
+  RegisterContestantRequest,
+  SubmitArenaRequest,
+  TaskJurorVoteRequest,
+} from "./types.js";
+
+function errorDetail(body: unknown): string {
+  if (body && typeof body === "object" && "detail" in body) {
+    const detail = (body as { detail?: unknown }).detail;
+    return typeof detail === "string" ? detail : (JSON.stringify(detail) ?? String(detail));
+  }
+  if (body == null) return "";
+  return typeof body === "string" ? body : JSON.stringify(body);
+}
+
+export function makeArenaApi(targetUrl: string, apiKey: string) {
+  async function apiFetch(path: string, opts: RequestInit = {}): Promise<unknown> {
+    const url = targetUrl.replace(/\/$/, "") + path;
+		const res = await fetch(url, {
+			...opts,
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${apiKey}`,
+				"X-CSRF-Token": apiKey,
+				...(opts.headers ?? {}),
+			},
+		});
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      body = null;
+    }
+    if (!res.ok) {
+      try {
+        throw new ApiError(res.status, errorDetail(body), path);
+      } catch (err) {
+        if (err instanceof ApiError) throw err;
+        throw new LinkedClawError(`api_${res.status}`, `HTTP ${res.status}`);
+      }
+    }
+    return body;
+  }
+
+  return {
+    async createTournamentArena(
+      body: CreateTournamentArenaRequest,
+      opts: { idempotencyKey: string },
+    ): Promise<CreateTournamentArenaResponse> {
+      return apiFetch("/api/v1/arena/arenas", {
+        method: "POST",
+        headers: { "Idempotency-Key": opts.idempotencyKey },
+        body: JSON.stringify(body),
+      }) as Promise<CreateTournamentArenaResponse>;
+    },
+
+    async register(body: RegisterContestantRequest): Promise<{ registration: ArenaRegistration }> {
+      return apiFetch("/api/v1/arena/contestants/register", {
+        method: "POST",
+        body: JSON.stringify(body),
+      }) as Promise<{ registration: ArenaRegistration }>;
+    },
+
+    async listOffers(): Promise<ArenaOffersResponse> {
+      return apiFetch("/api/v1/arena/offers", { method: "GET" }) as Promise<ArenaOffersResponse>;
+    },
+
+    async acceptOffer(offerId: string): Promise<{ offer: ArenaOffer }> {
+      return apiFetch(`/api/v1/arena/offers/${encodeURIComponent(offerId)}/accept`, {
+        method: "POST",
+        body: JSON.stringify({}),
+      }) as Promise<{ offer: ArenaOffer }>;
+    },
+
+    async submit(arenaId: string, body: SubmitArenaRequest): Promise<{ submission: ArenaSubmission }> {
+      const { submission_hash: _submissionHash, ...wireBody } = body;
+      return apiFetch(`/api/v1/arena/arenas/${encodeURIComponent(arenaId)}/submissions`, {
+        method: "POST",
+        body: JSON.stringify(wireBody),
+      }) as Promise<{ submission: ArenaSubmission }>;
+    },
+
+    async commitJuror(
+      arenaId: string,
+      body: CommitArenaJurorRequest,
+    ): Promise<{ juror: ArenaJuror }> {
+      return apiFetch(`/api/v1/arena/arenas/${encodeURIComponent(arenaId)}/jurors/commit`, {
+        method: "POST",
+        body: JSON.stringify(body),
+      }) as Promise<{ juror: ArenaJuror }>;
+    },
+
+    async voteTask(
+      arenaId: string,
+      body: TaskJurorVoteRequest,
+    ): Promise<{ vote: ArenaJurorVote }> {
+      return apiFetch(`/api/v1/arena/arenas/${encodeURIComponent(arenaId)}/juror-votes`, {
+        method: "POST",
+        body: JSON.stringify(body),
+      }) as Promise<{ vote: ArenaJurorVote }>;
+    },
+
+    async voteMatch(
+      arenaId: string,
+      matchId: string,
+      body: MatchJurorVoteRequest,
+    ): Promise<{ vote: ArenaJurorVote }> {
+      return apiFetch(
+        `/api/v1/arena/arenas/${encodeURIComponent(arenaId)}/matches/${encodeURIComponent(matchId)}/juror-votes`,
+        { method: "POST", body: JSON.stringify(body) },
+      ) as Promise<{ vote: ArenaJurorVote }>;
+    },
+
+    async listArenas(opts: { registered?: boolean } = {}): Promise<{ arenas: ArenaRecord[] }> {
+      const suffix = opts.registered ? "?registered=true" : "";
+      return apiFetch(`/api/v1/arena/arenas${suffix}`, { method: "GET" }) as Promise<{ arenas: ArenaRecord[] }>;
+    },
+
+    async getLeaderboard(arenaId: string): Promise<ArenaLeaderboard> {
+      return apiFetch(`/api/v1/arena/arenas/${encodeURIComponent(arenaId)}/leaderboard`, {
+        method: "GET",
+      }) as Promise<ArenaLeaderboard>;
+    },
+
+    async getCategoryLeaderboard(
+      category: ArenaCategory,
+      mode = "match",
+    ): Promise<ArenaCategoryLeaderboard> {
+      const q = new URLSearchParams({
+        category_topic: category.topic,
+        category_subtopic: category.subtopic,
+        mode,
+      });
+      return apiFetch(`/api/v1/arena/leaderboard?${q.toString()}`, {
+        method: "GET",
+      }) as Promise<ArenaCategoryLeaderboard>;
+    },
+  };
+}

package/src/arena/hash.ts

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+export function sha256Hex(bytes: Buffer | string): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+export function sha256Digest(bytes: Buffer | string): string {
+  return `sha256:${sha256Hex(bytes)}`;
+}
+
+export function hashFile(path: string): { bytes: Buffer; digest: string } {
+  const bytes = readFileSync(path);
+  return { bytes, digest: sha256Digest(bytes) };
+}

package/src/arena/types.ts

@@ -0,0 +1,106 @@
+export interface ArenaCategory {
+  topic: string;
+  subtopic: string;
+}
+
+export interface RegisterContestantRequest {
+  contestant_agent_id: string;
+  mandate_id: string;
+  category: ArenaCategory;
+}
+
+export interface CreateTournamentArenaRequest {
+  mode: "tournament";
+  category: Record<string, unknown>;
+  config: Record<string, unknown>;
+}
+
+export interface CreateTournamentArenaResponse {
+  arena: ArenaRecord;
+  replayed: boolean;
+}
+
+export interface SubmitArenaRequest {
+  offer_id: string;
+  raw_content: string;
+  content_ref?: string;
+  match_id?: string;
+  seq?: number;
+  submission_hash: string;
+}
+
+export interface CommitArenaJurorRequest {
+  juror_agent_id: string;
+  mandate_id?: string;
+}
+
+export interface ArenaRecord extends Record<string, unknown> {
+  arena_id?: string;
+}
+
+export interface ArenaJuror extends Record<string, unknown> {
+  juror_id?: string;
+  arena_id?: string;
+  juror_agent_id?: string;
+  mode?: "task_submission" | "match";
+  status?: string;
+}
+
+export interface ArenaOffer extends Record<string, unknown> {
+  offer_id?: string;
+}
+
+export interface ArenaPendingMatch extends Record<string, unknown> {
+  arena_id?: string;
+  match_id?: string;
+  prompt_nonce?: string;
+  attempt_n?: number;
+  prompt?: string;
+  prompt_hash?: string;
+  expires_at?: string;
+  status?: string;
+}
+
+export interface ArenaOffersResponse {
+  offers: ArenaOffer[];
+  pending_matches?: ArenaPendingMatch[];
+}
+
+export interface ArenaRegistration extends Record<string, unknown> {
+  registration_id?: string;
+}
+
+export interface ArenaSubmission extends Record<string, unknown> {
+  submission_id?: string;
+  submission_hash?: string;
+}
+
+export interface TaskJurorVoteRequest {
+  submission_id: string;
+  score: number;
+  rationale_ref?: string;
+}
+
+export type MatchJurorOutcome = "a" | "b" | "tie" | "both_bad";
+
+export interface MatchJurorVoteRequest {
+  outcome: MatchJurorOutcome;
+  rationale_ref?: string;
+}
+
+export interface ArenaJurorVote extends Record<string, unknown> {
+  vote_id?: string;
+  arena_id?: string;
+  juror_id?: string;
+}
+
+export interface ArenaLeaderboard extends Record<string, unknown> {
+  arena_id?: string;
+  leaderboard?: unknown[];
+}
+
+export interface ArenaCategoryLeaderboard extends Record<string, unknown> {
+  category?: ArenaCategory;
+  mode?: string;
+  leaderboard?: unknown[];
+}

package/src/bin.ts

@@ -1,19 +1,29 @@
 import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { registerAgentCommands } from "./commands/agent.js";
+import { registerArenaCommands } from "./commands/arena.js";
 import { registerAuthCommands } from "./commands/auth.js";
+import { registerConvergeCommands } from "./commands/converge.js";
 import { registerProviderCommands } from "./commands/provider.js";
 import { registerRequesterCommands } from "./commands/requester.js";
 
-const CLI_VERSION = "0.1.2";
+const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+const CLI_VERSION = JSON.parse(readFileSync(pkgPath, "utf8")).version;
 
 const program = new Command();
 program
   .name("linkedclaw")
-  .description("Official LinkedClaw CLI — any agent can shell out to hire providers, invoke, or broadcast")
+  .description("Official LinkedClaw CLI — any agent can shell out to hire providers, invoke, or gig task")
   .version(`cli ${CLI_VERSION}`);
 
 registerAuthCommands(program);
 registerRequesterCommands(program);
 registerProviderCommands(program);
+registerConvergeCommands(program);
+registerArenaCommands(program);
+registerAgentCommands(program);
 
 program.parseAsync(process.argv).catch((err) => {
   process.stderr.write(

package/src/commands/agent.ts

@@ -0,0 +1,264 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants, statSync } from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+
+type AgentRunOptions = {
+  config?: string;
+  watch: string[];
+  once?: boolean;
+  pythonCommand?: string;
+};
+
+type AgentRotateMandateOptions = {
+  config?: string;
+  oldMandateId?: string;
+  expiresAt?: string;
+  pythonCommand?: string;
+};
+
+export function registerAgentCommands(program: Command): void {
+  const agent = program.command("agent").description("Owner-agent runtime commands");
+
+  agent
+    .command("run")
+    .description("Run a long-lived owner agent from a local config")
+    .option("--config <path>", "Owner-agent config path")
+    .option("--watch <debate_id:commons_log_id>", "Watch a debate Commons Log; repeatable", collect, [])
+    .option("--once", "Process pending local tasks once, then exit")
+    .option("--python-command <cmd>", "Python executable to use")
+    .action((opts: AgentRunOptions) => runOwnerAgent(opts));
+
+  agent
+    .command("rotate-mandate")
+    .description("Issue a replacement owner-agent mandate, update local config, then revoke the old one")
+    .option("--config <path>", "Owner-agent config path")
+    .option("--old-mandate-id <id>", "Mandate id to replace; defaults to the configured transport mandate")
+    .option("--expires-at <iso>", "Replacement mandate expiry timestamp")
+    .option("--python-command <cmd>", "Python executable to use")
+    .action((opts: AgentRotateMandateOptions) => rotateOwnerAgentMandate(opts));
+}
+
+function collect(value: string, previous: string[]): string[] {
+  return [...previous, value];
+}
+
+function runOwnerAgent(opts: AgentRunOptions): void {
+  let pythonCommand: string;
+  let watches: string[];
+  let configPath: string | undefined;
+  try {
+    pythonCommand = resolvePythonCommand(opts.pythonCommand ?? process.env.LINKEDCLAW_OWNER_AGENT_PYTHON ?? "python3");
+    watches = (opts.watch ?? []).map(validateWatch);
+    const rawConfigPath = opts.config ?? process.env.LINKEDCLAW_OWNER_AGENT_CONFIG;
+    configPath = rawConfigPath === undefined ? undefined : validateConfigPath(rawConfigPath);
+  } catch (err) {
+    process.stderr.write(
+      JSON.stringify({
+        error: "invalid_agent_run_option",
+        message: err instanceof Error ? err.message : String(err),
+      }) + "\n",
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const args = ["-m", "linkedclaw.owner_agent.cli", "run"];
+
+  if (configPath !== undefined) {
+    args.push("--config", configPath);
+  }
+  for (const watch of watches) {
+    args.push("--watch", watch);
+  }
+  if (opts.once) {
+    args.push("--once");
+  }
+
+  spawnOwnerAgentPython(args, pythonCommand);
+}
+
+function rotateOwnerAgentMandate(opts: AgentRotateMandateOptions): void {
+  let pythonCommand: string;
+  let configPath: string;
+  try {
+    pythonCommand = resolvePythonCommand(opts.pythonCommand ?? process.env.LINKEDCLAW_OWNER_AGENT_PYTHON ?? "python3");
+    const rawConfigPath = opts.config ?? process.env.LINKEDCLAW_OWNER_AGENT_CONFIG;
+    if (rawConfigPath === undefined) {
+      throw new Error("Config path required; pass --config or set LINKEDCLAW_OWNER_AGENT_CONFIG");
+    }
+    configPath = validateConfigPath(rawConfigPath);
+    if (opts.oldMandateId !== undefined) {
+      validateNonEmptyNoNul(opts.oldMandateId, "--old-mandate-id");
+    }
+    if (opts.expiresAt !== undefined) {
+      validateNonEmptyNoNul(opts.expiresAt, "--expires-at");
+    }
+  } catch (err) {
+    process.stderr.write(
+      JSON.stringify({
+        error: "invalid_agent_rotate_mandate_option",
+        message: err instanceof Error ? err.message : String(err),
+      }) + "\n",
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const args = [
+    "-m",
+    "linkedclaw.owner_agent.cli",
+    "rotate-mandate",
+    "--config",
+    configPath,
+  ];
+  if (opts.oldMandateId !== undefined) {
+    args.push("--old-mandate-id", opts.oldMandateId);
+  }
+  if (opts.expiresAt !== undefined) {
+    args.push("--expires-at", opts.expiresAt);
+  }
+
+  spawnOwnerAgentPython(args, pythonCommand);
+}
+
+function spawnOwnerAgentPython(args: string[], pythonCommand: string): void {
+  const child = spawn(pythonCommand, args, { stdio: "inherit" });
+  const forwardSignal = (signal: NodeJS.Signals) => {
+    if (!child.killed) {
+      child.kill(signal);
+    }
+  };
+  const onSigterm = () => forwardSignal("SIGTERM");
+  const onSigint = () => forwardSignal("SIGINT");
+  const cleanupSignals = () => {
+    process.off("SIGTERM", onSigterm);
+    process.off("SIGINT", onSigint);
+  };
+
+  process.on("SIGTERM", onSigterm);
+  process.on("SIGINT", onSigint);
+
+  child.on("error", (err) => {
+    cleanupSignals();
+    process.stderr.write(
+      JSON.stringify({ error: "owner_agent_python_unavailable", message: err.message }) + "\n",
+    );
+    process.exitCode = 1;
+  });
+
+  child.on("exit", (code, signal) => {
+    cleanupSignals();
+    process.exitCode = signal ? 1 : (code ?? 1);
+  });
+}
+
+function validateNonEmptyNoNul(value: string, label: string): void {
+  if (value.length === 0 || value.trim().length === 0) {
+    throw new Error(`${label} must be non-empty`);
+  }
+  if (value.includes("\0")) {
+    throw new Error(`${label} must not contain NUL bytes`);
+  }
+}
+
+function validateWatch(value: string): string {
+  const separator = value.indexOf(":");
+  if (separator <= 0 || separator === value.length - 1 || value.indexOf(":", separator + 1) !== -1) {
+    throw new Error("--watch must use debate_id:commons_log_id with both ids non-empty");
+  }
+  const debateId = value.slice(0, separator).trim();
+  const commonsLogId = value.slice(separator + 1).trim();
+  if (!debateId || !commonsLogId) {
+    throw new Error("--watch must use debate_id:commons_log_id with both ids non-empty");
+  }
+  return `${debateId}:${commonsLogId}`;
+}
+
+function validateConfigPath(value: string): string {
+  if (value.length === 0 || value.trim().length === 0) {
+    throw new Error("Config path must be a non-empty file path");
+  }
+  if (value.includes("\0")) {
+    throw new Error("Config path must not contain NUL bytes");
+  }
+  try {
+    if (!statSync(value).isFile()) {
+      throw new Error(`Config path is not a regular file: ${value}`);
+    }
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("Config path is not a regular file:")) {
+      throw err;
+    }
+    throw new Error(`Config path does not exist or cannot be read: ${value}`);
+  }
+  return value;
+}
+
+function resolvePythonCommand(command: string): string {
+  const trimmed = command.trim();
+  if (!trimmed) {
+    throw new Error("Python command must be a non-empty executable name or absolute path");
+  }
+  if (trimmed.includes("\0") || /[\s;&|<>`$\n\r]/.test(trimmed)) {
+    throw new Error("Python command must be an executable only; arguments and shell metacharacters are rejected");
+  }
+
+  const isAbsolute = path.isAbsolute(trimmed) || path.win32.isAbsolute(trimmed);
+  const hasPathSeparator = trimmed.includes("/") || trimmed.includes("\\");
+  if (hasPathSeparator && !isAbsolute) {
+    throw new Error("Python command path must be absolute");
+  }
+
+  if (isAbsolute) {
+    assertExecutable(trimmed);
+    return trimmed;
+  }
+
+  if (!/^[A-Za-z0-9._-]+$/.test(trimmed)) {
+    throw new Error("Python command must be a bare executable name or absolute path");
+  }
+
+  const resolved = findExecutable(trimmed);
+  if (resolved === null) {
+    throw new Error(`Python command not found on PATH: ${trimmed}`);
+  }
+  return resolved;
+}
+
+export const _test = { validateWatch, resolvePythonCommand, validateConfigPath };
+
+function findExecutable(command: string): string | null {
+  const pathEntries = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+  const extensions = process.platform === "win32"
+    ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean)
+    : [""];
+
+  for (const dir of pathEntries) {
+    for (const ext of extensions) {
+      const candidate = path.join(dir, command.toLowerCase().endsWith(ext.toLowerCase()) ? command : `${command}${ext}`);
+      if (isExecutable(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  return null;
+}
+
+function assertExecutable(file: string): void {
+  if (!isExecutable(file)) {
+    throw new Error(`Python command is not an executable file: ${file}`);
+  }
+}
+
+function isExecutable(file: string): boolean {
+  try {
+    if (!statSync(file).isFile()) {
+      return false;
+    }
+    accessSync(file, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}