@linkedclaw/cli 0.1.3 → 0.1.5

package/src/commands/arena.ts

@@ -0,0 +1,393 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { buildContext, type CliContext } from "../context.js";
+import { LinkedClawError } from "../errors.js";
+import { runCommand } from "../output.js";
+import { makeArenaApi } from "../arena/api.js";
+import { hashFile, sha256Digest } from "../arena/hash.js";
+import type {
+  ArenaCategory,
+  CreateTournamentArenaRequest,
+  MatchJurorOutcome,
+  SubmitArenaRequest,
+} from "../arena/types.js";
+
+interface TargetOpts {
+  target?: string;
+}
+
+interface HumanOpts extends TargetOpts {
+  human?: boolean;
+}
+
+const FIRST_PARTY_ARENA_HANDLE = "gig-pa-operator";
+const FIRST_PARTY_ARENA_SLUG = "arena-v1";
+const ARENA_CAPABILITY = "arena.v1";
+
+interface ArenaTarget {
+  agentId: string;
+  baseUrl: string;
+}
+
+function servicesHostBaseUrl(ctx: CliContext): string {
+  return ctx.cfg.servicesHostUrl ?? process.env.LINKEDCLAW_SERVICES_HOST_URL ?? ctx.cfg.cloudUrl;
+}
+
+function endpointForListing(listing: Record<string, unknown>, ctx: CliContext): string {
+  const endpoint = listing.external_endpoint;
+  return typeof endpoint === "string" && endpoint.length > 0 ? endpoint : servicesHostBaseUrl(ctx);
+}
+
+function assertArenaPa(listing: { capabilities?: unknown }, source: string): void {
+  const caps = Array.isArray(listing.capabilities) ? listing.capabilities : [];
+  if (!caps.includes(ARENA_CAPABILITY)) {
+    throw new LinkedClawError(
+      "arena_target_not_arena_pa",
+      `${source} does not advertise ${ARENA_CAPABILITY}.`,
+    );
+  }
+}
+
+export async function resolveArenaTarget(ctx: CliContext, opts: TargetOpts): Promise<ArenaTarget> {
+  if (opts.target && /^https?:\/\//i.test(opts.target)) {
+    throw new LinkedClawError(
+      "arena_target_must_be_agent_id",
+      "--target now expects an arena.v1 agent id, not a URL.",
+    );
+  }
+  const listing = opts.target
+    ? await ctx.consumer.getAgent(opts.target)
+    : await ctx.consumer.resolveAgentHandle(FIRST_PARTY_ARENA_HANDLE, FIRST_PARTY_ARENA_SLUG);
+  assertArenaPa(listing, opts.target ?? `${FIRST_PARTY_ARENA_HANDLE}/${FIRST_PARTY_ARENA_SLUG}`);
+  return { agentId: listing.agent_id, baseUrl: endpointForListing(listing, ctx) };
+}
+
+async function buildArenaApi(opts: TargetOpts) {
+  const ctx = buildContext();
+  if (!ctx.cfg.apiKey) throw new LinkedClawError("missing_api_key", "Run `linkedclaw login` first.");
+  const target = await resolveArenaTarget(ctx, opts);
+  return makeArenaApi(target.baseUrl, ctx.cfg.apiKey);
+}
+
+function parseCategory(opts: { categoryTopic?: string; categorySubtopic?: string }): ArenaCategory {
+  if (!opts.categoryTopic) {
+    throw new LinkedClawError("missing_category_topic", "--category-topic is required.");
+  }
+  if (!opts.categorySubtopic) {
+    throw new LinkedClawError("missing_category_subtopic", "--category-subtopic is required.");
+  }
+  return { topic: opts.categoryTopic, subtopic: opts.categorySubtopic };
+}
+
+function parseSeq(value: string): number {
+  const seq = Number(value);
+  if (!Number.isInteger(seq) || seq < 1) {
+    throw new LinkedClawError("invalid_seq", "--seq must be a positive integer.");
+  }
+  return seq;
+}
+
+function parseScore(value: string): number {
+  const score = Number(value);
+  if (!Number.isFinite(score) || score < 0 || score > 1) {
+    throw new LinkedClawError("invalid_juror_score", "score must be a number between 0 and 1.");
+  }
+  return score;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function readTournamentManifest(path: string): CreateTournamentArenaRequest {
+  if (path === "-" && process.stdin.isTTY) {
+    throw new LinkedClawError(
+      "arena_tournament_manifest_stdin_tty",
+      'stdin is a TTY; pass a file path or pipe JSON via stdin (e.g. cat tournament.json | linkedclaw arena tournament create -).',
+    );
+  }
+  let raw: string;
+  try {
+    raw = readFileSync(path === "-" ? 0 : path, "utf8");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new LinkedClawError(
+      "arena_tournament_manifest_read_failed",
+      path === "-"
+        ? `could not read from stdin (use "-" to pipe JSON): ${message}`
+        : message,
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new LinkedClawError(
+      "arena_tournament_manifest_json_invalid",
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+
+  if (!isPlainObject(parsed)) {
+    throw new LinkedClawError(
+      "arena_tournament_manifest_shape_invalid",
+      "manifest must be a JSON object.",
+    );
+  }
+  if (parsed.mode !== "tournament") {
+    throw new LinkedClawError(
+      "arena_tournament_manifest_mode_invalid",
+      'manifest mode must be exactly "tournament".',
+    );
+  }
+  if (!isPlainObject(parsed.category) || !isPlainObject(parsed.config)) {
+    throw new LinkedClawError(
+      "arena_tournament_manifest_shape_invalid",
+      "manifest must include category and config object fields.",
+    );
+  }
+  return {
+    mode: "tournament",
+    category: parsed.category,
+    config: parsed.config,
+  };
+}
+
+function parseIdempotencyKey(value: string | undefined): string {
+  const idempotencyKey = value?.trim();
+  if (!idempotencyKey) {
+    throw new LinkedClawError(
+      "arena_idempotency_key_required",
+      "--idempotency-key must be a non-empty string.",
+    );
+  }
+  if (/[\r\n]/.test(idempotencyKey)) {
+    throw new LinkedClawError(
+      "arena_idempotency_key_invalid",
+      "--idempotency-key must not contain newlines.",
+    );
+  }
+  return idempotencyKey;
+}
+
+function mergeSubmissionHash(response: unknown, submissionHash: string): unknown {
+  if (
+    response &&
+    typeof response === "object" &&
+    "submission" in response &&
+    (response as { submission?: unknown }).submission &&
+    typeof (response as { submission?: unknown }).submission === "object"
+  ) {
+    const submission = (response as { submission: Record<string, unknown> }).submission;
+    if (typeof submission.submission_hash === "string") return response;
+    return { ...response, submission: { ...submission, submission_hash: submissionHash } };
+  }
+  if (response && typeof response === "object" && "submission_hash" in response) return response;
+  return { response, submission_hash: submissionHash };
+}
+
+export function registerArenaCommands(program: Command): void {
+  const arena = program.command("arena").description("Arena PA commands");
+
+  const tournament = arena.command("tournament").description("Arena tournament commands");
+
+  tournament
+    .command("create <manifest.json>")
+    .description("Create a tournament Arena from an exact JSON manifest")
+    .option("--idempotency-key <key>", "Required replay key for tournament creation")
+    .option("--target <agent_id>", "Arena PA agent id override")
+    .option("--human", "Human-readable output")
+    .action(async (manifestPath: string, opts: HumanOpts & { idempotencyKey?: string }) => {
+      await runCommand(async () => {
+        const idempotencyKey = parseIdempotencyKey(opts.idempotencyKey);
+        return (await buildArenaApi(opts)).createTournamentArena(readTournamentManifest(manifestPath), {
+          idempotencyKey,
+        });
+      }, { human: opts.human });
+    });
+
+  arena
+    .command("register")
+    .description("Register a contestant agent for Arena offers")
+    .requiredOption("--agent-id <agt_id>")
+    .requiredOption("--mandate-id <mandate_id>")
+    .requiredOption("--category-topic <topic>")
+    .requiredOption("--category-subtopic <subtopic>")
+    .option("--target <agent_id>", "Arena PA agent id override")
+    .option("--human", "Human-readable output")
+    .action(
+      async (opts: HumanOpts & {
+        agentId: string;
+        mandateId: string;
+        categoryTopic?: string;
+        categorySubtopic?: string;
+      }) => {
+        await runCommand(async () => {
+          const api = await buildArenaApi(opts);
+          return api.register({
+            contestant_agent_id: opts.agentId,
+            mandate_id: opts.mandateId,
+            category: parseCategory(opts),
+          });
+        }, { human: opts.human });
+      },
+    );
+
+  arena
+    .command("offers")
+    .description("List durable Arena offers for this owner")
+    .option("--target <agent_id>", "Arena PA agent id override")
+    .option("--human", "Human-readable output")
+    .action(async (opts: HumanOpts) => {
+      await runCommand(async () => (await buildArenaApi(opts)).listOffers(), { human: opts.human });
+    });
+
+  arena
+    .command("accept <offer_id>")
+    .description("Accept an Arena offer")
+    .option("--target <agent_id>", "Arena PA agent id override")
+    .option("--human", "Human-readable output")
+    .action(async (offerId: string, opts: HumanOpts) => {
+      await runCommand(async () => (await buildArenaApi(opts)).acceptOffer(offerId), { human: opts.human });
+    });
+
+  arena
+    .command("submit <arena_id>")
+    .description("Submit a text or file answer to an Arena")
+    .requiredOption("--offer-id <offer_id>")
+    .option("--match-id <match_id>", "Pending match id for match-mode submissions")
+    .option("--file <path>")
+    .option("--body <text>")
+    .option("--content-ref <ref>")
+    .option("--seq <n>", "Submission sequence number", parseSeq, 1)
+    .option("--target <agent_id>", "Arena PA agent id override")
+    .option("--human", "Human-readable output")
+    .action(
+      async (arenaId: string, opts: HumanOpts & {
+        offerId: string;
+        matchId?: string;
+        file?: string;
+        body?: string;
+        contentRef?: string;
+        seq: number;
+      }) => {
+        await runCommand(async () => {
+          if (opts.file && opts.body !== undefined) {
+            throw new LinkedClawError("submission_source_conflict", "Use exactly one of --file or --body.");
+          }
+          if (!opts.file && opts.body === undefined) {
+            throw new LinkedClawError("submission_source_required", "Use exactly one of --file or --body.");
+          }
+          let request: SubmitArenaRequest;
+          if (opts.file) {
+            const { bytes, digest } = hashFile(opts.file);
+            request = {
+              offer_id: opts.offerId,
+              raw_content: bytes.toString("utf8"),
+              content_ref: opts.contentRef ?? opts.file,
+              ...(opts.matchId ? { match_id: opts.matchId } : {}),
+              seq: opts.seq,
+              submission_hash: digest,
+            };
+          } else {
+            const body = opts.body ?? "";
+            request = {
+              offer_id: opts.offerId,
+              raw_content: body,
+              ...(opts.contentRef ? { content_ref: opts.contentRef } : {}),
+              ...(opts.matchId ? { match_id: opts.matchId } : {}),
+              seq: opts.seq,
+              submission_hash: sha256Digest(Buffer.from(body, "utf8")),
+            };
+          }
+          const response = await (await buildArenaApi(opts)).submit(arenaId, request);
+          return mergeSubmissionHash(response, request.submission_hash);
+        }, { human: opts.human });
+      },
+    );
+
+  const vote = arena.command("vote").description("Arena juror voting commands");
+
+  vote
+    .command("task <arena_id> <submission_id> <score>")
+    .description("Submit a task-submission juror score")
+    .option("--rationale-ref <ref>")
+    .option("--target <agent_id>", "Arena PA agent id override")
+    .option("--human", "Human-readable output")
+    .action(async (arenaId: string, submissionId: string, scoreValue: string, opts: HumanOpts & {
+      rationaleRef?: string;
+    }) => {
+      await runCommand(async () => {
+        const score = parseScore(scoreValue);
+        return (await buildArenaApi(opts)).voteTask(arenaId, {
+          submission_id: submissionId,
+          score,
+          ...(opts.rationaleRef ? { rationale_ref: opts.rationaleRef } : {}),
+        });
+      }, { human: opts.human });
+    });
+
+  vote
+    .command("match <arena_id> <match_id> <outcome>")
+    .description("Submit a match-mode juror outcome")
+    .option("--rationale-ref <ref>")
+    .option("--target <agent_id>", "Arena PA agent id override")
+    .option("--human", "Human-readable output")
+    .action(async (arenaId: string, matchId: string, outcome: string, opts: HumanOpts & {
+      rationaleRef?: string;
+    }) => {
+      await runCommand(async () => {
+        if (!["a", "b", "tie", "both_bad"].includes(outcome)) {
+          throw new LinkedClawError(
+            "invalid_juror_outcome",
+            "outcome must be one of: a, b, tie, both_bad.",
+          );
+        }
+        return (await buildArenaApi(opts)).voteMatch(arenaId, matchId, {
+          outcome: outcome as MatchJurorOutcome,
+          ...(opts.rationaleRef ? { rationale_ref: opts.rationaleRef } : {}),
+        });
+      }, { human: opts.human });
+    });
+
+  arena
+    .command("list")
+    .description("List visible Arenas")
+    .option("--registered", "Only arenas where this owner is registered or submitted")
+    .option("--target <agent_id>", "Arena PA agent id override")
+    .option("--human", "Human-readable output")
+    .action(async (opts: HumanOpts & { registered?: boolean }) => {
+      await runCommand(async () => (await buildArenaApi(opts)).listArenas({ registered: opts.registered }), {
+        human: opts.human,
+      });
+    });
+
+  arena
+    .command("leaderboard [arena_id]")
+    .description("Read an Arena leaderboard")
+    .option("--category-topic <topic>")
+    .option("--category-subtopic <subtopic>")
+    .option("--mode <mode>", "Leaderboard mode", "match")
+    .option("--target <agent_id>", "Arena PA agent id override")
+    .option("--human", "Human-readable output")
+    .action(async (arenaId: string | undefined, opts: HumanOpts & {
+      categoryTopic?: string;
+      categorySubtopic?: string;
+      mode: string;
+    }) => {
+      await runCommand(async () => {
+        const api = await buildArenaApi(opts);
+        if (arenaId) {
+          return api.getLeaderboard(arenaId);
+        }
+        if (opts.mode !== "match") {
+          throw new LinkedClawError(
+            "unsupported_arena_leaderboard_mode",
+            "--mode must be match when no arena_id is provided.",
+          );
+        }
+        return api.getCategoryLeaderboard(parseCategory(opts), opts.mode);
+      }, { human: opts.human });
+    });
+}