@fitlab-ai/agent-infra 0.9.1 → 0.9.3

package/lib/init.ts

@@ -8,13 +8,13 @@ import { resolveTemplateDir } from './paths.ts';
 import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.ts';
 import { enginesForPlatform } from './sandbox/engines/index.ts';
 import { VERSION } from './version.ts';
+import { listAgentClientAdapters } from './agent-clients/registry.ts';
+import { serializeAgentClients } from './agent-clients/config.ts';
 import {
-  BUILTIN_TUI_IDS,
-  BUILTIN_TUI_DISPLAY,
-  isPathOwnedByDisabledTUI,
-  resolveEnabledTUIs
-} from './builtin-tuis.ts';
-import type { BuiltinTUIId } from './builtin-tuis.ts';
+  applyAgentClientReconciliation,
+  planAgentClientReconciliation
+} from './agent-clients/reconcile.ts';
+import type { AgentClientState } from './agent-clients/types.ts';
 
 type FileRegistry = {
   managed: string[];
@@ -28,6 +28,7 @@ type SourceEntry = {
 };
 
 type Defaults = {
+  agentClients: AgentConfig['agentClients'];
   files: FileRegistry;
   sandbox: Record<string, unknown>;
   task: { shortIdLength: number };
@@ -44,7 +45,7 @@ type AgentConfig = {
   task: { shortIdLength: number };
   labels: Record<string, unknown>;
   files: FileRegistry;
-  tuis: string[];
+  agentClients: ReturnType<typeof serializeAgentClients>;
   templates?: { sources: SourceEntry[] };
   skills?: { sources: SourceEntry[] };
 };
@@ -59,28 +60,6 @@ const PLATFORM_DEFAULT_ENGINES = Object.freeze({
   win32: 'wsl2'
 });
 
-function isPathOwnedByOtherPlatform(relativePath: string, platformType: string): boolean {
-  const top = String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '').split('/')[0] ?? '';
-  if (!top.startsWith('.')) return false;
-
-  const candidate = top.slice(1);
-  if (!KNOWN_PLATFORMS.has(candidate)) return false;
-  return candidate !== platformType;
-}
-
-function buildDefaultFiles(platformType: string, enabledTUIs: Set<BuiltinTUIId>): FileRegistry {
-  const ownedByDisabled = (entry: string) => isPathOwnedByDisabledTUI(entry, enabledTUIs);
-  return {
-    managed: (defaults.files.managed || []).filter(
-      (entry) => !isPathOwnedByOtherPlatform(entry, platformType) && !ownedByDisabled(entry)
-    ),
-    merged: (defaults.files.merged || []).filter(
-      (entry) => !isPathOwnedByOtherPlatform(entry, platformType) && !ownedByDisabled(entry)
-    ),
-    ejected: structuredClone(defaults.files.ejected || [])
-  };
-}
-
 function detectProjectName(): string {
   try {
     const url = execSync('git remote get-url origin', { stdio: ['pipe', 'pipe', 'pipe'] })
@@ -222,11 +201,12 @@ async function cmdInit(): Promise<void> {
     );
   }
 
-  let enabledTUIs: string[];
+  const adapters = listAgentClientAdapters();
+  let enabledClientIds: string[];
   try {
-    enabledTUIs = await multiSelect(
-      'Built-in TUI command files to install/manage',
-      BUILTIN_TUI_IDS.map((id) => ({ id, label: BUILTIN_TUI_DISPLAY[id] }))
+    enabledClientIds = await multiSelect(
+      'Agent Client project integrations to enable',
+      adapters.map((adapter) => ({ id: adapter.id, label: adapter.displayName }))
     );
   } catch (e) {
     err(e instanceof Error ? e.message : String(e));
@@ -234,7 +214,7 @@ async function cmdInit(): Promise<void> {
     process.exitCode = 1;
     return;
   }
-  const enabledTUISet = resolveEnabledTUIs(enabledTUIs);
+  const enabledClientSet = new Set(enabledClientIds);
 
   const templateSources = parseLocalSources(await prompt(
     'Template sources (optional, comma-separated local paths, e.g. ~/my-templates; Enter to skip)',
@@ -249,6 +229,39 @@ async function cmdInit(): Promise<void> {
   const project = projectName;
   const replacements = { project, org: orgName };
 
+  const defaultState = Object.fromEntries(defaults.agentClients.map((entry) => [
+    entry.id,
+    {
+      enabled: enabledClientSet.has(entry.id),
+      installInSandbox: entry.installInSandbox
+    }
+  ])) as AgentClientState;
+  const config: AgentConfig = {
+    project: projectName,
+    org: orgName,
+    language,
+    platform: { type: platformType },
+    templateVersion: VERSION,
+    sandbox: structuredClone(defaults.sandbox),
+    task: structuredClone(defaults.task),
+    labels: structuredClone(defaults.labels),
+    files: { managed: [], merged: [], ejected: [] },
+    agentClients: serializeAgentClients(defaultState)
+  };
+
+  if (sandboxEngine) config.sandbox.engine = sandboxEngine;
+  if (templateSources.length > 0) config.templates = { sources: templateSources };
+  if (skillSources.length > 0) config.skills = { sources: skillSources };
+
+  const workflowPlan = planAgentClientReconciliation({
+    config: config as unknown as Record<string, unknown>,
+    mutation: { type: 'none' },
+    projectRoot: process.cwd(),
+    templateRoot: templateDir,
+    platformType,
+    language
+  });
+
   console.log('');
   if (orgName) {
     info(`Installing update-agent-infra seed command for: ${projectName} (${orgName})`);
@@ -257,18 +270,6 @@ async function cmdInit(): Promise<void> {
   }
   console.log('');
 
-  // select language-specific template filenames
-  let claudeSrc, geminiSrc, opencodeSrc;
-  if (language === 'zh-CN') {
-    claudeSrc = 'update-agent-infra.zh-CN.md';
-    geminiSrc = 'update-agent-infra.zh-CN.toml';
-    opencodeSrc = 'update-agent-infra.zh-CN.md';
-  } else {
-    claudeSrc = 'update-agent-infra.en.md';
-    geminiSrc = 'update-agent-infra.en.toml';
-    opencodeSrc = 'update-agent-infra.en.md';
-  }
-
   // install skill
   copySkillDir(
     path.join(templateDir, '.agents', 'skills', 'update-agent-infra'),
@@ -285,68 +286,8 @@ async function cmdInit(): Promise<void> {
   );
   ok('Installed .agents/scripts/lib/agent-infra-package.js');
 
-  // install Claude command (only if enabled)
-  if (enabledTUISet.has('claude-code')) {
-    renderFile(
-      path.join(templateDir, '.claude', 'commands', claudeSrc),
-      path.join('.claude', 'commands', 'update-agent-infra.md'),
-      replacements
-    );
-    ok('Installed .claude/commands/update-agent-infra.md');
-  }
-
-  // install Gemini command (only if enabled)
-  if (enabledTUISet.has('gemini-cli')) {
-    renderFile(
-      path.join(templateDir, '.gemini', 'commands', '_project_', geminiSrc),
-      path.join('.gemini', 'commands', project, 'update-agent-infra.toml'),
-      replacements
-    );
-    ok(`Installed .gemini/commands/${project}/update-agent-infra.toml`);
-  }
-
-  // install OpenCode command (only if enabled)
-  if (enabledTUISet.has('opencode')) {
-    renderFile(
-      path.join(templateDir, '.opencode', 'commands', opencodeSrc),
-      path.join('.opencode', 'commands', 'update-agent-infra.md'),
-      replacements
-    );
-    ok('Installed .opencode/commands/update-agent-infra.md');
-  }
-
-  // generate .agents/.airc.json
-  const config: AgentConfig = {
-    project: projectName,
-    org: orgName,
-    language,
-    platform: { type: platformType },
-    templateVersion: VERSION,
-    sandbox: structuredClone(defaults.sandbox),
-    task: structuredClone(defaults.task),
-    labels: structuredClone(defaults.labels),
-    files: buildDefaultFiles(platformType, enabledTUISet),
-    tuis: enabledTUIs
-  };
-
-  if (sandboxEngine) {
-    config.sandbox.engine = sandboxEngine;
-  }
-
-  if (templateSources.length > 0) {
-    config.templates = {
-      sources: templateSources
-    };
-  }
-
-  if (skillSources.length > 0) {
-    config.skills = {
-      sources: skillSources
-    };
-  }
-
-  fs.mkdirSync(path.dirname(configPath), { recursive: true });
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  const reconcileResult = applyAgentClientReconciliation(workflowPlan);
+  for (const target of reconcileResult.applied) ok(`Installed ${target}`);
   ok(`Generated ${configPath}`);
 
   // done
@@ -356,24 +297,15 @@ async function cmdInit(): Promise<void> {
   console.log('  If this init used npx, install agent-infra persistently before update or validation:');
   console.log('    npm install -g @fitlab-ai/agent-infra');
   console.log('');
-  if (enabledTUISet.size === 0) {
-    console.log('  No built-in TUI selected.');
+  if (workflowPlan.nextSteps.length === 0) {
+    console.log('  No Agent Client project integration enabled.');
     console.log(`  Configure "customTUIs" in ${configPath} before running update-agent-infra.`);
     console.log('');
   } else {
     console.log('  Next step: open this project in any AI TUI and run:');
     console.log('');
-    const claudeOrOpencode: string[] = [];
-    if (enabledTUISet.has('claude-code')) claudeOrOpencode.push('Claude Code');
-    if (enabledTUISet.has('opencode')) claudeOrOpencode.push('OpenCode');
-    if (claudeOrOpencode.length > 0) {
-      console.log(`    ${claudeOrOpencode.join(' / ')}:  /update-agent-infra`);
-    }
-    if (enabledTUISet.has('gemini-cli')) {
-      console.log(`    Gemini CLI:              /${project}:update-agent-infra`);
-    }
-    if (enabledTUISet.has('codex')) {
-      console.log('    Codex CLI:               $update-agent-infra');
+    for (const nextStep of workflowPlan.nextSteps) {
+      console.log(`    ${nextStep.displayName}: ${nextStep.command}`);
     }
     console.log('');
     console.log('  This will render all templates and set up the full');

package/lib/internal/agent-client.ts

@@ -0,0 +1,186 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  AgentClientConfigError,
+  normalizeAgentClients
+} from '../agent-clients/config.ts';
+import { normalizeCustomTUIs } from '../agent-clients/custom-tuis.ts';
+import { renderNextStepCommands } from '../agent-clients/next-steps.ts';
+import { getAgentClientModelSelection } from '../agent-clients/registry.ts';
+import { isAgentClientId } from '../agent-clients/types.ts';
+
+const USAGE = 'Usage: agent-infra-internal agent-client <next-steps|model-selection> [options]\n';
+
+type ParsedArgs = Readonly<{
+  skillName: string;
+  taskRef?: string;
+  version?: string;
+  format: 'text' | 'json';
+}>;
+
+function failure(code: string, message: string): void {
+  process.stdout.write(`${JSON.stringify({
+    status: 'failed',
+    changed: false,
+    commands: [],
+    diagnostics: [],
+    error: { code, message }
+  })}\n`);
+  process.exitCode = 1;
+}
+
+function parseArgs(args: string[]): ParsedArgs | null {
+  if (args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    return null;
+  }
+  if (args[0] !== 'next-steps') {
+    failure('AGENT_CLIENT_PAYLOAD_INVALID', "operation must be 'next-steps'");
+    return null;
+  }
+  let skillName: string | undefined;
+  let taskRef: string | undefined;
+  let version: string | undefined;
+  let format: 'text' | 'json' = 'text';
+  const seen = new Set<string>();
+  for (let index = 1; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!['--skill', '--task-ref', '--version', '--format'].includes(flag)) {
+      failure('AGENT_CLIENT_PAYLOAD_INVALID', `unknown option '${flag}'`);
+      return null;
+    }
+    if (seen.has(flag)) {
+      failure('AGENT_CLIENT_PAYLOAD_INVALID', `duplicate option '${flag}'`);
+      return null;
+    }
+    const value = args[++index];
+    if (!value || value.startsWith('--')) {
+      failure('AGENT_CLIENT_PAYLOAD_INVALID', `option '${flag}' requires a value`);
+      return null;
+    }
+    seen.add(flag);
+    if (flag === '--skill') skillName = value;
+    if (flag === '--task-ref') taskRef = value;
+    if (flag === '--version') version = value;
+    if (flag === '--format') {
+      if (value !== 'text' && value !== 'json') {
+        failure('AGENT_CLIENT_PAYLOAD_INVALID', "format must be 'text' or 'json'");
+        return null;
+      }
+      format = value;
+    }
+  }
+  if (!skillName) {
+    failure('AGENT_CLIENT_PAYLOAD_INVALID', "option '--skill' is required");
+    return null;
+  }
+  return {
+    skillName,
+    ...(taskRef ? { taskRef } : {}),
+    ...(version ? { version } : {}),
+    format
+  };
+}
+
+function agentClient(args: string[] = []): void {
+  if (args[0] === 'model-selection') {
+    const values: Record<string, string> = {};
+    const seen = new Set<string>();
+    for (let index = 1; index < args.length; index += 1) {
+      const flag = args[index]!;
+      if (!['--client', '--format'].includes(flag) || seen.has(flag)) {
+        failure('AGENT_CLIENT_PAYLOAD_INVALID', `invalid or duplicate option '${flag}'`);
+        return;
+      }
+      const value = args[++index];
+      if (!value || value.startsWith('--')) {
+        failure('AGENT_CLIENT_PAYLOAD_INVALID', `option '${flag}' requires a value`);
+        return;
+      }
+      seen.add(flag);
+      values[flag] = value;
+    }
+    const client = values['--client'];
+    const format = values['--format'] ?? 'text';
+    if (!isAgentClientId(client) || !['text', 'json'].includes(format)) {
+      failure('AGENT_CLIENT_PAYLOAD_INVALID', 'model-selection requires a known --client and text|json format');
+      return;
+    }
+    const context = getAgentClientModelSelection(client);
+    if (format === 'json') {
+      process.stdout.write(`${JSON.stringify({
+        status: 'resolved', changed: false, client, context, error: null
+      })}\n`);
+      return;
+    }
+    if (context.kind === 'interactive-only') {
+      process.stdout.write(`Model selection: interactive-only\nCommand: ${context.command}\n${context.guidance}\n`);
+    } else {
+      process.stdout.write(`Model selection: ${context.completeness} catalog\nSource: ${context.source}\n`);
+      for (const model of context.models) {
+        const efforts = model.reasoningEfforts?.length
+          ? ` (${model.reasoningEfforts.join(', ')})`
+          : '';
+        process.stdout.write(`- ${model.id}${efforts}\n`);
+      }
+      if (context.guidance) process.stdout.write(`${context.guidance}\n`);
+    }
+    return;
+  }
+  const parsed = parseArgs(args);
+  if (!parsed || process.exitCode) return;
+
+  let config: Record<string, unknown>;
+  try {
+    const configPath = path.join(process.cwd(), '.agents', '.airc.json');
+    const raw = JSON.parse(fs.readFileSync(configPath, 'utf8')) as unknown;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+      throw new Error('configuration root must be an object');
+    }
+    config = raw as Record<string, unknown>;
+  } catch (error) {
+    failure('AGENT_CLIENT_CONFIG_INVALID', String(error));
+    return;
+  }
+
+  try {
+    const clients = normalizeAgentClients(config);
+    const custom = normalizeCustomTUIs(process.cwd(), config.customTUIs ?? []);
+    const commands = renderNextStepCommands({
+      projectName: String(config.project ?? ''),
+      state: clients.state,
+      customTUIs: custom.items,
+      skillName: parsed.skillName,
+      ...(parsed.taskRef ? { taskRef: parsed.taskRef } : {}),
+      ...(parsed.version ? { version: parsed.version } : {})
+    });
+    if (parsed.format === 'json') {
+      process.stdout.write(`${JSON.stringify({
+        status: 'rendered',
+        changed: false,
+        commands,
+        diagnostics: custom.diagnostics,
+        error: null
+      })}\n`);
+      return;
+    }
+    for (const command of commands) {
+      process.stdout.write(`  - ${command.displayName}: ${command.command}\n`);
+    }
+    for (const diagnostic of custom.diagnostics) {
+      process.stderr.write(`${diagnostic.code} at ${diagnostic.path}\n`);
+    }
+  } catch (error) {
+    if (error instanceof AgentClientConfigError) {
+      failure(error.code, error.message);
+      return;
+    }
+    failure(
+      'AGENT_CLIENT_RENDER_INVALID',
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+}
+
+export { agentClient };

package/lib/internal/git-workflow.ts

@@ -1,5 +1,5 @@
 import fs from 'node:fs';
-import { commitExplicitPaths, inspectGitWorkflow, pushGitRefs } from '../git/workflow.ts';
+import { commitExplicitPaths, inspectGitWorkflow, pushGitRefs, pushRebasedBranch } from '../git/workflow.ts';
 import { compareReviewTrees, snapshotReview } from '../git/review-snapshot.ts';
 import { resolvePostReviewGlobs } from '../task/review-fingerprint.ts';
 
@@ -23,11 +23,15 @@ function gitWorkflow(args: string[] = []): void {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
     result = input ? pushGitRefs({ cwd: cwd ?? process.cwd(), ...input }) : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
+  } else if (action === 'push-rebased') {
+    const inputIndex = rest.indexOf('--input');
+    const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
+    result = input ? pushRebasedBranch({ cwd: cwd ?? process.cwd(), ...input }) : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
   } else if (action === 'snapshot' || action === 'compare-trees') {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
     if (!input) result = { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
-    else if (action === 'snapshot') result = { status: 'no-op', changed: false, snapshot: snapshotReview({ cwd: cwd ?? process.cwd(), mode: input.mode, baseline: input.baseline, globs: input.globs ?? resolvePostReviewGlobs({}, {}) }), error: null };
+    else if (action === 'snapshot') result = { status: 'no-op', changed: false, snapshot: snapshotReview({ cwd: cwd ?? process.cwd(), mode: input.mode, baseline: input.baseline, diffBase: input.diffBase, globs: input.globs ?? resolvePostReviewGlobs({}, {}) }), error: null };
     else result = { status: 'no-op', changed: false, comparison: compareReviewTrees({ cwd: cwd ?? process.cwd(), expected: input.expected, actual: input.actual }), error: null };
   } else result = { status: 'failed', changed: false, error: { code: 'GIT_ACTION_INVALID', message: `Unknown git-workflow action '${action ?? ''}'` } };
   output(result);

package/lib/internal/platform-checks.ts

@@ -2,9 +2,9 @@ import path from 'node:path';
 
 import {
   fetchPlatformCheckLogs,
-  inspectRequiredChecks,
+  inspectPullRequestReadiness,
   resolvePlatformCheckRun,
-  watchPlatformChecks
+  watchPullRequestReadiness
 } from '../platform/pr-checks.ts';
 import type { ChecksResult } from '../platform/pr-checks.ts';
 
@@ -70,7 +70,7 @@ async function platformChecks(args: string[] = []): Promise<void> {
   };
   const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
-  if (operation === 'inspect') { finish(inspectRequiredChecks(taskRef, { cwd })); return; }
+  if (operation === 'inspect') { finish(inspectPullRequestReadiness(taskRef, { cwd })); return; }
   if (operation === 'resolve-run') {
     if (!values.checkName) { fail('resolve-run requires --check-name'); return; }
     finish(resolvePlatformCheckRun(taskRef, { cwd, checkName: values.checkName, detailsUrl: values.detailsUrl }));
@@ -91,7 +91,7 @@ async function platformChecks(args: string[] = []): Promise<void> {
   process.once('SIGINT', abort);
   process.once('SIGTERM', abort);
   try {
-    finish(await watchPlatformChecks(taskRef, { cwd, intervalSeconds, deadlineSeconds, signal: controller.signal }));
+    finish(await watchPullRequestReadiness(taskRef, { cwd, intervalSeconds, deadlineSeconds, signal: controller.signal }));
   } finally {
     process.removeListener('SIGINT', abort);
     process.removeListener('SIGTERM', abort);

package/lib/internal/platform-comment.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import {
   checkPlatformCommentOwner,
   listPlatformComments,
@@ -8,9 +9,11 @@ import {
 } from '../platform/issue-comments.ts';
 import type { CommentKind } from '../platform/issue-comments.ts';
 import type { PlatformResult } from '../platform/types.ts';
+import { backfillCompletionComments } from '../platform/completion-backfill.ts';
 
 const USAGE = `Usage: agent-infra-internal platform-comment list --issue <N> [--cwd <path>]
        agent-infra-internal platform-comment owner <task-ref> [--cwd <path>]
+       agent-infra-internal platform-comment backfill <task-ref> --agent <agent> [--cwd <path>]
        agent-infra-internal platform-comment sync <task-ref> --kind <kind> --agent <agent> [--artifact <file>] [--body-file <path|->] [--status-label <label>] [--backfill] [--cwd <path>]
 `;
 
@@ -52,7 +55,7 @@ function readBodyFile(value: string, cwd: string): string {
 function platformComment(args: string[] = []): void {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
-  if (!operation || !['list', 'owner', 'sync'].includes(operation)) { fail('a valid operation is required'); return; }
+  if (!operation || !['list', 'owner', 'backfill', 'sync'].includes(operation)) { fail('a valid operation is required'); return; }
   const hasTaskRef = operation !== 'list';
   const taskRef = hasTaskRef ? args[1] : undefined;
   if (hasTaskRef && (!taskRef || taskRef.startsWith('--'))) { fail(`${operation} requires a task ref`); return; }
@@ -73,10 +76,22 @@ function platformComment(args: string[] = []): void {
     finish(checkPlatformCommentOwner(taskRef!, { cwd }));
     return;
   }
+  if (operation === 'backfill') {
+    const unexpected = Object.keys(parsed.values).find((key) => !['cwd', 'agent'].includes(key));
+    if (unexpected) { fail(`backfill does not accept '--${unexpected}'`); return; }
+    const agent = parsed.values.agent;
+    if (typeof agent !== 'string' || !agent) { fail('backfill requires --agent'); return; }
+    const normalizedAgent = normalizeAgentToken(agent);
+    if (!normalizedAgent) { fail(`invalid --agent '${agent}': ${AGENT_USAGE_HINT}`); return; }
+    finish(backfillCompletionComments(taskRef!, { cwd, agent: normalizedAgent }));
+    return;
+  }
   const kind = parsed.values.kind;
   const agent = parsed.values.agent;
   if (!['task', 'artifact', 'summary', 'cancel'].includes(String(kind))) { fail('sync requires a valid --kind'); return; }
   if (typeof agent !== 'string' || !agent) { fail('sync requires --agent'); return; }
+  const normalizedAgent = normalizeAgentToken(agent);
+  if (!normalizedAgent) { fail(`invalid --agent '${agent}': ${AGENT_USAGE_HINT}`); return; }
   if (kind === 'artifact' && typeof parsed.values.artifact !== 'string') { fail('artifact sync requires --artifact'); return; }
   if ((kind === 'summary' || kind === 'cancel') && typeof parsed.values.bodyFile !== 'string') { fail(`${kind} sync requires --body-file`); return; }
   let body: string | undefined;
@@ -88,7 +103,7 @@ function platformComment(args: string[] = []): void {
   }
   finish(syncPlatformComment(taskRef!, {
     kind: kind as CommentKind,
-    agent,
+    agent: normalizedAgent,
     artifact: typeof parsed.values.artifact === 'string' ? parsed.values.artifact : undefined,
     body,
     backfill: parsed.values.backfill === true,

package/lib/internal/platform-issue.ts

@@ -1,5 +1,6 @@
 import path from 'node:path';
 
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import {
   bindPlatformIssue,
   createPlatformIssue,
@@ -76,6 +77,9 @@ function platformIssue(args: string[] = []): void {
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
   if (operation === 'inspect') { finish(inspectPlatformIssue(taskRef, { cwd })); return; }
   if (typeof values.agent !== 'string' || !values.agent) { fail(`${operation} requires --agent`); return; }
+  const agent = normalizeAgentToken(values.agent);
+  if (!agent) { fail(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
+  values.agent = agent;
   if (operation === 'create') {
     finish(createPlatformIssue(taskRef, { cwd, agent: values.agent, dryRun: values.dryRun === true })); return;
   }

package/lib/internal/platform-pr-review.ts

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { inspectPlatformPullRequestByNumber } from '../platform/pull-requests.ts';
+import { listPrReviews, publishPrReview } from '../platform/pr-review.ts';
+import type { PrReviewEvent } from '../platform/pr-review.ts';
+import type { PlatformResult } from '../platform/types.ts';
+
+const USAGE = `Usage: agent-infra-internal platform-pr-review inspect --pr <N> [--cwd <path>]
+       agent-infra-internal platform-pr-review list --pr <N> [--cwd <path>]
+       agent-infra-internal platform-pr-review publish --pr <N> --scope <taskId|pr{N}> --round <N> --commit <sha> --event <COMMENT|APPROVE|REQUEST_CHANGES> --body-file <path|-> [--dry-run] [--cwd <path>]
+`;
+
+const BOOLEAN_FLAGS = new Set(['--dry-run']);
+const VALUE_FLAGS = new Set(['--cwd', '--pr', '--scope', '--round', '--commit', '--event', '--body-file']);
+
+function key(flag: string): string {
+  return flag.slice(2).replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+function fail(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'PR_REVIEW_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function finish(output: PlatformResult): void {
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+  if (output.status === 'failed') process.exitCode = 1;
+  if (output.status === 'blocked') process.exitCode = 2;
+}
+
+function parse(args: string[], start: number) {
+  const values: Record<string, string | boolean> = {};
+  const seen = new Set<string>();
+  for (let index = start; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!BOOLEAN_FLAGS.has(flag) && !VALUE_FLAGS.has(flag)) return { values, error: `unknown option '${flag}'` };
+    if (seen.has(flag)) return { values, error: `duplicate option '${flag}'` };
+    seen.add(flag);
+    if (BOOLEAN_FLAGS.has(flag)) { values[key(flag)] = true; continue; }
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) return { values, error: `option '${flag}' requires a value` };
+    values[key(flag)] = value;
+  }
+  return { values };
+}
+
+function readBodyFile(value: string, cwd: string): string {
+  return value === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(path.resolve(cwd, value), 'utf8');
+}
+
+function platformPrReview(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const operation = args[0];
+  if (!operation || !['inspect', 'list', 'publish'].includes(operation)) { fail('a valid operation is required'); return; }
+  const parsed = parse(args, 1);
+  if (parsed.error) { fail(parsed.error); return; }
+  const values = parsed.values;
+  const cwd = path.resolve(typeof values.cwd === 'string' ? values.cwd : process.cwd());
+  const allowed: Record<string, string[]> = {
+    inspect: ['cwd', 'pr'],
+    list: ['cwd', 'pr'],
+    publish: ['cwd', 'pr', 'scope', 'round', 'commit', 'event', 'bodyFile', 'dryRun']
+  };
+  const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
+  if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
+  const pr = Number(values.pr);
+  if (!Number.isInteger(pr) || pr <= 0) { fail(`${operation} requires a positive --pr`); return; }
+  if (operation === 'inspect') {
+    finish(inspectPlatformPullRequestByNumber(pr, { cwd }));
+    return;
+  }
+  if (operation === 'list') {
+    finish(listPrReviews(pr, { cwd }));
+    return;
+  }
+  const scope = typeof values.scope === 'string' ? values.scope : '';
+  const round = Number(values.round);
+  const commit = typeof values.commit === 'string' ? values.commit : '';
+  const event = values.event as string;
+  if (!scope || !/^(?:pr\d+|TASK-\d{8}-\d{6})$/.test(scope)) { fail('publish requires --scope <taskId|pr{N}>'); return; }
+  if (!Number.isInteger(round) || round <= 0) { fail('publish requires a positive --round'); return; }
+  if (!/^[0-9a-f]{7,40}$/i.test(commit)) { fail('publish requires --commit <sha>'); return; }
+  if (!['COMMENT', 'APPROVE', 'REQUEST_CHANGES'].includes(event)) { fail('publish requires --event <COMMENT|APPROVE|REQUEST_CHANGES>'); return; }
+  if (typeof values.bodyFile !== 'string') { fail('publish requires --body-file'); return; }
+  let body: string;
+  try {
+    body = readBodyFile(values.bodyFile, cwd);
+  } catch (error) {
+    fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`);
+    return;
+  }
+  finish(publishPrReview({
+    cwd,
+    prNumber: pr,
+    identity: { scope, round, commitSha: commit },
+    event: event as PrReviewEvent,
+    body,
+    dryRun: values.dryRun === true
+  }));
+}
+
+export { platformPrReview };