@fitlab-ai/agent-infra 0.8.5 → 0.9.1

package/lib/internal/task-context.ts

@@ -0,0 +1,35 @@
+import { parseTaskScope } from '../task/command-options.ts';
+import { resolveTaskContext } from '../task/resolve-ref.ts';
+
+const USAGE = `Usage: agent-infra-internal task-context resolve [<task-ref> | --task <task-ref> | -t <task-ref>]\n`;
+
+function fail(code: string, message: string, usage = false): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code, message } })}\n`);
+  if (usage) process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskContext(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (args[0] !== 'resolve') { fail('TASK_CONTEXT_PAYLOAD_INVALID', "operation 'resolve' is required", true); return; }
+  let scope;
+  try {
+    scope = parseTaskScope(args.slice(1));
+  } catch (error) {
+    fail('TASK_CONTEXT_PAYLOAD_INVALID', error instanceof Error ? error.message : String(error), true);
+    return;
+  }
+  if (scope.positionals.length > 1 || (scope.explicit && scope.positionals.length > 0)) {
+    fail('TASK_CONTEXT_PAYLOAD_INVALID', 'task ref must be provided once', true);
+    return;
+  }
+  const taskRef = scope.taskRef ?? scope.positionals[0];
+  const result = resolveTaskContext(taskRef);
+  if (!result.ok) { fail(result.code, result.message); return; }
+  process.stdout.write(`${JSON.stringify({
+    status: 'resolved', changed: false, taskId: result.taskId, taskDir: result.taskDir,
+    taskMdPath: result.taskMdPath, taskState: result.state, error: null
+  })}\n`);
+}
+
+export { taskContext };

package/lib/internal/task-event.ts

@@ -0,0 +1,51 @@
+import { applyTaskEvent, eventCatalog } from '../task/events.ts';
+import type { TaskEventRequest, Verdict } from '../task/events.ts';
+
+const USAGE = `Usage: agent-infra-internal task-event <N | TASK-id> <event> --agent <agent> [event options] [--dry-run]
+
+Apply one closed-set task lifecycle event and print a structured JSON result.
+Events: ${eventCatalog.join(', ')}
+`;
+
+const FLAGS: Record<string, keyof TaskEventRequest> = {
+  '--agent': 'agent', '--round': 'round', '--question': 'question', '--artifact': 'artifact',
+  '--fix-for': 'fixFor', '--implementation-input': 'implementationInput',
+  '--verdict': 'verdict', '--blockers': 'blockers', '--major': 'major',
+  '--minor': 'minor', '--manual-validation': 'manualValidation', '--files-modified': 'filesModified',
+  '--tests-passed': 'testsPassed', '--summary-result': 'summaryResult'
+};
+const NUMERIC = new Set(['round', 'question', 'blockers', 'major', 'minor', 'manualValidation', 'filesModified', 'testsPassed']);
+
+function usageFailure(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'EVENT_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskEvent(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (args.length < 2) { usageFailure('task ref and event are required'); return; }
+  const request: TaskEventRequest = { taskRef: args[0]!, event: args[1]!, agent: '' };
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag === '--dry-run') {
+      if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+      seen.add(flag); request.dryRun = true; continue;
+    }
+    const key = FLAGS[flag];
+    if (!key) { usageFailure(`unknown option '${flag}'`); return; }
+    if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) { usageFailure(`option '${flag}' requires a value`); return; }
+    seen.add(flag);
+    if (NUMERIC.has(key)) (request as Record<string, unknown>)[key] = Number(value);
+    else if (key === 'verdict') request.verdict = value as Verdict;
+    else (request as Record<string, unknown>)[key] = value;
+  }
+  const result = applyTaskEvent(request);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskEvent };

package/lib/internal/task-ledger.ts

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+
+import { applyLedgerIntent } from '../task/ledger-intents.ts';
+import type { LedgerIntent } from '../task/ledger-intents.ts';
+import { isReviewStage, parseLedger, summarizeLedgerStage, validateLedgerRows } from '../task/ledger.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+
+const USAGE = `Usage: agent-infra-internal task-ledger <task-ref> <intent> [intent flags] [--dry-run]\n\nIntents: finding-upsert, finding-respond, finding-review, decision-next-id, decision-upsert, stage-status\n`;
+const FLAGS: Record<string, string> = {
+  '--stage': 'stage', '--review-artifact': 'reviewArtifact', '--ordinal': 'ordinal',
+  '--severity': 'severity', '--evidence': 'evidence', '--id': 'id', '--round': 'round',
+  '--status': 'status', '--artifact': 'artifact'
+};
+const NUMERIC = new Set(['ordinal', 'round']);
+
+function usageFailure(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LEDGER_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskLedger(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const [taskRef, kind] = args;
+  if (!taskRef || !kind) { usageFailure('task ref and intent are required'); return; }
+  if (!['finding-upsert', 'finding-respond', 'finding-review', 'decision-next-id', 'decision-upsert', 'stage-status'].includes(kind)) {
+    usageFailure(`unknown ledger intent '${kind}'`); return;
+  }
+  const values: Record<string, unknown> = { kind, taskRef };
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag === '--dry-run') {
+      if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+      seen.add(flag); values.dryRun = true; continue;
+    }
+    const key = FLAGS[flag];
+    if (!key) { usageFailure(`unknown option '${flag}'`); return; }
+    if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) { usageFailure(`option '${flag}' requires a value`); return; }
+    seen.add(flag); values[key] = NUMERIC.has(key) ? Number(value) : value;
+  }
+  const required: Record<string, string[]> = {
+    'finding-upsert': ['stage', 'reviewArtifact', 'ordinal', 'severity', 'evidence'],
+    'finding-respond': ['id', 'round', 'status', 'evidence'],
+    'finding-review': ['id', 'status', 'evidence'],
+    'decision-next-id': [],
+    'decision-upsert': ['id', 'stage', 'artifact'],
+    'stage-status': ['stage']
+  };
+  const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind]!]);
+  const unexpected = Object.keys(values).find((key) => !allowed.has(key));
+  const missing = required[kind]!.find((key) => values[key] === undefined);
+  if (unexpected) { usageFailure(`${kind} does not accept '${unexpected}'`); return; }
+  if (missing) { usageFailure(`${kind} requires '${missing}'`); return; }
+  if (kind === 'stage-status') {
+    if (!isReviewStage(String(values.stage))) { usageFailure(`stage-status requires a valid review stage`); return; }
+    const resolved = resolveTaskRef(taskRef);
+    if (!resolved.ok || resolved.state !== 'active') {
+      const message = resolved.ok ? `task ${resolved.taskId} is ${resolved.state}, expected active` : resolved.message;
+      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: resolved.ok ? 'TASK_STATE_MISMATCH' : resolved.code, message } })}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      const rows = parseLedger(fs.readFileSync(resolved.taskMdPath, 'utf8'));
+      const invalid = validateLedgerRows(rows);
+      if (invalid) {
+        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, taskId: resolved.taskId, error: invalid })}\n`);
+        process.exitCode = 1;
+        return;
+      }
+      process.stdout.write(`${JSON.stringify({ status: 'ready', changed: false, taskId: resolved.taskId, stageStatus: summarizeLedgerStage(rows, values.stage as 'analysis' | 'plan' | 'code'), error: null })}\n`);
+    } catch (error) {
+      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, taskId: resolved.taskId, error: { code: 'LEDGER_DOCUMENT_INVALID', message: error instanceof Error ? error.message : String(error) } })}\n`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  const result = applyLedgerIntent(values as LedgerIntent);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskLedger };

package/lib/internal/task-lifecycle.ts

@@ -0,0 +1,41 @@
+import { applyTaskLifecycle, lifecycleIntentCatalog } from '../task/lifecycle.ts';
+import type { TaskLifecycleRequest } from '../task/lifecycle.ts';
+
+const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\n`;
+const FLAGS: Record<string, string> = {
+  '--agent': 'agent', '--reason': 'reason', '--unblock-condition': 'unblockCondition',
+  '--note': 'note', '--alert-number': 'alertNumber', '--staging-dir': 'stagingDir',
+  '--issue-number': 'issueNumber'
+};
+
+function usageFailure(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LIFECYCLE_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskLifecycle(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (args.length < 2) { usageFailure('task ref and intent are required'); return; }
+  const values: Record<string, unknown> = { taskRef: args[0], intent: args[1], agent: '' };
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag === '--dry-run') {
+      if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+      seen.add(flag); values.dryRun = true; continue;
+    }
+    const key = FLAGS[flag];
+    if (!key) { usageFailure(`unknown option '${flag}'`); return; }
+    if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) { usageFailure(`option '${flag}' requires a value`); return; }
+    seen.add(flag);
+    values[key] = key === 'alertNumber' || key === 'issueNumber' ? Number(value) : value;
+  }
+  const result = applyTaskLifecycle(values as TaskLifecycleRequest);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskLifecycle };

package/lib/internal/task-short-id.ts

@@ -0,0 +1,55 @@
+import path from 'node:path';
+
+import { detectRepoRoot } from '../task/resolve-ref.ts';
+import { configuredShortIdLength, executeShortIdCommand } from '../task/short-id.ts';
+
+const USAGE = `Usage: agent-infra-internal task-short-id <alloc|release|resolve|list> [argument] [--active-dir <path>] [--short-id-length <N>] [--verify]\n`;
+
+function failure(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, output: '', error: { code: 'SHORT_ID_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskShortId(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const operation = args[0];
+  if (!operation || !['alloc', 'release', 'resolve', 'list'].includes(operation)) { failure('a valid short-id operation is required'); return; }
+  const positional: string[] = [];
+  let activeDir: string | null = null;
+  let shortIdLength: number | null = null;
+  let verify = false;
+  const seen = new Set<string>();
+  for (let index = 1; index < args.length; index += 1) {
+    const value = args[index]!;
+    if (value === '--verify') {
+      if (seen.has(value)) { failure(`duplicate option '${value}'`); return; }
+      seen.add(value); verify = true; continue;
+    }
+    if (value === '--active-dir' || value === '--short-id-length') {
+      if (seen.has(value)) { failure(`duplicate option '${value}'`); return; }
+      const optionValue = args[++index];
+      if (optionValue === undefined || optionValue.startsWith('--')) { failure(`option '${value}' requires a value`); return; }
+      seen.add(value);
+      if (value === '--active-dir') activeDir = path.resolve(optionValue);
+      else shortIdLength = Number(optionValue);
+      continue;
+    }
+    if (value.startsWith('--')) { failure(`unknown option '${value}'`); return; }
+    positional.push(value);
+  }
+  if (positional.length > (operation === 'list' ? 0 : 1)) { failure('too many positional arguments'); return; }
+  let repoRoot: string | null = null;
+  try { repoRoot = detectRepoRoot(); } catch { /* custom active-dir mode */ }
+  const resolvedActiveDir = activeDir ?? (repoRoot ? path.join(repoRoot, '.agents', 'workspace', 'active') : null);
+  if (!resolvedActiveDir) { failure('cannot determine active task directory'); return; }
+  const width = shortIdLength ?? (repoRoot ? configuredShortIdLength(repoRoot) : 2);
+  const result = executeShortIdCommand({
+    operation: operation as 'alloc' | 'release' | 'resolve' | 'list',
+    argument: positional[0], activeDir: resolvedActiveDir, shortIdLength: width, verify
+  });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskShortId };

package/lib/internal/task-snapshot.ts

@@ -0,0 +1,32 @@
+import { collectTaskSnapshot } from '../task/snapshot.ts';
+
+const USAGE = 'Usage: agent-infra-internal task-snapshot <N | TASK-id> [--format json|text]\n';
+
+function fail(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'SNAPSHOT_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskSnapshot(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (!args[0] || args[0].startsWith('--')) { fail('task ref is required'); return; }
+  let format: 'json' | 'text' = 'json';
+  let seenFormat = false;
+  for (let index = 1; index < args.length; index += 1) {
+    const flag = args[index];
+    if (flag !== '--format') { fail(`unknown option '${flag}'`); return; }
+    if (seenFormat) { fail("duplicate option '--format'"); return; }
+    const value = args[++index];
+    if (value !== 'json' && value !== 'text') { fail("option '--format' requires 'json' or 'text'"); return; }
+    seenFormat = true;
+    format = value;
+  }
+  const result = collectTaskSnapshot(args[0]);
+  if (format === 'text') {
+    process.stdout.write(result.status === 'ready' ? `${result.evidence}\n` : `Snapshot failed: ${result.error?.code} - ${result.error?.message}\n`);
+  } else process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskSnapshot };

package/lib/internal/task-verify.ts

@@ -0,0 +1,33 @@
+import { renderTaskVerification, verifyTaskEvent } from '../task/verification.ts';
+
+const USAGE = 'Usage: agent-infra-internal task-verify <N | TASK-id> <verification-event> [--artifact <canonical.md>] [--format json|text]\n';
+
+function fail(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'VERIFY_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskVerify(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (!args[0] || !args[1] || args[0].startsWith('--') || args[1].startsWith('--')) { fail('task ref and verification event are required'); return; }
+  let artifact: string | undefined;
+  let format: 'json' | 'text' = 'json';
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag !== '--artifact' && flag !== '--format') { fail(`unknown option '${flag}'`); return; }
+    if (seen.has(flag)) { fail(`duplicate option '${flag}'`); return; }
+    const value = args[++index];
+    if (!value || value.startsWith('--')) { fail(`option '${flag}' requires a value`); return; }
+    seen.add(flag);
+    if (flag === '--artifact') artifact = value;
+    else if (value === 'json' || value === 'text') format = value;
+    else { fail("option '--format' requires 'json' or 'text'"); return; }
+  }
+  const result = verifyTaskEvent({ taskRef: args[0], event: args[1], ...(artifact ? { artifact } : {}) });
+  process.stdout.write(format === 'text' ? renderTaskVerification(result) : `${JSON.stringify(result)}\n`);
+  process.exitCode = result.status === 'pass' ? 0 : result.status === 'blocked' ? 2 : 1;
+}
+
+export { taskVerify };

package/lib/internal/task-warning.ts

@@ -0,0 +1,50 @@
+import { applyWorkflowWarningIntent } from '../task/workflow-warning-intents.ts';
+import type { WorkflowWarningIntent } from '../task/workflow-warning-intents.ts';
+
+const USAGE = `Usage: agent-infra-internal task-warning <task-ref> <add|set-status|list> [intent flags] [--dry-run]\n`;
+const FLAGS: Record<string, string> = {
+  '--step': 'step', '--severity': 'severity', '--code': 'code', '--target': 'target',
+  '--message': 'message', '--action': 'action', '--id': 'id', '--status': 'status', '--resolution': 'resolution'
+};
+
+function usageFailure(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'WARNING_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskWarning(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const [taskRef, kind] = args;
+  if (!taskRef || !kind || !['add', 'set-status', 'list'].includes(kind)) { usageFailure('task ref and a valid intent are required'); return; }
+  const values: Record<string, unknown> = { kind, taskRef };
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag === '--dry-run') {
+      if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+      seen.add(flag); values.dryRun = true; continue;
+    }
+    const key = FLAGS[flag];
+    if (!key) { usageFailure(`unknown option '${flag}'`); return; }
+    if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) { usageFailure(`option '${flag}' requires a value`); return; }
+    seen.add(flag); values[key] = value;
+  }
+  const required: Record<string, string[]> = {
+    add: ['step', 'severity', 'code', 'target', 'message', 'action'],
+    'set-status': ['id', 'status', 'resolution'], list: []
+  };
+  const optional = kind === 'list' ? ['status'] : [];
+  const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind]!, ...optional]);
+  const unexpected = Object.keys(values).find((key) => !allowed.has(key));
+  const missing = required[kind]!.find((key) => values[key] === undefined);
+  if (unexpected) { usageFailure(`${kind} does not accept '${unexpected}'`); return; }
+  if (missing) { usageFailure(`${kind} requires '${missing}'`); return; }
+  const result = applyWorkflowWarningIntent(values as WorkflowWarningIntent);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskWarning };

package/lib/platform/adapters.ts

@@ -0,0 +1,30 @@
+import type { PlatformResult } from './types.ts';
+
+type PlatformAdapterContext = {
+  cwd: string;
+  gitRemote?: (cwd: string) => string | null;
+  client?: unknown;
+};
+
+type PlatformAdapter = {
+  type: string;
+  resolveContext(context: PlatformAdapterContext): PlatformResult;
+};
+
+const adapters = new Map<string, PlatformAdapter>();
+
+function registerPlatformAdapter(adapter: PlatformAdapter): void {
+  if (!adapter.type.trim()) throw new Error('Platform adapter type is required');
+  adapters.set(adapter.type, adapter);
+}
+
+function getPlatformAdapter(type: string | null): PlatformAdapter | null {
+  return type ? adapters.get(type) ?? null : null;
+}
+
+function listPlatformAdapters(): string[] {
+  return [...adapters.keys()].sort();
+}
+
+export { getPlatformAdapter, listPlatformAdapters, registerPlatformAdapter };
+export type { PlatformAdapter, PlatformAdapterContext };

package/lib/platform/context.ts

@@ -0,0 +1,164 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+import semver from 'semver';
+
+import { getPlatformAdapter, registerPlatformAdapter } from './adapters.ts';
+import { createGitHubClient, MINIMUM_GITHUB_CLI_VERSION } from './github-client.ts';
+import type { GitHubClient } from './github-client.ts';
+import { platformResult } from './types.ts';
+import type { PlatformResult } from './types.ts';
+
+type ContextOptions = {
+  cwd?: string;
+  gitRemote?: (cwd: string) => string | null;
+  client?: {
+    version(options?: Parameters<GitHubClient['version']>[0]): ReturnType<GitHubClient['version']>;
+    json(args: string[], options?: Parameters<GitHubClient['json']>[1]): ReturnType<GitHubClient['json']>;
+  };
+  platformType?: string;
+};
+
+function findRepoRoot(cwd: string): string {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch {
+    return cwd;
+  }
+}
+
+function parseGitHubRemote(remote: string): string | null {
+  const trimmed = remote.trim().replace(/\.git$/, '');
+  const match = trimmed.match(/^(?:https?:\/\/github\.com\/|ssh:\/\/(?:git@)?github\.com\/|git@github\.com:)([^/\s]+\/[^/\s]+)$/i);
+  return match?.[1] || null;
+}
+
+function defaultGitRemote(cwd: string): string | null {
+  try {
+    return execFileSync('git', ['remote', 'get-url', 'origin'], {
+      cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function readPlatformType(repoRoot: string): string | null {
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8'));
+    return typeof config?.platform?.type === 'string' ? config.platform.type : null;
+  } catch {
+    return null;
+  }
+}
+
+function failure(error: { code: string; message: string; retryable: boolean }, repo: string | null): PlatformResult {
+  const blocked = error.retryable || error.code === 'AUTH_REQUIRED' || error.code === 'PLATFORM_DEPENDENCY_MISSING';
+  return platformResult(blocked ? 'blocked' : 'failed', {
+    platform: { type: 'github', repository: repo, currentUser: null }, error
+  });
+}
+
+function resolveGitHubContext(options: ContextOptions & { cwd: string }): PlatformResult {
+  const { cwd } = options;
+  const platform = 'github';
+  const client = options.client || createGitHubClient();
+  const version = client.version({ cwd });
+  if (!version.ok) return failure(version.error, null);
+  if (!semver.gte(version.value, MINIMUM_GITHUB_CLI_VERSION)) {
+    return failure({
+      code: 'GH_CLI_VERSION_UNSUPPORTED',
+      message: `GitHub CLI ${version.value} is unsupported; install gh >= ${MINIMUM_GITHUB_CLI_VERSION}`,
+      retryable: false
+    }, null);
+  }
+  const remote = (options.gitRemote || defaultGitRemote)(cwd);
+  if (!remote) {
+    return platformResult('no-op', {
+      platform: { type: platform, repository: null, currentUser: null },
+      error: { code: 'REMOTE_MISSING', message: 'Git origin remote is not configured', retryable: false }
+    });
+  }
+  const ownerRepo = parseGitHubRemote(remote);
+  if (!ownerRepo) {
+    const nonGitHub = !/github\.com/i.test(remote);
+    return platformResult(nonGitHub ? 'no-op' : 'failed', {
+      platform: { type: platform, repository: null, currentUser: null },
+      error: {
+        code: nonGitHub ? 'PLATFORM_UNSUPPORTED' : 'REMOTE_INVALID',
+        message: `Unable to parse GitHub owner/repo from '${remote}'`,
+        retryable: false
+      }
+    });
+  }
+
+  const repository = client.json(['api', `repos/${ownerRepo}`], { cwd });
+  if (!repository.ok) return failure(repository.error, null);
+  const repositoryValue = repository.value as { fork?: boolean; full_name?: string; parent?: { full_name?: string } } | null;
+  const upstream = repositoryValue?.fork ? repositoryValue.parent?.full_name : repositoryValue?.full_name;
+  if (!upstream) {
+    return platformResult('blocked', {
+      platform: { type: platform, repository: null, currentUser: null },
+      error: { code: 'UPSTREAM_UNRESOLVED', message: 'Unable to resolve the upstream repository', retryable: false }
+    });
+  }
+  const user = client.json(['api', 'user'], { cwd });
+  if (!user.ok) return failure(user.error, upstream);
+  const userValue = user.value as { login?: string } | null;
+  const permissions = client.json(['api', `repos/${upstream}`], { cwd });
+  if (!permissions.ok) return failure(permissions.error, upstream);
+  const permissionValue = permissions.value as { permissions?: Record<string, boolean> } | null;
+  const values = permissionValue?.permissions || {};
+  const capabilities = {
+    authenticated: Boolean(userValue?.login),
+    comment: Boolean(userValue?.login),
+    triage: Boolean(values.triage || values.push || values.admin),
+    push: Boolean(values.push || values.admin),
+    admin: Boolean(values.admin)
+  };
+  const status = Object.values(capabilities).every(Boolean) ? 'no-op' : 'degraded';
+  return platformResult(status, {
+    changed: false,
+    platform: { type: platform, repository: upstream, currentUser: userValue?.login || null },
+    resource: { kind: 'repository', number: null },
+    capabilities,
+    operations: [{ name: 'resolve', status: 'no-op', reasonCode: null }]
+  });
+}
+
+registerPlatformAdapter({
+  type: 'github',
+  resolveContext(options) {
+    return resolveGitHubContext(options as ContextOptions & { cwd: string });
+  }
+});
+
+registerPlatformAdapter({
+  type: 'none',
+  resolveContext() {
+    return platformResult('no-op', {
+      platform: { type: 'none', repository: null, currentUser: null },
+      operations: [{ name: 'resolve', status: 'no-op', reasonCode: 'PLATFORM_DISABLED' }]
+    });
+  }
+});
+
+function resolvePlatformContext(options: ContextOptions = {}): PlatformResult {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const repoRoot = findRepoRoot(cwd);
+  const platform = options.platformType ?? readPlatformType(repoRoot);
+  const adapter = getPlatformAdapter(platform);
+  if (!adapter) {
+    return platformResult('no-op', {
+      platform: { type: platform, repository: null, currentUser: null },
+      error: { code: 'PLATFORM_UNSUPPORTED', message: `Platform '${platform || 'none'}' has no registered adapter`, retryable: false }
+    });
+  }
+  return adapter.resolveContext({ cwd, gitRemote: options.gitRemote, client: options.client });
+}
+
+export { parseGitHubRemote, resolvePlatformContext };
+export type { ContextOptions };