@mhingston5/lasso 0.1.0

package/src/mutation/derive.ts

@@ -0,0 +1,308 @@
+import type { HarnessSpec } from "../spec/types.js";
+import type { HarnessExecutionTrace } from "../versioning/types.js";
+import type { HarnessMutation } from "./types.js";
+import type { ExecutionTraceEntry } from "../compiler/runtime-helpers.js";
+import type { FailureSignature, FailureContext, FailureClass } from "../failures/ontology.js";
+
+const FAILURE_THRESHOLD_FOR_VERIFICATION = 2;
+const TRANSIENT_FAILURE_THRESHOLD = 2;
+
+export function deriveMutationsFromTrace(
+  trace: HarnessExecutionTrace,
+  currentSpec: HarnessSpec,
+): HarnessMutation[] {
+  if (trace.entries.length === 0) {
+    return [];
+  }
+
+  const mutations: HarnessMutation[] = [];
+  const failuresByNode = groupFailuresByNode(trace.entries);
+
+  for (const [nodeId, failures] of failuresByNode) {
+    const node = currentSpec.graph.nodes.find((n) => n.id === nodeId);
+    if (!node) continue;
+
+    if (
+      failures.length > FAILURE_THRESHOLD_FOR_VERIFICATION &&
+      !node.verificationPolicy
+    ) {
+      mutations.push({
+        type: "add-verification",
+        params: {
+          nodeId,
+          verificationPolicy: {
+            rules: [
+              {
+                kind: "expression",
+                checkNodeId: `${nodeId}-verify`,
+                onFail: "retry",
+                maxAttempts: 2,
+              },
+            ],
+          },
+        },
+      });
+    }
+
+    const transientFailures = failures.filter(
+      (f) => f.details && (f.details as Record<string, unknown>).category === "transient",
+    );
+    if (
+      transientFailures.length >= TRANSIENT_FAILURE_THRESHOLD &&
+      !node.retryPolicy
+    ) {
+      mutations.push({
+        type: "modify-node",
+        params: {
+          nodeId,
+          changes: {
+            retryPolicy: {
+              maxAttempts: 3,
+              backoff: "exponential",
+              initialDelay: 1,
+            },
+          },
+        },
+      });
+    }
+  }
+
+  if (
+    trace.failureCount > 0 &&
+    currentSpec.humanPolicy &&
+    !(currentSpec.humanPolicy as Record<string, unknown>).approvalRequired
+  ) {
+    mutations.push({
+      type: "toggle-approval",
+      params: { approvalRequired: true },
+    });
+  }
+
+  return mutations;
+}
+
+export function deriveMutationsFromFailure(
+  signature: FailureSignature,
+  currentSpec: HarnessSpec,
+  context?: FailureContext,
+): HarnessMutation[] {
+  const nodeId = context?.nodeId;
+  if (!nodeId) {
+    return [];
+  }
+
+  const node = currentSpec.graph.nodes.find((n) => n.id === nodeId);
+  if (!node) {
+    return [];
+  }
+
+  const mutations: HarnessMutation[] = [];
+
+  switch (signature.class) {
+    case "auth":
+      mutations.push(createAuthCheckMutation(nodeId, currentSpec));
+      break;
+
+    case "tool":
+      mutations.push(createToolAvailabilityCheckMutation(nodeId, currentSpec));
+      break;
+
+    case "resource":
+      mutations.push(createResourceProvisioningCheckMutation(nodeId, currentSpec));
+      break;
+
+    case "network":
+      if (signature.retryable && !node.retryPolicy) {
+        mutations.push(createRetryBackoffMutation(nodeId));
+      }
+      break;
+
+    case "semantic":
+      if (!node.verificationPolicy) {
+        mutations.push(createVerificationMutation(nodeId));
+      }
+      break;
+
+    case "human":
+      mutations.push({
+        type: "toggle-approval",
+        params: { approvalRequired: true },
+      });
+      break;
+
+    case "environment-drift":
+      mutations.push(createEnvironmentCheckMutation(nodeId, currentSpec));
+      break;
+
+    case "unknown":
+      if (!node.verificationPolicy) {
+        mutations.push(createVerificationMutation(nodeId));
+      }
+      break;
+  }
+
+  return mutations;
+}
+
+function createAuthCheckMutation(
+  nodeId: string,
+  spec: HarnessSpec,
+): HarnessMutation {
+  const authCheckId = `${nodeId}-auth-check`;
+  const incomingEdge = spec.graph.edges.find((e) => e.to === nodeId);
+
+  return {
+    type: "add-node",
+    params: {
+      node: {
+        id: authCheckId,
+        label: `Auth check for ${nodeId}`,
+        kind: "tool" as const,
+        tool: "bash",
+        args: ["-c", "git remote -v >/dev/null 2>&1 || echo 'AUTH_FAILED'"],
+      },
+      edges: [
+        {
+          from: incomingEdge?.from ?? spec.graph.entryNodeId,
+          to: authCheckId,
+        },
+        { from: authCheckId, to: nodeId },
+      ],
+    },
+  };
+}
+
+function createToolAvailabilityCheckMutation(
+  nodeId: string,
+  spec: HarnessSpec,
+): HarnessMutation {
+  const checkId = `${nodeId}-tool-check`;
+  const incomingEdge = spec.graph.edges.find((e) => e.to === nodeId);
+
+  return {
+    type: "add-node",
+    params: {
+      node: {
+        id: checkId,
+        label: `Tool availability check for ${nodeId}`,
+        kind: "tool" as const,
+        tool: "bash",
+        args: ["-c", "command -v node >/dev/null 2>&1 || echo 'TOOL_MISSING'"],
+      },
+      edges: [
+        {
+          from: incomingEdge?.from ?? spec.graph.entryNodeId,
+          to: checkId,
+        },
+        { from: checkId, to: nodeId },
+      ],
+    },
+  };
+}
+
+function createResourceProvisioningCheckMutation(
+  nodeId: string,
+  spec: HarnessSpec,
+): HarnessMutation {
+  const checkId = `${nodeId}-resource-check`;
+  const incomingEdge = spec.graph.edges.find((e) => e.to === nodeId);
+
+  return {
+    type: "add-node",
+    params: {
+      node: {
+        id: checkId,
+        label: `Resource check for ${nodeId}`,
+        kind: "tool" as const,
+        tool: "bash",
+        args: ["-c", "df -h / | awk 'NR==2 {print $5}' | sed 's/%//' | awk '{if ($1 > 90) print \"DISK_FULL\"}'"],
+      },
+      edges: [
+        {
+          from: incomingEdge?.from ?? spec.graph.entryNodeId,
+          to: checkId,
+        },
+        { from: checkId, to: nodeId },
+      ],
+    },
+  };
+}
+
+function createRetryBackoffMutation(nodeId: string): HarnessMutation {
+  return {
+    type: "modify-node",
+    params: {
+      nodeId,
+      changes: {
+        retryPolicy: {
+          maxAttempts: 3,
+          backoff: "exponential",
+          initialDelay: 1,
+        },
+      },
+    },
+  };
+}
+
+function createVerificationMutation(nodeId: string): HarnessMutation {
+  return {
+    type: "add-verification",
+    params: {
+      nodeId,
+      verificationPolicy: {
+        rules: [
+          {
+            kind: "expression",
+            checkNodeId: `${nodeId}-verify`,
+            onFail: "retry",
+            maxAttempts: 2,
+          },
+        ],
+      },
+    },
+  };
+}
+
+function createEnvironmentCheckMutation(
+  nodeId: string,
+  spec: HarnessSpec,
+): HarnessMutation {
+  const checkId = `${nodeId}-env-check`;
+  const incomingEdge = spec.graph.edges.find((e) => e.to === nodeId);
+
+  return {
+    type: "add-node",
+    params: {
+      node: {
+        id: checkId,
+        label: `Environment check for ${nodeId}`,
+        kind: "tool" as const,
+        tool: "bash",
+        args: ["-c", "uname -a >/dev/null 2>&1 || echo 'ENV_CHECK_FAILED'"],
+      },
+      edges: [
+        {
+          from: incomingEdge?.from ?? spec.graph.entryNodeId,
+          to: checkId,
+        },
+        { from: checkId, to: nodeId },
+      ],
+    },
+  };
+}
+
+function groupFailuresByNode(
+  entries: ExecutionTraceEntry[],
+): Map<string, ExecutionTraceEntry[]> {
+  const grouped = new Map<string, ExecutionTraceEntry[]>();
+
+  for (const entry of entries) {
+    if (entry.phase === "failure") {
+      const existing = grouped.get(entry.nodeId) ?? [];
+      existing.push(entry);
+      grouped.set(entry.nodeId, existing);
+    }
+  }
+
+  return grouped;
+}

package/src/mutation/diff.ts

@@ -0,0 +1,52 @@
+import type { HarnessSpec } from "../spec/types.js";
+import type { SpecDiff } from "./types.js";
+
+export function diffSpecs(before: HarnessSpec, after: HarnessSpec): SpecDiff {
+  const beforeNodeIds = new Set(before.graph.nodes.map((n) => n.id));
+  const afterNodeIds = new Set(after.graph.nodes.map((n) => n.id));
+
+  const addedNodes: string[] = [];
+  const removedNodes: string[] = [];
+  const modifiedNodes: string[] = [];
+
+  for (const id of afterNodeIds) {
+    if (!beforeNodeIds.has(id)) {
+      addedNodes.push(id);
+    }
+  }
+
+  for (const id of beforeNodeIds) {
+    if (!afterNodeIds.has(id)) {
+      removedNodes.push(id);
+    }
+  }
+
+  for (const afterNode of after.graph.nodes) {
+    if (!beforeNodeIds.has(afterNode.id)) continue;
+    const beforeNode = before.graph.nodes.find((n) => n.id === afterNode.id);
+    if (beforeNode && JSON.stringify(beforeNode) !== JSON.stringify(afterNode)) {
+      modifiedNodes.push(afterNode.id);
+    }
+  }
+
+  const edgeKey = (e: { from: string; to: string }) => `${e.from}->${e.to}`;
+  const beforeEdges = new Map(before.graph.edges.map((e) => [edgeKey(e), e]));
+  const afterEdges = new Map(after.graph.edges.map((e) => [edgeKey(e), e]));
+
+  const addedEdges: Array<{ from: string; to: string }> = [];
+  const removedEdges: Array<{ from: string; to: string }> = [];
+
+  for (const [key, edge] of afterEdges) {
+    if (!beforeEdges.has(key)) {
+      addedEdges.push(edge);
+    }
+  }
+
+  for (const [key, edge] of beforeEdges) {
+    if (!afterEdges.has(key)) {
+      removedEdges.push(edge);
+    }
+  }
+
+  return { addedNodes, removedNodes, modifiedNodes, addedEdges, removedEdges };
+}

package/src/mutation/engine.ts

@@ -0,0 +1,256 @@
+import type { HarnessSpec, TaskNode, TaskEdge } from "../spec/types.js";
+import { diffSpecs } from "./diff.js";
+import type {
+  HarnessMutation,
+  MutationPolicy,
+  MutationResult,
+  AddNodeParams,
+  RemoveNodeParams,
+  ModifyNodeParams,
+  AddEdgeParams,
+  ToggleApprovalParams,
+  AddVerificationParams,
+  ReplaceNodeParams,
+  TightenGuardrailParams,
+} from "./types.js";
+
+export function mutateHarness(
+  spec: HarnessSpec,
+  mutations: HarnessMutation[],
+  policy?: MutationPolicy,
+): MutationResult {
+  if (policy) {
+    enforcePolicy(mutations, policy);
+  }
+
+  let current: HarnessSpec = structuredClone(spec);
+  const applied: HarnessMutation[] = [];
+
+  for (const mutation of mutations) {
+    switch (mutation.type) {
+      case "add-node":
+        current = applyAddNode(current, mutation.params as unknown as AddNodeParams);
+        break;
+      case "remove-node":
+        current = applyRemoveNode(current, mutation.params as unknown as RemoveNodeParams);
+        break;
+      case "modify-node":
+        current = applyModifyNode(current, mutation.params as unknown as ModifyNodeParams);
+        break;
+      case "add-edge":
+        current = applyAddEdge(current, mutation.params as unknown as AddEdgeParams);
+        break;
+      case "toggle-approval":
+        current = applyToggleApproval(current, mutation.params as unknown as ToggleApprovalParams);
+        break;
+      case "add-verification":
+        current = applyAddVerification(current, mutation.params as unknown as AddVerificationParams);
+        break;
+      case "replace-node":
+        current = applyReplaceNode(current, mutation.params as unknown as ReplaceNodeParams);
+        break;
+      case "tighten-guardrail":
+        current = applyTightenGuardrail(current, mutation.params as unknown as TightenGuardrailParams);
+        break;
+    }
+    applied.push(mutation);
+  }
+
+  return {
+    spec: current,
+    mutations: applied,
+    diff: diffSpecs(spec, current),
+  };
+}
+
+function enforcePolicy(mutations: HarnessMutation[], policy: MutationPolicy): void {
+  const allowed = new Set(policy.allowedMutations);
+  for (const mutation of mutations) {
+    if (!allowed.has(mutation.type)) {
+      throw new Error(`Mutation type "${mutation.type}" is not allowed by policy`);
+    }
+  }
+
+  if (mutations.length > policy.maxMutations) {
+    throw new Error(
+      `Mutation count ${mutations.length} exceeds maximum allowed ${policy.maxMutations}`,
+    );
+  }
+}
+
+function applyAddNode(spec: HarnessSpec, params: AddNodeParams): HarnessSpec {
+  const existing = spec.graph.nodes.find((n) => n.id === params.node.id);
+  if (existing) {
+    throw new Error(`Node "${params.node.id}" already exists`);
+  }
+
+  const nodes = [...spec.graph.nodes, params.node];
+  const edges = params.edges
+    ? [...spec.graph.edges, ...params.edges]
+    : [...spec.graph.edges];
+
+  return {
+    ...spec,
+    graph: { ...spec.graph, nodes, edges },
+  };
+}
+
+function applyRemoveNode(spec: HarnessSpec, params: RemoveNodeParams): HarnessSpec {
+  const node = spec.graph.nodes.find((n) => n.id === params.nodeId);
+  if (!node) {
+    throw new Error(`Node "${params.nodeId}" not found`);
+  }
+
+  const incoming = spec.graph.edges.filter((e) => e.to === params.nodeId);
+  const outgoing = spec.graph.edges.filter((e) => e.from === params.nodeId);
+
+  const remainingEdges = spec.graph.edges.filter(
+    (e) => e.from !== params.nodeId && e.to !== params.nodeId,
+  );
+
+  const bridgingEdges: TaskEdge[] = [];
+  for (const inEdge of incoming) {
+    for (const outEdge of outgoing) {
+      bridgingEdges.push({ from: inEdge.from, to: outEdge.to });
+    }
+  }
+
+  const nodes = spec.graph.nodes.filter((n) => n.id !== params.nodeId);
+  const edges = [...remainingEdges, ...bridgingEdges];
+
+  let entryNodeId = spec.graph.entryNodeId;
+  if (entryNodeId === params.nodeId && nodes.length > 0) {
+    entryNodeId = nodes[0].id;
+  }
+
+  return {
+    ...spec,
+    graph: { ...spec.graph, nodes, edges, entryNodeId },
+  };
+}
+
+function applyModifyNode(spec: HarnessSpec, params: ModifyNodeParams): HarnessSpec {
+  const idx = spec.graph.nodes.findIndex((n) => n.id === params.nodeId);
+  if (idx === -1) {
+    throw new Error(`Node "${params.nodeId}" not found`);
+  }
+
+  const { id: _id, kind: _kind, ...safeChanges } = params.changes as Record<string, unknown>;
+
+  const nodes = [...spec.graph.nodes];
+  nodes[idx] = { ...nodes[idx], ...safeChanges } as TaskNode;
+
+  return {
+    ...spec,
+    graph: { ...spec.graph, nodes },
+  };
+}
+
+function applyAddEdge(spec: HarnessSpec, params: AddEdgeParams): HarnessSpec {
+  const exists = spec.graph.edges.some(
+    (e) => e.from === params.edge.from && e.to === params.edge.to,
+  );
+  if (exists) {
+    throw new Error(
+      `Edge "${params.edge.from}->${params.edge.to}" already exists`,
+    );
+  }
+
+  const fromNode = spec.graph.nodes.find((n) => n.id === params.edge.from);
+  if (!fromNode) {
+    throw new Error(`Source node "${params.edge.from}" not found`);
+  }
+
+  const toNode = spec.graph.nodes.find((n) => n.id === params.edge.to);
+  if (!toNode) {
+    throw new Error(`Target node "${params.edge.to}" not found`);
+  }
+
+  return {
+    ...spec,
+    graph: { ...spec.graph, edges: [...spec.graph.edges, params.edge] },
+  };
+}
+
+function applyToggleApproval(
+  spec: HarnessSpec,
+  params: ToggleApprovalParams,
+): HarnessSpec {
+  const currentPolicy = spec.humanPolicy ?? {};
+  const currentApproval = (currentPolicy as Record<string, unknown>).approvalRequired as
+    | boolean
+    | undefined;
+
+  const newApproval =
+    params.approvalRequired !== undefined ? params.approvalRequired : !currentApproval;
+
+  return {
+    ...spec,
+    humanPolicy: {
+      ...currentPolicy,
+      approvalRequired: newApproval,
+    },
+  };
+}
+
+function applyAddVerification(
+  spec: HarnessSpec,
+  params: AddVerificationParams,
+): HarnessSpec {
+  const idx = spec.graph.nodes.findIndex((n) => n.id === params.nodeId);
+  if (idx === -1) {
+    throw new Error(`Node "${params.nodeId}" not found`);
+  }
+
+  const nodes = [...spec.graph.nodes];
+  nodes[idx] = {
+    ...nodes[idx],
+    verificationPolicy: params.verificationPolicy,
+  } as TaskNode;
+
+  return {
+    ...spec,
+    graph: { ...spec.graph, nodes },
+  };
+}
+
+function applyReplaceNode(
+  spec: HarnessSpec,
+  params: ReplaceNodeParams,
+): HarnessSpec {
+  const idx = spec.graph.nodes.findIndex((n) => n.id === params.nodeId);
+  if (idx === -1) {
+    throw new Error(`Node "${params.nodeId}" not found`);
+  }
+
+  const { id: _id, kind: _kind, ...safeChanges } = params.changes as Record<string, unknown>;
+
+  const nodes = [...spec.graph.nodes];
+  nodes[idx] = { ...nodes[idx], ...safeChanges } as TaskNode;
+
+  return {
+    ...spec,
+    graph: { ...spec.graph, nodes },
+  };
+}
+
+function applyTightenGuardrail(
+  spec: HarnessSpec,
+  params: TightenGuardrailParams,
+): HarnessSpec {
+  const idx = spec.graph.nodes.findIndex((n) => n.id === params.nodeId);
+  if (idx === -1) {
+    throw new Error(`Node "${params.nodeId}" not found`);
+  }
+
+  const nodes = [...spec.graph.nodes];
+  nodes[idx] = {
+    ...nodes[idx],
+    verificationPolicy: params.verificationPolicy,
+  } as TaskNode;
+
+  return {
+    ...spec,
+    graph: { ...spec.graph, nodes },
+  };
+}

package/src/mutation/types.ts

@@ -0,0 +1,84 @@
+import type { HarnessSpec, TaskNode, TaskEdge } from "../spec/types.js";
+
+export type MutationType =
+  | "add-node"
+  | "remove-node"
+  | "modify-node"
+  | "add-edge"
+  | "toggle-approval"
+  | "add-verification"
+  | "replace-node"
+  | "tighten-guardrail";
+
+export type MutationTrigger =
+  | "node_failed"
+  | "confidence_low"
+  | "cost_high"
+  | "loop_detected"
+  | "retry_exhausted"
+  | "verification_failed"
+  | "tool_missing"
+  | "auth_expired";
+
+export interface HarnessMutation {
+  type: MutationType;
+  params: Record<string, unknown>;
+  trigger?: MutationTrigger;
+  description?: string;
+}
+
+export interface MutationPolicy {
+  allowedMutations: MutationType[];
+  maxMutations: number;
+}
+
+export interface MutationResult {
+  spec: HarnessSpec;
+  mutations: HarnessMutation[];
+  diff: SpecDiff;
+}
+
+export interface SpecDiff {
+  addedNodes: string[];
+  removedNodes: string[];
+  modifiedNodes: string[];
+  addedEdges: Array<{ from: string; to: string }>;
+  removedEdges: Array<{ from: string; to: string }>;
+}
+
+export interface AddNodeParams {
+  node: TaskNode;
+  edges?: TaskEdge[];
+}
+
+export interface RemoveNodeParams {
+  nodeId: string;
+}
+
+export interface ModifyNodeParams {
+  nodeId: string;
+  changes: Partial<TaskNode>;
+}
+
+export interface AddEdgeParams {
+  edge: TaskEdge;
+}
+
+export interface ToggleApprovalParams {
+  approvalRequired?: boolean;
+}
+
+export interface AddVerificationParams {
+  nodeId: string;
+  verificationPolicy: NonNullable<TaskNode["verificationPolicy"]>;
+}
+
+export interface ReplaceNodeParams {
+  nodeId: string;
+  changes: Partial<TaskNode>;
+}
+
+export interface TightenGuardrailParams {
+  nodeId: string;
+  verificationPolicy: NonNullable<TaskNode["verificationPolicy"]>;
+}