apex-code 0.5.0 → 0.5.2

package/docs/containerization.md

@@ -1,4 +1,4 @@
-# Containerization
+# Run Apex Code in an isolated environment
 
 Apex Code ships no built-in sandbox. A session runs with the permissions of the account
 that started it, on every platform, so containment is something you provide rather than
@@ -13,7 +13,7 @@ There are two general options. You can either
 1. run the whole `apex-code` process inside an isolated environment, or
 2. run `apex-code` on the host and route tool execution into an isolated environment.
 
-## Choose a pattern
+## Choose an isolation method
 
 | Pattern | What is isolated | Best for | Notes |
 | --- | --- | --- | --- |
@@ -23,12 +23,16 @@ There are two general options. You can either
 
 Extensions run wherever the `apex-code` process runs. If you run host `apex-code` with a tool-routing extension, other custom extension tools still run on the host unless they also delegate their operations.
 
-## Gondolin
+## Decide what Apex Code can access
 
 [Gondolin](https://github.com/earendil-works/gondolin) is a local Linux micro-VM.
 Use the [example extension](../examples/extensions/gondolin) when you want `apex-code` on the host but all built-in tools routed into the VM.
 
-Setup:
+- A read-write host mount lets Apex Code modify those host files.
+- Mounting `~/.apex-code/agent` exposes your Apex Code credentials, settings, extensions, and sessions.
+- Environment variables passed into a container are available to processes inside it.
+- Network access may allow code or tool output to leave the environment.
+- Tool-only isolation does not constrain the host Apex Code process or extension tools that do not use the isolated backend.
 
 ```bash
 cp -R packages/coding-agent/examples/extensions/gondolin ~/.apex-code/agent/extensions/gondolin
@@ -36,16 +40,14 @@ cd ~/.apex-code/agent/extensions/gondolin
 npm install --ignore-scripts
 ```
 
-Run from the project you want mounted:
+## Run Apex Code in plain Docker
 
 ```bash
 cd /path/to/project
 apex-code -e ~/.apex-code/agent/extensions/gondolin
 ```
 
-The extension mounts the host cwd at `/workspace` in the VM and overrides `read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls`.
-User `!` commands are routed into the VM, as well.
-File changes under `/workspace` write through to the host.
+### Build the image
 
 Requirements: Node.js >= 23.6.0 for `@earendil-works/gondolin`, plus QEMU (requires installation through your package manager).
 
@@ -67,11 +69,16 @@ WORKDIR /workspace
 ENTRYPOINT ["apex-code"]
 ```
 
-Build and run:
+Build it from the directory containing the file:
 
 ```bash
 docker build -t apex-code-sandbox -f Dockerfile.apex-code .
 
+### Start Apex Code
+
+From the working folder you want Apex Code to access, run:
+
+```bash
 docker run --rm -it \
   -e ANTHROPIC_API_KEY \
   -v "$PWD:/workspace" \
@@ -79,21 +86,16 @@ docker run --rm -it \
   apex-code-sandbox
 ```
 
-The `-v "$PWD:/workspace"` mounts your current directory into the container at /workspace such that reads and writes in `/workspace` inside Docker directly affect your host files, like in the Gondolin example.
+Replace `ANTHROPIC_API_KEY` with the credential required by your provider. The named `apex-code-agent-home` volume keeps container-local settings, credentials, and sessions between runs.
 
 Use a named volume for `/root/.apex-code/agent` if you want container-local settings and sessions. Mounting your host `~/.apex-code/agent` exposes host auth and session files to the container.
 
-## OpenShell
+### Verify the workspace
 
-Use [NVIDIA OpenShell](https://docs.nvidia.com/openshell/about/overview) when you want a policy-controlled sandbox with filesystem, process, network, credential, and inference controls.
-OpenShell can run sandboxes through a local gateway backed by Docker, Podman, or a VM runtime, or through a remote Kubernetes gateway.
+Inside Apex Code, run:
 
-Every sandbox requires an active gateway.
-Register and select one before creating a sandbox:
-
-```bash
-openshell gateway add <gateway-url> --name <name>
-openshell gateway select <name>
+```text
+!pwd
 ```
 
 Launch `apex-code` inside an OpenShell sandbox:
@@ -105,8 +107,7 @@ openshell sandbox create --name apex-code-sandbox --from apex-code -- apex-code
 In this pattern, the whole `apex-code` process runs inside the sandbox.
 Built-in tools, `!` commands, and extension tools execute inside the OpenShell boundary.
 
-If the gateway is remote, project files are not bind-mounted from the host, meaning writes in the sandbox are not reflected on your machine.
-Clone the repository inside the sandbox or use OpenShell file transfer commands:
+Configure credentials before creating the sandbox. Do not run `/login` inside the sandbox because that writes a real credential into it.
 
 ```bash
 openshell sandbox upload apex-code-sandbox ./repo /workspace

package/docs/custom-provider.md

@@ -397,34 +397,40 @@ interface OAuthCredentials {
 For providers with non-standard APIs, implement `streamSimple`. Study the existing API implementations before writing your own:
 
 **Reference implementations:**
-- [anthropic-messages.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/api/anthropic-messages.ts) - Anthropic Messages API
-- [mistral-conversations.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/api/mistral-conversations.ts) - Mistral Conversations API
-- [openai-completions.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/api/openai-completions.ts) - OpenAI Chat Completions
-- [openai-responses.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/api/openai-responses.ts) - OpenAI Responses API
-- [google-generative-ai.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/api/google-generative-ai.ts) - Google Generative AI
-- [bedrock-converse-stream.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/api/bedrock-converse-stream.ts) - AWS Bedrock
+- [anthropic-messages.ts](https://github.com/earendil-works/pi/blob/main/packages/ai/src/api/anthropic-messages.ts) - Anthropic Messages API
+- [mistral-conversations.ts](https://github.com/earendil-works/pi/blob/main/packages/ai/src/api/mistral-conversations.ts) - Mistral Conversations API
+- [openai-completions.ts](https://github.com/earendil-works/pi/blob/main/packages/ai/src/api/openai-completions.ts) - OpenAI Chat Completions
+- [openai-responses.ts](https://github.com/earendil-works/pi/blob/main/packages/ai/src/api/openai-responses.ts) - OpenAI Responses API
+- [google-generative-ai.ts](https://github.com/earendil-works/pi/blob/main/packages/ai/src/api/google-generative-ai.ts) - Google Generative AI
+- [bedrock-converse-stream.ts](https://github.com/earendil-works/pi/blob/main/packages/ai/src/api/bedrock-converse-stream.ts) - AWS Bedrock
 
 ### Stream Pattern
 
-All providers follow the same pattern:
+All providers follow the same pattern. The context is a normalized transcript: the system prompt and tool declarations live in its system messages, so read them with `getCurrentSystemPrompt(context.messages)` and `getCurrentTools(context.messages)` rather than expecting `context.systemPrompt` or `context.tools`. Models that accept system messages mid-conversation can send them in place; otherwise call `collapseSystemMessages(context)` first to fold later system messages into the leading one.
 
 ```typescript
 import {
   type AssistantMessage,
   type AssistantMessageEventStream,
-  type Context,
   type Model,
   type SimpleStreamOptions,
+  type TranscriptContext,
   calculateCost,
+  collapseSystemMessages,
   createAssistantMessageEventStream,
+  getCurrentSystemPrompt,
+  getCurrentTools,
 } from "@earendil-works/pi-ai";
 
 function streamMyProvider(
   model: Model<any>,
-  context: Context,
+  context: TranscriptContext,
   options?: SimpleStreamOptions
 ): AssistantMessageEventStream {
   const stream = createAssistantMessageEventStream();
+  const transcript = collapseSystemMessages(context);
+  const systemPrompt = getCurrentSystemPrompt(transcript.messages);
+  const tools = getCurrentTools(transcript.messages);
 
   (async () => {
     // Initialize output message
@@ -634,7 +640,7 @@ pi.registerProvider("my-provider", {
 
 ## Testing Your Implementation
 
-Test your provider against the same test suites used by built-in providers. Copy and adapt these test files from [packages/ai/test/](https://github.com/earendil-works/pi-mono/tree/main/packages/ai/test):
+Test your provider against the same test suites used by built-in providers. Copy and adapt these test files from [packages/ai/test/](https://github.com/earendil-works/pi/tree/main/packages/ai/test):
 
 | Test | Purpose |
 |------|---------|
@@ -668,10 +674,10 @@ interface ProviderConfig {
   /** API type for streaming. Required at provider or model level when defining models. */
   api?: Api;
 
-  /** Custom streaming implementation for non-standard APIs. */
+  /** Custom streaming implementation for non-standard APIs. Receives a normalized transcript. */
   streamSimple?: (
     model: Model<Api>,
-    context: Context,
+    context: TranscriptContext,
     options?: SimpleStreamOptions
   ) => AssistantMessageEventStream;
 
@@ -727,6 +733,9 @@ interface ProviderModelConfig {
     cacheWrite: number;
   };
 
+  /** Best-effort prompt cache lifetime in seconds per retention tier. Unset disables cache warming. */
+  promptCache?: { short?: number; long?: number };
+
   /** Maximum context window size in tokens. */
   contextWindow: number;
 

package/docs/development.md

@@ -19,6 +19,19 @@ Run tests from source:
 
 The script can be run from any directory. Apex Code keeps the caller's current working directory.
 
+### Experimental remote harness
+
+The remote harness server/client integration is development-only. Run it from the repository with:
+
+```bash
+PI_EXPERIMENTAL=1 ./pi-test.sh server
+PI_EXPERIMENTAL=1 ./pi-test.sh client
+```
+
+`PI_SERVER_DIR` overrides the server profile and socket directory (default: `~/.pi/server`). `PI_SERVER_ID` selects the logical server ID when `--server-id` is omitted.
+
+The `client` and `experimental/plugin` package subpaths resolve only under the `source` condition in a checkout. Their implementations and the server/client commands are excluded from npm packages and standalone binaries. `pi-client`, `pi-protocol`, and `pi-server` are development dependencies of coding-agent, not runtime dependencies. The local SDK and stdio RPC API are unchanged.
+
 ## Forking / Rebranding
 
 Apex Code itself is a fork of Pi configured this way. Configure via `package.json`:
@@ -60,6 +73,12 @@ npm test                          # Run all tests
 npm test -- test/specific.test.ts # Run specific test
 ```
 
+### Published package smoke test
+
+After building, run `npm run check:package-install`. It packs the public packages and installs only coding-agent as a direct dependency in a temporary directory outside the repository. Local tarball overrides select declared transitive dependencies without installing development-only packages. The check verifies SDK imports and CLI startup without credentials or model requests.
+
+`npm run check` also checks runtime dependency declarations and rejects excluded development sources pulled into a package's build through imports.
+
 ## Project Structure
 
 ```

package/docs/docs.json

@@ -1,7 +1,7 @@
 {
   "navigation": [
     {
-      "title": "Start here",
+      "title": "Get Started",
       "items": [
         {
           "title": "Overview",
@@ -12,138 +12,178 @@
           "path": "quickstart.md"
         },
         {
-          "title": "Using Pi",
-          "path": "usage.md"
-        },
-        {
-          "title": "Providers",
-          "path": "providers.md"
-        },
-        {
-          "title": "Security",
-          "path": "security.md"
-        },
-        {
-          "title": "Containerization",
-          "path": "containerization.md"
-        },
-        {
-          "title": "Settings",
-          "path": "settings.md"
-        },
-        {
-          "title": "Keybindings",
-          "path": "keybindings.md"
-        },
-        {
-          "title": "Sessions",
-          "path": "sessions.md"
-        },
+          "title": "How Pi Works",
+          "path": "how-pi-works.md"
+        }
+      ]
+    },
+    {
+      "title": "Guides",
+      "items": [
         {
-          "title": "Compaction",
-          "path": "compaction.md"
+          "title": "Run Pi",
+          "items": [
+            {
+              "title": "Use Pi in the Terminal",
+              "path": "usage.md"
+            },
+            {
+              "title": "Choose a Model",
+              "path": "models.md"
+            },
+            {
+              "title": "Manage Sessions and Context",
+              "path": "sessions.md"
+            },
+            {
+              "title": "Run Pi Safely",
+              "path": "security.md"
+            },
+            {
+              "title": "Isolate Pi",
+              "path": "containerization.md"
+            },
+            {
+              "title": "Run Local Models",
+              "path": "llama-cpp.md"
+            },
+            {
+              "title": "Configure Your Terminal",
+              "path": "terminal-setup.md"
+            },
+            {
+              "title": "Configure Shell Commands",
+              "path": "shell-aliases.md"
+            },
+            {
+              "title": "Run Pi in tmux",
+              "path": "tmux.md"
+            },
+            {
+              "title": "Run Pi on Windows",
+              "path": "windows.md"
+            },
+            {
+              "title": "Run Pi on Android",
+              "path": "termux.md"
+            }
+          ]
+        },
+        {
+          "title": "Customize Pi",
+          "items": [
+            {
+              "title": "Configure Pi",
+              "path": "configuration.md"
+            },
+            {
+              "title": "Create Prompt Templates",
+              "path": "prompt-templates.md"
+            },
+            {
+              "title": "Add Skills",
+              "path": "skills.md"
+            },
+            {
+              "title": "Create Themes",
+              "path": "themes.md"
+            },
+            {
+              "title": "Use Pi Packages",
+              "path": "packages.md"
+            }
+          ]
+        },
+        {
+          "title": "Build on Pi",
+          "items": [
+            {
+              "title": "Build Extensions",
+              "path": "extensions.md"
+            },
+            {
+              "title": "Add Custom Providers",
+              "path": "custom-provider.md"
+            },
+            {
+              "title": "Build Terminal UI Components",
+              "path": "tui.md"
+            },
+            {
+              "title": "Integrate with the CLI",
+              "path": "cli-integration.md"
+            },
+            {
+              "title": "Use the SDK",
+              "path": "sdk.md"
+            }
+          ]
         }
       ]
     },
     {
-      "title": "Customization",
+      "title": "Reference",
       "items": [
         {
-          "title": "Extensions",
-          "path": "extensions.md"
+          "title": "CLI",
+          "path": "cli.md"
         },
         {
-          "title": "Skills",
-          "path": "skills.md"
+          "title": "Slash Commands",
+          "path": "slash-commands.md"
         },
         {
-          "title": "Prompt Templates",
-          "path": "prompt-templates.md"
+          "title": "Settings",
+          "path": "settings.md"
         },
         {
-          "title": "Themes",
-          "path": "themes.md"
+          "title": "Environment Variables",
+          "path": "environment-variables.md"
         },
         {
-          "title": "Pi Packages",
-          "path": "packages.md"
+          "title": "Keybindings",
+          "path": "keybindings.md"
         },
         {
-          "title": "Custom Models",
-          "path": "models.md"
+          "title": "Provider Authentication",
+          "path": "providers.md"
         },
         {
-          "title": "Custom Providers",
-          "path": "custom-provider.md"
-        }
-      ]
-    },
-    {
-      "title": "Reference",
-      "items": [
-        {
-          "title": "Session Format",
+          "title": "Session File Format",
           "path": "session-format.md"
-        }
-      ]
-    },
-    {
-      "title": "Programmatic Usage",
-      "items": [
-        {
-          "title": "SDK",
-          "path": "sdk.md"
         },
         {
-          "title": "RPC Mode",
-          "path": "rpc.md"
+          "title": "Compaction and Branch Summaries",
+          "path": "compaction.md"
         },
         {
-          "title": "JSON Event Stream Mode",
+          "title": "JSON Event Stream",
           "path": "json.md"
         },
         {
-          "title": "TUI Components",
-          "path": "tui.md"
-        }
-      ]
-    },
-    {
-      "title": "Platform Setup",
-      "items": [
-        {
-          "title": "Windows",
-          "path": "windows.md"
-        },
-        {
-          "title": "Termux on Android",
-          "path": "termux.md"
+          "title": "RPC Protocol",
+          "path": "rpc.md"
         },
         {
-          "title": "tmux",
-          "path": "tmux.md"
+          "title": "RPC Commands",
+          "path": "rpc-commands.md"
         },
         {
-          "title": "Terminal Setup",
-          "path": "terminal-setup.md"
+          "title": "RPC Extension UI",
+          "path": "rpc-extension-ui.md"
         },
         {
-          "title": "Shell Aliases",
-          "path": "shell-aliases.md"
-        }
-      ]
-    },
-    {
-      "title": "Development",
-      "items": [
-        {
-          "title": "Development",
-          "path": "development.md"
+          "title": "Message Types",
+          "path": "message-types.md"
         }
       ]
     }
   ],
   "redirects": [
+    {
+      "from": "development.md",
+      "to": "index.md"
+    },
     {
       "from": "session.md",
       "to": "session-format.md"
@@ -151,6 +191,10 @@
     {
       "from": "tree.md",
       "to": "sessions.md"
+    },
+    {
+      "from": "process-integration.md",
+      "to": "cli-integration.md"
     }
   ]
 }