# Dawn

Dawn is a TypeScript-first meta-framework for building graph-based AI agents with the ergonomics of Next.js: file-system routing, shared and route-local tools with inferred types, scenario testing, route-level agent features, durable threads, and Dawn HTTP runtimes for development and deployment.

## Install and activate the default research starter
```
npm create dawn-ai-app@latest my-agent
cd my-agent
npm install
npm run typegen
npm run check
npm run typecheck
npm test
npm run eval
cp .env.example .env
# Add a real OPENAI_API_KEY to .env
npm run verify
npm run dev
```
Requires Node.js 24 or later and npm 11. The tests and eval run offline with deterministic fixtures; live activation requires the real provider key and serves on http://127.0.0.1:3000.

## Project Shape
- `dawn.config.ts` at repo root. Supported keys include `appDir`, `backends`, `permissions`, `checkpointer`, `threadsStore`, `env`, `toolOutput`, `summarization`, `sandbox`, `memory`, and `build`.
- `src/app/**/index.ts` — route entry; exports exactly one of default `agent(...)`, named `workflow` (async function), named `graph` (LangGraph graph), or named `chain` (LangChain LCEL Runnable).
- `src/app/**/state.ts` — optional Zod route state schema.
- `src/tools/*.ts` — shared authored tools available to routes by default; the research scaffold keeps `searchCorpus` and `readDoc` here.
- `src/app/**/tools/*.ts` — route-local authored tools; visible only to that route and shadow same-named shared tools. Tool default exports are async functions and their types are inferred.
- `workspace/AGENTS.md` — optional app-workspace prompt guidance, re-read on every turn and shared by consuming agent routes and subagents; it is not route-local.
- `src/app/**/memory.md` — optional stable prompt memory for one route. The default research scaffold includes it.
- `src/app/**/memory.ts` — optional typed long-term memory collection; contributes `recall` and `remember`. The default research scaffold includes it.
- `src/app/**/plan.md` — optional route-local planning seed; contributes todo state, `writeTodos`, and `plan_update` but is not itself updated at runtime.
- `src/app/**/skills/<name>/SKILL.md` — optional route-local instructions loaded on demand through `readSkill`.
- `src/app/**/subagents/<name>/index.ts` — optional immediate child agent routes exposed through `task`; children get shared and their own route-local tools, not the parent's local tools.
- `agent({ reasoning })` — optional OpenAI-backed reasoning-effort configuration.
- `src/app/**/run.test.ts` — colocated scenario tests.
- `.dawn/dawn.generated.d.ts` — auto-generated ambient types. Never edit by hand.

## Pathname Rules
- Directory path becomes URL pathname.
- `(public)` — route group; excluded from pathname.
- `[tenant]` — dynamic segment preserved in the route id; provide the value in JSON input.
- Default scaffold example: `src/app/research/index.ts` → `/research`; agent route key `/research#agent`.
- Optional basic scaffold example: `src/app/(public)/hello/[tenant]/index.ts` → `/hello/[tenant]`.

## Minimal Agent Route
```ts
import { agent } from "@dawn-ai/sdk"

export default agent({
  model: "gpt-5-mini",
  systemPrompt: "You are a research coordinator. Search the local corpus, dispatch specialists when useful, and cite every claim.",
})
```

## Minimal Tool
```ts
// src/tools/searchCorpus.ts (shared; the default research scaffold uses this location)
export default async (input: { readonly query: string }) => {
  return [{ path: "corpus/agent-architectures.md", score: 2, snippet: "ReAct and plan-and-execute are common agent architectures." }]
}
```

## Commands
- `dawn add` — list the blueprint catalog; `dawn add <name-or-url>` — fetch and print an integration blueprint for an agent to apply
- `dawn build` — emit configured deployment targets (`node` + `langsmith` by default; `hono` opt-in)
- `dawn check` — validate app structure/config
- `dawn dev` — local Agent Protocol runtime server
- `dawn docs [topic]` — print local documentation snippets
- `dawn eval [path]` — run eval definitions
- `dawn inspect` — open the optional Dawn Inspector browser UI
- `dawn memory [subcommand] [args...]` — inspect and manage long-term memory
- `dawn routes` — list discovered routes
- `dawn run <routePath>` — execute a route with JSON stdin/stdout
- `dawn start` — serve the Dawn Node runtime in production (default `0.0.0.0:8000`)
- `dawn test [path]` — run scenarios
- `dawn typegen` — regenerate `.dawn/dawn.generated.d.ts`
- `dawn verify` — run five phases: app discovery, route discovery, type generation, dependency/environment advisories, and runtime readiness
- `echo '{"messages":[{"role":"user","content":"What are common agent architectures?"}]}' | dawn run /research` — execute the default scaffold route

## Agent Protocol
- `GET /healthz`
- `POST /threads`
- `GET /threads/:thread_id`
- `DELETE /threads/:thread_id`
- `POST /threads/:thread_id/cancel`
- `POST /threads/:thread_id/runs/wait`
- `POST /threads/:thread_id/runs/stream`
- `GET /threads/:thread_id/state`
- `POST /threads/:thread_id/resume`
- `GET /memory/candidates`
- `POST /memory/candidates/:id/approve`
- `POST /memory/candidates/:id/reject`
- Run body: `{ "route": "/research#agent", "input": { "messages": [{ "role": "user", "content": "What are common agent architectures?" }] } }`
- Resume body: `{ "resume": [{ "interruptId": "<id>", "status": "resolved", "payload": "once" | "always" | "deny" }], "route": "/research#agent" }`; the strict envelope must address every currently pending interrupt exactly once. Nested interrupts resume through the root thread.
- App middleware gates execution routes, not the whole server. The middleware-bypassing management routes are thread create/read/delete/state/cancel plus all memory-candidate routes; candidate listing spans namespaces, while approve/reject mutate records. Health also bypasses middleware for readiness probes. Any non-local exposure requires reverse-proxy or platform authentication and network restrictions covering the entire service.

## Runtime Capabilities
- `toolOutput` offloads large tool results into `workspace/tool-outputs/` and keeps an in-context preview.
- `summarization` is opt-in and compresses older thread history when configured.
- `memory` enables typed long-term recall/write governance through route-local memory definitions.
- `sandbox` configures isolated execution for workspace commands where supported.

## Documentation map
- [Getting Started](https://dawnai.org/docs/getting-started) — scaffold, verify offline, and make the first keyed live run.
- [Add a Tool](https://dawnai.org/docs/recipes/add-a-tool) — build the first typed application feature.
- [Memory](https://dawnai.org/docs/memory) — choose prompt context, typed long-term memory, retrieval, episodes, or distillation.
- [Agent Protocol](https://dawnai.org/docs/dev-server/agent-protocol) — integrate a client with thread and run endpoints.
- [Embed the Runtime](https://dawnai.org/docs/embedding) — host Dawn inside an existing server.
- [Fixtures and Recording](https://dawnai.org/docs/testing-agents/fixtures) — replay deterministic fixtures or record local model calls.
- [Persistence and Tenancy](https://dawnai.org/docs/persistence) — choose durable stores and tenant boundaries.
- [Production Topology](https://dawnai.org/docs/production-topology) — place runtimes, stores, proxies, and workers.
- [Security Architecture](https://dawnai.org/docs/security-architecture) — review trust boundaries before exposure.
- [Deployment Options](https://dawnai.org/docs/deployment) — select Node and Docker, Kubernetes, LangSmith, or edge deployment.
- [Configuration Reference](https://dawnai.org/docs/configuration) — inspect every supported configuration key.
- [CLI Reference](https://dawnai.org/docs/cli) — use the local development, test, build, and operations commands.
- [API Reference](https://dawnai.org/docs/api) — inspect exported application-facing types and functions.

## Packages
- `@dawn-ai/sdk` — authoring contract (types, `RuntimeContext`, test helpers)
- `@dawn-ai/langgraph` — LangGraph graphs/workflows adapter
- `@dawn-ai/langchain` — LangChain LCEL adapter and provider-aware agent materialization
- `@dawn-ai/cli` — the `dawn` CLI

## Deployment
Choose targets with `build.targets` (the list replaces the defaults). `node` emits a Node >=24 Dawn HTTP server plus a marker-managed Dockerfile for self-hosting; the research scaffold's `npm start` script loads `.env` before serving the emitted artifact, while bare `dawn start` does not load `config.env`. Supply secrets in the runtime environment when invoking the CLI directly or running the emitted image. `hono` is opt-in for compatible edge apps after `DAWN_E1005` capability validation; it serves Agent Protocol and AG-UI with generated Postgres stores, but no filesystem, shell, sandbox, tool-output offloading, skills, or typed long-term memory, and its run/cancel registry is isolate-local. `langsmith` emits `langgraph.json` and generated graph entries rather than the Dawn HTTP server; middleware, AG-UI, and the sandbox manager are absent, and its current `node_version: "22"` conflicts with Dawn packages' Node >=24 requirement.

## Task-Specific Prompts
Copy-ready prompts for common tasks:
- Scaffold: https://dawnai.org/prompts/scaffold
- Add a tool: https://dawnai.org/prompts/add-a-tool
- Write a route: https://dawnai.org/prompts/write-a-route
- Write a test: https://dawnai.org/prompts/write-a-test
- Deploy: https://dawnai.org/prompts/deploy

## Agent Config Templates
Drop-in agent configuration for a Dawn project:
- https://dawnai.org/AGENTS.md

## Brand Assets
Official Dawn AI logos, icons, favicons, and social assets:
- Asset manifest: https://dawnai.org/brand/assets.json
- Full brand kit ZIP: https://dawnai.org/brand/dawn-ai-brand-assets.zip

## Full Reference
https://dawnai.org/llms-full.txt

## Source
https://github.com/cacheplane/dawnai
## Blog

- [Eve validates the shape. Now pick your runtime.](https://dawnai.org/blog/eve-validates-the-shape): Vercel shipped eve, an open-source agent framework where each agent is a directory of files. It looks great, and it confirms the thesis behind Dawn. Here is an honest side-by-side, and where Dawn fits.
- [The App Router for AI Agents](https://dawnai.org/blog/app-router-for-ai-agents): File-system routes, type-safe tools, and the capability layer Dawn adds around real LangGraph.js agent applications.
- [Why we built Dawn](https://dawnai.org/blog/why-we-built-dawn): Dawn is a TypeScript-first framework for building LangGraph.js agents with file-system routes, route-local tools, generated types, and a local dev loop.