@mhingston5/lasso 0.1.0

package/src/spec/schema.ts

@@ -0,0 +1,254 @@
+/**
+ * JSON Schema for HarnessSpec validation using Ajv
+ */
+
+export const harnessSpecSchema = {
+  type: "object",
+  required: ["name", "graph"],
+  additionalProperties: false,
+  properties: {
+    name: { type: "string", minLength: 1 },
+    graph: {
+      type: "object",
+      required: ["entryNodeId", "nodes", "edges"],
+      additionalProperties: false,
+      properties: {
+        entryNodeId: { type: "string", minLength: 1 },
+        nodes: {
+          type: "array",
+          items: {
+            oneOf: [
+              {
+                type: "object",
+                required: ["id", "kind", "tool", "args"],
+                additionalProperties: false,
+                properties: {
+                  id: { type: "string", minLength: 1 },
+                  kind: { const: "tool" },
+                  tool: { type: "string", minLength: 1 },
+                  args: { type: "array", items: { type: "string" } },
+                  env: { 
+                    type: "object",
+                    additionalProperties: { type: "string" }
+                  },
+                  cwd: { type: "string" },
+                  label: { type: "string" },
+                  executionPolicy: { $ref: "#/$defs/executionPolicy" },
+                  retryPolicy: { $ref: "#/$defs/retryPolicy" },
+                  verificationPolicy: { $ref: "#/$defs/verificationPolicy" }
+                }
+              },
+              {
+                type: "object",
+                required: ["id", "kind", "provider", "model", "prompt"],
+                additionalProperties: false,
+                properties: {
+                  id: { type: "string", minLength: 1 },
+                  kind: { const: "llm" },
+                  provider: { type: "string", minLength: 1 },
+                  model: { type: "string", minLength: 1 },
+                  prompt: { type: "string", minLength: 1 },
+                  system: { type: "string" },
+                  temperature: { type: "number" },
+                  maxTokens: { type: "number" },
+                  label: { type: "string" },
+                  executionPolicy: { $ref: "#/$defs/executionPolicy" },
+                  retryPolicy: { $ref: "#/$defs/retryPolicy" },
+                  verificationPolicy: { $ref: "#/$defs/verificationPolicy" }
+                }
+              },
+              {
+                type: "object",
+                required: ["id", "kind", "prompt", "interactionType"],
+                additionalProperties: false,
+                properties: {
+                  id: { type: "string", minLength: 1 },
+                  kind: { const: "human" },
+                  prompt: { type: "string", minLength: 1 },
+                  interactionType: { enum: ["approval", "input", "choice"] },
+                  options: { type: "array", items: { type: "string" } },
+                  timeout: { type: "number" },
+                  label: { type: "string" },
+                  executionPolicy: { $ref: "#/$defs/executionPolicy" },
+                  verificationPolicy: { $ref: "#/$defs/verificationPolicy" }
+                }
+              },
+              {
+                type: "object",
+                required: ["id", "kind", "condition", "thenNodeId", "elseNodeId"],
+                additionalProperties: false,
+                properties: {
+                  id: { type: "string", minLength: 1 },
+                  kind: { const: "condition" },
+                  condition: { type: "string", minLength: 1 },
+                  thenNodeId: { type: "string", minLength: 1 },
+                  elseNodeId: { type: "string", minLength: 1 },
+                  label: { type: "string" },
+                  executionPolicy: { $ref: "#/$defs/executionPolicy" },
+                  verificationPolicy: { $ref: "#/$defs/verificationPolicy" }
+                }
+              },
+              {
+                type: "object",
+                required: ["id", "kind", "waitFor"],
+                additionalProperties: false,
+                properties: {
+                  id: { type: "string", minLength: 1 },
+                  kind: { const: "merge" },
+                  waitFor: { type: "array", items: { type: "string", minLength: 1 }, minItems: 1 },
+                  strategy: { enum: ["all", "any", "majority"] },
+                  label: { type: "string" },
+                  executionPolicy: { $ref: "#/$defs/executionPolicy" },
+                  verificationPolicy: { $ref: "#/$defs/verificationPolicy" }
+                }
+              },
+              {
+                type: "object",
+                required: ["id", "kind", "specRef"],
+                additionalProperties: false,
+                properties: {
+                  id: { type: "string", minLength: 1 },
+                  kind: { const: "subworkflow" },
+                  specRef: { type: "string", minLength: 1 },
+                  inputs: { type: "object" },
+                  label: { type: "string" },
+                  executionPolicy: { $ref: "#/$defs/executionPolicy" },
+                  retryPolicy: { $ref: "#/$defs/retryPolicy" },
+                  verificationPolicy: { $ref: "#/$defs/verificationPolicy" }
+                }
+              }
+            ]
+          }
+        },
+        edges: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["from", "to"],
+            additionalProperties: false,
+            properties: {
+              from: { type: "string", minLength: 1 },
+              to: { type: "string", minLength: 1 }
+            }
+          }
+        }
+      }
+    },
+    executionPolicy: { $ref: "#/$defs/executionPolicy" },
+    humanPolicy: { $ref: "#/$defs/humanPolicy" },
+    observabilityPolicy: { $ref: "#/$defs/observabilityPolicy" }
+  },
+  $defs: {
+    executionPolicy: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        timeout: { type: "number" },
+        maxMemory: { type: "number" },
+        maxSteps: { type: "number", minimum: 1 },
+        costLimitUsd: { type: "number", exclusiveMinimum: 0 },
+        continueOnFailure: { type: "boolean" },
+        failureClassification: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["pattern", "category", "retry"],
+            additionalProperties: false,
+            properties: {
+              pattern: { type: "string", minLength: 1 },
+              category: { enum: ["transient", "permanent", "resource", "configuration"] },
+              retry: { type: "boolean" }
+            }
+          }
+        }
+      }
+    },
+    retryPolicy: {
+      type: "object",
+      required: ["maxAttempts", "backoff"],
+      additionalProperties: false,
+      properties: {
+        maxAttempts: { type: "number", minimum: 1 },
+        backoff: { enum: ["constant", "linear", "exponential"] },
+        initialDelay: { type: "number" },
+        maxDelay: { type: "number" },
+        retryOn: {
+          type: "array",
+          items: { enum: ["transient", "resource"] }
+        }
+      }
+    },
+    verificationPolicy: {
+      type: "object",
+      required: ["rules"],
+      additionalProperties: false,
+      properties: {
+        rules: {
+          type: "array",
+          items: {
+            oneOf: [
+              {
+                type: "object",
+                required: ["kind", "checkNodeId", "onFail"],
+                additionalProperties: false,
+                properties: {
+                  kind: { const: "tool" },
+                  checkNodeId: { type: "string", minLength: 1 },
+                  onFail: { enum: ["block", "warn", "retry"] },
+                  maxAttempts: { type: "number" }
+                }
+              },
+              {
+                type: "object",
+                required: ["kind", "checkNodeId", "onFail"],
+                additionalProperties: false,
+                properties: {
+                  kind: { const: "llm" },
+                  checkNodeId: { type: "string", minLength: 1 },
+                  onFail: { enum: ["block", "warn", "retry"] },
+                  maxAttempts: { type: "number" }
+                }
+              },
+              {
+                type: "object",
+                required: ["kind", "checkNodeId", "onFail"],
+                additionalProperties: false,
+                properties: {
+                  kind: { const: "expression" },
+                  checkNodeId: { type: "string", minLength: 1 },
+                  onFail: { enum: ["block", "warn", "retry"] },
+                  maxAttempts: { type: "number" }
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    humanPolicy: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        defaultTimeout: { type: "number" },
+        allowAsync: { type: "boolean" },
+        notificationChannels: {
+          type: "array",
+          items: { type: "string" }
+        }
+      }
+    },
+    observabilityPolicy: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        tracing: { type: "boolean" },
+        metrics: { type: "boolean" },
+        logLevel: { enum: ["debug", "info", "warn", "error"] },
+        logDestinations: {
+          type: "array",
+          items: { type: "string" }
+        }
+      }
+    }
+  }
+};

package/src/spec/types.ts

@@ -0,0 +1,319 @@
+/**
+ * Lasso Harness Specification Types
+ *
+ * Declarative contract for defining autonomous task workflows.
+ */
+
+// ============================================================================
+// Core Harness Spec
+// ============================================================================
+
+export interface HarnessSpec {
+  /** Unique name for this harness */
+  name: string;
+
+  /** Task graph defining the workflow */
+  graph: TaskGraph;
+
+  /** Global execution policies (optional) */
+  executionPolicy?: ExecutionPolicy;
+
+  /** Human intervention policies (optional) */
+  humanPolicy?: HumanPolicy;
+
+  /** Observability configuration (optional) */
+  observabilityPolicy?: ObservabilityPolicy;
+}
+
+// ============================================================================
+// Task Graph
+// ============================================================================
+
+export interface TaskGraph {
+  /** ID of the entry node where execution begins */
+  entryNodeId: string;
+
+  /** All nodes in the graph */
+  nodes: TaskNode[];
+
+  /** Edges connecting nodes */
+  edges: TaskEdge[];
+}
+
+export interface TaskEdge {
+  /** Source node ID */
+  from: string;
+
+  /** Target node ID */
+  to: string;
+}
+
+// ============================================================================
+// Node Types
+// ============================================================================
+
+export type TaskNode =
+  | ToolNode
+  | LlmNode
+  | HumanNode
+  | ConditionNode
+  | MergeNode
+  | SubworkflowNode;
+
+export interface BaseNode {
+  /** Unique node identifier */
+  id: string;
+
+  /** Optional human-readable label */
+  label?: string;
+
+  /** Execution policy for this node */
+  executionPolicy?: ExecutionPolicy;
+
+  /** Retry policy for this node (only valid for tool, llm, subworkflow nodes) */
+  retryPolicy?: RetryPolicy;
+
+  /** Verification policy for this node */
+  verificationPolicy?: VerificationPolicy;
+}
+
+/** Execute a tool command */
+export interface ToolNode extends BaseNode {
+  kind: "tool";
+
+  /** Tool name or path */
+  tool: string;
+
+  /** Arguments to pass to the tool */
+  args: string[];
+
+  /** Environment variables (optional) */
+  env?: Record<string, string>;
+
+  /** Working directory (optional) */
+  cwd?: string;
+}
+
+/** Execute an LLM prompt */
+export interface LlmNode extends BaseNode {
+  kind: "llm";
+
+  /** LLM provider identifier */
+  provider: string;
+
+  /** Model name */
+  model: string;
+
+  /** Prompt template or literal */
+  prompt: string;
+
+  /** Optional system message */
+  system?: string;
+
+  /** Temperature (optional) */
+  temperature?: number;
+
+  /** Max tokens (optional) */
+  maxTokens?: number;
+}
+
+/** Wait for human input/approval */
+export interface HumanNode extends BaseNode {
+  kind: "human";
+
+  /** Prompt to show the human */
+  prompt: string;
+
+  /** Type of human interaction */
+  interactionType: "approval" | "input" | "choice";
+
+  /** For choice interactions, the available options */
+  options?: string[];
+
+  /** Timeout in seconds (optional) */
+  timeout?: number;
+}
+
+/** Conditional branching based on expression */
+export interface ConditionNode extends BaseNode {
+  kind: "condition";
+
+  /** Condition expression to evaluate */
+  condition: string;
+
+  /** Node ID to execute if condition is true */
+  thenNodeId: string;
+
+  /** Node ID to execute if condition is false */
+  elseNodeId: string;
+}
+
+/** Merge point for parallel branches */
+export interface MergeNode extends BaseNode {
+  kind: "merge";
+
+  /** List of node IDs to wait for */
+  waitFor: string[];
+
+  /** Merge strategy */
+  strategy?: "all" | "any" | "majority";
+}
+
+/** Execute a sub-workflow */
+export interface SubworkflowNode extends BaseNode {
+  kind: "subworkflow";
+
+  /** Reference to another harness spec */
+  specRef: string;
+
+  /** Input parameters to pass to the subworkflow */
+  inputs?: Record<string, any>;
+}
+
+// ============================================================================
+// Execution Policies
+// ============================================================================
+
+export interface ExecutionPolicy {
+  /** Timeout in seconds (optional) */
+  timeout?: number;
+
+  /** Maximum memory in MB (optional) */
+  maxMemory?: number;
+
+  /** Maximum number of node executions (optional) */
+  maxSteps?: number;
+
+  /** Maximum LLM cost in USD (optional) */
+  costLimitUsd?: number;
+
+  /** Whether to continue on failure */
+  continueOnFailure?: boolean;
+
+  /** Failure classification rules */
+  failureClassification?: FailureClassification[];
+}
+
+export interface FailureClassification {
+  /** Pattern to match against error messages */
+  pattern: string;
+
+  /** Classification category */
+  category: "transient" | "permanent" | "resource" | "configuration";
+
+  /** Whether to retry on this classification */
+  retry: boolean;
+}
+
+// ============================================================================
+// Retry Policy
+// ============================================================================
+
+export interface RetryPolicy {
+  /** Maximum number of retry attempts */
+  maxAttempts: number;
+
+  /** Backoff strategy */
+  backoff: "constant" | "linear" | "exponential";
+
+  /** Initial delay in seconds (optional) */
+  initialDelay?: number;
+
+  /** Maximum delay in seconds (optional) */
+  maxDelay?: number;
+
+  /** Retry only on specific failure categories (optional) */
+  retryOn?: Array<"transient" | "resource">;
+}
+
+// ============================================================================
+// Verification Policy
+// ============================================================================
+
+export interface VerificationPolicy {
+  /** Verification rules */
+  rules: VerificationRule[];
+
+  /** Verification strategy */
+  strategy?: "all-must-pass" | "first-pass" | "any-block";
+}
+
+export type VerificationRule =
+  | ToolVerificationRule
+  | LlmVerificationRule
+  | ExpressionVerificationRule;
+
+export interface ToolVerificationRule {
+  /** Verification kind - tool verifier */
+  kind: "tool";
+
+  /** Node ID of the tool verification check to run */
+  checkNodeId: string;
+
+  /** Action to take on verification failure */
+  onFail: "block" | "warn" | "retry";
+
+  /** Maximum verification attempts (optional) */
+  maxAttempts?: number;
+}
+
+export interface LlmVerificationRule {
+  /** Verification kind - LLM verifier */
+  kind: "llm";
+
+  /** Node ID of the LLM verification check to run */
+  checkNodeId: string;
+
+  /** Action to take on verification failure */
+  onFail: "block" | "warn" | "retry";
+
+  /** Maximum verification attempts (optional) */
+  maxAttempts?: number;
+}
+
+export interface ExpressionVerificationRule {
+  /** Verification kind - expression verifier */
+  kind: "expression";
+
+  /** Node ID of the condition verification check to run */
+  checkNodeId: string;
+
+  /** Action to take on verification failure */
+  onFail: "block" | "warn" | "retry";
+
+  /** Maximum verification attempts (optional) */
+  maxAttempts?: number;
+}
+
+// ============================================================================
+// Human Policy
+// ============================================================================
+
+export interface HumanPolicy {
+  /** Default timeout for human interactions in seconds */
+  defaultTimeout?: number;
+
+  /** Whether to allow asynchronous human interactions */
+  allowAsync?: boolean;
+
+  /** Notification channels for human interventions */
+  notificationChannels?: string[];
+}
+
+// ============================================================================
+// Observability Policy
+// ============================================================================
+
+export interface ObservabilityPolicy {
+  /** Whether to collect traces */
+  tracing?: boolean;
+
+  /** Whether to collect metrics */
+  metrics?: boolean;
+
+  /** Log level */
+  logLevel?: "debug" | "info" | "warn" | "error";
+
+  /** Custom log destinations */
+  logDestinations?: string[];
+}