@linkedclaw/cli 0.1.2 → 0.1.5

package/src/handlers/subprocess.ts

@@ -0,0 +1,185 @@
+/**
+ * SubprocessHandler bridges the ProviderHandler interface to
+ * a user child process via stdin/stdout JSON-lines. Each inbound event gets
+ * an `id`; handler must respond with exactly one `{id, result}` or `{id, error}`.
+ *
+ * Wire protocol (one JSON object per line):
+ *   CLI → child stdin:   {id, type, ...event fields}
+ *   child stdout → CLI:  {id, result: {...}} | {id, error: {code, message}}
+ *
+ * Anything the child writes to stderr is passed through for operator visibility.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import type { Readable, Writable } from "node:stream";
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline";
+import type {
+  GigTaskExecuteEvent,
+  GigTaskExecuteResult,
+  GigTaskOfferDecision,
+  GigTaskOfferEvent,
+  InvokeEvent,
+  InvokeHandlerResult,
+  ProviderHandler,
+  SessionAcceptDecision,
+  SessionCreateEvent,
+  SessionEndInboundEvent,
+  SessionMessageEvent,
+  SessionReply,
+} from "@linkedclaw/provider-runtime";
+
+interface Pending {
+  resolve: (value: unknown) => void;
+  reject: (err: Error) => void;
+  timer?: ReturnType<typeof setTimeout>;
+}
+
+export interface SubprocessHandlerOptions {
+  /** Shell-style command. Uses /bin/sh -c on posix, cmd /c on windows. */
+  cmd: string;
+  /** Working directory for the child. */
+  cwd?: string;
+  /** Extra env for the child. */
+  env?: NodeJS.ProcessEnv;
+  /** Per-event default timeout (ms). Core already enforces its own timeouts. */
+  requestTimeoutMs?: number;
+}
+
+export class SubprocessHandler implements ProviderHandler {
+  private readonly child: ChildProcess;
+  private readonly stdin: Writable;
+  private readonly pending = new Map<string, Pending>();
+  private readonly requestTimeoutMs: number;
+
+  constructor(opts: SubprocessHandlerOptions) {
+    this.requestTimeoutMs = opts.requestTimeoutMs ?? 600_000;
+    const shell = process.platform === "win32" ? "cmd.exe" : "/bin/sh";
+    const shellArgs = process.platform === "win32" ? ["/c", opts.cmd] : ["-c", opts.cmd];
+    this.child = spawn(shell, shellArgs, {
+      stdio: ["pipe", "pipe", "inherit"],
+      cwd: opts.cwd,
+      env: { ...process.env, ...opts.env },
+    });
+    if (!this.child.stdin || !this.child.stdout) {
+      throw new Error("subprocess handler: child stdin/stdout not available");
+    }
+    this.stdin = this.child.stdin;
+    const rl = createInterface({ input: this.child.stdout as Readable });
+    rl.on("line", (line) => this.handleLine(line));
+    this.child.on("exit", (code, signal) => this.handleExit(code, signal));
+  }
+
+  // ───── ProviderHandler impl ─────
+
+  async onSessionCreate(evt: SessionCreateEvent): Promise<SessionAcceptDecision> {
+    return this.request<SessionAcceptDecision>(evt);
+  }
+
+  async onSessionMessage(evt: SessionMessageEvent): Promise<SessionReply> {
+    const r = await this.request<unknown>(evt);
+    if (r === null || r === undefined) return null;
+    if (typeof r === "string") return r;
+    if (typeof r === "object") {
+      const obj = r as Record<string, unknown>;
+      if (typeof obj["content"] === "string") return obj["content"] as string;
+      if ("payload" in obj) return obj as { payload: unknown };
+    }
+    return null;
+  }
+
+  async onSessionEnd(evt: SessionEndInboundEvent): Promise<void> {
+    try {
+      await this.request<unknown>(evt);
+    } catch {
+      // session is ending anyway; ignore handler errors here
+    }
+  }
+
+  async onInvoke(evt: InvokeEvent): Promise<InvokeHandlerResult> {
+    return this.request<InvokeHandlerResult>(evt);
+  }
+
+  async onGigTaskOffer(evt: GigTaskOfferEvent): Promise<GigTaskOfferDecision> {
+    return this.request<GigTaskOfferDecision>(evt);
+  }
+
+  async onGigTaskExecute(evt: GigTaskExecuteEvent): Promise<GigTaskExecuteResult> {
+    return this.request<GigTaskExecuteResult>(evt);
+  }
+
+  // ───── shutdown ─────
+
+  async close(): Promise<void> {
+    if (this.child.exitCode !== null) return;
+    this.stdin.end();
+    try {
+      this.child.kill("SIGTERM");
+    } catch {
+      // already gone
+    }
+    for (const p of this.pending.values()) {
+      p.reject(new Error("handler_closed"));
+      if (p.timer) clearTimeout(p.timer);
+    }
+    this.pending.clear();
+  }
+
+  // ───── internals ─────
+
+  private request<T>(frame: { type: string } & object): Promise<T> {
+    const id = randomUUID();
+    const line = JSON.stringify({ id, ...frame }) + "\n";
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`handler_timeout: no response for ${frame.type} after ${this.requestTimeoutMs}ms`));
+      }, this.requestTimeoutMs);
+      if (typeof (timer as unknown as { unref?: () => void }).unref === "function") {
+        (timer as unknown as { unref: () => void }).unref();
+      }
+      this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer });
+      this.stdin.write(line, (err) => {
+        if (err) {
+          this.pending.delete(id);
+          clearTimeout(timer);
+          reject(err);
+        }
+      });
+    });
+  }
+
+  private handleLine(line: string): void {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let msg: unknown;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      process.stderr.write(`handler wrote non-JSON line: ${trimmed}\n`);
+      return;
+    }
+    if (typeof msg !== "object" || msg === null) return;
+    const m = msg as { id?: unknown; result?: unknown; error?: unknown };
+    if (typeof m.id !== "string") return;
+    const p = this.pending.get(m.id);
+    if (!p) return;
+    this.pending.delete(m.id);
+    if (p.timer) clearTimeout(p.timer);
+    if (m.error !== undefined) {
+      const err = m.error as { code?: string; message?: string };
+      p.reject(Object.assign(new Error(err.message ?? "handler_error"), { code: err.code }));
+    } else {
+      p.resolve(m.result);
+    }
+  }
+
+  private handleExit(code: number | null, signal: NodeJS.Signals | null): void {
+    const reason = signal ?? `exit ${code}`;
+    for (const p of this.pending.values()) {
+      p.reject(new Error(`handler_crashed (${reason})`));
+      if (p.timer) clearTimeout(p.timer);
+    }
+    this.pending.clear();
+  }
+}

package/src/output.ts

@@ -0,0 +1,57 @@
+import { ApiError, LinkedClawError, NetworkError } from "./errors.js";
+
+export interface PrintOptions {
+  human?: boolean;
+}
+
+export function printResult(value: unknown, opts: PrintOptions = {}): void {
+  if (opts.human) {
+    if (typeof value === "string") process.stdout.write(value + "\n");
+    else process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+    return;
+  }
+  process.stdout.write(JSON.stringify(value) + "\n");
+}
+
+export function printError(err: unknown): void {
+  const payload: Record<string, unknown> =
+    err instanceof ApiError
+      ? { error: err.code, status: err.status, path: err.path, detail: err.detail }
+      : err instanceof NetworkError
+        ? { error: err.code, message: err.message }
+        : err instanceof LinkedClawError
+          ? { error: err.code, message: err.message }
+          : { error: "internal_error", message: err instanceof Error ? err.message : String(err) };
+  process.stderr.write(JSON.stringify(payload) + "\n");
+}
+
+export async function runCommand(fn: () => Promise<unknown> | unknown, opts: PrintOptions = {}): Promise<void> {
+  try {
+    const out = await fn();
+    if (out !== undefined) printResult(out, opts);
+  } catch (err) {
+    printError(err);
+    process.exitCode = 1;
+  }
+}
+
+export async function readLine(prompt: string): Promise<string> {
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    return (await rl.question(prompt)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+export async function readStdin(): Promise<string> {
+  if (process.stdin.isTTY) {
+    process.stderr.write("reading from stdin — press Ctrl-D when done\n");
+  }
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}

package/src/types.ts

@@ -0,0 +1,90 @@
+// CLI-local request/response types. Only types consumed by commands are here.
+// Response/listing types are typed as Record<string,unknown> in the SDK methods;
+// these interfaces are used for request body construction and CLI flag parsing.
+
+export type EntityId = string;
+
+export type PricingModel =
+  | "free"
+  | "per_session"
+  | "per_message"
+  | "per_call"
+  | "per_task";
+
+export type VerifyMethod = "none" | "custom" | "output_schema";
+
+export interface CreateAgentRequest {
+  slug: string;
+  name: string;
+  description: string;
+  capabilities: string[];
+  pricing_model?: PricingModel;
+  price_credits?: number;
+  status?: "online" | "offline" | "disabled";
+  verify_method?: VerifyMethod;
+  verify_config?: Record<string, unknown>;
+  min_requester_reputation?: number;
+  min_sessions?: number;
+  require_payment?: boolean;
+  slot_fulfillment?: string[];
+  fork_policy?: string | null;
+}
+
+export type UpdateAgentRequest = Partial<Omit<CreateAgentRequest, "slug">>;
+
+export interface EndSessionRequest {
+  message_count?: number | null;
+  final_output?: string | null;
+}
+
+export interface InvokeRequest {
+  capability: string;
+  input: Record<string, unknown>;
+  max_credits?: number;
+  manifest_id?: EntityId;
+  manifest?: TaskManifest;
+  timeout_seconds?: number;
+  referred_by?: EntityId;
+}
+
+export interface TaskManifest {
+  intention: string;
+  [key: string]: unknown;
+}
+
+export interface CreateGigTaskRequest {
+  capability: string;
+  instruction: string;
+  target_providers: number;
+  credits_per_provider: number;
+  deadline?: string | null;
+  task_params?: Record<string, unknown>;
+  result_schema?: Record<string, unknown> | null;
+  acceptance_criteria?: Record<string, unknown> | null;
+  partition_type?: string;
+  payment_type?: string;
+  required_stake?: number;
+  referred_by?: EntityId;
+}
+
+export interface AcceptGigTaskRequest {
+  agent_id: EntityId;
+  slot_key?: string | null;
+}
+
+export interface GigTaskSubmitRequest {
+  result_data: string;
+  result_payload?: Record<string, unknown> | null;
+  proof?: Array<{ type: string; value: string; label?: string }> | null;
+}
+
+// Re-export provider-runtime types needed by commands
+export type {
+  ProviderHandler,
+  GigTaskOfferDecision,
+  GigTaskExecuteResult,
+  InvokeHandlerResult,
+  SessionAcceptDecision,
+  SessionReply,
+} from "@linkedclaw/provider-runtime";
+export type { MessageType } from "@linkedclaw/provider";

package/test/agent-help.test.ts

@@ -0,0 +1,207 @@
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from "vitest";
+import { spawnSync } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { chmodSync, existsSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+
+const spawnMock = vi.hoisted(() => vi.fn());
+
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>();
+  return { ...actual, spawn: spawnMock };
+});
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BIN = path.resolve(__dirname, "../dist/bin.js");
+const ORIGINAL_CONFIG_ENV = process.env.LINKEDCLAW_OWNER_AGENT_CONFIG;
+const ORIGINAL_EXIT_CODE = process.exitCode;
+
+type FakeChild = EventEmitter & {
+  killed: boolean;
+  kill: ReturnType<typeof vi.fn>;
+};
+
+let activeChild: FakeChild | undefined;
+
+beforeAll(() => {
+  if (!existsSync(BIN)) {
+    throw new Error(`bin not built — run 'pnpm --filter @linkedclaw/cli build' first (${BIN})`);
+  }
+});
+
+beforeEach(() => {
+  spawnMock.mockReset();
+  delete process.env.LINKEDCLAW_OWNER_AGENT_CONFIG;
+  activeChild = undefined;
+});
+
+afterEach(() => {
+  if (activeChild !== undefined) {
+    activeChild.emit("exit", 0, null);
+    activeChild = undefined;
+  }
+  if (ORIGINAL_CONFIG_ENV === undefined) {
+    delete process.env.LINKEDCLAW_OWNER_AGENT_CONFIG;
+  } else {
+    process.env.LINKEDCLAW_OWNER_AGENT_CONFIG = ORIGINAL_CONFIG_ENV;
+  }
+  process.exitCode = ORIGINAL_EXIT_CODE;
+});
+
+function run(args: string[]): { code: number | null; stdout: string; stderr: string } {
+  const r = spawnSync("node", [BIN, ...args], { encoding: "utf8" });
+  return { code: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+
+function makeFakeChild(): FakeChild {
+  const child = new EventEmitter() as FakeChild;
+  child.killed = false;
+  child.kill = vi.fn(() => true);
+  activeChild = child;
+  return child;
+}
+
+function makeFakePython(): string {
+  const dir = mkdtempSync(path.join(tmpdir(), "linkedclaw-agent-cli-"));
+  const fakePython = path.join(dir, "fake-python");
+  writeFileSync(fakePython, "#!/bin/sh\nexit 0\n", "utf8");
+  chmodSync(fakePython, 0o700);
+  return fakePython;
+}
+
+async function runHiddenAgent(args: string[]): Promise<FakeChild> {
+  const child = makeFakeChild();
+  spawnMock.mockReturnValueOnce(child);
+  const program = new Command();
+  program.exitOverride();
+  const { registerAgentCommands } = await import("../src/commands/agent.js");
+  registerAgentCommands(program);
+  await program.parseAsync(["node", "cli", "agent", "run", ...args]);
+  return child;
+}
+
+async function runHiddenRotate(args: string[]): Promise<FakeChild | undefined> {
+  const child = makeFakeChild();
+  spawnMock.mockReturnValueOnce(child);
+  const program = new Command();
+  program.exitOverride();
+  const { registerAgentCommands } = await import("../src/commands/agent.js");
+  registerAgentCommands(program);
+  await program.parseAsync(["node", "cli", "agent", "rotate-mandate", ...args]);
+  return process.exitCode === 1 ? undefined : child;
+}
+
+describe("agent command packaging", () => {
+  it("exposes the owner-agent run command in the npm CLI", () => {
+    const top = run(["--help"]);
+    expect(top.code).toBe(0);
+    expect(top.stdout).toContain("agent");
+
+    const agent = run(["agent", "--help"]);
+    expect(agent.code).toBe(0);
+    expect(agent.stdout).toContain("run");
+    expect(agent.stdout).toContain("rotate-mandate");
+
+    const runHelp = run(["agent", "run", "--help"]);
+    expect(runHelp.code).toBe(0);
+    expect(runHelp.stdout).toContain("--config");
+    expect(runHelp.stdout).toContain("--watch");
+    expect(runHelp.stdout).toContain("--once");
+    expect(runHelp.stdout).toContain("--python-command");
+
+    const rotateHelp = run(["agent", "rotate-mandate", "--help"]);
+    expect(rotateHelp.code).toBe(0);
+    expect(rotateHelp.stdout).toContain("--config");
+    expect(rotateHelp.stdout).toContain("--old-mandate-id");
+    expect(rotateHelp.stdout).toContain("--expires-at");
+    expect(rotateHelp.stdout).toContain("--python-command");
+  });
+
+  it("reads LINKEDCLAW_OWNER_AGENT_CONFIG when --config is omitted", async () => {
+    const configPath = path.join(mkdtempSync(path.join(tmpdir(), "linkedclaw-agent-cli-")), "config.yaml");
+    const fakePython = makeFakePython();
+    writeFileSync(configPath, "agent_id: ag_owner\n", "utf8");
+    process.env.LINKEDCLAW_OWNER_AGENT_CONFIG = configPath;
+
+    await runHiddenAgent(["--watch", "debate_1:clg_1", "--once", "--python-command", fakePython]);
+
+    expect(spawnMock).toHaveBeenCalledWith(fakePython, [
+      "-m",
+      "linkedclaw.owner_agent.cli",
+      "run",
+      "--config",
+      configPath,
+      "--watch",
+      "debate_1:clg_1",
+      "--once",
+    ], { stdio: "inherit" });
+  });
+
+  it("forwards SIGTERM and SIGINT to the Python child", async () => {
+    const fakePython = makeFakePython();
+    const sigtermChild = await runHiddenAgent(["--once", "--python-command", fakePython]);
+
+    process.emit("SIGTERM");
+    expect(sigtermChild.kill).toHaveBeenCalledWith("SIGTERM");
+    sigtermChild.emit("exit", 0, null);
+    activeChild = undefined;
+
+    const sigintChild = await runHiddenAgent(["--once", "--python-command", fakePython]);
+    process.emit("SIGINT");
+    expect(sigintChild.kill).toHaveBeenCalledWith("SIGINT");
+  });
+
+  it("rotates mandates with env config and forwards optional flags", async () => {
+    const configPath = path.join(mkdtempSync(path.join(tmpdir(), "linkedclaw-agent-cli-")), "config.yaml");
+    const fakePython = makeFakePython();
+    writeFileSync(configPath, "agent_id: ag_owner\n", "utf8");
+    process.env.LINKEDCLAW_OWNER_AGENT_CONFIG = configPath;
+
+    await runHiddenRotate([
+      "--old-mandate-id",
+      "man_old",
+      "--expires-at",
+      "2026-05-04T00:00:00Z",
+      "--python-command",
+      fakePython,
+    ]);
+
+    expect(spawnMock).toHaveBeenCalledWith(fakePython, [
+      "-m",
+      "linkedclaw.owner_agent.cli",
+      "rotate-mandate",
+      "--config",
+      configPath,
+      "--old-mandate-id",
+      "man_old",
+      "--expires-at",
+      "2026-05-04T00:00:00Z",
+    ], { stdio: "inherit" });
+  });
+
+  it("rejects invalid rotate mandate options as JSON", async () => {
+    const configPath = path.join(mkdtempSync(path.join(tmpdir(), "linkedclaw-agent-cli-")), "config.yaml");
+    const fakePython = makeFakePython();
+    writeFileSync(configPath, "agent_id: ag_owner\n", "utf8");
+    const stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    await runHiddenRotate([
+      "--config",
+      configPath,
+      "--old-mandate-id",
+      "",
+      "--python-command",
+      fakePython,
+    ]);
+
+    expect(spawnMock).not.toHaveBeenCalled();
+    expect(stderrSpy).toHaveBeenCalled();
+    const payload = JSON.parse(String(stderrSpy.mock.calls[0][0]));
+    expect(payload.error).toBe("invalid_agent_rotate_mandate_option");
+    expect(payload.message).toContain("--old-mandate-id");
+    stderrSpy.mockRestore();
+  });
+});