@evo-dev/core 0.0.1-alpha

package/src/agents/index.ts

@@ -0,0 +1,561 @@
+import { readFile } from "node:fs/promises";
+import type { TaskContract, TaskExecutionMode } from "../task/index.ts";
+
+export type AgentPersistence = "named" | "dynamic";
+export type AgentLens =
+  | "review"
+  | "qa"
+  | "security"
+  | "release"
+  | "architecture"
+  | "migration"
+  | "test";
+export type AgentOutputSchemaId =
+  | "review-findings-v1"
+  | "verification-summary-v1"
+  | "design-options-v1";
+export type AgentFindingSeverity = "blocker" | "high" | "medium" | "low" | "info";
+
+export interface AgentPermissions {
+  canReadMetadata: boolean;
+  canReadSourceContent: boolean;
+  canWriteFiles: boolean;
+  canRunCommands: boolean;
+  canUseNetwork: boolean;
+  canSpawnAgents: boolean;
+  canWriteMemory: boolean;
+}
+
+export interface AgentProfile {
+  version: 1;
+  id: string;
+  name: string;
+  persistence: AgentPersistence;
+  description: string;
+  traits: {
+    expertise: string[];
+    stance: string[];
+    approach: string[];
+    domain: string[];
+  };
+  inputs: {
+    required: string[];
+    optional: string[];
+    forbidden: string[];
+  };
+  permissions: AgentPermissions;
+  output: {
+    schema: AgentOutputSchemaId;
+    requiredFields: string[];
+  };
+  privacy: {
+    classification: "local-private";
+    metadataOnly: true;
+    rawPromptStored: false;
+    sourceContentStored: false;
+  };
+}
+
+export interface AgentPlannedInvocation {
+  profile: AgentProfile;
+  lens: AgentLens;
+  reason: string;
+  plannedOnly: true;
+}
+
+export interface AgentMergePlan {
+  strategy: "none" | "single-output" | "dedupe-preserve-conflicts-fail-closed";
+  outputSchema: AgentOutputSchemaId | null;
+  dedupeBy: string[];
+  conflictPolicy: string[];
+  failClosedCategories: string[];
+}
+
+export interface AgentComposeDryRunPlan {
+  ok: boolean;
+  taskId: string;
+  mode: TaskExecutionMode | null;
+  workflowId: string | null;
+  agents: AgentPlannedInvocation[];
+  permissions: AgentPermissions;
+  mergePlan: AgentMergePlan;
+  warnings: string[];
+  blockers: string[];
+  rationale: string;
+}
+
+export interface AgentContextDryRunBundle {
+  profile: AgentProfile;
+  context: {
+    metadataOnly: true;
+    allowedSections: string[];
+    forbiddenSections: string[];
+    provenance: string[];
+  };
+  warnings: string[];
+  blockers: string[];
+}
+
+export interface ReviewFindingOutput {
+  summary: string;
+  findings: Array<{
+    severity: AgentFindingSeverity;
+    category: string;
+    path?: string;
+    line?: number;
+    title: string;
+    rationale: string;
+    recommendation: string;
+    evidenceRefs: string[];
+    confidence: "low" | "medium" | "high";
+  }>;
+  confidence: "low" | "medium" | "high";
+  evidenceRefs: string[];
+}
+
+const DEFAULT_AGENT_PERMISSIONS: AgentPermissions = {
+  canReadMetadata: true,
+  canReadSourceContent: false,
+  canWriteFiles: false,
+  canRunCommands: false,
+  canUseNetwork: false,
+  canSpawnAgents: false,
+  canWriteMemory: false,
+};
+const FORBIDDEN_INPUTS = ["rawPrompts", "secrets", "rawCommandLogs", "sourceCorpus"];
+const SAFE_AGENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const PRIVACY_BLOCKER_PATTERN =
+  /raw prompt|rawprompt|source corpus|sourcecorpus|secret|\.env|raw command|raw log|internal url|private url|network|write files|run commands|spawn agents|write memory/i;
+const LENS_TO_EXPERTISE: Record<AgentLens, string[]> = {
+  review: ["code-review"],
+  qa: ["qa", "verification"],
+  security: ["security", "privacy"],
+  release: ["release", "packaging"],
+  architecture: ["architecture"],
+  migration: ["migration", "impact-analysis"],
+  test: ["testing"],
+};
+
+export function createDefaultAgentPermissions(): AgentPermissions {
+  return { ...DEFAULT_AGENT_PERMISSIONS };
+}
+
+export function applyStrictestAgentPermissions(
+  ...permissions: Array<Partial<AgentPermissions> | undefined>
+): AgentPermissions {
+  const merged = createDefaultAgentPermissions();
+  for (const candidate of permissions) {
+    if (candidate === undefined) continue;
+    for (const key of Object.keys(merged) as Array<keyof AgentPermissions>) {
+      merged[key] = merged[key] && candidate[key] === true;
+    }
+  }
+  return merged;
+}
+
+export function parseAgentProfile(value: unknown): AgentProfile {
+  if (!isRecord(value)) throw new Error("Agent profile must be an object.");
+  if (value.version !== 1) throw new Error("Agent profile version must be 1.");
+  const profile = value as unknown as AgentProfile;
+  assertString(profile.id, "profile.id");
+  assertString(profile.name, "profile.name");
+  if (profile.persistence !== "named" && profile.persistence !== "dynamic") {
+    throw new Error("Agent profile persistence must be named or dynamic.");
+  }
+  if (
+    profile.privacy?.metadataOnly !== true ||
+    profile.privacy.rawPromptStored !== false ||
+    profile.privacy.sourceContentStored !== false
+  ) {
+    throw new Error("Agent profile must be metadata-only and must not store raw prompts/source.");
+  }
+  const permissions = normalizeAgentPermissions(profile.permissions);
+  if (
+    permissions.canWriteFiles ||
+    permissions.canRunCommands ||
+    permissions.canUseNetwork ||
+    permissions.canSpawnAgents ||
+    permissions.canWriteMemory ||
+    permissions.canReadSourceContent
+  ) {
+    throw new Error("Agent profile requests permissions outside I8 dry-run boundaries.");
+  }
+  if (!SAFE_AGENT_ID_PATTERN.test(profile.id)) throw new Error("Agent profile id is unsafe.");
+  assertStringArray(profile.traits?.expertise, "profile.traits.expertise");
+  assertStringArray(profile.traits?.stance, "profile.traits.stance");
+  assertStringArray(profile.traits?.approach, "profile.traits.approach");
+  assertStringArray(profile.traits?.domain, "profile.traits.domain");
+  assertStringArray(profile.inputs?.required, "profile.inputs.required");
+  assertStringArray(profile.inputs?.optional, "profile.inputs.optional");
+  assertStringArray(profile.inputs?.forbidden, "profile.inputs.forbidden");
+  if (!FORBIDDEN_INPUTS.every((item) => profile.inputs.forbidden.includes(item))) {
+    throw new Error(
+      "Agent profile must forbid raw prompts, secrets, raw command logs, and source corpus.",
+    );
+  }
+  if (!isKnownOutputSchema(profile.output?.schema))
+    throw new Error("Agent profile output schema is unsupported.");
+  assertStringArray(profile.output.requiredFields, "profile.output.requiredFields");
+  return { ...profile, permissions };
+}
+
+export async function readAgentProfile(path: string): Promise<AgentProfile> {
+  return parseAgentProfile(JSON.parse(await readFile(path, "utf8")));
+}
+
+export function composeAgentDryRun(input: {
+  contract: TaskContract;
+  workflowId?: string;
+  lenses?: AgentLens[];
+}): AgentComposeDryRunPlan {
+  const mode = input.contract.route.mode;
+  const workflowId = input.workflowId ?? input.contract.route.workflowId;
+  const warnings: string[] = [];
+  const blockers: string[] = [];
+  const permissions = createDefaultAgentPermissions();
+  const requestedLenses = dedupeLenses(input.lenses ?? []);
+  const privacyBlockers = collectPrivacyBoundaryBlockers(
+    input.contract,
+    requestedLenses,
+    workflowId,
+  );
+  blockers.push(...privacyBlockers);
+
+  if (mode === "minimal") {
+    return {
+      ok: blockers.length === 0,
+      taskId: input.contract.taskId,
+      mode,
+      workflowId,
+      agents: [],
+      permissions,
+      mergePlan: createMergePlan([]),
+      warnings,
+      blockers,
+      rationale: "Minimal mode does not force dynamic agents by default.",
+    };
+  }
+
+  const selectedLenses = selectLenses(
+    mode,
+    requestedLenses,
+    workflowId,
+    input.contract.route.requiredReview,
+  );
+  const agents = selectedLenses.map((lens) => ({
+    profile: createDynamicProfile(lens, input.contract, permissions),
+    lens,
+    reason: createLensReason(lens, mode, workflowId),
+    plannedOnly: true as const,
+  }));
+
+  if (mode === "standard" && agents.length > 1) {
+    blockers.push("Standard mode allows at most one optional reviewer/triager in I8 dry-run.");
+  }
+
+  return {
+    ok: blockers.length === 0,
+    taskId: input.contract.taskId,
+    mode,
+    workflowId,
+    agents,
+    permissions,
+    mergePlan: createMergePlan(agents),
+    warnings,
+    blockers,
+    rationale:
+      agents.length === 0
+        ? "No dynamic agents selected; deterministic verification may be sufficient."
+        : `Selected ${agents.length} planned-only agent(s) based on mode/workflow/lenses.`,
+  };
+}
+
+export function loadAgentContextDryRun(profile: AgentProfile): AgentContextDryRunBundle {
+  const parsed = parseAgentProfile(profile);
+  return {
+    profile: parsed,
+    context: {
+      metadataOnly: true,
+      allowedSections: [
+        "role",
+        "inputs",
+        "permissions",
+        "output-schema",
+        "privacy",
+        "failure-behavior",
+      ],
+      forbiddenSections: [...FORBIDDEN_INPUTS, "rawSource", "rawEvidence", "memoryBodies"],
+      provenance: [`agent-profile:${parsed.id}`],
+    },
+    warnings: [],
+    blockers: [],
+  };
+}
+
+export function validateAgentOutput(
+  schema: AgentOutputSchemaId,
+  output: unknown,
+): { ok: boolean; errors: string[] } {
+  if (schema === "verification-summary-v1")
+    return validateRequiredObject(output, ["summary", "status", "evidenceRefs"]);
+  if (schema === "design-options-v1")
+    return validateRequiredObject(output, ["summary", "options", "recommendation", "evidenceRefs"]);
+  const errors: string[] = [];
+  if (!isRecord(output)) return { ok: false, errors: ["Output must be an object."] };
+  if (typeof output.summary !== "string") errors.push("summary is required.");
+  if (!Array.isArray(output.findings)) errors.push("findings array is required.");
+  if (
+    output.confidence !== "low" &&
+    output.confidence !== "medium" &&
+    output.confidence !== "high"
+  ) {
+    errors.push("confidence must be low/medium/high.");
+  }
+  if (!Array.isArray(output.evidenceRefs)) errors.push("evidenceRefs array is required.");
+  return { ok: errors.length === 0, errors };
+}
+
+export function mergeReviewFindings(outputs: ReviewFindingOutput[]): {
+  acceptedFindings: ReviewFindingOutput["findings"];
+  unresolvedConflicts: string[];
+} {
+  const byKey = new Map<string, ReviewFindingOutput["findings"][number]>();
+  const conflicts: string[] = [];
+  for (const output of outputs) {
+    for (const finding of output.findings) {
+      const key = `${finding.category}:${finding.path ?? ""}:${finding.line ?? ""}:${finding.title}`;
+      const existing = byKey.get(key);
+      if (existing === undefined) {
+        byKey.set(key, finding);
+        continue;
+      }
+      if (severityRank(finding.severity) > severityRank(existing.severity)) byKey.set(key, finding);
+      if (
+        finding.severity !== existing.severity ||
+        finding.recommendation !== existing.recommendation
+      ) {
+        conflicts.push(key);
+      }
+    }
+  }
+  return { acceptedFindings: [...byKey.values()], unresolvedConflicts: conflicts };
+}
+
+export function formatAgentComposeDryRun(plan: AgentComposeDryRunPlan): string {
+  return [
+    "EvoDev agent compose dry-run",
+    "",
+    `Task: ${plan.taskId}`,
+    `Mode: ${plan.mode ?? "not routed"}`,
+    `Workflow: ${plan.workflowId ?? "none"}`,
+    `Rationale: ${plan.rationale}`,
+    "No-write/no-spawn: true",
+    "Privacy: local-private, metadata-only, raw prompts/source/secrets/logs forbidden",
+    "Agents:",
+    ...(plan.agents.length === 0
+      ? ["  - none"]
+      : plan.agents.map(
+          (agent) =>
+            `  - ${agent.profile.id} [${agent.lens}] traits=${agent.profile.traits.expertise.join(",")} schema=${agent.profile.output.schema} plannedOnly=${agent.plannedOnly}`,
+        )),
+    "Inputs:",
+    ...(plan.agents.length === 0
+      ? ["  - none"]
+      : [
+          `  - required: ${plan.agents[0].profile.inputs.required.join(",")}`,
+          `  - optional: ${plan.agents[0].profile.inputs.optional.join(",")}`,
+          `  - forbidden: ${plan.agents[0].profile.inputs.forbidden.join(",")}`,
+        ]),
+    "Permissions:",
+    ...Object.entries(plan.permissions).map(([key, value]) => `  - ${key}: ${value}`),
+    "Merge plan:",
+    `  - strategy: ${plan.mergePlan.strategy}`,
+    `  - outputSchema: ${plan.mergePlan.outputSchema ?? "none"}`,
+    "Warnings:",
+    ...(plan.warnings.length === 0
+      ? ["  - none"]
+      : plan.warnings.map((warning) => `  - ${warning}`)),
+    "Blockers:",
+    ...(plan.blockers.length === 0
+      ? ["  - none"]
+      : plan.blockers.map((blocker) => `  - ${blocker}`)),
+  ].join("\n");
+}
+
+export function formatAgentContextDryRun(bundle: AgentContextDryRunBundle): string {
+  return [
+    "EvoDev agent load-context dry-run",
+    "",
+    `Agent: ${bundle.profile.id}`,
+    `Persistence: ${bundle.profile.persistence}`,
+    "Allowed sections:",
+    ...bundle.context.allowedSections.map((section) => `  - ${section}`),
+    "Forbidden sections:",
+    ...bundle.context.forbiddenSections.map((section) => `  - ${section}`),
+    "Permissions:",
+    ...Object.entries(bundle.profile.permissions).map(([key, value]) => `  - ${key}: ${value}`),
+    "Blockers:",
+    ...(bundle.blockers.length === 0
+      ? ["  - none"]
+      : bundle.blockers.map((blocker) => `  - ${blocker}`)),
+  ].join("\n");
+}
+
+function createDynamicProfile(
+  lens: AgentLens,
+  contract: TaskContract,
+  permissions: AgentPermissions,
+): AgentProfile {
+  return {
+    version: 1,
+    id: `dynamic-${lens}-${contract.taskId}`.slice(0, 100),
+    name: `Dynamic ${lens} reviewer`,
+    persistence: "dynamic",
+    description: `Task-scoped ${lens} profile for metadata-only dry-run planning.`,
+    traits: {
+      expertise: LENS_TO_EXPERTISE[lens],
+      stance: ["skeptical-reviewer"],
+      approach: ["evidence-first", "fail-closed"],
+      domain: ["software-rd"],
+    },
+    inputs: {
+      required: ["taskContract", "scope", "evidenceSummary"],
+      optional: ["workflowPlan"],
+      forbidden: FORBIDDEN_INPUTS,
+    },
+    permissions,
+    output: {
+      schema: "review-findings-v1",
+      requiredFields: ["summary", "findings", "confidence", "evidenceRefs"],
+    },
+    privacy: {
+      classification: "local-private",
+      metadataOnly: true,
+      rawPromptStored: false,
+      sourceContentStored: false,
+    },
+  };
+}
+
+function selectLenses(
+  mode: TaskExecutionMode | null,
+  requested: AgentLens[],
+  workflowId: string | null,
+  requiredReview: string[],
+): AgentLens[] {
+  if (requested.length > 0) return mode === "standard" ? requested.slice(0, 1) : requested;
+  if (mode === "standard") return requiredReview.length > 0 ? ["review"] : [];
+  if (mode === "rigorous") {
+    if (workflowId?.includes("security")) return ["security", "review"];
+    if (workflowId?.includes("release")) return ["release", "security"];
+    if (workflowId?.includes("migration")) return ["migration", "architecture"];
+    if (workflowId?.includes("architecture")) return ["architecture", "review"];
+    return requiredReview.length > 0 ? ["review", "qa"] : [];
+  }
+  return [];
+}
+
+function createMergePlan(agents: AgentPlannedInvocation[]): AgentMergePlan {
+  if (agents.length === 0)
+    return {
+      strategy: "none",
+      outputSchema: null,
+      dedupeBy: [],
+      conflictPolicy: [],
+      failClosedCategories: [],
+    };
+  if (agents.length === 1)
+    return {
+      strategy: "single-output",
+      outputSchema: agents[0].profile.output.schema,
+      dedupeBy: [],
+      conflictPolicy: [],
+      failClosedCategories: [],
+    };
+  return {
+    strategy: "dedupe-preserve-conflicts-fail-closed",
+    outputSchema: "review-findings-v1",
+    dedupeBy: ["category", "path", "line", "title"],
+    conflictPolicy: ["preserve dissent", "keep higher severity unless evidence refutes"],
+    failClosedCategories: ["security", "privacy", "release"],
+  };
+}
+
+function createLensReason(
+  lens: AgentLens,
+  mode: TaskExecutionMode | null,
+  workflowId: string | null,
+): string {
+  return `${lens} lens selected for ${mode ?? "unrouted"} mode${workflowId ? ` and workflow ${workflowId}` : ""}.`;
+}
+
+function collectPrivacyBoundaryBlockers(
+  contract: TaskContract,
+  lenses: AgentLens[],
+  workflowId: string | null,
+): string[] {
+  const text = [
+    contract.source.summary,
+    contract.currentState.summary,
+    contract.targetState.summary,
+    contract.route.rationale,
+    workflowId ?? "",
+    ...contract.scope.allowedOperations,
+    ...contract.scope.requiresUserConfirmation,
+    ...lenses,
+  ].join(" ");
+  return PRIVACY_BLOCKER_PATTERN.test(text)
+    ? [
+        "Agent planning refuses privacy/risky context requiring raw data, writes, commands, network, spawning, or memory.",
+      ]
+    : [];
+}
+
+function validateRequiredObject(
+  output: unknown,
+  fields: string[],
+): { ok: boolean; errors: string[] } {
+  if (!isRecord(output)) return { ok: false, errors: ["Output must be an object."] };
+  const errors = fields
+    .filter((field) => output[field] === undefined)
+    .map((field) => `${field} is required.`);
+  return { ok: errors.length === 0, errors };
+}
+
+function normalizeAgentPermissions(value: AgentPermissions): AgentPermissions {
+  return { ...createDefaultAgentPermissions(), ...value };
+}
+
+function isKnownOutputSchema(value: unknown): value is AgentOutputSchemaId {
+  return (
+    value === "review-findings-v1" ||
+    value === "verification-summary-v1" ||
+    value === "design-options-v1"
+  );
+}
+
+function dedupeLenses(lenses: AgentLens[]): AgentLens[] {
+  return [...new Set(lenses)];
+}
+
+function severityRank(severity: AgentFindingSeverity): number {
+  return { info: 0, low: 1, medium: 2, high: 3, blocker: 4 }[severity];
+}
+
+function assertString(value: unknown, path: string): void {
+  if (typeof value !== "string" || value.length === 0)
+    throw new Error(`${path} must be a non-empty string.`);
+}
+
+function assertStringArray(value: unknown, path: string): void {
+  if (
+    !Array.isArray(value) ||
+    value.some((item) => typeof item !== "string" || item.length === 0)
+  ) {
+    throw new Error(`${path} must be an array of non-empty strings.`);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/assets/errors.ts

@@ -0,0 +1,21 @@
+export class EvoDevAssetError extends Error {
+  constructor(
+    message: string,
+    readonly filePath?: string,
+  ) {
+    super(filePath ? `${message}: ${filePath}` : message);
+    this.name = "EvoDevAssetError";
+  }
+}
+
+export function describeType(value: unknown): string {
+  if (value === null) {
+    return "null";
+  }
+
+  if (Array.isArray(value)) {
+    return "array";
+  }
+
+  return typeof value;
+}

package/src/assets/index.ts

@@ -0,0 +1,18 @@
+export { EvoDevAssetError } from "./errors.ts";
+export {
+  type AgentManifest,
+  type AssetManifest,
+  type AssetTarget,
+  type BaseAssetManifest,
+  type SkillManifest,
+  parseAgentManifest,
+  parseSkillManifest,
+} from "./manifest.ts";
+export {
+  type AssetScannerPaths,
+  type AssetScanResult,
+  type ScannedAsset,
+  scanAgentAssets,
+  scanAssets,
+  scanSkillAssets,
+} from "./scanner.ts";

package/src/assets/manifest.ts

@@ -0,0 +1,109 @@
+import { EvoDevAssetError, describeType } from "./errors.ts";
+
+export type AssetTarget = "claude" | "codex";
+
+export interface BaseAssetManifest {
+  id: string;
+  name: string;
+  version: string;
+  category: string;
+  description: string;
+  targets: AssetTarget[];
+  entry: string;
+  license?: string;
+}
+
+export interface SkillManifest extends BaseAssetManifest {
+  kind: "skill";
+}
+
+export interface AgentManifest extends BaseAssetManifest {
+  kind: "agent";
+}
+
+export type AssetManifest = SkillManifest | AgentManifest;
+
+export function parseSkillManifest(value: unknown): SkillManifest {
+  return {
+    ...parseBaseManifest(value, "skill manifest"),
+    kind: "skill",
+  };
+}
+
+export function parseAgentManifest(value: unknown): AgentManifest {
+  return {
+    ...parseBaseManifest(value, "agent manifest"),
+    kind: "agent",
+  };
+}
+
+function parseBaseManifest(value: unknown, label: string): BaseAssetManifest {
+  const root = expectRecord(value, label);
+  const manifest: BaseAssetManifest = {
+    id: expectSlug(root.id, `${label}.id`),
+    name: expectNonEmptyString(root.name, `${label}.name`),
+    version: expectNonEmptyString(root.version, `${label}.version`),
+    category: expectSlug(root.category, `${label}.category`),
+    description: expectNonEmptyString(root.description, `${label}.description`),
+    targets: expectTargets(root.targets, `${label}.targets`),
+    entry: expectRelativePath(root.entry, `${label}.entry`),
+  };
+
+  if (root.license !== undefined) {
+    manifest.license = expectNonEmptyString(root.license, `${label}.license`);
+  }
+
+  return manifest;
+}
+
+function expectRecord(value: unknown, path: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new EvoDevAssetError(`Invalid ${path}; expected object, got ${describeType(value)}`);
+  }
+
+  return value as Record<string, unknown>;
+}
+
+function expectNonEmptyString(value: unknown, path: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new EvoDevAssetError(`Invalid ${path}; expected non-empty string`);
+  }
+
+  return value;
+}
+
+function expectSlug(value: unknown, path: string): string {
+  const text = expectNonEmptyString(value, path);
+
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(text)) {
+    throw new EvoDevAssetError(`Invalid ${path}; expected lowercase kebab-case slug`);
+  }
+
+  return text;
+}
+
+function expectTargets(value: unknown, path: string): AssetTarget[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new EvoDevAssetError(`Invalid ${path}; expected non-empty target array`);
+  }
+
+  const targets = value.map((target, index) => {
+    if (target !== "claude" && target !== "codex") {
+      throw new EvoDevAssetError(`Invalid ${path}[${index}]; expected claude or codex`);
+    }
+
+    return target;
+  });
+
+  return [...new Set(targets)];
+}
+
+function expectRelativePath(value: unknown, path: string): string {
+  const text = expectNonEmptyString(value, path);
+
+  if (text.startsWith("/") || text.includes("..")) {
+    throw new EvoDevAssetError(`Invalid ${path}; expected safe relative path`);
+  }
+
+  return text;
+}