Lasso

Table of contents

• What is Lasso?
• Why Lasso exists
• What Lasso does
• How it works
• Slash commands
• Bundled workflows
• Request examples
• Custom workflows
• HarnessSpec reference
• Library API
  • Compiler
  • Compiler feedback
  • Verification engine
  • Compiler optimizations
  • Harness mutations
  • Guardrails
  • Failure mode generation
  • Risk assessment
  • Per-node harnesses
  • Trace-based synthesis
  • Adaptive runtime
  • Lineage persistence
  • Harness memory
  • Environment model
  • Failure ontology
  • Capabilities
  • Meta-harness
  • Multi-harness composition
• How Lasso fits with pi-duroxide
• Non-goals

---

Lasso goes from intent to executable workflow — and repairs the harness while it runs.

Intent
  → Environment discovery (tools, resources, constraints)
  → Memory query (past patterns, what worked/failed)
  → Graph synthesis (planner + capabilities)
  → Failure prediction (auth, tool, network, resource)
  → Risk assessment (probability × impact, threshold filtering)
  → Policy synthesis (mutations: add verification, retry, approval)
  → Compilation (validate → lower → optimize → execute)
  → Per-node harnesses (guardrails, verification hooks)
  → Runtime adaptation (trace → synthesize → continueAsNew)

What is Lasso?

Lasso is a runtime harness synthesizer built on pi-duroxide. It synthesizes deterministic scaffolding around non-deterministic parts — predicting failures, assessing risks, and generating per-node guardrails before execution. It's a TypeScript package that plugs into pi via the pi field in package.json. When installed, it:

1. Boots pi-duroxide (the durable workflow runtime)
2. Registers 5 slash commands (/lasso:plan, /lasso:run, etc.)
3. Exports a library API for programmatic use

There are two ways to use it:

Mode	How	When
Chat mode	Slash commands inside pi's coding agent UI	Interactive workflow planning and execution
Library mode	import { compileHarnessSpec } from "lasso"	Building custom tooling, CI pipelines, or other extensions

Quick start

Install

# From this repository
pi install .

# Or from npm (once published)
pi install @mhingston5/lasso

Chat mode (inside pi)

# 1. Plan a workflow from a freeform brief
/lasso:plan Validate that the bug fix in fix.patch works against main

# 2. Run it (paste the JSON output from step 1)
/lasso:run {"workflow":"patch-validation","input":{...}}

# 3. Inspect what happened
/lasso:inspect

Library mode (TypeScript)

import { compileHarnessSpec, mutateHarness, classifyFailure } from "lasso";

const compiled = compileHarnessSpec(spec);
const signature = classifyFailure(error, { nodeId: "deploy" });

Safety: Lasso checks out refs, applies patches, and merges branches in the target repo. Use a throwaway clone or disposable worktree, not your primary checkout.

---

Why Lasso exists

pi-duroxide gives you a durable workflow runtime. That is the right layer when you already know what workflow you want to run.

Lasso sits one level higher. It:

1. discovers the execution environment (available tools, auth, constraints)
2. synthesizes a workflow graph from intent
3. predicts failures before they happen
4. mutates the harness to prevent them
5. compiles into a replay-safe durable workflow
6. repairs the harness at runtime based on observed failures
7. remembers what worked across sessions

Use Lasso when you want workflow automation that is:

• more reusable than an ad hoc prompt
• more inspectable than hidden agent logic
• safer to validate before execution
• adaptive — it repairs itself when things go wrong
• aware of its environment — it knows what tools are available

What Lasso does

Lasso takes a declarative HarnessSpec, validates it, lowers it to CIR, optimizes it, and compiles it into a replay-safe workflow that runs on pi-duroxide.

Out of the box, it ships with:

• Two bundled workflows — patch-validation and pr-review-merge
• Slash commands — /lasso:plan, /lasso:replan, /lasso:compile, /lasso:run, /lasso:inspect
• A library API — for programmatic use from TypeScript

How it works

The generation pipeline

Intent (brief or skill markdown)
  ↓
parsePromptOrSkill() → IntentIR
  ↓
buildTaskGraph() → TaskGraph
  ↓
analyzeRisks() → RiskModel
  ↓
generateFailureModes() → FailureMode[] + Risk[]
  ↓
assessRisks() → RiskAssessment (overallScore, threshold filtering)
  ↓
synthesizePolicy() → PolicyBundle
  ↓
synthesizeHarness() → HarnessSpec (with per-node guardrails & verification hooks)
  ↓
compileHarnessSpec() → CompiledWorkflow → pi-duroxide

The adaptation loop

Workflow executes
  ↓
Execution trace captured (timestamps, I/O snapshots, failures)
  ↓
synthesizeFromTrace(trace, currentSpec, env) → HarnessSynthesisResult
  → classifies repeated failures, slow nodes, cost spikes
  → derives mutations
  ↓
mutateHarness(spec, mutations) → new spec
  ↓
prepareRuntimeReplan() → continue_as_new / needs_operator_input / stop
  ↓
New version with repaired harness

The feedback loop

compileHarnessSpec()
  ↓
analyzeCompiledWorkflow()
  → CostEstimate (LLM calls, duration, USD)
  → RiskAssessment (cost, failure, quality, complexity)
  → HarnessMutation[] (executable, with triggers)
  ↓
mutateHarness(spec, mutations)
  → replace expensive models
  → add retry policies
  → add verification hooks
  ↓
Recompile with improvements

---

Slash commands

Command	Use it when	What it does
/lasso:plan <brief>	You have an English brief and want a draft request	Returns a draft JSON request or a clarification result
/lasso:replan <JSON>	You have a previous request plus a real outcome	Returns a revised draft, needs_operator_input, or stop
/lasso:compile <input>	You want to inspect what Lasso will register	Compiles and stores the artifact in memory
/lasso:run <input>	You want to execute a workflow locally	Compiles, registers, and starts the workflow
/lasso:inspect [name]	You want to see compiled spec, CIR, and runtime state	Shows the latest or named compiled workflow

/lasso:plan

Deterministic, draft-only. Classifies a brief into patch-validation, pr-review-merge, or custom and returns a draft JSON envelope you can pass to /lasso:compile or /lasso:run. Does not compile, register, or run anything.

For the two bundled families, it extracts structured fields with strict validation. For custom families (via skill markdown with an explicit workflow name), it builds a sequential graph from parsed steps.

/lasso:replan

Deterministic, draft-only. Accepts the original request plus an observedOutcome and returns one of:

1. a revised draft request
2. needs_operator_input — human must provide new facts
3. stop — auto-retrying would be wrong

Custom compile/run input shapes

/lasso:compile and /lasso:run accept four input forms:

1. Bundled workflow request JSON — { "workflow": "patch-validation", "input": {...} }
2. Raw HarnessSpec JSON — the full spec
3. Envelope with spec or specPath — { "spec": {...}, "input": {...} } or { "specPath": "/path/to/spec.json" }
4. Direct path — /tmp/custom-spec.json

---

Bundled workflows

Both operate entirely against a local repository or worktree.

patch-validation

Validates a candidate fix against a known-bad baseline:

1. Check out baselineRef and run reproduceCommands to confirm the bug
2. Apply the candidate from candidateSource
3. Re-run reproduceCommands — expect them to pass
4. Run verificationCommands as a broader regression check
5. Optionally route to human approval

Terminal outcomes: validated-fix, not-reproduced, apply-failed, candidate-failed, rejected

pr-review-merge

Local rehearsal of a review-and-merge flow:

1. Inspect the repo
2. Run verification commands
3. Generate an LLM review summary
4. Route through human approval
5. Perform local merge
6. Re-run verification after merge

---

Request examples

patch-validation

{
  "workflow": "patch-validation",
  "input": {
    "repoPath": "/absolute/path/to/disposable-worktree",
    "baselineRef": "main",
    "candidateSource": { "kind": "patchFile", "value": "/path/to/fix.patch" },
    "reproduceCommands": ["npm test -- --grep 'the broken test'"],
    "verificationCommands": ["npm test"],
    "reviewInstructions": "Approve if the patch applies cleanly and verification passes.",
    "approvalRequired": false
  }
}

pr-review-merge

{
  "workflow": "pr-review-merge",
  "input": {
    "repoPath": "/absolute/path/to/disposable-worktree",
    "sourceBranch": "feature/pr-change",
    "targetBranch": "main",
    "reviewInstructions": "Approve only if verification passes and the diff looks safe.",
    "verificationCommands": ["node -e \"process.exit(0)\""]
  }
}

replan

{
  "workflow": "patch-validation",
  "originalRequest": {
    "workflow": "patch-validation",
    "input": { "..." : "..." }
  },
  "observedOutcome": {
    "terminalNodeId": "validated-fix",
    "notes": ["prod hotfix"]
  }
}

For aborted attempts: { "aborted": true, "abortReason": "retry-exhaustion" }

Custom HarnessSpec compile

{
  "name": "custom-echo",
  "graph": {
    "entryNodeId": "echo",
    "nodes": [
      { "id": "echo", "kind": "tool", "tool": "bash", "args": ["-lc", "echo hello"] }
    ],
    "edges": []
  }
}

---

Custom workflows

Use /lasso:compile and /lasso:run with any HarnessSpec, or use Lasso as a library:

import { validateHarnessSpec, lowerHarnessSpecToCir, compileHarnessSpec } from "lasso";

validateHarnessSpec(spec);       // structural validation
lowerHarnessSpecToCir(spec);     // inspect lowered IR
compileHarnessSpec(spec);        // produce replay-safe workflow

Arbitrary workflow families are supported. The planner accepts custom families via skill markdown with an explicit workflow name.

---

HarnessSpec reference

Canonical sources: src/spec/types.ts, src/spec/schema.ts, src/spec/validate.ts

Top-level shape

{
  "name": "workflow-name",
  "graph": { "entryNodeId": "start", "nodes": [], "edges": [] },
  "executionPolicy": {},
  "humanPolicy": {},
  "observabilityPolicy": {}
}

Field	Required	Type	Notes
name	Yes	string	Unique workflow name
graph	Yes	object	Contains entryNodeId, nodes, edges
executionPolicy	No	object	Global execution settings
humanPolicy	No	object	Human interaction defaults
observabilityPolicy	No	object	Trace / metrics / logging

All top-level objects are strict. Unknown fields are rejected.

Node kinds

Kind	Key fields	Maps to
tool	tool, args, env, cwd	ctx.pi.tool()
llm	provider, model, prompt, system	ctx.pi.llm()
human	prompt, interactionType, options	ctx.waitForEvent()
condition	condition, thenNodeId, elseNodeId	Branch evaluation
merge	waitFor, strategy	Fork-join synchronization
subworkflow	specRef, inputs	ctx.scheduleSubOrchestration()

Per-node fields (available on all node kinds via BaseNode):

Field	Type	Notes
guardrails	NodeGuardrails	Per-node limits (timeout, retries, cost, constraints)
verificationHooks	VerificationHook[]	Inline checks that run after this node completes

Validation rules

1. Node IDs must be unique
2. entryNodeId must exist
3. Every edge from/to must reference an existing node
4. condition.thenNodeId and condition.elseNodeId must exist
5. merge.waitFor must not be empty
6. human nodes with interactionType: "choice" must have options
7. Unreachable nodes are rejected
8. retryPolicy only on tool, llm, subworkflow
9. Verification rules cannot reference missing nodes
10. Circular verification dependencies are rejected

---

Library API

Compiler

import { compileHarnessSpec, type CompiledHarnessWorkflow } from "lasso";

const compiled = compileHarnessSpec(spec);
// compiled.name, compiled.spec, compiled.cir, compiled.optimizations
// compiled.register(pi) — registers with pi-duroxide

Pipeline: validate → lower → optimize → validate CIR → build generator.

Compiler feedback

Analyzes compiled workflows and emits executable mutations (not just advisory suggestions):

import { analyzeCompiledWorkflow, mutateHarness } from "lasso";

const analysis = analyzeCompiledWorkflow(compiled);
// analysis.cost — LLM calls, duration, USD estimate
// analysis.risk — cost, failure, quality, complexity
// analysis.mutations — executable HarnessMutation[] with triggers

// Apply mutations directly
const { spec: improvedSpec } = mutateHarness(spec, analysis.mutations);

Each mutation carries a trigger (why it was emitted) and description (human-readable reason):

Trigger	Mutation	Effect
cost_high	replace-node	Swap expensive model for cheaper one
retry_exhausted	modify-node	Add retry policy with exponential backoff
verification_failed	add-verification	Add verification hook
loop_detected	modify-node	Flag adjacent nodes for merge

Guardrails

Enforce execution limits at runtime. The compiler stops execution when limits are exceeded, throwing a GuardrailExceededError with a descriptive message.

{
  "name": "limited-workflow",
  "executionPolicy": {
    "maxSteps": 25,
    "costLimitUsd": 0.25,
    "timeout": 300000
  },
  "graph": { "..." : "..." }
}

Field	Type	Enforcement
maxSteps	number (positive integer)	Stops after N node executions
costLimitUsd	number (positive)	Stops when estimated LLM cost exceeds limit
timeout	number (ms)	Stops after wall-clock time

Step count resets on continueAsNew (adaptive evolution). Cost accumulates across versions.

Failure mode generation

Before execution, Lasso generates plausible failure modes from the task description and environment. This answers "Where am I likely to fail?" before acting.

import { generateFailureModes } from "lasso";

const generation = generateFailureModes("Deploy my app to staging", env);
// generation.failureModes — array of FailureMode
// generation.riskSummary — "HIGH RISK: auth failures likely (env constraint detected)"

Task keyword	Generated failure modes
deploy	auth expiry, network timeout, config drift
test	flaky tests, timeout, environment mismatch
build	dependency failure, disk full, OOM
merge	conflict, verification failure
database	connection timeout, migration failure
api	rate limit, auth expiry, schema mismatch
file	permission denied, disk full, path not found

Failure modes are cross-referenced with environment constraints: if auth constraint detected, auth failure probability is boosted. Each mode includes triggers, mitigations, and recovery actions.

generateFailureModes() now returns risks: Risk[] alongside failureModes, converting each failure mode into a quantified risk with probability, impact, and score.

Risk assessment

First-class Risk type with quantitative scoring. Each risk carries probability (0-1), impact (0-1), and a composite score. assessRisks() filters by threshold and returns a structured assessment.

import { generateFailureModes, assessRisks } from "lasso";

const generation = generateFailureModes("Deploy my app to staging", env);
// generation.risks — Risk[] converted from failure modes

const assessment = assessRisks(generation.risks);
// assessment.overallScore — average risk score (0-1)
// assessment.risksAboveThreshold — risks scoring >= highRiskThreshold (default 0.7)
// assessment.highRiskThreshold — the threshold used

// Custom threshold
const strict = assessRisks(generation.risks, { highRiskThreshold: 0.5 });

Risk interface:

Field	Type	Description
id	string	Unique risk identifier
probability	number (0-1)	Likelihood of occurrence
impact	number (0-1)	Severity if it occurs
score	number	probability × impact
signals	string[]	Triggers or indicators
mitigations	HarnessMutation[]	Suggested mitigations as executable mutations
failureClass	FailureClass	Classification (auth, tool, network, etc.)
description	string	Human-readable description

Per-node harnesses

Every node in a HarnessSpec can carry its own guardrails and verification hooks. These override global settings and run only during that node's execution.

{
  "id": "deploy",
  "kind": "tool",
  "tool": "bash",
  "args": ["./deploy.sh"],
  "guardrails": {
    "timeoutSeconds": 120,
    "maxRetries": 2,
    "maxCostUsd": 0.10,
    "constraints": ["exit_code == 0"]
  },
  "verificationHooks": [
    {
      "name": "health-check",
      "kind": "tool",
      "check": "curl -sf http://localhost:3000/health",
      "onFail": "block",
      "maxAttempts": 3
    }
  ]
}

NodeGuardrails:

Field	Type	Description
timeoutSeconds	number	Max execution time for this node
maxRetries	number	Max retries (overrides global retryPolicy)
maxCostUsd	number	Max LLM cost for this node
constraints	string[]	Custom expressions that must hold true

VerificationHook:

Field	Type	Description
name	string	Hook identifier
kind	"tool" | "llm" | "expression"	Type of check
check	string	Tool name, LLM prompt, or expression
onFail	"block" | "warn" | "retry"	Action on failure
maxAttempts	number	Max verification attempts (optional)

Per-node guardrails override global executionPolicy settings. Verification hooks run inline after the node completes, with retry/block/warn semantics.

Trace-based synthesis

synthesizeFromTrace() analyzes an execution trace mid-flight, classifies failures, and derives mutations — wired into the compiler's adaptation loop.

import { DefaultMetaHarness } from "lasso";

const meta = new DefaultMetaHarness(config);

const trace = {
  completedNodes: [
    { nodeId: "build", startedAt: 1, completedAt: 2, costUsd: 0.05 },
  ],
  failedNodes: [
    { nodeId: "deploy", startedAt: 2, failedAt: 3, error: "auth expired", failureClass: "auth", retryCount: 3 },
  ],
  totalCostUsd: 0.15,
  capturedAt: Date.now(),
};

const result = await meta.synthesizeFromTrace(trace, currentSpec, environment);
// result.mutations — HarnessMutation[] derived from trace analysis
// result.spec — mutated HarnessSpec
// result.rationale — human-readable explanation of changes
// result.decision — "continue" | "needs_operator_input" | "stop"

The synthesis classifies:

• Repeated failures — same node failing across retries → add verification or block
• Slow nodes — duration spikes → tighten timeout guardrails
• Cost spikes — LLM cost above expected → swap to cheaper model

This feeds directly into the continueAsNew path, producing a new harness version with repairs applied.

Verification engine

Standalone module with compositional strategies:

import { runVerification } from "lasso/verification/engine";

// Strategies: "all-must-pass" (default), "first-pass", "any-block"
const report = yield* runVerification(nodeId, hooks, nodeMap, state, ctx, "first-pass");
// report.overallStatus — "pass" | "warn" | "block"
// report.hookResults — per-hook outcome + duration

Compiler optimizations

Three passes between lowering and CIR validation:

1. Dead-node elimination — removes unreachable nodes
2. Single-branch merge elision — simplifies single-branch merges
3. Tool-node fusion — merges adjacent bash/sh nodes

import { optimizeCirWorkflow } from "lasso/cir/optimize";

const { optimized, passes } = optimizeCirWorkflow(cir);
// passes — ["dead-node-elimination", "merge-elision", "tool-fusion"]

Harness mutations

Structural spec modifications from execution traces or compiler feedback:

import { deriveMutationsFromTrace, deriveMutationsFromFailure, mutateHarness } from "lasso";

// From execution trace
const mutations = deriveMutationsFromTrace(trace, spec);

// From classified failure
const mutations = deriveMutationsFromFailure(signature, spec, { nodeId: "deploy" });

// Apply
const { spec: newSpec, diff } = mutateHarness(spec, mutations);

Mutation types: add-node, remove-node, modify-node, add-edge, toggle-approval, add-verification, replace-node, tighten-guardrail

Triggers: node_failed, confidence_low, cost_high, loop_detected, retry_exhausted, verification_failed, tool_missing, auth_expired

Adaptive runtime

Reference workflows get automatic version evolution:

import { prepareRuntimeReplan, MAX_ADAPTIVE_VERSIONS } from "lasso";

const decision = await prepareRuntimeReplan(metadata, input, result);
// decision.type — "continue_as_new" | "needs_operator_input" | "stop"

Capped at 5 versions (MAX_ADAPTIVE_VERSIONS). Each version records a HarnessVersion with full lineage.

Lineage persistence

import { FileLineageStore } from "lasso";

const store = new FileLineageStore("/path/to/store");
await store.saveVersion(version);
await store.saveLineage(entry);

const chain = await store.getLineageChain(3);
const recent = await store.queryLineage({ terminalNodeId: "validated-fix", limit: 10 });

Harness memory

Tracks patterns across sessions:

import { FileMemoryStore, adviseFromMemory } from "lasso";

const store = new FileMemoryStore("/path/to/memory");
const advice = await adviseFromMemory("deploy-staging", store);
// advice.suggestions — "Previously, auth-check-before-deploy improved success rate"
// advice.warnings — "Pattern deploy-without-auth failed 6 times"

Environment model

Discovers execution environment before generating a harness:

import { discoverEnvironment, analyzeEnvironment } from "lasso";

const env = await discoverEnvironment("/path/to/repo");
// env.tools — bash, git, node, etc.
// env.constraints — auth, network, rate-limit
// env.repoState — branch, uncommitted changes, remotes

const analysis = analyzeEnvironment(env, ["git", "node"]);
// analysis.readinessScore — 0-100
// analysis.preparatorySteps — actionable prep steps

Failure ontology

7 failure classes with evidence and recovery:

import { classifyFailure, suggestRecovery } from "lasso";

const signature = classifyFailure(error, { nodeId: "deploy" });
// signature.class — "auth" | "tool" | "resource" | "semantic" | "human" | "environment-drift" | "network" | "unknown"
// signature.confidence — 0-1
// signature.suggestedRecovery — actionable steps

const recovery = suggestRecovery(signature);

Capabilities

Dynamic graph generation from required tools:

import { DefaultCapabilityRegistry, planWorkflowRequest } from "lasso";

const registry = new DefaultCapabilityRegistry();
// Pre-registered: bash, git, node, llm-review, human-approval

const result = planWorkflowRequest(brief, registry);

Meta-harness

Full generation pipeline — discover, predict, synthesize, compile:

import { DefaultMetaHarness, DefaultCapabilityRegistry, FileMemoryStore } from "lasso";

const meta = new DefaultMetaHarness({
  capabilityRegistry: new DefaultCapabilityRegistry(),
  memoryStore: new FileMemoryStore("/path/to/memory"),
});

const result = await meta.generateHarness("Deploy my app to staging");
// result.spec — generated HarnessSpec
// result.environmentAnalysis — tool/resource availability
// result.predictedFailures — anticipated failures with confidence
// result.compilerAnalysis — cost, risk, mutations
// result.readinessScore — 0-100
// result.appliedMutations — what was changed

Multi-harness composition

// Sequential chain
const chained = meta.composeHarnesses([
  { name: "research", spec: researchSpec },
  { name: "plan", spec: planSpec },
  { name: "execute", spec: executeSpec },
]);

// Parallel execution
const parallel = meta.composeParallel([verificationSpec, notificationSpec]);

// Conditional branching
const conditional = meta.composeConditional("isProduction", prodSpec, stagingSpec);

Node IDs are prefixed with stage names to avoid collisions.

---

How Lasso fits with pi-duroxide

Lasso is distributed as a pi extension (package.json has a "pi" field pointing to ./src/index.ts). When you pi install it:

1. pi loads src/index.ts, which exports a default extension function
2. That function (src/pi/extension.ts) first boots pi-duroxide
3. Then it registers the 5 slash commands with pi's ExtensionAPI

The layering:

• pi-duroxide owns workflow lifecycle, replay, timers, events, and runtime registration
• Lasso owns spec validation, CIR lowering, optimization, compilation, and operator-facing commands

In other words: pi-duroxide is the durable runtime engine; Lasso is the harness generation, optimization, and adaptation layer built on top of it.

Non-goals

Lasso does not currently aim to provide:

• live GitHub or gh integration
• autonomous code authoring or patch generation
• LLM-backed planning or replanning (all planning is deterministic)
• automatic compile/run behavior from /lasso:plan or /lasso:replan
• arbitrary generated TypeScript