@tryinget/pi-agent-registry 0.3.0

package/src/fleet-lint-utils.ts

@@ -0,0 +1,66 @@
+// ---
+// summary: deterministic digest, diagnostic, and logical-identity helpers shared by fleet lint modules.
+// read_when:
+//   - changing fleet report hashing, diagnostic ordering, or logical repository identity.
+// ---
+
+import { createHash } from "node:crypto";
+import { basename, dirname } from "node:path";
+import type { FleetLintDiagnostic } from "./fleet-lint-types.ts";
+
+export function fleetSha256(value: string | Buffer): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function stableFleetValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stableFleetValue);
+  if (typeof value !== "object" || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+      .map(([key, entry]) => [key, stableFleetValue(entry)]),
+  );
+}
+
+export function addFleetDiagnostic(
+  target: FleetLintDiagnostic[],
+  repo: string,
+  code: string,
+  severity: FleetLintDiagnostic["severity"],
+  message: string,
+  path?: string,
+  hint?: string,
+): void {
+  target.push({
+    code,
+    severity,
+    repo,
+    ...(path ? { path } : {}),
+    message,
+    ...(hint ? { hint } : {}),
+  });
+}
+
+export function sortFleetDiagnostics(values: FleetLintDiagnostic[]): FleetLintDiagnostic[] {
+  const compare = (left: string, right: string) => (left < right ? -1 : left > right ? 1 : 0);
+  return values.sort((a, b) =>
+    compare(
+      [a.repo, a.code, a.path ?? "", a.message].join("\0"),
+      [b.repo, b.code, b.path ?? "", b.message].join("\0"),
+    ),
+  );
+}
+
+function logicalFleetPath(root: string): string {
+  const parent = basename(dirname(root)) || "root";
+  const leaf = basename(root) || "unknown";
+  return `${parent}/${leaf}`;
+}
+
+export function logicalFleetRepo(root: string): string {
+  return logicalFleetPath(root);
+}
+
+export function logicalFleetRoot(root: string): string {
+  return logicalFleetPath(root);
+}

package/src/fleet-lint.ts

@@ -0,0 +1,375 @@
+// ---
+// summary: aggregate, immutable-observation fleet lint orchestration and deterministic report digest.
+// read_when:
+//   - changing agent_registry lint, fleet aggregation, profile baselines, collisions, or report identity.
+// ---
+
+import { basename, dirname, relative } from "node:path";
+import { EC_PROFILE_SCHEMA, type EcProfileSource, loadEcProfiles } from "./ec-profiles.ts";
+import { captureFleetGitSnapshot, type FleetGitSnapshot } from "./fleet-git-snapshot.ts";
+import { normalizeFleetRole } from "./fleet-lint-provenance.ts";
+import { invalidFleetRepositoryResult, lintFleetRepository } from "./fleet-lint-repository.ts";
+import {
+  AGENT_FLEET_LINT_SCHEMA,
+  type AgentFleetLintReport,
+  type FleetLintCollision,
+  type FleetLintDiagnostic,
+  type FleetLintRepositoryResult,
+} from "./fleet-lint-types.ts";
+import {
+  addFleetDiagnostic,
+  fleetSha256,
+  logicalFleetRoot,
+  sortFleetDiagnostics,
+  stableFleetValue,
+} from "./fleet-lint-utils.ts";
+import { AGENT_REGISTRY_ROOTS_ENV, defaultRegistryRoots, expandTildePath } from "./registry.ts";
+import { discoverAgentRepositories, RegistryDiscoveryError } from "./registry-discovery.ts";
+
+const DEFAULT_STALE_AFTER_DAYS = 90;
+const DEFAULT_MAX_REPOSITORIES = 5_000;
+const RFC3339_TIMESTAMP =
+  /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](\d{2}):(\d{2}))$/u;
+
+export interface FleetLintOptions {
+  roots?: string[];
+  ec?: EcProfileSource;
+  observedAt?: string;
+  staleAfterDays?: number;
+  maxRepositories?: number;
+}
+
+export class FleetLintInfrastructureError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "FleetLintInfrastructureError";
+    this.code = code;
+  }
+}
+
+export function defaultFleetLintRoots(): string[] {
+  return process.env[AGENT_REGISTRY_ROOTS_ENV]?.trim()
+    ? defaultRegistryRoots()
+    : [expandTildePath("~/ai-society/agents/agent-*")];
+}
+
+function digestValue(value: unknown): string {
+  return fleetSha256(JSON.stringify(stableFleetValue(value)));
+}
+
+function canonicalObservedAt(value: string): { text: string; date: Date } {
+  const match = RFC3339_TIMESTAMP.exec(value);
+  if (!match) {
+    throw new FleetLintInfrastructureError(
+      "fleet.options_invalid",
+      "observedAt must be one RFC3339 timestamp",
+    );
+  }
+  const [, yearText, monthText, dayText, hourText, minuteText, secondText, zoneHour, zoneMinute] =
+    match;
+  const year = Number(yearText);
+  const month = Number(monthText);
+  const day = Number(dayText);
+  const hour = Number(hourText);
+  const minute = Number(minuteText);
+  const second = Number(secondText);
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const daysInMonth = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  const validFields =
+    month >= 1 &&
+    month <= 12 &&
+    day >= 1 &&
+    day <= (daysInMonth[month - 1] ?? 0) &&
+    hour <= 23 &&
+    minute <= 59 &&
+    second <= 59 &&
+    (zoneHour === undefined || Number(zoneHour) <= 23) &&
+    (zoneMinute === undefined || Number(zoneMinute) <= 59);
+  const date = new Date(value);
+  if (!validFields || !Number.isFinite(date.getTime())) {
+    throw new FleetLintInfrastructureError(
+      "fleet.options_invalid",
+      "observedAt must be one valid RFC3339 timestamp",
+    );
+  }
+  return { text: date.toISOString(), date };
+}
+
+function logicalProfileSourcePath(ec: EcProfileSource): string {
+  const repository = basename(dirname(ec.skillsRoot)) || "root";
+  const filename = basename(ec.path) || "profiles.json";
+  return `${repository}/skills/${filename}`;
+}
+
+async function captureProfileSource(ec: EcProfileSource, diagnostics: FleetLintDiagnostic[]) {
+  const repo = "engineering-core/skills-profiles";
+  try {
+    const snapshot = await captureFleetGitSnapshot(dirname(ec.skillsRoot));
+    const profilePath = relative(snapshot.root, ec.path).split("\\").join("/");
+    const file = await snapshot.readFile(profilePath, 2 * 1024 * 1024);
+    if (!file) throw new Error(`committed profile source is missing: ${profilePath}`);
+    const status =
+      snapshot.status === "clean_observed" && file.sha256 === ec.rawSha256 ? "bound" : "dirty";
+    if (status !== "bound") {
+      addFleetDiagnostic(
+        diagnostics,
+        repo,
+        status === "dirty" ? "profile.source_dirty" : "profile.source_unstable",
+        "error",
+        "engineering-core profile bytes are not one clean stable committed observation",
+        profilePath,
+      );
+    }
+    return {
+      snapshot,
+      profile: {
+        path: logicalProfileSourcePath(ec),
+        schema: ec.schema,
+        rawSha256: ec.rawSha256,
+        commit: snapshot.commit,
+        blobOid: file.blobOid,
+        committedSha256: file.sha256,
+        status,
+      } satisfies AgentFleetLintReport["profileSource"],
+    };
+  } catch {
+    addFleetDiagnostic(
+      diagnostics,
+      repo,
+      "profile.source_invalid",
+      "error",
+      "engineering-core profile bytes could not be bound to one committed Git snapshot",
+      logicalProfileSourcePath(ec),
+    );
+    return {
+      snapshot: undefined as FleetGitSnapshot | undefined,
+      profile: {
+        path: logicalProfileSourcePath(ec),
+        schema: ec.schema,
+        rawSha256: ec.rawSha256,
+        status: "invalid",
+      } satisfies AgentFleetLintReport["profileSource"],
+    };
+  }
+}
+
+function addCollisions(repositories: FleetLintRepositoryResult[]): FleetLintCollision[] {
+  const collisions: FleetLintCollision[] = [];
+  for (const [kind, values] of [
+    ["name", repositories.map((entry) => [entry.manifest.name, entry] as const)],
+    ["role", repositories.map((entry) => [entry.manifest.role, entry] as const)],
+  ] as const) {
+    const index = new Map<string, FleetLintRepositoryResult[]>();
+    for (const [value, repository] of values) {
+      if (!value) continue;
+      const normalized = kind === "role" ? normalizeFleetRole(value) : value;
+      index.set(normalized, [...(index.get(normalized) ?? []), repository]);
+    }
+    for (const [normalizedValue, matches] of index) {
+      if (matches.length < 2) continue;
+      const repos = matches.map((entry) => entry.repo).sort();
+      collisions.push({ kind, normalizedValue, repositories: repos });
+      for (const entry of matches) {
+        addFleetDiagnostic(
+          entry.diagnostics,
+          entry.repo,
+          `${kind}.exact_collision`,
+          "error",
+          `${kind} collides exactly after normalization across: ${repos.join(", ")}`,
+          "agent.json",
+          "semantic differentiation remains an owner review; lint proves only this exact collision",
+        );
+        sortFleetDiagnostics(entry.diagnostics);
+      }
+    }
+  }
+  return collisions.sort((a, b) => {
+    const left = `${a.kind}\0${a.normalizedValue}`;
+    const right = `${b.kind}\0${b.normalizedValue}`;
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+}
+
+export async function lintAgentFleet(
+  options: FleetLintOptions = {},
+): Promise<AgentFleetLintReport> {
+  const observation = canonicalObservedAt(options.observedAt ?? new Date().toISOString());
+  const observedAt = observation.text;
+  const observedDate = observation.date;
+  const staleAfterDays = options.staleAfterDays ?? DEFAULT_STALE_AFTER_DAYS;
+  if (!Number.isSafeInteger(staleAfterDays) || staleAfterDays <= 0) {
+    throw new FleetLintInfrastructureError(
+      "fleet.options_invalid",
+      "staleAfterDays must be a positive safe integer",
+    );
+  }
+  const roots = options.roots ?? defaultFleetLintRoots();
+  let ec: EcProfileSource;
+  try {
+    ec = options.ec ?? (await loadEcProfiles());
+  } catch {
+    throw new FleetLintInfrastructureError(
+      "profile.source_load_failed",
+      "engineering-core skill profile source could not be loaded",
+    );
+  }
+  const diagnostics: FleetLintDiagnostic[] = [];
+  if (ec.schema !== EC_PROFILE_SCHEMA) {
+    addFleetDiagnostic(
+      diagnostics,
+      "engineering-core/skills-profiles",
+      "profile.legacy_schema",
+      "error",
+      `fleet lint requires ${EC_PROFILE_SCHEMA}; legacy compatibility is runtime-only`,
+      logicalProfileSourcePath(ec),
+    );
+  }
+  const profileSource = await captureProfileSource(ec, diagnostics);
+  let discovered: Awaited<ReturnType<typeof discoverAgentRepositories>>;
+  try {
+    discovered = await discoverAgentRepositories(
+      roots,
+      true,
+      options.maxRepositories ?? DEFAULT_MAX_REPOSITORIES,
+    );
+  } catch (error) {
+    if (error instanceof RegistryDiscoveryError) {
+      throw new FleetLintInfrastructureError(error.code, error.message);
+    }
+    throw new FleetLintInfrastructureError(
+      "fleet.discovery_failed",
+      "fleet repository discovery failed unexpectedly",
+    );
+  }
+  if (discovered.omittedCount > 0) {
+    addFleetDiagnostic(
+      diagnostics,
+      "fleet",
+      "fleet.repository_limit_exceeded",
+      "error",
+      `${discovered.omittedCount} candidate repositories were omitted by the bound`,
+    );
+  }
+
+  const repositories: FleetLintRepositoryResult[] = [];
+  for (const failure of discovered.failures) {
+    const repo = logicalFleetRoot(failure.root);
+    const repositoryDiagnostics: FleetLintDiagnostic[] = [];
+    addFleetDiagnostic(
+      repositoryDiagnostics,
+      repo,
+      failure.code,
+      "error",
+      "candidate repository could not be resolved after bounded discovery",
+      undefined,
+      "later fleet candidates were still inspected",
+    );
+    repositories.push(invalidFleetRepositoryResult(failure.root, false, repositoryDiagnostics));
+  }
+  for (const candidate of discovered.repositories) {
+    try {
+      repositories.push(
+        await lintFleetRepository({
+          root: candidate.root,
+          manifestPresent: candidate.manifestPresent,
+          ec,
+          ecSnapshot: profileSource.snapshot,
+          observedAt: observedDate,
+          staleAfterDays,
+        }),
+      );
+    } catch {
+      const repositoryDiagnostics: FleetLintDiagnostic[] = [];
+      const repo = logicalFleetRoot(candidate.root);
+      addFleetDiagnostic(
+        repositoryDiagnostics,
+        repo,
+        "repository.lint_failed",
+        "error",
+        "repository lint failed unexpectedly inside its aggregate isolation boundary",
+        undefined,
+        "one repository failed bounded capture; later fleet candidates were still inspected",
+      );
+      repositories.push(
+        invalidFleetRepositoryResult(
+          candidate.root,
+          candidate.manifestPresent,
+          repositoryDiagnostics,
+        ),
+      );
+    }
+  }
+  if (profileSource.snapshot) {
+    try {
+      const finalProfileState = await profileSource.snapshot.finish();
+      if (!finalProfileState.stable) {
+        profileSource.profile.status = "invalid";
+        addFleetDiagnostic(
+          diagnostics,
+          "engineering-core/skills-profiles",
+          "profile.source_concurrent_change",
+          "error",
+          "engineering-core profile HEAD or worktree status changed during fleet capture",
+          logicalProfileSourcePath(ec),
+        );
+      }
+    } catch {
+      profileSource.profile.status = "invalid";
+      addFleetDiagnostic(
+        diagnostics,
+        "engineering-core/skills-profiles",
+        "profile.source_finalize_failed",
+        "error",
+        "engineering-core profile endpoint stability could not be verified after fleet capture",
+        logicalProfileSourcePath(ec),
+      );
+    }
+  }
+  repositories.sort((a, b) => (a.repo < b.repo ? -1 : a.repo > b.repo ? 1 : 0));
+  const collisions = addCollisions(repositories);
+  const allDiagnostics = sortFleetDiagnostics([
+    ...diagnostics,
+    ...repositories.flatMap((entry) => entry.diagnostics),
+  ]);
+  const count = (severity: FleetLintDiagnostic["severity"]) =>
+    allDiagnostics.filter((entry) => entry.severity === severity).length;
+  const state: Omit<AgentFleetLintReport, "reportSha256" | "stateSha256" | "observedAt"> = {
+    schema: AGENT_FLEET_LINT_SCHEMA,
+    kind: "immutable_observation",
+    authorityEffect: "none",
+    roots: roots.map(logicalFleetRoot),
+    profileSource: profileSource.profile,
+    policy: {
+      staleAfterDays,
+      lifecycleAuthority: "advisory_signal_only",
+      dispatchPosture: "fleet_phase_0_disabled",
+    },
+    repositories,
+    collisions,
+    diagnostics: allDiagnostics,
+    summary: {
+      status: count("error") > 0 ? "unhealthy" : "healthy",
+      candidateRepositories:
+        discovered.repositories.length + discovered.failures.length + discovered.omittedCount,
+      includedRepositories: repositories.length,
+      omittedRepositories: discovered.omittedCount,
+      manifests: repositories.filter((entry) => entry.manifest.present).length,
+      errors: count("error"),
+      warnings: count("warning"),
+      infos: count("info"),
+      recentActivitySignals: repositories.filter(
+        (entry) => entry.lifecycle.signal === "recent_activity",
+      ).length,
+      staleCandidateSignals: repositories.filter(
+        (entry) => entry.lifecycle.signal === "stale_candidate",
+      ).length,
+      unknownLifecycleSignals: repositories.filter((entry) => entry.lifecycle.signal === "unknown")
+        .length,
+    },
+  };
+  const stateSha256 = digestValue(state);
+  const complete = { ...state, observedAt, stateSha256 };
+  return { ...complete, reportSha256: digestValue(complete) };
+}

package/src/fleet-prompt-compiler.ts

@@ -0,0 +1,155 @@
+// ---
+// summary: trusted byte-for-byte reconstruction of the ratified tpl-agent-repo v2 system-prompt compiler contract.
+// read_when:
+//   - changing fleet prompt freshness, canonical persona inputs, or compiler provenance.
+// ---
+
+import { createHash } from "node:crypto";
+
+export const FLEET_PERSONA_FILES = [
+  "README.md",
+  "identity.md",
+  "reason.md",
+  "main_task.md",
+  "dream_goal.md",
+  "behavior_rules.md",
+] as const;
+export const FLEET_PERSONA_DIR = "docs/person";
+export const FLEET_COMPILED_PROMPT_PATH = "docs/person/system-prompt.md";
+export const FLEET_PROMPT_COMPILER_CONTRACT = "ai-society.agent-prompt-compiler/1";
+
+export interface FleetPromptCompileResult {
+  expected: Buffer;
+  expectedSha256: string;
+  inputSha256: string;
+  inputPaths: string[];
+}
+
+export class FleetPromptCompilerError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "FleetPromptCompilerError";
+  }
+}
+
+function sha256(value: string | Buffer): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function decodeUtf8(bytes: Buffer, path: string): string {
+  try {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    throw new FleetPromptCompilerError(`canonical prompt input is not UTF-8: ${path}`);
+  }
+}
+
+function compareCodePoints(left: string, right: string): number {
+  const leftPoints = [...left].map((value) => value.codePointAt(0) ?? -1);
+  const rightPoints = [...right].map((value) => value.codePointAt(0) ?? -1);
+  for (let index = 0; index < Math.min(leftPoints.length, rightPoints.length); index += 1) {
+    if (leftPoints[index] !== rightPoints[index]) return leftPoints[index] - rightPoints[index];
+  }
+  return leftPoints.length - rightPoints.length;
+}
+
+function hasUnpairedSurrogate(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) return true;
+      index += 1;
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function assertPortableJson(value: unknown, path = "$manifest"): void {
+  if (typeof value === "string" && hasUnpairedSurrogate(value)) {
+    throw new FleetPromptCompilerError(
+      `unpaired surrogate cannot be encoded by the Python compiler: ${path}`,
+    );
+  }
+  if (typeof value === "number") {
+    throw new FleetPromptCompilerError(
+      `numeric additive manifest value cannot be proven byte-identical to the Python compiler: ${path}`,
+    );
+  }
+  if (Array.isArray(value)) {
+    for (const [index, entry] of value.entries()) {
+      assertPortableJson(entry, `${path}[${index}]`);
+    }
+  } else if (typeof value === "object" && value !== null) {
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      if (hasUnpairedSurrogate(key)) {
+        throw new FleetPromptCompilerError(
+          `unpaired surrogate cannot be encoded by the Python compiler: ${path} key`,
+        );
+      }
+      assertPortableJson(entry, `${path}.${key}`);
+    }
+  }
+}
+
+function sortJson(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortJson);
+  if (typeof value !== "object" || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => compareCodePoints(left, right))
+      .map(([key, entry]) => [key, sortJson(entry)]),
+  );
+}
+
+function canonicalInputDigest(entries: Array<{ path: string; sha256: string }>): string {
+  return sha256(JSON.stringify(entries.sort((a, b) => compareCodePoints(a.path, b.path))));
+}
+
+export async function compileFleetSystemPrompt(params: {
+  manifestBytes: Buffer;
+  readFile(path: string): Promise<Buffer | undefined>;
+}): Promise<FleetPromptCompileResult> {
+  const manifestText = decodeUtf8(params.manifestBytes, "agent.json");
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(manifestText);
+  } catch (error) {
+    throw new FleetPromptCompilerError(
+      `agent.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+    throw new FleetPromptCompilerError("agent.json root must be an object");
+  }
+  assertPortableJson(manifest);
+
+  const parts: string[] = [
+    "<!-- compiled: do not edit -->\n",
+    "# Agent system prompt\n\n",
+    "## Manifest\n\n",
+    "```json\n",
+    JSON.stringify(sortJson(manifest), null, 2),
+    "\n```\n",
+  ];
+  const inputs = [{ path: "agent.json", sha256: sha256(params.manifestBytes) }];
+  const inputPaths = ["agent.json"];
+  for (const name of FLEET_PERSONA_FILES) {
+    const path = `${FLEET_PERSONA_DIR}/${name}`;
+    const bytes = await params.readFile(path);
+    if (!bytes) throw new FleetPromptCompilerError(`missing canonical prompt input: ${path}`);
+    const text = decodeUtf8(bytes, path).replace(/\r\n?/gu, "\n").replace(/\n+$/u, "");
+    parts.push(`\n## Persona source: ${name}\n\n`, text, "\n");
+    inputs.push({ path, sha256: sha256(bytes) });
+    inputPaths.push(path);
+  }
+  const expected = Buffer.from(parts.join(""), "utf8");
+  return {
+    expected,
+    expectedSha256: sha256(expected),
+    inputSha256: canonicalInputDigest(inputs),
+    inputPaths,
+  };
+}