Yawr cover image

Yawr

Active OpensourceGoTypeScriptVS Code ExtensionWorkflowsRunbooksGovernanceReact Flow
GitHub

Overview

Yawr (Yet Another Workflow Runtime) is an open-source workflow and operational runbook runtime engineered in Go, paired with a rich VS Code extension built with TypeScript and React Flow. It provides a deterministic platform for defining, executing, and auditing multi-step operations with rigorous governance enforcement, append-only evidence capture, and graph-level interactive debugging.

Structured as a monorepo (runtime/ for the Go engine and CLI; apps/vscode/ for the editor extension), Yawr treats workflow semantics as the strict authority of the runtime. The editor extension never re-implements workflow logic or schemas; instead, it projects runtime-owned execution states over a bidirectional streaming JSON-lines protocol (yawr.stdio/v1) and JSON-RPC 2.0 interfaces.

Key Capabilities

  • Executable Runbooks — Define complex operational procedures in structured YAML (.runbook.yaml / .yawr). Supports branching, conditional logic, loops, joins, nested static/dynamic includes, and automated compensation triggers.
  • Runtime Governance & Safety Gates — Enforce command allowlists and denylists, scrub prohibited environment variables before dispatch, redact sensitive output patterns, and require multi-operator approval quorums at critical steps.
  • Append-Only Evidence & Auditability — Preserves complete execution integrity via append-oriented JSONL trace files, per-step state checkpoints, SHA256 hashed attachments, and typed durable Results that survive interruptions and allow deterministic resumption.
  • Contract-Identical Tool Bindings — Uniformly abstract tool integrations across multiple transports (local native binaries, MCP stdio subprocesses, MCP HTTP endpoints, and Windows AppContainer isolated file-only transports). Tool definitions enforce identical action names, schemas, classifications, and governance rules across testing and production.
  • Interactive React Flow Graph Canvas — Visualizes live workflow topology and execution flow directly inside VS Code. Configurable step pacing (minimumStepDisplayMs), execution lanes, and persistent graph history give operators clear visibility into active runs.
  • Visual Runbook Debugger — Set before and after breakpoints on graph nodes, step into or over static includes, evaluate read-only GXL watches, and inspect actual vs. effective variable overrides tracked with audit markers (DBG).

Core Architecture

Yawr isolates workflow responsibilities into four distinct layers:

1. Admission & Planning

The parser validates runbook syntax and enforces semantic relationships beyond schema capabilities. Package and tool catalogs resolve declared references (requires:, toolRefs:). Planning serves as a trust boundary: dynamic includes resolve identities exclusively through approved catalogs, preventing arbitrary filesystem access.

2. Execution Engine

The Go engine governs control flow, step progression, retries, output captures, and terminal outcomes. Discrete executors handle commands, tool dispatch, and operator interactions without mutating presentation state. A single active writer owns each durable run, protected by lease and epoch checks to eliminate concurrent state corruption.

3. Integration & Protocols

  • CLI Commands: Direct execution via yawr run, non-dispatching dry-runs via yawr dry-run, run history inspection (yawr ls), and garbage collection (yawr gc).
  • Editor Stdio Transport (yawr.stdio/v1): Reserves stdin/stdout for streaming JSON-lines events, interactive prompts, host actions, and cancellations without requiring HTTP servers or SSE daemons.
  • JSON-RPC 2.0 Server (yawr serve): Long-lived background daemon mode for IDE and automation integrations.
  • Host Action Protocol: Runbooks can request logical host capabilities (such as external-view.open), which the trusted editor host statically maps to allowlisted operations.

4. Presentation & Editor Projections

The VS Code extension renders real-time execution graphs using React Flow and provides an Operator Inspector with three dedicated tabs:

  • Definition: Renders authored parameters, tool bindings, CLI command policies, branch conditions, approval quorums, and compensation rules.
  • Run: Shows live execution telemetry, step attempt counts, elapsed timing, captured variables, process stdout/stderr, and evidence hashes.
  • Debug: Manages graph breakpoints, watches, and effective value overrides.

Example Runbook

Below is an example operational triage runbook demonstrating tool calls, output captures, approval gates, and published results:

apiVersion: yawr.runbook/v1
id: incident-triage
name: Incident Triage & Mitigation
kind: mitigation
description: Verify connectivity, acquire approval, and trigger automated service recovery

toolRefs:
  - name: ping
    path: ../tools/ping.tool.yaml
  - name: rollout
    path: ../tools/rollout.tool.yaml

vars:
  target_host: api.internal.local
  cluster_id: prod-east-01

flow:
  - step:
      id: check_latency
      type: tool
      title: Check host reachability
      tool:
        name: ping
        action: check
        args:
          host: "${target_host}"
          count: "3"
      capture:
        ping_latency: stdout

  - step:
      id: approval_gate
      type: gate
      title: Operator Quorum Approval
      governance:
        requires_approval: true
        allowed_roles: ["sre-oncall", "infrastructure-lead"]
      prompt: |
        Ping latency check returned: ${ping_latency}
        Authorize rollout mitigation for cluster: ${cluster_id}?

  - step:
      id: apply_mitigation
      type: tool
      title: Trigger safe rollout
      tool:
        name: rollout
        action: restart
        args:
          cluster: "${cluster_id}"
      compensate:
        step: rollback_mitigation

  - step:
      id: finish
      type: end
      publish_results: true
      result:
        category: mitigated
        code: 200

Contract-Identical Tool Bindings

In production systems, tools often run through diverse transports: local scripts in testing, MCP (Model Context Protocol) subprocesses in developer environments, or authenticated remote HTTP microservices in production.

Yawr ensures contract identity across all transports:

apiVersion: yawr.tool/v1
name: query-service
version: "1.0"
transport:
  mode: mcp-stdio
  command: npx
  args: ["-y", "@company/query-mcp-server"]

governance:
  allowed-environments: ["staging", "production"]
  command-allowlist: ["SELECT *", "SHOW STATUS"]
  redact-patterns: ["(?i)bearer [a-z0-9-_]+", "(?i)password=[^&\\s]+"]

actions:
  - name: check_status
    description: Query cluster health indicators
    classification: read-only
    returns: json

Regardless of transport mode (native, mcp-stdio, mcp-http, or native-file-only), the logical action name, input/output schemas, classification (read-only, mutating, destructive), and governance policies remain invariant.

Tech Stack

  • Runtime & CLI: Go 1.25.7 (concurrency-safe, race-tested, zero external runtime dependencies)
  • Editor Extension: TypeScript, React, React Flow, VS Code Extension API
  • Tooling & Transports: Model Context Protocol (MCP), JSON-RPC 2.0, yawr.stdio/v1
  • Testing & Verification: Vitest, Go race-detector test suite, Fake-clock dwell tests, Chrome DevTools Protocol (CDP) webview observation
  • Packaging: Monorepo with npm workspaces and Go multi-module workspace (go.work)
Back to All Projects