sam 9d5040fd65 refactor: add internal/eventbus as the broker-neutral messaging contract
dependencies-and-contracts.md rule 1 says domains must not import
internal/infrastructure. internal/daemon and internal/agentexec both did,
and for exactly the thing the doc carves out: "internal/eventbus is an
approved shared application contract ... it MUST remain broker-neutral."

The Publisher/Consumer/Requester interfaces existed but lived inside the
NATS package, so a caller could depend on the behaviour yet still had to
import the implementation to name it. They now live in internal/eventbus,
and nats.Client asserts against eventbus.Bus.

The larger violation was ownership of meaning. The doc says "message schemas
stay with their owning domains; the event bus transports messages, it does
not own their meaning." The bus exported TaskEnvelope and a PublishTask
method, so the transport knew what a unit of work was, and it exported the
archie.agent.* subject helpers, so it also owned the agent protocol.

  - TaskEnvelope, its routing Kind, the label vocabulary and the task
    subjects move to internal/domain/workintake, which encodes and decodes
    its own bytes. This starts internal/domain/ per organisation.md.
  - The agent request/response/system subjects move to internal/agentexec,
    which defines what those messages mean.
  - internal/workflow keeps only the kind-to-registry mapping; the label
    table stays single and lives with the domain that reads forge issues.
  - The bus now carries opaque payloads on plain-string subjects.

Consumers declare the smallest interface they need rather than taking the
whole Bus: daemon.TaskBus is publish-unique/fetch/request, agentexec.
RequestBus is publish-request/reply-inbox, and archie-agent's stageBus is
fetch/respond. None can reach what it does not use.

Two defects this surfaced:

  - archie-agent declared its own JetStream stream with a second copy of the
    name, subjects, retention, dedup window, MaxDeliver and TTLs that
    nats.Connect already sets -- two definitions of one stream, free to
    diverge. Config now takes Subjects and FilterSubject from composition,
    which is what let the agent use the shared client and delete its
    hand-rolled setup.
  - Replying to a request needs core NATS, not the JetStream publish path:
    a reply inbox is ephemeral and belongs to no stream, so a durable
    publish to it fails. The old code hid this by using the raw connection.
    The contract now distinguishes Respond from Publish. The agentexec
    round-trip test caught it after I had made the same mistake in
    archie-agent.

Also translated the SDK's ErrNoResponders into eventbus.ErrNoResponders, so
the daemon's taskrun retry no longer imports the NATS SDK to name a
transient condition. The SDK is now confined to the nats package, the *rpc
packages (themselves NATS infrastructure), and cmd/*.

The agentexec test fake previously hand-rolled a JetStream consumer; it now
drains the client's own consumer, which is both closer to production and
avoids conflicting consumers on a work-queue stream.

Verified: go build, go vet, gofmt clean; full test suite passes.
2026-07-29 11:40:24 +10:00
2026-07-28 18:46:50 +10:00
2026-07-29 02:10:44 +10:00
2026-07-28 18:46:50 +10:00
2026-07-28 18:46:50 +10:00
2026-07-28 18:46:50 +10:00
2026-07-28 18:46:50 +10:00
2026-07-28 18:46:50 +10:00

Tau CLI Reference

Tau is a provider-agnostic coding agent with an interactive terminal UI. It provides an extensible, personalised environment for working with AI models, featuring an interactive TUI, an optional Web UI, session history, token tracking, and plugin integration.

Usage

tau [global flags] [command]

Running tau with no arguments starts an interactive chat session and also starts a local Web UI on 127.0.0.1. You do not need a --model flag; if no model is configured the session starts unselected and you pick one with /model.

Global Flags

Flag Description
--provider <name> Provider name to use (e.g. deepseek, openrouter). Env: TAU_PROVIDER
--model <id> Model ID to use. Also accepts provider:model-id or provider/model-id
--max-tokens <n> Maximum completion tokens per response
--temperature <f> Sampling temperature (0–2)
--resume, -r <id|latest> Resume a saved session by ID, or latest
--execute, -x <text> Execute mode: process prompt, print response, exit (reads stdin when piped)
--prompt, -p <text> [deprecated] Use -x/--execute instead. One-shot / execute mode
--jsonl, --stream-json Output framed JSONL events on stdout instead of plain text (execute mode)
--child Run as a headless agent child process (internal use; hidden)
--web Start the Web UI and open it in the default browser
--port <n> HTTP port for the Web UI. Default 0 = OS-assigned ephemeral port
--no-web Do not start the Web UI. TUI only
--insecure Skip TLS certificate verification. Env: TAU_INSECURE
--verbose Show debug messages on stderr. Env: TAU_VERBOSE

Enabling Providers

Tau discovers providers automatically. To enable a provider:

  1. tau setup (recommended for first run): Interactive walkthrough for selecting a provider and authenticating. Managed API keys are stored in ~/.config/tau/auth.yaml — env vars override them when both are present.

  2. tau provider CLI:

    tau provider list                      # show all providers and auth state
    tau provider login deepseek            # enter and store a managed API key
    tau provider login openai-codex        # OAuth device-code flow
    tau provider login                     # interactive selector (TTY only)
    tau provider logout openai             # disable and clear credentials
    

    For non-OAuth providers, tau provider login stores a managed API key in auth.yaml.

  3. Environment variable: Export the provider's API key env var (e.g. DEEPSEEK_API_KEY=sk-...). Tau detects it at startup.

  4. TUI slash commands: /provider [name] to toggle a provider, /provider login <name> for OAuth flow.

  5. config.yaml: Add a provider block (see Configuration below).

Run /model in the TUI to pick from all enabled providers' models.

Web UI

When tau starts interactively, it binds a local HTTP/WebSocket server on 127.0.0.1. The URL is shown in the TUI status bar.

./tau              # TUI + Web UI, URL in status bar
./tau --web        # TUI + Web UI, also opens the browser
./tau --no-web     # TUI only
./tau --port 9343  # Fixed port

The browser connects to /ws and receives the same event stream as the TUI. Commands sent from the browser are forwarded to the coordinator identically to TUI commands. Multiple browser tabs may connect to the same session.

Slash Commands (TUI)

Command Description
/model [id] Switch model; opens picker when called without an ID
/provider [name] Toggle a provider on/off; lists all providers when called without an argument
/provider login <provider> OAuth device-code sign-in for github-copilot or openai-codex; opens the browser and copies the code when possible
/provider logout <provider> Disable a provider / remove its saved key
/refresh Re-discover models from all enabled providers
/effort [level] Set reasoning effort (off, low, medium, high, max)
/reasoning [on|off] Toggle display of model reasoning content
/system <prompt> Set the session system prompt
/session [list|info|export|delete|<id>] Manage saved sessions
/resume [id] Resume a saved session
/new Start a fresh conversation (aliases: /clear, /reset)
/reload Reload extensions/plugins
/help Show all available commands
/exit Quit tau

Subcommands

tau setup

Interactive setup wizard for first-run configuration. Walks through provider selection, authentication (API key or OAuth), and model selection.

tau setup

Called automatically on first run if no providers are configured.

tau provider

Manage provider authentication from the CLI.

tau provider list                       # table of providers with status, source, and auth type
tau provider login [name]               # authenticate an OAuth or API-key provider
tau provider login                      # interactive selector when stdin is a TTY
tau provider logout <name>              # disable provider and clear managed credentials

Provider credentials are managed via the keychain or stored in ~/.config/tau/auth.yaml. See docs/providers.md for the full provider architecture.

tau models

List available models from the configured provider.

tau models [--json]

Uses the live models.dev catalog (network). For the model list used in the interactive TUI, see the embedded snapshot (internal/providers/snapshot/).

tau refresh

Force a refresh of the models.dev network catalog and list models.

tau refresh

Downloads the latest catalog for the configured provider. This affects the tau models output and the snapshot generator, but interactive sessions use the embedded offline snapshot (internal/providers/snapshot/models.json).

tau sessions

List saved chat sessions.

tau sessions

Shows a table of sessions with ID, model, message count, tokens, cost, and date. Use /session inside the TUI for richer session management.

tau token

Print the resolved API key / bearer token for the selected provider.

tau token

Useful for debugging auth configuration.

tau update

Update the current tau binary from GitHub release assets, or check for available updates.

tau update [--check] [--version v0.16.2] [--repo owner/repo] [--force]

The updater downloads the platform archive and checksums.txt, verifies the archive checksum, extracts the tau binary, and applies it in place.

By default, update checks only happen when you run tau update manually. Set updates.mode: warn in configuration to keep manual checks with update notifications, or updates.mode: disabled to disable all update checks including tau update. Dev builds (version dev) are always excluded from update checks — only release builds are eligible.

Configuration

Tau loads ~/.config/tau/config.yaml (global) and .tau.yaml (project-local). Example configs are in config-example.yaml and config-deepseek-example.yaml.

Minimal configuration

# ~/.config/tau/config.yaml
default_provider: deepseek
default_model: deepseek-chat

providers:
  - name: deepseek
    base_url: https://api.deepseek.com/v1
    auth:
      type: api_key
      api_key_env: DEEPSEEK_API_KEY

Model metadata (context window, pricing, reasoning) is loaded from the embedded snapshot - you do not need to repeat it in config. See docs/ai-sdk.md for full integration details.

ProviderConfig fields

Field Description
name Provider identifier (matches tau's catalog ID)
base_url API endpoint. Must include /v1 when the provider uses it
type ai-sdk class override (anthropic for Anthropic native API; omit for OpenAI-compatible)
auth.type api_key, none, or oauth_pkce
auth.api_key_env Environment variable name for the API key
auth.api_key Literal API key (not recommended; prefer api_key_env)
headers Optional static request headers; do not put bearer tokens here
models Optional list of model overrides (see below)

Model overrides

Tau's embedded snapshot provides model metadata. Override individual fields only when you need to customise them:

providers:
  - name: openai
    auth:
      type: api_key
      api_key_env: OPENAI_API_KEY
    models:
      - id: gpt-5.4
        context_window: 200000
        default_max_tokens: 16384

Documentation Index

Architecture & Design

Core Systems

  • Agent Coordinator - turn loop, command handlers, tool execution, prompts
  • Chat Types - complete command/event reference, core types
  • Tools - registry, built-in tools, mutation queue, UIBridge
  • Commands - slash command registry, custom commands

UI Systems

  • Terminal UI (TUI) - inline rendering, widget tree, slash commands, completions, notifications
  • Web UI - Vue 3 SPA, state management, components, protocol, build
  • Server & Bridge - HTTP/WebSocket server, event fan-out, wire format
  • taui Framework - standalone TUI rendering engine, widgets, color system

Infrastructure

  • Configuration - YAML config format, env vars, CLI flags
  • Providers - provider catalogue, auth state, model discovery, dynamic switching
  • AI SDK Integration - embedded snapshot, dynamic streamer, URL rules, reasoning
  • Sessions - SQLite persistence, session lifecycle, JSONL export
  • Skills - SKILL.md discovery, frontmatter parsing, prompt rendering

Extensibility

  • Plugin SDK - gRPC extension system, tools, slash commands, lifecycle events
S
Description
Archie connects events from your systems to agents that can investigate, reason, and act. Define what an event means, map its data into a workflow, and give that workflow an agent equipped for the job: its own execution environment, tools, and identity.
https://archie.catlow.cloud
Readme Apache-2.0
132 MiB
0 Stars 1 Watchers 0 Forks
2026-11-10 10:01:23 +00:00
Languages
Go 76.7%
Vue 13.1%
TypeScript 7.8%
JavaScript 1.2%
Shell 0.6%
Other 0.4%