@linkedclaw/cli 0.1.2 → 0.1.3

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 {
+  BroadcastExecuteEvent,
+  BroadcastExecuteResult,
+  BroadcastOfferDecision,
+  BroadcastOfferEvent,
+  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 onBroadcastOffer(evt: BroadcastOfferEvent): Promise<BroadcastOfferDecision> {
+    return this.request<BroadcastOfferDecision>(evt);
+  }
+
+  async onBroadcastExecute(evt: BroadcastExecuteEvent): Promise<BroadcastExecuteResult> {
+    return this.request<BroadcastExecuteResult>(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 CreateBroadcastRequest {
+  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 AcceptBroadcastRequest {
+  agent_id: EntityId;
+  slot_key?: string | null;
+}
+
+export interface BroadcastSubmitRequest {
+  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,
+  BroadcastOfferDecision,
+  BroadcastExecuteResult,
+  InvokeHandlerResult,
+  SessionAcceptDecision,
+  SessionReply,
+} from "@linkedclaw/provider-runtime";
+export type { MessageType } from "@linkedclaw/provider";

package/test/cli-help.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BIN = path.resolve(__dirname, "../dist/bin.js");
+
+beforeAll(() => {
+  if (!existsSync(BIN)) {
+    throw new Error(`bin not built — run 'pnpm -r --filter @linkedclaw/cli build' first (${BIN})`);
+  }
+});
+
+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 ?? "" };
+}
+
+describe("cli help", () => {
+  it("--help lists every top-level verb from §3.9", () => {
+    const { code, stdout } = run(["--help"]);
+    expect(code).toBe(0);
+    for (const verb of [
+      "provider", "broadcast", "search", "hire", "send", "end",
+      "invoke", "receipt", "trust", "credits", "register", "login", "whoami",
+    ]) {
+      expect(stdout).toContain(verb);
+    }
+  });
+
+  it("hire --help shows --message and --interactive", () => {
+    const { code, stdout } = run(["hire", "--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toContain("--message");
+    expect(stdout).toContain("--interactive");
+  });
+
+  it("register --help shows --no-browser and --cloud-url", () => {
+    const { code, stdout } = run(["register", "--help"]);
+    expect(code).toBe(0);
+    expect(stdout).toContain("--no-browser");
+    expect(stdout).toContain("--cloud-url");
+  });
+
+  it("provider --help shows all six subcommands", () => {
+    const { code, stdout } = run(["provider", "--help"]);
+    expect(code).toBe(0);
+    for (const sub of ["register", "update", "listings", "run", "pick", "submit"]) {
+      expect(stdout).toContain(sub);
+    }
+  });
+
+  it("broadcast --help shows all six subcommands", () => {
+    const { code, stdout } = run(["broadcast", "--help"]);
+    expect(code).toBe(0);
+    for (const sub of ["create", "get", "list", "available", "accept", "submit"]) {
+      expect(stdout).toContain(sub);
+    }
+  });
+});

package/test/hire-flags.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi } from "vitest";
+
+const sendSpy = vi.fn().mockResolvedValue({ ok: true });
+const eventsSpy = vi.fn().mockResolvedValue({ events: [{}, {}] });
+const hireSpy = vi.fn().mockResolvedValue({ session: { session_id: "s1" }, activated: true });
+const endSessionSpy = vi.fn().mockResolvedValue({ ok: true });
+
+vi.mock("../src/context.js", () => ({
+  buildContext: () => ({
+    cfg: { apiKey: "k", cloudUrl: "http://x" },
+    requesterFlows: { hire: hireSpy, send: sendSpy, search: vi.fn(), invoke: vi.fn() },
+    consumer: { getSessionEvents: eventsSpy, endSession: endSessionSpy, invoke: vi.fn() },
+    providerClient: {},
+  }),
+}));
+
+vi.mock("../src/output.js", () => ({
+  runCommand: async (fn: () => Promise<unknown>) => fn(),
+  readStdin: async () => "",
+  printError: () => {},
+  printResult: () => {},
+}));
+
+describe("hire --message", () => {
+  it("calls requesterFlows.send once with message and seq=1", async () => {
+    const { Command } = await import("commander");
+    const program = new Command();
+    program.exitOverride();
+    const { registerRequesterCommands } = await import("../src/commands/requester.js");
+    registerRequesterCommands(program);
+
+    await program.parseAsync([
+      "node", "cli", "hire", "agent-1",
+      "--capability", "test-cap",
+      "--message", "hello",
+    ]);
+
+    expect(hireSpy).toHaveBeenCalled();
+    expect(sendSpy).toHaveBeenCalledWith("s1", "hello", 1);
+  });
+});
+
+describe("hire --interactive flag", () => {
+  it("--interactive option is registered on the hire command", async () => {
+    const { Command } = await import("commander");
+    const program = new Command();
+    const { registerRequesterCommands } = await import("../src/commands/requester.js");
+    registerRequesterCommands(program);
+
+    const hireCmd = program.commands.find((c) => c.name() === "hire");
+    expect(hireCmd).toBeDefined();
+    const interactiveOpt = hireCmd!.options.find((o) => o.long === "--interactive");
+    expect(interactiveOpt).toBeDefined();
+  });
+});

package/test/recv-flags.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from "vitest";
+
+const eventsSpy = vi.fn();
+
+vi.mock("../src/context.js", () => ({
+  buildContext: () => ({
+    cfg: { apiKey: "k", cloudUrl: "http://x" },
+    requesterFlows: { hire: vi.fn(), send: vi.fn(), search: vi.fn(), invoke: vi.fn() },
+    consumer: { getSessionEvents: eventsSpy, endSession: vi.fn(), invoke: vi.fn() },
+    providerClient: {},
+  }),
+}));
+
+vi.mock("../src/output.js", () => ({
+  runCommand: async (fn: () => Promise<unknown>) => fn(),
+  readStdin: async () => "",
+  printError: () => {},
+  printResult: () => {},
+}));
+
+describe("recv subcommand", () => {
+  it("registers with --since, --wait, --human options", async () => {
+    const { Command } = await import("commander");
+    const program = new Command();
+    const { registerRequesterCommands } = await import("../src/commands/requester.js");
+    registerRequesterCommands(program);
+
+    const recvCmd = program.commands.find((c) => c.name() === "recv");
+    expect(recvCmd).toBeDefined();
+    expect(recvCmd!.options.find((o) => o.long === "--since")).toBeDefined();
+    expect(recvCmd!.options.find((o) => o.long === "--wait")).toBeDefined();
+    expect(recvCmd!.options.find((o) => o.long === "--human")).toBeDefined();
+  });
+
+  it("calls getSessionEvents with offset=0 by default", async () => {
+    eventsSpy.mockResolvedValueOnce({ events: [{ event_seq: 1 }], next_offset: 1 });
+    const { Command } = await import("commander");
+    const program = new Command();
+    program.exitOverride();
+    const { registerRequesterCommands } = await import("../src/commands/requester.js");
+    registerRequesterCommands(program);
+
+    await program.parseAsync(["node", "cli", "recv", "ses_1"]);
+
+    expect(eventsSpy).toHaveBeenCalledWith("ses_1", { offset: 0 });
+  });
+
+  it("forwards --since as offset", async () => {
+    eventsSpy.mockResolvedValueOnce({ events: [{ event_seq: 7 }], next_offset: 7 });
+    const { Command } = await import("commander");
+    const program = new Command();
+    program.exitOverride();
+    const { registerRequesterCommands } = await import("../src/commands/requester.js");
+    registerRequesterCommands(program);
+
+    await program.parseAsync(["node", "cli", "recv", "ses_2", "--since", "5"]);
+
+    expect(eventsSpy).toHaveBeenCalledWith("ses_2", { offset: 5 });
+  });
+
+  it("polls repeatedly under --wait until events arrive", async () => {
+    eventsSpy.mockReset();
+    eventsSpy
+      .mockResolvedValueOnce({ events: [], next_offset: 0 })
+      .mockResolvedValueOnce({ events: [], next_offset: 0 })
+      .mockResolvedValueOnce({ events: [{ event_seq: 1 }], next_offset: 1 });
+
+    vi.useFakeTimers();
+    const { Command } = await import("commander");
+    const program = new Command();
+    program.exitOverride();
+    const { registerRequesterCommands } = await import("../src/commands/requester.js");
+    registerRequesterCommands(program);
+
+    const promise = program.parseAsync(["node", "cli", "recv", "ses_3", "--wait", "10"]);
+    await vi.advanceTimersByTimeAsync(1500);
+    await vi.advanceTimersByTimeAsync(1500);
+    await promise;
+    vi.useRealTimers();
+
+    expect(eventsSpy).toHaveBeenCalledTimes(3);
+  });
+});

package/test/register-browser.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi } from "vitest";
+
+const writeSpy = vi.fn();
+const readFileSpy = vi.fn().mockReturnValue({});
+
+vi.mock("../src/config.js", () => ({
+  configPath: () => "/tmp/cli-test-config.yaml",
+  configDir: () => "/tmp",
+  readFileConfig: readFileSpy,
+  writeFileConfig: writeSpy,
+  resolveConfig: () => ({ apiKey: "", cloudUrl: "http://localhost:17221" }),
+}));
+
+vi.mock("../src/output.js", () => ({
+  runCommand: async (fn: () => Promise<unknown>) => fn(),
+  readLine: async () => "test-api-key-abc123",
+  readStdin: async () => "test-api-key-abc123",
+  printError: () => {},
+  printResult: () => {},
+}));
+
+const openSpy = vi.fn().mockResolvedValue(undefined);
+vi.mock("open", () => ({ default: openSpy }));
+
+describe("register --browser", () => {
+  it("opens portal URL and persists pasted key via writeFileConfig", async () => {
+    openSpy.mockResolvedValueOnce(undefined);
+
+    const { Command } = await import("commander");
+    const program = new Command();
+    program.exitOverride();
+    const { registerAuthCommands } = await import("../src/commands/auth.js");
+    registerAuthCommands(program);
+
+    await program.parseAsync(["node", "cli", "register", "--cloud-url", "http://test:17221"]);
+
+    expect(openSpy).toHaveBeenCalledWith("http://test:17221/register");
+    expect(writeSpy).toHaveBeenCalledWith(expect.objectContaining({ apiKey: "test-api-key-abc123" }));
+  });
+
+  it("falls through to URL print when open() throws (headless)", async () => {
+    openSpy.mockRejectedValueOnce(new Error("no DISPLAY"));
+    writeSpy.mockClear();
+
+    const { Command } = await import("commander");
+    const program = new Command();
+    program.exitOverride();
+    const { registerAuthCommands } = await import("../src/commands/auth.js");
+    registerAuthCommands(program);
+
+    await program.parseAsync(["node", "cli", "register", "--cloud-url", "http://test:17221"]);
+
+    expect(writeSpy).toHaveBeenCalled();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules", "test"]
+}

package/tsup.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/bin.ts"],
+  format: ["esm"],
+  platform: "node",
+  dts: false,
+  sourcemap: true,
+  clean: true,
+  target: "node20",
+  splitting: false,
+  shims: false,
+  banner: { js: "#!/usr/bin/env node" },
+  // Bundle the four SDK packages so `npm install -g @linkedclaw/cli` works without
+  // separate installs.
+  noExternal: [
+    "@linkedclaw/consumer",
+    "@linkedclaw/consumer-runtime",
+    "@linkedclaw/provider",
+    "@linkedclaw/provider-runtime",
+  ],
+  // ws is CJS and requires Node built-ins dynamically; keep it external so Node
+  // resolves it natively at runtime (ws is a direct dep for this reason).
+  external: ["ws"],
+});

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["test/**/*.test.ts"],
+    environment: "node",
+  },
+});