@greppleai/grip 0.0.0-stage → 0.1.3

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,104 @@
+# Workspace Sandbox
+
+`/sandbox` is the user-only interactive command for workspace tool backends. It can show or clear the active backend, attach an existing sandbox daemon, or manage a Lima VM. Connections are session-local: switching back to an earlier session reconnects its remembered sandbox while Grip remains running. Local Grip retains provider credentials, model calls, session history, extensions, RPC, and UI; subagent workspace tools inherit the active backend.
+
+The command appears in slash-command completion but not in model-visible catalogs, system prompts, tool definitions, templates, skills, or rules. This is not a permission boundary: a model with host shell access may still invoke Lima directly.
+
+## Commands
+
+```text
+/sandbox [status]
+/sandbox clear
+/sandbox --attach <ws://url>
+/sandbox start [--name <lima-instance>] [--template <lima-template>] [--update]
+/sandbox list
+/sandbox stop [vm]
+```
+
+- `/sandbox status` shows the active workspace tool backend. `/sandbox clear` disconnects it without stopping a VM.
+- `/sandbox --attach` connects to an already-running daemon without managing its lifecycle. Set `GRIP_REMOTE_TOKEN` if required. The daemon workspace root must match `--remote-cwd` in deferred mode, or `sandbox.workspaceMountPath` otherwise.
+- `/sandbox start` creates a per-session Lima VM with the current working directory mounted read/write at `/workspace`. `--template` overrides the VM template for a new instance. `--name` creates an absent VM, resumes a stopped per-session VM, or attaches to a running VM after guest-mode inspection. A running VM with a verified shared guest-state marker uses the direct shared-daemon protocol; a VM without it follows the per-session path.
+- `/sandbox start --name <running-shared-VM> --update` updates a verified shared guest and reconnects this TUI. It stages and validates the replacement first, stops its supervised daemon (disconnecting every attached client), atomically replaces the executable, and restarts the same service. It cannot be combined with `--template`; legacy, stopped, or unverifiable VMs are refused without disconnecting anyone.
+- `/sandbox list` shows Lima instances mounting the current workspace. A shared VM mounting a parent might not appear from a child workspace; attach by exact name instead.
+- `/sandbox stop` stops only tracked per-session daemons and process-owned VMs. For a shared named VM or an attached daemon it detaches the current session only. A matching name or mount does not establish ownership; named per-session VMs remain running after daemon stop. Grip never stops another client's shared guest or VM.
+
+```text
+/sandbox start
+/sandbox start --template template:alpine
+/sandbox list
+/sandbox stop
+/sandbox start --name my-dev
+/sandbox start --name my-dev --update
+/sandbox stop
+```
+
+A successful start shows the VM name/id, host-to-guest workspace mount, redacted daemon endpoint, and backend status. Workspace tools and resources then route through the guest daemon. Sandbox bash calls receive the current `GRIP_SESSION_ID`, `GRIP_SESSION_FILE`, `GRIP_PROVIDER`, `GRIP_MODEL`, and `GRIP_REASONING_LEVEL` metadata for the active session; other host environment variables are not forwarded automatically.
+
+## Configuration
+
+The mounted workspace is writable. The daemon normally binds through a host loopback forward on port `8787`; newly created VMs select an available port if necessary. New per-session daemons use fresh bearer tokens. Running shared guests retain their existing token, retrieved by each local TUI via Lima access. Grip keeps tokens in memory and redacts them from displayed output. Tokens are not stored in session files, so sandbox backends are not restored after Grip exits.
+
+Start precedence: command `--template`, then `GRIP_SANDBOX_*` environment variables, project `.grip/settings.json`, global `~/.grip/agent/settings.json`, then defaults. Available settings:
+
+```json
+{
+  "sandbox": {
+    "limaBinary": "limactl",
+    "limaTemplate": "template:docker-rootful",
+    "limaInstanceNamePrefix": "grip-sandbox",
+    "workspaceMountPath": "/workspace",
+    "daemonPort": 8787,
+    "daemonHostBind": "127.0.0.1",
+    "cleanup": "stop"
+  }
+}
+```
+
+| Environment variable | Setting |
+| --- | --- |
+| `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_DAEMON_PORT` | `sandbox.daemonPort` |
+| `GRIP_SANDBOX_DAEMON_HOST_BIND` | `sandbox.daemonHostBind` |
+| `GRIP_SANDBOX_CLEANUP` | `sandbox.cleanup` (`stop` or `remove`) |
+| `GRIP_SANDBOX_GUEST_BINARY` | Explicit local Linux ELF guest executable for development |
+
+The default Lima template name contains `docker-rootful`; it is a Lima VM template choice, not a Docker-container sandbox runtime. Change `sandbox.limaTemplate` or use `--template` to select a different Lima template.
+
+### Guest Grip during development
+
+A new managed VM installs an exact-version Linux Grip release using the checksummed repository installer, when those release assets are published. Existing named VMs must already provide Grip. To test local code, cross-compile a Linux binary matching the guest architecture and opt in:
+
+```bash
+NODE_OPTIONS=--import=tsx ./scripts/build-binaries.sh --skip-install --platform linux-x64
+GRIP_SANDBOX_GUEST_BINARY="$PWD/packages/coding-agent/binaries/grip-linux-x64" ./grip-test.sh
+# In Grip: /sandbox start --name my-dev --update
+```
+
+For ARM64 use `--platform linux-arm64` and `grip-linux-arm64`. The ELF is validated, copied via `limactl copy` only when safe, checked against its SHA-256 and version, and installed at `~/.local/bin/grip`. An identical installation is reused. Normal attachment never replaces the running shared guest's binary. Explicit `--update` uses `GRIP_SANDBOX_GUEST_BINARY` when set; a source/tsx development session requires it rather than silently installing a release. Otherwise the update downloads the checksummed Linux release matching the Grip version that issued the command. The shared systemd unit must already run `~/.local/bin/grip`; other service binary paths require manual reconciliation. Downloads and validation complete before client disconnection. An uncertain install or restart leaves the VM for inspection. The guest needs `sha256sum` and `/proc`.
+
+## Direct shared Lima attachment
+
+In each host workspace run `/sandbox start --name <running-shared-VM>`. The VM must already have a fixed writable parent mount, matching loopback forward, exact-version guest Grip, and a verified `~/.cache/grip/shared-lima` guest-state directory. Its systemd user manager must be running with linger enabled so Grip can start or reuse a supervised shared daemon. This command does not provision a new shared VM or convert a legacy one: a running VM without the shared marker takes the per-session path.
+
+Each TUI obtains the guest credential through local Lima access and opens its own authenticated v2 WebSocket workspace channel. Parent-root clients can access their children; shared file writes and edits use revision preconditions, but shell writes can still race. Transfers are unavailable in shared mode. `/sandbox stop` and `/sandbox clear` detach only the current TUI; neither stops the shared daemon or VM. Coordinate all clients and independently verify ownership before any manual guest or VM shutdown.
+
+Grip probes guest mode under the named owner lock before any legacy setup. A missing marker follows the per-session path; unreadable, symlinked, or ambiguous state refuses attachment. A stopped shared VM with a mismatched mount is not automatically resumed. Per-session start and stop check for shared guest state before rotating or killing a legacy daemon. Noncooperating programs may ignore these locks; a VM name alone proves nothing.
+
+Shared startup requires guest `systemd-run --user`, `systemctl --user`, and `loginctl ... Linger=yes` already enabled by an operator. Grip launches one transient `grip-shared-lima-PORT.service` with `Restart=no`; it does not automatically restart failed units or retry uncertain operations. The unit reads its private 0600 token file without passing credentials in service arguments. Grip verifies its MainPID against a boot-ID/process-start-time-bound PID record before reuse. Missing manager, mismatched process identity, or uncertain guest state require manual reconciliation; guest shutdown remains explicit.
+
+## Lifecycle and security
+
+Automatically named, process-owned VMs follow `sandbox.cleanup` on graceful Grip shutdown, subject to stopped-VM uncertainty. Tracked per-session named Lima daemons stop without stopping their VMs. A failed readiness check leaves uncertain guest state for manual reconciliation. Shared guest daemons and VMs remain running. Session switches reconnect remembered channels while the process remains running.
+
+Lima VMs are not complete security sandboxes. The workspace is mounted read/write and guest processes can modify it as the guest user. Subagents inherit the active workspace backend, reject host cwd overrides, and do not load host project context or extensions. The daemon token grants privileged workspace tool access. Reused VMs retain their own software, credentials, filesystem, and network access; use only trusted instances and Lima templates. Keep `sandbox.daemonHostBind` loopback-only unless you provide a separate trusted network/TLS boundary, and do not store secrets in the mounted workspace unless the guest should read them.
+
+## Troubleshooting
+
+- Lima missing: install Lima or configure `GRIP_SANDBOX_LIMA` / `sandbox.limaBinary`. New managed VMs require the published exact-version guest installer; reused VMs must provide a matching binary.
+- Port conflict: a newly created VM selects an available port; a running shared VM requires its configured forward to match exactly.
+- Activation failure: inspect VM and daemon state before retrying; do not stop an unverified VM or other shared clients.
+- Empty `/sandbox list`: only instances mounting the current workspace appear. An ancestor-mounted shared VM may not appear from a child directory; attach by name.
+- `/sandbox stop` not found: use the listed id or name, or switch to the owning workspace. Stopped or uncertain VMs require manual reconciliation before removal.

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).