@fitlab-ai/agent-infra 0.8.5 → 0.9.1

package/lib/platform/pull-requests.ts

@@ -0,0 +1,386 @@
+import fs from 'node:fs';
+
+import { parseTaskFrontmatter } from '../task/frontmatter.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { extractSection } from '../task/sections.ts';
+import { captureTaskWriteMetadata, writeTask } from '../task/write.ts';
+import { resolvePlatformContext } from './context.ts';
+import { createGitHubClient } from './github-client.ts';
+import type { GitHubClient } from './github-client.ts';
+import { inspectPlatformIssue } from './issues.ts';
+import { planPullRequestMetadata } from './pull-request-metadata.ts';
+import { platformResult } from './types.ts';
+import type { PlatformOperation, PlatformResult } from './types.ts';
+
+type PullRequestSnapshot = {
+  repository: string;
+  number: number;
+  nodeId: string;
+  url: string;
+  state: 'open' | 'closed';
+  title: string;
+  body: string;
+  draft: boolean;
+  head: { repository: string; ref: string; sha: string };
+  base: { repository: string; ref: string; sha: string };
+  mergedAt: string | null;
+  mergeCommitSha: string | null;
+  labels: string[];
+  assignees: string[];
+  milestone: string | null;
+};
+
+type PullRequestResult = PlatformResult & {
+  task: { id: string | null; issueNumber: number | null; prNumber: number | null };
+  pullRequest: PullRequestSnapshot | null;
+};
+type SharedOptions = { cwd?: string; client?: GitHubClient };
+type CreateOptions = SharedOptions & {
+  agent: string;
+  base: string;
+  head: string;
+  title: string;
+  body: string;
+  draft?: boolean;
+  dryRun?: boolean;
+};
+type BindOptions = SharedOptions & { agent: string; pr: number; dryRun?: boolean };
+type SyncOptions = SharedOptions & { agent: string; metadata?: boolean; closingIssue?: boolean; dryRun?: boolean };
+
+type RemotePullRequest = {
+  number?: number;
+  node_id?: string;
+  html_url?: string;
+  state?: string;
+  title?: string;
+  body?: string | null;
+  draft?: boolean;
+  pull_request?: unknown;
+  head?: { ref?: string; sha?: string; repo?: { full_name?: string } | null };
+  base?: { ref?: string; sha?: string; repo?: { full_name?: string } | null };
+  merged_at?: string | null;
+  merge_commit_sha?: string | null;
+  labels?: Array<string | { name?: string }>;
+  assignees?: Array<{ login?: string }>;
+  milestone?: { title?: string } | null;
+};
+
+function result(
+  status: PlatformResult['status'],
+  taskId: string | null,
+  issueNumber: number | null,
+  prNumber: number | null,
+  overrides: Partial<PullRequestResult> = {}
+): PullRequestResult {
+  return {
+    ...platformResult(status),
+    task: { id: taskId, issueNumber, prNumber },
+    pullRequest: null,
+    ...overrides
+  };
+}
+
+function normalizePullRequest(remote: RemotePullRequest, repository: string): PullRequestSnapshot | null {
+  const number = Number(remote.number);
+  const headRepository = remote.head?.repo?.full_name;
+  const baseRepository = remote.base?.repo?.full_name;
+  if (!Number.isInteger(number) || number <= 0 || !remote.node_id || !remote.html_url ||
+      !remote.head?.ref || !remote.head.sha || !headRepository || !remote.base?.ref || !baseRepository) return null;
+  return {
+    repository,
+    number,
+    nodeId: remote.node_id,
+    url: remote.html_url,
+    state: remote.state === 'closed' ? 'closed' : 'open',
+    title: remote.title || '',
+    body: remote.body || '',
+    draft: Boolean(remote.draft),
+    head: { repository: headRepository, ref: remote.head.ref, sha: remote.head.sha },
+    base: { repository: baseRepository, ref: remote.base.ref, sha: remote.base.sha || '' },
+    mergedAt: remote.merged_at || null,
+    mergeCommitSha: remote.merge_commit_sha || null,
+    labels: (remote.labels || []).map((label) => typeof label === 'string' ? label : label.name || '').filter(Boolean).sort(),
+    assignees: (remote.assignees || []).map((assignee) => assignee.login || '').filter(Boolean).sort(),
+    milestone: remote.milestone?.title || null
+  };
+}
+
+function expectedHead(repository: string, head: string): { repository: string; ref: string } {
+  const colon = head.indexOf(':');
+  if (colon === -1) return { repository, ref: head };
+  const repoName = repository.split('/')[1] || '';
+  return { repository: `${head.slice(0, colon)}/${repoName}`, ref: head.slice(colon + 1) };
+}
+
+function selectPullRequest(remotes: RemotePullRequest[], repository: string, head: string, base: string):
+  | { status: 'resolved'; pullRequest: PullRequestSnapshot }
+  | { status: 'missing' | 'ambiguous'; pullRequest: null } {
+  const wanted = expectedHead(repository, head);
+  const matches = remotes.flatMap((remote) => {
+    const normalized = normalizePullRequest(remote, repository);
+    return normalized && normalized.state === 'open' && normalized.head.repository === wanted.repository &&
+      normalized.head.ref === wanted.ref && normalized.base.repository === repository && normalized.base.ref === base
+      ? [normalized] : [];
+  });
+  if (matches.length === 1) return { status: 'resolved', pullRequest: matches[0]! };
+  return { status: matches.length === 0 ? 'missing' : 'ambiguous', pullRequest: null };
+}
+
+function resolvedContext(taskRef: string, options: SharedOptions) {
+  const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
+  if (!resolved.ok) return { ok: false as const, output: result('failed', resolved.taskId, null, null, {
+    error: { code: resolved.code, message: resolved.message, retryable: false }
+  }) };
+  const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+  const frontmatter = parseTaskFrontmatter(content);
+  const issue = Number(frontmatter.issue_number);
+  const pr = Number(frontmatter.pr_number);
+  const issueNumber = Number.isInteger(issue) && issue > 0 ? issue : null;
+  const prNumber = Number.isInteger(pr) && pr > 0 ? pr : null;
+  const client = options.client || createGitHubClient();
+  const context = resolvePlatformContext({ cwd: resolved.repoRoot, client });
+  const usable = (context.status === 'no-op' || context.status === 'degraded') && context.platform.repository;
+  if (!usable) return { ok: false as const, output: result(context.status, resolved.taskId, issueNumber, prNumber, {
+    platform: context.platform, capabilities: context.capabilities, operations: context.operations, error: context.error
+  }) };
+  return { ok: true as const, resolved, content, frontmatter, issueNumber, prNumber, client, context };
+}
+
+function inspectGitHubPullRequest(client: GitHubClient, repository: string, number: number, cwd: string) {
+  const fetched = client.json<RemotePullRequest>(['api', `repos/${repository}/pulls/${number}`], { cwd });
+  if (!fetched.ok) return fetched;
+  const pullRequest = normalizePullRequest(fetched.value, repository);
+  return pullRequest
+    ? { ok: true as const, value: pullRequest }
+    : { ok: false as const, error: { code: 'PR_IDENTITY_INVALID', message: 'Remote resource is not a valid pull request', retryable: false } };
+}
+
+function locatePullRequest(base: ReturnType<typeof resolvedContext> & { ok: true }, head: string, target: string) {
+  const repository = base.context.platform.repository!;
+  const listed = base.client.json<RemotePullRequest[]>([
+    'api', `repos/${repository}/pulls?state=open&base=${encodeURIComponent(target)}&per_page=100`
+  ], { cwd: base.resolved.repoRoot });
+  if (!listed.ok) return listed;
+  const selected = selectPullRequest(listed.value, repository, head, target);
+  return selected.status === 'resolved'
+    ? { ok: true as const, value: selected.pullRequest }
+    : { ok: false as const, error: {
+      code: selected.status === 'ambiguous' ? 'PR_IDENTITY_AMBIGUOUS' : 'PR_NOT_FOUND',
+      message: selected.status === 'ambiguous' ? 'Multiple pull requests match the exact head/base identity' : 'No pull request matches the exact head/base identity',
+      retryable: false
+    } };
+}
+
+function inspectPlatformPullRequest(taskRef: string, options: SharedOptions = {}): PullRequestResult {
+  const base = resolvedContext(taskRef, options);
+  if (!base.ok) return base.output;
+  if (!base.prNumber) return result('no-op', base.resolved.taskId, base.issueNumber, null, {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    error: { code: 'PR_NOT_LINKED', message: 'Task has no valid pr_number', retryable: false }
+  });
+  const fetched = inspectGitHubPullRequest(base.client, base.context.platform.repository!, base.prNumber, base.resolved.repoRoot);
+  if (!fetched.ok) return result(fetched.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: base.prNumber }, error: fetched.error
+  });
+  return result('no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: fetched.value, error: null
+  });
+}
+
+function appendActivity(content: string, line: string): string {
+  const body = extractSection(content, ['活动日志', 'Activity Log']);
+  return `${body.replace(/\s+$/, '')}${body.trim() ? '\n' : ''}${line}`;
+}
+
+function writeCreateStarted(base: ReturnType<typeof resolvedContext> & { ok: true }, agent: string) {
+  const starts = (base.content.match(/\*\*Create PR \[started\]\*\*/g) || []).length;
+  const dones = (base.content.match(/\*\*Create PR\*\*/g) || []).length;
+  if (starts > dones) return { status: 'no-op' as const };
+  const metadata = captureTaskWriteMetadata();
+  return writeTask({
+    taskRef: base.resolved.taskId,
+    expectedState: 'active',
+    mutations: [{ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: '活动日志', body: appendActivity(
+      base.content, `- ${metadata.timestamp} — **Create PR [started]** by ${agent} — started`
+    ) }]
+  }, { repoRoot: base.resolved.repoRoot, metadataProvider: () => metadata });
+}
+
+function bindIdentity(base: ReturnType<typeof resolvedContext> & { ok: true }, pullRequest: PullRequestSnapshot, agent: string, dryRun = false) {
+  if (base.prNumber && base.prNumber !== pullRequest.number) return { status: 'failed' as const, error: {
+    code: 'PR_BIND_CONFLICT', message: `Task is already bound to PR #${base.prNumber}`
+  } };
+  if (base.prNumber === pullRequest.number) return { status: 'no-op' as const, error: null };
+  const current = fs.readFileSync(base.resolved.taskMdPath, 'utf8');
+  const metadata = captureTaskWriteMetadata();
+  return writeTask({
+    taskRef: base.resolved.taskId,
+    expectedState: 'active',
+    dryRun,
+    mutations: [
+      { kind: 'frontmatter', set: { pr_number: pullRequest.number, pr_status: 'created', assigned_to: agent } },
+      { kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: '活动日志', body: appendActivity(
+        current, `- ${metadata.timestamp} — **Create PR** by ${agent} — PR #${pullRequest.number} created → ${pullRequest.url}`
+      ) }
+    ]
+  }, { repoRoot: base.resolved.repoRoot, metadataProvider: () => metadata });
+}
+
+function bindPlatformPullRequest(taskRef: string, options: BindOptions): PullRequestResult {
+  const base = resolvedContext(taskRef, options);
+  if (!base.ok) return base.output;
+  if (!Number.isInteger(options.pr) || options.pr <= 0) return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    error: { code: 'PR_NUMBER_INVALID', message: 'PR number must be positive', retryable: false }
+  });
+  if (base.prNumber && base.prNumber !== options.pr) return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    error: { code: 'PR_BIND_CONFLICT', message: `Task is already bound to PR #${base.prNumber}`, retryable: false }
+  });
+  const fetched = inspectGitHubPullRequest(base.client, base.context.platform.repository!, options.pr, base.resolved.repoRoot);
+  if (!fetched.ok) return result(fetched.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, { error: fetched.error });
+  const written = bindIdentity(base, fetched.value, options.agent, options.dryRun);
+  if (written.status === 'failed') return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    pullRequest: fetched.value, error: { code: written.error.code, message: written.error.message, retryable: false }
+  });
+  return result(options.dryRun ? 'planned' : written.status === 'no-op' ? 'no-op' : 'applied', base.resolved.taskId, base.issueNumber, options.dryRun ? base.prNumber : fetched.value.number, {
+    changed: !options.dryRun && written.status === 'applied', platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: fetched.value.number }, pullRequest: fetched.value,
+    operations: [{ name: 'task:bind-pr', status: options.dryRun ? 'planned' : written.status === 'no-op' ? 'no-op' : 'applied', reasonCode: null }], error: null
+  });
+}
+
+function createPlatformPullRequest(taskRef: string, options: CreateOptions): PullRequestResult {
+  const base = resolvedContext(taskRef, options);
+  if (!base.ok) return base.output;
+  if (!options.base || !options.head || !options.title.trim() || !options.body.trim()) return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    error: { code: 'PR_PAYLOAD_INVALID', message: 'base, head, title and body are required', retryable: false }
+  });
+  if (base.prNumber) return inspectPlatformPullRequest(taskRef, options);
+  const located = locatePullRequest(base, options.head, options.base);
+  if (!located.ok && located.error.code === 'PR_IDENTITY_AMBIGUOUS') return result('failed', base.resolved.taskId, base.issueNumber, null, {
+    platform: base.context.platform, capabilities: base.context.capabilities, error: located.error
+  });
+  if (options.dryRun) return result('planned', base.resolved.taskId, base.issueNumber, null, {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    operations: [{ name: located.ok ? 'pr:reuse' : 'pr:create', status: 'planned', reasonCode: null }], error: null
+  });
+  const started = writeCreateStarted(base, options.agent);
+  if (started.status === 'failed') return result('failed', base.resolved.taskId, base.issueNumber, null, {
+    error: { code: started.error.code, message: started.error.message, retryable: false }
+  });
+  let pullRequest = located.ok ? located.value : null;
+  let created = false;
+  if (!pullRequest) {
+    const repository = base.context.platform.repository!;
+    const response = base.client.json<RemotePullRequest>(['api', `repos/${repository}/pulls`, '-X', 'POST', '--input', '-'], {
+      cwd: base.resolved.repoRoot,
+      method: 'POST',
+      input: JSON.stringify({ title: options.title, body: options.body, head: options.head, base: options.base, draft: Boolean(options.draft) })
+    });
+    if (response.ok) pullRequest = normalizePullRequest(response.value, repository);
+    else if (response.error.retryable) {
+      const recovered = locatePullRequest(base, options.head, options.base);
+      if (recovered.ok) pullRequest = recovered.value;
+      else return result('blocked', base.resolved.taskId, base.issueNumber, null, {
+        platform: base.context.platform, capabilities: base.context.capabilities,
+        operations: [{ name: 'pr:create', status: 'failed', reasonCode: 'PR_CREATE_OUTCOME_UNKNOWN' }],
+        error: { code: 'PR_CREATE_OUTCOME_UNKNOWN', message: response.error.message, retryable: true }
+      });
+    } else return result('failed', base.resolved.taskId, base.issueNumber, null, {
+      platform: base.context.platform, capabilities: base.context.capabilities,
+      operations: [{ name: 'pr:create', status: 'failed', reasonCode: response.error.code }], error: response.error
+    });
+    if (!pullRequest) return result('failed', base.resolved.taskId, base.issueNumber, null, {
+      error: { code: 'PR_CREATE_RESPONSE_INVALID', message: 'PR create response lacks validated identity', retryable: false }
+    });
+    created = true;
+  }
+  const refreshed = resolvedContext(taskRef, options);
+  if (!refreshed.ok) return result('failed', base.resolved.taskId, base.issueNumber, null, {
+    pullRequest, error: { code: 'PR_CREATED_BIND_FAILED', message: pullRequest.url, retryable: false }
+  });
+  const bound = bindIdentity(refreshed, pullRequest, options.agent);
+  if (bound.status === 'failed') return result('failed', base.resolved.taskId, base.issueNumber, null, {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: pullRequest.number }, pullRequest,
+    operations: [{ name: created ? 'pr:create' : 'pr:reuse', status: 'applied', reasonCode: null }, { name: 'task:bind-pr', status: 'failed', reasonCode: bound.error.code }],
+    error: { code: 'PR_CREATED_BIND_FAILED', message: `${pullRequest.url}: ${bound.error.message}`, retryable: false }
+  });
+  return result('applied', base.resolved.taskId, base.issueNumber, pullRequest.number, {
+    changed: true, platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: pullRequest.number }, pullRequest,
+    operations: [{ name: created ? 'pr:create' : 'pr:reuse', status: created ? 'applied' : 'no-op', reasonCode: null }, { name: 'task:bind-pr', status: 'applied', reasonCode: null }], error: null
+  });
+}
+
+function syncPlatformPullRequest(taskRef: string, options: SyncOptions): PullRequestResult {
+  const base = resolvedContext(taskRef, options);
+  if (!base.ok) return base.output;
+  if (!base.prNumber) return result('failed', base.resolved.taskId, base.issueNumber, null, {
+    error: { code: 'PR_NOT_LINKED', message: 'Task has no valid pr_number', retryable: false }
+  });
+  const fetched = inspectGitHubPullRequest(base.client, base.context.platform.repository!, base.prNumber, base.resolved.repoRoot);
+  if (!fetched.ok) return result(fetched.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, { error: fetched.error });
+  if (!options.metadata && !options.closingIssue) return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    error: { code: 'PR_PAYLOAD_INVALID', message: 'sync requires a desired-state option', retryable: false }
+  });
+  if (!base.issueNumber) return result('degraded', base.resolved.taskId, null, base.prNumber, {
+    pullRequest: fetched.value, error: { code: 'ISSUE_NOT_LINKED', message: 'Task has no linked Issue to copy metadata from', retryable: false }
+  });
+  const issue = inspectPlatformIssue(taskRef, { cwd: base.resolved.repoRoot, client: base.client });
+  if (!issue.issue) return result(issue.status, base.resolved.taskId, base.issueNumber, base.prNumber, {
+    platform: base.context.platform, capabilities: base.context.capabilities, pullRequest: fetched.value, error: issue.error
+  });
+  const planned = planPullRequestMetadata({
+    pullRequest: fetched.value,
+    issue: issue.issue,
+    taskType: base.frontmatter.type || 'task',
+    issueNumber: base.issueNumber,
+    capabilities: base.context.capabilities
+  }).operations.filter((operation) => options.metadata || operation.name === 'closing-issue')
+    .filter((operation) => options.closingIssue || operation.name !== 'closing-issue');
+  const operations: PlatformOperation[] = planned.map(({ name, status, reasonCode }) => ({ name, status, reasonCode }));
+  if (options.dryRun) return result(planned.some((operation) => operation.status === 'planned') ? 'planned' : 'no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    platform: base.context.platform, capabilities: base.context.capabilities, pullRequest: fetched.value, operations, error: null
+  });
+  const payload: Record<string, unknown> = {};
+  for (const operation of planned) {
+    if (operation.status !== 'planned') continue;
+    if (operation.name === 'labels') payload.labels = operation.value;
+    if (operation.name === 'assignees') payload.assignees = operation.value;
+    if (operation.name === 'closing-issue') payload.body = operation.value;
+    if (operation.name === 'milestone') {
+      const milestones = base.client.json<unknown[]>(['api', '--paginate', '--slurp', `repos/${base.context.platform.repository}/milestones?state=open&per_page=100`], { cwd: base.resolved.repoRoot });
+      if (!milestones.ok) return result(milestones.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, { pullRequest: fetched.value, operations, error: milestones.error });
+      const flat = milestones.value.flatMap((entry) => Array.isArray(entry) ? entry : [entry]) as Array<{ title?: string; number?: number }>;
+      payload.milestone = flat.find((entry) => entry.title === operation.value)?.number ?? null;
+    }
+  }
+  if (Object.keys(payload).length === 0) {
+    const degraded = planned.some((operation) => operation.status === 'skipped');
+    return result(degraded ? 'degraded' : 'no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+      platform: base.context.platform, capabilities: base.context.capabilities, resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: fetched.value, operations, error: null
+    });
+  }
+  const patched = base.client.json<RemotePullRequest>(['api', `repos/${base.context.platform.repository}/issues/${base.prNumber}`, '-X', 'PATCH', '--input', '-'], {
+    cwd: base.resolved.repoRoot, method: 'PATCH', input: JSON.stringify(payload)
+  });
+  if (!patched.ok) return result(patched.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, { pullRequest: fetched.value, operations, error: patched.error });
+  return result(planned.some((operation) => operation.status === 'skipped') ? 'degraded' : 'applied', base.resolved.taskId, base.issueNumber, base.prNumber, {
+    changed: true, platform: base.context.platform, capabilities: base.context.capabilities,
+    resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: fetched.value,
+    operations: operations.map((operation) => operation.status === 'planned' ? { ...operation, status: 'applied' } : operation), error: null
+  });
+}
+
+export {
+  bindPlatformPullRequest,
+  createPlatformPullRequest,
+  inspectGitHubPullRequest,
+  inspectPlatformPullRequest,
+  normalizePullRequest,
+  selectPullRequest,
+  syncPlatformPullRequest
+};
+export type { BindOptions, CreateOptions, PullRequestResult, PullRequestSnapshot, SyncOptions };

package/lib/platform/release-notes.ts

@@ -0,0 +1,167 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+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';
+
+type ReleaseNoteOptions = {
+  cwd?: string;
+  platformType?: string;
+  client?: GitHubClient;
+};
+
+type ReleaseNoteCommit = { oid: string; title: string; authors: ReleaseNoteActor[] };
+
+const unsupportedError = {
+  code: 'PLATFORM_RELEASE_NOTES_UNSUPPORTED',
+  message: 'Release notes are not supported for the configured platform',
+  retryable: false
+};
+
+function baseResult(status: 'no-op' | 'failed' | 'blocked') {
+  return {
+    status,
+    changed: false,
+    range: null,
+    history: [],
+    pullRequests: [],
+    commits: [] as ReleaseNoteCommit[],
+    error: status === 'no-op' ? unsupportedError : null
+  };
+}
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+function configuredPlatform(cwd: string): string | null {
+  try {
+    const value = JSON.parse(fs.readFileSync(path.join(cwd, '.agents', '.airc.json'), 'utf8'));
+    return typeof value?.platform?.type === 'string' ? value.platform.type : null;
+  } catch {
+    return null;
+  }
+}
+
+function releaseNoteContext(
+  input: { fromTag: string; toTag: string; branch: string; historyLimit?: number },
+  options: ReleaseNoteOptions = {}
+) {
+  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') return baseResult('no-op');
+  let fromOid: string;
+  let toOid: string;
+  let fromTime: string;
+  let toTime: string;
+  let commitFacts: Array<{ oid: string; title: string }>;
+  try {
+    fromOid = git(cwd, ['rev-parse', '--verify', `${input.fromTag}^{commit}`]);
+    toOid = git(cwd, ['rev-parse', '--verify', `${input.toTag}^{commit}`]);
+    git(cwd, ['merge-base', '--is-ancestor', fromOid, toOid]);
+    fromTime = git(cwd, ['show', '-s', '--format=%cI', fromOid]);
+    toTime = git(cwd, ['show', '-s', '--format=%cI', toOid]);
+    const raw = git(cwd, ['log', '--reverse', '--no-merges', '--format=%H%x00%s', `${fromOid}..${toOid}`]);
+    commitFacts = raw ? raw.split('\n').map((line) => {
+      const [oid = '', title = ''] = line.split('\0');
+      return { oid, title };
+    }) : [];
+  } 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 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();
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+    return { ...commit, authors };
+  });
+  const pullRequests = platform.pullRequests
+    .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
+          };
+        }) : []
+    }))
+    .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,
+    pullRequests,
+    commits,
+    error: null
+  };
+}
+
+function publishReleaseNotes(
+  input: { tag: string; title: string; notesFile: string; dryRun?: boolean },
+  options: ReleaseNoteOptions = {}
+) {
+  if (!input.tag || !input.title || !input.notesFile) {
+    return { status: 'failed' as const, changed: false, operation: null, url: null, error: { code: 'RELEASE_NOTES_INPUT_INVALID', message: 'tag, title, and notes-file are required', retryable: false } };
+  }
+  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 };
+  }
+  return publishGitHubReleaseNotes({ ...input, repository: context.platform.repository }, { cwd, client: options.client });
+}
+
+export { publishReleaseNotes, releaseNoteContext };

package/lib/platform/releases.ts

@@ -0,0 +1,71 @@
+import { createGitHubClient } from './github-client.ts';
+import type { GitHubClient } from './github-client.ts';
+import { resolvePlatformContext } from './context.ts';
+import { platformResult } from './types.ts';
+
+type ReleaseSnapshot = { tag: string; published: boolean; draft: boolean; url: string | null };
+type ReleaseOptions = { cwd?: string; client?: GitHubClient };
+
+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 });
+  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 };
+  }
+  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,headBranch,status,conclusion,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 };
+}
+
+function upsertPlatformRelease(input: { tag: string; title?: string; notesFile?: string }, options: ReleaseOptions = {}) {
+  const inspected = 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' }] };
+}
+
+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 });
+  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 ensure = [`${major}.${minor}.${patch + 1}`, `${major}.${minor}.x`];
+  if (patch === 0) ensure.push(`${major}.${minor + 1}.0`, `${major}.${minor + 1}.x`);
+  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 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}`], { cwd: options.cwd });
+      operations.push({ name: 'ensure-milestone', title, status: created.ok ? 'applied' : 'failed' });
+    }
+  }
+  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 };
+}
+
+export { inspectPlatformRelease, reconcileReleaseMilestones, upsertPlatformRelease };