@fitlab-ai/agent-infra 0.9.11 → 0.9.13

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

@@ -2,8 +2,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { resolvePlatformContext } from './context.js';
-import { fetchGitHubReleaseNoteData, publishGitHubReleaseNotes } from './github-release-notes.js';
+import { resolvePlatformProviderContext } from './context.js';
+import { providerError, providerOperationContext, providerStatus, unsupportedProviderOperation } from './provider-bridge.js';
+import { resourceIdentityNumber } from './resource-identity.js';
 const unsupportedError = {
     code: 'PLATFORM_RELEASE_NOTES_UNSUPPORTED',
     message: 'Release notes are not supported for the configured platform',
@@ -103,14 +104,21 @@ function configuredPlatform(cwd) {
         return null;
     }
 }
-function releaseNoteContext(input, options = {}) {
+async function releaseNoteContext(input, options = {}) {
     const historyLimit = input.historyLimit ?? 3;
     if (!input.fromTag || !input.toTag || !input.branch || !Number.isInteger(historyLimit) || historyLimit < 1 || historyLimit > 20) {
         return { ...baseResult('failed'), error: { code: 'RELEASE_NOTES_INPUT_INVALID', message: 'from-tag, to-tag, branch, and a history limit from 1 to 20 are required', retryable: false } };
     }
     const cwd = path.resolve(options.cwd || process.cwd());
     const platformType = options.platformType ?? configuredPlatform(cwd);
-    if (platformType !== 'github')
+    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;
     let toOid;
@@ -132,28 +140,24 @@ function releaseNoteContext(input, options = {}) {
     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,
-        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 };
-    }
+    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
+        })
+        : 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();
-        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);
@@ -161,43 +165,37 @@ function releaseNoteContext(input, options = {}) {
         });
         return { ...commit, authors };
     });
-    const pullRequests = platform.pullRequests
+    const pullRequests = 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.name || label)) : [],
-        author: item.author && typeof item.author === 'object'
-            ? { login: String(item.author.login || '').toLowerCase(), bot: String(item.author.login || '').endsWith('[bot]') }
-            : null,
-        closingIssues: Array.isArray(item.closingIssuesReferences)
-            ? item.closingIssuesReferences.map((issue) => {
-                const value = issue;
-                return {
-                    number: Number(value.number),
-                    title: String(value.title || ''),
-                    url: String(value.url || ''),
-                    labels: Array.isArray(value.labels) ? value.labels.map((label) => String(label.name || label)) : [],
-                    author: value.author && typeof value.author === 'object'
-                        ? { login: String(value.author.login || '').toLowerCase(), bot: String(value.author.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',
         changed: false,
         range: { fromTag: input.fromTag, toTag: input.toTag, fromOid, toOid },
-        history: platform.history,
+        history: platform.value.history,
         pullRequests,
         commits,
         error: null
     };
 }
-function publishReleaseNotes(input, options = {}) {
+async function publishReleaseNotes(input, options = {}) {
     if (!input.tag || !input.title || !input.notesFile || !SHA256_PATTERN.test(input.expectedSha256)) {
         return releaseNoteFailure('RELEASE_NOTES_INPUT_INVALID', 'tag, title, notes-file, and expected-sha256 are required');
     }
@@ -213,13 +211,38 @@ function publishReleaseNotes(input, options = {}) {
     }
     const cwd = path.resolve(options.cwd || process.cwd());
     const platformType = options.platformType ?? configuredPlatform(cwd);
-    if (platformType !== 'github')
-        return { status: 'no-op', 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' : 'failed', 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 }
+        };
     }
-    return publishGitHubReleaseNotes({ ...input, repository: context.platform.repository }, { cwd, client: options.client });
+    if (loaded.ok) {
+        const context = loaded.value.context;
+        if (!context.platform.repository)
+            return { status: context.status === 'blocked' ? 'blocked' : 'failed', 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', changed: published.value.changed, operation: 'publish-notes', url: null, error: null };
+    }
+    return { status: 'failed', changed: false, operation: null, url: null, error: { code: 'PLATFORM_PROVIDER_LOAD_FAILED', message: 'Selected provider failed to load', retryable: false } };
 }
 export { normalizeReleaseNoteBytes, publishReleaseNotes, releaseNoteContext, releaseNoteSha256, stageReleaseNotes };
 //# sourceMappingURL=release-notes.js.map

package/dist/lib/platform/releases.js

@@ -1,57 +1,80 @@
-import { createGitHubClient } from './github-client.js';
-import { resolvePlatformContext } from './context.js';
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { resolvePlatformProviderContext } from './context.js';
 import { platformResult } from './types.js';
+import { providerError, providerOperationContext, providerStatus, unsupportedProviderOperation } from './provider-bridge.js';
 function flattenPages(value) {
     if (!Array.isArray(value))
         return [];
     return value.flatMap((entry) => Array.isArray(entry) ? entry : [entry]).filter((entry) => Boolean(entry) && typeof entry === 'object');
 }
-function inspectPlatformRelease(tag, options = {}) {
-    const client = options.client ?? createGitHubClient();
-    const context = resolvePlatformContext({ cwd: options.cwd, client });
+async function inspectPlatformRelease(tag, options = {}) {
+    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(['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 = { 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(['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, options = {}) {
-    const inspected = inspectPlatformRelease(input.tag, options);
+async function upsertPlatformRelease(input, options = {}) {
+    const inspected = await inspectPlatformRelease(input.tag, options);
     if (inspected.release?.published)
         return { ...inspected, status: 'no-op', changed: false, operations: [] };
     if (inspected.status === 'blocked' || inspected.status === 'failed')
         return { ...inspected, changed: false, operations: [] };
     if (!inspected.platform.repository)
         return { ...inspected, status: 'no-op', 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' : 'failed', changed: false, operations: [{ name: 'create-release', status: 'failed' }], error: created.error };
-    return { ...inspectPlatformRelease(input.tag, options), status: 'applied', changed: true, operations: [{ name: 'create-release', status: 'applied' }] };
+    const loaded = await resolvePlatformProviderContext({ cwd: options.cwd, client: options.client });
+    if (loaded.ok) {
+        let notes;
+        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', 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', changed: created.value.changed, operations: [{ name: 'create-release', status: 'applied' }], error: null };
+    }
+    return { ...inspected, status: 'failed', 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, options = {}) {
+async function reconcileReleaseMilestones(version, options = {}) {
     const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
     if (!match)
         return { status: 'failed', 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(['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]);
@@ -66,25 +89,31 @@ function reconcileReleaseMilestones(version, options = {}) {
         const nextLine = `${major}.${minor + 1}.x`;
         ensure.push({ title: nextMinor, description: `Issues that we want to release in v${nextMinor}.` }, { title: nextLine, description: `Issues that we want to resolve in ${major}.${minor + 1} line.` });
     }
-    const operations = [];
-    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' }))
+                ],
+                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' : 'no-op',
+            changed: reconciled.value.changed,
+            operations: [
+                ...reconciled.value.closed.map((title) => ({ name: 'close-milestone', title, status: 'applied' })),
+                ...reconciled.value.created.map((title) => ({ name: 'ensure-milestone', title, status: 'applied' }))
+            ],
+            error: null
+        };
     }
-    const failed = operations.some((operation) => operation.status === 'failed');
-    const changed = operations.some((operation) => operation.status === 'applied');
-    return { status: failed ? 'failed' : changed ? 'applied' : 'no-op', changed, operations, error: failed ? { code: 'MILESTONE_RECONCILE_FAILED', message: 'One or more milestone operations failed' } : null };
+    return { status: 'failed', changed: false, operations: [], error: { code: 'PLATFORM_CAPABILITY_UNSUPPORTED', message: 'Release milestone reconciliation is unavailable', retryable: false } };
 }
 export { inspectPlatformRelease, reconcileReleaseMilestones, upsertPlatformRelease };
 //# sourceMappingURL=releases.js.map

package/dist/lib/platform/resource-identity.d.ts

@@ -0,0 +1,26 @@
+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>>;
+declare function isResourceIdentity(value: unknown): value is CanonicalResourceIdentity;
+declare function parseResourceIdentity(value: unknown, label?: string): CanonicalResourceIdentity;
+declare function serializeResourceIdentity(identity: ResourceIdentity): string;
+declare function resourceIdentityEquals(left: unknown, right: unknown): boolean;
+declare function primaryIdentityKind(declaration: ProviderIdentityDeclaration | undefined, resourceKind: PlatformResourceKind): ResourceIdentityKind;
+declare function parseResourceToken(token: string, resourceKind: PlatformResourceKind, declaration: ProviderIdentityDeclaration | undefined): ResourceIdentity;
+declare function identityFromRemoteValue(value: unknown, resourceKind: PlatformResourceKind, declaration: ProviderIdentityDeclaration | undefined): ResourceIdentity;
+declare function resourceIdentityNumber(identity: ResourceIdentity | null | undefined): number | null;
+declare function resourceIdentityString(identity: ResourceIdentity | null | undefined): string | null;
+declare function reviewMarker(identity: ResourceIdentity): string;
+export { identityFromRemoteValue, isResourceIdentity, parseResourceIdentity, parseResourceToken, primaryIdentityKind, resourceIdentityEquals, resourceIdentityNumber, resourceIdentityString, reviewMarker, serializeResourceIdentity };
+export type { CanonicalResourceIdentity, PlatformResourceKind, ProviderIdentityDeclaration, ResourceIdentity, ResourceIdentityKind };

package/dist/lib/platform/resource-identity.js

@@ -0,0 +1,92 @@
+function identityError(message) {
+    return Object.assign(new Error(`PLATFORM_IDENTITY_INVALID: ${message}`), {
+        code: 'PLATFORM_IDENTITY_INVALID'
+    });
+}
+function isResourceIdentity(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const candidate = value;
+    if (Object.keys(candidate).length !== 2 || typeof candidate.kind !== 'string')
+        return false;
+    if (candidate.kind === 'number') {
+        return Number.isSafeInteger(candidate.value) && candidate.value > 0;
+    }
+    return (candidate.kind === 'id' || candidate.kind === 'key')
+        && typeof candidate.value === 'string'
+        && candidate.value.length > 0
+        && candidate.value.trim() === candidate.value;
+}
+function parseResourceIdentity(value, label = 'identity') {
+    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) {
+    return JSON.stringify(parseResourceIdentity(identity));
+}
+function resourceIdentityEquals(left, right) {
+    return isResourceIdentity(left) && isResourceIdentity(right)
+        && left.kind === right.kind && left.value === right.value;
+}
+function primaryIdentityKind(declaration, resourceKind) {
+    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, resourceKind, declaration) {
+    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, resourceKind, declaration) {
+    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) {
+    return identity?.kind === 'number' ? identity.value : null;
+}
+function resourceIdentityString(identity) {
+    return identity && (identity.kind === 'id' || identity.kind === 'key') ? identity.value : null;
+}
+function reviewMarker(identity) {
+    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 };
+//# sourceMappingURL=resource-identity.js.map

package/dist/lib/platform/task-identities.js

@@ -0,0 +1,31 @@
+import { parseResourceIdentity } from './resource-identity.js';
+import { isLegacyCompatibilityEnabled, legacyCompatibilityError, VERSION } from '../version.js';
+import { parse as parseYaml } from 'yaml';
+function taskIssueIdentity(frontmatter, _declaration, runtimeVersion = VERSION) {
+    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) {
+    const value = error && typeof error === 'object' ? error : {};
+    return {
+        code: typeof value.code === 'string' ? value.code : 'PLATFORM_IDENTITY_INVALID',
+        message: error instanceof Error ? error.message : String(error)
+    };
+}
+export { taskIssueIdentity, taskIssueIdentityError };
+//# sourceMappingURL=task-identities.js.map

package/dist/lib/platform/verification-required.js

@@ -1,16 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
-import { hasPlatformCapability } from "./adapters.js";
 import { inspectRequiredChecks } from "./pr-checks.js";
-import { resolvePlatformContext } from "./context.js";
+import { resolvePlatformProviderContext } from "./context.js";
 import { resolveReviewedHeadRelation } from "./merged-pr-equivalence.js";
+import { readPrDeliveryFact } from "../task/pr-delivery-fact.js";
+import { resourceIdentityNumber } from "./resource-identity.js";
 const CHECK_TYPE = "required-checks";
 const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
-function validPrNumber(value) {
-    const parsed = Number(value);
-    return Number.isInteger(parsed) && parsed > 0;
-}
 function readPrFlow(repoRoot) {
     try {
         const config = JSON.parse(fs.readFileSync(path.join(repoRoot, ".agents", ".airc.json"), "utf8"));
@@ -30,7 +27,14 @@ function readHead(repoRoot) {
 }
 export function evaluateRequiredChecks(context, shared) {
     const { metadata, localHead, inspection, prFlow } = context;
-    if (prFlow === "disabled" || metadata.pr_status === "skipped" || !validPrNumber(metadata.pr_number)) {
+    const factRead = readPrDeliveryFact(metadata);
+    if (factRead.status === "invalid") {
+        return shared.failResult(CHECK_TYPE, factRead.error.message, "check_failed");
+    }
+    const fact = factRead.status === "valid" ? factRead.fact : null;
+    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");
     }
     const reviewedHead = String(metadata.last_reviewed_commit || "");
@@ -73,22 +77,28 @@ export function evaluateRequiredChecks(context, shared) {
     }
     return shared.failResult(CHECK_TYPE, inspection.error?.message || `Required checks are ${state || "unavailable"}`, "check_failed");
 }
-export function check({ taskDir }, shared) {
+export async function check({ taskDir }, shared) {
     const task = shared.loadTask(taskDir);
     if (!task.ok)
         return shared.failResult(CHECK_TYPE, task.message);
     const prFlow = readPrFlow(shared.repoRoot);
-    if (prFlow === "disabled" || task.metadata.pr_status === "skipped" || !validPrNumber(task.metadata.pr_number)) {
+    const factRead = readPrDeliveryFact(task.metadata);
+    if (factRead.status === "invalid")
+        return shared.failResult(CHECK_TYPE, factRead.error.message, "check_failed");
+    const bound = factRead.status === "valid" && factRead.fact.state === "bound";
+    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`, "dependency_error");
     }
     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,