@fastagent-sh/fastagent 0.24.4 → 0.26.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="https://fastagent.sh"><img src="https://raw.githubusercontent.com/fastagent-sh/fastagent/main/assets/hero.png" alt="FastAgent — Vibe first. Then FastAgent. An agent directory becomes a live service in your app, on GitHub, in Telegram, or any channel." width="860"></a>
+  <a href="https://fastagent.sh"><img src="https://raw.githubusercontent.com/fastagent-sh/fastagent/main/assets/hero.png" alt="FastAgent — Vibe first. Then FastAgent. An agent directory becomes a live service in your app, in Telegram, in Slack, or any channel." width="860"></a>
 </p>
 
 [![CI](https://github.com/fastagent-sh/fastagent/actions/workflows/ci.yml/badge.svg)](https://github.com/fastagent-sh/fastagent/actions/workflows/ci.yml)
@@ -16,41 +16,42 @@
   <sub>— the agent harness &amp; multi-provider LLM API under the hood</sub>
 </p>
 
-A file-defined agent directory can become a live service. FastAgent takes it out of the terminal and serves it in your Next/Astro app, Telegram, Slack, Feishu, an API endpoint, or your own channel.
+A file-defined agent directory can become a live service. FastAgent takes it out of the terminal and serves it in your Next/Astro app, Telegram, Slack, Feishu, on a clock, or behind your own channel.
 
 Leave the terminal. Become a live service.
 
 - **Add it to your app** — one route, your auth, your database, your host.
-- **Run it as a live service** — Telegram, Slack or Feishu bot, webhook handler, API endpoint, or custom channel.
+- **Run it as a live service** — Telegram, Slack or Feishu bot, webhook handler, schedule, or custom channel.
 
 FastAgent is not a new agent-authoring DSL. You bring the existing definition and project layout; FastAgent provides the serving runtime and adapters around it.
 
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/gh/fastagent-sh/fastagent@main/assets/demo.svg" alt="Three acts in one terminal: a coding agent vibes a support agent into a directory; fastagent dev serves it live, answering a GitHub pull request, a Telegram message, and an HTTP invoke; fastagent deploy fly --run ships it to a live URL." width="860">
+  <img src="https://cdn.jsdelivr.net/gh/fastagent-sh/fastagent@main/assets/demo.svg" alt="Three acts in one terminal: a coding agent vibes a support agent into a directory; fastagent dev serves it live, answering a Telegram message and a Slack mention and firing a daily schedule; fastagent deploy fly --run ships it to a live URL." width="860">
 </p>
 
 ## Why FastAgent
 
-Coding agents made it cheap to vibe useful agent directories. The hard part is the next step: local agents live in terminals, but real services receive webhooks, join Telegram, serve product users, and expose stable APIs.
+Coding agents made it cheap to vibe useful agent directories. The hard part is the next step: local agents live in terminals, but real services receive webhooks, join chats, run on a clock, and keep their conversations across restarts.
 
 FastAgent is the missing bridge from local agent directory to live service.
 
 ## Features
 
-- **Vibe first — add a `fastagent/` folder to any project.** The agent is that folder; the project around it is what it works on, and the project's `AGENTS.md` is its context. Markdown instructions, reusable skills, and TypeScript tools stay as files you inspect, edit, and commit — no new DSL, no framework rewrite.
-- **Channels.** Serve the same agent as a Telegram bot, a Slack app, a Feishu or Lark bot, an HTTP/SSE endpoint, or your own adapter: verified webhooks, streaming replies, group-aware.
-- **Models, tools & skills.** Any model provider (OpenAI, Anthropic, Google, …) via OAuth or API key; typed tools discovered from `tools/` (the filename is the name, Zod-validated); Agent Skills loaded on demand. Built on the open-source [pi](https://github.com/earendil-works/pi) harness.
-- **App embedding — your stack, we plug in.** Mount the agent in your Next / Astro / Hono / Bun / Node route with one handler, or call `invoke` like any function from your own code — your auth, your database, your infra. FastAgent composes with your app, never owns it.
+- **Vibe first — an agent is a directory of its own.** A `SYSTEM.md` prompt, reusable skills, and TypeScript tools stay as files you inspect, edit, and commit — no new DSL, no framework rewrite. The projects it works on are declared beside it as its content, which it reads and changes but which never becomes part of its definition.
+- **Channels.** Serve the same agent as a Telegram bot, a Slack app, a Feishu or Lark bot, or your own adapter: verified webhooks, streaming replies, group-aware.
+- **Durable by default.** Every conversation lives in the instance's storage, and an accepted message is answered after a restart. Built on the open-source [pi](https://github.com/earendil-works/pi) durable harness.
+- **Models, tools & skills.** Any model provider (OpenAI, Anthropic, Google, …) via OAuth or API key, plus your own providers in code; typed tools in `src/tools/` (TypeBox-validated); Agent Skills loaded on demand.
+- **App embedding — your stack, we plug in.** Open the agent in your own process and call it like any function, behind your auth, with your database and infra; mount its channels in your Next / Astro / Hono / Bun / Node app with one handler. FastAgent composes with your app, never owns it.
 - **Deploy anywhere.** No application build step — the directory is the deployable unit. `fastagent deploy docker|fly|railway|agentcore` generates the container + target config and a runbook (`--run` drives it to completion). Local Docker gets user-owned Compose + durable state; optional `--tunnel` adds an ephemeral Quick Tunnel service for webhook channels; AWS Bedrock AgentCore gets a one-stack CloudFormation topology (webhooks via a forwarder Lambda, schedules via EventBridge). Durable ingress remains yours.
 
 ## Design philosophy
 
 FastAgent is built around a small serving contract, app-owned runtime concerns, typed boundaries, and composable adapters.
 
-- **Small serving core** — `invoke` decouples channels, agents, harnesses, and infra.
+- **One API, in process and over HTTP** — the [Agent API](docs/SPEC.md) is what every channel, schedule and app calls, and what a program calls a deployed agent with.
 - **App-owned runtime** — no takeover of your auth, database, routes, or deployment.
 - **Typed edges** — typed tools, explicit events, boundary validation.
-- **Agent-native shape** — the directory is the deployable unit, and channels drive the same contract.
+- **Agent-native shape** — the directory is the deployable unit, and every check is a command a coding agent can run.
 
 Read the [Design principles](https://fastagent.sh/docs/principles/) for the full rationale.
 
@@ -59,9 +60,10 @@ Read the [Design principles](https://fastagent.sh/docs/principles/) for the full
 FastAgent stays a small serving layer, so it never dictates your stack. Capabilities other agent frameworks bake into a platform, we leave to your app, your infra, or the agent itself — composed in, not locked in.
 
 - **No platform to move to.** No dashboard, no control plane, no runtime you deploy *into* — run it locally, embed it in your app, or ship the directory anywhere.
-- **No new format or DSL.** `AGENTS.md`, Agent Skills, TypeScript tools, HTTP/SSE — FastAgent consumes the standards you already use instead of a parallel ecosystem.
-- **No workflow engine.** The agent decides its own steps; for deterministic multi-step orchestration, call `invoke` from your own queue or workflow.
-- **No model or cloud lock-in.** The Agent Handler contract is harness-neutral (the [SPEC](https://fastagent.sh/docs/spec/) says *engine* — same seam), with [pi](https://pi.dev) as the built-in harness; bring your own harness and every channel keeps working unchanged.
+- **No new format or DSL.** `AGENTS.md`, Agent Skills, TypeScript modules — FastAgent consumes the standards you already use instead of a parallel ecosystem.
+- **No workflow engine.** The agent decides its own steps; for deterministic multi-step orchestration, send messages from your own queue or workflow.
+- **One key, no auth system.** A served agent answers its channels, each of which verifies its platform, and, given `FASTAGENT_API_KEY`, the Agent API under `/v1`: one key for the whole instance, kept on a server, that keeps everyone but its customer out. Users, roles and per-session access are your app's, in front of it.
+- **No model or cloud lock-in.** Any provider pi-ai supports, or your own; any host that runs a container.
 
 ## Install
 
@@ -78,7 +80,7 @@ npm i -g @fastagent-sh/fastagent   # CLI: fastagent init/dev/start/...
 npm i @fastagent-sh/fastagent      # library API for embedding or code tools
 ```
 
-Requires **Node >= 22.19** (the floor is inherited from the pi harness and `undici`), and also runs under **Bun** (smoke-tested in CI on Bun 1.3; its native fetch replaces the undici path). The npm package ships compiled JavaScript and type declarations.
+Requires **Node >= 24.15** or **Bun >= 1.4**, both set by the agent's storage, `node:sqlite`: Node stops calling it experimental in 24.15, and Bun ships it from 1.4 (smoke-tested in CI on 1.4.0; its native fetch replaces the undici path). The npm package ships compiled JavaScript and type declarations.
 
 ## Quickstart
 
@@ -88,12 +90,10 @@ cd my-agent
 fastagent dev
 ```
 
-Then send a local test turn:
+Then send it a message:
 
 ```bash
-curl -N -X POST localhost:8787/invoke \
-  -H 'content-type: application/json' \
-  -d '{"session":"s1","text":"hello"}'
+fastagent invoke "hello"
 ```
 
 For production-style local serving:
@@ -107,35 +107,20 @@ There is no FastAgent build step: the agent folder is the deployable unit.
 ## Embed in an app
 
 ```ts
-import { createInvokeHandler, createPiAgentFromDefinition } from "@fastagent-sh/fastagent";
+import { openAgent } from "@fastagent-sh/fastagent";
 
-const { agent } = await createPiAgentFromDefinition("./agent", {
-  model: "openai-codex/gpt-5.5",
-});
+const agent = await openAgent("./agent", { model: "openai/gpt-5.5" });
 
-export const POST = createInvokeHandler(agent); // Fetch-shaped handler
+const session = await agent.sessions.create();
+for await (const event of agent.messages.stream({ sessionId: session.id, content: "hi" })) {
+  if (event.type === "delta" && event.channel === "text") render(event.text);
+}
 ```
 
-No directory? Assemble from typed parts:
-
-```ts
-import { createPiAgent, defineTool, z } from "@fastagent-sh/fastagent";
-
-const lookupOrder = defineTool({
-  name: "lookup-order",
-  description: "Look up an order by id.",
-  input: z.object({ orderId: z.string() }),
-  async execute({ orderId }) {
-    return await db.find(orderId);
-  },
-});
-
-const agent = createPiAgent({
-  model: "openai-codex/gpt-5.5",
-  instructions: "You are a support assistant. Use lookup-order for order questions.",
-  tools: [lookupOrder],
-});
-```
+`await agent.serve()` adds the agent's channels and schedules to your app: a Fetch handler for its webhooks, mounted
+where your framework routes them, or a server of its own (`listen`) ([Embedding](docs/embedding.md)). Served with a key
+(`FASTAGENT_API_KEY` for `start`), the same API is reachable over HTTP under `/v1`, and another program calls it with
+`connectAgent(url, { apiKey })` from `@fastagent-sh/fastagent/client` as it would the opened agent.
 
 ## Documentation
 
@@ -154,43 +139,30 @@ const agent = createPiAgent({
 | [Channel development](https://fastagent.sh/docs/channel-development/) | Build custom channel adapters |
 | [API reference](https://fastagent.sh/docs/api-reference/) | Public TypeScript API reference |
 | [Troubleshooting](https://fastagent.sh/docs/troubleshooting/) | Common setup/runtime issues |
-| [Agent Handler SPEC](https://fastagent.sh/docs/spec/) | Agent Handler protocol v0.1 |
+| [Agent API SPEC](https://fastagent.sh/docs/spec/) | The Agent API every Caller uses |
 | [Core design](https://fastagent.sh/docs/design/core/) | Maintainer architecture notes |
 
 ## Public API surface & stability
 
-The root export intentionally contains the supported surface only.
+The package exports the supported surface only, from one entry per kind of user, and names every export (no
+`export *`), which CI asserts:
 
-Engine-neutral and runtime-neutral are different properties, and the entries are layered by them —
-each layer drops one, and every layer's dependency list is asserted in CI:
+| Area | Examples | Stability |
+|---|---|---|
+| The Agent API | `Agent`, `AgentError` ([Agent API](docs/SPEC.md)) | Stable within its version |
+| Directory → agent → service | `openAgent`, `LocalAgent`, `serve()`'s `Service` (`fetch`, `listen`) | Usable now, may tighten before 1.0 |
+| Over HTTP | `connectAgent` (`/client`), the `/v1` routes ([Agent API](docs/SPEC.md) §9) | Stable within its version |
+| A host embedding agents | `createAgent`, `CredentialStore`, `credentialFile`, `signIn`, `signInOptions`, `providerAuth` ([embedding](docs/embedding.md#6-a-desktop-host)) | Usable now, may tighten before 1.0 |
+| Authoring | `defineAgent`, `defineChannel`, `defineSchedule`, `needs`, `sessionIdOf`, `readBodyCapped`, `text`, `secretEquals` | Usable now, may tighten before 1.0 |
+| Not exported | The assembly's parts (`router`, `createScheduler`), content editing, the model environment, harness internals | No compatibility promise |
 
-| | engine-neutral | runtime-neutral | costs |
-|---|---|---|---|
-| `/core`, `/session` | yes | yes | nothing |
-| `/node` | yes | no (filesystem, clock, environment) | `@hono/node-server`, `croner` |
-| `/pi` | no | no | the pi runtime |
+A tool or an extension is pi-durable's own (`defineTool`, `defineExtension` from `@earendil-works/pi-durable`), and a
+custom provider is pi-ai's (`createProvider` from `@earendil-works/pi-ai`): `init` adds both packages to the agent.
 
-`Provider` and `ProviderAuth` are exported as types because our options name them; the factory that
-builds one, `createProvider`, comes from `@earendil-works/pi-ai` — add it as a direct dependency when
-you register a custom provider.
+Entry points (`./package.json` is also exported, for tools that read the version):
 
-| Area | Examples | Stability |
-|---|---|---|
-| Contract | `Agent`, `AgentEvent`, `collect` | Stable within SPEC v0.1 |
-| Directory → service | `createAgentService` (pi opener), `mountAgentService` + `MountableAgent` (neutral assembly), `AgentService` | The supported way to mount an agent directory in an app |
-| Mounting | `createInvokeHandler`, `Routes`, `ChannelHandler` | Reference implementation, pre-1.0 |
-| Node binding | `nodeListener`, `serveNode` (from `/node`) | The one runtime-specific piece; see below |
-| pi assembly | `createPiAgentFromDir`, `createPiAgentFromDefinition`, `createPiAgent` | Usable now, may tighten before 1.0 |
-| Tool/channel authoring | `defineTool`, `z`, `defineRoutine`, `ChannelModule` | Usable now, may tighten before 1.0 |
-| Injection ports | `PiSessionRecordStore`, `piSessionRecordStore`, `piInMemorySessionRecordStore`, `Lease`, `Provider` | Public because options reference them |
-| Not exported | The assembly's parts — `router`, `createControlPlane`, `loadTools`/`loadChannels`/`loadRoutines`, `createScheduler` — and prompt/config internals | `createAgentService` does this; no compatibility promise |
-
-Subpath entry points (`./package.json` is also exported, for tools that read the version):
-
-- `@fastagent-sh/fastagent/core` — engine-neutral contract, consumption helpers, channel kit, schedules, and the session-control clients (`connectSessionControl`, `connectAgent`). **Zero third-party dependencies**, enforced by test;
-- `@fastagent-sh/fastagent/node` — the engine-neutral pieces that need a Node runtime: `mountAgentService` (the assembly), `serveNode` / `nodeListener` (the `node:http` ↔ Fetch binding);
-- `@fastagent-sh/fastagent/session` — the engine-neutral session-control contract (types and error codes);
-- `@fastagent-sh/fastagent/pi` — the pi reference implementation;
+- `@fastagent-sh/fastagent` — the Agent API, `openAgent`, what a host embedding agents needs, and what an author writes;
+- `@fastagent-sh/fastagent/client` — `connectAgent`, the Agent API over HTTP, for a program anywhere `fetch` runs;
 - `@fastagent-sh/fastagent/telegram` — Telegram bot channel;
 - `@fastagent-sh/fastagent/slack` — Slack Events API bot channel;
 - `@fastagent-sh/fastagent/feishu` — canonical Feishu bot channel (飞书, open.feishu.cn);
@@ -200,7 +172,7 @@ Subpath entry points (`./package.json` is also exported, for tools that read the
 
 ```txt
 src/     the npm package: CLI, library API, reference implementation
-test/    vitest suite (faux models by default) + reusable SPEC conformance
+test/    vitest suite (faux models by default) + the Agent API's conformance suite
 docs/    user docs, SPEC, and maintainer design notes
 ```
 
@@ -208,16 +180,16 @@ One package; subpath exports are the module boundary.
 
 ## Status
 
-FastAgent is pre-1.0. The stable design center is the Agent Handler contract in `docs/SPEC.md`; the package API may still tighten before 1.0. Notable changes are recorded in the [GitHub Releases](https://github.com/fastagent-sh/fastagent/releases).
+FastAgent is pre-1.0. The stable design center is the Agent API in `docs/SPEC.md`; the package API may still tighten before 1.0. Notable changes are recorded in the [GitHub Releases](https://github.com/fastagent-sh/fastagent/releases).
 
 ## Designed for more
 
-The neutral contract leaves room for capabilities that are not complete product features yet:
+The Agent API leaves room for capabilities that are not complete product features yet:
 
-- **Durable execution**: Telegram, Slack, and Feishu/Lark accepted turns replay at least once today; general durability and exactly-once execution remain future backend work.
-- **Sandboxed execution** — all seven coding tools, ② project context, channels, and author-written `tools/` reach the local process directly; a sandbox around the complete agent process is future work.
-- **Observability export** — leveled logs and per-turn traces exist today; an OpenTelemetry exporter does not.
-- **More harness bindings and channels** — pi is the built-in harness; another harness can implement the Agent contract, and community channels can use the channel kit.
+- **Scale-out**: one process holds an instance's storage today; spreading one instance over several processes is future work.
+- **Sandboxed execution** — the coding tools, channels, and author-written code reach the local process directly; a sandbox around the complete agent process is future work.
+- **Observability export** — leveled logs exist today; an OpenTelemetry exporter does not.
+- **More channels and connectors** — community channels can use the channel kit; MCP servers as connectors are planned.
 - **More deploy targets** — local Docker, Fly, Railway, and AWS Bedrock AgentCore ship today; the generated container is the portable path for other hosts.
 
 See [Contributing](https://github.com/fastagent-sh/fastagent/blob/main/CONTRIBUTING.md) if one of these is the problem you want to work on.
@@ -231,9 +203,9 @@ See [Contributing](https://github.com/fastagent-sh/fastagent/blob/main/CONTRIBUT
 
 ## Acknowledgements
 
-FastAgent stands on open source. The built-in harness is **[pi](https://github.com/earendil-works/pi)** ([pi.dev](https://pi.dev)) — its agent loop, multi-provider LLM API, and the interactive TUI that `fastagent chat` drives.
+FastAgent stands on open source. The harness is **[pi](https://github.com/earendil-works/pi)** ([pi.dev](https://pi.dev)) — pi-durable's durable agent loop and pi-ai's multi-provider LLM API.
 
-It also depends on, and is grateful to, [zod](https://github.com/colinhacks/zod), [undici](https://github.com/nodejs/undici), [chokidar](https://github.com/paulmillr/chokidar), [giget](https://github.com/unjs/giget), [@clack/prompts](https://github.com/bombshell-dev/clack), [ignore](https://github.com/kaelzhang/node-ignore), and [octokit/webhooks](https://github.com/octokit/webhooks).
+It also depends on, and is grateful to, [Effect](https://github.com/Effect-TS/effect), [undici](https://github.com/nodejs/undici), [chokidar](https://github.com/paulmillr/chokidar), [giget](https://github.com/unjs/giget), [@clack/prompts](https://github.com/bombshell-dev/clack), [ignore](https://github.com/kaelzhang/node-ignore), and [croner](https://github.com/Hexagon/croner).
 
 The scaffolded `writing-great-skills` skill is vendored from [mattpocock/skills](https://github.com/mattpocock/skills), with its license included.