@fitlab-ai/agent-infra 0.9.12 → 0.9.13

package/lib/platform/release-notes.ts

@@ -3,21 +3,22 @@ import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 
-import { resolvePlatformContext } from './context.ts';
-import {
-  fetchGitHubReleaseNoteData,
-  publishGitHubReleaseNotes
-} from './github-release-notes.ts';
-import type { ReleaseNoteActor } from './github-release-notes.ts';
-import type { GitHubClient } from './github-client.ts';
+import { resolvePlatformProviderContext } from './context.ts';
+import type { PlatformClient } from './context.ts';
+import { providerError, providerOperationContext, providerStatus, unsupportedProviderOperation } from './provider-bridge.ts';
+import { resourceIdentityNumber } from './resource-identity.ts';
+import type { ResourceIdentity } from './resource-identity.ts';
 
 type ReleaseNoteOptions = {
   cwd?: string;
   platformType?: string;
-  client?: GitHubClient;
+  client?: PlatformClient;
 };
 
+type ReleaseNoteActor = { id?: string; name?: string };
 type ReleaseNoteCommit = { oid: string; title: string; authors: ReleaseNoteActor[] };
+type ReleaseNoteIssue = { number: number; identity?: ResourceIdentity; title: string; url: string; labels: string[]; author: { login: string; bot: boolean } | null };
+type ReleaseNotePullRequest = { number: number; identity?: ResourceIdentity; title: string; body: string; url: string; mergedAt: string; labels: string[]; author: { login: string; bot: boolean } | null; closingIssues: ReleaseNoteIssue[] };
 
 const unsupportedError = {
   code: 'PLATFORM_RELEASE_NOTES_UNSUPPORTED',
@@ -130,7 +131,7 @@ function configuredPlatform(cwd: string): string | null {
   }
 }
 
-function releaseNoteContext(
+async function releaseNoteContext(
   input: { fromTag: string; toTag: string; branch: string; historyLimit?: number },
   options: ReleaseNoteOptions = {}
 ) {
@@ -140,7 +141,13 @@ function releaseNoteContext(
   }
   const cwd = path.resolve(options.cwd || process.cwd());
   const platformType = options.platformType ?? configuredPlatform(cwd);
-  if (platformType !== 'github') return baseResult('no-op');
+  const loaded = await resolvePlatformProviderContext({ cwd, platformType: platformType || undefined, client: options.client });
+  if (!loaded.ok) {
+    if (loaded.context.status === 'no-op') return baseResult('no-op');
+    const status = loaded.context.status === 'blocked' ? 'blocked' : 'failed';
+    return { ...baseResult(status), error: loaded.context.error };
+  }
+  if (!loaded.value.context.platform.repository) return baseResult('no-op');
   let fromOid: string;
   let toOid: string;
   let fromTime: string;
@@ -160,75 +167,61 @@ function releaseNoteContext(
   } catch {
     return { ...baseResult('failed'), error: { code: 'RELEASE_NOTES_RANGE_INVALID', message: 'The release tag range is missing or is not ancestral', retryable: false } };
   }
-  const context = resolvePlatformContext({ cwd, platformType, client: options.client });
-  if (!context.platform.repository) {
-    return {
-      ...baseResult(context.status === 'blocked' ? 'blocked' : 'failed'),
-      error: context.error || { code: 'PLATFORM_CONTEXT_UNAVAILABLE', message: 'Platform repository is unavailable', retryable: context.status === 'blocked' }
-    };
-  }
-  const platform = fetchGitHubReleaseNoteData(
-    {
-      repository: context.platform.repository,
+  const platform = loaded.value.provider.releases?.collectNotes
+    ? await loaded.value.provider.releases.collectNotes({
+      context: providerOperationContext(loaded.value),
       commitOids: commitFacts.map((item) => item.oid),
       branch: input.branch,
       historyLimit,
       fromTime,
       toTime
-    },
-    { cwd, client: options.client }
-  );
-  if (platform.status === 'blocked' || platform.status === 'failed' || !('authors' in platform)) {
-    return { ...baseResult(platform.status), error: platform.error };
-  }
+    })
+    : unsupportedProviderOperation(loaded.value.provider, 'releases.collectNotes');
+  if (!platform.ok) return { ...baseResult(platform.error.retryable ? 'blocked' : 'failed'), error: providerError(platform.error, 'PLATFORM_PROVIDER_OPERATION_FAILED') };
   const commits = commitFacts.map((commit) => {
     const seen = new Set<string>();
-    const authors = (platform.authors.get(commit.oid) || []).filter((actor) => {
-      const key = actor.login || actor.email?.toLowerCase() || actor.name.toLowerCase();
+    const authors = platform.value.history.filter((item) => item.sha === commit.oid).flatMap((item) => item.author ? [item.author] : [])
+      .concat(platform.value.actors)
+      .filter((actor) => {
+      const key = actor.id || actor.name || '';
       if (seen.has(key)) return false;
       seen.add(key);
       return true;
-    });
+      });
     return { ...commit, authors };
   });
-  const pullRequests = platform.pullRequests
+  const pullRequests: ReleaseNotePullRequest[] = platform.value.mergedPullRequests
     .map((item) => ({
-      number: Number(item.number),
-      title: String(item.title || ''),
-      body: String(item.body || ''),
-      url: String(item.url || ''),
-      mergedAt: String(item.mergedAt || ''),
-      labels: Array.isArray(item.labels) ? item.labels.map((label) => String((label as { name?: string }).name || label)) : [],
-      author: item.author && typeof item.author === 'object'
-        ? { login: String((item.author as { login?: string }).login || '').toLowerCase(), bot: String((item.author as { login?: string }).login || '').endsWith('[bot]') }
-        : null,
-      closingIssues: Array.isArray(item.closingIssuesReferences)
-        ? item.closingIssuesReferences.map((issue) => {
-          const value = issue as Record<string, unknown>;
-          return {
-            number: Number(value.number),
-            title: String(value.title || ''),
-            url: String(value.url || ''),
-            labels: Array.isArray(value.labels) ? value.labels.map((label) => String((label as { name?: string }).name || label)) : [],
-            author: value.author && typeof value.author === 'object'
-              ? { login: String((value.author as { login?: string }).login || '').toLowerCase(), bot: String((value.author as { login?: string }).login || '').endsWith('[bot]') }
-              : null
-          };
-        }) : []
+      number: item.number || resourceIdentityNumber(item.identity) || 0,
+      ...(item.identity ? { identity: item.identity } : {}),
+      title: item.title,
+      body: item.body,
+      url: item.displayUrl || '',
+      mergedAt: item.mergedAt || '',
+      labels: item.labels || [],
+      author: item.author ? { login: item.author.name || item.author.id || '', bot: false } : null,
+      closingIssues: platform.value.closingIssues.filter((issue) => issue.id === item.id).map((issue) => ({
+        number: issue.number || resourceIdentityNumber(issue.identity) || 0,
+        ...(issue.identity ? { identity: issue.identity } : {}),
+        title: issue.title,
+        url: issue.displayUrl || '',
+        labels: issue.labels || [],
+        author: issue.author ? { login: issue.author.name || issue.author.id || '', bot: false } : null
+      }))
     }))
     .sort((left, right) => left.number - right.number);
   return {
     status: 'no-op' as const,
     changed: false,
     range: { fromTag: input.fromTag, toTag: input.toTag, fromOid, toOid },
-    history: platform.history,
+    history: platform.value.history,
     pullRequests,
     commits,
     error: null
   };
 }
 
-function publishReleaseNotes(
+async function publishReleaseNotes(
   input: { tag: string; title: string; notesFile: string; expectedSha256: string; dryRun?: boolean },
   options: ReleaseNoteOptions = {}
 ) {
@@ -246,12 +239,36 @@ function publishReleaseNotes(
   }
   const cwd = path.resolve(options.cwd || process.cwd());
   const platformType = options.platformType ?? configuredPlatform(cwd);
-  if (platformType !== 'github') return { status: 'no-op' as const, changed: false, operation: null, url: null, error: unsupportedError };
-  const context = resolvePlatformContext({ cwd, platformType, client: options.client });
-  if (!context.platform.repository) {
-    return { status: context.status === 'blocked' ? 'blocked' as const : 'failed' as const, changed: false, operation: null, url: null, error: context.error };
+  const loaded = await resolvePlatformProviderContext({ cwd, platformType: platformType || undefined, client: options.client });
+  if (!loaded.ok) {
+    const status = loaded.context.status === 'blocked'
+      ? 'blocked'
+      : loaded.context.status === 'no-op' ? 'no-op' : 'failed';
+    return {
+      ...baseResult(status),
+      error: loaded.context.error || { code: 'PLATFORM_PROVIDER_LOAD_FAILED', message: 'Selected provider failed to load', retryable: false }
+    };
+  }
+  if (loaded.ok) {
+    const context = loaded.value.context;
+    if (!context.platform.repository) return { status: context.status === 'blocked' ? 'blocked' as const : 'failed' as const, changed: false, operation: null, url: null, error: context.error };
+    const published = loaded.value.provider.releases?.publishNotes
+      ? await loaded.value.provider.releases.publishNotes({
+        context: providerOperationContext(loaded.value),
+        release: { kind: 'key', value: input.tag },
+        title: input.title,
+        notes: {
+          text: fs.readFileSync(input.notesFile, 'utf8'),
+          sha256: actualSha256,
+          byteLength: fs.statSync(input.notesFile).size
+        },
+        mutation: { idempotencyKey: `release-notes:publish:${input.tag}` }
+      })
+      : unsupportedProviderOperation(loaded.value.provider, 'releases.publishNotes');
+    if (!published.ok) return { status: providerStatus(published.error), changed: false, operation: null, url: null, error: providerError(published.error, 'PLATFORM_PROVIDER_OPERATION_FAILED') };
+    return { status: 'applied' as const, changed: published.value.changed, operation: 'publish-notes', url: null, error: null };
   }
-  return publishGitHubReleaseNotes({ ...input, repository: context.platform.repository }, { cwd, client: options.client });
+  return { status: 'failed' as const, changed: false, operation: null, url: null, error: { code: 'PLATFORM_PROVIDER_LOAD_FAILED', message: 'Selected provider failed to load', retryable: false } };
 }
 
 export {

package/lib/platform/releases.ts

@@ -1,52 +1,78 @@
-import { createGitHubClient } from './github-client.ts';
-import type { GitHubClient } from './github-client.ts';
-import { resolvePlatformContext } from './context.ts';
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { resolvePlatformProviderContext } from './context.ts';
+import type { PlatformClient } from './context.ts';
 import { platformResult } from './types.ts';
+import { providerError, providerOperationContext, providerStatus, unsupportedProviderOperation } from './provider-bridge.ts';
 
 type ReleaseSnapshot = { tag: string; published: boolean; draft: boolean; url: string | null };
-type ReleaseOptions = { cwd?: string; client?: GitHubClient };
+type ReleaseOptions = { cwd?: string; client?: PlatformClient };
 
 function flattenPages(value: unknown): Array<Record<string, unknown>> {
   if (!Array.isArray(value)) return [];
   return value.flatMap((entry) => Array.isArray(entry) ? entry : [entry]).filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === 'object');
 }
 
-function inspectPlatformRelease(tag: string, options: ReleaseOptions = {}) {
-  const client = options.client ?? createGitHubClient();
-  const context = resolvePlatformContext({ cwd: options.cwd, client });
+async function inspectPlatformRelease(tag: string, options: ReleaseOptions = {}) {
+  const loaded = await resolvePlatformProviderContext({ cwd: options.cwd, client: options.client });
+  const context = loaded.ok ? loaded.value.context : loaded.context;
   if (!context.platform.repository) return { ...platformResult(context.status), platform: context.platform, release: null, workflows: [], error: context.error };
-  const result = client.json<Record<string, unknown>>(['release', 'view', tag, '--repo', context.platform.repository, '--json', 'tagName,isDraft,url'], { cwd: options.cwd });
-  if (!result.ok) {
-    if (result.error.code === 'RESOURCE_NOT_FOUND') return { ...platformResult('no-op'), platform: context.platform, release: null, workflows: [], error: null };
-    return { ...platformResult(result.error.retryable ? 'blocked' : 'failed'), platform: context.platform, release: null, workflows: [], error: result.error };
+  if (loaded.ok) {
+    const inspected = loaded.value.provider.releases?.inspect
+      ? await loaded.value.provider.releases.inspect({ context: providerOperationContext(loaded.value), tag })
+      : unsupportedProviderOperation(loaded.value.provider, 'releases.inspect');
+    if (!inspected.ok) {
+      if (inspected.error.code === 'RESOURCE_NOT_FOUND') return { ...platformResult('no-op'), platform: context.platform, release: null, workflows: [], error: null };
+      return { ...platformResult(providerStatus(inspected.error)), platform: context.platform, release: null, workflows: [], error: providerError(inspected.error, 'PLATFORM_PROVIDER_OPERATION_FAILED') };
+    }
+    return {
+      ...platformResult('no-op'),
+      platform: context.platform,
+      release: { tag: inspected.value.tag, published: !inspected.value.draft, draft: inspected.value.draft, url: inspected.value.displayUrl || null },
+      workflows: inspected.value.workflows || [],
+      error: null
+    };
   }
-  const release: ReleaseSnapshot = { tag: String(result.value.tagName || tag), published: !Boolean(result.value.isDraft), draft: Boolean(result.value.isDraft), url: result.value.url ? String(result.value.url) : null };
-  const runs = client.json<unknown[]>(['run', 'list', '--repo', context.platform.repository, '--limit', '100', '--json', 'name,workflowName,displayTitle,event,headBranch,headSha,status,conclusion,createdAt,databaseId,attempt,url'], { cwd: options.cwd });
-  return { ...platformResult(runs.ok ? 'no-op' : runs.error.retryable ? 'blocked' : 'degraded'), platform: context.platform, release, workflows: runs.ok ? runs.value : [], error: runs.ok ? null : runs.error };
+  return { ...platformResult('failed'), platform: context.platform, release: null, workflows: [], error: context.error };
 }
 
-function upsertPlatformRelease(input: { tag: string; title?: string; notesFile?: string }, options: ReleaseOptions = {}) {
-  const inspected = inspectPlatformRelease(input.tag, options);
+async function upsertPlatformRelease(input: { tag: string; title?: string; notesFile?: string }, options: ReleaseOptions = {}) {
+  const inspected = await inspectPlatformRelease(input.tag, options);
   if (inspected.release?.published) return { ...inspected, status: 'no-op' as const, changed: false, operations: [] };
   if (inspected.status === 'blocked' || inspected.status === 'failed') return { ...inspected, changed: false, operations: [] };
   if (!inspected.platform.repository) return { ...inspected, status: 'no-op' as const, changed: false, operations: [] };
-  const client = options.client ?? createGitHubClient();
-  const args = ['release', 'create', input.tag, '--repo', inspected.platform.repository!, '--title', input.title ?? input.tag];
-  if (input.notesFile) args.push('--notes-file', input.notesFile); else args.push('--generate-notes');
-  const created = client.text(args, { cwd: options.cwd, method: 'POST' });
-  if (!created.ok) return { ...inspected, status: created.error.retryable ? 'blocked' as const : 'failed' as const, changed: false, operations: [{ name: 'create-release', status: 'failed' }], error: created.error };
-  return { ...inspectPlatformRelease(input.tag, options), status: 'applied' as const, changed: true, operations: [{ name: 'create-release', status: 'applied' }] };
+  const loaded = await resolvePlatformProviderContext({ cwd: options.cwd, client: options.client });
+  if (loaded.ok) {
+    let notes: { text: string; sha256: string; byteLength: number } | undefined;
+    if (input.notesFile) {
+      try {
+        const bytes = fs.readFileSync(input.notesFile);
+        notes = { text: bytes.toString('utf8'), sha256: `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`, byteLength: bytes.byteLength };
+      } catch {
+        return { ...inspected, status: 'failed' as const, changed: false, operations: [{ name: 'create-release', status: 'failed' }], error: { code: 'RELEASE_NOTES_FILE_UNREADABLE', message: 'notes-file could not be read', retryable: false } };
+      }
+    }
+    const created = loaded.value.provider.releases?.create
+      ? await loaded.value.provider.releases.create({
+        context: providerOperationContext(loaded.value),
+        tag: input.tag,
+        title: input.title ?? input.tag,
+        ...(notes ? { notes } : {}),
+        mutation: { idempotencyKey: `release:create:${input.tag}` }
+      })
+      : unsupportedProviderOperation(loaded.value.provider, 'releases.create');
+    if (!created.ok) return { ...inspected, status: providerStatus(created.error), changed: false, operations: [{ name: 'create-release', status: 'failed' }], error: providerError(created.error, 'PLATFORM_PROVIDER_OPERATION_FAILED') };
+    return { ...inspected, status: 'applied' as const, changed: created.value.changed, operations: [{ name: 'create-release', status: 'applied' }], error: null };
+  }
+  return { ...inspected, status: 'failed' as const, changed: false, operations: [{ name: 'create-release', status: 'failed' }], error: { code: 'PLATFORM_PROVIDER_LOAD_FAILED', message: 'Selected provider failed to load', retryable: false } };
 }
 
-function reconcileReleaseMilestones(version: string, options: ReleaseOptions = {}) {
+async function reconcileReleaseMilestones(version: string, options: ReleaseOptions = {}) {
   const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
   if (!match) return { status: 'failed' as const, changed: false, operations: [], error: { code: 'RELEASE_VERSION_INVALID', message: `Invalid version '${version}'` } };
-  const client = options.client ?? createGitHubClient();
-  const context = resolvePlatformContext({ cwd: options.cwd, client });
+  const loaded = await resolvePlatformProviderContext({ cwd: options.cwd, client: options.client });
+  const context = loaded.ok ? loaded.value.context : loaded.context;
   if (!context.platform.repository) return { ...platformResult(context.status), changed: false, operations: [], error: context.error };
-  const listed = client.json<unknown>(['api', '--paginate', '--slurp', `repos/${context.platform.repository}/milestones?state=all&per_page=100`], { cwd: options.cwd });
-  if (!listed.ok) return { ...platformResult(listed.error.retryable ? 'blocked' : 'failed'), changed: false, operations: [], error: listed.error };
-  const milestones = flattenPages(listed.value).map((item) => ({ title: String(item.title || ''), number: Number(item.number), state: String(item.state || '') }));
   const major = Number(match[1]); const minor = Number(match[2]); const patch = Number(match[3]);
   const nextPatch = `${major}.${minor}.${patch + 1}`;
   const currentLine = `${major}.${minor}.x`;
@@ -62,22 +88,30 @@ function reconcileReleaseMilestones(version: string, options: ReleaseOptions = {
       { title: nextLine, description: `Issues that we want to resolve in ${major}.${minor + 1} line.` }
     );
   }
-  const operations: Array<{ name: string; title: string; status: 'applied' | 'no-op' | 'failed' }> = [];
-  const current = milestones.find((item) => item.title === version);
-  if (current && current.state !== 'closed') {
-    const closed = client.json(['api', '--method', 'PATCH', `repos/${context.platform.repository}/milestones/${current.number}`, '-f', 'state=closed'], { cwd: options.cwd });
-    operations.push({ name: 'close-milestone', title: version, status: closed.ok ? 'applied' : 'failed' });
-  } else operations.push({ name: 'close-milestone', title: version, status: 'no-op' });
-  for (const { title, description } of ensure) {
-    if (milestones.some((item) => item.title === title)) operations.push({ name: 'ensure-milestone', title, status: 'no-op' });
-    else {
-      const created = client.json(['api', '--method', 'POST', `repos/${context.platform.repository}/milestones`, '-f', `title=${title}`, '-f', `description=${description}`], { cwd: options.cwd });
-      operations.push({ name: 'ensure-milestone', title, status: created.ok ? 'applied' : 'failed' });
-    }
+  if (loaded.ok) {
+    const reconciled = loaded.value.provider.releases?.reconcileMilestones
+      ? await loaded.value.provider.releases.reconcileMilestones({
+        context: providerOperationContext(loaded.value),
+        version,
+        desired: [
+          { key: version, title: version, description: `Issues that we want to resolve in v${version}.`, state: 'closed' },
+          ...ensure.map((item) => ({ key: item.title, title: item.title, description: item.description, state: 'open' as const }))
+        ],
+        mutation: { idempotencyKey: `milestones:reconcile:${version}` }
+      })
+      : unsupportedProviderOperation(loaded.value.provider, 'releases.reconcileMilestones');
+    if (!reconciled.ok) return { status: providerStatus(reconciled.error), changed: false, operations: [], error: providerError(reconciled.error, 'PLATFORM_PROVIDER_OPERATION_FAILED') };
+    return {
+      status: reconciled.value.changed ? 'applied' as const : 'no-op' as const,
+      changed: reconciled.value.changed,
+      operations: [
+        ...reconciled.value.closed.map((title) => ({ name: 'close-milestone', title, status: 'applied' as const })),
+        ...reconciled.value.created.map((title) => ({ name: 'ensure-milestone', title, status: 'applied' as const }))
+      ],
+      error: null
+    };
   }
-  const failed = operations.some((operation) => operation.status === 'failed');
-  const changed = operations.some((operation) => operation.status === 'applied');
-  return { status: failed ? 'failed' as const : changed ? 'applied' as const : 'no-op' as const, changed, operations, error: failed ? { code: 'MILESTONE_RECONCILE_FAILED', message: 'One or more milestone operations failed' } : null };
+  return { status: 'failed' as const, changed: false, operations: [], error: { code: 'PLATFORM_CAPABILITY_UNSUPPORTED', message: 'Release milestone reconciliation is unavailable', retryable: false } };
 }
 
 export { inspectPlatformRelease, reconcileReleaseMilestones, upsertPlatformRelease };

package/lib/platform/resource-identity.ts

@@ -0,0 +1,121 @@
+type ResourceIdentityKind = 'id' | 'number' | 'key';
+type ResourceIdentity =
+  | { kind: 'id'; value: string }
+  | { kind: 'number'; value: number }
+  | { kind: 'key'; value: string };
+type CanonicalResourceIdentity = ResourceIdentity;
+
+type PlatformResourceKind = 'issue' | 'pull-request' | 'comment' | 'release';
+type ProviderIdentityDeclaration = Partial<Record<PlatformResourceKind, ResourceIdentityKind>>;
+
+function identityError(message: string): Error & { code: string } {
+  return Object.assign(new Error(`PLATFORM_IDENTITY_INVALID: ${message}`), {
+    code: 'PLATFORM_IDENTITY_INVALID'
+  });
+}
+
+function isResourceIdentity(value: unknown): value is CanonicalResourceIdentity {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const candidate = value as Record<string, unknown>;
+  if (Object.keys(candidate).length !== 2 || typeof candidate.kind !== 'string') return false;
+  if (candidate.kind === 'number') {
+    return Number.isSafeInteger(candidate.value) && (candidate.value as number) > 0;
+  }
+  return (candidate.kind === 'id' || candidate.kind === 'key')
+    && typeof candidate.value === 'string'
+    && candidate.value.length > 0
+    && candidate.value.trim() === candidate.value;
+}
+
+function parseResourceIdentity(value: unknown, label = 'identity'): CanonicalResourceIdentity {
+  if (!isResourceIdentity(value)) throw identityError(`${label} must contain exactly one valid kind/value pair`);
+  if (value.kind === 'number') return { kind: 'number', value: value.value };
+  if (value.kind === 'id') return { kind: 'id', value: value.value };
+  return { kind: 'key', value: value.value };
+}
+
+function serializeResourceIdentity(identity: ResourceIdentity): string {
+  return JSON.stringify(parseResourceIdentity(identity));
+}
+
+function resourceIdentityEquals(left: unknown, right: unknown): boolean {
+  return isResourceIdentity(left) && isResourceIdentity(right)
+    && left.kind === right.kind && left.value === right.value;
+}
+
+function primaryIdentityKind(
+  declaration: ProviderIdentityDeclaration | undefined,
+  resourceKind: PlatformResourceKind
+): ResourceIdentityKind {
+  const kind = declaration?.[resourceKind];
+  if (kind !== 'id' && kind !== 'number' && kind !== 'key') {
+    throw identityError(`provider does not declare a primary identity for ${resourceKind}`);
+  }
+  return kind;
+}
+
+function parseResourceToken(
+  token: string,
+  resourceKind: PlatformResourceKind,
+  declaration: ProviderIdentityDeclaration | undefined
+): ResourceIdentity {
+  if (typeof token !== 'string' || token.length === 0) throw identityError('resource token must be a non-empty string');
+  const kind = primaryIdentityKind(declaration, resourceKind);
+  if (kind === 'number') {
+    if (!/^[1-9]\d*$/u.test(token)) throw identityError(`${resourceKind} token must be a positive safe integer`);
+    const value = Number(token);
+    if (!Number.isSafeInteger(value) || value <= 0) throw identityError(`${resourceKind} token must be a positive safe integer`);
+    return { kind, value };
+  }
+  const value = token.trim();
+  if (!value) throw identityError(`${resourceKind} token must not be empty`);
+  return { kind, value };
+}
+
+function identityFromRemoteValue(
+  value: unknown,
+  resourceKind: PlatformResourceKind,
+  declaration: ProviderIdentityDeclaration | undefined
+): ResourceIdentity {
+  const kind = primaryIdentityKind(declaration, resourceKind);
+  if (isResourceIdentity(value)) {
+    if (value.kind !== kind) throw identityError(`${resourceKind} response identity kind does not match provider declaration`);
+    return value;
+  }
+  if (kind === 'number') {
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value > 0) return { kind, value };
+    if (typeof value === 'string' && /^[1-9]\d*$/u.test(value)) return parseResourceToken(value, resourceKind, declaration);
+    throw identityError(`${resourceKind} response does not contain a valid number identity`);
+  }
+  if (typeof value !== 'string' || !value.trim()) throw identityError(`${resourceKind} response does not contain a valid string identity`);
+  return { kind, value: value.trim() };
+}
+
+function resourceIdentityNumber(identity: ResourceIdentity | null | undefined): number | null {
+  return identity?.kind === 'number' ? identity.value : null;
+}
+
+function resourceIdentityString(identity: ResourceIdentity | null | undefined): string | null {
+  return identity && (identity.kind === 'id' || identity.kind === 'key') ? identity.value : null;
+}
+
+function reviewMarker(identity: ResourceIdentity): string {
+  const parsed = parseResourceIdentity(identity);
+  if (parsed.kind === 'number') return `pr${parsed.value}`;
+  const encoded = Buffer.from(serializeResourceIdentity(parsed), 'utf8').toString('base64url');
+  return `pr:${encoded}`;
+}
+
+export {
+  identityFromRemoteValue,
+  isResourceIdentity,
+  parseResourceIdentity,
+  parseResourceToken,
+  primaryIdentityKind,
+  resourceIdentityEquals,
+  resourceIdentityNumber,
+  resourceIdentityString,
+  reviewMarker,
+  serializeResourceIdentity
+};
+export type { CanonicalResourceIdentity, PlatformResourceKind, ProviderIdentityDeclaration, ResourceIdentity, ResourceIdentityKind };

package/lib/platform/task-identities.ts

@@ -0,0 +1,40 @@
+import type { ProviderIdentityDeclaration, ResourceIdentity } from './resource-identity.ts';
+import { parseResourceIdentity } from './resource-identity.ts';
+import { isLegacyCompatibilityEnabled, legacyCompatibilityError, VERSION } from '../version.ts';
+import { parse as parseYaml } from 'yaml';
+
+function taskIssueIdentity(
+  frontmatter: Record<string, string | number | boolean | null>,
+  _declaration?: ProviderIdentityDeclaration,
+  runtimeVersion = VERSION
+): ResourceIdentity | null {
+  const serialized = frontmatter.platform_issue_identity;
+  if (typeof serialized === 'string' && serialized.trim()) {
+    try {
+      const decoded = parseYaml(serialized);
+      return parseResourceIdentity(
+        JSON.parse(typeof decoded === 'string' ? decoded : serialized),
+        'platform_issue_identity'
+      );
+    } catch {
+      return null;
+    }
+  }
+  const legacy = frontmatter.issue_number;
+  const number = typeof legacy === 'number' ? legacy : typeof legacy === 'string' && /^[1-9]\d*$/u.test(legacy) ? Number(legacy) : NaN;
+  // TODO(compat): Remove the numeric issue_number fallback before the first stable v1.0.0 release.
+  if (Number.isSafeInteger(number) && number > 0 && !isLegacyCompatibilityEnabled(runtimeVersion)) {
+    throw legacyCompatibilityError('issue_number', runtimeVersion);
+  }
+  return Number.isSafeInteger(number) && number > 0 ? { kind: 'number', value: number } : null;
+}
+
+function taskIssueIdentityError(error: unknown): { code: string; message: string } {
+  const value = error && typeof error === 'object' ? error as { code?: unknown } : {};
+  return {
+    code: typeof value.code === 'string' ? value.code : 'PLATFORM_IDENTITY_INVALID',
+    message: error instanceof Error ? error.message : String(error)
+  };
+}
+
+export { taskIssueIdentity, taskIssueIdentityError };

package/lib/platform/types.ts

@@ -23,15 +23,17 @@ type PlatformOperation = {
 type CommentIdentity = {
   kind: 'task' | 'artifact' | 'summary' | 'cancel';
   marker: string;
-  ids: number[];
+  ids: Array<number | string>;
   parts: number;
 };
 
+import type { ResourceIdentity } from './resource-identity.ts';
+
 type PlatformResult = {
   status: PlatformStatus;
   changed: boolean;
   platform: { type: string | null; repository: string | null; currentUser: string | null };
-  resource: { kind: 'repository' | 'issue' | 'pull-request'; number: number | null };
+  resource: { kind: 'repository' | 'issue' | 'pull-request'; number: number | null; identity?: ResourceIdentity };
   capabilities: PlatformCapabilities;
   operations: PlatformOperation[];
   comment: CommentIdentity | null;

package/lib/platform/verification-required.ts

@@ -2,20 +2,15 @@ import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 
-import { hasPlatformCapability } from "./adapters.ts";
 import { inspectRequiredChecks } from "./pr-checks.ts";
-import { resolvePlatformContext } from "./context.ts";
+import { resolvePlatformProviderContext } from "./context.ts";
 import { resolveReviewedHeadRelation } from "./merged-pr-equivalence.ts";
 import { readPrDeliveryFact } from "../task/pr-delivery-fact.ts";
+import { resourceIdentityNumber } from "./resource-identity.ts";
 
 const CHECK_TYPE = "required-checks";
 const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
 
-function validPrNumber(value: any): any {
-  const parsed = Number(value);
-  return Number.isInteger(parsed) && parsed > 0;
-}
-
 function readPrFlow(repoRoot: any): any {
   try {
     const config = JSON.parse(fs.readFileSync(path.join(repoRoot, ".agents", ".airc.json"), "utf8"));
@@ -40,8 +35,9 @@ export function evaluateRequiredChecks(context: any, shared: any): any {
     return shared.failResult(CHECK_TYPE, factRead.error.message, "check_failed");
   }
   const fact = factRead.status === "valid" ? factRead.fact : null;
-  const prNumber = fact?.state === "bound" ? fact.identity.number : null;
-  if (prFlow === "disabled" || fact?.state === "skipped" || !validPrNumber(prNumber)) {
+  const prIdentity = fact?.state === "bound" ? fact.identity.resource : null;
+  const prNumber = resourceIdentityNumber(prIdentity);
+  if (prFlow === "disabled" || fact?.state === "skipped" || !prIdentity) {
     return shared.passResult(CHECK_TYPE, "Skipped: required checks are not applicable to this task");
   }
 
@@ -90,7 +86,7 @@ export function evaluateRequiredChecks(context: any, shared: any): any {
   return shared.failResult(CHECK_TYPE, inspection.error?.message || `Required checks are ${state || "unavailable"}`, "check_failed");
 }
 
-export function check({ taskDir }: any, shared: any): any {
+export async function check({ taskDir }: any, shared: any): Promise<any> {
   const task = shared.loadTask(taskDir);
   if (!task.ok) return shared.failResult(CHECK_TYPE, task.message);
   const prFlow = readPrFlow(shared.repoRoot);
@@ -100,8 +96,10 @@ export function check({ taskDir }: any, shared: any): any {
   if (prFlow === "disabled" || (factRead.status === "valid" && factRead.fact.state === "skipped") || !bound) {
     return evaluateRequiredChecks({ metadata: task.metadata, localHead: null, inspection: null, prFlow }, shared);
   }
-  const platform = resolvePlatformContext({ cwd: shared.repoRoot });
-  if (!hasPlatformCapability(platform.platform.type, "required-checks")) {
+  const loaded = await resolvePlatformProviderContext({ cwd: shared.repoRoot });
+  const platform = loaded.ok ? loaded.value.context : loaded.context;
+  const supportsChecks = loaded.ok && Boolean(loaded.value.provider.checks?.inspectRequired);
+  if (!supportsChecks) {
     return shared.blockedResult(
       CHECK_TYPE,
       `Platform '${platform.platform.type || "none"}' does not provide required-checks inspection`,
@@ -110,7 +108,7 @@ export function check({ taskDir }: any, shared: any): any {
   }
   const localHead = readHead(shared.repoRoot);
   if (!localHead) return evaluateRequiredChecks({ metadata: task.metadata, localHead, inspection: null, prFlow }, shared);
-  const inspection = inspectRequiredChecks(task.metadata.id, { cwd: shared.repoRoot });
+  const inspection = await inspectRequiredChecks(task.metadata.id, { cwd: shared.repoRoot });
   return evaluateRequiredChecks({
     metadata: task.metadata,
     localHead,