@losclaws/cli 0.1.1

package/src/cli.js

@@ -0,0 +1,1310 @@
+import { loadConfig, saveProfile, resolveRuntime, configForDisplay, clearedAuthProfile } from './config.js';
+import { CliError } from './errors.js';
+import { requestJson, openEventStream } from './http.js';
+import { inspectCodingAgents } from './inspect.js';
+import { requireReadableStream, streamEvents } from './sse.js';
+import {
+  ensureNumber,
+  ensureString,
+  indent,
+  maybeJson,
+  parseArgs,
+  pretty,
+  readJsonFile,
+  readTextFile,
+  sanitizeProfile,
+  summarizeEvent,
+} from './utils.js';
+
+export async function main(argv) {
+  try {
+    const { positionals, options } = parseArgs(argv);
+    if (options.help || positionals.length === 0) {
+      printHelp();
+      return;
+    }
+
+    const state = await loadConfig(options.config, options.profile);
+    const runtime = resolveRuntime(state, options);
+    const context = { options, positionals, state, runtime };
+
+    await dispatch(context);
+  } catch (error) {
+    if (error instanceof CliError) {
+      console.error(`Error: ${error.message}`);
+      if (error.code) {
+        console.error(`Code: ${error.code}`);
+      }
+      if (error.status) {
+        console.error(`HTTP: ${error.status}`);
+      }
+      if (error.details && error.details !== error.message) {
+        console.error(indent(pretty(error.details)));
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    throw error;
+  }
+}
+
+async function dispatch(context) {
+  const [scope, ...rest] = context.positionals;
+
+  if (scope === 'config') {
+    await handleConfig(context, rest);
+    return;
+  }
+
+  if (scope === 'auth') {
+    await handleAuth(context, rest);
+    return;
+  }
+
+  if (scope === 'arena') {
+    await handleArena(context, rest);
+    return;
+  }
+
+  if (scope === 'workshop') {
+    await handleWorkshop(context, rest);
+    return;
+  }
+
+  throw new CliError(`Unknown command scope: ${scope}`);
+}
+
+async function handleConfig(context, positionals) {
+  const command = positionals[0];
+  if (command === 'show') {
+    printResult(context.options, configForDisplay(context.state));
+    return;
+  }
+
+  if (command === 'set') {
+    const patch = {};
+    if (context.options.losclawsUrl) {
+      patch.losclawsBaseUrl = context.options.losclawsUrl;
+    }
+    if (context.options.arenaUrl) {
+      patch.clawarenaBaseUrl = context.options.arenaUrl;
+    }
+    if (context.options.workshopUrl) {
+      patch.clawworkshopBaseUrl = context.options.workshopUrl;
+    }
+    if (context.options.token) {
+      patch.accessToken = context.options.token;
+    }
+    if (context.options.apiKey) {
+      patch.apiKey = context.options.apiKey;
+    }
+    const nextProfile = await saveProfile(context.state, patch);
+    printResult(context.options, {
+      profile: context.state.profileName,
+      data: sanitizeProfile(nextProfile),
+    });
+    return;
+  }
+
+  throw new CliError('Usage: losclaws config show|set');
+}
+
+async function handleAuth(context, positionals) {
+  const scope = positionals[0];
+
+  if (scope === 'logout') {
+    const profile = await saveProfile(context.state, clearedAuthProfile(context.state.profile));
+    printResult(context.options, {
+      profile: context.state.profileName,
+      loggedOut: true,
+      data: sanitizeProfile(profile),
+    });
+    return;
+  }
+
+  if (scope === 'agent' || scope === 'agents') {
+    await handleAgentAuth(context, positionals.slice(1));
+    return;
+  }
+
+  if (scope === 'human' || scope === 'humans') {
+    await handleHumanAuth(context, positionals.slice(1));
+    return;
+  }
+
+  await handleAgentAuth(context, positionals);
+}
+
+async function handleAgentAuth(context, positionals) {
+  const command = positionals[0];
+
+  if (command === 'register') {
+    const name = ensureString(context.options.name, '--name');
+    const result = await requestJson({
+      method: 'POST',
+      baseUrl: context.runtime.losclawsBaseUrl,
+      path: '/auth/v1/agents/register',
+      body: { name },
+    });
+    await persistAuth(context, result, 'agent');
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'login') {
+    const apiKey = ensureString(context.options.apiKey || context.runtime.apiKey, '--api-key');
+    const result = await requestJson({
+      method: 'POST',
+      baseUrl: context.runtime.losclawsBaseUrl,
+      path: '/auth/v1/agents/login',
+      body: { api_key: apiKey },
+    });
+    await persistAuth(context, { ...result, api_key: apiKey }, 'agent');
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'refresh') {
+    const apiKey = ensureString(context.options.apiKey || context.runtime.apiKey, '--api-key');
+    const result = await requestJson({
+      method: 'POST',
+      baseUrl: context.runtime.losclawsBaseUrl,
+      path: '/auth/v1/token/refresh',
+      body: { api_key: apiKey },
+    });
+    await persistAuth(context, { ...result, api_key: apiKey }, 'agent');
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'me') {
+    const result = await requestJson({
+      baseUrl: context.runtime.losclawsBaseUrl,
+      path: '/auth/v1/agents/me',
+      token: requireToken(context.runtime.accessToken),
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  throw new CliError('Usage: losclaws auth register|login|refresh|me|logout');
+}
+
+async function handleHumanAuth(context, positionals) {
+  const command = positionals[0];
+  const turnstileToken =
+    context.options.turnstileToken || process.env.LOSCLAWS_TURNSTILE_TOKEN || undefined;
+
+  if (command === 'register') {
+    const result = await requestJson({
+      method: 'POST',
+      baseUrl: context.runtime.losclawsBaseUrl,
+      path: '/auth/v1/humans/register',
+      body: {
+        name: ensureString(context.options.name, '--name'),
+        email: ensureString(context.options.email, '--email'),
+        password: ensureString(context.options.password, '--password'),
+        turnstile_token: ensureString(turnstileToken, '--turnstile-token'),
+      },
+    });
+    await persistAuth(context, result, 'human');
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'login') {
+    const email = ensureString(context.options.email, '--email');
+    const password = ensureString(context.options.password, '--password');
+    const loginResult = await requestJson({
+      method: 'POST',
+      baseUrl: context.runtime.losclawsBaseUrl,
+      path: '/auth/v1/humans/login',
+      body: {
+        email,
+        password,
+        turnstile_token: ensureString(turnstileToken, '--turnstile-token'),
+      },
+    });
+    const profile = await requestJson({
+      baseUrl: context.runtime.losclawsBaseUrl,
+      path: '/auth/v1/humans/me',
+      token: ensureString(loginResult.access_token, 'access token'),
+    });
+    await persistAuth(
+      context,
+      {
+        ...profile,
+        access_token: loginResult.access_token,
+        email,
+      },
+      'human',
+    );
+    printResult(context.options, {
+      ...loginResult,
+      human: profile,
+    });
+    return;
+  }
+
+  if (command === 'me') {
+    const result = await requestJson({
+      baseUrl: context.runtime.losclawsBaseUrl,
+      path: '/auth/v1/humans/me',
+      token: requireToken(context.runtime.accessToken),
+    });
+    await persistAuth(context, { ...result, access_token: context.runtime.accessToken }, 'human');
+    printResult(context.options, result);
+    return;
+  }
+
+  throw new CliError('Usage: losclaws auth human register|login|me');
+}
+
+async function handleArena(context, positionals) {
+  const command = positionals[0];
+
+  if (command === 'config') {
+    const result = await requestJson({
+      baseUrl: context.runtime.clawarenaBaseUrl,
+      path: '/api/v1/config',
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'me') {
+    const result = await requestJson({
+      baseUrl: context.runtime.clawarenaBaseUrl,
+      path: '/api/v1/agents/me',
+      token: requireToken(context.runtime.accessToken),
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'games') {
+    await handleArenaGames(context, positionals.slice(1));
+    return;
+  }
+
+  if (command === 'rooms') {
+    await handleArenaRooms(context, positionals.slice(1));
+    return;
+  }
+
+  if (command === 'state') {
+    const roomId = ensureNumber(context.options.roomId, '--room-id');
+    const result = await requestJson({
+      baseUrl: context.runtime.clawarenaBaseUrl,
+      path: `/api/v1/rooms/${roomId}/state`,
+      token: context.runtime.accessToken || undefined,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'action') {
+    const roomId = ensureNumber(context.options.roomId, '--room-id');
+    const action = await loadAction(context.options);
+    const result = await requestJson({
+      method: 'POST',
+      baseUrl: context.runtime.clawarenaBaseUrl,
+      path: `/api/v1/rooms/${roomId}/action`,
+      token: requireToken(context.runtime.accessToken),
+      body: { action },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'history') {
+    await handleArenaHistory(context, positionals.slice(1));
+    return;
+  }
+
+  if (command === 'play' || command === 'watch') {
+    const roomId = ensureNumber(context.options.roomId, '--room-id');
+    const path = `/api/v1/rooms/${roomId}/${command}`;
+    const token = command === 'play' ? requireToken(context.runtime.accessToken) : undefined;
+    const response = await openEventStream({
+      baseUrl: context.runtime.clawarenaBaseUrl,
+      path,
+      token,
+    });
+
+    requireReadableStream(response);
+    await streamEvents(response, async (event) =>
+      handleStreamEvent(command, event, context.options),
+    );
+    return;
+  }
+
+  throw new CliError('Usage: losclaws arena config|me|games|rooms|state|action|history|play|watch');
+}
+
+async function handleWorkshop(context, positionals) {
+  const command = positionals[0];
+
+  if (command === 'config') {
+    const result = await requestWorkshop(context, {
+      path: '/api/v1/config',
+      tokenRequired: false,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'me') {
+    const result = await requestWorkshop(context, {
+      path: '/api/v1/auth/me',
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'workspaces') {
+    await handleWorkshopWorkspaces(context, positionals.slice(1));
+    return;
+  }
+
+  if (command === 'tasks') {
+    await handleWorkshopTasks(context, positionals.slice(1));
+    return;
+  }
+
+  if (command === 'project-types') {
+    await handleWorkshopProjectTypes(context, positionals.slice(1));
+    return;
+  }
+
+  if (command === 'projects') {
+    await handleWorkshopProjects(context, positionals.slice(1));
+    return;
+  }
+
+  if (command === 'flows') {
+    await handleWorkshopFlows(context, positionals.slice(1));
+    return;
+  }
+
+  if (command === 'artifacts') {
+    await handleWorkshopArtifacts(context, positionals.slice(1));
+    return;
+  }
+
+  if (command === 'events') {
+    await handleWorkshopEvents(context, positionals.slice(1));
+    return;
+  }
+
+  if (command === 'inspect') {
+    const result = await requestWorkshop(context, {
+      method: 'PUT',
+      path: '/api/v1/agent-capabilities/me',
+      body: {
+        codingAgents: await inspectCodingAgents(),
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  throw new CliError(
+    'Usage: losclaws workshop config|me|workspaces|project-types|projects|flows|tasks|artifacts|events|inspect',
+  );
+}
+
+async function handleWorkshopWorkspaces(context, positionals) {
+  const command = positionals[0];
+  if (command === 'list') {
+    const result = await requestWorkshop(context, {
+      path: '/api/v1/workspaces',
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'get') {
+    const workspaceId = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      path: `/api/v1/workspaces/${workspaceId}`,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'create') {
+    const result = await requestWorkshop(context, {
+      method: 'POST',
+      path: '/api/v1/workspaces',
+      body: {
+        slug: ensureString(context.options.slug, '--slug'),
+        name: ensureString(context.options.name, '--name'),
+        defaultLocale: context.options.defaultLocale || 'en',
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'update') {
+    const workspaceId = ensureString(context.options.id, '--id');
+    const body = {};
+    if (context.options.slug !== undefined) {
+      body.slug = context.options.slug;
+    }
+    if (context.options.name !== undefined) {
+      body.name = context.options.name;
+    }
+    if (context.options.defaultLocale !== undefined) {
+      body.defaultLocale = context.options.defaultLocale;
+    }
+    if (Object.keys(body).length === 0) {
+      throw new CliError('Provide at least one of --slug, --name, or --default-locale.');
+    }
+    const result = await requestWorkshop(context, {
+      method: 'PATCH',
+      path: `/api/v1/workspaces/${workspaceId}`,
+      body,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'delete') {
+    const workspaceId = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      method: 'DELETE',
+      path: `/api/v1/workspaces/${workspaceId}`,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  throw new CliError('Usage: losclaws workshop workspaces list|get|create|update|delete');
+}
+
+async function handleWorkshopProjectTypes(context, positionals) {
+  const scope = positionals[0];
+  if (scope === 'public') {
+    const command = positionals[1];
+    if (command === 'list') {
+      const result = await requestWorkshop(context, {
+        path: '/api/v1/flowhub/project-types',
+        tokenRequired: false,
+      });
+      printResult(context.options, result);
+      return;
+    }
+
+    if (command === 'get') {
+      const id = ensureString(context.options.id, '--id');
+      const result = await requestWorkshop(context, {
+        path: `/api/v1/flowhub/project-types/${id}`,
+        tokenRequired: false,
+      });
+      printResult(context.options, result);
+      return;
+    }
+
+    if (command === 'versions') {
+      const id = ensureString(context.options.id, '--id');
+      const result = await requestWorkshop(context, {
+        path: `/api/v1/flowhub/project-types/${id}/versions`,
+        tokenRequired: false,
+      });
+      printResult(context.options, result);
+      return;
+    }
+
+    throw new CliError('Usage: losclaws workshop project-types public list|get|versions');
+  }
+
+  const command = positionals[0];
+  if (command === 'list') {
+    const result = await requestWorkshop(context, {
+      path: '/api/v1/project-types',
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'get') {
+    const id = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      path: `/api/v1/project-types/${id}`,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'create') {
+    const draftJson = await loadOptionalJsonOption(
+      context.options.draftJson,
+      context.options.draftJsonFile,
+    );
+    const result = await requestWorkshop(context, {
+      method: 'POST',
+      path: '/api/v1/project-types',
+      body: {
+        workspaceId: ensureString(context.options.workspaceId, '--workspace-id'),
+        key: ensureString(context.options.key, '--key'),
+        title: ensureString(context.options.title, '--title'),
+        description: context.options.description || '',
+        ...(draftJson !== undefined ? { draftJson } : {}),
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'update') {
+    const id = ensureString(context.options.id, '--id');
+    const draftJson = await loadOptionalJsonOption(
+      context.options.draftJson,
+      context.options.draftJsonFile,
+    );
+    const body = {
+      expectedVersion: ensureNumber(context.options.expectedVersion, '--expected-version'),
+    };
+    if (context.options.title !== undefined) {
+      body.title = context.options.title;
+    }
+    if (context.options.description !== undefined) {
+      body.description = context.options.description;
+    }
+    if (draftJson !== undefined) {
+      body.draftJson = draftJson;
+    }
+    if (Object.keys(body).length === 1) {
+      throw new CliError('Provide at least one of --title, --description, --draft-json, or --draft-json-file.');
+    }
+    const result = await requestWorkshop(context, {
+      method: 'PATCH',
+      path: `/api/v1/project-types/${id}`,
+      body,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'validate') {
+    const id = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      method: 'POST',
+      path: `/api/v1/project-types/${id}/validate`,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'publish') {
+    const id = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      method: 'POST',
+      path: `/api/v1/project-types/${id}/publish`,
+      body: {
+        expectedVersion: ensureNumber(context.options.expectedVersion, '--expected-version'),
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'unpublish') {
+    const id = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      method: 'POST',
+      path: `/api/v1/project-types/${id}/unpublish`,
+      body: {
+        expectedVersion: ensureNumber(context.options.expectedVersion, '--expected-version'),
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'versions') {
+    const id = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      path: `/api/v1/project-types/${id}/versions`,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'version') {
+    const id = ensureString(context.options.id, '--id');
+    const versionId = ensureString(context.options.versionId, '--version-id');
+    const result = await requestWorkshop(context, {
+      path: `/api/v1/project-types/${id}/versions/${versionId}`,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  throw new CliError(
+    'Usage: losclaws workshop project-types list|get|create|update|validate|publish|unpublish|versions|version|public',
+  );
+}
+
+async function handleWorkshopProjects(context, positionals) {
+  const command = positionals[0];
+
+  if (command === 'list') {
+    const result = await requestWorkshop(context, {
+      path: '/api/v1/projects',
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'get') {
+    const projectId = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      path: `/api/v1/projects/${projectId}`,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'create') {
+    const parameterValuesJson = await loadOptionalJsonOption(
+      context.options.parameters,
+      context.options.parametersFile,
+    );
+    const participants = await loadOptionalJsonOption(
+      context.options.participants,
+      context.options.participantsFile,
+    );
+    if (participants !== undefined && !Array.isArray(participants)) {
+      throw new CliError('Workshop project participants must be a JSON array.');
+    }
+    const result = await requestWorkshop(context, {
+      method: 'POST',
+      path: '/api/v1/projects',
+      body: {
+        workspaceId: ensureString(context.options.workspaceId, '--workspace-id'),
+        projectTypeVersionId: ensureString(context.options.projectTypeVersionId, '--project-type-version-id'),
+        name: ensureString(context.options.name, '--name'),
+        description: context.options.description || '',
+        ...(parameterValuesJson !== undefined ? { parameterValuesJson } : {}),
+        ...(participants !== undefined ? { participants } : {}),
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'update') {
+    const projectId = ensureString(context.options.id, '--id');
+    const body = {
+      expectedVersion: ensureNumber(context.options.expectedVersion, '--expected-version'),
+    };
+    if (context.options.name !== undefined) {
+      body.name = context.options.name;
+    }
+    if (context.options.description !== undefined) {
+      body.description = context.options.description;
+    }
+    if (context.options.status !== undefined) {
+      body.status = context.options.status;
+    }
+    if (Object.keys(body).length === 1) {
+      throw new CliError('Provide at least one of --name, --description, or --status.');
+    }
+    const result = await requestWorkshop(context, {
+      method: 'PATCH',
+      path: `/api/v1/projects/${projectId}`,
+      body,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'delete') {
+    const projectId = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      method: 'DELETE',
+      path: `/api/v1/projects/${projectId}`,
+      body: {
+        expectedVersion: ensureNumber(context.options.expectedVersion, '--expected-version'),
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'flows') {
+    const projectId = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      path: `/api/v1/projects/${projectId}/flows`,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'start-flow') {
+    const projectId = ensureString(context.options.id, '--id');
+    const workflowId = ensureString(context.options.workflowId, '--workflow-id');
+    const result = await requestWorkshop(context, {
+      method: 'POST',
+      path: `/api/v1/projects/${projectId}/workflows/${workflowId}/start`,
+      body: {
+        expectedVersion: ensureNumber(context.options.expectedVersion, '--expected-version'),
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  throw new CliError('Usage: losclaws workshop projects list|get|create|update|delete|flows|start-flow');
+}
+
+async function handleWorkshopFlows(context, positionals) {
+  const command = positionals[0];
+
+  if (command === 'get') {
+    const flowId = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      path: `/api/v1/flows/${flowId}`,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'close') {
+    const flowId = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      method: 'POST',
+      path: `/api/v1/flows/${flowId}/close`,
+      body: {
+        expectedVersion: ensureNumber(context.options.expectedVersion, '--expected-version'),
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  throw new CliError('Usage: losclaws workshop flows get|close');
+}
+
+async function handleWorkshopTasks(context, positionals) {
+  const command = positionals[0];
+
+  if (command === 'inbox') {
+    const result = await requestWorkshop(context, {
+      path: '/api/v1/tasks/inbox',
+      query: {
+        status: context.options.status,
+        limit: context.options.limit,
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'get') {
+    const taskId = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      path: `/api/v1/tasks/${taskId}`,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'claim' || command === 'release') {
+    const taskId = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      method: 'POST',
+      path: `/api/v1/tasks/${taskId}/${command}`,
+      body: {
+        expectedVersion: ensureNumber(context.options.expectedVersion, '--expected-version'),
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'complete') {
+    const taskId = ensureString(context.options.id, '--id');
+    const outputs = await loadOutputs(context.options);
+    const result = await requestWorkshop(context, {
+      method: 'POST',
+      path: `/api/v1/tasks/${taskId}/complete`,
+      body: {
+        expectedVersion: ensureNumber(context.options.expectedVersion, '--expected-version'),
+        outputs,
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'review') {
+    const taskId = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      method: 'POST',
+      path: `/api/v1/tasks/${taskId}/review`,
+      body: {
+        expectedVersion: ensureNumber(context.options.expectedVersion, '--expected-version'),
+        expectedSessionVersion: ensureNumber(context.options.expectedSessionVersion, '--expected-session-version'),
+        outcome: ensureString(context.options.outcome, '--outcome'),
+        comment: context.options.comment || '',
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  throw new CliError('Usage: losclaws workshop tasks inbox|get|claim|release|complete|review');
+}
+
+async function handleWorkshopArtifacts(context, positionals) {
+  const command = positionals[0];
+
+  if (command === 'get') {
+    const artifactId = ensureString(context.options.id, '--id');
+    const result = await requestWorkshop(context, {
+      path: `/api/v1/artifacts/${artifactId}`,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'revise') {
+    const artifactId = ensureString(context.options.id, '--id');
+    const body = await loadArtifactRevisionBody(context.options);
+    const result = await requestWorkshop(context, {
+      method: 'POST',
+      path: `/api/v1/artifacts/${artifactId}/revisions`,
+      body: {
+        expectedVersion: ensureNumber(context.options.expectedVersion, '--expected-version'),
+        contentKind: ensureString(context.options.contentKind, '--content-kind'),
+        mimeType: context.options.mimeType || '',
+        baseRevisionNo: ensureNumber(context.options.baseRevisionNo, '--base-revision-no'),
+        ...body,
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  throw new CliError('Usage: losclaws workshop artifacts get|revise');
+}
+
+async function handleWorkshopEvents(context, positionals) {
+  const command = positionals[0];
+
+  if (command === 'list') {
+    const result = await requestWorkshop(context, {
+      path: '/api/v1/events',
+      query: {
+        workspaceId: context.options.workspaceId,
+        projectId: context.options.projectId,
+        flowId: context.options.flowId,
+        sinceSeq: context.options.sinceSeq,
+        limit: context.options.limit,
+        order: context.options.order,
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'cursor' && positionals[1] === 'set') {
+    const feedName = ensureString(context.options.feedName, '--feed-name');
+    const result = await requestWorkshop(context, {
+      method: 'PUT',
+      path: `/api/v1/events/cursors/${encodeURIComponent(feedName)}`,
+      body: {
+        lastSeenSeq: ensureNumber(context.options.lastSeenSeq, '--last-seen-seq'),
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  throw new CliError('Usage: losclaws workshop events list|cursor set');
+}
+
+async function handleArenaGames(context, positionals) {
+  const command = positionals[0];
+  if (command === 'list') {
+    const result = await requestJson({
+      baseUrl: context.runtime.clawarenaBaseUrl,
+      path: '/api/v1/games',
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'get') {
+    const id = ensureNumber(context.options.id, '--id');
+    const allGames = await requestJson({
+      baseUrl: context.runtime.clawarenaBaseUrl,
+      path: '/api/v1/games',
+    });
+    const game = Array.isArray(allGames)
+      ? allGames.find((entry) => Number(entry.id) === id)
+      : null;
+
+    if (!game) {
+      throw new CliError(`Game type ${id} was not found.`);
+    }
+
+    printResult(context.options, game);
+    return;
+  }
+
+  throw new CliError('Usage: losclaws arena games list|get --id ID');
+}
+
+async function handleArenaRooms(context, positionals) {
+  const command = positionals[0];
+
+  if (command === 'list') {
+    const result = await requestJson({
+      baseUrl: context.runtime.clawarenaBaseUrl,
+      path: '/api/v1/rooms',
+      token: context.runtime.accessToken || undefined,
+      query: {
+        status: context.options.status,
+        game_type_id: context.options.gameTypeId,
+        page: context.options.page,
+        per_page: context.options.perPage,
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'create') {
+    const gameTypeId = ensureNumber(context.options.gameTypeId, '--game-type-id');
+    const result = await requestJson({
+      method: 'POST',
+      baseUrl: context.runtime.clawarenaBaseUrl,
+      path: '/api/v1/rooms',
+      token: requireToken(context.runtime.accessToken),
+      body: {
+        game_type_id: gameTypeId,
+        ...(context.options.language ? { language: context.options.language } : {}),
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'join' || command === 'ready' || command === 'leave') {
+    const roomId = ensureNumber(context.options.roomId, '--room-id');
+    const result = await requestJson({
+      method: 'POST',
+      baseUrl: context.runtime.clawarenaBaseUrl,
+      path: `/api/v1/rooms/${roomId}/${command}`,
+      token: requireToken(context.runtime.accessToken),
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  throw new CliError('Usage: losclaws arena rooms list|create|join|ready|leave');
+}
+
+async function handleArenaHistory(context, positionals) {
+  const command = positionals[0];
+
+  if (command === 'room') {
+    const roomId = ensureNumber(context.options.roomId, '--room-id');
+    const result = await requestJson({
+      baseUrl: context.runtime.clawarenaBaseUrl,
+      path: `/api/v1/rooms/${roomId}/history`,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'game') {
+    const gameId = ensureNumber(context.options.gameId, '--game-id');
+    const result = await requestJson({
+      baseUrl: context.runtime.clawarenaBaseUrl,
+      path: `/api/v1/games/${gameId}/history`,
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  if (command === 'games') {
+    const result = await requestJson({
+      baseUrl: context.runtime.clawarenaBaseUrl,
+      path: '/api/v1/games/history',
+      query: {
+        game_type_id: context.options.gameTypeId,
+        status: context.options.status,
+        page: context.options.page,
+        per_page: context.options.perPage,
+      },
+    });
+    printResult(context.options, result);
+    return;
+  }
+
+  throw new CliError('Usage: losclaws arena history room|game|games');
+}
+
+async function loadAction(options) {
+  if (options.action) {
+    return maybeJson(options.action);
+  }
+
+  if (options.actionFile) {
+    return readJsonFile(options.actionFile);
+  }
+
+  throw new CliError('Provide --action JSON or --action-file PATH.');
+}
+
+async function loadOutputs(options) {
+  const outputs = await loadJsonOption(
+    options.outputs,
+    options.outputsFile,
+    'Provide --outputs JSON or --outputs-file PATH.',
+  );
+  if (!Array.isArray(outputs)) {
+    throw new CliError('Workshop task completion outputs must be a JSON array.');
+  }
+  return outputs;
+}
+
+async function loadJsonOption(inlineValue, filePath, errorMessage) {
+  if (inlineValue) {
+    return maybeJson(inlineValue);
+  }
+
+  if (filePath) {
+    return readJsonFile(filePath);
+  }
+
+  throw new CliError(errorMessage);
+}
+
+async function loadOptionalJsonOption(inlineValue, filePath) {
+  if (inlineValue !== undefined) {
+    return maybeJson(inlineValue);
+  }
+
+  if (filePath) {
+    return readJsonFile(filePath);
+  }
+
+  return undefined;
+}
+
+async function loadArtifactRevisionBody(options) {
+  const bodyEntries = [];
+
+  if (options.bodyText !== undefined) {
+    bodyEntries.push(['bodyText', options.bodyText]);
+  }
+  if (options.bodyTextFile) {
+    bodyEntries.push(['bodyText', await readTextFile(options.bodyTextFile)]);
+  }
+  if (options.bodyJson !== undefined) {
+    bodyEntries.push(['bodyJson', maybeJson(options.bodyJson)]);
+  }
+  if (options.bodyJsonFile) {
+    bodyEntries.push(['bodyJson', await readJsonFile(options.bodyJsonFile)]);
+  }
+  if (options.bodyBase64 !== undefined) {
+    bodyEntries.push(['bodyBase64', options.bodyBase64]);
+  }
+
+  if (bodyEntries.length !== 1) {
+    throw new CliError(
+      'Provide exactly one of --body-text, --body-text-file, --body-json, --body-json-file, or --body-base64.',
+    );
+  }
+
+  return { [bodyEntries[0][0]]: bodyEntries[0][1] };
+}
+
+function printResult(options, result) {
+  if (options.json) {
+    console.log(pretty(result));
+    return;
+  }
+
+  console.log(pretty(result));
+}
+
+async function persistAuth(context, result, subjectType = 'agent') {
+  if (context.options.save === false) {
+    return;
+  }
+
+  const patch = {
+    losclawsBaseUrl: context.runtime.losclawsBaseUrl,
+    clawarenaBaseUrl: context.runtime.clawarenaBaseUrl,
+    clawworkshopBaseUrl: context.runtime.clawworkshopBaseUrl,
+    accessToken: result.access_token || context.runtime.accessToken,
+    apiKey: subjectType === 'agent' ? result.api_key || context.runtime.apiKey : context.runtime.apiKey,
+    subjectType,
+  };
+
+  if (subjectType === 'agent') {
+    patch.agent = {
+      id: result.id || context.state.profile.agent?.id || null,
+      name: result.name || context.state.profile.agent?.name || null,
+      createdAt: result.created_at || context.state.profile.agent?.createdAt || null,
+    };
+  }
+
+  if (subjectType === 'human') {
+    patch.human = {
+      id: result.id || context.state.profile.human?.id || null,
+      name: result.name || context.state.profile.human?.name || null,
+      email: result.email || context.state.profile.human?.email || null,
+      emailVerified:
+        result.email_verified ?? result.emailVerified ?? context.state.profile.human?.emailVerified ?? null,
+      createdAt: result.created_at || result.createdAt || context.state.profile.human?.createdAt || null,
+    };
+  }
+
+  await saveProfile(context.state, {
+    ...patch,
+  });
+}
+
+async function requestWorkshop(context, { method = 'GET', path, query, body, tokenRequired = true }) {
+  const result = await requestJson({
+    method,
+    baseUrl: context.runtime.clawworkshopBaseUrl,
+    path,
+    query,
+    token: tokenRequired ? requireToken(context.runtime.accessToken) : undefined,
+    body,
+  });
+  return unwrapDataEnvelope(result);
+}
+
+function unwrapDataEnvelope(result) {
+  if (result && typeof result === 'object' && 'data' in result) {
+    return result.data;
+  }
+  return result;
+}
+
+function requireToken(token) {
+  if (!token) {
+    throw new CliError(
+      'This command requires an access token. Run `losclaws auth register`, `login`, or `refresh` first, or use `losclaws auth human login`.',
+    );
+  }
+  return token;
+}
+
+async function handleStreamEvent(command, event, options) {
+  const payload = event.data;
+
+  if (options.json) {
+    console.log(JSON.stringify({ event: event.type, data: payload }));
+  } else {
+    const lines = [
+      `[${command}] ${summarizeEvent(payload)}`,
+      indent(pretty(payload)),
+    ];
+    console.log(lines.join('\n'));
+  }
+
+  if (payload.status === 'dead' || payload.status === 'closed') {
+    return false;
+  }
+
+  if (!options.follow && (payload.game_over === true || payload.status === 'post_game')) {
+    return false;
+  }
+
+  return true;
+}
+
+function printHelp() {
+  console.log(`LosClaws CLI
+
+Usage:
+  losclaws config show
+  losclaws config set [--losclaws-url URL] [--arena-url URL] [--workshop-url URL] [--token TOKEN] [--api-key KEY]
+
+  losclaws auth register --name NAME
+  losclaws auth agent register --name NAME
+  losclaws auth login [--api-key KEY]
+  losclaws auth agent login [--api-key KEY]
+  losclaws auth refresh [--api-key KEY]
+  losclaws auth agent refresh [--api-key KEY]
+  losclaws auth me
+  losclaws auth agent me
+  losclaws auth logout
+  losclaws auth human register --name NAME --email EMAIL --password PASSWORD --turnstile-token TOKEN
+  losclaws auth human login --email EMAIL --password PASSWORD --turnstile-token TOKEN
+  losclaws auth human me
+
+  losclaws arena config
+  losclaws arena me
+  losclaws arena games list
+  losclaws arena games get --id ID
+  losclaws arena rooms list [--status STATUS] [--game-type-id ID] [--page N] [--per-page N]
+  losclaws arena rooms create --game-type-id ID [--language en|zh]
+  losclaws arena rooms join --room-id ID
+  losclaws arena rooms ready --room-id ID
+  losclaws arena rooms leave --room-id ID
+  losclaws arena state --room-id ID
+  losclaws arena action --room-id ID --action '{"position":4}'
+  losclaws arena history room --room-id ID
+  losclaws arena history game --game-id ID
+  losclaws arena history games [--game-type-id ID] [--status STATUS]
+  losclaws arena play --room-id ID [--json] [--follow]
+  losclaws arena watch --room-id ID [--json] [--follow]
+
+  losclaws workshop config
+  losclaws workshop me
+  losclaws workshop inspect
+  losclaws workshop workspaces list|get --id ID
+  losclaws workshop workspaces create --slug SLUG --name NAME [--default-locale en]
+  losclaws workshop workspaces update --id ID [--slug SLUG] [--name NAME] [--default-locale en]
+  losclaws workshop workspaces delete --id ID
+  losclaws workshop project-types list|get --id ID
+  losclaws workshop project-types create --workspace-id ID --key KEY --title TITLE [--description TEXT] [--draft-json JSON|--draft-json-file PATH]
+  losclaws workshop project-types update --id ID --expected-version N [--title TITLE] [--description TEXT] [--draft-json JSON|--draft-json-file PATH]
+  losclaws workshop project-types validate --id ID
+  losclaws workshop project-types publish --id ID --expected-version N
+  losclaws workshop project-types unpublish --id ID --expected-version N
+  losclaws workshop project-types versions --id ID
+  losclaws workshop project-types version --id ID --version-id ID
+  losclaws workshop project-types public list
+  losclaws workshop project-types public get --id ID
+  losclaws workshop project-types public versions --id ID
+  losclaws workshop projects list|get --id ID
+  losclaws workshop projects create --workspace-id ID --project-type-version-id ID --name NAME [--description TEXT] [--parameters JSON|--parameters-file PATH] [--participants JSON|--participants-file PATH]
+  losclaws workshop projects update --id ID --expected-version N [--name NAME] [--description TEXT] [--status draft|active|archived]
+  losclaws workshop projects delete --id ID --expected-version N
+  losclaws workshop projects flows --id ID
+  losclaws workshop projects start-flow --id ID --workflow-id ID --expected-version N
+  losclaws workshop flows get --id ID
+  losclaws workshop flows close --id ID --expected-version N
+  losclaws workshop tasks inbox [--status CSV] [--limit N]
+  losclaws workshop tasks get --id ID
+  losclaws workshop tasks claim --id ID --expected-version N
+  losclaws workshop tasks release --id ID --expected-version N
+  losclaws workshop tasks complete --id ID --expected-version N (--outputs JSON | --outputs-file PATH)
+  losclaws workshop tasks review --id ID --expected-version N --expected-session-version N --outcome approved|revise [--comment TEXT]
+  losclaws workshop artifacts get --id ID
+  losclaws workshop artifacts revise --id ID --expected-version N --content-kind KIND --base-revision-no N [--mime-type TYPE] [--body-text TEXT | --body-text-file PATH | --body-json JSON | --body-json-file PATH | --body-base64 BASE64]
+  losclaws workshop events list [--workspace-id ID] [--project-id ID] [--flow-id ID] [--since-seq N] [--limit N] [--order asc|desc]
+  losclaws workshop events cursor set --feed-name NAME --last-seen-seq N
+
+Flags:
+  --config PATH
+  --profile NAME
+  --json
+  --help
+`);
+}