flue AGENTS.md

Flue

Flue is a TypeScript framework for building autonomous AI agents and running them anywhere. An agent is a plain exported function: hooks in its body compose its capabilities — model (useModel), tools, skills, sandboxes, state — and its return value is its instruction. Agents live in durable conversations: accepted input survives crashes, restarts, and redeploys, and interrupted work recovers to a deterministic state. Applications build with Vite (the flue() plugin plus an explicit app.ts route map) and deploy to Node.js or Cloudflare Workers from the same source, with persistence adapters (SQLite, Postgres, MySQL, MongoDB, Redis, and more), channels that turn provider webhooks (Slack, GitHub, Telegram, ...) into agent conversations, and clients — the Flue Agent SDK (@flue/sdk), @flue/react, and the flue CLI — for driving conversations over HTTP or from code. The model layer is Pi's provider protocol, used directly.

Contributing

See CONTRIBUTING.md for the full picture. In short:

• Bug reports → https://github.com/withastro/flue/issues
• Feature requests → https://github.com/withastro/flue/discussions
• Pull requests are not accepted; they are automatically closed and converted into one of the two contribution types above.

Terminology

Agent                         — a capitalized, exported plain function; Flue Hooks in its body attach
                                tools, instructions, and state, and its returned string is its
                                instruction; the function name (or its `agentName` string-literal
                                static) is the agent's durable identity
Agent module                  — a source file whose first statement is the `'use agent'` directive;
                                every capitalized exported function in it is an agent
└─ AgentInstance              — URL `<id>`; the agent's durable identity, independent of authoring
   └─ Harness                 — runtime-initialized agent environment; defaults to name `"default"`
      └─ Session              — one `harness.session(name?)`; defaults to `"default"`
         └─ Operation        — one `session.prompt` / `skill` / `task` / `shell` call
            └─ Turn          — one LLM round-trip inside pi-agent-core