fastagent: Instructions file for Codex

fastagent — Agent Guide

What this is

fastagent is "Vibe first. Then FastAgent" for agent directories: it turns a file-defined agent (a SYSTEM.md prompt, skills/, code under src/, and existing AGENTS.md project context) into a live service inside an app, in Telegram, Slack or Feishu, or behind a custom channel without a new authoring DSL.

The design center is decided in docs/design/architecture.md: an agent is a definition assembled onto one harness, pi-durable, and served through one API of our own, the consumer Agent API of docs/SPEC.md; everything else is pi-durable's own API.

Source of truth

Code truth is src/.

Repo map

One line per file: what it owns. The reason it is that way lives in the file's own header — the one place that cannot drift away from the code it explains. Directories that have no header file (src/deploy, test/live) point at where theirs lives.

src/
├── agent-api.ts            # the Agent API (docs/SPEC.md) as types, plus its limits and error values;
│                           # imports nothing
├── agent-api-stream.ts     # stream(agent, request): send a message and read its answer as written, over any Agent
├── answer-text.ts          # a message's answer text as it streams: its deltas, plus entry text no delta carried
├── channel.ts              # the Channel contract: ChannelModule / Routes / ChannelHandler / LongConnection*
├── conversation-sessions.ts # which Agent session each of a Caller's conversations talks in (a channel's chats and
│                           # threads, a schedule's runs), and the order a new one is created in
├── service.ts              # THE PRODUCT AS ONE CALL — an opened agent becomes a live service (mountAgentService),
│                           # plus the assembly parts dev/start share: routesFor / startSchedules
├── effect-port.ts          # the ONE crossing from a Promise-shaped port into Effect: port / portJoin / portAbort /
│                           # portRequest / portCleanup / PortFailure
├── once.ts                 # work that runs once per process, its outcome shared (shutdown, AgentCore activation)
├── core.ts, node.ts, pi.ts # the three public layers, by what each costs to import: neutral + Effect only, no Node /
│                           # harness-neutral but needs Node / names the harness. Asserted in package-boundary.test.ts
├── index.ts                # supported all-in-one entry (re-exports core + node + pi)
├── cli.ts                  # the THIN entry (import-free; lazy-loads cli/program.ts)
├── cli/                    # the CLI, built on clig.dev
│   ├── kernel.ts           # CommandSpec-as-data + the commander adapter (commander appears ONLY here); exit 0/1/2
│   ├── program.ts          # the spec registry — the CLI surface's source of truth; lazy per-command imports
│   ├── invoke-stream.ts    # `invoke`: one message's answer, as stream() reads it, as text or JSON lines → exit code
│   ├── models-view.ts, auth-view.ts, content-view.ts # `models` / auth-report / content output
│   ├── add-feishu.ts, add-slack.ts # `add feishu|lark` / `add slack` onboarding
│   ├── shared.ts, serve.ts # cross-command helpers: serve/bind reporting, tunnel (the ASSEMBLY is service.ts)
│   ├── fail.ts             # the process-exiting failure boundary
│   ├── login-relay.ts      # `login` split across a process boundary: LoginIO as JSON lines, box half + terminal half
│   ├── box-login.ts        # `login --deployment`: the login runs ON the deployed box, through the host's own shell
│   └── commands/           # one module per command; `deploy` dispatches to one commands/deploy/<host>.ts each
├── telegram.ts, slack.ts,  # subpath-export shims (@fastagent-sh/fastagent/telegram etc.)
│   feishu.ts, lark.ts
├── bind.ts                 # the ONE reading of a bind address, as the six different questions it is
├── log.ts                  # leveled logging singleton (dev=debug, start=info)
├── tunnel.ts               # `--tunnel`: cloudflared + per-channel webhook dispatch
├── dev-supervisor.ts       # `dev` supervisor: restart on code edits (src/, config, package.json, .env); the
│                           # prompt files and skills are read per message
├── proxy.ts                # the process's outbound-fetch policy: the declared proxy, loopback exempt by default
├── open-url.ts             # best-effort "open this in a browser" (callers still print the URL); only https or
│                           # loopback http reaches the opener, because some URLs come from a deployed box
├── env.ts                  # ENTERING the selected environment: dev `.secrets/.env` or production
│                           # `.secrets/production/.env` → process.env, then the egress that follows
├── serving-command.ts      # which command serves this process (`dev` marks it): the default a channel's ingress
│                           # setting falls back to, read through the process environment the CLI and the agent share
├── runtime.ts              # agent runtime/package-manager detection (node vs bun) + readPackageJson
├── paths.ts                # ADDRESSING (which directory is the agent: the one named, never searched for) + the
│                           # shared path predicates and the machinery paths that follow (.secrets/.state/content)
├── git.ts                  # running git, and what ONE result means (an answer, a "no", or no git at all)
├── content/                # what an agent works on and knows — harness-neutral
│   ├── declare.ts          # a shared entry and a machine's binding, read and refused in ONE place (names, keys)
│   ├── file.ts             # `context.json` + `context.local.json` read (a reader its part, an edit the whole) and written
│   ├── mount.ts            # content/, where the clones go: the dir with its own .gitignore
│   ├── resolve.ts          # where each entry is for THIS instance (a clone, a bound dir): the one answer every reader uses
│   ├── git.ts              # a GitHub entry's git: which repository a checkout is of, its ref, a fresh clone
│   └── source.ts           # what a command's <source> adds (github:owner/repo, a checkout, a directory)
├── environment/            # the commands an agent runs, declared in context.json — harness-neutral
│   ├── declare.ts          # the `environment` declaration, read and refused in ONE place; the backend allowlist
│   ├── mise.ts             # the agent's OWN mise (an npm dep per platform), packages as arguments: install, enter
│   └── apt.ts              # which declared apt packages THIS machine lacks (dpkg; Debian and Ubuntu only)
├── authoring.ts            # creating an agent + editing its content as an API; `init`/`content` are thin wrappers
├── declared-secrets.ts     # WHICH env vars this agent needs, in ONE shape (`needs()` in code, context.json's
│                           # variables), and what "has no value" means
├── atomic-write.ts         # writeFileAtomic: the ONE "whole file or none of it" write
├── locked-file.ts          # the cross-process locked read-modify-write that REPLACES a file (credentials,
│                           # context.json), pi's lock included, so every reader of those files reads without one
├── state-file.ts           # a Caller's durable JSON state under the state root (channels, schedules), read and
│                           # written whole
├── version.ts              # package version + the pi-durable and pi-ai ranges a scaffolded agent depends on
├── scaffold/               # `init` / `add <channel>` / `add skill` + templates/ (real files)
├── channels/
│   ├── router.ts           # how route tables become ONE Fetch handler: the path rule and dispatch, no guard of its
│   │                       # own (every route verifies its caller). Fetch-only: /core serves through it
│   ├── serve.ts            # the server a Fetch handler is served on (Effect's, on Node's or Bun's own), behind the
│   │                       # totality boundary; and `nodeListener`, the bridge an app's own node:http server mounts
│   ├── agentcore-service.ts # the AgentCore serving assembly (same product as service.ts, built for that
│   │                       # host): channels discovered on trusted ingress, the whole definition opened
│   │                       # on the first envelope, an external clock, no resident connections
│   ├── agentcore.ts        # the AgentCore Runtime adapter: POST /invocations + GET /ping, the envelope kinds,
│   │                       # and the shared-secret boundary that separates a forwarder call from any IAM one
│   ├── agentcore-protocol.ts # THE WIRE between the forwarder Lambda and the container (types + constants)
│   ├── agentcore-limits.ts # the host's body ceilings, computed once
│   ├── busy.ts             # the process's work in flight (every unsettled message, channel and schedule work not
│   │                       # yet at one), read by /ping (HealthyBusy) and by `dev` before it restarts
│   ├── discover.ts         # a definition's built channels, mounted: route channels' routes, long connections bound
│   ├── body.ts, respond.ts # channel-authoring kit (body cap, responses)
│   ├── secret.ts           # the ONE constant-time comparison every shared-secret gate reads through
│   ├── wait-health.ts      # readiness probe for a server THIS process reaches directly (not a public URL)
│   ├── registration.ts     # the shared registrar outcome (registered|manual|failed) + the ONE retry loop
│   ├── kit/                # WRITING a channel. Its defining property is an import fact, asserted in
│   │   │                   # package-boundary.test.ts: everything here has consumers only under
│   │   │                   # channels/<platform>/, and serve/router/discover have none there
│   │   ├── preview-kit.ts  # pure turn-view reducer, line renderers, preview policies
│   │   ├── delivery.ts     # scoped coalescing previews, ordered native writes, terminal settlement
│   │   ├── event-stream.ts # typed, demand-driven Agent iterator acquisition and scoped cleanup
│   │   ├── invoke-turn-kit.ts # prepare inputs → one keyed, queued message; the prompt manifest wording
│   │   ├── transport.ts    # whether a call is worth waiting out a rate limit for (DROPPABLE_FRAME, CONTEXT_READ)
│   │   ├── turn-runner.ts  # accept → dequeue → execute → settle over the queue + store + discussion source
│   │   ├── turn-queue.ts   # per-session FIFO root fibers; queued work counts busy and survives ingress ACK
│   │   ├── turn-store.ts   # generic durable turn intent + the answer owed to it (record shape/validator/order injected)
│   │   ├── room-threads.ts # what a thread-reading tool may read: its turn's room (registered by the turn runner),
│   │   │                   # never one it is told; the thread list's format and bound
│   │   ├── place-history.ts # the DiscussionSource a turn folds + the place-history fold (budget, labels) + what a
│   │   │                   # place remembers between platform reads (cursor, the turns' own outputs)
│   │   ├── context-buffer.ts # generic durable un-summoned-discussion buffer (peek→completed→commit)
│   │   ├── thread-participants.ts # who the agent has HEARD in a thread (the summon rule)
│   │   ├── seen.ts         # bounded durable delivery dedup
│   │   ├── signature.ts    # replay window for a signed webhook ingress
│   │   ├── tasks.ts        # side-task tracking (ACK-independent work); drain is observation only
│   │   ├── text.ts         # Unicode-safe code-point slicing
│   │   ├── attachment-path.ts # where an attachment lands (the conversation id encoded into a directory)
│   │   ├── stop-command.ts # the shared /stop parsing every chat channel accepts, and the abort it dispatches
│   │   └── thread-fork.ts  # a new thread starts as a fork of its room at the message its reply chain names (by key)
│   ├── telegram/           # telegram channel: see docs/design/core.md §7
│   │   ├── telegram.ts     # ingress + per-turn lifecycle + composition
│   │   ├── parse.ts        # pure protocol parsing: fields, prompt envelope, summon/route policy
│   │   ├── invoke-turn.ts  # resolve this platform's attachments for one turn
│   │   ├── turn-store.ts   # telegram's record + update_id arrival order over the generic store
│   │   ├── context-buffer.ts # telegram's entry shape + attachment selection over the generic buffer
│   │   ├── preview.ts      # live-preview pump + terminal-write policy
│   │   ├── telegram-api.ts # the single Bot API pipeline + HTML-aware split
│   │   ├── shared-api.ts   # the ONE transport per state root the channel and the send tool share; records what
│   │   │                   # the agent sends itself into that chat's discussion (no update ever echoes it)
│   │   ├── register-webhook.ts # --tunnel setWebhook registration
│   │   └── scaffold/       # `add telegram` bundle (channel + send tool)
│   ├── slack/              # Slack Agent: native streams + inline tool traces, signed Events API ingress
│   │   ├── slack.ts        # ingress + per-turn lifecycle + composition
│   │   ├── parse.ts, model.ts, reaction.ts # pure protocol parsing/shapes + the reaction vocabulary
│   │   ├── invoke-turn.ts, preview.ts # turn IO + BOTH renderers (native Agent stream, classic edits)
│   │   ├── history.ts      # a place's history: conversations.history (top level) / .replies (a thread)
│   │   ├── slack-api.ts    # the Bot API pipeline (retry, markdown/text splitting, files, history reads)
│   │   ├── shared-api.ts   # the ONE transport per state root the channel and the send tool share
│   │   ├── onboard.ts, setup-server.ts, manifest.ts, config-api.ts, onboarding-state.ts, welcomed.ts,
│   │   │                   # register-webhook.ts # `add slack`: the app-creation flow and what it remembers
│   │   └── scaffold/       # `add slack` bundle (channel + slack-send + slack-threads)
│   ├── feishu/             # CANONICAL Feishu channel engine — see docs/design/core.md
│   │   ├── feishu.ts       # ingress + per-turn lifecycle + composition; Lark binds this engine via a profile
│   │   ├── cloud.ts        # explicit Feishu-reference / Lark-compatibility capability profiles
│   │   ├── model.ts, normalize.ts, parse.ts, crypto.ts, card.ts # protocol/content/policy + security/card
│   │   ├── invoke-turn.ts, preview.ts # turn IO + streaming-card delivery
│   │   ├── history.ts      # a place's history read from the platform (cursor, own-output exclusion, names)
│   │   ├── feishu-api.ts   # canonical Open API pipeline (token cache, retry, cardkit)
│   │   ├── ws-ingress.ts   # the long-connection ingress (the WebSocket form of the same engine)
│   │   ├── setup-mode.ts   # the onboarding choice (webhook vs websocket) + the scopes every agent app asks for
│   │   ├── shared-api.ts   # channel/send-tool transport sharing per cloud and state root
│   │   ├── register-app.ts # `add feishu`: scan-to-create device flow
│   │   ├── register-webhook.ts, bootstrap-token.ts # event URL + token automation
│   │   └── scaffold/       # `add feishu` bundle (channel + feishu-send + feishu-threads)
│   └── lark/               # Lark compatibility/degraded edges over the Feishu engine
│       ├── lark.ts         # thin branded adapter bound to LARK_COMPAT_CLOUD
│       ├── onboard.ts      # unbound launcher + credentials + manual config fallback
│       └── scaffold/       # `add lark` bundle
├── deploy/                 # `deploy docker|fly|railway|agentcore` (core.md §9). Neutral kernel at top, one
│   │                       # directory per host. ADDING A HOST: deploy/hosts.ts says what to write and what
│   │                       # to read first
│   ├── hosts.ts            # DEPLOY_HOSTS, the targets as a value + the add-a-host guide
│   ├── residency.ts        # what forbids scaling to zero: ONE rule every host that can scale reads
│   ├── channel-ingress.ts  # HOW A RUNNING CHANNEL IS REACHED: default route, who can set that URL, the
│   │                       # words when nobody can (or when a box's login stopped registration). Consumed by
│   │                       # every host AND by the serving path
│   ├── registration-gate.ts # host-neutral step-7 gate policy over the registrars' facts
│   ├── preflight.ts        # host-neutral pre-flight: the definition builds, its model exists and authenticates
│   │                       # where it runs, channel discovery, warnings
│   ├── build-context.ts    # what the build context holds that must not ship, and what a KEPT ignore file lets through
│   ├── container.ts        # portable image + ignore files + release manifest (host-neutral), and the one command
│   │                       # that runs `login --stdio` inside that image where its server runs
│   ├── workspace.ts        # the deployed lifecycle every host shares: assert the storage is MOUNTED, one
│   │                       # process lease, recoverable definition replacement (definition/ is cwd; .state/
│   │                       # and .secrets/ stay beside it)
│   ├── secrets.ts          # both directions of the value carry: the NAMES a runbook lists, the VALUES
│   │                       # `--run` sends, and the FASTAGENT_ENV the container expands back
│   ├── runner.ts           # the shared host-CLI dispatcher seam (CliRunner + spawnRunner; faked in tests)
│   ├── box-shell.ts        # a running box's owner-authenticated shell as a byte channel (`login --deployment`)
│   ├── docker/    { plan.ts, run.ts } # Compose topology (agent + optional Quick Tunnel) + the compose driver
│   ├── fly/       { plan.ts, run.ts } # artifacts + runbook (pure) + the flyctl driver
│   ├── railway/   { plan.ts, run.ts } # same two roles — NOT a copy of Fly (thin config, minted URL)
│   └── agentcore/ { plan.ts, run.ts, destroy.ts, aws-cli.ts, logs.ts, shell.ts, zip.ts, forwarder.js } # ONE stack:
│                             # runtime + forwarder Lambda (webhooks, and the alarms the container sets). No public
│                             # URL, no resident process, no volume — the facts every difference follows from.
│                             # destroy.ts is the other direction, and it exists because three of the four
│                             # resources cannot be stack resources. aws-cli.ts owns what ONE AWS CLI result
│                             # MEANS — there / gone / could not find out — because eleven call sites each
│                             # deciding that produced the same defect five review rounds running. Every AWS
│                             # read that asks "is it there, and could I tell" goes through it. shell.ts is the
│                             # command-shell WebSocket `login --deployment` speaks (SigV4 presigned, AWS CLI creds)
├── schedule/               # the N axis: prompts on a cron and the clock that fires them
│   ├── schedule.ts         # a schedule as built ({ name, cron, tz?, prompt }) from `defineSchedule` in src/schedules/
│   ├── cron.ts             # the one place touching `croner`: nextRun + cronError
│   ├── scheduler.ts        # the resident clock loops + claim/run/settle over the Agent API: a schedule is refused
│   │                       # by a busy session (skipped), a wake-up queues; stop cancels waits, runs go on;
│   │                       # fireScheduleNow, one fire outside the clock (`schedules run`)
│   ├── wakeups.ts          # the agent's self-scheduled wake-ups: neutral store + guardrails
│   ├── wake-alarm.ts       # the EXTERNAL-clock form of both: schedules as recurring EventBridge schedules,
│   │                       # wake-ups as one-shots
│   ├── eventbridge-cron.ts # a cron in EventBridge's dialect; the build refuses what it cannot express
│   └── state.ts            # schedule state under <stateRoot>/schedule/, incl. THE claim: the decision to fire,
│                           # the outcome written back into it, and therefore the whole (bounded) fire history
└── harnesses/              # the only directory that imports @earendil-works/pi-*
    ├── pi-durable/         # the Agent API on pi-durable, in process
    │   ├── open.ts         # a definition (config + generated registry) assembled into an Agent; the secrets
    │   │                   # gate and manifest; pi-ai's built-in models with the definition's providers
    │   ├── serve.ts        # openServing: a directory opened to be served (definition, code, models, content,
    │   │                   # storage, Agent) — what dev, start, AgentCore and an embedder open through; holding
    │   │                   # the instance for a command that writes its state outside a serve
    │   ├── storage.ts      # a SQLite database one process holds (the instance's, `invoke`'s), and its lock
    │   │                   # where SQLite's own locks fail
    │   ├── define.ts       # what an author writes: defineAgent, needs (secrets beside the code that reads them),
    │   │                   # defineSchedule
    │   ├── registry.ts     # the generated `.fastagent/registry.ts`: one default import per module of src/
    │   ├── text.ts         # SYSTEM.md, AGENTS.md, skills (loaded as pi loads them) and prompt templates, read per
    │   │                   # message; the deployed agent's self-change section
    │   ├── agent.ts        # openDurableAgent: a Harness on the instance's storage, and the ten operations over it
    │   ├── reads.ts        # what the operations and resume read: a session's conversation, its published entries,
    │   │                   # a message's status and end, the session's state
    │   ├── resume.ts       # resume: the replay, the `state` snapshot, then what each commit adds
    │   ├── sessions.ts     # which conversations are sessions (a subagent's is not) and each one's latest activity,
    │   │                   # its newest own id: a cache read at open and moved by every commit, which every
    │   │                   # operation and listSessions read
    │   ├── entries.ts      # pi-durable's entries as published entries, and the entry kinds FastAgent writes
    │   ├── messages.ts     # input submissions as messages: request ids, statuses, outcomes, the session's state
    │   ├── ids.ts          # every id as the storage's incarnation plus pi-durable's id, so none is ever reused;
    │   │                   # listSessions' cursors, which no id reads as; the session id a tool runs in
    │   ├── wake.ts         # `wake` and `unwake` as pi-durable tools, installed when a serve gives the state root
    │   ├── defaults.ts     # the deployment's default model and thinking level, for a conversation that names none
    │   └── release.ts      # temporary: places the messages a run that did not answer left waiting
    └── models/             # the model environment: pi-ai's models, credentials and sign-in
        ├── models.ts       # pi-ai's model collection as FastAgent composes it (built-ins over a credential store,
        │                   # the definition's providers), and the reads a report, a login or a picker make of it
        ├── credentials.ts  # the credentials file store + which files (layers) an agent reads
        ├── environment.ts  # an agent's model environment as ONE value (credential store + models + auth status):
        │                   # every reader builds it here, never from the parts
        └── login.ts        # signing in to a model provider, for any front end; `fastagent login` is one
test/                       # vitest; faux models by default
├── agent-api-conformance.ts # the Agent API's conformance suite (docs/SPEC.md §9), run in process by
│                           # durable-agent.test.ts over durable-subject.ts
├── scripted-agent.ts       # an Agent whose answers a test scripts: what channel, schedule and service tests run on
├── embedding.test.ts       # the docs/embedding.md snippets against REAL express/fastify (why they are devDeps)
└── live/                   # probes for what the offline suite FAKES — see test/live/README.md
docs/                       # SPEC, guides, and maintainer design notes (design/core.md = architecture)