@linkedclaw/cli 0.1.2 → 0.1.3

package/src/commands/requester.ts

@@ -0,0 +1,436 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { load as yamlLoad } from "js-yaml";
+import type { ConsumerClient } from "@linkedclaw/consumer";
+import type {
+  AcceptBroadcastRequest,
+  BroadcastSubmitRequest,
+  CreateBroadcastRequest,
+  EndSessionRequest,
+  InvokeRequest,
+  TaskManifest,
+} from "../types.js";
+import { buildContext, type CliContext } from "../context.js";
+import { runCommand, readStdin } from "../output.js";
+
+export function registerRequesterCommands(program: Command): void {
+  program
+    .command("search <capability>")
+    .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("--human", "Human-readable output")
+    .action(async (capability: string, opts) => {
+      await runCommand(async () => {
+        const { requesterFlows } = buildContext();
+        return requesterFlows.search(capability, {
+          ...(opts.owner ? { owner: opts.owner } : {}),
+          ...(opts.status ? { status: opts.status } : {}),
+          ...(opts.sort ? { sort: opts.sort } : {}),
+        });
+      }, { human: opts.human });
+    });
+
+  program
+    .command("hire <agent_id>")
+    .description("Create and activate a 1:1 session with an agent")
+    .requiredOption("--capability <cap>", "Capability being hired")
+    .option("--max-messages <n>", "Message cap (server default 1)", (v) => parseInt(v, 10))
+    .option("--referred-by <ref_id>", "Attribution: referrer agent id")
+    .option("--no-activate", "Create session but do not activate (returns session only)")
+    .option("--message <msg>", "Send a single message after activation, then return")
+    .option("--interactive", "Open a REPL after activation (> message / .end / .status / .quit)")
+    .option("--human", "Human-readable output")
+    .action(async (agentId: string, opts) => {
+      await runCommand(async () => {
+        const ctx = buildContext();
+        const { requesterFlows, cfg } = ctx;
+        const result = await requesterFlows.hire({
+          providerAgentId: agentId,
+          capability: opts.capability,
+          ...(opts.maxMessages !== undefined ? { maxMessages: opts.maxMessages } : {}),
+          ...(opts.referredBy !== undefined ? { referredBy: opts.referredBy } : {}),
+          autoActivate: opts.activate !== false,
+          apiKey: cfg.apiKey!,
+          agentId: cfg.agentId ?? "",
+          relayUrl: cfg.relayUrl,
+        });
+
+        const sessionId =
+          (result as { session?: { session_id?: string } }).session?.session_id;
+
+        if (opts.message && sessionId) {
+          await requesterFlows.send(sessionId, opts.message, 1);
+        }
+
+        if (opts.interactive && sessionId) {
+          await runHireRepl(sessionId, ctx);
+        }
+
+        return result;
+      }, { human: opts.human });
+    });
+
+  program
+    .command("send <session_id> <message>")
+    .description(
+      'Send a message in an active session. Message is wrapped as {"text": "..."} ' +
+      'if it\'s a plain string, or passed through if it\'s a JSON object. Use "-" to read from stdin.',
+    )
+    .requiredOption("--seq <n>", "Sequence number (server requires ≥ 1)", (v) => parseInt(v, 10))
+    .option("--json", "Interpret message as a JSON object literal (default: wrap as {text})")
+    .option("--human", "Human-readable output")
+    .action(async (sessionId: string, message: string, opts) => {
+      await runCommand(async () => {
+        const { requesterFlows } = buildContext();
+        const raw = message === "-" ? await readStdin() : message;
+        const payload: Record<string, unknown> | string = opts.json
+          ? (parseJsonOrFail(raw, "<message>") as Record<string, unknown>)
+          : raw;
+        return requesterFlows.send(sessionId, payload, opts.seq);
+      }, { human: opts.human });
+    });
+
+  program
+    .command("recv <session_id>")
+    .description(
+      "Fetch session events since --since (default 0). With --wait, polls " +
+      "every 1.5s until new events arrive or the deadline elapses.",
+    )
+    .option("--since <seq>", "Offset to fetch events from (default 0)", (v) => parseInt(v, 10))
+    .option("--wait <s>", "Long-poll up to N seconds for new events", (v) => parseInt(v, 10))
+    .option("--human", "Human-readable output")
+    .action(async (sessionId: string, opts) => {
+      await runCommand(async () => {
+        const { consumer } = buildContext();
+        const offset = opts.since ?? 0;
+        const deadline = opts.wait !== undefined ? Date.now() + opts.wait * 1000 : 0;
+        let resp = await consumer.getSessionEvents(sessionId, { offset });
+        while (
+          opts.wait !== undefined &&
+          (resp.events?.length ?? 0) === 0 &&
+          Date.now() < deadline
+        ) {
+          await new Promise((r) => setTimeout(r, 1500));
+          resp = await consumer.getSessionEvents(sessionId, { offset });
+        }
+        if (opts.human) return formatEventsHuman(resp.events ?? []);
+        return resp;
+      }, { human: opts.human });
+    });
+
+  program
+    .command("end <session_id>")
+    .description("Mark a session ended")
+    .option("--message-count <n>", "Declare final message count", (v) => parseInt(v, 10))
+    .option("--final-output <text>", "Final output blurb (optional)")
+    .option("--human", "Human-readable output")
+    .action(async (sessionId: string, opts) => {
+      await runCommand(async () => {
+        const { consumer } = buildContext();
+        const body: EndSessionRequest = {};
+        if (opts.messageCount !== undefined) body.message_count = opts.messageCount;
+        if (opts.finalOutput !== undefined) body.final_output = opts.finalOutput;
+        return endSession(consumer, sessionId, body);
+      }, { human: opts.human });
+    });
+
+  program
+    .command("invoke <agent_id>")
+    .description("One-shot stateless invoke")
+    .requiredOption("--capability <cap>", "Capability")
+    .requiredOption("--input <json>", 'JSON input (or "-" to read from stdin)')
+    .option("--max-credits <n>", "Max credits", (v) => parseInt(v, 10))
+    .option("--timeout <s>", "Server-side timeout seconds (5..300, default 60)", (v) => parseInt(v, 10))
+    .option("--referred-by <ref_id>", "Attribution: referrer agent id")
+    .option("--manifest-id <mft_id>", "Pre-registered task manifest id")
+    .option(
+      "--manifest <json>",
+      'Inline task manifest JSON (literal, @file, or "-" for stdin). Minimum: {"intention":"..."}',
+    )
+    .option(
+      "--intention <text>",
+      "Shortcut: builds a minimal manifest {intention: <text>} if --manifest/--manifest-id are not set.",
+    )
+    .option("--human", "Human-readable output")
+    .action(async (agentId: string, opts) => {
+      await runCommand(async () => {
+        const { consumer } = buildContext();
+        const inputJson = opts.input === "-" ? await readStdin() : opts.input;
+        const input = parseJsonOrFail(inputJson, "--input");
+        const manifest = await resolveManifestOpt(
+          opts.manifest,
+          opts.manifestId,
+          opts.intention,
+          `invoke: ${opts.capability}`,
+        );
+        const body: InvokeRequest = { capability: opts.capability, input };
+        if (opts.maxCredits !== undefined) body.max_credits = opts.maxCredits;
+        if (opts.timeout !== undefined) body.timeout_seconds = opts.timeout;
+        if (opts.referredBy !== undefined) body.referred_by = opts.referredBy;
+        if (opts.manifestId !== undefined) body.manifest_id = opts.manifestId;
+        if (manifest !== undefined) body.manifest = manifest;
+        return invokeAgent(consumer, agentId, body);
+      }, { human: opts.human });
+    });
+
+  const broadcast = program.command("broadcast").description("Broadcast task commands");
+
+  broadcast
+    .command("create <manifest>")
+    .description(
+      'Create a broadcast task from a YAML/JSON manifest file. Use "-" for stdin. ' +
+      'Required fields: capability, instruction, target_providers, credits_per_provider.',
+    )
+    .option("--human", "Human-readable output")
+    .action(async (manifestPath: string, opts) => {
+      await runCommand(async () => {
+        const { consumer } = buildContext();
+        const raw = manifestPath === "-" ? await readStdin() : readFileSync(manifestPath, "utf8");
+        const body = parseYamlOrJson(raw) as CreateBroadcastRequest;
+        return consumer.createGigTask(body as unknown as Record<string, unknown>);
+      }, { human: opts.human });
+    });
+
+  broadcast
+    .command("get <bct_id>")
+    .description("Get a broadcast task by id")
+    .option("--human", "Human-readable output")
+    .action(async (taskId: string, opts) => {
+      await runCommand(async () => {
+        const { consumer } = buildContext();
+        return consumer.getGigTask(taskId);
+      }, { human: opts.human });
+    });
+
+  broadcast
+    .command("list")
+    .description("List broadcasts I own")
+    .option("--status <s>", "Filter by status")
+    .option("--human", "Human-readable output")
+    .action(async (opts) => {
+      await runCommand(async () => {
+        const { consumer } = buildContext();
+        return consumer.listGigTasks({
+          ...(opts.status ? { status: opts.status } : {}),
+        });
+      }, { human: opts.human });
+    });
+
+  broadcast
+    .command("available")
+    .description("List open broadcasts I could pick up (as provider)")
+    .option("--human", "Human-readable output")
+    .action(async (opts) => {
+      await runCommand(async () => {
+        const { providerClient } = buildContext();
+        return providerClient.listGigTasksAvailable();
+      }, { human: opts.human });
+    });
+
+  broadcast
+    .command("accept <bct_id>")
+    .description("Accept a broadcast (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("--human", "Human-readable output")
+    .action(async (taskId: string, opts) => {
+      await runCommand(async () => {
+        const { providerClient } = buildContext();
+        const body: AcceptBroadcastRequest = { 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
+    .command("submit <bct_id>")
+    .description(
+      "Submit broadcast 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)')
+    .option("--human", "Human-readable output")
+    .action(async (taskId: string, opts) => {
+      await runCommand(async () => {
+        const { providerClient } = buildContext();
+        const raw = opts.body === "-" ? await readStdin() : opts.body;
+        const body = parseJsonOrFail(raw, "--body") as unknown as BroadcastSubmitRequest;
+        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");
+        }
+        return providerClient.submitGigTask(taskId, body as unknown as Record<string, unknown>);
+      }, { human: opts.human });
+    });
+
+  program
+    .command("receipt <rct_id>")
+    .description("Fetch a single receipt")
+    .option("--human", "Human-readable output")
+    .action(async (receiptId: string, opts) => {
+      await runCommand(async () => {
+        const { consumer } = buildContext();
+        return consumer.getReceipt(receiptId);
+      }, { human: opts.human });
+    });
+
+  program
+    .command("trust <agent_id>")
+    .description("Get trust summary for an agent (per-capability)")
+    .option("--human", "Human-readable output")
+    .action(async (agentId: string, opts) => {
+      await runCommand(async () => {
+        const { consumer } = buildContext();
+        return consumer.getTrustScore(agentId);
+      }, { human: opts.human });
+    });
+
+  program
+    .command("credits")
+    .description("Current credit balance")
+    .option("--human", "Human-readable output")
+    .action(async (opts) => {
+      await runCommand(async () => {
+        const { consumer } = buildContext();
+        return consumer.getBalance();
+      }, { human: opts.human });
+    });
+}
+
+async function runHireRepl(
+  sessionId: string,
+  ctx: CliContext,
+): Promise<void> {
+  const readline = await import("node:readline/promises");
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  process.stderr.write(
+    `interactive: session ${sessionId}\n` +
+    `  > <text>   send message\n` +
+    `  .status    poll session events count\n` +
+    `  .end       end the session and exit\n` +
+    `  .quit      exit without ending\n`,
+  );
+  // seq=1 is reserved for --message; REPL starts at 2. If --message wasn't
+  // used, seq=2 is still legal (monotonic ≥1, server accepts any start value).
+  let seq = 2;
+  try {
+    while (true) {
+      const line = (await rl.question("> ")).trim();
+      if (!line) continue;
+      if (line === ".quit") return;
+      if (line === ".end") {
+        const out = await endSession(ctx.consumer, sessionId, {});
+        process.stdout.write(JSON.stringify(out) + "\n");
+        return;
+      }
+      if (line === ".status") {
+        const events = await ctx.consumer.getSessionEvents(sessionId, { offset: 0 });
+        const count = Array.isArray((events as { events?: unknown[] }).events)
+          ? (events as { events: unknown[] }).events.length
+          : 0;
+        process.stderr.write(`events: ${count}\n`);
+        continue;
+      }
+      const out = await ctx.requesterFlows.send(sessionId, line, seq++);
+      process.stdout.write(JSON.stringify(out) + "\n");
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+function endSession(
+  consumer: ConsumerClient,
+  sessionId: string,
+  body: EndSessionRequest,
+): Promise<Record<string, unknown>> {
+  return consumer.endSession(sessionId, {
+    finalOutput: body.final_output ?? undefined,
+    messageCount: body.message_count ?? undefined,
+  });
+}
+
+function invokeAgent(
+  consumer: ConsumerClient,
+  agentId: string,
+  opts: InvokeRequest,
+): Promise<unknown> {
+  return consumer.invoke(agentId, {
+    capability: opts.capability,
+    input: opts.input,
+    maxCredits: opts.max_credits ?? undefined,
+    manifestId: opts.manifest_id ?? undefined,
+    manifest: opts.manifest as Record<string, unknown> | undefined,
+    timeoutSeconds: opts.timeout_seconds ?? undefined,
+    referredBy: opts.referred_by ?? undefined,
+  });
+}
+
+function formatEventsHuman(events: Record<string, unknown>[]): string {
+  if (events.length === 0) return "(no events)";
+  return events
+    .map((ev) => {
+      const seq = ev.seq ?? ev.offset ?? "?";
+      const type = ev.event_type ?? ev.type ?? "event";
+      const from = ev.sender_agent_id ?? ev.from ?? "-";
+      const payload = ev.payload ?? ev.data ?? {};
+      return `[${seq}] ${type} from=${from} ${JSON.stringify(payload)}`;
+    })
+    .join("\n");
+}
+
+function parseJsonOrFail(raw: string, label: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`${label} must be a JSON object`);
+    }
+    return parsed as Record<string, unknown>;
+  } catch (err) {
+    throw new Error(`invalid JSON in ${label}: ${(err as Error).message}`);
+  }
+}
+
+function parseYamlOrJson(raw: string): unknown {
+  const trimmed = raw.trimStart();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) return JSON.parse(raw);
+  return yamlLoad(raw);
+}
+
+/**
+ * Resolve the manifest for invoke. Server requires exactly one of manifest_id
+ * or manifest; the CLI auto-constructs a minimal `{intention}` manifest when
+ * neither is provided so "just invoke" works out of the box.
+ */
+async function resolveManifestOpt(
+  manifestOpt: string | undefined,
+  manifestId: string | undefined,
+  intention: string | undefined,
+  defaultIntention: string,
+): Promise<TaskManifest | undefined> {
+  if (manifestOpt !== undefined && manifestId !== undefined) {
+    throw new Error("--manifest and --manifest-id are mutually exclusive");
+  }
+  if (manifestId !== undefined) {
+    return undefined; // body.manifest_id set separately by caller
+  }
+  if (manifestOpt !== undefined) {
+    let raw: string;
+    if (manifestOpt === "-") {
+      raw = await readStdin();
+    } else if (manifestOpt.startsWith("@")) {
+      raw = readFileSync(manifestOpt.slice(1), "utf8");
+    } else {
+      raw = manifestOpt;
+    }
+    const parsed = parseJsonOrFail(raw, "--manifest");
+    if (typeof parsed.intention !== "string" || parsed.intention.length === 0) {
+      throw new Error('--manifest must include a non-empty "intention" field');
+    }
+    return parsed as unknown as TaskManifest;
+  }
+  // Neither --manifest nor --manifest-id supplied — auto-construct the
+  // minimum manifest the server requires.
+  return { intention: intention ?? defaultIntention };
+}

package/src/config.ts

@@ -0,0 +1,76 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { load as yamlLoad, dump as yamlDump } from "js-yaml";
+
+export const DEFAULT_CLOUD_URL = "https://api.linkedclaw.com";
+export const DEFAULT_RELAY_URL = "wss://api.linkedclaw.com/ws";
+
+export interface SanitizeConfig {
+  scope?: { stripPatterns?: string[] };
+  output?: { stripPatterns?: string[] };
+}
+
+export interface ProviderConfig {
+  cloudUrl: string;
+  relayUrl: string;
+  apiKey?: string;
+  agentId?: string;
+  agentName?: string;
+  slug?: string;
+  description?: string;
+  capabilities?: string[];
+  pricingModel?: string;
+  priceCredits?: number;
+  invokeTimeoutMs?: number;
+  sessionTurnTimeoutMs?: number;
+  broadcastTimeoutMs?: number;
+  maxConcurrentRuns?: number;
+  perRequesterLimit?: number;
+  sanitize?: SanitizeConfig;
+}
+
+export interface CliConfig extends ProviderConfig {}
+
+export function configDir(): string {
+  return process.env["LINKEDCLAW_CONFIG_DIR"] ?? join(homedir(), ".linkedclaw");
+}
+
+export function configPath(): string {
+  return join(configDir(), "config.yaml");
+}
+
+export function readFileConfig(path: string = configPath()): Partial<CliConfig> {
+  if (!existsSync(path)) return {};
+  const raw = readFileSync(path, "utf8");
+  const parsed = yamlLoad(raw);
+  if (parsed === null || parsed === undefined) return {};
+  if (typeof parsed !== "object") {
+    throw new Error(`config file ${path} is not a YAML object`);
+  }
+  return parsed as Partial<CliConfig>;
+}
+
+export function writeFileConfig(cfg: Partial<CliConfig>, path: string = configPath()): void {
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeFileSync(path, yamlDump(cfg), { mode: 0o600 });
+  if (process.platform !== "win32") chmodSync(path, 0o600);
+}
+
+export function resolveConfig(overrides: Partial<ProviderConfig> = {}): ProviderConfig {
+  const env = process.env;
+  const file = readFileConfig();
+  const cloudUrl =
+    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 apiKey = overrides.apiKey ?? env["LINKEDCLAW_API_KEY"] ?? file.apiKey;
+  return {
+    ...file,
+    ...overrides,
+    cloudUrl,
+    relayUrl,
+    ...(apiKey !== undefined ? { apiKey } : {}),
+  };
+}

package/src/context.ts

@@ -0,0 +1,27 @@
+import { ConsumerClient } from "@linkedclaw/consumer";
+import { ProviderClient } from "@linkedclaw/provider";
+import { RequesterFlows } from "@linkedclaw/consumer-runtime";
+import { resolveConfig, type ProviderConfig } from "./config.js";
+import { ConfigError } from "./errors.js";
+
+export interface CliContext {
+  cfg: ProviderConfig;
+  consumer: ConsumerClient;
+  providerClient: ProviderClient;
+  requesterFlows: RequesterFlows;
+}
+
+export function buildContext(overrides: Partial<ProviderConfig> = {}): CliContext {
+  const cfg = resolveConfig(overrides);
+  if (!cfg.apiKey) {
+    throw new ConfigError(
+      "missing apiKey — run `linkedclaw login`, set LINKEDCLAW_API_KEY, or edit ~/.linkedclaw/config.yaml",
+    );
+  }
+
+  const consumer = new ConsumerClient(cfg.cloudUrl, cfg.apiKey);
+  const providerClient = new ProviderClient(cfg.cloudUrl, cfg.apiKey);
+  const requesterFlows = new RequesterFlows(consumer);
+
+  return { cfg, consumer, providerClient, requesterFlows };
+}

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