apex-code 0.5.0 → 0.5.1

package/docs/sdk.md

@@ -109,6 +109,8 @@ interface AgentSession {
 
   // State access
   agent: Agent;
+  sessionManager: SessionManager;
+  refreshContext(): void;
   model: Model | undefined;
   thinkingLevel: ThinkingLevel;
   messages: AgentMessage[];
@@ -129,6 +131,8 @@ interface AgentSession {
 }
 ```
 
+`session.navigateTree()` rejects while an agent response, manual or automatic compaction, or another tree navigation is active, even with `summarize: false`. It does not queue navigation or return `{ cancelled: true }` for these conflicts. Wait for the active operation to finish (for example, with `await session.waitForIdle()`) and retry. Rejection leaves the active branch unchanged.
+
 Session replacement APIs such as new-session, resume, fork, and import live on `AgentSessionRuntime`, not on `AgentSession`.
 
 ### createAgentSessionRuntime() and AgentSessionRuntime
@@ -262,13 +266,13 @@ const state = session.agent.state;
 // state.messages: AgentMessage[] - conversation history
 // state.model: Model - current model
 // state.thinkingLevel: ThinkingLevel - current thinking level
-// state.systemPrompt: string - system prompt
-// state.tools: AgentTool[] - available tools
+// state.systemPrompt: string - read-only, replayed from the transcript's system messages
+// state.tools: AgentTool[] - executable tools; changes are declared to the model before the next request
 // state.streamingMessage?: AgentMessage - current partial assistant message
 // state.errorMessage?: string - latest assistant error
 
-// Replace messages (useful for branching or restoration)
-session.agent.state.messages = messages; // copies the top-level array
+// Model-visible messages are projected from session.sessionManager.
+// agent.state.messages is a refreshed inspection cache; do not assign it for restoration.
 
 // Replace tools
 session.agent.state.tools = tools; // copies the top-level array
@@ -277,6 +281,15 @@ session.agent.state.tools = tools; // copies the top-level array
 await session.agent.waitForIdle();
 ```
 
+Provider requests use `session.sessionManager` as the canonical finalized context. Assigning `session.agent.state.messages` does not replace persisted context and may be overwritten at the next request boundary. Restore externally stored history when constructing the session instead:
+
+```typescript
+const restoredManager = SessionManager.inMemory(process.cwd(), { id: sessionId }, entries);
+const { session } = await createAgentSession({ sessionManager: restoredManager });
+```
+
+For an existing session, use `session.navigateTree(entryId)` to move its active branch. Use `session.sessionManager.appendMessage(...)` plus `session.refreshContext()` only when intentionally appending externally managed entries.
+
 ### Events
 
 Subscribe to events to receive streaming output and lifecycle notifications.
@@ -427,7 +440,7 @@ If no model is provided:
 2. Uses default from settings
 3. Falls back to first available model
 
-Remote catalogs are persisted locally so later runtimes can restore them without a network request. The default file is `~/.pi/agent/models-store.json`; set `modelsStorePath` to choose another location, or inject `modelsStore` to control persistence. Network refreshes are throttled to once per provider every four hours unless forced. To force an immediate refresh, call `await modelRuntime.refresh({ allowNetwork: true, force: true, signal })`. Setting `PI_OFFLINE` disables model network access.
+Remote catalogs are persisted locally so later runtimes can restore them without a network request. The default file is `~/.apex-code/agent/models-store.json`; set `modelsStorePath` to choose another location, or inject `modelsStore` to control persistence. Network refreshes are throttled to once per provider every four hours unless forced. To force an immediate refresh, call `await modelRuntime.refresh({ allowNetwork: true, force: true, signal })`. Setting `APEX_CODE_OFFLINE=1` disables model network access; `PI_OFFLINE=1` remains a compatibility alias.
 
 To match CLI model parsing, use the exported resolver helpers:
 
@@ -548,30 +561,39 @@ The `edit` tool returns `details.diff` for Apex Code's TUI display and `details.
 ```typescript
 import { createAgentSession } from "apex-code";
 
-// Read-only mode
-const { session } = await createAgentSession({
-  tools: ["read", "grep", "find", "ls"],
-});
+const { session } = await createAgentSession();
 
-// Pick specific tools
-const { session } = await createAgentSession({
-  tools: ["read", "bash", "grep"],
-});
+try {
+  await session.prompt("What files are in the current directory?");
+  console.log(session.getLastAssistantText());
+} finally {
+  session.dispose();
+}
+```
 
-// Use PowerShell instead of Bash on Windows
-const { session } = await createAgentSession({
-  tools: ["read", "powershell", "edit", "write"],
-});
+This uses the working directory, discovered resources, stored settings, and configured credentials. `prompt()` resolves when the run finishes.
 
-// Disable one tool while keeping the rest available
-const { session } = await createAgentSession({
-  excludeTools: ["ask_question"],
-});
-```
+The [complete minimal example](../examples/sdk/01-minimal.ts) also streams text events. All [SDK examples](../examples/sdk/) are typechecked with the repository.
+
+<a id="session-management"></a>
+
+## Session lifecycle
+
+`createAgentSession()` creates an `AgentSession`. The session owns one conversation, its model and tools, queued messages, compaction state, and extension runtime.
+
+Read current state through `session.messages`, `session.model`, `session.thinkingLevel`, `session.systemPrompt`, and `session.getActiveToolNames()`.
 
-#### Tools with Custom cwd
+`session.systemPrompt` is read-only and returns the current effective system prompt, including changes that have not yet been sent to the model. Tool changes are declared to the model before the next request.
 
-When you pass a custom `cwd`, `createAgentSession()` builds selected built-in tools for that cwd.
+<a id="sessionmanager-api"></a>
+
+### Session storage
+
+Sessions are persistent by default. `SessionManager` owns the persisted or in-memory entry tree and tracks its active leaf. Branching changes that leaf without deleting abandoned branches. When Pi reconstructs model context, the manager selects the active branch and applies compaction.
+
+`SessionManager` is authoritative for finalized model context. Restore external history by constructing the session with a manager containing those entries. Assigning `session.agent.state.messages` does not replace persisted context.
+
+Use an in-memory manager when the host does not want session files:
 
 ```typescript
 import { createAgentSession, SessionManager } from "apex-code";
@@ -787,63 +809,31 @@ import {
 const { session } = await createAgentSession({
   sessionManager: SessionManager.inMemory(),
 });
+```
 
-// New persistent session
-const { session: persisted } = await createAgentSession({
-  sessionManager: SessionManager.create(process.cwd()),
-});
+See the checked [sessions example](../examples/sdk/11-sessions.ts) for creating, opening, continuing, listing, and forking sessions. [Session File Format](session-format.md) defines the persisted JSONL contract, and [Message Types](message-types.md) defines transcript values. For exact methods and signatures, use the exported TypeScript declarations or [`session-manager.ts`](../src/core/session-manager.ts).
 
-// Continue most recent
-const { session: continued, modelFallbackMessage } = await createAgentSession({
-  sessionManager: SessionManager.continueRecent(process.cwd()),
-});
-if (modelFallbackMessage) {
-  console.log("Note:", modelFallbackMessage);
-}
+`cwd` selects the workspace used for project resource discovery, context files, session grouping, and built-in tool paths. Pass it explicitly when the target differs from `process.cwd()`.
 
-// Open specific file
-const { session: opened } = await createAgentSession({
-  sessionManager: SessionManager.open("/path/to/session.jsonl"),
-});
+`session.dispose()` aborts active work, invalidates extension contexts, disconnects from the agent, and removes event listeners. Call it when the session is no longer needed.
 
-// List sessions
-const currentProjectSessions = await SessionManager.list(process.cwd());
-const allSessions = await SessionManager.listAll(process.cwd());
+`AgentSessionRuntime` adds `newSession()`, `switchSession()`, `fork()`, and `importFromJsonl()`. Each operation replaces the active `AgentSession` and recreates services for the target working directory.
 
-// Session replacement API for /new, /resume, /fork, /clone, and import flows.
-const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
-  const services = await createAgentSessionServices({ cwd });
-  return {
-    ...(await createAgentSessionFromServices({
-      services,
-      sessionManager,
-      sessionStartEvent,
-    })),
-    services,
-    diagnostics: services.diagnostics,
-  };
-};
+After a runtime replacement, subscriptions belong to the old `AgentSession` and must be rebound. See the [session runtime example](../examples/sdk/13-session-runtime.ts).
 
-const runtime = await createAgentSessionRuntime(createRuntime, {
-  cwd: process.cwd(),
-  agentDir: getAgentDir(),
-  sessionManager: SessionManager.create(process.cwd()),
-});
+## Prompting
 
-// Replace the active session with a fresh one
-await runtime.newSession();
+`prompt()` handles extension commands and expands file-based prompt templates before ordinary user messages enter the agent. For an accepted agent run, it resolves after the run finishes, including automatic retries.
 
-// Replace the active session with another saved session
-await runtime.switchSession("/path/to/session.jsonl");
+A prompt sent while the session is already streaming must specify whether it should steer the current run or follow it. Calling `prompt()` without that choice rejects rather than guessing.
 
-// Replace the active session with a fork from a specific user entry
-await runtime.fork("entry-id");
+A steering message enters after the current assistant turn and its tool calls. A follow-up enters after the current run finishes its pending work. `steer()` and `followUp()` expose those behaviors directly.
 
-// Clone the active path through a specific entry
-await runtime.fork("entry-id", { position: "at" });
-```
+`abort()` stops the active operation and waits for the session to become idle. `waitForIdle()` waits without aborting it.
 
-**SessionManager tree API:**
+## Subscribing to events
+
+Subscribe before prompting when the host needs streamed output:
 
 ```typescript
 const sm = SessionManager.open("/path/to/session.jsonl");
@@ -1042,16 +1032,20 @@ session.subscribe((event) => {
   }
 });
 
-await session.prompt("Get status and list files.");
+try {
+  await session.prompt("Explain this repository");
+} finally {
+  unsubscribe();
+}
 ```
 
-## Run Modes
+Session events report message updates, tool execution, queues, compaction, retries, and run lifecycle changes.
 
-The SDK exports run mode utilities for building custom interfaces on top of `createAgentSession()`:
+`message_end` contains the authoritative completed message. `agent_end` marks the end of one low-level agent run, but automatic recovery or queued work can still follow.
 
-### InteractiveMode
+Use `agent_settled` when the host needs to know that Pi will not continue automatically.
 
-Full TUI interactive mode with editor, chat history, and all built-in commands:
+## Configuring a session
 
 ```typescript
 import {
@@ -1064,34 +1058,19 @@ import {
   SessionManager,
 } from "apex-code";
 
-const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
-  const services = await createAgentSessionServices({ cwd });
-  return {
-    ...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent })),
-    services,
-    diagnostics: services.diagnostics,
-  };
-};
-const runtime = await createAgentSessionRuntime(createRuntime, {
-  cwd: process.cwd(),
-  agentDir: getAgentDir(),
-  sessionManager: SessionManager.create(process.cwd()),
-});
+Each boundary can be supplied explicitly:
 
-const mode = new InteractiveMode(runtime, {
-  migratedProviders: [],
-  modelFallbackMessage: undefined,
-  initialMessage: "Hello",
-  initialImages: [],
-  initialMessages: [],
-});
+- `modelRuntime`, `model`, `thinkingLevel`, and `scopedModels` control model access and selection.
+- `settingsManager` supplies merged settings or an in-memory configuration.
+- `sessionManager` supplies persistent or in-memory conversation history.
+- `resourceLoader` supplies extensions, skills, prompt templates, themes, and context files.
+- `tools`, `noTools`, `excludeTools`, and `customTools` control the active tool set.
 
-await mode.run();
-```
+Use `DefaultResourceLoader` when you want standard discovery with selected overrides. Supply a custom `ResourceLoader` when the host owns resource storage and discovery completely.
 
-### runPrintMode
+<a id="inlineextension"></a>
 
-Single-shot mode: send prompts, output result, exit:
+Inline extension factories can be supplied through `DefaultResourceLoader`. Give one an `InlineExtension` name only when it needs a stable name in diagnostics and startup output.
 
 ```typescript
 import {
@@ -1104,31 +1083,27 @@ import {
   SessionManager,
 } from "apex-code";
 
-const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
-  const services = await createAgentSessionServices({ cwd });
-  return {
-    ...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent })),
-    services,
-    diagnostics: services.diagnostics,
-  };
-};
-const runtime = await createAgentSessionRuntime(createRuntime, {
-  cwd: process.cwd(),
-  agentDir: getAgentDir(),
-  sessionManager: SessionManager.create(process.cwd()),
-});
-
-await runPrintMode(runtime, {
-  mode: "text",
-  initialMessage: "Hello",
-  initialImages: [],
-  messages: ["Follow up"],
-});
-```
-
-### runRpcMode
-
-JSON-RPC mode for subprocess integration:
+## Examples
+
+| Example | Purpose |
+|---|---|
+| [Minimal](../examples/sdk/01-minimal.ts) | Create, prompt, observe, and dispose a session |
+| [Custom model](../examples/sdk/02-custom-model.ts) | Select a model and thinking level |
+| [System prompt](../examples/sdk/03-custom-prompt.ts) | Replace or append to the system prompt |
+| [Skills](../examples/sdk/04-skills.ts) | Discover, filter, and add skills |
+| [Tools](../examples/sdk/05-tools.ts) | Select built-in tools and their working directory |
+| [Extensions](../examples/sdk/06-extensions.ts) | Load file-based and inline extensions |
+| [Context files](../examples/sdk/07-context-files.ts) | Add or replace project instructions |
+| [Prompt templates](../examples/sdk/08-prompt-templates.ts) | Add file-style prompt templates |
+| [Credentials](../examples/sdk/09-api-keys-and-oauth.ts) | Configure credential and model storage |
+| [Settings](../examples/sdk/10-settings.ts) | Supply file-backed or in-memory settings |
+| [Sessions](../examples/sdk/11-sessions.ts) | Control session persistence and restoration |
+| [Full control](../examples/sdk/12-full-control.ts) | Replace default discovery and state services |
+| [Session runtime](../examples/sdk/13-session-runtime.ts) | Replace the active session safely |
+
+<a id="exports"></a>
+
+## Resources
 
 ```typescript
 import {

package/docs/security.md

@@ -1,10 +1,10 @@
-# Security
+# Run Apex Code safely
 
 Apex Code is a local coding agent. It runs with the permissions of the user account that starts it, and it treats files writable by that user as inside the same local trust boundary.
 
 See also [`SECURITY.md`](https://github.com/Fchery87/apex-code/blob/main/SECURITY.md) at the repository root for the reporting process, maintainer ownership, and what is in and out of scope; this page covers the underlying project-trust and sandboxing mechanics in more detail.
 
-## Project Trust
+Files, comments, instructions, command output, and model responses can steer the model through prompt injection. Project trust controls which project resources load at startup, but it does not make that content or the resulting actions safe.
 
 Project trust controls whether Apex Code loads project-local settings, resources, packages, and extensions. It is not a sandbox and it does not restrict what the model can ask tools to do after you start working in a directory.
 
@@ -28,7 +28,7 @@ Trusting a project allows Apex Code to load project resources that require trust
 
 Declining trust skips protected resources. Context files such as `AGENTS.override.md`, `AGENTS.md`, and `CLAUDE.md` are loaded regardless of project trust unless context loading is disabled. Before trust is resolved, Apex Code only loads context files, user/global extensions, and CLI `-e` extensions. User/global and CLI extensions can handle the `project_trust` event; the first extension that returns a yes/no decision owns the decision.
 
-Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, `defaultProjectTrust: "ask"` and `"never"` ignore such resources, while `"always"` trusts them. Use `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
+### How Apex Code chooses a trust decision
 
 ## Permissions and Isolation
 
@@ -38,11 +38,11 @@ Apex Code ships no built-in sandbox. There is no OS-level boundary between a ses
 
 Project trust is only an input-loading guard, layered alongside the permission gate. It prevents a repository from silently changing Apex Code's settings or extensions before you approve it. It does not make untrusted code, untrusted prompts, or untrusted model output safe by itself. Prompt injection from repository files, comments, documentation, context files, or build output is expected local-agent risk and cannot be reliably prevented by Apex Code.
 
-## Running Untrusted or Unmonitored Work
+Use `/trust` to save a decision for future Apex Code processes.
 
 For untrusted repositories, generated code you do not intend to monitor closely, or unattended automation, run Apex Code in a contained environment. It has no boundary of its own, so this is the containment boundary rather than an extra one. Use a container, VM, micro-VM, remote sandbox, or policy-controlled sandbox with only the files and credentials required for the task.
 
-Common patterns are documented in [Containerization](containerization.md):
+Print, JSON, and RPC modes cannot show the built-in trust prompt. If no command-line override, extension, or saved decision applies:
 
 - run the whole Apex Code process inside a container/sandbox
 - run host Apex Code while routing built-in tool execution into a Gondolin micro-VM
@@ -52,9 +52,9 @@ Common patterns are documented in [Containerization](containerization.md):
 - restrict network access when the task does not need it
 - review diffs and outputs before copying results back to trusted systems
 
-If you bind-mount a host workspace read/write, writes from inside the container or VM can still modify host files. Use read-only mounts or copy files into and out of the sandbox when you need stronger protection from unintended writes.
+Use `--approve` or `--no-approve` when an automated run needs an explicit one-time decision.
 
-## Reporting Security Issues
+## Reduce impact and improve recovery
 
 To report a security issue, follow Apex Code's own [Security Policy](https://github.com/Fchery87/apex-code/blob/main/SECURITY.md) — private disclosure via [GitHub private vulnerability reporting](https://github.com/Fchery87/apex-code/security/advisories/new). Do not open a public issue for security-sensitive reports.