Tahyi

How it Works

Tahyi turns infrastructure work into a traced, gated execution loop. A specialist agent wakes on a trigger, plans under policy, classifies each action as a two-way or one-way door, executes (or waits for approval), and hands off to peers through the coordination layer.

This page walks through that loop end to end. For vocabulary, see Core Concepts.

Overview

Trigger → Wake → Plan → Classify → Execute / Gate → Log → Handoff

Every step produces audit entries. Nothing runs silently.

1. Triggers

Work enters the swarm through one of three paths:

TriggerSourceExample
HeartbeatScheduled wakeDeployment agent checks for pending rollouts every 15 minutes
Webhook / alertExternal signalMonitoring agent wakes on a firing SLO alert
Human assignmentDashboard or CLIOperator assigns a migration review to the DBA specialist

The coordination layer creates a task for each trigger — bounded scope, explicit owner, inspectable thread.

2. Planning

On wake, the specialist receives context from the coordination layer:

  • Registered environment state (cluster, namespace, account)
  • Active policy rules (dry-run default, approval requirements)
  • Recent audit history for the same environment
  • Open tasks and pending handoffs

The agent builds an action plan — a ordered list of tool calls with rationale. Plans are written to the audit log before any tool executes.

Pre-0.1 builds default to dry-run: the plan is visible, but infrastructure is not touched until approved.

3. Safety classification

Each planned action is classified before execution:

Door typeTestRouting
Two-wayCan this be reversed without data loss or downtime?Execute autonomously within policy
One-wayIs this irreversible or high blast radius?Pause at approval gate

Examples:

  • Two-way: Scale a deployment replica count, restart a pod, toggle a feature flag with rollback path
  • One-way: DROP TABLE, delete a production bucket, rotate credentials that invalidate live sessions

Classification is explicit in the plan — not inferred after the fact. If an action cannot name its guardrail (dry-run, approval, reversibility proof, blast-radius cap), it does not ship.

4. Execution

Once classified:

  1. Two-way actions run immediately. Outcomes are logged with before/after state.
  2. One-way actions enter a safety gate. The agent stops, writes the plan to the audit log, and waits for human approval via the dashboard or CLI.
  3. Dry-run mode (default on early builds) simulates tool calls — full plan trace, zero side effects.
# Approve a gated plan from the CLI
npx tahyi plan approve <plan-id> --environment staging

Rejected plans are logged with the reason. The specialist may revise and resubmit.

5. Handoffs

When one specialist finishes but the work spans domains, the coordination layer routes a handoff:

Monitoring agent detects alert
  → plans initial triage (two-way)
  → hands off to Observability agent for log correlation
  → Observability finds root cause
  → hands off to Deployment agent for rollback

Handoffs are explicit tasks — not implicit context passed in chat. Each hop has its own audit trail.

6. Audit and replay

Every step produces append-only audit entries:

FieldRecorded
WhatTool call, API request, resource affected
WhyTask ID, trigger type, policy rule
HowPlan ID, classification, dry-run flag
WhoSpecialist name, environment, approver (if gated)
OutcomeSuccess, failure, rollback, rejection

You can replay an incident timeline from the audit log without reconstructing it from agent chat history.

Multi-agent coordination (0.2+)

Pre-0.1 runs a single specialist end to end. From 0.2 onward, multiple specialists share the coordination layer:

  • Tasks route to the right domain owner automatically
  • Context propagates across handoffs
  • Safety gates apply swarm-wide — a one-way door in any specialist requires approval

See Core Concepts — Release trajectory for the version roadmap.