🧵 Weft

An experimental hobby project — stitching together a few small services into a personal agent cluster. Not production-grade. Not battle-tested. Just tinkering.

MosaicDB (memory) + Zypi (runtime) + FlowEngine (logic) + YAS-MCP (connectors), coordinated through a ribbon ndjson event log.

---

Stack

Layer	Submodule	Role	Lang	Port
Memory	MosaicDB	Semantic search, property graph, RAG, agent memory, MCP server	Elixir	4040
Runtime	Zypi	Firecracker microVM sandbox, sessions, image warm, guest agent	Elixir + Go	4000
Logic	FlowEngine	DAG workflow engine, retry/backoff, WebSocket streaming, Python SDK	Rust	3000
Connectors	YAS-MCP	OpenAPI→MCP bridge, A2A protocol, OIDC, circuit breakers, 10 connector specs	Rust	3001
Coordination	Ribbon	ndjson event log, state machine, agent self-discovery, git verification	Rust	—
Control Plane	Weft (this repo)	MCP server, agent loop orchestrator, circuit breakers, identity issuance, vault	Rust	8080

Architecture

flowchart TB
    dirge["dirge / pi<br/>MCP client"]

    subgraph weft["Weft Control Plane :8080"]
        cb["Circuit Breakers"]
        fan["Fanout"]
        orch["Agent Orchestrator<br/>plan→exec→observe→learn"]
        vault["Vault<br/>OS keyring"]
        id["Identity<br/>WIMSE JWTs"]
    end

    subgraph services["Services"]
        mosaic["MosaicDB :4040<br/>Graph · Vector · RAG<br/>19 MCP tools"]
        zypi["Zypi :4000<br/>Firecracker μVMs<br/>Sessions · Agent"]
        flow["FlowEngine :3000<br/>DAG executor<br/>Retry · Streaming"]
        yasmcp["YAS-MCP :3001<br/>OpenAPI→MCP bridge<br/>10 connectors · A2A"]
    end

    ribbon["Ribbon<br/>ndjson event log<br/>State machine · Git verify"]

    dirge -->|MCP JSON-RPC| weft
    weft --> mosaic
    weft --> zypi
    weft --> flow
    weft --> yasmcp
    flow --> ribbon

Loading

Quick Start

git clone --recurse-submodules https://github.com/allen-munsch/weft.git
cd weft

# Build the ribbon binary (agent communication tool)
cargo build --release -p ribbon

# Start all services
make up

# Check cluster health
make status

# Run smoke test
make smoke-test

Connect dirge or pi

Weft is the sole MCP endpoint — dirge or pi connects here for all tools:

{
  "mcpServers": {
    "weft": {
      "command": "curl",
      "args": ["-X", "POST", "http://localhost:8080/mcp"],
      "transport": "http"
    }
  }
}

MCP Tools (~35 tools)

Agent Orchestration

Tool	Description
weft_agent_run	Full agent loop: plan → execute → observe → learn
weft_agent_status	Check result of an agent run
weft_workflow_run	Execute a FlowEngine DAG workflow
weft_sandbox_exec	One-shot Firecracker sandbox exec
weft_sandbox_session	Long-lived sandbox session
weft_session_exec	Execute in existing session
weft_warm_sandbox	Pre-warm VMs across all Zypi nodes

Memory (proxied to MosaicDB)

Tool	Description
weft_memory_search	Semantic search across knowledge graph
weft_memo_search	Full-text search across stored memos
weft_memory_store	Persistent storage with handles
weft_memory_graph	Property graph traversal
mosaic_traverse	Recursive CTE graph traversal
mosaic_analytics	DuckDB SQL across federated shards
mosaic_graph_report	Graph analysis — hubs, bridges, communities

Ribbon — Agent Communication

Tool	Description
weft_ribbon_status	Show all agent states from ndjson log
weft_ribbon_query	Filter events by agent, type, task, timestamp
weft_ribbon_send	Append event with state machine validation + breadcrumbs
weft_ribbon_render	Generate markdown/compact summaries
weft_ribbon_verify	Check commit hashes against git origins
weft_ribbon_whoami	Discover agent identity from scope.toml
weft_ribbon_scope	Show owned paths and services for any agent

Vault & Permissions

Tool	Description
weft_vault_store	Store credential in OS keyring
weft_vault_list	List stored credential labels
weft_vault_token	Get OAuth2 token for a connector
weft_vault_export	Export credentials as env vars
weft_vault_grant	Grant permission scope to agent
weft_vault_revoke	Revoke permission scope
weft_audit_log	Query agent action audit log
weft_undo	Reverse a prior agent action
weft_export	Export audit log, rules, memory

Browser & Chart

Tool	Description
weft_browse	Fetch URL from sandbox, extract text/links
weft_browser_start	Start headless Chromium session
weft_browser_navigate	Navigate to URL in browser session
weft_browser_extract	Extract DOM/text/screenshot
weft_browser_stop	Stop browser session
weft_chart	Render data as HTML chart

Rules

Tool	Description
weft_rules_parse	Parse WHEN/THEN rule → structured JSON
weft_rules_compile	Compile rule → FlowEngine DAG

Operations

Tool	Description
weft_health	Cluster-wide health + circuit status
weft_config	Show cluster topology and config
weft_circuit_status	Per-service circuit breaker state
weft_mcp_status	List YAS-MCP connector tools
weft_mcp_onboard	Register new OpenAPI spec
weft_mcp_offboard	Remove registered spec

Agent Coordination (Ribbon)

Agents communicate through shared/events.ndjson — an append-only ndjson log with a hardcoded state machine.

# Agent boot sequence:
ribbon whoami                          # discover your identity
ribbon query --agent {me} --event submitted  # find your tasks
ribbon send --agent {me} working --task "..."  # claim a task

# Full task lifecycle:
submitted → working → committed → completed

The ribbon binary (submodules/ribbon, v0.3.0+) enforces valid transitions with breadcrumb hints. See shared/AGENT-CONVENTIONS.md for the full protocol.

Agent Loop

1. dirge sends:     "find urgent emails from the last 3 days"
2. Weft recalls: MosaicDB search for prior context
3. Weft plans:   LLM (or template) → FlowEngine DAG JSON
4. FlowEngine:   Executes DAG with zypi.exec nodes (parallel, retry, streaming)
5. Weft observes: Stores results + eval metrics in MosaicDB
6. Weft learns:   Records findings as structured semantic memory
7. dirge receives:   Handle stubs → expandable to full results

WIMSE Workload Identity

The weft-identity crate implements IETF WIMSE workload identity patterns:

• Platform JWTs — short-lived identity tokens instead of raw OAuth tokens in sandboxes
• Audience scoping — separate credentials for platform access vs. external federation
• Delegation chains — full provenance tracking across multi-agent hops
• Autonomy levels — distinguishes user-delegated from agent-autonomous actions

Status: crate built and tested (15 tests), integration into agent loop pending.

Design Principles

1. Thin orchestrator. MosaicDB, Zypi, FlowEngine, YAS-MCP do the actual work. Weft composes them.
2. Circuit breakers on every backend. Each service fails independently. Weft degrades gracefully.
3. All state in MosaicDB. No in-memory agent state. Errors stored as learnable memory.
4. Sandbox everything. User code runs in Firecracker microVMs, never on the host.
5. Single MCP endpoint. Dirge talks to Weft. Weft proxies to submodules internally.
6. Ribbon for coordination. Agents communicate through a versioned ndjson event log with state machine validation.

Development

cargo build                          # Build workspace
cargo build --release -p ribbon        # Build ribbon binary
cargo test                           # Run all tests
RUST_LOG=weft=debug cargo run        # Run control plane

make up                              # Start cluster
make down                            # Stop cluster
make smoke-test                      # Full cluster exercise
make status                          # Cluster health

Configuration

Variable	Default	Description
WEFT_BIND	0.0.0.0:8080	Control plane bind address
MOSAIC_URL	http://localhost:4040	MosaicDB base URL
ZYPI_URL	http://localhost:4000	Zypi base URL
ZYPI_NODES	(empty)	Comma-separated Zypi node URLs
FLOWENGINE_URL	http://localhost:3000	FlowEngine base URL
YAS_MCP_URL	http://yas-mcp:3001	YAS-MCP base URL
ZYPI_DEFAULT_IMAGE	ubuntu:24.04	Default sandbox image
WEFT_BELT_BINARY	target/release/belt	Path to ribbon binary

Submodules

Submodule	Remote
submodules/mosaic	git@github.com:allen-munsch/mosaic.git
submodules/zypi	git@github.com:allen-munsch/zypi.git
submodules/flowengine	git@github.com:allen-munsch/flowengine.git
submodules/yas-mcp	git@github.com:allen-munsch/yas-mcp.git
submodules/ribbon	git@github.com:allen-munsch/ribbon.git

git submodule update --init --recursive

GNU Affero General Public License v3.0 only

License

AGPL-3.0-only