@greppleai/grip 0.0.0-stage → 0.0.1

package/docs/rules.md

@@ -0,0 +1,117 @@
+# Rules
+
+Rules are on-demand, mandatory instruction files. Use them for constraints and policies that must apply when the current task or files match the rule description.
+
+Rules use progressive disclosure like skills: Grip lists available rules in the system prompt, and the agent loads the full file only when applicable.
+
+## Locations
+
+Grip loads rules from:
+
+- Global:
+  - `~/.grip/agent/rules/`
+  - `~/.agents/rules/`
+- Project:
+  - `.grip/rules/`
+  - `.agents/rules/` in `cwd` and ancestor directories (up to git repo root, or filesystem root when not in a repo)
+- Packages: `rules/` directories or `grip.rules` entries in `package.json`
+- Settings: `rules` array with files or directories
+- CLI: `--rule <path>` (repeatable, additive even with `--no-rules`)
+
+Discovery rules:
+
+- In `~/.grip/agent/rules/` and `.grip/rules/`, direct root `.md` files are discovered as individual rules
+- In all rule locations, directories containing `RULES.md` are discovered recursively
+- In `~/.agents/rules/` and project `.agents/rules/`, root `.md` files are ignored
+
+Disable discovery with `--no-rules` (explicit `--rule` paths still load).
+
+## How Rules Work
+
+1. At startup, Grip scans rule locations and extracts names and descriptions
+2. The system prompt includes available rules in XML format
+3. When a task or file matches, the agent uses `read` to load the full `RULES.md`
+4. Applicable rules are mandatory and constrain normal behavior and skills
+
+Only descriptions are always in context. Full instructions load on demand.
+
+## Rule Commands
+
+Rules register as `/rule:name` commands when skill commands are enabled:
+
+```bash
+/rule:typescript          # Load the rule
+/rule:naming-conventions use for new files
+```
+
+Arguments after the command are appended to the rule content as user text.
+
+## Rule Structure
+
+A rule is a directory with a `RULES.md` file. Everything else is freeform.
+
+```text
+typescript/
+├── RULES.md
+└── references/
+    └── examples.md
+```
+
+### RULES.md Format
+
+```markdown
+---
+name: typescript
+description: Mandatory TypeScript rules. Load before editing *.ts or *.tsx files.
+---
+
+# TypeScript Rules
+
+- No `any` unless absolutely necessary.
+- Use top-level imports only.
+```
+
+Use relative paths from the rule directory:
+
+```markdown
+See [examples](references/examples.md).
+```
+
+## Frontmatter
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Max 64 chars. Lowercase a-z, 0-9, hyphens. Falls back to parent directory name. |
+| `description` | Yes | Max 1024 chars. Defines when the rule applies. |
+| `tools` | No | Tool name or YAML list of lazy tools to load automatically when the rule is loaded via `read` or `/rule:name`. |
+| `disable-model-invocation` | No | When `true`, the rule is hidden from the system prompt. Users must use `/rule:name`. |
+
+Example with associated lazy tools:
+
+```yaml
+---
+name: github-review
+description: Mandatory PR review rules. Load when reviewing GitHub pull requests.
+tools:
+  - github_get_pr
+  - github_list_review_comments
+---
+```
+
+When the agent loads this rule, Grip loads those tools into the active tool context for the next turn.
+
+## Description Best Practices
+
+The description determines when the agent loads the rule. Write applicability, not capability.
+
+Good:
+
+```yaml
+description: Mandatory TypeScript rules. Load before editing *.ts or *.tsx files.
+```
+
+Poor:
+
+```yaml
+description: TypeScript help.
+```

package/docs/sandbox.md

@@ -0,0 +1,181 @@
+# Workspace Sandbox
+
+`/sandbox` is the single interactive command for workspace tool backends. It can show or clear the active backend, attach an existing sandbox daemon, or manage a Docker container or Lima VM. Sandbox connections are session-local: a new session starts on its underlying backend, returning to an earlier session reconnects its remembered sandbox while Grip remains running, and multiple session sandboxes may coexist. Local Grip remains the orchestrator: provider credentials, model calls, session history, extensions, RPC, and UI stay in the local process; subagent workspace tools inherit the parent session's active sandbox.
+
+The command is user-only. It is shown in interactive slash-command completion, but it is not exposed through RPC `get_commands`, extension-visible command catalogs, system prompts, tool definitions, prompt templates, skills, or rules. This only hides the Grip operator command from LLM-visible catalogs; it does not prevent a model with host shell access from invoking Docker or Lima directly.
+
+## Commands
+
+Type these commands in interactive mode:
+
+```text
+/sandbox [status]
+/sandbox clear
+/sandbox --attach <ws://url>
+/sandbox start [--runtime docker|lima] [--image <image>] [--name <lima-instance>] [--template <lima-template>]
+/sandbox list [--runtime docker|lima]
+/sandbox stop [sandbox]
+```
+
+- `/sandbox` and `/sandbox status` show the active workspace tool backend.
+- `/sandbox clear` disconnects the active deferred or sandbox backend without stopping a managed container or VM.
+- `/sandbox --attach` connects to an already-running sandbox daemon without starting or managing its container. Set `GRIP_REMOTE_TOKEN` when the daemon requires authentication. The daemon workspace root must match `--remote-cwd` in deferred mode, or `sandbox.workspaceMountPath` (default `/workspace`) otherwise.
+- `/sandbox start` launches a Docker container by default. With `--runtime lima`, it creates a Lima VM from `template:docker-rootful`, mounts the current working directory read-write at `/workspace`, starts `grip --daemon` inside the VM, and switches workspace tools and project resource loading to that daemon. Use `--template` to override the Lima template for a new VM. Passing `--name` implies `--runtime lima` when no runtime is specified; without `--name`, runtime selection is unchanged. `--name` creates the named instance if missing, starts it if stopped, or reuses it if running. Existing instances must already have a writable `/workspace` mount mapping to the current directory. Explicitly named VMs remain running after `/sandbox stop` or graceful Grip shutdown; only their Grip daemon is stopped, regardless of `sandbox.cleanup`.
+- `/sandbox list` lists sandboxes for the current workspace. Use `/sandbox list --runtime lima` to list matching Lima instances that can be reused by name.
+- `/sandbox stop` stops the active Grip-owned sandbox. For a daemon connected with `--attach`, it only detaches and restores the previous tool backend. Explicitly named Lima VMs remain running, but their Grip daemon is stopped. With an id or name, it uses the active runtime, or `sandbox.runtime` when no sandbox is active. Ambiguous cases require an explicit target.
+
+Example:
+
+```text
+GRIP_REMOTE_TOKEN=... grip
+/sandbox --attach ws://127.0.0.1:8787/grip/workspace
+/sandbox stop
+
+/sandbox start --image grip-sandbox:local
+/sandbox list
+
+/sandbox start --runtime lima
+/sandbox start --runtime lima --template template:alpine
+/sandbox list --runtime lima
+/sandbox stop
+
+/sandbox start --name my-dev
+/sandbox stop
+```
+
+When start succeeds, Grip shows the sandbox name/id, the host-to-sandbox workspace mount, a redacted daemon endpoint, and a status line that workspace tools/resources now route through the sandbox daemon.
+
+## Workspace mount and daemon endpoint
+
+Defaults:
+
+| Setting | Default |
+| --- | --- |
+| Host workspace | current working directory |
+| Container workspace | `/workspace` |
+| Daemon command | `grip --daemon` |
+| Docker network mode | `bridge` |
+| Daemon preferred bind and endpoint | `127.0.0.1:8787` |
+| Daemon token | generated per start |
+| Lima binary | `limactl` |
+| Lima template | `template:docker-rootful` |
+
+The mounted workspace is read/write. Any process in the container can modify files in the mounted host directory. Paths reported by the daemon use the container workspace root (`/workspace`), while local Grip keeps session and UI state on the host. The container uses Docker bridge networking and publishes only the authenticated daemon port to the configured host bind address (`127.0.0.1` by default), so sandbox processes cannot directly access host loopback services. Grip uses the configured daemon port when available and otherwise selects an available host port, allowing separate sessions to keep concurrent sandbox containers. The default image also configures `/tmp` as an additional confined temporary root, so workspace tools can use disposable scratch files without exposing another host mount.
+
+Sandbox bash calls receive the current `GRIP_SESSION_ID`, `GRIP_SESSION_FILE`, `GRIP_PROVIDER`, `GRIP_MODEL`, and `GRIP_REASONING_LEVEL` values per invocation. This metadata follows the active session rather than the daemon process environment; other host environment variables are not forwarded automatically.
+
+`/sandbox start` uses a fresh bearer token for every daemon. Docker receives it through the container environment. Lima generates it inside the guest and returns it directly to the host launcher. Grip keeps the token in memory and uses it to connect to the daemon. Tokens are not put in Docker or Lima command arguments, image layers, container or instance names, labels, URLs, or user-facing status. Status, list output, and errors redact secrets.
+
+## Image and configuration
+
+The configured default image is `ghcr.io/greppleai/grip-sandbox:latest`, but its publication has not been verified. Until it is available, build a reviewed local image below or configure a verified compatible replacement; do not assume the default image can be pulled. The local example image uses integrated `grip --daemon` from `@greppleai/grip`. There is no separate Grip daemon package or binary.
+
+When a sandbox daemon connects, Grip also loads `~/.grip/AGENTS.md` from the daemon user's home directory as user-scoped context. This is separate from the orchestrator's global instructions and lets custom Docker images or Lima users define instructions that apply only inside the sandbox. Create or update the file inside the sandbox, then run `/reload` to refresh context.
+Configuration precedence for a start is:
+
+1. command flags: `/sandbox start --runtime <runtime>`, `--image <image>`, `--name <lima-instance>`, and `--template <lima-template>`;
+2. environment variables: `GRIP_SANDBOX_*`;
+3. project settings in `.grip/settings.json`;
+4. global settings in `~/.grip/agent/settings.json`;
+5. defaults.
+
+Sandbox settings:
+
+```json
+{
+  "sandbox": {
+    "runtime": "docker",
+    "image": "grip-sandbox:local",
+    "dockerBinary": "docker",
+    "limaBinary": "limactl",
+    "limaTemplate": "template:docker-rootful",
+    "limaInstanceNamePrefix": "grip-sandbox",
+    "workspaceMountPath": "/workspace",
+    "containerNamePrefix": "grip-sandbox",
+    "daemonPort": 8787,
+    "daemonHostBind": "127.0.0.1",
+    "cleanup": "stop"
+  }
+}
+```
+
+Environment overrides:
+
+| Variable | Setting |
+| --- | --- |
+| `GRIP_SANDBOX_RUNTIME` | `sandbox.runtime` (`docker` or `lima`) |
+| `GRIP_SANDBOX_IMAGE` | `sandbox.image` |
+| `GRIP_SANDBOX_DOCKER` | `sandbox.dockerBinary` |
+| `GRIP_SANDBOX_LIMA` | `sandbox.limaBinary` |
+| `GRIP_SANDBOX_LIMA_TEMPLATE` | `sandbox.limaTemplate` |
+| `GRIP_SANDBOX_LIMA_INSTANCE_PREFIX` | `sandbox.limaInstanceNamePrefix` |
+| `GRIP_SANDBOX_WORKSPACE_MOUNT` | `sandbox.workspaceMountPath` |
+| `GRIP_SANDBOX_CONTAINER_PREFIX` | `sandbox.containerNamePrefix` |
+| `GRIP_SANDBOX_DAEMON_PORT` | `sandbox.daemonPort` |
+| `GRIP_SANDBOX_DAEMON_HOST_BIND` | `sandbox.daemonHostBind` |
+| `GRIP_SANDBOX_CLEANUP` | `sandbox.cleanup` (`stop` or `remove`) |
+
+## Base image
+
+Build the local base image from repository release artifacts:
+
+```bash
+npm run release:local -- --out /tmp/grip-local-release --force
+docker build \
+  -f packages/coding-agent/examples/sandbox-docker/Dockerfile \
+  -t grip-sandbox:local \
+  /tmp/grip-local-release
+```
+
+Then use it for one start:
+
+```text
+/sandbox start --image grip-sandbox:local
+```
+
+Or make it the default:
+
+```bash
+GRIP_SANDBOX_IMAGE=grip-sandbox:local grip
+```
+
+See [`../examples/sandbox-docker/README.md`](../examples/sandbox-docker/README.md) for image build inputs and manual `docker run` commands.
+
+## Sandbox identity, list, and stop
+
+Grip labels sandbox containers and filters list/stop operations by those labels, not by name alone. Labels include sandbox ownership, workspace hash, workspace mount target, daemon port, owner uid when available, Grip version, and a session id. Labels do not contain tokens.
+
+Docker container names use the configured prefix plus a sanitized workspace name, workspace hash, and per-start session suffix. Managed Lima names use `sandbox.limaInstanceNamePrefix` with the same workspace/session identity and a random suffix. Daemon ports are allocated per start, preferring `sandbox.daemonPort` and falling back to an available host port. `/sandbox list --runtime lima` reports Lima instances whose writable `/workspace` mount maps to the current host workspace; their names can be passed back to `/sandbox start --runtime lima --name <name>`. Explicitly named VMs are left running by `/sandbox stop`, whether newly created or reused, while Grip stops or removes automatically named VMs according to `sandbox.cleanup`.
+
+Stopping the active sandbox clears the current session's remote tool backend and returns it to the previous non-sandbox backend or local tool execution. If Grip was started in deferred remote mode, stop leaves that session's deferred backend unconfigured. Switching sessions disconnects the old live client without stopping its managed sandbox; returning to that session reconnects it from memory. On graceful Grip shutdown, Docker containers and automatically named Lima instances started by that Grip process are stopped or removed according to `sandbox.cleanup`; explicitly named Lima VMs remain running with their Grip daemon stopped. Tokens are never persisted to session files, so sandboxes are not restored after Grip exits.
+
+## Security boundaries
+
+Docker and Lima sandbox modes are not complete security sandboxes.
+
+- The current working directory is mounted read/write into the container or VM.
+- Subagents inherit the active workspace backend. Sandboxed subagents reject host cwd overrides, do not load host project context or extensions, treat custom system prompts as literal text, and cannot continue an older run after the parent backend changes.
+- Sandbox processes can read, write, delete, or chmod files in that mount as the guest user.
+- Files created by the default image are owned by uid `1000` unless Docker/user policy changes it.
+- `/tmp` is writable container-local scratch storage and is removed with the container; it is not mounted from the host by default.
+- The daemon token authorizes high-privilege workspace tool access for the mounted workspace.
+- Anyone with Docker access on the host may inspect containers, images, mounts, labels, ports, and environment depending on host policy.
+- Override Docker images and Lima templates are trusted code. A malicious image or template can run arbitrary processes against the mounted workspace.
+- Docker socket mounts, privileged mode, broad host volumes, or extra credentials can further break the intended boundary.
+- Bridge networking prevents direct host-loopback access, but the container may still reach external networks and host services deliberately exposed beyond loopback.
+- Reused Lima instances retain their existing filesystem, software, credentials, and network access; only reuse instances you trust.
+- Hidden command behavior only keeps `/sandbox` out of LLM-visible Grip catalogs. It is not an OS, Docker, or VM permission boundary.
+
+Use trusted images, avoid mounting the Docker socket, avoid privileged containers, keep `sandbox.daemonHostBind` loopback-only unless you add a separate trusted network/TLS boundary, and do not place secrets in the mounted workspace unless the sandbox image should access them.
+
+## Troubleshooting
+
+- Docker missing: install Docker or set `GRIP_SANDBOX_DOCKER` / `sandbox.dockerBinary` to the correct executable.
+- Lima missing: install Lima or set `GRIP_SANDBOX_LIMA` / `sandbox.limaBinary`. Newly created Lima VMs, including explicitly named ones, provision the current `@greppleai/grip` version through npm when `grip` is missing; reused instances must already provide a compatible `grip` command. Provisioning requires an apt-based guest and package availability.
+- Permission denied connecting to Docker: add the user to the appropriate Docker group, start Docker Desktop, or run Grip where Docker is accessible. Treat Docker group membership as host-level administrative power.
+- Image pull/build failure: verify the image name, registry authentication, network access, and local build command. For local images, build with the local release directory as context; do not use `--skip-install` for the sandbox Dockerfile.
+- Port conflict: Grip prefers the configured daemon port (default `8787`) and automatically selects an available port when it is occupied. A remaining bind failure can indicate an invalid `sandbox.daemonHostBind`, exhausted local resources, or a race with another process.
+- Start succeeds but daemon activation fails: the container or VM may still be running. Use the runtime-specific `/sandbox list` and `/sandbox stop <id-or-name>` commands to clean it up.
+- `/sandbox list` is empty: Docker listing only includes Grip-labeled containers; Lima listing only includes instances with the current workspace mounted at `/workspace`. Check that you selected the intended runtime and workspace.
+- `/sandbox stop` says no sandbox was found: pass the listed id or name, or switch to the workspace that owns the sandbox.
+- Already stopped: stop is idempotent for matching containers and reports already-stopped containers cleanly.

package/docs/sdk.md

@@ -0,0 +1,360 @@
+> Grip can help you use the SDK. Ask it to build an integration for your use case.
+
+# SDK
+
+The SDK provides programmatic access to Grip's agent capabilities. Use `GripAgent` as the composition root for embedded apps, custom interfaces, automated workflows, and tests.
+
+See [examples/sdk/](../examples/sdk/) for working examples from minimal to full control.
+
+`CreateGripAgentOptions.hooks` controls Claude-compatible hooks. Automatic discovery is user-only. Set the host-only `trustProjectHooks: true` only after approving the destination repository; it does not discover project hooks when the initial workspace backend is non-local. Once an approved local snapshot exists, project/local command hooks follow later backend transitions and execute inside sandbox/remote operations rather than on the host. Project/local HTTP hooks fail closed on non-local backends. User hooks and `hooks.snapshot` remain trusted host configuration, while `hooks.allowedHttpHookUrls` and `hooks.httpHookAllowedEnvVars` impose host ceilings. See [hooks.md](hooks.md).
+
+## Quick Start
+
+```typescript
+import { AuthStorage, InMemorySessionManager, ModelRegistry, GripAgent } from "@greppleai/grip";
+
+const authStorage = AuthStorage.create();
+const modelRegistry = ModelRegistry.create(authStorage);
+const pi = await GripAgent.create({
+  sessionManager: new InMemorySessionManager(),
+  authStorage,
+  modelRegistry,
+});
+
+const session = await pi.createAgentSession();
+
+session.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+
+await session.prompt("What files are in the current directory?");
+await pi.dispose();
+```
+
+## Core Concepts
+
+### GripAgent
+
+`GripAgent` owns shared app services, the session lifecycle backend, and the current active `AgentSession`.
+
+```typescript
+import { InMemorySessionManager, GripAgent } from "@greppleai/grip";
+
+const pi = await GripAgent.create({
+  sessionManager: new InMemorySessionManager(),
+});
+
+const session = await pi.createAgentSession();
+```
+
+The session manages agent lifecycle, message history, model state, compaction, and event streaming.
+
+```typescript
+interface AgentSession {
+  // Send a prompt and wait for completion
+  prompt(text: string, options?: PromptOptions): Promise<void>;
+
+  // Queue messages during streaming
+  steer(text: string): Promise<void>;
+  followUp(text: string): Promise<void>;
+
+  // Subscribe to events (returns unsubscribe function)
+  subscribe(listener: (event: AgentSessionEvent) => void): () => void;
+
+  // Session info
+  sessionFile: string | undefined;
+  sessionId: string;
+
+  // Model control
+  setModel(model: Model): Promise<void>;
+  setThinkingLevel(level: ThinkingLevel): void;
+  cycleModel(): Promise<ModelCycleResult | undefined>;
+  cycleThinkingLevel(): ThinkingLevel | undefined;
+
+  // State access
+  agent: Agent;
+  model: Model | undefined;
+  thinkingLevel: ThinkingLevel;
+  messages: AgentMessage[];
+  isStreaming: boolean;
+
+  // In-place tree navigation within the current session file
+  navigateTree(targetId: string, options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string }): Promise<{ editorText?: string; cancelled: boolean }>;
+
+  // Compaction
+  compact(customInstructions?: string): Promise<CompactionResult>;
+  abortCompaction(): void;
+
+  // Abort current operation
+  abort(): Promise<void>;
+
+  // Cleanup
+  dispose(): void;
+}
+```
+
+Most one-off session options can be passed directly to `GripAgent.create()`:
+
+```typescript
+const pi = await GripAgent.create({
+  cwd: process.cwd(),
+  model,
+  thinkingLevel: "high",
+  tools: ["read", "grep", "find", "ls"],
+  authStorage,
+  modelRegistry,
+  settingsManager,
+  resourceLoader,
+  sessionManager,
+});
+```
+
+Use `pi.createAgentSession({ session })` when you already have an opened or created `Session`. Here `pi` is the example's local `GripAgent` instance.
+
+### AgentSession
+
+`AgentSession` owns active conversation behavior: prompts, message history, model state, compaction, event streaming, and in-place tree navigation.
+
+Use `session.sessionReference` when you need the backend-neutral active session reference. For local JSONL sessions this is the session file path; for in-memory sessions it is `undefined`. `session.sessionFile` remains available as a local-file-oriented alias.
+
+Session replacement APIs such as new-session, resume, fork, clone, and import live on `GripAgent`, not on `AgentSession`.
+
+```typescript
+interface PromptOptions {
+  expandPromptTemplates?: boolean;
+  images?: ImageContent[];
+  streamingBehavior?: "steer" | "followUp";
+  source?: InputSource;
+  preflightResult?: (success: boolean) => void;
+}
+```
+
+### SessionManager and Session
+
+`SessionManager` handles lifecycle and discovery: create, open, continue, list, fork, and import. It returns a `Session`.
+
+`Session` owns active persisted conversation state and tree operations.
+
+## Prompting
+
+```typescript
+await session.prompt("What files are here?");
+
+await session.prompt("What's in this image?", {
+  images: [{ type: "image", source: { type: "base64", mediaType: "image/png", data: "..." } }],
+});
+
+await session.prompt("After you're done, also check X", { streamingBehavior: "followUp" });
+```
+
+Use `steer()` or `followUp()` for explicit queueing during streaming:
+
+```typescript
+await session.steer("New instruction");
+await session.followUp("After you're done, also do this");
+```
+
+## Events
+
+```typescript
+const unsubscribe = session.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+```
+
+Subscriptions are attached to a specific `AgentSession`. Re-subscribe after `GripAgent` replaces the active session.
+
+## Session Replacement
+
+```typescript
+import { LocalSessionManager, GripAgent } from "@greppleai/grip";
+
+const pi = await GripAgent.create({
+  cwd: process.cwd(),
+  sessionManager: new LocalSessionManager({ cwd: process.cwd() }),
+});
+
+await pi.createAgentSession();
+await pi.newSession();
+await pi.switchSession("/path/to/session.jsonl");
+await pi.fork("entry-id");
+await pi.fork("entry-id", { position: "at" });
+await pi.importFromJsonl("/path/to/old-session.jsonl");
+```
+
+After replacement, use `pi.session` for the new active `AgentSession`.
+
+## Common Configuration
+
+### Model
+
+```typescript
+import { getModel } from "@greppleai/grip-ai";
+import { AuthStorage, ModelRegistry, GripAgent } from "@greppleai/grip";
+
+const authStorage = AuthStorage.create();
+const modelRegistry = ModelRegistry.create(authStorage);
+const model = getModel("anthropic", "claude-opus-4-5");
+
+const pi = await GripAgent.create({
+  authStorage,
+  modelRegistry,
+  model,
+  thinkingLevel: "medium",
+});
+const session = await pi.createAgentSession();
+```
+
+### API keys and OAuth
+
+```typescript
+const authStorage = AuthStorage.create();
+const modelRegistry = ModelRegistry.create(authStorage);
+authStorage.setRuntimeApiKey("anthropic", "sk-my-temp-key");
+
+const pi = await GripAgent.create({ authStorage, modelRegistry });
+await pi.createAgentSession();
+```
+
+### Resource loading
+
+Use `DefaultResourceLoader` to override or discover extensions, skills, rules, prompt templates, themes, and context files.
+
+```typescript
+const loader = new DefaultResourceLoader({
+  cwd: process.cwd(),
+  agentDir: getAgentDir(),
+  systemPromptOverride: () => "You are a helpful assistant.",
+});
+await loader.reload();
+
+const pi = await GripAgent.create({ resourceLoader: loader });
+await pi.createAgentSession();
+```
+
+### Tools
+
+```typescript
+const pi = await GripAgent.create({
+  tools: ["read", "grep", "find", "ls"],
+  noTools: "builtin",
+  customTools: [myTool],
+});
+await pi.createAgentSession();
+```
+
+Built-in tool names include `read`, `bash`, `edit`, `write`, `websearch`, `session_search`, `session_entry_get`, `compress_context`, `grep`, `find`, `ls`, `subagent`, `subagent_runs`, `create_subagent`, and the `lsp_*` navigation/refactoring tools. The subagent and LSP tool families are inactive by default. Set `enableSubagents: true` in settings to activate subagents or `enableLspTools: true` in settings or `GripAgent.create()` to expose configured LSP tools. An explicit `tools` option selects any subset regardless of these defaults; `noTools: "all"` and `noTools: "builtin"` remain authoritative.
+
+### Settings
+
+```typescript
+const settingsManager = SettingsManager.inMemory({
+  enableSubagents: true,
+  compaction: { enabled: false },
+  retry: { enabled: true, maxRetries: 2 },
+});
+
+const pi = await GripAgent.create({ settingsManager });
+await pi.createAgentSession();
+```
+
+For a live session, `session.setSubagentsEnabled(enabled)` persists the setting and immediately refreshes active tools and orchestration guidance. `session.reload()` applies settings-file changes.
+
+## Language servers
+
+Each active `AgentSession` owns exactly one LSP runtime; `GripAgent` resolves its configuration and replaces it with the session lifecycle. Supply the same validated configuration used by settings or the CLI through `lsp`:
+
+```typescript
+import { InMemorySessionManager, GripAgent } from "@greppleai/grip";
+
+const pi = await GripAgent.create({
+  cwd: process.cwd(),
+  sessionManager: new InMemorySessionManager(process.cwd()),
+  enableLspTools: true,
+  lsp: {
+    type: "configuration",
+    configuration: {
+      servers: [
+        {
+          id: "typescript",
+          selectors: [{ languageId: "typescript", pattern: "**/*.ts" }],
+          transport: { type: "tcp", host: "127.0.0.1", port: 2087 },
+          lifecycle: { type: "attached" },
+          workspace: { type: "session" },
+        },
+      ],
+    },
+  },
+});
+
+const session = await pi.createAgentSession();
+console.log(session.getLspStatus());
+```
+
+Hosts can also provide `lspConnectionFactories`, grant `trustProjectLspTransports` after applying their own trust policy, and return destination-specific LSP options from `resolveSessionOptions`. The grant covers every active project-origin transport and positive project `enabled: true` activation because both commands and attached endpoints can expose document content; project settings cannot grant it to themselves. `GripAgent.create()` and `resolveSessionOptions` inputs propagate through new, resumed, forked, and cross-cwd replacement sessions; source-relative paths are re-resolved for the destination cwd. Use `session.configureLsp(layer)` for a validated session-runtime-only replacement; normal reload or session replacement re-applies the configured sources. `session.reload()` returns current raw, source- and JSON-path-attributed LSP configuration diagnostics. `pi.diagnostics` exposes formatted diagnostics from initial session creation and refreshes them after reload or session replacement. Invalid or unreadable LSP configuration yields nonfatal diagnostics at the applicable error or warning severity and an empty disabled LSP state rather than retaining stale runtime state; unrelated application diagnostics remain fatal.
+
+See [Language Server Protocol](lsp.md) for complete configuration, a host-provided connection-factory example, lifecycle ownership, status fields, reload behavior, and migration guidance.
+
+## Run Modes
+
+The SDK exports run mode utilities for building custom interfaces on top of `GripAgent`.
+
+```typescript
+import { InteractiveMode, LocalSessionManager, GripAgent, runPrintMode, runRpcMode } from "@greppleai/grip";
+
+const pi = await GripAgent.create({
+  cwd: process.cwd(),
+  sessionManager: new LocalSessionManager({ cwd: process.cwd() }),
+});
+await pi.createAgentSession();
+
+await runPrintMode(pi, {
+  mode: "text",
+  initialMessage: "Hello",
+  initialImages: [],
+  messages: [],
+});
+
+await runRpcMode(pi);
+
+const mode = new InteractiveMode(pi, {
+  migratedProviders: [],
+  modelFallbackMessage: pi.modelFallbackMessage,
+  initialMessage: "Hello",
+  initialImages: [],
+  initialMessages: [],
+});
+await mode.run();
+```
+
+See [RPC documentation](rpc.md) for the JSON protocol.
+
+## Main Exports
+
+```typescript
+GripAgent
+AgentSession
+AuthStorage
+ModelRegistry
+DefaultResourceLoader
+defineTool
+InMemorySessionManager
+LocalSessionManager
+SettingsManager
+createEventBus
+createCodingTools
+createReadOnlyTools
+createReadTool, createBashTool, createEditTool, createWriteTool
+createGrepTool, createFindTool, createLsTool, createSubagentTool
+LspClient, LspManager, LspFileSync, LspRouter, LspPathMapper
+loadLspConfiguration, parseLspConfiguration, resolveLspConfiguration
+createManagedStdioConnectionFactory, createTcpConnectionFactory
+registerStandaloneLspLifecycleHandlers
+```
+
+The package root curates the public LSP API directly from the modules under `core/lsp/`. `createSubagentTool` requires a `SubagentRunner` in its options. `GripAgent` configures the embedded runner automatically; standalone tool construction must provide its own in-process runner.
+For extension types, see [extensions.md](extensions.md). For LSP configuration, lifecycle, transport, routing, status, and public type exports, see [Language Server Protocol](lsp.md).