@fitlab-ai/agent-infra 0.9.10 → 0.9.12

package/lib/platform/verification-required.ts

@@ -6,6 +6,7 @@ import { hasPlatformCapability } from "./adapters.ts";
 import { inspectRequiredChecks } from "./pr-checks.ts";
 import { resolvePlatformContext } from "./context.ts";
 import { resolveReviewedHeadRelation } from "./merged-pr-equivalence.ts";
+import { readPrDeliveryFact } from "../task/pr-delivery-fact.ts";
 
 const CHECK_TYPE = "required-checks";
 const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
@@ -34,7 +35,13 @@ function readHead(repoRoot: any): any {
 
 export function evaluateRequiredChecks(context: any, shared: any): any {
   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 prNumber = fact?.state === "bound" ? fact.identity.number : null;
+  if (prFlow === "disabled" || fact?.state === "skipped" || !validPrNumber(prNumber)) {
     return shared.passResult(CHECK_TYPE, "Skipped: required checks are not applicable to this task");
   }
 
@@ -87,7 +94,10 @@ export function check({ taskDir }: any, shared: any): any {
   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 });

package/lib/platform/verification-sync.ts

@@ -10,6 +10,7 @@ import { inspectGitHubIssueMetadata, requirementSectionAnchors } from "./issues.
 import { listRemoteComments } from "./issue-comments.ts";
 import { taskTypeLabel } from "./metadata-labels.ts";
 import { inspectGitHubPullRequest } from "./pull-requests.ts";
+import { readPrDeliveryFact } from "../task/pr-delivery-fact.ts";
 
 const CHECK_TYPE = "platform-sync";
 const VERSION_LINE_REGEX = /^[0-9]+\.[0-9]+\.x$/;
@@ -151,12 +152,16 @@ function buildSyncContext({ taskDir, config, artifactFile }: any): any {
   }
 
   const issueNumber = parseIssueNumber(task.metadata.issue_number);
-  const prNumber = parsePrNumber(task.metadata.pr_number);
+  const fact = readPrDeliveryFact(task.metadata);
+  if (fact.status === "invalid") {
+    return { earlyReturn: failResult(CHECK_TYPE, fact.error.message, "check_failed") };
+  }
+  const prNumber = fact.status === "valid" && fact.fact.state === "bound" ? fact.fact.identity.number : null;
   if (config.when === "issue_number_exists" && !issueNumber) {
     return { earlyReturn: passResult(CHECK_TYPE, "Skipped: task has no issue_number") };
   }
-  if (config.when === "pr_number_exists" && !prNumber) {
-    return { earlyReturn: passResult(CHECK_TYPE, "Skipped: task has no pr_number") };
+  if (config.when === "pr_fact_bound" && !prNumber) {
+    return { earlyReturn: passResult(CHECK_TYPE, "Skipped: task has no verified bound pull request") };
   }
 
   if (!issueNumber) {
@@ -322,7 +327,7 @@ function fetchRemoteData(context: any): any {
   if (context.prMarker) {
     if (!context.prNumber) {
       return {
-        earlyReturn: failResult(CHECK_TYPE, "Expected a valid pr_number for PR comment verification", "check_failed")
+        earlyReturn: failResult(CHECK_TYPE, "Expected a verified bound pull request for PR comment verification", "check_failed")
       };
     }
 

package/lib/pr-review/evidence-grading.ts

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { parseTaskFrontmatter } from '../task/frontmatter.ts';
+import { parseTypedTaskFrontmatter } from '../task/frontmatter.ts';
+import { readPrDeliveryFact } from '../task/pr-delivery-fact.ts';
 
 // ---------------------------------------------------------------------------
 // Host resolution (PL-4): PR -> unique / ambiguous / none.
@@ -62,7 +63,7 @@ export function extractClosingIssueNumbers(body: string): number[] {
 /**
  * Scan `.agents/workspace/active/{task-id}/task.md` files for tasks bound to the
  * PR number or to one of the PR's closing issues. A task is emitted at most once;
- * a direct `pr_number` hit takes priority over the issue-number reverse lookup.
+ * a verified fact identity hit takes priority over the issue-number reverse lookup.
  */
 export function collectHostCandidates(input: {
   prNumber: number;
@@ -87,9 +88,11 @@ export function collectHostCandidates(input: {
     } catch {
       continue;
     }
-    const frontmatter = parseTaskFrontmatter(content);
+    let frontmatter: ReturnType<typeof parseTypedTaskFrontmatter>;
+    try { frontmatter = parseTypedTaskFrontmatter(content); } catch { continue; }
     const issueNumber = toPositiveNumber(frontmatter.issue_number);
-    const prNumber = toPositiveNumber(frontmatter.pr_number);
+    const fact = readPrDeliveryFact(frontmatter);
+    const prNumber = fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.number : null;
     if (prNumber === input.prNumber) {
       candidates.push({ taskId: entry.name, taskDir, issueNumber, prNumber });
     } else if (issueNumber !== null && input.closingIssues.includes(issueNumber)) {

package/lib/process-data/normalize.ts

@@ -1,4 +1,5 @@
 import { sha256 } from './store.ts';
+import { normalizeAgentToken } from '../agent-clients/tokens.ts';
 
 import type { CapturedObject, JsonValue, NormalizedKind, NormalizedRecord } from './types.ts';
 
@@ -14,14 +15,7 @@ function recordId(kind: NormalizedKind, identity: string, suffix = ''): string {
 
 function canonicalActor(raw: string): string | null {
   const lowered = raw.toLowerCase();
-  const aliases: Record<string, string> = {
-    'claude-code': 'claude',
-    'antigravity-cli': 'antigravity',
-    'gemini-cli': 'gemini',
-    gemini: 'gemini'
-  };
-  if (['claude', 'codex', 'antigravity', 'opencode', 'cursor', 'human'].includes(lowered)) return lowered;
-  return aliases[lowered] ?? null;
+  return normalizeAgentToken(lowered);
 }
 
 function nextOccurrence(occurrences: Map<string, number>, identity: string): string {

package/lib/run/host.ts

@@ -9,27 +9,74 @@ export type RunProcessResult = {
   stderr?: string;
 };
 
-function resolveCommand(file: string): string {
-  if (process.platform !== 'win32' || path.extname(file)) {
-    return file;
-  }
+type CommandResolution = Readonly<{
+  path: string;
+  source: 'absolute' | 'path' | 'current-directory' | 'unresolved';
+  pathEntry?: string;
+}>;
+
+function resolveCommandDetails(
+  file: string,
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env
+): CommandResolution {
+  if (path.isAbsolute(file)) return { path: file, source: 'absolute' };
 
-  const pathValue = process.env.Path || process.env.PATH || '';
-  const extensions = (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
-  for (const dir of pathValue.split(path.delimiter).filter(Boolean)) {
+  const pathValue = platform === 'win32'
+    ? env.Path || env.PATH || ''
+    : env.PATH || '';
+  const extensions = platform === 'win32'
+    ? (path.extname(file)
+      ? ['']
+      : (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean))
+    : [''];
+  for (const dir of pathValue.split(path.delimiter)) {
     for (const extension of extensions) {
-      const lowerCandidate = path.join(dir, `${file}${extension.toLowerCase()}`);
-      if (fs.existsSync(lowerCandidate)) return lowerCandidate;
-      const upperCandidate = path.join(dir, `${file}${extension.toUpperCase()}`);
-      if (fs.existsSync(upperCandidate)) return upperCandidate;
+      const candidates = extension
+        ? [`${file}${extension.toLowerCase()}`, `${file}${extension.toUpperCase()}`]
+        : [file];
+      for (const candidateName of candidates) {
+        const candidate = path.resolve(dir || '.', candidateName);
+        try {
+          const stat = fs.statSync(candidate);
+          if (!stat.isFile()) continue;
+          if (platform !== 'win32' && (stat.mode & 0o111) === 0) continue;
+          return {
+            path: candidate,
+            source: dir ? 'path' : 'current-directory',
+            pathEntry: dir
+          };
+        } catch {
+          // Keep searching the remaining PATH entries.
+        }
+      }
     }
   }
 
-  return file;
+  return { path: file, source: 'unresolved' };
+}
+
+function resolveCommand(
+  file: string,
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env
+): string {
+  return resolveCommandDetails(file, platform, env).path;
 }
 
-function needsShell(file: string): boolean {
-  return process.platform === 'win32' && /\.(?:bat|cmd)$/i.test(file);
+function resolveCommandFromAbsolutePath(
+  file: string,
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env
+): string | null {
+  const resolution = resolveCommandDetails(file, platform, env);
+  return resolution.source === 'path' && resolution.pathEntry && path.isAbsolute(resolution.pathEntry)
+    ? resolution.path
+    : null;
+}
+
+function needsShell(file: string, platform: NodeJS.Platform = process.platform): boolean {
+  return platform === 'win32' && /\.(?:bat|cmd)$/i.test(file);
 }
 
 export async function runHostCommand(command: string[]): Promise<RunProcessResult> {
@@ -45,3 +92,5 @@ export async function runHostCommand(command: string[]): Promise<RunProcessResul
     child.on('close', (exitCode, signal) => resolve({ exitCode, signal }));
   });
 }
+
+export { needsShell, resolveCommand, resolveCommandFromAbsolutePath };

package/lib/sandbox/agent-client-reconciler.ts

@@ -28,7 +28,7 @@ type SandboxCapabilityConfig = Readonly<{
   project: string;
   tools: readonly string[];
   customTools?: readonly SandboxTool[];
-  agentClientState?: AgentClientState;
+  agentClientState: AgentClientState;
 }>;
 
 type SandboxRuntimeCapabilityProjection = Readonly<{
@@ -98,18 +98,6 @@ function agentInfraTool(home: string): SandboxTool {
   };
 }
 
-function compatAgentClientState(tools: readonly string[]): AgentClientState {
-  return Object.fromEntries(
-    listAgentClientAdapters().map((adapter) => [
-      adapter.id,
-      {
-        enabled: true,
-        installInSandbox: tools.includes(adapter.id)
-      }
-    ])
-  ) as AgentClientState;
-}
-
 function stableValue(value: unknown): unknown {
   if (Array.isArray(value)) {
     return value.map(stableValue);
@@ -206,7 +194,7 @@ function hooksByPhase(
 function createSandboxCapabilityPlan(
   config: SandboxCapabilityConfig
 ): SandboxCapabilityPlan {
-  const state = config.agentClientState ?? compatAgentClientState(config.tools);
+  const state = config.agentClientState;
   const selectedAgentClients = listInstalledAgentClientAdapters(state);
   const context = { home: config.home, project: config.project };
   const selectedTools = selectedAgentClients.map((adapter) =>
@@ -228,7 +216,9 @@ function createSandboxCapabilityPlan(
   const nonClientTools: SandboxTool[] = [];
   const selectedCustomTools: SandboxTool[] = [];
   for (const id of config.tools) {
-    if (isAgentClientId(id)) continue;
+    if (isAgentClientId(id)) {
+      throw new Error(`Agent Client '${id}' must be provided by agentClientState`);
+    }
     if (id === 'agent-infra') {
       if (!nonClientTools.some((tool) => tool.id === id)) {
         nonClientTools.push(agentInfraTool(config.home));

package/lib/sandbox/commands/create.ts

@@ -77,7 +77,7 @@ import {
   commitSandboxControlReplacement,
   quiesceSandboxControlRoot,
   recoverSandboxControlReplacement,
-  readSandboxControlManifestForTransition
+  readSandboxControlManifest
 } from '../control/lifecycle.ts';
 import { inspectSandboxControlContainer } from '../control/container-identity.ts';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.ts';
@@ -1250,7 +1250,7 @@ export async function create(args: string[]): Promise<void> {
             const recoveryResult = await recoverSandboxControlReplacement(controlPaths.root, replacementLease);
             const hadExistingControlRoot = hadControlRootBeforeAcquire || recoveryResult === 'restored';
             const previousManifest = fs.existsSync(controlPaths.manifestPath)
-              ? readSandboxControlManifestForTransition(controlPaths.manifestPath)
+              ? readSandboxControlManifest(controlPaths.manifestPath)
               : null;
             if (hadExistingControlRoot) {
               await quiesceSandboxControlRoot(controlPaths.root);
@@ -1423,10 +1423,10 @@ export async function create(args: string[]): Promise<void> {
               ...(target.workspace.mode === 'task-bound' ? { runtimeDir: control.runtimeDir } : {}),
               ...(target.workspace.mode === 'task-bound'
                 ? {
-                  taskSource: assertSandboxTaskSource(
+                  taskSources: [assertSandboxTaskSource(
                     effectiveConfig.repoRoot,
                     target.workspace.taskId
-                  ),
+                  )],
                   taskId: target.workspace.taskId
                 }
                 : {})

package/lib/sandbox/commands/enter.ts

@@ -3,7 +3,9 @@ import {
   assertValidBranchName,
   containerNameCandidates,
   sandboxBranchLabel,
-  sandboxLabel
+  sandboxLabel,
+  sandboxTaskIdLabel,
+  sandboxWorkspaceModeLabel
 } from '../constants.ts';
 import { detectEngine } from '../engine.ts';
 import { ensureSandboxReady } from '../recovery.ts';
@@ -21,7 +23,10 @@ import {
   fetchSandboxRows,
   selectSandboxContainer,
 } from './list-running.ts';
-import { resolveSandboxTarget } from '../workspace-identity.ts';
+import {
+  resolveSandboxReentryContext,
+  resolveSandboxTarget
+} from '../workspace-identity.ts';
 
 const USAGE = `Usage: ai sandbox exec [--recreate] <branch | TASK-id | N> [cmd...]
 
@@ -128,7 +133,11 @@ export async function enter(args: string[]): Promise<number> {
   const { running, nonRunning } = fetchSandboxRows(
     engine,
     sandboxLabel(config),
-    sandboxBranchLabel(config)
+    sandboxBranchLabel(config),
+    {
+      mode: sandboxWorkspaceModeLabel(config),
+      taskId: sandboxTaskIdLabel(config)
+    }
   );
   const found = selectSandboxContainer(
     [...running, ...nonRunning],
@@ -140,11 +149,22 @@ export async function enter(args: string[]): Promise<number> {
       `No sandbox found for branch '${branch}'. Run 'ai sandbox create ${branch}' to create one.`
     );
   }
+  const containerWorkspace = found.workspaceMode === 'task-bound' && found.taskId
+    ? { mode: 'task-bound' as const, taskId: found.taskId }
+    : found.workspaceMode === 'branch-only'
+      ? { mode: 'branch-only' as const }
+      : { mode: 'legacy-invalid' as const };
+  const reentry = resolveSandboxReentryContext({
+    target,
+    containerWorkspace,
+    repoRoot: config.repoRoot
+  });
   const ready = await ensureSandboxReady({
     config,
     engine,
     branch,
-    workspace: target.workspace,
+    workspace: reentry.workspace,
+    reentry: reentry.reentry,
     row: found,
     allowRecreate: parsed.recreate,
     recreate: async () => {

package/lib/sandbox/config.ts

@@ -4,7 +4,6 @@ import { homedir, platform } from 'node:os';
 import { execFileSync } from 'node:child_process';
 import pc from 'picocolors';
 import { normalizeAgentClients } from '../agent-clients/config.ts';
-import { isAgentClientId } from '../agent-clients/types.ts';
 import type { AgentClientState } from '../agent-clients/types.ts';
 import { validateSandboxEngine } from './engine.ts';
 import type { SandboxEngineInput } from './engine.ts';
@@ -64,7 +63,7 @@ export type SandboxConfig = {
   tools: string[];
   customTools: SandboxTool[];
   agentClientState: AgentClientState;
-  agentClientSource: 'canonical' | 'legacy';
+  delivery?: { remote: string; baseRef: string };
   refreshIntervalDays: number;
   dockerfile: string | null;
   vm: SandboxVmConfig;
@@ -74,8 +73,8 @@ type AircConfig = {
   project?: unknown;
   org?: unknown;
   agentClients?: unknown;
-  tuis?: unknown;
   sandbox?: SandboxConfigInput;
+  delivery?: { remote?: unknown; baseRef?: unknown };
 };
 
 function detectRepoRoot(): string {
@@ -110,17 +109,10 @@ function cloneDefaults(): SandboxConfigInput & { vm: SandboxVmConfig; runtimes:
 
 function resolveSandboxToolIds(
   sandbox: SandboxConfigInput,
-  agentClients: ReturnType<typeof normalizeAgentClients>,
   defaults: readonly string[]
 ): string[] {
   if (Array.isArray(sandbox.tools)) {
-    const tools = sandbox.tools.filter((tool): tool is string => typeof tool === 'string');
-    return agentClients.source === 'canonical'
-      ? tools.filter((tool) => !isAgentClientId(tool))
-      : tools;
-  }
-  if (agentClients.remainingSandboxTools !== undefined) {
-    return [...agentClients.remainingSandboxTools];
+    return sandbox.tools.filter((tool): tool is string => typeof tool === 'string');
   }
   return [...defaults];
 }
@@ -142,10 +134,10 @@ export function loadConfig({
   }
 
   const airc = JSON.parse(fs.readFileSync(configPath, 'utf8')) as AircConfig;
-  const sandboxInput = airc.sandbox;
   const agentClients = normalizeAgentClients(airc);
   const defaults = cloneDefaults();
   const sandbox = airc.sandbox ?? {};
+  const delivery = airc.delivery ?? {};
   const engine = validateSandboxEngine(sandbox.engine ?? defaults.engine, { platformFn });
   const project = airc.project;
 
@@ -178,7 +170,7 @@ export function loadConfig({
   }
 
   const customTools = parseCustomTools(sandbox.customTools, { home });
-  const tools = resolveSandboxToolIds(sandbox, agentClients, defaults.tools);
+  const tools = resolveSandboxToolIds(sandbox, defaults.tools);
 
   return {
     repoRoot,
@@ -199,7 +191,10 @@ export function loadConfig({
     tools,
     customTools,
     agentClientState: agentClients.state,
-    agentClientSource: agentClients.source,
+    delivery: {
+      remote: typeof delivery.remote === 'string' ? delivery.remote : 'origin',
+      baseRef: typeof delivery.baseRef === 'string' ? delivery.baseRef : 'main'
+    },
     refreshIntervalDays: asNonNegativeIntegerOrDefault(
       sandbox.refreshIntervalDays,
       defaults.refreshIntervalDays

package/lib/sandbox/control/container-identity.ts

@@ -1,4 +1,4 @@
-import type { SandboxControlManifest, SandboxControlManifestLike } from './protocol.ts';
+import type { SandboxControlManifest } from './protocol.ts';
 import { commandForEngine, runEngine, runProbe } from '../shell.ts';
 
 export type ContainerObservation =
@@ -48,7 +48,7 @@ export function classifySandboxContainerInspection(
 }
 
 export async function inspectSandboxControlContainer(
-  manifest: SandboxControlManifestLike,
+  manifest: SandboxControlManifest,
   options: { run?: typeof runEngine; probe?: typeof runProbe; timeoutMs?: number } = {}
 ): Promise<ContainerObservation> {
   try {