LOU-W4, LOU-W7: sessions for createAgent; AGENTS.md auto-loading

README.md

@@ -22,6 +22,8 @@ dashboard — any provider, any deploy target, no lock-in.
 - **Human-in-the-loop** — flag a tool `needsApproval` and pause execution until a human approves or rejects it, then `resumeAfterApproval()` from any process
 - **Durable execution** — pass a `sessionId` + `checkpointStore` and a crash mid-conversation resumes instead of restarting
 - **Cancellation** — pass an `AbortSignal` (`agent.send(input, { signal })`) to stop a run; it resolves with `finishReason: 'aborted'` and the transcript so far, and the signal reaches the provider, tools and delegated agents
+- **Sessions** — `agent.session()` keeps a multi-turn conversation (in memory, or persisted with `FileSessionStore`)
+- **Project instructions** — `createAgent({ projectInstructions: true })` appends the nearest `AGENTS.md` / `CLAUDE.md` to the instructions (opt-in)
 - **Parallel tool calls** — when the model asks for several tools in one turn they run concurrently (cap it with `toolConcurrency`, or `1` for sequential), and results still reach the transcript in the model's call order
 - **Skills** — `defineSkill()` / `loadSkills('./skills')`: only each skill's name and description sit in the system prompt; the model loads the full markdown on demand through an auto-registered `load_skill` tool
 - **Multi-agent delegation** — wrap a child agent as a tool with `createDelegateTool()`, with a `maxDepth` guard against delegation loops
@@ -206,6 +208,17 @@ console.log(result.text);
 console.log(result.usage.totalTokens, result.finishReason, result.steps);
 ```
 
+### Multi-turn sessions
+
+```ts
+import { createAgent } from '@loushy/build-ai-agent';
+
+const session = createAgent({ provider }).session(); // or .session({ id, store: new FileSessionStore(dir) })
+await session.send('My name is Ali.');
+const { text } = await session.send('What is my name?'); // remembers
+console.log(session.id, session.messages.length);
+```
+
 ## Documentation
 
 - [Installation](docs/installation.md) - requirements, peer/provider packages, installing from a local build
@@ -216,6 +229,7 @@ console.log(result.usage.totalTokens, result.finishReason, result.steps);
 - [Workspace tools](docs/workspace-tools.md) - file system and shell tools for coding agents, and their security model
 - [Tracing and observability](docs/observability.md) - OpenTelemetry GenAI spans, attribute table, content opt-in
 - [Testing](docs/testing.md) - unit-test agents deterministically with the scripted `mockModel`
+- [Sessions](docs/sessions.md) - multi-turn conversations: `agent.session()`, `MemorySessionStore`, `FileSessionStore`
 - [Skills](docs/skills.md) - on-demand instructions: `defineSkill()`, `loadSkills()`, how they save context
 - [Agent Forge](docs/agent-forge.md) - the visual dashboard (`loushy studio`): quickstart, first-agent walkthrough, hook authoring
 - Full guides site: [linuxdevil.github.io/agent-sdk-docs](https://linuxdevil.github.io/agent-sdk-docs/)

docs/configuration.md

@@ -145,6 +145,7 @@ what the examples and the Quick Start use by default.
 | `tools`    | `Record<string, ToolDescriptor>`, keyed by the name the agent uses. |
 | `name`     | Agent name (default `'agent'`).                                    |
 | `maxSteps` | Passed through to `AgentExecutor.execute()`.                        |
+| `projectInstructions` | `true` or `{ cwd?, files? }`: append the nearest `AGENTS.md` / `CLAUDE.md` to the instructions (off by default; see [Project instructions](#project-instructions)). |
 
 With neither `model` nor `provider`, `createAgent()` resolves from the
 environment: `LOUSHY_MODEL` (a `'provider/model'` string) if set, otherwise
@@ -159,6 +160,35 @@ variable (`createAgent: OPENAI_API_KEY is not set. ...`), an unknown prefix
 lists the supported ones and suggests the closest, and a missing optional peer
 dependency prints the exact `npm install` command.
 
+## Project instructions
+
+Many repositories keep guidance for coding agents in an `AGENTS.md` (or
+`CLAUDE.md`) file. `createAgent` can append it to the agent's instructions:
+
+```ts
+import { createAgent } from '@loushy/build-ai-agent';
+
+const agent = createAgent({
+  instructions: 'You review pull requests.',
+  provider,
+  projectInstructions: true, // or { cwd: './packages/api', files: ['AGENTS.md'] }
+});
+```
+
+The file is added after your own instructions under the heading
+`## Project instructions (from AGENTS.md)`. It is read once, when the agent is
+created. The lookup walks up from `cwd` (default `process.cwd()`) and uses the
+nearest directory that has one of `files` (default `['AGENTS.md', 'CLAUDE.md']`,
+first match wins), stopping at the nearest directory that contains `.git` or at
+the filesystem root. Content over 32,000 characters is cut with a truncation
+marker. If no file is found nothing is added.
+
+This is **opt-in** on purpose: reading files from disk by default would surprise
+people who embed the SDK in a server, where the working directory is not the
+project the agent is about. To find the file yourself (for example to show it),
+use `loadProjectInstructions({ cwd, files, stopAt, maxChars })`, which returns
+`{ path, content }` or `undefined`.
+
 ## `AgentExecutor.execute()` options
 
 `AgentExecutor` is static: call `AgentExecutor.execute(options)`. Only

docs/sessions.md

@@ -0,0 +1,84 @@
+# Sessions
+
+`agent.send(text)` is single-turn: every call starts from an empty history. A
+**session** is a multi-turn conversation: it keeps the transcript and passes it
+to the model on every `send()`.
+
+```ts
+import { createAgent } from '@loushy/build-ai-agent';
+
+const chat = createAgent({ instructions: 'Be brief.', provider });
+
+const session = chat.session(); // in memory, new generated id
+await session.send('My name is Ali.');
+const { text } = await session.send('What is my name?'); // sees the first exchange
+
+console.log(session.id, session.messages.length);
+```
+
+## The session object
+
+| Member | Description |
+| ------ | ----------- |
+| `id` | The session id: generated (a UUID) unless you pass one. |
+| `send(input, { signal })` | Sends a user message with the whole conversation so far and resolves with the usual `ExecutionResult`. |
+| `messages` | A read-only snapshot of the transcript (user, assistant and tool messages; no system prompt). Editing the snapshot does not change the session. |
+| `load()` | Reads the saved transcript from the store. `send()` does this for you; call it to show history before the first `send()` of a resumed session. |
+| `clear()` | Forgets the conversation, including in the store. |
+
+Concurrent `send()` calls on one session are queued and run one after another in
+call order, so the transcript never interleaves.
+
+A `send()` that throws (a provider error, or a tool that throws a
+`PropagatingToolError`) or is aborted with `signal` leaves the transcript
+exactly as it was before that call. An aborted `send()` resolves with
+`finishReason: 'aborted'`, as `agent.send()` does. The stored transcript never
+contains an assistant tool-call turn without the matching tool results.
+
+Sessions are a thin layer: the session owns the transcript and hands it to the
+executor on each turn. They do not use the checkpoint/resume mechanism
+(`sessionId` + `checkpointStore` on `AgentExecutor.execute()`), which is for
+resuming one interrupted run, not for continuing a conversation.
+
+## Stores
+
+A `SessionStore` keeps transcripts between calls:
+
+```ts
+import type { Message } from '@loushy/build-ai-agent';
+
+interface SessionStore {
+  load(id: string): Promise<Message[] | undefined>;
+  save(id: string, messages: readonly Message[]): Promise<void>;
+  delete(id: string): Promise<void>;
+}
+```
+
+- `MemorySessionStore` (the default, one new store per session) lives as long as
+  the process. Share one instance between sessions to look them up by id.
+- `FileSessionStore(dir)` writes one JSON file per session (`<dir>/<id>.json`),
+  atomically (temp file, then rename), creating `dir` on first save.
+
+```ts
+import { createAgent, FileSessionStore } from '@loushy/build-ai-agent';
+
+const agent = createAgent({ provider });
+const store = new FileSessionStore('./.loushy/sessions');
+
+const first = agent.session({ id: 'user-42', store });
+await first.send('My name is Ali.');
+
+// Later, even in another process or another createAgent() instance:
+const again = agent.session({ id: 'user-42', store });
+await again.send('What is my name?'); // "Ali"
+```
+
+Session ids must match `^[A-Za-z0-9_-]{1,128}$` (they become file names, so
+`../x` and `a/b` are refused with an error that says so). Implement
+`SessionStore` yourself to keep transcripts in a database or Redis.
+
+## Project instructions
+
+Not part of sessions, but often wanted together: see "Project instructions" in
+[Configuration](configuration.md) to give an agent your repository's
+`AGENTS.md`.

llms-full.txt

@@ -20,6 +20,8 @@ dashboard — any provider, any deploy target, no lock-in.
 - **Human-in-the-loop** — flag a tool `needsApproval` and pause execution until a human approves or rejects it, then `resumeAfterApproval()` from any process
 - **Durable execution** — pass a `sessionId` + `checkpointStore` and a crash mid-conversation resumes instead of restarting
 - **Cancellation** — pass an `AbortSignal` (`agent.send(input, { signal })`) to stop a run; it resolves with `finishReason: 'aborted'` and the transcript so far, and the signal reaches the provider, tools and delegated agents
+- **Sessions** — `agent.session()` keeps a multi-turn conversation (in memory, or persisted with `FileSessionStore`)
+- **Project instructions** — `createAgent({ projectInstructions: true })` appends the nearest `AGENTS.md` / `CLAUDE.md` to the instructions (opt-in)
 - **Parallel tool calls** — when the model asks for several tools in one turn they run concurrently (cap it with `toolConcurrency`, or `1` for sequential), and results still reach the transcript in the model's call order
 - **Skills** — `defineSkill()` / `loadSkills('./skills')`: only each skill's name and description sit in the system prompt; the model loads the full markdown on demand through an auto-registered `load_skill` tool
 - **Multi-agent delegation** — wrap a child agent as a tool with `createDelegateTool()`, with a `maxDepth` guard against delegation loops
@@ -204,6 +206,17 @@ console.log(result.text);
 console.log(result.usage.totalTokens, result.finishReason, result.steps);
 ```
 
+### Multi-turn sessions
+
+```ts
+import { createAgent } from '@loushy/build-ai-agent';
+
+const session = createAgent({ provider }).session(); // or .session({ id, store: new FileSessionStore(dir) })
+await session.send('My name is Ali.');
+const { text } = await session.send('What is my name?'); // remembers
+console.log(session.id, session.messages.length);
+```
+
 ## Documentation
 
 - [Installation](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/installation.md) - requirements, peer/provider packages, installing from a local build
@@ -214,6 +227,7 @@ console.log(result.usage.totalTokens, result.finishReason, result.steps);
 - [Workspace tools](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/workspace-tools.md) - file system and shell tools for coding agents, and their security model
 - [Tracing and observability](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/observability.md) - OpenTelemetry GenAI spans, attribute table, content opt-in
 - [Testing](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/testing.md) - unit-test agents deterministically with the scripted `mockModel`
+- [Sessions](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/sessions.md) - multi-turn conversations: `agent.session()`, `MemorySessionStore`, `FileSessionStore`
 - [Skills](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/skills.md) - on-demand instructions: `defineSkill()`, `loadSkills()`, how they save context
 - [Agent Forge](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/agent-forge.md) - the visual dashboard (`loushy studio`): quickstart, first-agent walkthrough, hook authoring
 - Full guides site: [linuxdevil.github.io/agent-sdk-docs](https://linuxdevil.github.io/agent-sdk-docs/)
@@ -1949,6 +1963,7 @@ what the examples and the Quick Start use by default.
 | `tools`    | `Record<string, ToolDescriptor>`, keyed by the name the agent uses. |
 | `name`     | Agent name (default `'agent'`).                                    |
 | `maxSteps` | Passed through to `AgentExecutor.execute()`.                        |
+| `projectInstructions` | `true` or `{ cwd?, files? }`: append the nearest `AGENTS.md` / `CLAUDE.md` to the instructions (off by default; see [Project instructions](#project-instructions)). |
 
 With neither `model` nor `provider`, `createAgent()` resolves from the
 environment: `LOUSHY_MODEL` (a `'provider/model'` string) if set, otherwise
@@ -1963,6 +1978,35 @@ variable (`createAgent: OPENAI_API_KEY is not set. ...`), an unknown prefix
 lists the supported ones and suggests the closest, and a missing optional peer
 dependency prints the exact `npm install` command.
 
+## Project instructions
+
+Many repositories keep guidance for coding agents in an `AGENTS.md` (or
+`CLAUDE.md`) file. `createAgent` can append it to the agent's instructions:
+
+```ts
+import { createAgent } from '@loushy/build-ai-agent';
+
+const agent = createAgent({
+  instructions: 'You review pull requests.',
+  provider,
+  projectInstructions: true, // or { cwd: './packages/api', files: ['AGENTS.md'] }
+});
+```
+
+The file is added after your own instructions under the heading
+`## Project instructions (from AGENTS.md)`. It is read once, when the agent is
+created. The lookup walks up from `cwd` (default `process.cwd()`) and uses the
+nearest directory that has one of `files` (default `['AGENTS.md', 'CLAUDE.md']`,
+first match wins), stopping at the nearest directory that contains `.git` or at
+the filesystem root. Content over 32,000 characters is cut with a truncation
+marker. If no file is found nothing is added.
+
+This is **opt-in** on purpose: reading files from disk by default would surprise
+people who embed the SDK in a server, where the working directory is not the
+project the agent is about. To find the file yourself (for example to show it),
+use `loadProjectInstructions({ cwd, files, stopAt, maxChars })`, which returns
+`{ path, content }` or `undefined`.
+
 ## `AgentExecutor.execute()` options
 
 `AgentExecutor` is static: call `AgentExecutor.execute(options)`. Only
@@ -2361,6 +2405,93 @@ them as LLM, agent and tool calls with token usage; others show them as
 ordinary spans with attributes. Which conventions a given backend supports,
 and which version of them, varies; check its documentation.
 
+# Sessions
+
+Source: docs/sessions.md
+
+`agent.send(text)` is single-turn: every call starts from an empty history. A
+**session** is a multi-turn conversation: it keeps the transcript and passes it
+to the model on every `send()`.
+
+```ts
+import { createAgent } from '@loushy/build-ai-agent';
+
+const chat = createAgent({ instructions: 'Be brief.', provider });
+
+const session = chat.session(); // in memory, new generated id
+await session.send('My name is Ali.');
+const { text } = await session.send('What is my name?'); // sees the first exchange
+
+console.log(session.id, session.messages.length);
+```
+
+## The session object
+
+| Member | Description |
+| ------ | ----------- |
+| `id` | The session id: generated (a UUID) unless you pass one. |
+| `send(input, { signal })` | Sends a user message with the whole conversation so far and resolves with the usual `ExecutionResult`. |
+| `messages` | A read-only snapshot of the transcript (user, assistant and tool messages; no system prompt). Editing the snapshot does not change the session. |
+| `load()` | Reads the saved transcript from the store. `send()` does this for you; call it to show history before the first `send()` of a resumed session. |
+| `clear()` | Forgets the conversation, including in the store. |
+
+Concurrent `send()` calls on one session are queued and run one after another in
+call order, so the transcript never interleaves.
+
+A `send()` that throws (a provider error, or a tool that throws a
+`PropagatingToolError`) or is aborted with `signal` leaves the transcript
+exactly as it was before that call. An aborted `send()` resolves with
+`finishReason: 'aborted'`, as `agent.send()` does. The stored transcript never
+contains an assistant tool-call turn without the matching tool results.
+
+Sessions are a thin layer: the session owns the transcript and hands it to the
+executor on each turn. They do not use the checkpoint/resume mechanism
+(`sessionId` + `checkpointStore` on `AgentExecutor.execute()`), which is for
+resuming one interrupted run, not for continuing a conversation.
+
+## Stores
+
+A `SessionStore` keeps transcripts between calls:
+
+```ts
+import type { Message } from '@loushy/build-ai-agent';
+
+interface SessionStore {
+  load(id: string): Promise<Message[] | undefined>;
+  save(id: string, messages: readonly Message[]): Promise<void>;
+  delete(id: string): Promise<void>;
+}
+```
+
+- `MemorySessionStore` (the default, one new store per session) lives as long as
+  the process. Share one instance between sessions to look them up by id.
+- `FileSessionStore(dir)` writes one JSON file per session (`<dir>/<id>.json`),
+  atomically (temp file, then rename), creating `dir` on first save.
+
+```ts
+import { createAgent, FileSessionStore } from '@loushy/build-ai-agent';
+
+const agent = createAgent({ provider });
+const store = new FileSessionStore('./.loushy/sessions');
+
+const first = agent.session({ id: 'user-42', store });
+await first.send('My name is Ali.');
+
+// Later, even in another process or another createAgent() instance:
+const again = agent.session({ id: 'user-42', store });
+await again.send('What is my name?'); // "Ali"
+```
+
+Session ids must match `^[A-Za-z0-9_-]{1,128}$` (they become file names, so
+`../x` and `a/b` are refused with an error that says so). Implement
+`SessionStore` yourself to keep transcripts in a database or Redis.
+
+## Project instructions
+
+Not part of sessions, but often wanted together: see "Project instructions" in
+[Configuration](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/configuration.md) to give an agent your repository's
+`AGENTS.md`.
+
 # Skills
 
 Source: docs/skills.md

llms.txt

@@ -10,6 +10,7 @@
 - [API Overview](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/api-overview.md): The package root (`@loushy/build-ai-agent`) exports everything below.
 - [Configuration](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/configuration.md): A declarative agent is a YAML (`.yaml`/`.yml`) or JSON (`.json`) file, validated with zod by `loadSpec()` (`src/spec/schema.ts`).
 - [Tracing and observability](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/observability.md): `AgentExecutor.execute()` and `FlowExecutor.execute()` emit spans through a `TraceExporter`.
+- [Sessions](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/sessions.md): `agent.send(text)` is single-turn: every call starts from an empty history.
 - [Skills](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/skills.md): A skill is a named chunk of instructions (a markdown document) that the model loads only when it needs it.
 - [Testing agents](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/testing.md): `@loushy/build-ai-agent/testing` ships `mockModel`: a scripted, deterministic `LLMProvider` for unit tests.
 - [Workspace tools](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/workspace-tools.md): Workspace tools give an agent a file system and a shell, so you can build coding agents in the style of Claude Code.