@bastani/atomic 0.9.19-alpha.6 → 0.9.19-alpha.8

package/docs/custom-provider/oauth.md

@@ -0,0 +1,131 @@
+---
+title: Provider OAuth
+description: OAuth login callbacks, credential storage, and dynamic catalog refresh.
+---
+
+# Provider OAuth
+
+## OAuth Support
+
+Add OAuth/SSO authentication that integrates with `/login`:
+
+```typescript
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@bastani/pi-ai";
+
+pi.registerProvider("corporate-ai", {
+  baseUrl: "https://ai.corp.com/v1",
+  api: "openai-responses",
+  models: [...],
+  oauth: {
+    name: "Corporate AI (SSO)",
+
+    async login(callbacks: OAuthLoginCallbacks, signal: AbortSignal): Promise<OAuthCredentials> {
+      // Option 1: Browser-based OAuth
+      callbacks.onAuth({ url: "https://sso.corp.com/authorize?..." });
+
+      // Option 2: Device code flow
+      callbacks.onDeviceCode({
+        userCode: "ABCD-1234",
+        verificationUri: "https://sso.corp.com/device"
+      });
+
+      // Option 3: Prompt for token/code
+      const code = await callbacks.onPrompt({ message: "Enter SSO code:" });
+
+      // Exchange for tokens (your implementation). Forward `signal` so
+      // cancelling /login aborts the in-flight network request.
+      const tokens = await exchangeCodeForTokens(code, { signal });
+
+      return {
+        refresh: tokens.refreshToken,
+        access: tokens.accessToken,
+        expires: Date.now() + tokens.expiresIn * 1000
+      };
+    },
+
+    async refreshToken(
+      credentials: OAuthCredentials,
+      signal: AbortSignal | undefined
+    ): Promise<OAuthCredentials> {
+      const tokens = await refreshAccessToken(credentials.refresh, { signal });
+      return {
+        refresh: tokens.refreshToken ?? credentials.refresh,
+        access: tokens.accessToken,
+        expires: Date.now() + tokens.expiresIn * 1000
+      };
+    },
+
+    getApiKey(credentials: OAuthCredentials): string {
+      return credentials.access;
+    },
+
+    // Optional: modify models based on user's subscription
+    modifyModels(models, credentials) {
+      const region = decodeRegionFromToken(credentials.access);
+      return models.map(m => ({
+        ...m,
+        baseUrl: `https://${region}.ai.corp.com/v1`
+      }));
+    }
+  }
+});
+```
+
+After registration, users can authenticate via `/login corporate-ai`.
+
+Existing extension OAuth definitions keep their `login`, `refreshToken`, `getApiKey`, and optional `modifyModels` methods. OAuth refresh is serialized so concurrent requests do not overwrite each other's credentials.
+
+In isolated interactive mode, extension code and executable OAuth methods remain in the engine process. Atomic transports only the JSON-safe provider description (`id`, `name`, `loginLabel`, and `usesCallbackServer`) to the terminal process; it never serializes provider functions or acquired credentials and does not load the extension a second time in the frontend. `loginLabel` replaces the login dialog title, while `usesCallbackServer: true` exposes a redirect-URL paste field that races the browser callback. The engine executes the provider's login closure and correlates browser URLs, device codes, progress/info messages, prompts, selections, and manual-code callbacks with the originating login.
+
+After acquisition, the engine owns serialized credential persistence and logout. It publishes the authenticated provider against its already-loaded snapshot as soon as persistence succeeds; dynamic catalog and ambient-availability refreshes run separately under the model selector's deadline and never extend the login transaction. Logout similarly publishes stored-credential removal without invoking `refreshModels`; Atomic gives the provider's local remaining-auth probe a short deadline so extension code cannot keep the dialog open. The frontend applies the returned snapshot only after the engine transaction succeeds. Escape or Ctrl+C cancels only the matching login and leaves the prior credential/catalog intact. Built-in OAuth and direct, non-isolated extension OAuth use the same persistence and cancellation semantics; later provider registrations continue to override earlier registrations by ID.
+
+Intentional cancellation is quiet, including native `AbortError`, an aborted signal or its exact reason, nested abort causes, and the legacy exact `Login cancelled` error. Provider denial, timeout, network/protocol errors, malformed responses, token exchange failures, and storage failures remain visible. Catalog-refresh failures are reported by `/model` while cached models remain selectable; they do not turn a persisted login into a failed transaction.
+
+## Dynamic model catalog refresh
+
+Providers whose catalogs change at runtime can add `refreshModels`. Atomic calls it during the model picker's bounded asynchronous refresh, independently of authentication completion:
+
+```typescript
+pi.registerProvider("corporate-ai", {
+  baseUrl: "https://ai.corp.com/v1",
+  api: "openai-responses",
+  apiKey: "$CORPORATE_AI_KEY",
+  models: cachedModels,
+  async refreshModels({ signal, force, credential, store }) {
+    const models = await fetchCorporateModels({ signal, force, credential });
+    await store.write({ models, checkedAt: Date.now() });
+    return models;
+  }
+});
+```
+
+The current catalog stays readable while refresh is pending. Successful provider results are applied independently; a provider that fails, times out, or observes an aborted `signal` retains its previous list. Use the provider-scoped `store` only when the catalog should persist across sessions.
+
+### OAuthLoginCallbacks
+
+The `callbacks` object provides three ways to authenticate:
+
+```typescript
+interface OAuthLoginCallbacks {
+  // Open URL in browser (for OAuth redirects)
+  onAuth(params: { url: string }): void;
+
+  // Show device code (for device authorization flow)
+  onDeviceCode(params: { userCode: string; verificationUri: string }): void;
+
+  // Prompt user for input (for manual token entry)
+  onPrompt(params: { message: string }): Promise<string>;
+}
+```
+
+### OAuthCredentials
+
+Credentials are persisted in `~/.atomic/agent/auth.json` (legacy `~/.pi/agent/auth.json` may be read for compatibility):
+
+```typescript
+interface OAuthCredentials {
+  refresh: string;   // Refresh token (for refreshToken())
+  access: string;    // Access token (returned by getApiKey())
+  expires: number;   // Expiration timestamp in milliseconds
+}
+```

package/docs/custom-provider/override.md

@@ -0,0 +1,34 @@
+---
+title: Override an existing provider
+description: Change the behavior of a provider Atomic already ships.
+---
+
+# Override an existing provider
+
+## Override Existing Provider
+
+The simplest use case: redirect an existing provider through a proxy.
+
+```typescript
+// All Anthropic requests now go through your proxy
+pi.registerProvider("anthropic", {
+  baseUrl: "https://proxy.example.com"
+});
+
+// Add custom headers to OpenAI requests
+pi.registerProvider("openai", {
+  headers: {
+    "X-Custom-Header": "value"
+  }
+});
+
+// Both baseUrl and headers
+pi.registerProvider("google", {
+  baseUrl: "https://ai-gateway.corp.com/google",
+  headers: {
+    "X-Corp-Auth": "$CORP_AUTH_TOKEN"  // resolves from env; omit $ for a literal
+  }
+});
+```
+
+When only `baseUrl` and/or `headers` are provided (no `models`), all existing models for that provider are preserved with the new endpoint.

package/docs/custom-provider/registration.md

@@ -0,0 +1,163 @@
+---
+title: Register a provider
+description: Register and unregister a provider, and the API types a provider implements.
+---
+
+# Register a provider
+
+## Register New Provider
+
+To add a completely new provider, specify `models` along with the required configuration.
+
+If the model list comes from a remote endpoint, use an async extension factory:
+
+```typescript
+import type { ExtensionAPI } from "@bastani/atomic";
+
+export default async function (pi: ExtensionAPI) {
+  const response = await fetch("http://localhost:1234/v1/models");
+  const payload = (await response.json()) as {
+    data: Array<{
+      id: string;
+      name?: string;
+      context_window?: number;
+      max_tokens?: number;
+    }>;
+  };
+
+  pi.registerProvider("local-openai", {
+    baseUrl: "http://localhost:1234/v1",
+    apiKey: "$LOCAL_OPENAI_API_KEY",
+    api: "openai-completions",
+    models: payload.data.map((model) => ({
+      id: model.id,
+      name: model.name ?? model.id,
+      reasoning: false,
+      input: ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: model.context_window ?? 128000,
+      maxTokens: model.max_tokens ?? 4096,
+    })),
+  });
+}
+```
+
+This registers the fetched models before startup finishes.
+
+```typescript
+pi.registerProvider("my-llm", {
+  baseUrl: "https://api.my-llm.com/v1",
+  apiKey: "$MY_LLM_API_KEY",  // env var reference; omit $ for a literal value
+  api: "openai-completions",  // which streaming API to use
+  models: [
+    {
+      id: "my-llm-large",
+      name: "My LLM Large",
+      reasoning: true,        // supports extended thinking
+      input: ["text", "image"],
+      cost: {
+        input: 3.0,           // $/million tokens
+        output: 15.0,
+        cacheRead: 0.3,
+        cacheWrite: 3.75
+      },
+      contextWindow: 200000,
+      maxTokens: 16384
+    }
+  ]
+});
+```
+
+When `models` is provided, it **replaces** all existing models for that provider.
+
+## Unregister Provider
+
+Use `pi.unregisterProvider(name)` to remove a provider that was previously registered via `pi.registerProvider(name, ...)`:
+
+```typescript
+// Register
+pi.registerProvider("my-llm", {
+  baseUrl: "https://api.my-llm.com/v1",
+  apiKey: "$MY_LLM_API_KEY",
+  api: "openai-completions",
+  models: [
+    {
+      id: "my-llm-large",
+      name: "My LLM Large",
+      reasoning: true,
+      input: ["text", "image"],
+      cost: { input: 3.0, output: 15.0, cacheRead: 0.3, cacheWrite: 3.75 },
+      contextWindow: 200000,
+      maxTokens: 16384
+    }
+  ]
+});
+
+// Later, remove it
+pi.unregisterProvider("my-llm");
+```
+
+Unregistering removes that provider's dynamic models, API key fallback, OAuth provider registration, and custom stream handler registrations. Any built-in models or provider behavior that were overridden are restored.
+
+Calls made after the initial extension load phase are applied immediately, so no `/reload` is required.
+
+### API Types
+
+The `api` field determines which streaming implementation is used:
+
+| API | Use for |
+|-----|---------|
+| `anthropic-messages` | Anthropic Claude API and compatibles |
+| `openai-completions` | OpenAI Chat Completions API and compatibles |
+| `openai-responses` | OpenAI Responses API |
+| `azure-openai-responses` | Azure OpenAI Responses API |
+| `openai-codex-responses` | OpenAI Codex Responses API |
+| `mistral-conversations` | Native Mistral Chat Completions streaming |
+| `google-generative-ai` | Google Generative AI API |
+| `google-vertex` | Google Vertex AI API |
+| `bedrock-converse-stream` | Amazon Bedrock Converse API |
+
+Most OpenAI-compatible providers work with `openai-completions`. Use model-level `thinkingLevelMap` for model-specific thinking levels, and `compat` for provider quirks:
+
+```typescript
+models: [{
+  id: "custom-model",
+  // ...
+  reasoning: true,
+  thinkingLevelMap: {              // map Atomic thinking levels to provider values; null hides unsupported levels
+    minimal: null,
+    low: null,
+    medium: null,
+    high: "default",
+    xhigh: null,
+    max: "max"
+  },
+  compat: {
+    supportsDeveloperRole: false,   // use "system" instead of "developer"
+    supportsReasoningEffort: true,
+    maxTokensField: "max_tokens",   // instead of "max_completion_tokens"
+    requiresToolResultName: true,   // tool results need name field
+    thinkingFormat: "qwen",        // top-level enable_thinking: true
+    cacheControlFormat: "anthropic" // Anthropic-style cache_control markers
+  }
+}]
+```
+
+Use `openrouter` for OpenRouter-style `reasoning: { effort }` controls. Use `together` for Together-style `reasoning: { enabled }` controls; with `supportsReasoningEffort`, it also sends `reasoning_effort`. Use `qwen-chat-template` for local Qwen-compatible servers that read `chat_template_kwargs.enable_thinking` and need `preserve_thinking`.
+Use `cacheControlFormat: "anthropic"` for OpenAI-compatible providers that expose Anthropic-style prompt caching via `cache_control` on the system prompt, last tool definition, and last user/assistant text content.
+
+Use `mistral-conversations` for native Mistral models. If you intentionally route a Mistral-compatible or custom endpoint through `openai-completions`, set the required `compat` flags explicitly.
+
+### Auth Header
+
+If your provider expects `Authorization: Bearer <key>` but doesn't use a standard API, set `authHeader: true`:
+
+```typescript
+pi.registerProvider("custom-api", {
+  baseUrl: "https://api.example.com",
+  apiKey: "$MY_API_KEY",
+  authHeader: true,  // adds Authorization: Bearer header
+  api: "openai-completions",
+  models: [...]
+});
+```

package/docs/custom-provider/streaming.md

@@ -0,0 +1,214 @@
+---
+title: Provider streaming API
+description: "Implement a custom streaming API: events, content blocks, tool calls, stop reasons, and usage."
+---
+
+# Provider streaming API
+
+## Custom Streaming API
+
+For providers with non-standard APIs, implement `streamSimple`. Study the existing API implementations before writing your own:
+
+**Reference implementations:**
+
+Atomic uses provider implementations from its installed `@bastani/pi-ai` dependency. The streaming implementations behind the `api` field live under `node_modules/@bastani/pi-ai/dist/api/`, including:
+- `anthropic-messages.d.ts` / `anthropic-messages.js` - Anthropic Messages API
+- `mistral-conversations.d.ts` / `mistral-conversations.js` - Mistral Conversations/Chat streaming
+- `openai-completions.d.ts` / `openai-completions.js` - OpenAI Chat Completions
+- `openai-responses.d.ts` / `openai-responses.js` - OpenAI Responses API
+- `google-generative-ai.d.ts` / `google-generative-ai.js` - Google Generative AI
+- `bedrock-converse-stream.d.ts` / `bedrock-converse-stream.js` - Amazon Bedrock Converse API
+Per-vendor provider configurations (base URLs, auth, model catalogs) live under `dist/providers/`, for example `anthropic.d.ts` / `anthropic.js` and `mistral.d.ts` / `mistral.js`.
+
+### Stream Pattern
+
+All providers follow the same pattern:
+
+```typescript
+import {
+  type AssistantMessage,
+  type AssistantMessageEventStream,
+  type Context,
+  type Model,
+  type SimpleStreamOptions,
+  calculateCost,
+  createAssistantMessageEventStream,
+} from "@bastani/pi-ai";
+
+function streamMyProvider(
+  model: Model<any>,
+  context: Context,
+  options?: SimpleStreamOptions
+): AssistantMessageEventStream {
+  const stream = createAssistantMessageEventStream();
+
+  (async () => {
+    // Initialize output message
+    const output: AssistantMessage = {
+      role: "assistant",
+      content: [],
+      api: model.api,
+      provider: model.provider,
+      model: model.id,
+      usage: {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+      },
+      stopReason: "pending",
+      timestamp: Date.now(),
+    };
+
+    try {
+      // Push start event
+      stream.push({ type: "start", partial: output });
+
+      // Make API request and process response...
+      // Push content events as they arrive, and set output.stopReason from the
+      // terminal event. A reason your provider sends that you do not map must
+      // become an error, not a silent "stop".
+      if (output.stopReason === "pending") {
+        throw new Error("Provider stream ended without a stop reason");
+      }
+      if (output.stopReason === "error" || output.stopReason === "aborted") {
+        throw new Error(output.errorMessage || "An unknown error occurred");
+      }
+
+      // Push done event
+      stream.push({
+        type: "done",
+        reason: output.stopReason,
+        message: output
+      });
+      stream.end();
+    } catch (error) {
+      output.stopReason = options?.signal?.aborted ? "aborted" : "error";
+      output.errorMessage = error instanceof Error ? error.message : String(error);
+      stream.push({ type: "error", reason: output.stopReason, error: output });
+      stream.end();
+    }
+  })();
+
+  return stream;
+}
+```
+
+### Event Types
+
+Push events via `stream.push()` in this order:
+
+1. `{ type: "start", partial: output }` - Stream started
+
+2. Content events (repeatable, track `contentIndex` for each block):
+   - `{ type: "text_start", contentIndex, partial }` - Text block started
+   - `{ type: "text_delta", contentIndex, delta, partial }` - Text chunk
+   - `{ type: "text_end", contentIndex, content, partial }` - Text block ended
+   - `{ type: "thinking_start", contentIndex, partial }` - Thinking started
+   - `{ type: "thinking_delta", contentIndex, delta, partial }` - Thinking chunk
+   - `{ type: "thinking_end", contentIndex, content, partial }` - Thinking ended
+   - `{ type: "toolcall_start", contentIndex, partial }` - Tool call started
+   - `{ type: "toolcall_delta", contentIndex, delta, partial }` - Tool call JSON chunk
+   - `{ type: "toolcall_end", contentIndex, toolCall, partial }` - Tool call ended
+
+3. `{ type: "done", reason, message }` or `{ type: "error", reason, error }` - Stream ended
+
+The `partial` field in each event contains the current `AssistantMessage` state. Update `output.content` as you receive data, then include `output` as the `partial`.
+
+### Stop Reasons
+
+`StopReason` is `"pending" | "stop" | "length" | "toolUse" | "error" | "aborted"`.
+
+Start the partial message at `"pending"`. It is the reason every in-flight message carries, and it says the terminal event has not arrived yet — it is not a default standing in for `"stop"`. Set the real reason when the provider says the turn ended, then push `done` with it.
+
+Two checks belong immediately before `done`:
+
+- a stream that reached the end while still `"pending"` never received a terminal event, so raise rather than report a stop that did not happen;
+- `"error"` and `"aborted"` are failures, so raise them with `output.errorMessage` and let the `catch` push an `error` event.
+
+`done` accepts only `"stop"`, `"length"`, and `"toolUse"`, which is exactly what those two checks leave, so the `as "stop" | "length" | "toolUse"` cast older implementations used is no longer needed.
+
+Map each raw reason your provider can send onto one of the five terminal values, and **raise on one you do not recognise** rather than falling back to `"stop"`. This is what the built-in providers do: an unmapped reason becomes a provider error naming the raw value, so a new truncation or safety signal is visible instead of arriving as a turn that looks like it finished normally. The optional `rawStopReason` field on `AssistantMessage` is where the provider's own string belongs when you want to keep it.
+
+### Content Blocks
+
+Add content blocks to `output.content` as they arrive:
+
+```typescript
+// Text block
+output.content.push({ type: "text", text: "" });
+stream.push({ type: "text_start", contentIndex: output.content.length - 1, partial: output });
+
+// As text arrives
+const block = output.content[contentIndex];
+if (block.type === "text") {
+  block.text += delta;
+  stream.push({ type: "text_delta", contentIndex, delta, partial: output });
+}
+
+// When block completes
+stream.push({ type: "text_end", contentIndex, content: block.text, partial: output });
+```
+
+### Tool Calls
+
+Tool calls require accumulating JSON and parsing:
+
+```typescript
+// Start tool call
+output.content.push({
+  type: "toolCall",
+  id: toolCallId,
+  name: toolName,
+  arguments: {}
+});
+stream.push({ type: "toolcall_start", contentIndex: output.content.length - 1, partial: output });
+
+// Accumulate JSON
+let partialJson = "";
+partialJson += jsonDelta;
+try {
+  block.arguments = JSON.parse(partialJson);
+} catch {}
+stream.push({ type: "toolcall_delta", contentIndex, delta: jsonDelta, partial: output });
+
+// Complete
+stream.push({
+  type: "toolcall_end",
+  contentIndex,
+  toolCall: { type: "toolCall", id, name, arguments: block.arguments },
+  partial: output
+});
+```
+
+### Usage and Cost
+
+Update usage from API response and calculate cost:
+
+```typescript
+output.usage.input = response.usage.input_tokens;
+output.usage.output = response.usage.output_tokens;
+output.usage.cacheRead = response.usage.cache_read_tokens ?? 0;
+output.usage.cacheWrite = response.usage.cache_write_tokens ?? 0;
+output.usage.totalTokens = output.usage.input + output.usage.output +
+                           output.usage.cacheRead + output.usage.cacheWrite;
+calculateCost(model, output.usage);
+```
+
+`calculateCost()` selects one rate set for the whole request. Aggregate input is `usage.input + usage.cacheRead + usage.cacheWrite`; a tier applies only when that sum is strictly greater than `inputTokensAbove`, and the matching tier with the highest threshold wins. Every tier must provide complete `input`, `output`, `cacheRead`, and `cacheWrite` rates. Extension-registered models preserve these tiers, and matching `models.json` `modelOverrides` use the same replacement rules described in [Custom Models](/models/reference#request-wide-cost-tiers).
+
+### Registration
+
+Register your stream function:
+
+```typescript
+pi.registerProvider("my-provider", {
+  baseUrl: "https://api.example.com",
+  apiKey: "$MY_API_KEY",
+  api: "my-custom-api",
+  models: [...],
+  streamSimple: streamMyProvider
+});
+```