@tryinget/pi-agent-registry 0.3.0

package/src/agent-skill-resolver.ts

@@ -0,0 +1,50 @@
+// ---
+// summary: registry-owned ExtraSkillProfileResolver mapping standing-agent names onto materialized skill selections.
+// read_when:
+//   - changing how ASC resolves pi-agent-registry agent names as skill profiles.
+// ---
+
+import type { ExtraSkillProfileResolver } from "@tryinget/pi-autonomous-session-control/execution";
+import { materializeSkillDirs, planSkillSelection } from "./ec-profiles.ts";
+import type { AgentRegistry } from "./registry.ts";
+
+export const AGENT_SKILL_REGISTRY_LABEL = "pi-agent-registry" as const;
+
+/**
+ * Fleet Phase-2 skill seam: the registry resolves its own agent names for the
+ * ASC runtime's extraSkillProfileResolver hook. ASC consults this only after
+ * its built-in skill-librarian registry misses, and ASC owns cleanup of the
+ * materialized selection once the dispatched child settles.
+ *
+ * Returning undefined declines the profile so ASC fails closed with its own
+ * diagnostics; SubagentSkillSelectionError marks registry-owned fail-closed
+ * paths (unknown extra skill, unknown EC profile, filesystem failure).
+ */
+export function createAgentSkillProfileResolver(
+  registry: AgentRegistry,
+): ExtraSkillProfileResolver {
+  return async (profile) => {
+    const manifest = registry.get(profile);
+    if (!manifest) {
+      return undefined;
+    }
+    const selection = planSkillSelection({
+      ...(manifest.skills?.profile !== undefined ? { profile: manifest.skills.profile } : {}),
+      ...(manifest.skills?.extra ? { extra: manifest.skills.extra } : {}),
+      ec: registry.ec,
+      manifestRoot: manifest.root,
+      userSkillsRoot: registry.userSkillsRoot,
+    });
+    const materialized = await materializeSkillDirs(selection, manifest.name);
+    return {
+      noSkills: true,
+      skillSources: [materialized.dir],
+      skillProfile: manifest.name,
+      loadedSkills: materialized.skills,
+      librarySkills: [],
+      skillWarnings: [],
+      skillRegistry: AGENT_SKILL_REGISTRY_LABEL,
+      cleanup: materialized.cleanup,
+    };
+  };
+}

package/src/asc-execution-surface.ts

@@ -0,0 +1,64 @@
+// ---
+// summary: capability-checked loader for the ASC-owned execution surface used by Fleet Phase-2 dispatch.
+// read_when:
+//   - changing how pi-agent-registry consumes ASC runtime/session/model contracts.
+// ---
+
+import type {
+  AscExecutionRuntime,
+  ResolvedSubagentModelSelection,
+  ResolvedSubagentSessionsDir,
+} from "@tryinget/pi-autonomous-session-control/execution";
+
+export interface AscExecutionSurface {
+  createAscExecutionRuntime: (options: unknown) => AscExecutionRuntime;
+  resolveSubagentSessionsDir: (options?: {
+    explicitDir?: string;
+    cwd?: string;
+    agentDir?: string;
+    sessionDirEnv?: string;
+  }) => ResolvedSubagentSessionsDir;
+  resolveSubagentModelSelection: (ctx?: {
+    model?: { provider?: unknown; id?: unknown };
+  }) => ResolvedSubagentModelSelection;
+}
+
+let cached: AscExecutionSurface | undefined | "unloaded" = "unloaded";
+
+/**
+ * Load ASC's exported execution surface. The registry declares the ASC
+ * dependency as a workspace link; an installed/published ASC that predates
+ * the execution exports resolves to `undefined` and every Phase-2 dispatch
+ * fails closed with `asc_execution_unavailable` (confirmed_no_effects).
+ * Execution machinery stays ASC-owned; this loader only checks capability.
+ */
+export async function loadAscExecutionSurface(): Promise<AscExecutionSurface | undefined> {
+  if (cached !== "unloaded") {
+    return cached;
+  }
+  try {
+    const mod = (await import("@tryinget/pi-autonomous-session-control/execution")) as Record<
+      string,
+      unknown
+    >;
+    const surface = {
+      createAscExecutionRuntime: mod.createAscExecutionRuntime,
+      resolveSubagentSessionsDir: mod.resolveSubagentSessionsDir,
+      resolveSubagentModelSelection: mod.resolveSubagentModelSelection,
+    };
+    cached =
+      typeof surface.createAscExecutionRuntime === "function" &&
+      typeof surface.resolveSubagentSessionsDir === "function" &&
+      typeof surface.resolveSubagentModelSelection === "function"
+        ? (surface as AscExecutionSurface)
+        : undefined;
+  } catch {
+    cached = undefined;
+  }
+  return cached;
+}
+
+/** Test-only surface cache reset. */
+export function resetAscExecutionSurfaceCache(): void {
+  cached = "unloaded";
+}

package/src/dispatch-authorization.ts

@@ -0,0 +1,237 @@
+// ---
+// summary: exact-task AK authorization reads and dispatch evidence recording through the ak CLI boundary.
+// read_when:
+//   - changing task authorization rules or AK evidence semantics for standing-agent dispatch.
+// ---
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import {
+  type AkTaskSnapshot,
+  DISPATCH_EVIDENCE_CHECK_TYPE,
+  DISPATCH_PHASE,
+  DISPATCH_RECEIPT_SCHEMA,
+} from "./dispatch-contract.ts";
+
+const execFileAsync = promisify(execFile);
+
+const AK_TIMEOUT_MS = 15_000;
+
+export type AkAuthorizationFailureCode =
+  | "ak_unavailable"
+  | "task_not_found"
+  | "task_repo_mismatch"
+  | "task_not_claimed"
+  | "task_lease_expired";
+
+export class AkAuthorizationError extends Error {
+  readonly code: AkAuthorizationFailureCode;
+
+  constructor(code: AkAuthorizationFailureCode, message: string) {
+    super(message);
+    this.name = "AkAuthorizationError";
+    this.code = code;
+  }
+}
+
+/** Read one exact AK task through `ak task show <id> -F json` (read-only). */
+export async function readAkTask(
+  taskId: number,
+  options?: { akBinary?: string },
+): Promise<AkTaskSnapshot> {
+  const akBinary = options?.akBinary ?? "ak";
+  let stdout: string;
+  try {
+    const result = await execFileAsync(akBinary, ["task", "show", String(taskId), "-F", "json"], {
+      timeout: AK_TIMEOUT_MS,
+      maxBuffer: 1024 * 1024,
+      windowsHide: true,
+    });
+    stdout = result.stdout;
+  } catch {
+    throw new AkAuthorizationError(
+      "ak_unavailable",
+      `AK task ${taskId} could not be read (ak task show failed); dispatch authorization is unverifiable`,
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    throw new AkAuthorizationError(
+      "ak_unavailable",
+      `AK task ${taskId} produced unparseable output; dispatch authorization is unverifiable`,
+    );
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new AkAuthorizationError("task_not_found", `AK task ${taskId} returned no task object`);
+  }
+  const row = parsed as Record<string, unknown>;
+  const id = row.id;
+  const repo = row.repo;
+  const title = row.title;
+  if (typeof id !== "number" || id !== taskId || typeof repo !== "string" || !repo) {
+    throw new AkAuthorizationError(
+      "task_not_found",
+      `AK task ${taskId} returned an unusable task identity`,
+    );
+  }
+  return {
+    id,
+    repo,
+    title: typeof title === "string" ? title : "",
+    status: typeof row.status === "string" ? row.status : "",
+    claimed_by: typeof row.claimed_by === "string" && row.claimed_by ? row.claimed_by : null,
+    lease_expires_at:
+      typeof row.lease_expires_at === "string" && row.lease_expires_at
+        ? row.lease_expires_at
+        : null,
+  };
+}
+
+/**
+ * Phase-2 exact-task authorization: the task must exist, be registered to the
+ * dispatch-origin repository, and carry a live claim. Readiness never becomes
+ * authorization — only an in-flight claim authorizes one read-only dispatch.
+ */
+export function authorizeExactTask(
+  task: AkTaskSnapshot,
+  expectedRepoRoot: string,
+): { ok: true } | { ok: false; code: AkAuthorizationFailureCode; message: string } {
+  if (normalizeRepoPath(task.repo) !== normalizeRepoPath(expectedRepoRoot)) {
+    return {
+      ok: false,
+      code: "task_repo_mismatch",
+      message: `AK task ${task.id} belongs to repo ${task.repo}; dispatch origin is ${expectedRepoRoot}`,
+    };
+  }
+  if (task.status !== "claimed") {
+    return {
+      ok: false,
+      code: "task_not_claimed",
+      message: `AK task ${task.id} status is "${task.status}"; only a claimed task authorizes one read-only standing-agent dispatch`,
+    };
+  }
+  if (!task.claimed_by) {
+    return {
+      ok: false,
+      code: "task_not_claimed",
+      message: `AK task ${task.id} is claimed without a claimant; authorization is unverifiable`,
+    };
+  }
+  if (task.lease_expires_at) {
+    const expiry = Date.parse(task.lease_expires_at);
+    if (!Number.isFinite(expiry) || expiry <= Date.now()) {
+      return {
+        ok: false,
+        code: "task_lease_expired",
+        message: `AK task ${task.id} claim lease is expired or unparseable; re-claim before dispatch`,
+      };
+    }
+  } else {
+    return {
+      ok: false,
+      code: "task_lease_expired",
+      message: `AK task ${task.id} carries no lease expiry; authorization is unverifiable`,
+    };
+  }
+  return { ok: true };
+}
+
+function normalizeRepoPath(value: string): string {
+  return value.replace(/\/+$/u, "");
+}
+
+/** Typed AK evidence details for one settled Phase-2 dispatch. */
+export function buildDispatchEvidenceDetails(facts: {
+  agent: string;
+  agentRepoCommit: string;
+  manifestSha256: string;
+  task: number;
+  attemptIndex: number;
+  dispatchId: string;
+  attemptId: string;
+  sessionName: string;
+  effectDisposition: string;
+  effectCorrelationId: string;
+  effectCorrelationEchoVerified: boolean;
+  noMutationObserved: boolean;
+  outputSha256: string;
+  receiptSha256: string;
+  receiptName?: string;
+}): Record<string, unknown> {
+  return {
+    schema: DISPATCH_RECEIPT_SCHEMA,
+    phase: DISPATCH_PHASE,
+    agent: facts.agent,
+    agentRepoCommit: facts.agentRepoCommit,
+    manifestSha256: facts.manifestSha256,
+    task: facts.task,
+    attemptIndex: facts.attemptIndex,
+    dispatchId: facts.dispatchId,
+    attemptId: facts.attemptId,
+    sessionName: facts.sessionName,
+    effectDisposition: facts.effectDisposition,
+    effectCorrelationId: facts.effectCorrelationId,
+    effectCorrelationEchoVerified: facts.effectCorrelationEchoVerified,
+    noMutationObserved: facts.noMutationObserved,
+    outputSha256: facts.outputSha256,
+    receiptSha256: facts.receiptSha256,
+    ...(facts.receiptName ? { receiptName: facts.receiptName } : {}),
+  };
+}
+
+export interface AkEvidenceRecordResult {
+  evidenceId: number;
+}
+
+export interface AkEvidenceRecordFailure {
+  error: Error;
+}
+
+/**
+ * Append one typed AK evidence row for a completed dispatch. Evidence is
+ * recorded only for a settled, no-mutation-observed dispatch; failures keep
+ * the immutable receipt as truth and leave AK recording to the parent task.
+ */
+export async function recordDispatchEvidence(
+  params: {
+    taskId: number;
+    details: Record<string, unknown>;
+  },
+  options?: { akBinary?: string },
+): Promise<AkEvidenceRecordResult> {
+  const akBinary = options?.akBinary ?? "ak";
+  const detailsJson = JSON.stringify(params.details);
+  let stdout: string;
+  try {
+    const result = await execFileAsync(
+      akBinary,
+      [
+        "evidence",
+        "record",
+        "--task",
+        String(params.taskId),
+        "--check-type",
+        DISPATCH_EVIDENCE_CHECK_TYPE,
+        "--result",
+        "pass",
+        "--details",
+        detailsJson,
+      ],
+      { timeout: AK_TIMEOUT_MS, maxBuffer: 1024 * 1024, windowsHide: true },
+    );
+    stdout = result.stdout;
+  } catch (error) {
+    throw new Error(
+      `AK evidence recording failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  const id = Number(
+    /Recorded evidence\s+#?(\d+)/iu.exec(stdout)?.[1] ?? /#(\d+)/u.exec(stdout)?.[1],
+  );
+  if (!Number.isInteger(id) || id <= 0) {
+    throw new Error(`AK evidence recording returned no evidence id (output: ${stdout.trim()})`);
+  }
+  return { evidenceId: id };
+}

package/src/dispatch-contract.ts

@@ -0,0 +1,89 @@
+// ---
+// summary: Fleet Phase-2 exact-task read-only standing-agent dispatch contract constants and types.
+// read_when:
+//   - changing the dispatch_agent Phase-2 gate, eligibility rules, or receipt/evidence semantics.
+// ---
+
+/**
+ * Fleet Phase 2 enables exactly one bounded execution shape:
+ * one registered standing agent, bound to one exact claimed AK task,
+ * read-only, executed through the ASC-owned runtime, recorded as one
+ * immutable receipt plus one AK evidence row. Everything else stays
+ * fail-closed exactly as in Phase 0/1.
+ */
+export const DISPATCH_PHASE = "fleet_phase_2" as const;
+
+export const DISPATCH_RECEIPT_SCHEMA = "pi-agent-registry.dispatch-receipt/1" as const;
+
+export const DISPATCH_EVIDENCE_CHECK_TYPE = "standing-agent-dispatch" as const;
+
+/**
+ * Tool allowlist for Phase-2 read-only dispatch. `bash` is admitted only as
+ * the fleet's established read-only exploration instrument (profile parity
+ * with ASC explorer/reviewer/tester/researcher); mutation tools are excluded
+ * and the child task contract plus parent-side observation bound the posture.
+ */
+export const READ_ONLY_DISPATCH_TOOLS: readonly string[] = ["read", "bash"];
+
+/**
+ * Provenance marker injected into every dispatched standing-agent child.
+ * `dispatch_agent` refuses to run inside a session that already carries it,
+ * keeping standing-agent dispatch one level deep.
+ */
+export const DISPATCH_CHILD_PROVENANCE_ENV = "PI_PROVENANCE_STANDING_AGENT_DISPATCH" as const;
+
+/** Default bounded child execution timeout (seconds) for Phase-2 dispatch. */
+export const DISPATCH_EXECUTION_TIMEOUT_SECONDS = 900;
+
+/** Default bounded child startup timeout (seconds) for Phase-2 dispatch. */
+export const DISPATCH_STARTUP_TIMEOUT_SECONDS = 120;
+
+/** Bounded retry posture: a failed attempt never burns the pair, but at most
+ * this many receipts may exist per (agent, exact task) pair, and only ONE may
+ * be settled. */
+export const MAX_DISPATCH_ATTEMPTS_PER_PAIR = 3;
+
+export type DispatchFailureReason =
+  | "invalid_request"
+  | "recursive_dispatch"
+  | "unknown_agent"
+  | "agent_not_read_only"
+  | "agent_repo_dirty"
+  | "agent_repo_drift"
+  | "agent_resolution_failed"
+  | "dispatch_already_recorded"
+  | "dispatch_attempts_exhausted"
+  | "ak_unavailable"
+  | "asc_execution_unavailable"
+  | "task_not_found"
+  | "task_repo_mismatch"
+  | "task_not_claimed"
+  | "task_lease_expired"
+  | "parent_repo_unobservable"
+  | "dispatch_failed"
+  | "read_only_violation_observed"
+  | "receipt_write_failed"
+  | "evidence_record_failed";
+
+export interface AkTaskSnapshot {
+  id: number;
+  repo: string;
+  title: string;
+  status: string;
+  claimed_by: string | null;
+  lease_expires_at: string | null;
+}
+
+export interface DispatchAgentRequest {
+  /** Registered standing-agent name (agent.json `name`). */
+  agent: string;
+  /** Exact AK task id that authorizes this one read-only dispatch. */
+  task: number;
+  /** Bounded read-only objective for the dispatched agent. */
+  objective: string;
+}
+
+export interface DispatchEffectFact {
+  spawnAttempted: boolean;
+  effectDisposition: "confirmed_no_effects" | "settled" | "effect_indeterminate";
+}