@fitlab-ai/agent-infra 0.9.11 → 0.9.13

package/lib/platform/pr-checks.ts

@@ -1,19 +1,23 @@
 import fs from 'node:fs';
 
-import { parseTaskFrontmatter } from '../task/frontmatter.ts';
+import { parseTypedTaskFrontmatter } from '../task/frontmatter.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
-import {
-  inspectPlatformRequiredChecks,
-  registerPlatformCapabilities
-} from './adapters.ts';
 import type { PlatformCheckSnapshot } from './adapters.ts';
-import { resolvePlatformContext } from './context.ts';
-import { createGitHubClient } from './github-client.ts';
-import type { GitHubClient } from './github-client.ts';
+import { resolvePlatformProviderContext } from './context.ts';
+import type { PlatformClient } from './context.ts';
 import { inspectPlatformPullRequest } from './pull-requests.ts';
 import { platformResult } from './types.ts';
 import type { PlatformResult } from './types.ts';
 import type { PullRequestSnapshot } from './pull-requests.ts';
+import { readPrDeliveryFact } from '../task/pr-delivery-fact.ts';
+import {
+  providerError,
+  providerOperationContext,
+  providerStatus,
+  resourceIdentity,
+  resourceIdentityNumber,
+  unsupportedProviderOperation
+} from './provider-bridge.ts';
 
 type CheckBucket = 'pass' | 'fail' | 'pending' | 'cancel';
 type CheckState = 'passed' | 'failed' | 'pending' | 'timed-out' | 'cancelled' | 'no-required';
@@ -29,8 +33,9 @@ type ChecksResult = PlatformResult & {
   resolution?: { status: 'resolved' | 'missing' | 'ambiguous'; runId: number | null; jobId: number | null };
   logs?: { runId: number; jobId?: number; text: string };
 };
-type InspectionOptions = { cwd?: string; client?: unknown };
-type SharedOptions = { cwd?: string; client?: GitHubClient };
+type GitHubClient = PlatformClient;
+type InspectionOptions = { cwd?: string; client?: PlatformClient; runtimeVersion?: string };
+type SharedOptions = { cwd?: string; client?: PlatformClient };
 
 function classifyRequiredChecks(required: CheckSnapshot[]): ChecksSnapshot {
   if (required.length === 0) return { state: 'no-required', required };
@@ -80,8 +85,8 @@ function checksResult(status: PlatformResult['status'], overrides: Partial<Check
   };
 }
 
-function normalizeBucket(value: { bucket?: string; state?: string; conclusion?: string }): CheckBucket {
-  const raw = String(value.bucket || value.conclusion || value.state || '').toLowerCase();
+function normalizeBucket(value: { bucket?: string; status?: string; state?: string; conclusion?: string }): CheckBucket {
+  const raw = String(value.bucket || value.status || value.conclusion || value.state || '').toLowerCase();
   if (['pass', 'success', 'successful', 'neutral'].includes(raw)) return 'pass';
   if (['fail', 'failure', 'failed', 'error', 'timed_out', 'action_required'].includes(raw)) return 'fail';
   if (['cancel', 'cancelled', 'canceled', 'skipped', 'stale'].includes(raw)) return 'cancel';
@@ -105,84 +110,81 @@ function normalizeChecks(value: unknown): CheckSnapshot[] {
   });
 }
 
-registerPlatformCapabilities('github', {
-  inspectRequiredChecks({ client, repository, number, cwd }) {
-    const github = (client as GitHubClient | undefined) || createGitHubClient();
-    const inspected = github.json<unknown>([
-      'pr', 'checks', String(number), '--repo', repository,
-      '--json', 'name,state,bucket,link,workflow,startedAt,completedAt'
-    ], { cwd });
-    return inspected.ok
-      ? { ok: true, value: normalizeChecks(inspected.value) }
-      : { ok: false, error: inspected.error };
-  }
-});
+function inspectGitHubRequiredChecks(client: GitHubClient, repository: string, number: number, cwd: string) {
+  const inspected = client.json<unknown>([
+    'pr', 'checks', String(number), '--repo', repository,
+    '--json', 'name,state,bucket,link,workflow,startedAt,completedAt'
+  ], { cwd });
+  return inspected.ok
+    ? { ok: true as const, value: normalizeChecks(inspected.value) }
+    : { ok: false as const, error: inspected.error };
+}
 
-function resolvedTask(taskRef: string, options: InspectionOptions) {
+async function resolvedTask(taskRef: string, options: InspectionOptions) {
   const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
   if (!resolved.ok) return { ok: false as const, output: checksResult('failed', { error: { code: resolved.code, message: resolved.message, retryable: false } }) };
-  const frontmatter = parseTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8'));
-  const pr = Number(frontmatter.pr_number);
-  const prNumber = Number.isInteger(pr) && pr > 0 ? pr : null;
-  if (!prNumber) return { ok: false as const, output: checksResult('failed', { error: { code: 'PR_NOT_LINKED', message: 'Task has no valid pr_number', retryable: false } }) };
-  const client = (options.client as GitHubClient | undefined) || createGitHubClient();
-  const context = resolvePlatformContext({ cwd: resolved.repoRoot, client });
+  const frontmatter = parseTypedTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8'));
+  const fact = readPrDeliveryFact(frontmatter, options.runtimeVersion);
+  if (fact.status === 'invalid') return { ok: false as const, output: checksResult('failed', { error: { code: fact.error.code, message: fact.error.message, retryable: false } }) };
+  const prIdentity = fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.resource : null;
+  const prNumber = resourceIdentityNumber(prIdentity);
+  if (!prIdentity) return { ok: false as const, output: checksResult('failed', { error: { code: fact.status === 'missing' ? 'PR_DELIVERY_FACT_MISSING' : 'PR_NOT_LINKED', message: 'Task has no verified bound pull request', retryable: false } }) };
+  const loaded = await resolvePlatformProviderContext({ cwd: resolved.repoRoot, client: options.client });
+  const context = loaded.ok ? loaded.value.context : loaded.context;
   if (!context.platform.repository || !['no-op', 'degraded'].includes(context.status)) return { ok: false as const, output: checksResult(context.status, { platform: context.platform, capabilities: context.capabilities, error: context.error }) };
-  const inspected = inspectPlatformPullRequest(taskRef, { cwd: resolved.repoRoot, client });
+  const inspected = await inspectPlatformPullRequest(taskRef, { cwd: resolved.repoRoot, client: options.client });
   if (!inspected.pullRequest) return { ok: false as const, output: checksResult(inspected.status, { platform: context.platform, capabilities: context.capabilities, error: inspected.error }) };
-  return { ok: true as const, resolved, prNumber, client, context, pullRequest: inspected.pullRequest };
+  if (!loaded.ok) return { ok: false as const, output: checksResult('failed', { platform: context.platform, capabilities: context.capabilities, error: context.error }) };
+  return { ok: true as const, resolved, prNumber, prIdentity, client: options.client, context, pullRequest: inspected.pullRequest, provider: loaded.value.provider, loadedContext: loaded.value };
 }
 
-function inspectRequiredChecks(taskRef: string, options: InspectionOptions = {}): ChecksResult {
-  const base = resolvedTask(taskRef, options);
+async function inspectRequiredChecks(taskRef: string, options: InspectionOptions = {}): Promise<ChecksResult> {
+  const base = await resolvedTask(taskRef, options);
   if (!base.ok) return base.output;
   return inspectChecksForResolvedTask(base, options);
 }
 
-function inspectChecksForResolvedTask(
-  base: Extract<ReturnType<typeof resolvedTask>, { ok: true }>,
+async function inspectChecksForResolvedTask(
+  base: Extract<Awaited<ReturnType<typeof resolvedTask>>, { ok: true }>,
   options: InspectionOptions
-): ChecksResult {
+): Promise<ChecksResult> {
   const repository = base.context.platform.repository!;
-  const inspected = inspectPlatformRequiredChecks(base.context.platform.type, {
-    cwd: base.resolved.repoRoot,
-    repository,
-    number: base.prNumber,
-    headSha: base.pullRequest.head.sha,
-    client: options.client || base.client
-  });
-  if (!inspected.ok || !inspected.value) {
-    const error = inspected.error || {
-      code: 'REQUIRED_CHECKS_INSPECTION_INVALID',
-      message: 'Platform adapter returned no required-checks snapshot',
-      retryable: false
-    };
-    return checksResult(error.retryable ? 'blocked' : 'failed', {
-      platform: base.context.platform, capabilities: base.context.capabilities,
+  {
+    const inspected = base.provider.checks?.inspectRequired
+      ? await base.provider.checks.inspectRequired({
+        context: providerOperationContext(base.loadedContext),
+        changeRequest: base.prIdentity,
+        headSha: base.pullRequest.head.sha
+      })
+      : unsupportedProviderOperation(base.provider, 'checks.inspectRequired');
+    if (!inspected.ok) return checksResult(providerStatus(inspected.error), {
+      platform: base.context.platform,
+      capabilities: base.context.capabilities,
       resource: { kind: 'pull-request', number: base.prNumber },
-      pullRequest: base.pullRequest, error
+      pullRequest: base.pullRequest,
+      error: providerError(inspected.error, 'PLATFORM_PROVIDER_OPERATION_FAILED')
+    });
+    const required = normalizeChecks(inspected.value);
+    const classified = classifyRequiredChecks(required);
+    const status = classified.state === 'passed' || classified.state === 'no-required'
+      ? 'no-op'
+      : classified.state === 'failed' || classified.state === 'cancelled' ? 'failed' : 'blocked';
+    return checksResult(status, {
+      platform: base.context.platform, capabilities: base.context.capabilities,
+      resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: base.pullRequest,
+      checks: classified,
+      error: status === 'no-op' ? null : {
+        code: classified.state === 'pending' ? 'REQUIRED_CHECKS_PENDING' : `REQUIRED_CHECKS_${classified.state.toUpperCase()}`,
+        message: `Required checks are ${classified.state}`, retryable: classified.state === 'pending'
+      }
     });
   }
-  const classified = classifyRequiredChecks(inspected.value);
-  const status = classified.state === 'passed' || classified.state === 'no-required'
-    ? 'no-op'
-    : classified.state === 'failed' || classified.state === 'cancelled' ? 'failed' : 'blocked';
-  return checksResult(status, {
-    platform: base.context.platform, capabilities: base.context.capabilities,
-    resource: { kind: 'pull-request', number: base.prNumber },
-    pullRequest: base.pullRequest, checks: classified,
-    error: status === 'no-op' ? null : {
-      code: classified.state === 'pending' ? 'REQUIRED_CHECKS_PENDING' : `REQUIRED_CHECKS_${classified.state.toUpperCase()}`,
-      message: `Required checks are ${classified.state}`,
-      retryable: classified.state === 'pending'
-    }
-  });
 }
 
-function inspectPullRequestReadiness(taskRef: string, options: InspectionOptions = {}): ChecksResult {
-  const base = resolvedTask(taskRef, options);
+async function inspectPullRequestReadiness(taskRef: string, options: InspectionOptions = {}): Promise<ChecksResult> {
+  const base = await resolvedTask(taskRef, options);
   if (!base.ok) return base.output;
-  const checked = inspectChecksForResolvedTask(base, options);
+  const checked = await inspectChecksForResolvedTask(base, options);
   const classifiedCodes = new Set(['REQUIRED_CHECKS_PENDING', 'REQUIRED_CHECKS_FAILED', 'REQUIRED_CHECKS_CANCELLED']);
   if (checked.error && !classifiedCodes.has(checked.error.code)) return checked;
   const readiness = classifyPullRequestReadiness({
@@ -224,7 +226,7 @@ async function watchPullRequestReadiness(taskRef: string, options: InspectionOpt
       readiness: { state: 'cancelled', headSha: last?.pullRequest?.head.sha ?? '' },
       error: { code: 'PR_READINESS_CANCELLED', message: 'Pull request readiness watch was cancelled', retryable: false }
     });
-    last = inspectPullRequestReadiness(taskRef, options);
+    last = await inspectPullRequestReadiness(taskRef, options);
     if (last.readiness?.state !== 'pending' || last.error?.code !== 'PR_READINESS_PENDING') return last;
     const elapsed = now() - started;
     if (elapsed >= options.deadlineSeconds * 1000) return checksResult('blocked', {
@@ -237,33 +239,40 @@ async function watchPullRequestReadiness(taskRef: string, options: InspectionOpt
   }
 }
 
-function resolvePlatformCheckRun(taskRef: string, options: SharedOptions & { checkName: string; detailsUrl?: string }): ChecksResult {
-  const base = resolvedTask(taskRef, options);
+async function resolvePlatformCheckRun(taskRef: string, options: SharedOptions & { checkName: string; detailsUrl?: string }): Promise<ChecksResult> {
+  const base = await resolvedTask(taskRef, options);
   if (!base.ok) return base.output;
-  const direct = options.detailsUrl ? parseRunJobIdentity(options.detailsUrl) : null;
-  if (direct) {
-    const run = base.client.json<{ id?: number; head_sha?: string }>(['api', `repos/${base.context.platform.repository}/actions/runs/${direct.runId}`], { cwd: base.resolved.repoRoot });
-    if (!run.ok) return checksResult(run.error.retryable ? 'blocked' : 'failed', { platform: base.context.platform, capabilities: base.context.capabilities, pullRequest: base.pullRequest, error: run.error });
-    if (run.value.head_sha !== base.pullRequest.head.sha) return checksResult('failed', { error: { code: 'CHECK_RUN_HEAD_MISMATCH', message: 'Resolved run does not belong to the PR head SHA', retryable: false } });
-    return checksResult('no-op', { platform: base.context.platform, capabilities: base.context.capabilities, resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: base.pullRequest, resolution: { status: 'resolved', ...direct }, error: null });
+  {
+    const resolved = base.provider.checks?.resolveRun
+      ? await base.provider.checks.resolveRun({
+        context: providerOperationContext(base.loadedContext),
+        changeRequest: base.prIdentity,
+        checkName: options.checkName,
+        ...(options.detailsUrl ? { detailsUrl: options.detailsUrl } : {})
+      })
+      : unsupportedProviderOperation(base.provider, 'checks.resolveRun');
+    if (!resolved.ok) return checksResult(providerStatus(resolved.error), {
+      platform: base.context.platform, capabilities: base.context.capabilities,
+      resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: base.pullRequest,
+      error: providerError(resolved.error, 'PLATFORM_PROVIDER_OPERATION_FAILED')
+    });
+    const runId = Number(resolved.value.runId);
+    if (!Number.isSafeInteger(runId) || runId <= 0) return checksResult('failed', {
+      platform: base.context.platform, capabilities: base.context.capabilities,
+      resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: base.pullRequest,
+      error: { code: 'CHECK_RUN_IDENTITY_INVALID', message: 'Provider returned an invalid check run identity', retryable: false }
+    });
+    const jobId = resolved.value.jobId ? Number(resolved.value.jobId) : null;
+    return checksResult('no-op', {
+      platform: base.context.platform, capabilities: base.context.capabilities,
+      resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: base.pullRequest,
+      resolution: { status: 'resolved', runId, jobId: jobId !== null && Number.isSafeInteger(jobId) && jobId > 0 ? jobId : null }, error: null
+    });
   }
-  const listed = base.client.json<{ check_runs?: Array<{ name?: string; details_url?: string }> }>(['api', `repos/${base.context.platform.repository}/commits/${base.pullRequest.head.sha}/check-runs`], { cwd: base.resolved.repoRoot });
-  if (!listed.ok) return checksResult(listed.error.retryable ? 'blocked' : 'failed', { error: listed.error });
-  const candidates = (listed.value.check_runs || []).flatMap((check) => {
-    if (check.name !== options.checkName || !check.details_url) return [];
-    const identity = parseRunJobIdentity(check.details_url);
-    return identity ? [{ id: identity.runId, jobId: identity.jobId, name: check.name, headSha: base.pullRequest.head.sha }] : [];
-  });
-  const resolution = resolveRunCandidate(candidates, base.pullRequest.head.sha, options.checkName);
-  return checksResult(resolution.status === 'resolved' ? 'no-op' : 'failed', {
-    platform: base.context.platform, capabilities: base.context.capabilities,
-    resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: base.pullRequest,
-    resolution,
-    error: resolution.status === 'resolved' ? null : { code: resolution.status === 'ambiguous' ? 'CHECK_RUN_AMBIGUOUS' : 'CHECK_RUN_NOT_FOUND', message: `Check run is ${resolution.status}`, retryable: false }
-  });
 }
 
 function fetchCheckLogText(client: GitHubClient, args: string[], cwd: string) {
+  if (!client.text) return { ok: false as const, error: { code: 'PLATFORM_CLIENT_TEXT_UNAVAILABLE', message: 'Platform client does not support text responses', retryable: false } };
   const fetched = client.text(args, { cwd });
   if (fetched.ok || args[0] !== 'api' || !/response contains terminal escape sequences/i.test(fetched.error.message)) {
     return fetched;
@@ -271,20 +280,32 @@ function fetchCheckLogText(client: GitHubClient, args: string[], cwd: string) {
   return client.text([...args, '--allow-escape-sequences'], { cwd });
 }
 
-function fetchPlatformCheckLogs(taskRef: string, options: SharedOptions & { run: number; job?: number }): ChecksResult {
-  const base = resolvedTask(taskRef, options);
+async function fetchPlatformCheckLogs(taskRef: string, options: SharedOptions & { run: number; job?: number }): Promise<ChecksResult> {
+  const base = await resolvedTask(taskRef, options);
   if (!base.ok) return base.output;
-  const args = options.job
-    ? ['api', `repos/${base.context.platform.repository}/actions/jobs/${options.job}/logs`]
-    : ['run', 'view', String(options.run), '--repo', base.context.platform.repository!, '--log-failed'];
-  const fetched = fetchCheckLogText(base.client, args, base.resolved.repoRoot);
-  if (!fetched.ok) return checksResult(fetched.error.retryable ? 'blocked' : 'failed', { platform: base.context.platform, capabilities: base.context.capabilities, error: fetched.error });
-  if (!fetched.value) return checksResult('failed', { error: { code: 'CHECK_LOGS_MISSING', message: 'No failed logs are available', retryable: false } });
-  return checksResult('no-op', {
-    platform: base.context.platform, capabilities: base.context.capabilities,
-    resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: base.pullRequest,
-    logs: { runId: options.run, ...(options.job ? { jobId: options.job } : {}), text: fetched.value }, error: null
-  });
+  {
+    const fetched = base.provider.checks?.fetchLogs
+      ? await base.provider.checks.fetchLogs({
+        context: providerOperationContext(base.loadedContext),
+        runId: String(options.run),
+        ...(options.job ? { jobId: String(options.job) } : {})
+      })
+      : unsupportedProviderOperation(base.provider, 'checks.fetchLogs');
+    if (!fetched.ok) return checksResult(providerStatus(fetched.error), {
+      platform: base.context.platform, capabilities: base.context.capabilities,
+      resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: base.pullRequest,
+      error: providerError(fetched.error, 'PLATFORM_PROVIDER_OPERATION_FAILED')
+    });
+    if (!fetched.value.text) return checksResult('failed', {
+      platform: base.context.platform, capabilities: base.context.capabilities,
+      error: { code: 'CHECK_LOGS_MISSING', message: 'No failed logs are available', retryable: false }
+    });
+    return checksResult('no-op', {
+      platform: base.context.platform, capabilities: base.context.capabilities,
+      resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: base.pullRequest,
+      logs: { runId: options.run, ...(options.job ? { jobId: options.job } : {}), text: fetched.value.text }, error: null
+    });
+  }
 }
 
 export {
@@ -292,6 +313,7 @@ export {
   classifyRequiredChecks,
   fetchCheckLogText,
   fetchPlatformCheckLogs,
+  inspectGitHubRequiredChecks,
   inspectRequiredChecks,
   inspectPullRequestReadiness,
   parseRunJobIdentity,

package/lib/platform/pr-review.ts

@@ -1,23 +1,22 @@
-import { createGitHubClient } from './github-client.ts';
-import type { GitHubClient } from './github-client.ts';
-import { resolvePlatformContext } from './context.ts';
+import { resolvePlatformProviderContext } from './context.ts';
+import type { PlatformClient } from './context.ts';
 import { platformResult } from './types.ts';
 import type { PlatformOperation, PlatformResult } from './types.ts';
+import {
+  providerError,
+  providerOperationContext,
+  providerStatus,
+  providerResourceToken,
+  unsupportedProviderOperation
+} from './provider-bridge.ts';
+import { isResourceIdentity, resourceIdentityNumber, reviewMarker as resourceReviewMarker } from './resource-identity.ts';
+import type { ResourceIdentity } from './resource-identity.ts';
 
 export type PrReviewEvent = 'COMMENT' | 'APPROVE' | 'REQUEST_CHANGES';
-export type PrReviewIdentity = { scope: string; round: number; commitSha: string };
-export type PrReviewListEntry = { id: number; commitId: string; body: string; url: string };
+export type PrReviewIdentity = { scope: string; round: number; commitSha: string; resource?: ResourceIdentity };
+export type PrReviewListEntry = { id: number | string; commitId: string; body: string; url: string };
 export type PrReviewListResult = PlatformResult & { reviews: PrReviewListEntry[] };
 
-type RemoteReview = {
-  id?: number;
-  node_id?: string;
-  commit_id?: string;
-  body?: string | null;
-  state?: string;
-  html_url?: string;
-};
-
 const REVIEW_EVENTS: readonly PrReviewEvent[] = ['COMMENT', 'APPROVE', 'REQUEST_CHANGES'];
 // Marker-safe scope: a task id (`TASK-YYYYMMDD-HHMMSS`) or a bare PR number
 // (`pr{N}`). Any other value (e.g. one containing `\r\n` or `-->`) would break
@@ -25,7 +24,10 @@ const REVIEW_EVENTS: readonly PrReviewEvent[] = ['COMMENT', 'APPROVE', 'REQUEST_
 const REVIEW_SCOPE_PATTERN = /^(?:pr\d+|TASK-\d{8}-\d{6})$/;
 
 export function reviewMarker(identity: PrReviewIdentity): string {
-  return `<!-- review-pr:${identity.scope}:r${identity.round} -->`;
+  const scope = identity.resource && isResourceIdentity(identity.resource) && identity.resource.kind !== 'number'
+    ? resourceReviewMarker(identity.resource)
+    : identity.scope;
+  return `<!-- review-pr:${scope}:r${identity.round} -->`;
 }
 
 export function reviewedCommitMarker(sha: string): string {
@@ -44,105 +46,98 @@ function hasUsableContext(context: PlatformResult): boolean {
   return (context.status === 'no-op' || context.status === 'degraded') && context.platform.repository !== null;
 }
 
-function invalidPrNumber(prNumber: number): boolean {
-  return !Number.isInteger(prNumber) || prNumber <= 0;
-}
+type PrToken = string | number;
 
-export function listPrReviews(prNumber: number, options: { cwd?: string; client?: GitHubClient } = {}): PrReviewListResult {
-  const client = options.client || createGitHubClient();
-  const context = resolvePlatformContext({ cwd: options.cwd || process.cwd(), client });
+export async function listPrReviews(prNumber: PrToken, options: { cwd?: string; client?: PlatformClient } = {}): Promise<PrReviewListResult> {
+  const loaded = await resolvePlatformProviderContext({ cwd: options.cwd || process.cwd(), client: options.client });
+  const context = loaded.ok ? loaded.value.context : loaded.context;
   if (!hasUsableContext(context)) {
     return { ...platformResult(context.status, { platform: context.platform, capabilities: context.capabilities, error: context.error }), reviews: [] };
   }
-  const repository = context.platform.repository!;
-  if (invalidPrNumber(prNumber)) {
+  const identity = loaded.ok ? (() => { try { return providerResourceToken(loaded.value.provider, 'pull-request', String(prNumber)); } catch { return null; } })() : null;
+  if (!identity) {
     return {
       ...platformResult('failed', {
         platform: context.platform, capabilities: context.capabilities,
-        error: { code: 'PR_NUMBER_INVALID', message: 'PR number must be positive', retryable: false }
+        error: { code: 'PLATFORM_IDENTITY_TOKEN_INVALID', message: 'Pull request token is invalid', retryable: false }
       }),
       reviews: []
     };
   }
-  const fetched = client.json<RemoteReview[]>(['api', '--paginate', '--slurp', `repos/${repository}/pulls/${prNumber}/reviews?per_page=100`], { cwd: options.cwd || process.cwd() });
-  if (!fetched.ok) {
+  const identityNumber = resourceIdentityNumber(identity);
+  if (loaded.ok) {
+    const fetched = loaded.value.provider.reviews?.list
+      ? await loaded.value.provider.reviews.list({ context: providerOperationContext(loaded.value), changeRequest: identity })
+      : unsupportedProviderOperation(loaded.value.provider, 'reviews.list');
+    if (!fetched.ok) return {
+      ...platformResult(providerStatus(fetched.error), {
+        platform: context.platform, capabilities: context.capabilities,
+        resource: { kind: 'pull-request', number: identityNumber, identity }, error: providerError(fetched.error, 'PLATFORM_PROVIDER_OPERATION_FAILED')
+      }), reviews: []
+    };
     return {
-      ...platformResult(fetched.error.retryable ? 'blocked' : 'failed', {
+      ...platformResult('no-op', {
         platform: context.platform, capabilities: context.capabilities,
-        resource: { kind: 'pull-request', number: prNumber }, error: fetched.error
+        resource: { kind: 'pull-request', number: identityNumber, identity }, error: null
       }),
-      reviews: []
+      reviews: fetched.value.map((review) => ({ id: review.id, commitId: review.commitSha || '', body: review.body, url: review.displayUrl || '' }))
     };
   }
-  const flat = (fetched.value || []).flatMap((entry) => Array.isArray(entry) ? entry : [entry]);
-  const reviews: PrReviewListEntry[] = flat
-    .map((review) => ({
-      id: review.id ?? 0,
-      commitId: review.commit_id ?? '',
-      body: review.body ?? '',
-      url: review.html_url ?? ''
-    }))
-    .filter((review) => review.body !== '');
-  return {
-    ...platformResult('no-op', {
-      platform: context.platform, capabilities: context.capabilities,
-      resource: { kind: 'pull-request', number: prNumber }, error: null
-    }),
-    reviews
-  };
+  return { ...platformResult('failed', { platform: context.platform, capabilities: context.capabilities, error: context.error }), reviews: [] };
 }
 
-export function publishPrReview(options: {
+export async function publishPrReview(options: {
   cwd?: string;
-  client?: GitHubClient;
+  client?: PlatformClient;
   dryRun?: boolean;
-  prNumber: number;
+  prNumber: PrToken;
   identity: PrReviewIdentity;
   event: PrReviewEvent;
   body: string;
-}): PlatformResult {
-  const client = options.client || createGitHubClient();
-  const context = resolvePlatformContext({ cwd: options.cwd || process.cwd(), client });
+}): Promise<PlatformResult> {
+  const loaded = await resolvePlatformProviderContext({ cwd: options.cwd || process.cwd(), client: options.client });
+  const context = loaded.ok ? loaded.value.context : loaded.context;
   if (!hasUsableContext(context)) {
     return platformResult(context.status, { platform: context.platform, capabilities: context.capabilities, error: context.error });
   }
-  const repository = context.platform.repository!;
-  if (invalidPrNumber(options.prNumber)) {
+  const identity = loaded.ok ? (() => { try { return providerResourceToken(loaded.value.provider, 'pull-request', String(options.prNumber)); } catch { return null; } })() : null;
+  if (!identity) {
     return platformResult('failed', {
       platform: context.platform, capabilities: context.capabilities,
-      error: { code: 'PR_NUMBER_INVALID', message: 'PR number must be positive', retryable: false }
+      error: { code: 'PLATFORM_IDENTITY_TOKEN_INVALID', message: 'Pull request token is invalid', retryable: false }
     });
   }
+  const identityNumber = resourceIdentityNumber(identity);
   if (!REVIEW_EVENTS.includes(options.event)) {
     return platformResult('failed', {
       platform: context.platform, capabilities: context.capabilities,
-      resource: { kind: 'pull-request', number: options.prNumber },
+      resource: { kind: 'pull-request', number: identityNumber, identity },
       error: { code: 'REVIEW_EVENT_INVALID', message: `review event must be one of ${REVIEW_EVENTS.join('|')}`, retryable: false }
     });
   }
   if (!REVIEW_SCOPE_PATTERN.test(options.identity.scope) || !/^[0-9a-f]{7,40}$/i.test(options.identity.commitSha)) {
     return platformResult('failed', {
       platform: context.platform, capabilities: context.capabilities,
-      resource: { kind: 'pull-request', number: options.prNumber },
+      resource: { kind: 'pull-request', number: identityNumber, identity },
       error: { code: 'REVIEW_IDENTITY_INVALID', message: 'review scope must be a task id or pr{N}; commitSha is required', retryable: false }
     });
   }
 
-  const marker = reviewMarker(options.identity);
-  const listed = listPrReviews(options.prNumber, { cwd: options.cwd, client });
+  const marker = reviewMarker({ ...options.identity, resource: identity });
+  const listed = await listPrReviews(options.prNumber, { cwd: options.cwd, client: options.client });
   if (listed.status === 'failed' || listed.status === 'blocked') return listed;
   const existing = listed.reviews.find((review) => firstLine(review.body) === marker) ?? null;
   if (existing) {
     if (existing.commitId === options.identity.commitSha) {
       return platformResult('no-op', {
         platform: context.platform, capabilities: context.capabilities,
-        resource: { kind: 'pull-request', number: options.prNumber },
+        resource: { kind: 'pull-request', number: identityNumber, identity },
         operations: [{ name: 'review:publish', status: 'no-op', reasonCode: null }], error: null
       });
     }
     return platformResult('failed', {
       platform: context.platform, capabilities: context.capabilities,
-      resource: { kind: 'pull-request', number: options.prNumber },
+      resource: { kind: 'pull-request', number: identityNumber, identity },
       operations: [{ name: 'review:publish', status: 'failed', reasonCode: 'REVIEW_MARKER_CONFLICT' }],
       error: { code: 'REVIEW_MARKER_CONFLICT', message: 'A review with the same marker targets a different commit; start a new round', retryable: false }
     });
@@ -159,43 +154,51 @@ export function publishPrReview(options: {
   if (options.dryRun) {
     return platformResult('planned', {
       platform: context.platform, capabilities: context.capabilities,
-      resource: { kind: 'pull-request', number: options.prNumber },
+      resource: { kind: 'pull-request', number: identityNumber, identity },
       operations: [{ name: 'review:publish', status: 'planned', reasonCode: null }], error: null
     });
   }
 
-  const posted = client.json<RemoteReview>(['api', `repos/${repository}/pulls/${options.prNumber}/reviews`, '-X', 'POST', '--input', '-'], {
-    cwd: options.cwd || process.cwd(),
-    method: 'POST',
-    input: JSON.stringify({ commit_id: options.identity.commitSha, body: wrappedBody, event: options.event })
-  });
-  if (!posted.ok) {
-    if (posted.error.retryable) {
-      const reconciled = listPrReviews(options.prNumber, { cwd: options.cwd, client });
-      const found = reconciled.reviews.find((review) => firstLine(review.body) === marker);
-      if (found) {
-        return platformResult('applied', {
+  if (loaded.ok) {
+    const published = loaded.value.provider.reviews?.publish
+      ? await loaded.value.provider.reviews.publish({
+        context: providerOperationContext(loaded.value),
+        changeRequest: identity,
+        identity: options.identity,
+        event: options.event,
+        body: wrappedBody,
+        mutation: { idempotencyKey: `review:publish:${marker}` }
+      })
+      : unsupportedProviderOperation(loaded.value.provider, 'reviews.publish');
+    if (!published.ok) {
+      if (published.error.retryable) {
+        const reconciled = await listPrReviews(options.prNumber, { cwd: options.cwd, client: options.client });
+        const found = reconciled.reviews.find((review) => firstLine(review.body) === marker);
+        if (found) return platformResult('applied', {
           changed: true, platform: context.platform, capabilities: context.capabilities,
-          resource: { kind: 'pull-request', number: options.prNumber },
+          resource: { kind: 'pull-request', number: identityNumber, identity },
           operations: [{ name: 'review:publish', status: 'applied', reasonCode: 'CREATE_RECONCILED' }], error: null
         });
+        return platformResult('blocked', {
+          platform: context.platform, capabilities: context.capabilities,
+          resource: { kind: 'pull-request', number: identityNumber, identity },
+          operations: [{ name: 'review:publish', status: 'failed', reasonCode: 'REVIEW_CREATE_OUTCOME_UNKNOWN' }],
+          error: { code: 'REVIEW_CREATE_OUTCOME_UNKNOWN', message: published.error.message, retryable: true }
+        });
       }
-      return platformResult('blocked', {
+      return platformResult(providerStatus(published.error), {
         platform: context.platform, capabilities: context.capabilities,
-        resource: { kind: 'pull-request', number: options.prNumber },
-        operations: [{ name: 'review:publish', status: 'failed', reasonCode: 'REVIEW_CREATE_OUTCOME_UNKNOWN' }],
-        error: { code: 'REVIEW_CREATE_OUTCOME_UNKNOWN', message: posted.error.message, retryable: true }
+        resource: { kind: 'pull-request', number: identityNumber, identity },
+        operations: [{ name: 'review:publish', status: 'failed', reasonCode: published.error.code }],
+        error: providerError(published.error, 'PLATFORM_PROVIDER_OPERATION_FAILED')
       });
     }
-    return platformResult('failed', {
+    return platformResult('applied', {
+      changed: published.value.changed,
       platform: context.platform, capabilities: context.capabilities,
-      resource: { kind: 'pull-request', number: options.prNumber },
-      operations: [{ name: 'review:publish', status: 'failed', reasonCode: posted.error.code }], error: posted.error
+      resource: { kind: 'pull-request', number: identityNumber, identity },
+      operations: [{ name: 'review:publish', status: 'applied', reasonCode: null }], error: null
     });
   }
-  return platformResult('applied', {
-    changed: true, platform: context.platform, capabilities: context.capabilities,
-    resource: { kind: 'pull-request', number: options.prNumber },
-    operations: [{ name: 'review:publish', status: 'applied', reasonCode: null }], error: null
-  });
+  return platformResult('failed', { platform: context.platform, capabilities: context.capabilities, error: context.error });
 }