tuvl 2.0.0b8

  tuvl
_{/ˈtuːvəl/  ·  തൂവൽ  ·  feather}

Typed workflows of agents — code, database/HTTP/MCP tools, rules, models,
bounded tool loops and people — on a durable, journaled runtime,
built spec-first and served as REST, SSE and MCP.

Website  ·  Docs  ·  GitHub

tuvl 2.0 is a redesign with no 1.x compatibility layer — see the CHANGELOG. Versions follow SemVer.

A tuvl workflow is a graph of agents. Each agent has a typed contract — inputs, outputs, the signals it emits — and an engine that implements it:

Signals route to the next agent or a named end. tuvl lint project checks contracts, data flow, types and policy statically and prints each workflow's determinism profile and worst-case token cost. Every run is durable and journaled: it survives restarts, waits for people, can be paused, stepped and steered, and can be pinned and replayed as a zero-token test fixture.

kind: Workflow
version: tuvl/v2
metadata: { name: refund_flow, description: Handle a refund request }
spec:
  models: [Order, Refund]
  trigger:
    http: { path: /api/refunds, method: POST }
    input: { order_id: uuid, reason: str }
  agents:
    - id: load_order
      description: Load the order
      engine: tool
      inputs: { order_id: uuid }
      outputs: { order: Order }
      tool: { use: db, model: Order, op: read, where: { id: "{{ order_id }}" } }
      routes: { default: triage, not_found: END.missing, error: END.failed }
    - id: triage
      description: Decide how the refund is handled
      engine: decide
      inputs: { order: Order, reason: str }
      outputs: { lane: "enum[auto, review]" }
      decide:
        rules:
          - { when: "order.total > 500", then: review }
          - { when: "true", then: auto }
      routes: { auto: issue_refund, review: approval, error: END.failed }
    # … issue_refund (code), approval (human)
  outputs:
    default: { status: 200, body: { refund_id: "{{ refund.id }}" } }
    missing: { status: 404, body: { error: unknown order } }
    failed:  { status: 500, rollback: true, body: { error: refund failed } }

Install

uv tool install "tuvl[standard]"     # CLI + Insight (dev UI)
# or, in a project
uv add "tuvl[standard]"

tuvl alone is the production server; [standard] adds Insight, served only in dev mode, and the development tools (tuvl generate code, tuvl run tests, tuvl serve mcp). Features with their own packages are extras: tuvl[mcp], tuvl[redis], tuvl[vector], tuvl[otel-grpc]. tuvl ship installs only the ones a project uses.

Quick start

tuvl init demo --sample --preset gemini -y     # a ticket-triage project with a spec, tests and a lock
cd demo
tuvl lint project --strict                         # contracts, data flow, cost
tuvl run tests                                      # offline tests
tuvl dev --auto-login                          # Insight at http://localhost:8885/insight

Spec-driven

tuvl create spec refund-automation      # write the intent (Markdown, with checked Data and Flows)
tuvl lint spec                      # is the spec complete and consistent? (zero tokens)
tuvl verify spec                     # does the implementation match it, step by step?
tuvl list tasks                     # task statuses, derived — never typed in
tuvl generate code                         # schemas, code stubs, tests (no model)

The coding agent builds; tuvl referees. Every step above is deterministic and spends no tokens. Coding agents get the same operations over MCP (tuvl serve mcp) and a skill set in .agents/skills/.

The CI gate:

tuvl lint project --strict && tuvl generate code --check && tuvl verify lock && tuvl run tests && tuvl list tasks --strict

Authoring with your coding agent

Already have Claude Code, Codex or Gemini CLI? tuvl can drive it from an idea to a packaged project, and accept only what its own checks (no model in the loop) pass:

tuvl import idea brief.pdf           # IDEA-SK-0004: a numbered, immutable copy of the brief
tuvl generate spec --idea IDEA-SK-0004    # your agent drafts SPEC-SK-0004-01 on a branch; a person approves it
tuvl approve spec SPEC-SK-0004-01 && tuvl generate tasks SPEC-SK-0004-01
tuvl generate code --spec SPEC-SK-0004-01 --all   # models and skeletons first, then your agent, one PR per task
tuvl review code && tuvl ship --format both      # gate, image and a runnable archive

tuvl dev shows the same path in a terminal UI, and every step is in a local audit ledger. Details: docs/authoring.md.

Surfaces

• REST + SSE: each workflow's route, POST /api/workflows/{name}/runs, runs, journal events, approvals, operator control; OpenAPI generated from the contracts.
• MCP export: trigger.mcp.enabled lists a workflow as a tool on /mcp.
• TypeScript: @tuvl/client with npx tuvl-client generate for typed inputs and outputs.
• Insight: specs and task board, workflow canvas, runs with breakpoints, step mode and approvals, change-engine checks against pinned fixtures, judge calibration.

Production

tuvl generate lock && tuvl ship --tag registry/app:1.0    # gates, Dockerfile (pinned tuvl + only the extras you use), Helm chart
tuvl serve app --role api        # or: worker — scale HTTP and execution separately

Ed25519-signed JWT auth, default-deny triggers, scoped CRUD, approvals with no self-approval, secure fields kept away from models, optional Postgres row-level multi-tenancy.

Documentation

tuvl.dev · in this repository: agentic manual, runtime, engines, decide, loop and tools, judges, storage, models, spec-driven, Insight, API, CLI, security, observability.

License & contributing

tuvl is licensed under the Apache License, Version 2.0 — see LICENSE and NOTICE. It is free to use, modify and distribute, with an express patent grant. The name "tuvl" and the logos are not licensed for use as a brand (Apache-2.0 §6).

Releases up to and including 2.0.0b4 were published under the MIT License and remain available under it. Starting with 2.0.0b5 tuvl is Apache-2.0; see the changelog.

Development currently happens in a private repository, so the full source is not yet publicly browsable. This is temporary: the complete codebase will be published openly in a future release. In the meantime the project is open to contribution — bug reports, feature proposals, and patches are all welcome. See CONTRIBUTING to get started, or reach out at developer@tuvl.io.