@fitlab-ai/agent-infra 0.9.2 → 0.9.3

package/dist/lib/git/workflow.js

@@ -1,4 +1,6 @@
 import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 const defaultRunner = (args, cwd) => {
     const result = spawnSync('git', [...args], { cwd, encoding: 'utf8' });
     return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
@@ -10,6 +12,9 @@ function value(runner, cwd, args, trim = true) {
     const result = run(runner, cwd, args);
     return result.status === 0 ? (trim ? result.stdout.trim() : result.stdout.replace(/\n$/, '')) : null;
 }
+function cleanMessage(message) {
+    return message.replace(/(https?:\/\/)[^\s/@:]+(?::[^\s/@]*)?@/gi, '$1***@').trim();
+}
 function inspectGitWorkflow(cwd, runner = defaultRunner, remoteInput) {
     const head = value(runner, cwd, ['rev-parse', 'HEAD']);
     const branch = value(runner, cwd, ['branch', '--show-current']);
@@ -97,5 +102,53 @@ function pushGitRefs(input, runner = defaultRunner) {
     const failures = operations.filter((item) => item.status === 'failed').length;
     return { status: failures === 0 ? 'applied' : failures === operations.length ? 'failed' : 'degraded', changed: failures < operations.length, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations, error: failures ? { code: 'GIT_PUSH_PARTIAL', message: `${failures} ref push operation(s) failed` } : null };
 }
-export { commitExplicitPaths, inspectGitWorkflow, pushGitRefs };
+function pushRebasedBranch(input, runner = defaultRunner) {
+    const sha = /^[0-9a-f]{40}$/i;
+    const refName = /^(?!-)(?!.*\.\.)(?!.*(?:^|\/)\.)(?!.*[~^:?*\[\\\s])(?:[A-Za-z0-9._-]+\/)*[A-Za-z0-9._-]+$/;
+    if (!input.remote || !refName.test(input.remote) || !refName.test(input.branch) || !refName.test(input.baseBranch) ||
+        !sha.test(input.expectedOldHead) || !sha.test(input.newHead) || !sha.test(input.expectedBaseHead)) {
+        return { status: 'failed', changed: false, snapshot: null, operations: [], error: { code: 'GIT_REBASED_INPUT_INVALID', message: 'Remote, branches, and full 40-character SHAs are required' } };
+    }
+    const snapshot = inspectGitWorkflow(input.cwd, runner).snapshot;
+    if (!snapshot)
+        return { status: 'failed', changed: false, snapshot: null, operations: [], error: { code: 'GIT_INSPECT_FAILED', message: 'Unable to inspect Git repository' } };
+    if (snapshot.branch !== input.branch || snapshot.head !== input.newHead) {
+        return { status: 'failed', changed: false, snapshot, operations: [], error: { code: 'GIT_LOCAL_IDENTITY_MISMATCH', message: 'Current branch or HEAD does not match the rebased intent' } };
+    }
+    const rebasePaths = ['rebase-merge', 'rebase-apply']
+        .map((name) => value(runner, input.cwd, ['rev-parse', '--git-path', name]))
+        .filter((candidate) => Boolean(candidate));
+    if (snapshot.worktree.length > 0 || snapshot.staged.length > 0 ||
+        run(runner, input.cwd, ['rev-parse', '-q', '--verify', 'REBASE_HEAD']).status === 0 ||
+        rebasePaths.some((candidate) => fs.existsSync(path.isAbsolute(candidate) ? candidate : path.join(input.cwd, candidate)))) {
+        return { status: 'failed', changed: false, snapshot, operations: [], error: { code: 'GIT_LOCAL_STATE_UNSAFE', message: 'Working tree must be clean with no rebase in progress' } };
+    }
+    const remoteRef = `refs/heads/${input.branch}`;
+    const baseRef = `refs/heads/${input.baseBranch}`;
+    const remoteHead = value(runner, input.cwd, ['ls-remote', '--exit-code', input.remote, remoteRef])?.split(/\s+/)[0] ?? null;
+    if (remoteHead !== input.expectedOldHead) {
+        return { status: 'failed', changed: false, snapshot, operations: [], error: { code: 'GIT_REMOTE_HEAD_MISMATCH', message: `Expected remote head ${input.expectedOldHead}, received ${remoteHead ?? 'unavailable'}` } };
+    }
+    const baseHead = value(runner, input.cwd, ['ls-remote', '--exit-code', input.remote, baseRef])?.split(/\s+/)[0] ?? null;
+    if (baseHead !== input.expectedBaseHead) {
+        return { status: 'failed', changed: false, snapshot, operations: [], error: { code: 'GIT_REMOTE_BASE_MISMATCH', message: `Expected base head ${input.expectedBaseHead}, received ${baseHead ?? 'unavailable'}` } };
+    }
+    if (run(runner, input.cwd, ['merge-base', '--is-ancestor', input.expectedBaseHead, input.newHead]).status !== 0) {
+        return { status: 'failed', changed: false, snapshot, operations: [], error: { code: 'GIT_REBASED_ANCESTOR_MISMATCH', message: 'Rebased head does not contain the expected base head' } };
+    }
+    const pushed = run(runner, input.cwd, [
+        'push', `--force-with-lease=${remoteRef}:${input.expectedOldHead}`,
+        input.remote, `${input.newHead}:${remoteRef}`
+    ]);
+    if (pushed.status !== 0) {
+        const message = cleanMessage(pushed.stderr) || 'Rebased branch push was rejected';
+        return { status: 'failed', changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'push-rebased', status: 'failed', ref: input.branch, message }], error: { code: 'GIT_REBASED_PUSH_REJECTED', message } };
+    }
+    const verified = value(runner, input.cwd, ['ls-remote', '--exit-code', input.remote, remoteRef])?.split(/\s+/)[0] ?? null;
+    if (verified !== input.newHead) {
+        return { status: 'failed', changed: true, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'push-rebased', status: 'failed', ref: input.branch, message: 'Remote ref verification failed' }], error: { code: 'GIT_REBASED_VERIFY_FAILED', message: `Expected pushed head ${input.newHead}, received ${verified ?? 'unavailable'}` } };
+    }
+    return { status: 'applied', changed: true, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'push-rebased', status: 'applied', ref: input.branch }], error: null };
+}
+export { commitExplicitPaths, inspectGitWorkflow, pushGitRefs, pushRebasedBranch };
 //# sourceMappingURL=workflow.js.map

package/dist/lib/internal/agent-client.js

@@ -3,7 +3,9 @@ import path from 'node:path';
 import { AgentClientConfigError, normalizeAgentClients } from '../agent-clients/config.js';
 import { normalizeCustomTUIs } from '../agent-clients/custom-tuis.js';
 import { renderNextStepCommands } from '../agent-clients/next-steps.js';
-const USAGE = 'Usage: agent-infra-internal agent-client next-steps --skill <skill-name> [--task-ref <NN|TASK-id>] [--format text|json]\n';
+import { getAgentClientModelSelection } from '../agent-clients/registry.js';
+import { isAgentClientId } from '../agent-clients/types.js';
+const USAGE = 'Usage: agent-infra-internal agent-client <next-steps|model-selection> [options]\n';
 function failure(code, message) {
     process.stdout.write(`${JSON.stringify({
         status: 'failed',
@@ -25,11 +27,12 @@ function parseArgs(args) {
     }
     let skillName;
     let taskRef;
+    let version;
     let format = 'text';
     const seen = new Set();
     for (let index = 1; index < args.length; index += 1) {
         const flag = args[index];
-        if (!['--skill', '--task-ref', '--format'].includes(flag)) {
+        if (!['--skill', '--task-ref', '--version', '--format'].includes(flag)) {
             failure('AGENT_CLIENT_PAYLOAD_INVALID', `unknown option '${flag}'`);
             return null;
         }
@@ -47,6 +50,8 @@ function parseArgs(args) {
             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'");
@@ -59,9 +64,60 @@ function parseArgs(args) {
         failure('AGENT_CLIENT_PAYLOAD_INVALID', "option '--skill' is required");
         return null;
     }
-    return { skillName, ...(taskRef ? { taskRef } : {}), format };
+    return {
+        skillName,
+        ...(taskRef ? { taskRef } : {}),
+        ...(version ? { version } : {}),
+        format
+    };
 }
 function agentClient(args = []) {
+    if (args[0] === 'model-selection') {
+        const values = {};
+        const seen = new Set();
+        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;
@@ -86,7 +142,8 @@ function agentClient(args = []) {
             state: clients.state,
             customTUIs: custom.items,
             skillName: parsed.skillName,
-            ...(parsed.taskRef ? { taskRef: parsed.taskRef } : {})
+            ...(parsed.taskRef ? { taskRef: parsed.taskRef } : {}),
+            ...(parsed.version ? { version: parsed.version } : {})
         });
         if (parsed.format === 'json') {
             process.stdout.write(`${JSON.stringify({

package/dist/lib/internal/git-workflow.js

@@ -1,5 +1,5 @@
 import fs from 'node:fs';
-import { commitExplicitPaths, inspectGitWorkflow, pushGitRefs } from '../git/workflow.js';
+import { commitExplicitPaths, inspectGitWorkflow, pushGitRefs, pushRebasedBranch } from '../git/workflow.js';
 import { compareReviewTrees, snapshotReview } from '../git/review-snapshot.js';
 import { resolvePostReviewGlobs } from '../task/review-fingerprint.js';
 function output(value) { process.stdout.write(`${JSON.stringify(value)}\n`); }
@@ -23,6 +23,11 @@ function gitWorkflow(args = []) {
         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;

package/dist/lib/internal/platform-checks.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { fetchPlatformCheckLogs, inspectRequiredChecks, resolvePlatformCheckRun, watchPlatformChecks } from '../platform/pr-checks.js';
+import { fetchPlatformCheckLogs, inspectPullRequestReadiness, resolvePlatformCheckRun, watchPullRequestReadiness } from '../platform/pr-checks.js';
 const USAGE = `Usage: agent-infra-internal platform-checks inspect <task-ref> [--cwd <path>]
        agent-infra-internal platform-checks watch <task-ref> --interval-seconds <N> --deadline-seconds <N> [--cwd <path>]
        agent-infra-internal platform-checks resolve-run <task-ref> --check-name <name> [--details-url <url>] [--cwd <path>]
@@ -76,7 +76,7 @@ async function platformChecks(args = []) {
         return;
     }
     if (operation === 'inspect') {
-        finish(inspectRequiredChecks(taskRef, { cwd }));
+        finish(inspectPullRequestReadiness(taskRef, { cwd }));
         return;
     }
     if (operation === 'resolve-run') {
@@ -108,7 +108,7 @@ async function platformChecks(args = []) {
     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);

package/dist/lib/internal/platform-comment.js

@@ -1,8 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
 import { checkPlatformCommentOwner, listPlatformComments, syncPlatformComment } from '../platform/issue-comments.js';
+import { backfillCompletionComments } from '../platform/completion-backfill.js';
 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>]
 `;
 function fail(message) {
@@ -50,7 +53,7 @@ function platformComment(args = []) {
         return;
     }
     const operation = args[0];
-    if (!operation || !['list', 'owner', 'sync'].includes(operation)) {
+    if (!operation || !['list', 'owner', 'backfill', 'sync'].includes(operation)) {
         fail('a valid operation is required');
         return;
     }
@@ -89,6 +92,25 @@ function platformComment(args = []) {
         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))) {
@@ -99,6 +121,11 @@ function platformComment(args = []) {
         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;
@@ -118,7 +145,7 @@ function platformComment(args = []) {
     }
     finish(syncPlatformComment(taskRef, {
         kind: kind,
-        agent,
+        agent: normalizedAgent,
         artifact: typeof parsed.values.artifact === 'string' ? parsed.values.artifact : undefined,
         body,
         backfill: parsed.values.backfill === true,

package/dist/lib/internal/platform-issue.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
 import { bindPlatformIssue, createPlatformIssue, inspectPlatformIssue, syncPlatformIssue } from '../platform/issues.js';
 const USAGE = `Usage: agent-infra-internal platform-issue inspect <task-ref> [--cwd <path>]
        agent-infra-internal platform-issue create <task-ref> --agent <agent> [--dry-run] [--cwd <path>]
@@ -92,6 +93,12 @@ function platformIssue(args = []) {
         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/dist/lib/internal/platform-pr-review.js

@@ -0,0 +1,132 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { inspectPlatformPullRequestByNumber } from '../platform/pull-requests.js';
+import { listPrReviews, publishPrReview } from '../platform/pr-review.js';
+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) {
+    return flag.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function fail(message) {
+    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) {
+    process.stdout.write(`${JSON.stringify(output)}\n`);
+    if (output.status === 'failed')
+        process.exitCode = 1;
+    if (output.status === 'blocked')
+        process.exitCode = 2;
+}
+function parse(args, start) {
+    const values = {};
+    const seen = new Set();
+    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, cwd) {
+    return value === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(path.resolve(cwd, value), 'utf8');
+}
+function platformPrReview(args = []) {
+    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 = {
+        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;
+    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;
+    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,
+        body,
+        dryRun: values.dryRun === true
+    }));
+}
+export { platformPrReview };
+//# sourceMappingURL=platform-pr-review.js.map

package/dist/lib/internal/platform-pr.js

@@ -1,8 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { bindPlatformPullRequest, createPlatformPullRequest, inspectPlatformPullRequest, syncPlatformPullRequest } from '../platform/pull-requests.js';
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
+import { bindPlatformPullRequest, createPlatformPullRequest, inspectPlatformPullRequest, resolveExternalPullRequest, syncPlatformPullRequest } from '../platform/pull-requests.js';
 import { summaryContext, syncPullRequestSummary } from '../platform/pr-summary.js';
 const USAGE = `Usage: agent-infra-internal platform-pr inspect <task-ref> [--cwd <path>]
+       agent-infra-internal platform-pr resolve-external <task-ref> --agent <agent> [--pr <N>] [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr create <task-ref> --agent <agent> --base <branch> --head <branch> --title-file <path|-> --body-file <path|-> [--draft] [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr bind <task-ref> --pr <N> --agent <agent> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr sync <task-ref> --agent <agent> [--metadata] [--closing-issue] [--dry-run] [--cwd <path>]
@@ -56,7 +58,7 @@ function platformPr(args = []) {
         return;
     }
     const operation = args[0];
-    if (!operation || !['inspect', 'create', 'bind', 'sync', 'summary-context', 'summary-sync'].includes(operation)) {
+    if (!operation || !['inspect', 'resolve-external', 'create', 'bind', 'sync', 'summary-context', 'summary-sync'].includes(operation)) {
         fail('a valid operation is required');
         return;
     }
@@ -74,6 +76,7 @@ function platformPr(args = []) {
     const cwd = path.resolve(typeof values.cwd === 'string' ? values.cwd : process.cwd());
     const allowed = {
         inspect: ['cwd'],
+        'resolve-external': ['cwd', 'agent', 'pr', 'dryRun'],
         create: ['cwd', 'agent', 'base', 'head', 'titleFile', 'bodyFile', 'draft', 'dryRun'],
         bind: ['cwd', 'agent', 'pr', 'dryRun'],
         sync: ['cwd', 'agent', 'metadata', 'closingIssue', 'dryRun'],
@@ -97,6 +100,21 @@ function platformPr(args = []) {
         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 === 'resolve-external') {
+        const pr = values.pr === undefined ? undefined : Number(values.pr);
+        if (pr !== undefined && (!Number.isInteger(pr) || pr <= 0)) {
+            fail('resolve-external requires a positive --pr');
+            return;
+        }
+        finish(resolveExternalPullRequest(taskRef, { cwd, agent: values.agent, pr, dryRun: values.dryRun === true }));
+        return;
+    }
     if (operation === 'bind') {
         const pr = Number(values.pr);
         if (!Number.isInteger(pr) || pr <= 0) {

package/dist/lib/internal/platform-release-notes.js

@@ -1,9 +1,28 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { publishReleaseNotes, releaseNoteContext } from '../platform/release-notes.js';
-function option(args, name) {
-    const index = args.indexOf(name);
-    return index >= 0 && args[index + 1] ? args[index + 1] : null;
+import { publishReleaseNotes, releaseNoteContext, stageReleaseNotes } from '../platform/release-notes.js';
+function parseOptions(args, valueFlags, switchFlags = []) {
+    const values = new Map();
+    const switches = new Set();
+    for (let index = 0; index < args.length; index += 1) {
+        const flag = args[index];
+        if (values.has(flag) || switches.has(flag))
+            return null;
+        if (switchFlags.includes(flag)) {
+            switches.add(flag);
+            continue;
+        }
+        if (!valueFlags.includes(flag))
+            return null;
+        const value = args[++index];
+        if (!value || value.startsWith('--'))
+            return null;
+        values.set(flag, value);
+    }
+    return { values, switches };
+}
+function invalidInput(message) {
+    return { status: 'failed', changed: false, error: { code: 'RELEASE_NOTES_INPUT_INVALID', message, retryable: false } };
 }
 function finish(result) {
     process.stdout.write(`${JSON.stringify(result)}\n`);
@@ -11,21 +30,37 @@ function finish(result) {
 }
 function platformReleaseNotes(args = []) {
     const [action, ...rest] = args;
-    const cwd = path.resolve(option(rest, '--cwd') || process.cwd());
     if (action === 'context') {
-        const historyRaw = option(rest, '--history-limit');
+        const parsed = parseOptions(rest, ['--cwd', '--history-limit', '--from-tag', '--to-tag', '--branch']);
+        if (!parsed)
+            return finish(invalidInput('invalid context options'));
+        const cwd = path.resolve(parsed.values.get('--cwd') || process.cwd());
+        const historyRaw = parsed.values.get('--history-limit') ?? null;
         finish(releaseNoteContext({
-            fromTag: option(rest, '--from-tag') || '',
-            toTag: option(rest, '--to-tag') || '',
-            branch: option(rest, '--branch') || '',
+            fromTag: parsed.values.get('--from-tag') || '',
+            toTag: parsed.values.get('--to-tag') || '',
+            branch: parsed.values.get('--branch') || '',
             historyLimit: historyRaw === null ? undefined : Number(historyRaw)
         }, { cwd }));
         return;
     }
+    if (action === 'stage') {
+        const parsed = parseOptions(rest, ['--cwd', '--notes-file']);
+        if (!parsed)
+            return finish(invalidInput('invalid stage options'));
+        const notesFile = parsed.values.get('--notes-file');
+        if (!notesFile)
+            return finish(invalidInput('notes-file is required'));
+        finish(stageReleaseNotes({ notesFile }, { cwd: path.resolve(parsed.values.get('--cwd') || process.cwd()) }));
+        return;
+    }
     if (action === 'publish') {
-        const notesPath = option(rest, '--notes-file');
+        const parsed = parseOptions(rest, ['--cwd', '--notes-file', '--tag', '--title', '--expected-sha256'], ['--dry-run']);
+        if (!parsed)
+            return finish(invalidInput('invalid publish options'));
+        const notesPath = parsed.values.get('--notes-file');
         if (!notesPath) {
-            finish({ status: 'failed', changed: false, error: { code: 'RELEASE_NOTES_INPUT_INVALID', message: 'notes-file is required', retryable: false } });
+            finish(invalidInput('notes-file is required'));
             return;
         }
         let resolvedNotesPath = notesPath;
@@ -35,11 +70,12 @@ function platformReleaseNotes(args = []) {
         }
         try {
             finish(publishReleaseNotes({
-                tag: option(rest, '--tag') || '',
-                title: option(rest, '--title') || option(rest, '--tag') || '',
+                tag: parsed.values.get('--tag') || '',
+                title: parsed.values.get('--title') || parsed.values.get('--tag') || '',
                 notesFile: resolvedNotesPath,
-                dryRun: rest.includes('--dry-run')
-            }, { cwd }));
+                expectedSha256: parsed.values.get('--expected-sha256') || '',
+                dryRun: parsed.switches.has('--dry-run')
+            }, { cwd: path.resolve(parsed.values.get('--cwd') || process.cwd()) }));
         }
         finally {
             if (notesPath === '-')
@@ -47,7 +83,7 @@ function platformReleaseNotes(args = []) {
         }
         return;
     }
-    finish({ status: 'failed', changed: false, error: { code: 'RELEASE_NOTES_INPUT_INVALID', message: 'Usage: platform-release-notes context|publish', retryable: false } });
+    finish(invalidInput('Usage: platform-release-notes context|stage|publish'));
 }
 export { platformReleaseNotes };
 //# sourceMappingURL=platform-release-notes.js.map