> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bastani.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK API reference

> SDK options, resource loaders, return values, run modes, and exports.

# SDK API reference

## Options Reference

### Directories

```typescript theme={null}
const { session } = await createAgentSession({
  // Working directory for DefaultResourceLoader discovery
  cwd: process.cwd(), // default
  
  // Global config directory
  agentDir: "~/.atomic/agent", // default (expands ~)
});
```

Atomic reads primary `.atomic` locations first and legacy `.pi` locations for compatibility when multiple config directories are supported. Passing an explicit `agentDir` makes that directory the user override.

`cwd` is used by `DefaultResourceLoader` for:

* Project extensions (`.atomic/extensions/`, then legacy `.pi/extensions/`)
* Project skills:
  * `.atomic/skills/`, then legacy `.pi/skills/`
  * `.agents/skills/` in `cwd` and ancestor directories (up to git repo root, or filesystem root when not in a repo)
* Project prompts (`.atomic/prompts/`, then legacy `.pi/prompts/`)
* Context files (`AGENTS.override.md`, `AGENTS.md`, or `CLAUDE.md` walking up from cwd)
* Session directory naming

`agentDir` is used by `DefaultResourceLoader` for:

* Global extensions (`extensions/`)
* Global skills:
  * `skills/` under `agentDir` (for example `~/.atomic/agent/skills/`; legacy `~/.pi/agent/skills/` is also considered by default)
  * `~/.agents/skills/`
* Global prompts (`prompts/`)
* Global context files (`AGENTS.override.md`, `AGENTS.md`, or `CLAUDE.md` under `agentDir`)
* Settings (`settings.json`)
* Custom models (`models.json`)
* Credentials (`auth.json`)
* Sessions (`sessions/`)

When you pass a custom `ResourceLoader`, `cwd` and `agentDir` no longer control resource discovery. They still influence session naming and tool path resolution.

### Model

```typescript theme={null}
import { getModel } from "@bastani/pi-ai/compat";
import { ModelRuntime } from "@bastani/atomic";

const modelRuntime = await ModelRuntime.create();

// Find specific built-in model (doesn't check if credentials exist)
const opus = getModel("anthropic", "claude-opus-4-5");
if (!opus) throw new Error("Model not found");

// Find any model by provider/id, including custom models from models.json
const customModel = modelRuntime.getModel("my-provider", "my-model");

// Get only models whose providers have configured authentication
const available = await modelRuntime.getAvailable();

const { session } = await createAgentSession({
  model: opus,
  thinkingLevel: "medium", // off, minimal, low, medium, high, xhigh, max (when supported by the model)
  
  // Models for cycling (CTRL+P in interactive mode)
  scopedModels: [
    { model: opus, thinkingLevel: "high" },
    { model: haiku, thinkingLevel: "off" },
  ],
  
  modelRuntime,
});
```

`ModelRegistry` keeps synchronous reads for extension compatibility, while catalog refresh is asynchronous. Extensions should await `modelRegistry.refresh()` before synchronous `getAll()`, `find()`, or `getAvailable()` reads when a provider may update its catalog. New SDK integrations use `ModelRuntime`; `await modelRuntime.refresh()` reports `aborted` and per-provider `errors`, and failed providers retain their last-known models.

If no model is provided:

1. Tries to restore from session (if continuing)
2. Uses default from settings
3. Falls back to first available model

> See [examples/sdk/02-custom-model.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/sdk/02-custom-model.ts)

#### Model catalog persistence and refresh

`ModelRuntime.create()` restores cached catalogs from local persistence but does not contact
pi.dev unless you opt in. `allowModelNetwork` (default `false`) enables a create-time network
refresh, and `modelRefreshTimeoutMs` (default `15_000`) bounds how long that refresh may run
before it is aborted. Pass `refreshOnCreate: false` to skip the initial catalog and
availability refresh entirely; built-in models remain available.

```typescript theme={null}
const refreshedRuntime = await ModelRuntime.create({
  allowModelNetwork: true,
  modelRefreshTimeoutMs: 15_000,
});
```

Remote catalogs are persisted locally so later runtimes can restore them without a network
request. The default file is `models-store.json` next to `models.json` — with the default
`modelsPath` that is `~/.atomic/agent/models-store.json`. Set `modelsStorePath` to choose
another location, or inject `modelsStore` to control persistence entirely; a runtime created
with `modelsPath: null` keeps its store in memory. 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
`ATOMIC_OFFLINE` (legacy alias `PI_OFFLINE`) disables model network access, and a
`refresh()` call that omits `allowNetwork` follows that same runtime network policy.

### API Keys and OAuth

`ModelRuntime` is the asynchronous SDK engine for provider composition, credentials, model catalogs, and requests. `ModelRegistry` remains a thin compatibility facade for extensions; `await modelRegistry.complete(model, context, options)` routes a request through its runtime with the resolved provider and auth. New SDK integrations should pass `modelRuntime` to `createAgentSession` and use `modelRuntime.complete()` directly when they issue standalone requests.

Credential resolution combines runtime API-key overrides, stored `auth.json` credentials, environment variables, and the active `models.json` provider configuration. OAuth acquisition is provider-owned and runs through `ModelRuntime.login()`.

```typescript theme={null}
import { AuthStorage, ModelRuntime } from "@bastani/atomic";

const authStorage = AuthStorage.create();
const modelRuntime = await ModelRuntime.create({ credentials: authStorage });

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  modelRuntime,
});

// Runtime API key override (not persisted to disk). Setting the key updates
// auth state; refresh the provider explicitly when its catalog must be current.
const providerId = "anthropic";
const authController = new AbortController();
await modelRuntime.setRuntimeApiKey(providerId, "sk-my-temp-key", { signal: authController.signal });
await modelRuntime.refresh({ providers: [providerId], signal: authController.signal });

// Custom credential and model configuration locations
const customRuntime = await ModelRuntime.create({
  authPath: "/my/app/auth.json",
  modelsPath: "/my/app/models.json",
});

const customSession = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  modelRuntime: customRuntime,
});

// Disable models.json while retaining built-in providers
const builtinsOnly = await ModelRuntime.create({ modelsPath: null });
```

> See the complete [`ModelRuntime` credential and model configuration example](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/sdk/09-api-keys-and-oauth.ts).

### System Prompt

Use a `ResourceLoader` to override the system prompt:

```typescript theme={null}
import { createAgentSession, DefaultResourceLoader } from "@bastani/atomic";

const loader = new DefaultResourceLoader({
  systemPromptOverride: () => "You are a helpful assistant.",
});
await loader.reload();

const { session } = await createAgentSession({ resourceLoader: loader });
```

> See [examples/sdk/03-custom-prompt.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/sdk/03-custom-prompt.ts)

### Tools

Specify which tools to expose by name:

* Built-in tool names enabled by default: `read`, `bash`, `kill`, `edit`, `write`, `find`, `search`, `ask_user_question`, `todo`
* `find` discovers filesystem paths by glob; `search` searches file contents with regex patterns across files, directories, globs, and internal URLs.
* `tools` is an allowlist: when provided, only the listed built-in, extension, and custom tool names are exposed, plus mandatory ordinary `intercom`.
* `excludedTools` is a blocklist: matching built-in, extension, and custom tool names are omitted from the final registry and active tool set, except mandatory ordinary `intercom`. If both are provided, `tools` is applied first and `excludedTools` subtracts from it.
* `noTools: "all"` disables every tool except mandatory ordinary `intercom`
* `noTools: "builtin"` disables default built-ins while keeping extension and custom tools enabled, except names listed in `excludedTools`

```typescript theme={null}
import { createAgentSession } from "@bastani/atomic";

// Read-only mode. `tools` selects optional tools; ordinary Intercom remains active.
const { session } = await createAgentSession({
  tools: ["read", "search", "find", "ls"],
});

// Pick specific optional tools. Ordinary Intercom remains active even when omitted.
const { session } = await createAgentSession({
  tools: ["read", "bash", "search"],
});

// Keep defaults but remove HITL prompts
const { session } = await createAgentSession({
  excludedTools: ["ask_user_question"],
});

// Allowlist first, then subtract exclusions
const { session } = await createAgentSession({
  tools: ["read", "bash", "ask_user_question"],
  excludedTools: ["ask_user_question"], // optional tools: read, bash; ordinary Intercom remains active
});
```

#### Bash tool behavior

Atomic's built-in `bash` tool matches upstream pi: when `bash` is enabled, commands execute through the configured shell with the Atomic process permissions. Use `tools`, `excludedTools`, or `noTools` to decide whether a session exposes the `bash` tool at all. Atomic no longer provides a command-level allow/deny option for `bash`; use an operating-system/container sandbox or a custom tool/extension when you need command allowlisting or stronger isolation.

#### Waiting for existing shell tasks

Both Bash and PowerShell factories accept `{ action: "wait", id: taskId, budgetMs: 1000 }` with a trusted `taskOwner` binding. No command is executed. `BashToolInput` and `PowerShellToolInput` distinguish command launches from existing-task waits; narrow by `action` before reading `command`.

`budgetMs` is optional, finite, and non-negative. Omission uses the owner's command wait policy and zero polls. Results keep the `WaitOutcome` in `details.observation`, available exit information in `details.exitCode`, and retained output in text content. Failure and cancellation metadata remain in the settled observation. Yielded waits advance through bounded retained-output pages for the same owned task, even when the tool is recreated. Partial UTF-8 characters continue on the next page. Settled waits return all retained output again, subject to labelled gaps and truncation. Aborting the call releases only its observation. A binding from `AgentTaskHost.ownerBinding` also releases waits for incoming owner messages.

Do not mix wait arguments with launch fields. Unknown or foreign IDs and unbound waits are rejected before execution hooks. Custom `operations.exec` does not provide existing-task ownership. See [Background tasks](/background-tasks) for examples and lifetime rules.

#### PowerShell tool behavior

`createPowerShellTool()` and `createPowerShellToolDefinition()` provide the same tool used by interactive sessions. When their default local operations execute on native Windows, they prefer `pwsh.exe`, fall back to `powershell.exe`, and throw a clear error when neither executable is available. `createLocalPowerShellOperations()` and `getPowerShellConfig()` are also exported for custom integrations. The PowerShell factories expose the current `ATOMIC_*` and legacy `PI_*` session snapshot by default; set `exposeSessionEnvironment: false` to opt out.

PowerShell tools and local operations accept a trusted `taskOwner` binding and the same
`wait` observation policy as bash. Owned native Windows execution automatically yields
after the owner's command budget (normally 10000 ms); explicit per-call budgets override it,
and execution timeout remains separate. Commands use encoded PowerShell transport internally,
while task descriptions retain the original command text. Without a supported owner,
explicit background requests are refused and foreground execution waits for completion.

```typescript theme={null}
import { createPowerShellTool } from "@bastani/atomic";

const powershell = createPowerShellTool("C:\\path\\to\\project");
```

#### Tools with Custom cwd

When you pass a custom `cwd`, `createAgentSession()` builds selected built-in tools for that cwd.

```typescript theme={null}
import { createAgentSession, SessionManager } from "@bastani/atomic";

const cwd = "/path/to/project";

// Use default tools for custom cwd
const { session } = await createAgentSession({
  cwd,
  sessionManager: SessionManager.inMemory(cwd),
});

// Or pick specific tools for custom cwd
const { session } = await createAgentSession({
  cwd,
  tools: ["read", "bash", "search"],
  sessionManager: SessionManager.inMemory(cwd),
});
```

> See [examples/sdk/05-tools.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/sdk/05-tools.ts)

### Custom Tools

```typescript theme={null}
import { Type } from "typebox";
import { createAgentSession, defineTool } from "@bastani/atomic";

// Inline custom tool
const myTool = defineTool({
  name: "my_tool",
  label: "My Tool",
  description: "Does something useful",
  parameters: Type.Object({
    input: Type.String({ description: "Input value" }),
  }),
  execute: async (_toolCallId, params) => ({
    content: [{ type: "text", text: `Result: ${params.input}` }],
    details: {},
  }),
});

// Pass custom tools directly
const { session } = await createAgentSession({
  customTools: [myTool],
});
```

Use `defineTool()` for standalone definitions and arrays like `customTools: [myTool]`. Inline `pi.registerTool({ ... })` already infers parameter types correctly.

Custom tools passed via `customTools` are combined with extension-registered tools. Extensions loaded by the ResourceLoader can also register tools via `pi.registerTool()`.

If you pass `tools`, include each custom or extension tool name you want enabled, for example `tools: ["read", "bash", "my_tool"]`. Use `excludedTools` to remove a custom or extension tool by name from the final exposed set.

`ToolDefinition.constrainedSampling` is part of the public SDK and survives `defineTool()`, `customTools`, tool wrappers, session/staged inspection, and isolated execution. Use `{ type: "json_schema", strict: "prefer" | "require" }`, `{ type: "grammar", variants: { openai_lark?: string, openai_regex?: string } }`, or `false`. `prefer` can fall back; `require` fails when the active model cannot enforce strict JSON Schema. Grammar constraints require one required string parameter and capable model metadata. Public inspection preserves optional-property identity exactly: an omitted key stays absent, an explicitly present `undefined` stays present, and `false` or a config object remains unchanged. The exported `ConstrainedSamplingConfig` type and [extension reference](/extensions/authoring#constrained-sampling) define the exact shape. Typed RPC clients receive the four model capability flags through optional `ModelInfo.compat`; see [RPC](/rpc/protocol#get_available_models).

Factory-created `createBashTool()` instances receive the same execution-time `ATOMIC_SESSION_*`/`PI_SESSION_*` model and session snapshot as the built-in bash tool. Set `exposeSessionEnvironment: false` only when the subprocess must not receive it. `MessageRenderOptions.outputPad` is likewise passed to normal and isolated custom message renderers.

Normal sessions also expose `kill({ id: taskId })` for their owned bash and PowerShell background tasks. Include `kill` when using a `tools` allowlist if the agent should be able to stop those tasks. The exported `createKillTool` and `createKillToolDefinition` factories accept `KillToolOptions.taskOwner`, a trusted execution-time callback returning the same owner binding used by shell launch. Without a binding they reject execution. The result details preserve the supervisor's `CancelReceipt`, including its decision, execution outcome, and cleanup state. See [Background tasks](/background-tasks#stop-a-shell-task-from-a-tool-call).

#### Structured output final results

`structured_output` is not registered in normal agent sessions by default. Add it only when a caller needs a machine-readable final-answer contract by registering the exported factory as a custom tool:

```typescript theme={null}
import { Type, type Static } from "typebox";
import {
  createAgentSession,
  createStructuredOutputTool,
  type StructuredOutputCapture,
} from "@bastani/atomic";

const DecisionSchema = Type.Object({
  approved: Type.Boolean(),
  findings: Type.Array(Type.String()),
}, { additionalProperties: false });

type Decision = Static<typeof DecisionSchema>;
const capture: StructuredOutputCapture<Decision> = {
  called: false,
  value: undefined,
};

const structuredOutput = createStructuredOutputTool({
  schema: DecisionSchema,
  capture,
});

const { session } = await createAgentSession({
  customTools: [structuredOutput],
});
```

The tool parameters are exactly the supplied schema: with `DecisionSchema`, the model calls `structured_output({ approved, findings })`. Array and primitive schemas are also accepted by the factory when the target provider/tool runtime supports them; the captured value is whatever JSON value matches the schema. A successful call stores the params in `capture.value`, returns them as pretty-printed JSON tool-result text for text print mode, keeps the flat value in tool `details`, writes the same JSON to the configured `output.outputPath` when an `output` file sink is configured, and sets `terminate: true` so there is no extra follow-up assistant turn. Atomic relies on the tool schema instead of extra structured-output parsing or sidecar validation. Structured-output tool definitions opt out of oversized-result persistence.

Custom tool names are supported, and the prompt metadata follows the configured name. If you use a custom name such as `final_decision`, include that name in any explicit `tools` allowlist. If the standard `structured_output` name is required, register the factory with its default name:

```typescript theme={null}
const finalDecision = createStructuredOutputTool({
  name: "final_decision",
  schema: DecisionSchema,
  capture,
});
// The model is prompted to call final_decision exactly once, not structured_output.

await createAgentSession({
  customTools: [finalDecision],
  tools: ["final_decision"], // only this tool is enabled
});

await createAgentSession({
  customTools: [createStructuredOutputTool({ schema: DecisionSchema, capture })],
  // Registers the standard structured_output tool for this session only.
});
```

> See [examples/sdk/05-tools.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/sdk/05-tools.ts)

### Extensions

Extensions are loaded by the `ResourceLoader`. `DefaultResourceLoader` discovers extensions from `~/.atomic/agent/extensions/` and `.atomic/extensions/` first, then legacy `~/.pi/agent/extensions/` and `.pi/extensions/`, plus settings.json extension sources.

```typescript theme={null}
import { createAgentSession, DefaultResourceLoader } from "@bastani/atomic";

const loader = new DefaultResourceLoader({
  additionalExtensionPaths: ["/path/to/my-extension.ts"],
  extensionFactories: [
    (pi) => {
      pi.on("agent_start", () => {
        console.log("[Inline Extension] Agent starting");
      });
    },
  ],
});
await loader.reload();

const { session } = await createAgentSession({ resourceLoader: loader });
```

`createAgentSession()` preserves resources from a supplied loader but restores Atomic's mandatory bundled Intercom extension after loader overrides, deferred reloads, and same-name extension or `customTools` collisions. The supplied loader still controls every optional extension.

Strict reloads (`failOnExtensionErrors: true`) require the loader's transactional `prepareReload()` support so a failed candidate cannot mutate live state before validation. `DefaultResourceLoader` provides that support. Custom loaders without it remain compatible with ordinary reloads, but strict reload fails before calling their mutating `reload()` method.

Extensions can register tools, subscribe to events, add commands, and more. See [Extensions](/extensions) for the full API.

**Event Bus:** Extensions can communicate via `pi.events`. Pass a shared `eventBus` to `DefaultResourceLoader` if you need to emit or listen from outside:

```typescript theme={null}
import { createEventBus, DefaultResourceLoader } from "@bastani/atomic";

const eventBus = createEventBus();
const loader = new DefaultResourceLoader({
  eventBus,
});
await loader.reload();

eventBus.on("my-extension:status", (data) => console.log(data));
```

> See [examples/sdk/06-extensions.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/sdk/06-extensions.ts) and [Extensions](/extensions)

### Skills

```typescript theme={null}
import {
  createAgentSession,
  DefaultResourceLoader,
  type Skill,
} from "@bastani/atomic";

const customSkill: Skill = {
  name: "my-skill",
  description: "Custom instructions",
  filePath: "/path/to/SKILL.md",
  baseDir: "/path/to",
  source: "custom",
};

const loader = new DefaultResourceLoader({
  skillsOverride: (current) => ({
    skills: [...current.skills, customSkill],
    diagnostics: current.diagnostics,
  }),
});
await loader.reload();

const { session } = await createAgentSession({ resourceLoader: loader });
```

> See [examples/sdk/04-skills.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/sdk/04-skills.ts)

### Context Files

```typescript theme={null}
import { createAgentSession, DefaultResourceLoader } from "@bastani/atomic";

const loader = new DefaultResourceLoader({
  agentsFilesOverride: (current) => ({
    agentsFiles: [
      ...current.agentsFiles,
      { path: "/virtual/AGENTS.md", content: "# Guidelines\n\n- Be concise" },
    ],
  }),
});
await loader.reload();

const { session } = await createAgentSession({ resourceLoader: loader });
```

> See [examples/sdk/07-context-files.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/sdk/07-context-files.ts)

### Slash Commands

```typescript theme={null}
import {
  createAgentSession,
  DefaultResourceLoader,
  type PromptTemplate,
} from "@bastani/atomic";

const customCommand: PromptTemplate = {
  name: "deploy",
  description: "Deploy the application",
  source: "(custom)",
  content: "# Deploy\n\n1. Build\n2. Test\n3. Deploy",
};

const loader = new DefaultResourceLoader({
  promptsOverride: (current) => ({
    prompts: [...current.prompts, customCommand],
    diagnostics: current.diagnostics,
  }),
});
await loader.reload();

const { session } = await createAgentSession({ resourceLoader: loader });
```

> See [examples/sdk/08-prompt-templates.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/sdk/08-prompt-templates.ts)

### Session Management

Sessions use a tree structure with `id`/`parentId` linking, enabling in-place branching.

```typescript theme={null}
import {
  type CreateAgentSessionRuntimeFactory,
  createAgentSession,
  createAgentSessionFromServices,
  createAgentSessionRuntime,
  createAgentSessionServices,
  getAgentDir,
  SessionManager,
} from "@bastani/atomic";

// In-memory (no persistence)
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
});

// New persistent session
const { session: persisted } = await createAgentSession({
  sessionManager: SessionManager.create(process.cwd()),
});

// Continue most recent
const { session: continued, modelFallbackMessage } = await createAgentSession({
  sessionManager: SessionManager.continueRecent(process.cwd()),
});
if (modelFallbackMessage) {
  console.log("Note:", modelFallbackMessage);
}

// Open specific file
const { session: opened } = await createAgentSession({
  sessionManager: SessionManager.open("/path/to/session.jsonl"),
});

// List sessions
const currentProjectSessions = await SessionManager.list(process.cwd());
const allSessions = await SessionManager.listAll(process.cwd());

// 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,
  };
};

const runtime = await createAgentSessionRuntime(createRuntime, {
  cwd: process.cwd(),
  agentDir: getAgentDir(),
  sessionManager: SessionManager.create(process.cwd()),
});

// Replace the active session with a fresh one
await runtime.newSession();

// Replace the active session with another saved session
await runtime.switchSession("/path/to/session.jsonl");

// Replace the active session with a fork from a specific user entry
await runtime.fork("entry-id");

// Clone the active path through a specific entry
await runtime.fork("entry-id", { position: "at" });
```

**SessionManager tree API:**

```typescript theme={null}
const sm = SessionManager.open("/path/to/session.jsonl");

// Session listing
const currentProjectSessions = await SessionManager.list(process.cwd());
const allSessions = await SessionManager.listAll(process.cwd());

// Tree traversal
const entries = sm.getEntries();        // All entries (excludes header)
const tree = sm.getTree();              // Full tree structure
const path = sm.getPath();              // Path from root to current leaf
const leaf = sm.getLeafEntry();         // Current leaf entry
const entry = sm.getEntry(id);          // Get entry by ID
const children = sm.getChildren(id);    // Direct children of entry

// Labels
const label = sm.getLabel(id);          // Get label for entry
sm.appendLabelChange(id, "checkpoint"); // Set label

// Branching
sm.branch(entryId);                     // Move leaf to earlier entry
sm.branchWithSummary(id, "Summary...");  // Branch with context summary
sm.createBranchedSession(leafId);       // Extract path to new file
```

> See [examples/sdk/11-sessions.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/sdk/11-sessions.ts) and [Session Format](/session-format)

### Settings Management

```typescript theme={null}
import { createAgentSession, SettingsManager, SessionManager } from "@bastani/atomic";

// Default: loads from files (global + project merged)
const { session } = await createAgentSession({
  settingsManager: SettingsManager.create(),
});

// With overrides
const settingsManager = SettingsManager.create();
settingsManager.applyOverrides({
  compaction: { enabled: false },
  retry: { enabled: true, maxRetries: 5 },
});
const { session } = await createAgentSession({ settingsManager });

// In-memory (no file I/O, for testing)
const { session } = await createAgentSession({
  settingsManager: SettingsManager.inMemory({ compaction: { enabled: false } }),
  sessionManager: SessionManager.inMemory(),
});

// Custom directories
const { session } = await createAgentSession({
  settingsManager: SettingsManager.create("/custom/cwd", "/custom/agent"),
});
```

**Static factories:**

* `SettingsManager.create(cwd?, agentDir?)` - Load from files
* `SettingsManager.inMemory(settings?)` - No file I/O

**Project-specific settings:**

Settings load from Atomic-first locations and merge:

1. Global: `~/.atomic/agent/settings.json`, then legacy `~/.pi/agent/settings.json`
2. Project: `<cwd>/.atomic/settings.json`, then legacy `<cwd>/.pi/settings.json`

Project overrides global. Nested objects merge keys. Setters modify global settings by default.

**Persistence and error handling semantics:**

* Settings getters/setters are synchronous for in-memory state.
* Setters enqueue persistence writes asynchronously.
* Call `await settingsManager.flush()` when you need a durability boundary (for example, before process exit or before asserting file contents in tests).
* `SettingsManager` does not print settings I/O errors. Use `settingsManager.drainErrors()` and report them in your app layer.

> See [examples/sdk/10-settings.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/sdk/10-settings.ts)

## ResourceLoader

Use `DefaultResourceLoader` to discover extensions, skills, prompts, themes, and context files.

```typescript theme={null}
import {
  DefaultResourceLoader,
  getAgentDir,
} from "@bastani/atomic";

const loader = new DefaultResourceLoader({
  cwd,
  agentDir: getAgentDir(),
});
await loader.reload();

const extensions = loader.getExtensions();
const skills = loader.getSkills();
const prompts = loader.getPrompts();
const themes = loader.getThemes();
const contextFiles = loader.getAgentsFiles().agentsFiles;
```

## Return Value

`createAgentSession()` returns:

```typescript theme={null}
interface CreateAgentSessionResult {
  // The session
  session: AgentSession;
  
  // Extensions result (for runner setup)
  extensionsResult: LoadExtensionsResult;
  
  // Warning if session model couldn't be restored
  modelFallbackMessage?: string;
}

interface LoadExtensionsResult {
  extensions: Extension[];
  errors: Array<{ path: string; error: string }>;
  runtime: ExtensionRuntime;
}
```

## Run Modes

The SDK exports run mode utilities for building custom interfaces on top of `createAgentSession()`:

### InteractiveMode

Full TUI interactive mode with editor, chat history, and all built-in commands:

```typescript theme={null}
import {
  type CreateAgentSessionRuntimeFactory,
  createAgentSessionFromServices,
  createAgentSessionRuntime,
  createAgentSessionServices,
  getAgentDir,
  InteractiveMode,
  SessionManager,
} from "@bastani/atomic";

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()),
});

const mode = new InteractiveMode(runtime, {
  migratedProviders: [],
  modelFallbackMessage: undefined,
  initialMessage: "Hello",
  initialImages: [],
  initialMessages: [],
});

await mode.run();
```

### runPrintMode

Single-shot mode: send prompts, output result, exit:

```typescript theme={null}
import {
  type CreateAgentSessionRuntimeFactory,
  createAgentSessionFromServices,
  createAgentSessionRuntime,
  createAgentSessionServices,
  getAgentDir,
  runPrintMode,
  SessionManager,
} from "@bastani/atomic";

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:

```typescript theme={null}
import {
  type CreateAgentSessionRuntimeFactory,
  createAgentSessionFromServices,
  createAgentSessionRuntime,
  createAgentSessionServices,
  getAgentDir,
  runRpcMode,
  SessionManager,
} from "@bastani/atomic";

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 runRpcMode(runtime);
```

See [RPC documentation](/rpc) for the JSON protocol.

## Exports

The main entry point exports:

```typescript theme={null}
// Factory
createAgentSession
createAgentSessionRuntime
AgentSessionRuntime

// Auth and Models
AuthStorage
ModelRegistry

// Resource loading
DefaultResourceLoader
type ResourceLoader
createEventBus

// Constants and helpers
CONFIG_DIR_NAME
defineTool
STRUCTURED_OUTPUT_TOOL_NAME
createStructuredOutputTool
createStructuredOutputCapture
getAgentDir
getPackageDir
getReadmePath
getDocsPath
getExamplesPath
generateDiffString
generateUnifiedPatch
type EditDiffResult

// Session management
SessionManager
SettingsManager

// Tool factories
createCodingTools
createReadOnlyTools
createReadTool, createBashTool, createEditTool, createWriteTool
createGrepTool, createFindTool, createLsTool

// Types
type CreateAgentSessionOptions
type CreateAgentSessionResult
type StructuredOutputCapture
type StructuredOutputToolOptions
type ExtensionFactory
type ExtensionAPI
type ToolDefinition
type Skill
type PromptTemplate
type Tool
```

For extension types, see [Extensions](/extensions) for the full API.

## Owner-bound task supervisor (S1)

S1 adds an SDK-only task foundation in `src/core/tasks/contracts.ts` and
`src/core/tasks/supervisor.ts`, backed by the native `TaskSupervisor`. It is an
internal trusted-host integration surface, not a new CLI command. The package root
exports the narrow `AgentTaskHost` adapter and its integration types, not the raw
supervisor. Runtime-created subagent contexts use it; bash/PTY and task UI integration are separate slices.

`AgentTaskHost` binds an actual trusted scope and mandatory `authorizeLaunch` guard.
Its `startAgentTask(intent, operation, runnerFactory)` returns a Result containing
`{taskId, lease}` after setup. Each launch supplies its own factory receiving the
original `AbortSignal`, reference and `reportActivity` context. Return separate
`result` and `cleanup` promises; yielding never replaces either promise, and only
confirmed cleanup may report `reaped`. Exact operation replay never calls another factory.
`observeAgentLaunch(taskId, policy?)` delegates to S1 initial observation; `waitForTask`,
`resolveTask`, `cancelTask`, `watchOwnerTasks` and `close` remain owner-scoped S1 doors.
Observation returns the exact Result/WaitOutcome DTO, not a new model response shape.
These APIs are for trusted first-party hosts, never model-supplied ownership or permission.

For already-admitted in-process tasks, the optional `taskExecution` runner hooks
retain the original execution and cleanup promises. An exact Intercom commit
yields the registered observation. In an explicit foreground group it also yields
active sibling observations through the existing group signal, once per child;
neither path detaches or completes those executions. Public launches in actual sessions use this bridge by default.

Each workflow admission boundary allocates one process-private stage attempt identity.
The actual stage session binds its original session/run/stage identity; fallback session
replacement keeps that identity and the same lazily bound `bindAgentTaskHost` owner.
Replacement disposal does not close tasks. Boundary sealing fences task admission and
starts owner closure; generation close awaits independent cleanup and surfaces failure.
Fresh boundaries have fresh identities, including restoration; history is not a restart
capability. Public producers, durable callback joins and nonvisual completion intent/admission use this owner binding.

When a task completion outbox is created from session history, it immediately retries
unacknowledged terminal completion intents through the current admission boundary.
It does not wait for another task to settle or recreate execution capabilities.
Acknowledged intents are not redelivered. Failed admission keeps the original completion
identity pending for retry; a closed boundary prevents admission.
Top-level session initialization restores admission keys from persisted custom messages,
so a crash after delivery is persisted but before its outbox acknowledgement does not
deliver the same completion again.

A host binds its actual session or workflow-stage scope with `bindHostSession`,
provides launch authorization and a runner factory, then calls `openTaskOwner`.
Authorization runs before native admission. `startAgentTask` registers an agent
task before runner setup and returns its lease without waiting for completion.
Exact operation replay reuses that task and execution; a fresh operation creates
a distinct task. Leases are environment-local capabilities, cannot be serialized,
and cannot be reconstructed from task IDs or historical records.

`initialObservation` applies launch policy: omitted policy yields
`default-background`, explicit background yields `explicit`, and foreground
registers a wait with its requested budget. A ready terminal result wins.
`await waitForTask(task, budgetMs?, designation?)` and
`await foregroundTask(task, budgetMs?)` return a Result containing a WaitOutcome,
not a lease. Native registration and the WaitId registry are populated synchronously
before either door awaits. Host lifecycle actions can use `findWait(waitId)` to
yield or dispose a registered observation; ordinary callers need no extra observe call.
SDK waits do not replace the host designation unless given a matching HostSession.
An elapsed/explicit yield or observer disposal never stops or relaunches execution;
a later yield of a disposed wait replays its ObserverCancelled Result.

Requested agent waits default to 30000 ms. Supply owner-host settings through
`bindHostSession({ scope, tasks: { wait: { kind: "automatic", agentBudgetMs: 5000 } },
authorizeLaunch, createRunner })`; `{ kind: "until-settled" }` disables timed yielding.
Per-call budgets override settings, including zero for immediate yield. These settings
apply to explicit foreground-first launch, live foregrounding and task-ID waits,
never to a default independent launch. Wide numeric budgets are not narrowed to u32.
Accepted `NaN` budgets (including configured `agentBudgetMs`) do not panic native
scheduling. The implementation leaves such observations pending until explicit yield,
settlement, observer disposal or owner closure: the elapsed comparison never reaches
`NaN`. It uses bounded sleep chunks without rewriting the caller's budget. This is
scheduling behavior, not a new finite-only input restriction or an RFC-mandated deadline;
other numeric budgets and per-call precedence are unchanged.

`await cancelTask(task, cause)` returns a Result containing a cancellation receipt
and preserves the first accepted cause. `closeTaskOwner` seals admission before
draining and succeeds only after independent cleanup acknowledgement. The trusted
runner supplies separate result and cleanup promises: confirmed reaping after
cancellation can close even if no result arrives. Natural cleanup-first delivery
waits for its outcome before acknowledging reaping. External native owner closure
also aborts resources attached to already-settled results without rewriting them.
Failed cleanup remains observable; absent acknowledgement can leave close pending.
User cancellation retains pending input attention until settlement or owner closure;
event-reduced and reattached snapshots report the same native facts. Runner result
rejections become failed `RunnerFailed` results; cleanup rejections become diagnostic
`CleanupFailed` resources, never successful reaping. Setup throws retain `SpawnFailed`
and unconfirmed cleanup. Strings and Error messages are preserved verbatim; other JS
values use safe string conversion, with `Unprintable JavaScript rejection` if conversion
throws. Cancelled cleanup still does not depend on the result promise settling.
This slice exercises fake runners, not force-stop or real-process cleanup guarantees.

### Supervised command SDK

`startCommandTask(owner, intent, operation)` starts an owned Unix pipe/PTY or Windows pipe/ConPTY command.
The command intent keeps execution timeout separate from observation: `waitForTask`
defaults to 10000 ms for commands, and expiry returns a yielded observation without
terminating the process. On Unix, owner closure sends TERM, allows 250 ms grace, then KILL,
reaps the leader and confirms process-group exit and reader drain. A cleanup failure
retains diagnostics instead of claiming a closed owner. This is normal owner/host
shutdown cleanup, not a guarantee for forced host death or a blocked JavaScript loop.

Both native and facade `CommandIntent` accept optional `shell: { program, args }`:
the executable is launched directly with `command` appended as one final argv argument.
Omitting `shell` preserves the default native pipe shell. `inheritEnv` defaults to
`true`; `false` uses exactly the supplied environment rather than inheriting the host's.
Both fields participate in operation replay identity.

`taskStdin(task)` returns a non-serializable stdin capability. `writeTaskInput` takes
an operation ID and `{kind:"bytes", bytes:Uint8Array}` or `{kind:"eof"}`. Empty bytes
are a no-op. Input has 65536 byte credits, refuses excess input before admission,
and replays recorded receipts without resending bytes. Ambiguous partial delivery
returns `InputDeliveryUnknown`, including operation ID and known accepted-byte count.

`readTaskOutput(task, {start, maximumBytes})` returns owned byte chunks at decimal
offsets, requested bounds, omitted ranges and an optional next offset. Requests
are clamped to the 1 MiB live-preview bound before allocating or reading a page;
use `nextOffset` to continue. It does not sanitize or normalize bytes. Retention
uses a 1 MiB live head/tail, 8 MiB foreground spill threshold and 5 GiB disk cap.
Retained output is not conversation history. File-spool policy uses supervised
pipe drains, never inherited direct file writers. Stdout, stderr and descendants
share one serialized disk budget; crossing writes retain only the permitted prefix.
The file remains within the cap during foreground collection and termination.
After foreground collection yields, rejected overflow kills the group and settles
`OutputLimitExceeded` after confirmed cleanup. Spool setup failure refuses launch
with `SpawnFailed`. Drained pipe/PTY output instead keeps running with bounded
retained bytes and omissions.
Unix PTY resize uses the retained portable-pty master; Windows PTY uses ConPTY.
Windows pipe and ConPTY commands start suspended and enter a kill-on-close Job Object
before resume. Failed containment refuses execution, with no unsupervised spawn fallback.
Cleanup must be confirmed; failures retain diagnostic resources rather than reporting reaping.
Native Windows legacy WSL `bash.exe` stdin transport remains refused for owned launch:
Windows jobs cannot supervise the Linux guest process tree. Atomic running inside WSL
uses the normal POSIX/Bash path instead.

Bash tools and `createLocalBashOperations` accept a trusted `taskOwner` binding.
On Unix and native Windows, that binding obtains pipe/PTY processes through supervised admission,
preserving configured shell arguments, cwd, environment and existing authorization.
Foreground collection honors the owner's command wait configuration, including
`until-settled`; the automatic default is 10000 ms. A yielded process stays owned
and its retained output remains readable. Bash output inserts explicit
`[Output omitted: bytes start-end]` markers, with an exclusive end offset, between
retained chunks rather than silently joining gaps. Without that binding, existing
bash and native PTY execution are unchanged. No UI is added.

`watchOwnerTasks(owner, cursor?)` provides an opaque `lease`, snapshot,
decimal-string cursor and disposable `AsyncIterable<NativeEvent>`. Each iterator
observes one contiguous delivery epoch. On local backlog overflow or native journal
reset, the subscription updates its authoritative `snapshot` and `cursor`, discards
stale queued deltas, and completes the old iterator (`next()` returns `done:true`,
including an already-pending read). This also works when an oversized final settlement
leaves no retained event, without later activity or cleanup. No synthetic reset event
is inserted and the `NativeEvent` and subscription types are unchanged.

After any iterator completion, reconcile `subscription.snapshot` at
`subscription.cursor`. If the owner is still live and observation is still wanted,
obtain another iterator from the **same** `subscription.events`; the old iterator stays
done. Reset does not dispose the subscription or close the owner. Subsequent deltas
are authentic and ordered; ignore events at or below an already-applied snapshot
cursor. Explicit `dispose()` (idempotent) or breaking out of a live iterator ends
observation, not the owner. Owner closure also ends delivery. Track your own disposal
when deciding whether to resume. New subscriptions are refused once owner closing
begins; existing subscriptions continue through cleanup/closure.
Calling `dispose()` from `onReconcile` also stops the active drain from publishing
its retained events. Pending and newly created iterators finish without those events;
the reconciled snapshot remains available.

The optional `subscription.onReconcile` callback is a convenience, not required for
correctness; callback exceptions remain visible as `subscription.failure`. Raw strings
and Error messages are preserved; unprintable values (including hostile conversion or
revoked proxies) use `Unprintable JavaScript rejection`. Diagnostic conversion cannot
interrupt event delivery or rearming the fallback poll. Native callbacks are wake hints;
journal drains and reset snapshots are authoritative. Each live subscription has one
fallback poll, stopped on disposal or observed closure.
The native byte journal and facade delivery backlog are bounded. Each task separately
retains its most recent 256 accepted activity report IDs, SHA-256 payload hashes and
receipts (`TASK_REPORT_IDENTITY_WINDOW`). Within that window, identical payloads return
`duplicate` with the original cursor; conflicting payloads return `ReportConflict`.
Neither check emits events or refreshes retention order. An evicted ID is fresh: while
the task is live it is `accepted`, applies its activity again and gets a new cursor;
existing terminal and owner-close guards still apply. Terminal outcome reports and
their recorded receipts are retained separately for the task record's lifetime and
never evicted by activity churn. This bounds identity entry count, not caller ID length,
task count, terminal payloads or total task-history memory. S1 adds no persistence layer.

Activity IDs have no reserved spellings, including `runner-outcome`, empty strings
and isolated surrogates. The facade submits its own result through private trusted
runner support: the actor selects a free terminal identity and accepts the outcome
under the same lock. With at most 256 retained activity IDs, at most 257 distinct
candidates suffice; selection emits no events and retains no extra ID history.
Caller-supplied reports still use the unchanged `reportTaskOutcome` contract:
same-ID cross-kind reports conflict, and terminal replay retains its original receipt.
The internal support also reuses an accepted terminal identity, so a different result
cannot replace it; cancellation-first still rejects late natural outcomes. Normal,
rejected and setup-failure results all use this path without bypassing cleanup evidence.

Caller-provided strings retain their exact JavaScript UTF-16 code units, including
isolated surrogates, valid pairs and embedded NUL, across scopes, intent, operation/report
identity, activity, results and nested output/cleanup metadata. They remain ordinary
`string` fields, not encoded wrappers. Replacing a surrogate with U+FFFD is a changed
payload or identity, never an exact replay. Nonempty descriptions supply the title;
otherwise the first nonblank task line is copied without rewriting its code units,
falling back to the agent name. Absent optional fields, empty strings, known zero metrics
and ordered duplicate data remain distinct. The optional `elapsedMs`, `toolCount` and `tokenCount` metrics and
completed/failed `exitCode` preserve JavaScript numbers without narrowing or normalization,
including fractional and extreme values. Within the retained activity window (and for
terminal reports throughout the task record's lifetime), exact replay distinguishes
omission, zero and negative zero; repeated NaN and infinite values acknowledge once.
Changed numeric payloads return `ReportConflict` without earning another event. `OutputRef` is
metadata, not proof of retained bytes: output
storage, `readTaskOutput`, command input, persistence, completion delivery and
real agent/Intercom integration belong to later slices. The credential-free
repository fixture `test/fixtures/task-s1-demo.ts` exercises this real facade and
native actor with one fake runner.

### Task transcript references

An admitted runner can call `context.bindTranscript(sessionManager)` with its existing
child session history. `readTaskTranscript(task, cursor?)` in `core/tasks/transcript.ts`
reads that binding through the task capability. It returns message and content-block
references, not copied text: `id`, `kind`, `source`, and `toolCallId` when applicable.
Kinds are `prompt`, `assistant`, `tool-call`, `tool-result`, and `response`.
Thinking blocks and non-conversation entries are excluded. Repeated source IDs are
deduplicated; repeated messages with different IDs remain distinct.

The first page contains up to 100 recent references in source order. Pass the opaque
`nextCursor` to read earlier references; `omittedEarlier` identifies remaining older
content. Cursors belong to one task and bound session. An unknown task returns
`UnknownTask`, a cursor from another task/session returns `ScopeMismatch`, and an
unbound or empty history returns `TranscriptUnavailable` with `Transcript unavailable`.
This adapter does not launch work or reconstruct live capabilities from history.
Production subagent runners bind their child history, and main and attached workflow
chat hosts mount the shared inspector. Command detail reads are scoped to the current
selection and view lifetime: late results and errors cannot overwrite another view.