apex-code 0.4.0 → 0.5.1

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"
     }
   ]
 }