@tryinget/pi-agent-registry 0.3.0

package/src/registry-discovery.ts

@@ -0,0 +1,225 @@
+// ---
+// summary: streaming bounded one-repo-per-agent discovery shared by runtime registry loading and aggregate fleet lint.
+// read_when:
+//   - changing fleet roots, zero-match behavior, missing-manifest visibility, discovery depth, or duplicate roots.
+// ---
+
+import { lstat, opendir, realpath } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { AGENT_MANIFEST_FILENAME, globToRegExp } from "./manifest.ts";
+
+const DISCOVERY_SKIP_DIRS: ReadonlySet<string> = new Set([
+  "node_modules",
+  ".git",
+  ".cache",
+  "dist",
+  "build",
+]);
+
+export interface DiscoveredAgentRepository {
+  root: string;
+  manifestPath: string;
+  manifestPresent: boolean;
+}
+
+export interface FailedAgentRepositoryDiscovery {
+  root: string;
+  code: "repository.resolve_failed";
+}
+
+export class RegistryDiscoveryError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "RegistryDiscoveryError";
+    this.code = code;
+  }
+}
+
+function comparePaths(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function heapUp(paths: string[], start: number): void {
+  let index = start;
+  while (index > 0) {
+    const parent = Math.floor((index - 1) / 2);
+    if (comparePaths(paths[parent], paths[index]) >= 0) return;
+    [paths[parent], paths[index]] = [paths[index], paths[parent]];
+    index = parent;
+  }
+}
+
+function heapDown(paths: string[], start: number): void {
+  let index = start;
+  while (true) {
+    const left = index * 2 + 1;
+    const right = left + 1;
+    let largest = index;
+    if (left < paths.length && comparePaths(paths[left], paths[largest]) > 0) largest = left;
+    if (right < paths.length && comparePaths(paths[right], paths[largest]) > 0) largest = right;
+    if (largest === index) return;
+    [paths[index], paths[largest]] = [paths[largest], paths[index]];
+    index = largest;
+  }
+}
+
+function insertBounded(
+  paths: string[],
+  included: Set<string>,
+  candidate: string,
+  maxRepositories: number,
+): boolean {
+  if (included.has(candidate)) {
+    throw new RegistryDiscoveryError(
+      "fleet.duplicate_candidate",
+      "one agent repository was matched more than once by configured roots",
+    );
+  }
+  if (paths.length < maxRepositories) {
+    paths.push(candidate);
+    included.add(candidate);
+    heapUp(paths, paths.length - 1);
+    return true;
+  }
+  if (comparePaths(candidate, paths[0]) >= 0) return false;
+  included.delete(paths[0]);
+  paths[0] = candidate;
+  included.add(candidate);
+  heapDown(paths, 0);
+  return true;
+}
+
+export async function discoverAgentRepositories(
+  roots: string[],
+  strictMissingRoot: boolean,
+  maxRepositories = 5_000,
+): Promise<{
+  repositories: DiscoveredAgentRepository[];
+  failures: FailedAgentRepositoryDiscovery[];
+  omittedCount: number;
+}> {
+  if (!Number.isSafeInteger(maxRepositories) || maxRepositories <= 0) {
+    throw new RegistryDiscoveryError(
+      "fleet.repository_bound_invalid",
+      "maxRepositories must be a positive safe integer",
+    );
+  }
+  if (new Set(roots).size !== roots.length) {
+    throw new RegistryDiscoveryError(
+      "fleet.duplicate_roots",
+      "configured agent registry roots contain duplicates",
+    );
+  }
+
+  const candidateHeap: string[] = [];
+  const includedCandidates = new Set<string>();
+  let totalMatches = 0;
+  for (const configuredRoot of roots) {
+    const leafGlob = /[*?[]/u.test(configuredRoot);
+    if (!leafGlob) {
+      const info = await lstat(configuredRoot).catch(() => undefined);
+      if (!info?.isDirectory() || info.isSymbolicLink()) {
+        if (strictMissingRoot) {
+          throw new RegistryDiscoveryError(
+            "fleet.root_invalid",
+            "configured agent registry root is not one non-symlink directory",
+          );
+        }
+        continue;
+      }
+      totalMatches += 1;
+      insertBounded(candidateHeap, includedCandidates, configuredRoot, maxRepositories);
+      continue;
+    }
+
+    const scanDir = dirname(configuredRoot);
+    const directory = await opendir(scanDir).catch(() => undefined);
+    if (!directory) {
+      if (strictMissingRoot) {
+        throw new RegistryDiscoveryError(
+          "fleet.root_missing",
+          "configured agent registry root does not exist",
+        );
+      }
+      continue;
+    }
+    const leafPattern = globToRegExp(basename(configuredRoot));
+    let rootMatches = 0;
+    for await (const entry of directory) {
+      if (
+        !entry.isDirectory() ||
+        entry.name.startsWith(".") ||
+        DISCOVERY_SKIP_DIRS.has(entry.name) ||
+        !leafPattern.test(entry.name)
+      ) {
+        continue;
+      }
+      rootMatches += 1;
+      totalMatches += 1;
+      insertBounded(candidateHeap, includedCandidates, join(scanDir, entry.name), maxRepositories);
+    }
+    if (strictMissingRoot && rootMatches === 0) {
+      throw new RegistryDiscoveryError(
+        "fleet.root_zero_match",
+        "configured agent registry pattern matched no repositories",
+      );
+    }
+  }
+
+  const repositories: DiscoveredAgentRepository[] = [];
+  const failures: FailedAgentRepositoryDiscovery[] = [];
+  const candidates = candidateHeap.sort(comparePaths);
+  const physicalOwners = new Map<string, string>();
+  for (const candidate of candidates) {
+    const physical = await realpath(candidate).catch(() => undefined);
+    if (!physical) {
+      failures.push({ root: candidate, code: "repository.resolve_failed" });
+      continue;
+    }
+    const existing = physicalOwners.get(physical);
+    if (existing && existing !== candidate) {
+      throw new RegistryDiscoveryError(
+        "fleet.duplicate_physical_repository",
+        "one physical agent repository was configured through multiple logical roots",
+      );
+    }
+    physicalOwners.set(physical, candidate);
+    const manifestPath = join(physical, AGENT_MANIFEST_FILENAME);
+    const manifestInfo = await lstat(manifestPath).catch(() => undefined);
+    repositories.push({
+      root: physical,
+      manifestPath,
+      manifestPresent: Boolean(manifestInfo?.isFile() || manifestInfo?.isSymbolicLink()),
+    });
+  }
+
+  return {
+    repositories,
+    failures,
+    omittedCount: Math.max(0, totalMatches - repositories.length - failures.length),
+  };
+}
+
+export async function discoverAgentManifestPaths(
+  roots: string[],
+  strictMissingRoot: boolean,
+): Promise<string[]> {
+  const discovered = await discoverAgentRepositories(roots, strictMissingRoot);
+  if (discovered.failures.length > 0) {
+    throw new RegistryDiscoveryError(
+      "registry.repository_resolve_failed",
+      "one configured agent repository could not be resolved",
+    );
+  }
+  if (discovered.omittedCount > 0) {
+    throw new RegistryDiscoveryError(
+      "registry.repository_bound_exceeded",
+      "agent registry discovery exceeded its repository bound",
+    );
+  }
+  return discovered.repositories
+    .filter((entry) => entry.manifestPresent)
+    .map((entry) => entry.manifestPath);
+}

package/src/registry.ts

@@ -0,0 +1,280 @@
+// ---
+// summary: agent manifest discovery across roots, fail-closed name indexing, and name -> composed launch resolution.
+// read_when:
+//   - changing manifest discovery depth, registry roots configuration, or the resolution contract.
+// ---
+
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import {
+  type EcProfileSource,
+  knownEcProfiles,
+  loadEcProfiles,
+  materializeSkillDirs,
+  planSkillSelection,
+} from "./ec-profiles.ts";
+import {
+  type AgentManifest,
+  assertAgentExtensionsExist,
+  defaultUserSkillsRoot,
+  expandAgentActivities,
+  loadAgentManifest,
+  readAgentSystemPrompt,
+  resolveAgentExtensions,
+} from "./manifest.ts";
+import { discoverAgentManifestPaths } from "./registry-discovery.ts";
+
+export const AGENT_REGISTRY_ROOTS_ENV = "PI_AGENT_REGISTRY_ROOTS";
+export class AgentRegistryError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AgentRegistryError";
+  }
+}
+
+export interface AgentRegistryOptions {
+  /** Discovery roots (agent-repo patterns or explicit dirs; default: fleet patterns / PI_AGENT_REGISTRY_ROOTS). */
+  roots?: string[];
+  /** Explicit engineering-core profiles source (default: resolved from env or home). */
+  ec?: EcProfileSource;
+  /** Overrides the user-level skills root for `skills.extra` resolution. */
+  userSkillsRoot?: string;
+}
+
+export interface AgentListing {
+  name: string;
+  display_name?: string;
+  version?: string;
+  role?: string;
+  creation_task?: string;
+  tools: string[];
+  skills: { profile?: string; extra?: string[] };
+  extensions: string[];
+  defaults: { model: string | null; thinking: string };
+  activities: string[];
+  manifestPath: string;
+}
+
+export interface ResolvedAgentLaunch {
+  name: string;
+  /** Composed system prompt: system_prompt_file contents + rendered advisory scope. */
+  role?: string;
+  creation_task?: string;
+  systemPrompt: string;
+  /** Comma-separated tool allowlist for the ASC custom profile (read-only default: read). */
+  tools: string;
+  thinking: string;
+  /** null = inherit parent session model. */
+  model: string | null;
+  /** Resolved child extension allowlist entries. */
+  extensions: string[];
+  /** Materialized child skill dirs (empty when the agent declares no skills). */
+  skillDirs: string[];
+  /** Skill names materialized into skillDirs. */
+  loadedSkills: string[];
+  /** Declared activity template paths (relative to the agent repo root, globs expanded). */
+  activities: string[];
+  /** Advisory repo scope rendered into the system prompt. */
+  scopeRepos: string[];
+  /** Advisory forbidden paths rendered into the system prompt. */
+  scopeForbidden: string[];
+  /** Operator scope note rendered into the system prompt. */
+  scopeNote?: string;
+  /** Removes materialized skill dirs; ASC owns cleanup once dispatched. */
+  cleanup: () => Promise<void>;
+}
+
+export interface AgentRegistry {
+  /** Configured discovery roots (agent-repo patterns or explicit dirs). */
+  roots: string[];
+  ec: EcProfileSource;
+  /** Configured user-level skills root used for `skills.extra` resolution. */
+  userSkillsRoot: string;
+  agents: Map<string, AgentManifest>;
+  list(): AgentListing[];
+  get(name: string): AgentManifest | undefined;
+  resolve(name: string): Promise<ResolvedAgentLaunch>;
+}
+
+/**
+ * Fleet layout: ONE STANDALONE REPO PER AGENT. The canonical fleet home is
+ * the workspace-level `~/ai-society/agents/agent-*` directory (conventions
+ * owner: softwareco-agents/docs/agent-registry.md). Company/lane agent homes
+ * may exist later as forward-compatible extras; PI_AGENT_REGISTRY_ROOTS
+ * overrides discovery entirely. No nesting inside product repos ever —
+ * an agent.json is only read at an agent-repo root.
+ */
+const DEFAULT_AGENT_REPO_PATTERNS: readonly string[] = [
+  "~/ai-society/agents/agent-*",
+  "~/ai-society/core/agent-*",
+  "~/ai-society/holdingco/agent-*",
+  "~/ai-society/teachingco/agent-*",
+  "~/ai-society/healthco/agent-*",
+  "~/ai-society/softwareco/owned/agent-*",
+  "~/ai-society/softwareco/infra/agent-*",
+  "~/ai-society/softwareco/contrib/agent-*",
+  "~/ai-society/softwareco/agents/agent-*",
+  "~/ai-society/softwareco/fork/agent-*",
+];
+
+export function expandTildePath(value: string): string {
+  if (value === "~") return homedir();
+  if (value.startsWith("~/")) return join(homedir(), value.slice(2));
+  return resolve(value);
+}
+
+/** Discovery roots: PI_AGENT_REGISTRY_ROOTS (colon-separated patterns) or the fleet defaults. */
+export function defaultRegistryRoots(): string[] {
+  const raw = process.env[AGENT_REGISTRY_ROOTS_ENV]?.trim();
+  if (raw) {
+    return raw
+      .split(":")
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.length > 0)
+      .map(expandTildePath);
+  }
+  return DEFAULT_AGENT_REPO_PATTERNS.map(expandTildePath);
+}
+
+export async function createAgentRegistry(options?: AgentRegistryOptions): Promise<AgentRegistry> {
+  const roots = options?.roots ?? defaultRegistryRoots();
+  const ec = options?.ec ?? (await loadEcProfiles());
+  const userSkillsRoot = options?.userSkillsRoot ?? defaultUserSkillsRoot();
+
+  const envConfigured =
+    options?.roots !== undefined || Boolean(process.env[AGENT_REGISTRY_ROOTS_ENV]?.trim());
+  const manifestPaths = await discoverAgentManifestPaths(roots, envConfigured).catch((error) => {
+    throw new AgentRegistryError(error instanceof Error ? error.message : String(error));
+  });
+  const agents = new Map<string, AgentManifest>();
+  for (const manifestPath of manifestPaths) {
+    const manifest = await loadAgentManifest(dirname(manifestPath), {
+      ecProfiles: knownEcProfiles(ec),
+    });
+    const existing = agents.get(manifest.name);
+    if (existing) {
+      throw new AgentRegistryError(
+        `duplicate agent name "${manifest.name}" declared by both ${existing.manifestPath} and ${manifest.manifestPath}`,
+      );
+    }
+    agents.set(manifest.name, manifest);
+  }
+
+  return {
+    roots,
+    ec,
+    userSkillsRoot,
+    agents,
+    list() {
+      return [...agents.values()]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map(
+          (manifest): AgentListing => ({
+            name: manifest.name,
+            ...(manifest.display_name ? { display_name: manifest.display_name } : {}),
+            ...(manifest.version ? { version: manifest.version } : {}),
+            ...(manifest.role ? { role: manifest.role } : {}),
+            ...(manifest.creation_task ? { creation_task: manifest.creation_task } : {}),
+            tools: [...manifest.tools],
+            skills: manifest.skills
+              ? {
+                  ...(manifest.skills.profile ? { profile: manifest.skills.profile } : {}),
+                  ...(manifest.skills.extra ? { extra: [...manifest.skills.extra] } : {}),
+                }
+              : {},
+            extensions: resolveAgentExtensions(manifest),
+            defaults: { ...manifest.defaults },
+            activities: [...manifest.activities],
+            manifestPath: manifest.manifestPath,
+          }),
+        );
+    },
+    get(name: string) {
+      return agents.get(name);
+    },
+    async resolve(name: string): Promise<ResolvedAgentLaunch> {
+      const manifest = agents.get(name);
+      if (!manifest) {
+        throw new AgentRegistryError(
+          `unknown agent: ${name} (registered: ${[...agents.keys()].sort().join(", ") || "none"})`,
+        );
+      }
+
+      const [systemPromptContents, expandedActivities] = await Promise.all([
+        readAgentSystemPrompt(manifest),
+        expandAgentActivities(manifest),
+        assertAgentExtensionsExist(manifest),
+      ]);
+
+      let skillDirs: string[] = [];
+      let loadedSkills: string[] = [];
+      let cleanup: () => Promise<void> = async () => {};
+      if (manifest.skills?.profile !== undefined || (manifest.skills?.extra?.length ?? 0) > 0) {
+        const selection = planSkillSelection({
+          ...(manifest.skills?.profile !== undefined ? { profile: manifest.skills.profile } : {}),
+          ...(manifest.skills?.extra ? { extra: manifest.skills.extra } : {}),
+          ec,
+          manifestRoot: manifest.root,
+          userSkillsRoot,
+        });
+        const materialized = await materializeSkillDirs(selection, manifest.name);
+        skillDirs = [materialized.dir];
+        loadedSkills = materialized.skills;
+        cleanup = materialized.cleanup;
+      }
+
+      const scopeSection = renderScopeSection(manifest);
+      const systemPrompt = scopeSection
+        ? `${systemPromptContents.replace(/\s+$/u, "")}\n\n---\n\n${scopeSection}`
+        : systemPromptContents;
+
+      return {
+        name: manifest.name,
+        systemPrompt,
+        ...(manifest.role ? { role: manifest.role } : {}),
+        ...(manifest.creation_task ? { creation_task: manifest.creation_task } : {}),
+        tools: manifest.tools.join(","),
+        thinking: manifest.defaults.thinking,
+        model: manifest.defaults.model,
+        extensions: resolveAgentExtensions(manifest),
+        skillDirs,
+        loadedSkills,
+        activities: expandedActivities,
+        scopeRepos: [...(manifest.scope?.repos ?? [])],
+        scopeForbidden: [...(manifest.scope?.forbidden ?? [])],
+        ...(manifest.scope?.note ? { scopeNote: manifest.scope.note } : {}),
+        cleanup,
+      };
+    },
+  };
+}
+
+/** Render the advisory operating-territory section appended to the system prompt. */
+export function renderScopeSection(manifest: AgentManifest): string {
+  const repos = manifest.scope?.repos ?? [];
+  const forbidden = manifest.scope?.forbidden ?? [];
+  const note = manifest.scope?.note;
+  if (repos.length === 0 && forbidden.length === 0 && !note) {
+    return "";
+  }
+  const lines: string[] = ["## Operating territory (advisory scope)", ""];
+  if (note) {
+    lines.push(note, "");
+  }
+  if (repos.length > 0) {
+    lines.push("Repository scope (advisory, not a sandbox):");
+    for (const repo of repos) {
+      lines.push(`- ${repo}`);
+    }
+  }
+  if (forbidden.length > 0) {
+    if (repos.length > 0) {
+      lines.push("");
+    }
+    lines.push("Forbidden paths:");
+    for (const entry of forbidden) {
+      lines.push(`- ${entry}`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/sessions-dir.ts

@@ -0,0 +1,30 @@
+// ---
+// summary: ASC-owned subagent session-root resolution for Fleet Phase-2 standing-agent dispatch.
+// read_when:
+//   - changing where dispatched standing-agent children record ASC sessions.
+// ---
+
+import { loadAscExecutionSurface } from "./asc-execution-surface.ts";
+
+export class RegistrySessionsDirError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RegistrySessionsDirError";
+  }
+}
+
+/**
+ * Fleet Phase 0 quarantined registry-owned session-root resolution; AK 5132
+ * (Fleet Phase 2) lifts the quarantine by delegating to ASC's exported
+ * contract when the installed ASC provides it. The registry never invents a
+ * session root and never re-implements pi-native session directory semantics.
+ */
+export async function resolveRegistrySubagentSessionsDir(cwd: string): Promise<string> {
+  const surface = await loadAscExecutionSurface();
+  if (!surface) {
+    throw new RegistrySessionsDirError(
+      "ASC execution surface is unavailable; subagent session-root resolution stays ASC-owned and fails closed",
+    );
+  }
+  return surface.resolveSubagentSessionsDir({ cwd }).path;
+}