pi-workbuddy 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-workbuddy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# pi-workbuddy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A **WorkBuddy AI** provider for [Pi](https://pi.dev), with browser-based account login and direct model access—**no separate bridge required**.
+
+> **Experimental and unofficial.** Built from static inspection of WorkBuddy AI 5.8.4. A user has successfully completed browser login and a basic live conversation with `deepseek-v4.1-flash`. Tool calling, image input, and long-running token refresh have not yet been verified against the live service. Automated tests use synthetic credentials and responses, including Pi's built-in streaming implementation.
+
+## Getting started
+
+Requires Node.js ≥22.19 and Pi with native provider support. Tested with Pi CLI **1.3.0**.
+
+Install the npm package after the `pi-workbuddy` release is published:
+
+```sh
+pi install npm:pi-workbuddy
+```
+
+Until the npm release is available, or to install directly from GitHub:
+
+```sh
+pi install git:github.com/lutfi238/pi-workbuddy
+```
+
+Then start `pi`. For local development, run `pi -e ./extensions/workbuddy.js` from the repository instead. Use only one installation source to avoid loading the provider twice.
+
+Inside Pi:
+
+1. Run `/login` and select **WorkBuddy AI**.
+2. Complete the login yourself in the browser using the URL displayed by Pi.
+3. Run `/model`; Pi refreshes model catalogs in the background. Wait for the refresh to finish, then select a model from the `workbuddy` provider.
+4. If you need to force discovery or diagnose a failure, run `/workbuddy refresh`.
+5. Send a prompt. Chat requests consume your WorkBuddy account quota.
+
+Press Escape to cancel login. Polling is limited to five minutes. You do not need to share a password or token with the agent, extract desktop credentials, install a bridge, or open a local callback port.
+
+For an optional persistent installation from a local checkout:
+
+```sh
+pi install .
+```
+
+Use `/reload` after updating a loaded extension. To sign out, run `/logout` and select WorkBuddy. This removes Pi's local credentials; it does not revoke every server-side account session or sign out the desktop application.
+
+### Commands
+
+| Command | Behavior |
+|---|---|
+| `/login` → WorkBuddy AI | Browser login with credentials stored by Pi |
+| `/logout` → WorkBuddy AI | Remove Pi's local WorkBuddy credentials |
+| `/workbuddy status` or `/workbuddy doctor` | Show local configuration, catalog source, active model, and the last sanitized catalog error; no network requests |
+| `/workbuddy refresh` | Fetch the authenticated catalog, refreshing the token if needed |
+| `/model` | Refresh model catalogs in the background and select a model |
+
+Before discovery, the provider includes conservative fallback metadata for `default-model`. Models are not listed as available until authentication is configured. If discovery fails, the last known catalog is retained **in memory**; it is not persisted across restarts. Pi may invoke discovery during its refresh lifecycle, but the extension factory does not make network requests when loaded.
+
+### Automatic model discovery
+
+There is no hardcoded allowlist of WorkBuddy model IDs. The provider fetches `/v3/config` with the signed-in account and projects compatible model entries into Pi. In Pi 1.3.0, opening `/model` refreshes provider catalogs in the background and updates the picker when discovery finishes. Pi also refreshes catalogs after login; `/workbuddy refresh` is the explicit manual override.
+
+A newly advertised model can therefore appear without changing the extension or adding its ID manually. The model must pass the existing compatibility and security filters: disabled models, models explicitly lacking tool support, and custom endpoints/protocols/API keys are excluded. Catalog visibility does not guarantee that your account can run every listed model.
+
+This is refresh-based discovery, not a realtime push subscription or continuous idle polling. Reopen `/model` to check for additions during a long session. Offline mode does not fetch new catalogs. Extension updates may still be necessary if WorkBuddy changes its API, authentication, metadata schema, or wire protocol.
+
+### Login succeeds, but discovery fails or Codex remains selected
+
+The message `Logged in ... Credentials saved` means Pi completed the login. The browser may still open the original WorkBuddy application through a server-provided redirect; this does not invalidate Pi's successful login. Signing in does not automatically change the active model.
+
+To diagnose discovery without sending a chat request:
+
+```text
+/reload
+/workbuddy refresh
+/workbuddy doctor
+```
+
+Refresh failures report safe categories such as `[http]` (HTTP status and business code), `[invalid-json]`, `[catalog-shape]`, `[catalog-empty]`, or `[catalog-filtered]` (counts by filter reason). Server messages and response bodies, model URLs, and tokens are not displayed. Do not sign in again or weaken endpoint restrictions before identifying the failure.
+
+**HTTP 400 / 12403:** catalog probes with synthetic account metadata reproduced this error when the server could not parse the client version from the User-Agent. Version 0.2.1 adds the compatibility header `CLI/unknown WorkBuddy/5.8.4 pi-workbuddy/0.2.1` to discovery, token refresh, and chat transport. The WorkBuddy marker identifies the inspected protocol compatibility baseline; the extension still declares its own identity. Destination-origin restrictions remain unchanged, and no desktop credentials are used. Public catalog discovery alone does not prove account-specific model access. See the [12403 investigation](research/12403-findings.md).
+
+To select the provider, run `/model` and search for `workbuddy`; selecting a model does not send a prompt. When troubleshooting with an agent, obtain explicit approval before sending quota-consuming inference requests. Never share `auth.json`, tokens, or login URLs.
+
+## Implementation
+
+- **Login:** a server-issued browser URL followed by polling `/v2/plugin/auth/token`. The UI uses Pi's native authentication mechanism; this is not a claim of an official public WorkBuddy OAuth integration.
+- **Token refresh:** `/v2/plugin/auth/token/refresh`, with credential storage and refresh locking managed by Pi.
+- **Catalog:** `GET https://www.workbuddy.ai/v3/config`.
+- **Chat:** `POST https://www.workbuddy.ai/v2/chat/completions`.
+- **Transport:** gzip requests, SSE framing and UTF-8 normalization, repeated or missing tool-call ID handling, usage tails, and cancellation.
+- **Message conversion and streaming:** delegated to Pi's built-in OpenAI Chat Completions implementation. Payload, response, and provider-event hooks are forwarded.
+- **Metadata:** live catalog metadata is supplemented with reviewed official vendor specifications for 24 named models. Context/output use the largest documented or advertised values, not smaller catalog defaults. Image support and reasoning efforts are additive. Routing aliases and newly discovered IDs remain catalog-driven; the reference table is not an allowlist. Disabled models, models without tool support, and custom model URLs, protocols, or API keys are excluded.
+- **Pricing:** model prices are set to zero because USD token rates are unknown—**this does not mean usage is free**. WorkBuddy's `usage.credit` field is not included in Pi's cost accounting; token usage is still processed.
+
+### Context and output budgets
+
+The default policy is **documented maximum capabilities**, not a conservative gateway-default policy. Context uses the largest positive safe integer among the catalog's input limit, configured context default, supported context lengths, and reviewed vendor context reference. Output similarly uses the larger catalog/vendor maximum, bounded by the shared context budget. Smaller catalog defaults do not reduce these maxima, and a larger live value is never reduced by an older vendor reference.
+
+For example, DeepSeek V4.1 Flash now advertises **1,048,576 context tokens**, **393,216 maximum output tokens**, image input, and **low/high/max** thinking. It no longer stays at the catalog's 300K default. Explicitly named regional/preview variants use their base-model references optimistically; identical gateway deployments are not guaranteed. Four routing aliases retain their own live metadata instead of inheriting an invented vendor identity.
+
+Image support is enabled when either WorkBuddy or the reviewed vendor reference advertises it, even if gateway metadata disables multimodal input. Supported reasoning efforts combine both sources. Known mandatory-thinking models cannot turn thinking off; Kimi K2.6 uses a thinking toggle rather than an unsupported vendor `reasoning_effort` parameter. Pi exposes text/image input, not every vendor-native audio, video, or hosted-tool feature.
+
+Fallbacks of 32,768 context / 4,096 output apply **only when neither source supplies the corresponding usable limit**. `maxAllowedSize` remains excluded because its units are unverified. Output is never added to input to invent a larger context. Rounded vendor notation such as 1M or 256K is normalized decimally where no exact integer is published; exact documented integers are used when available. Kimi completion ceilings share context with input; they are not independent additional output capacity. Grok's unspecified finite output cap and Kimi K2.8's unpublished output maximum retain the catalog value.
+
+Smaller explicit output requests remain supported; sampling and payload hooks cannot exceed the resulting model maximum or bypass Pi's remaining-context adjustment. Normal Pi `streamSimple` requests additionally fit output to estimated remaining context, including Pi 1.3.0's 4,096-token safety margin. This is distinct from the default 16,384-token compaction reserve. Full API `stream` callers still own input/remaining-context budgeting.
+
+**Optimistic does not mean live-verified:** vendor API limits/features may differ from WorkBuddy routing, account access, or gateway protocol support. OpenAI's native GPT-6 tool/endpoint restrictions, for example, do not establish whether WorkBuddy translates its own chat endpoint. Models are not disabled preemptively for this uncertainty. Actual errors should drive targeted compatibility fixes, rather than blanket reductions. There is no automatic downgrade, retry with another model, or quota-consuming capability probe.
+
+See the current [capability policy](research/capability-policy.md), [vendor references](research/vendor-capability-comparison.md), and historical [context-limit audit](research/context-limit-audit.md). No global Pi compaction settings are changed by the extension.
+
+### Native configuration
+
+```powershell
+# Default mode:
+$env:WORKBUDDY_MODE = "native"
+
+# Only when testing plain-JSON transport compatibility:
+$env:WORKBUDDY_GZIP = "0"
+pi -e ./extensions/workbuddy.js
+```
+
+Gzip is enabled by default. Bridge URLs and API keys are not used in native mode. The native origin cannot be changed through environment variables; an official endpoint change requires code review and testing.
+
+The `.env.example` file is a reference only: Pi and this extension do **not** automatically load `.env` files. Set variables in the shell or process that starts Pi.
+
+## Security and limitations
+
+- Pi stores credentials in its agent profile (`auth.json`), not in the project. Protect that file; never commit or share it.
+- The extension does not read the desktop application's credentials, databases, cookies, or sessions.
+- Authentication, discovery, and chat requests target only the HTTPS origin `www.workbuddy.ai`; HTTP redirects are rejected. Recognized production WorkBuddy/CodeBuddy account domains are used only as header values, not destination URLs.
+- Browser login URLs must use recognized production WorkBuddy/CodeBuddy origins. Login URLs can contain sensitive state; do not share them or screenshots containing them.
+- Remote configuration cannot import prompts, tools, commands, credentials, or model URLs into this extension. Discovery does not send a list of repositories.
+- `X-Private-Data: true` is a conservative privacy default, **not a guarantee** of the server's retention policy.
+- Errors are sanitized. The extension does not log tokens or upstream error bodies. Pi's debugging features and other extensions remain within Pi's trust boundary.
+- Catalog entries do not prove that a model is available to your account. Reasoning and image capabilities are not fully verified live; opaque `extra_fields` and model-specific behavior may require additional adapters.
+- This version targets the inspected international production service, not the China edition, custom enterprise SSO, staging deployments, or arbitrary hosts.
+- The service may reject third-party clients, change its protocol, or impose usage terms. This extension does not bypass authentication, account permissions, or quota limits.
+- If login fails, do not paste tokens as a workaround. Record only the sanitized HTTP/business code and investigate compatibility.
+
+## Legacy bridge mode (optional)
+
+The original bridge integration is still available, but it does **not** provide native account login:
+
+```powershell
+$env:WORKBUDDY_MODE = "bridge"
+$env:WORKBUDDY_BASE_URL = "http://127.0.0.1:8787/v1"
+# Set this if the bridge validates a local API key:
+$env:WORKBUDDY_API_KEY = "your-local-bridge-key"
+pi -e ./extensions/workbuddy.js
+```
+
+The bridge uses a separate provider ID, `workbuddy-bridge`, so native account credentials are not reused as a bridge API key. The default placeholder, `workbuddy-local`, is suitable only for bridges that do not validate API keys.
+
+Third-party bridges identified during research:
+
+- [workbuddy-connect-api](https://github.com/modersetech/workbuddy-connect-api), default port 8787.
+- [workbuddy-bridge](https://github.com/hanhan1223/workbuddy-bridge), default port 8799.
+
+Review their security and upstream instructions before use. The extension does not install or launch either bridge automatically.
+
+Additional bridge variables:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `WORKBUDDY_MODELS` | `auto` | Comma-separated fallback model IDs |
+| `WORKBUDDY_CONTEXT_WINDOW` | `32768` | Assumed context limit |
+| `WORKBUDDY_MAX_TOKENS` | `4096` | Assumed output limit |
+| `WORKBUDDY_TIMEOUT_MS` | `3000` | Discovery timeout in milliseconds |
+
+## Development and tests
+
+There are no runtime dependencies beyond the packages provided by Pi. Host packages are declared as peers, not bundled or installed again by the project.
+
+```sh
+npm test
+npm run check
+npm pack --dry-run
+```
+
+Host integration tests are optional and skipped unless `PI_AI_TEST_PATH` is set. To use an existing Pi installation, point it to the `pi-ai/dist` directory:
+
+```powershell
+$env:PI_AI_TEST_PATH = "C:/path/to/pi-coding-agent/node_modules/@earendil-works/pi-ai/dist"
+npm test
+node scripts/smoke-cli.mjs "C:/path/to/pi-coding-agent/dist/bundle/cli.js"
+```
+
+Host tests cover coordinated login, storage and refresh, tool-call/result round trips, reasoning, Unicode, usage tails, instrumentation, empty and truncated streams, errors, and cancellation. The CLI smoke test uses an offline temporary profile with synthetic credentials and removes it afterward. **None of these automated tests sends a prompt to the live WorkBuddy service.**
+
+Local investigation notes:
+[authentication](research/workbuddy-auth-findings.md) ·
+[chat protocol](research/workbuddy-protocol-findings.md) ·
+[error 12403](research/12403-findings.md) ·
+[context-limit audit](research/context-limit-audit.md).
+
+These notes are not included in the npm tarball. Raw third-party snapshots and generated evidence remain local and are excluded from Git; they are preserved verbatim rather than translated so their provenance and hashes remain valid. The authored documentation, code comments, user-facing messages, and test fixtures use English. Emoji in test fixtures intentionally exercise Unicode streaming.
+
+Pi CLI setup instructions were checked against Context7 library `/earendil-works/pi/v1.3.0`.
+
+## License
+
+The extension code is licensed under MIT. Third-party application snapshots and generated evidence are not part of the distributed package.

package/extensions/workbuddy.js

@@ -0,0 +1,15 @@
+import { openAICompletionsApi } from "@earendil-works/pi-ai/compat";
+import bridge from "../src/bridge-extension.js";
+import { createWorkbuddyProvider, registerNativeCommands } from "../src/native-provider.js";
+
+export default async function workbuddy(pi) {
+  const mode = process.env.WORKBUDDY_MODE || "native";
+  if (mode === "bridge") return bridge(pi);
+  if (mode !== "native") throw new Error("WORKBUDDY_MODE must be native or bridge.");
+  if (process.env.WORKBUDDY_GZIP && !["0", "1"].includes(process.env.WORKBUDDY_GZIP)) {
+    throw new Error("WORKBUDDY_GZIP must be 0 or 1.");
+  }
+  const provider = createWorkbuddyProvider({ api: openAICompletionsApi(), gzip: process.env.WORKBUDDY_GZIP !== "0" });
+  pi.registerProvider(provider);
+  registerNativeCommands(pi, provider);
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "pi-workbuddy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Native WorkBuddy account login and direct model provider for Pi",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lutfi238/pi-workbuddy.git"
+  },
+  "homepage": "https://github.com/lutfi238/pi-workbuddy#readme",
+  "bugs": {
+    "url": "https://github.com/lutfi238/pi-workbuddy/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "workbuddy",
+    "pi-extension"
+  ],
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/workbuddy.js"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "check": "node scripts/check.mjs"
+  }
+}

package/src/bridge-extension.js

@@ -0,0 +1,45 @@
+import { discoverModels, literalApiKey, modelDefinitions, readConfig } from "./bridge.js";
+
+/** WorkBuddy's OpenAI-compatible bridge; no desktop credential access. */
+export default async function workbuddy(pi) {
+  const config = readConfig();
+  let ids = config.fallbackIds;
+  let discoveryError;
+  const register = () => pi.registerProvider("workbuddy-bridge", {
+    baseUrl: config.baseUrl,
+    api: "openai-completions",
+    apiKey: literalApiKey(config.apiKey),
+    models: modelDefinitions(ids, config),
+  });
+  try { ids = await discoverModels(config); }
+  catch (error) { discoveryError = error.message; }
+  register();
+
+  pi.registerCommand("workbuddy", {
+    description: "WorkBuddy bridge: status or refresh model catalog",
+    handler: async (args, ctx) => {
+      const action = args.trim() || "status";
+      if (!["status", "refresh"].includes(action)) {
+        ctx.ui.notify("Usage: /workbuddy [status|refresh]", "warning");
+        return;
+      }
+      try {
+        const found = await discoverModels(config, ctx.signal);
+        if (action === "refresh") {
+          ids = found;
+          register();
+          discoveryError = undefined;
+        }
+        ctx.ui.notify(
+          "WorkBuddy bridge reachable: " + found.length + " advertised models. " +
+          (action === "refresh" ? "Catalog refreshed; select with /model." :
+            ids.length + " registered. Use /workbuddy refresh to update.") +
+          (discoveryError ? " Startup used fallback models." : ""),
+          "info",
+        );
+      } catch (error) {
+        ctx.ui.notify(error.message + " Existing catalog retained.", "warning");
+      }
+    },
+  });
+}

package/src/bridge.js

@@ -0,0 +1,63 @@
+export function readConfig(env = process.env) {
+  const url = new URL(env.WORKBUDDY_BASE_URL || "http://127.0.0.1:8787/v1");
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new Error("WORKBUDDY_BASE_URL must be an HTTP(S) URL without credentials, query, or fragment.");
+  }
+  const positiveInt = (name, fallback) => {
+    const value = env[name] === undefined ? fallback : Number(env[name]);
+    if (!Number.isSafeInteger(value) || value <= 0) throw new Error(name + " must be a positive integer.");
+    return value;
+  };
+  const contextWindow = positiveInt("WORKBUDDY_CONTEXT_WINDOW", 32768);
+  const maxTokens = positiveInt("WORKBUDDY_MAX_TOKENS", 4096);
+  if (maxTokens > contextWindow) throw new Error("WORKBUDDY_MAX_TOKENS must not exceed WORKBUDDY_CONTEXT_WINDOW.");
+  const fallbackIds = [...new Set((env.WORKBUDDY_MODELS || "auto").split(",").map(s => s.trim()).filter(Boolean))];
+  if (!fallbackIds.length) throw new Error("WORKBUDDY_MODELS must contain at least one model ID.");
+  return {
+    baseUrl: url.href.replace(/\/+$/, ""),
+    apiKey: env.WORKBUDDY_API_KEY || "workbuddy-local",
+    timeoutMs: positiveInt("WORKBUDDY_TIMEOUT_MS", 3000),
+    fallbackIds, contextWindow, maxTokens,
+  };
+}
+
+// ProviderConfig interprets $, ! prefixes. Escape literal bridge credentials.
+export function literalApiKey(key) {
+  const escaped = key.replaceAll("$", () => "$$");
+  return escaped.startsWith("!") ? "$!" + escaped.slice(1) : escaped;
+}
+
+export function modelDefinitions(ids, config) {
+  return ids.map(id => ({
+    id, name: "WorkBuddy · " + id,
+    reasoning: false, input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: config.contextWindow, maxTokens: config.maxTokens,
+  }));
+}
+
+export async function discoverModels(config, signal) {
+  const timeout = AbortSignal.timeout(config.timeoutMs);
+  let response;
+  try {
+    response = await fetch(config.baseUrl + "/models", {
+      headers: { Authorization: "Bearer " + config.apiKey },
+      signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+      redirect: "error",
+    });
+  } catch {
+    throw new Error("Bridge unreachable or request cancelled/timed out. Check its process, URL, and timeout.");
+  }
+  if (!response.ok) {
+    // Never echo upstream bodies: they can contain tokens or account details.
+    await response.body?.cancel();
+    throw new Error("Bridge model discovery failed (HTTP " + response.status + ").");
+  }
+  let body;
+  try { body = await response.json(); }
+  catch { throw new Error("Bridge returned invalid JSON."); }
+  if (!Array.isArray(body?.data)) throw new Error("Bridge must return an OpenAI model list: { data: [{ id }] }.");
+  const ids = [...new Set(body.data.map(item => item?.id).filter(id => typeof id === "string" && id.trim()))];
+  if (!ids.length) throw new Error("Bridge returned no usable model IDs.");
+  return ids;
+}

package/src/client-identity.js

@@ -0,0 +1,6 @@
+// Compatibility baseline: the operator-supplied WorkBuddy AI 5.8.4 artifact.
+// This is a protocol/version marker, not an assertion that Pi is the official desktop app.
+export const EXTENSION_VERSION = "0.2.1";
+export const WORKBUDDY_PROTOCOL_VERSION = "5.8.4";
+export const USER_AGENT = "CLI/unknown WorkBuddy/" + WORKBUDDY_PROTOCOL_VERSION +
+  " pi-workbuddy/" + EXTENSION_VERSION;

package/src/native-capabilities.js

@@ -0,0 +1,84 @@
+// Reviewed public vendor specifications supplement live WorkBuddy metadata.
+// These are optimistic capabilities, not entitlement checks or a model-ID allowlist.
+const profiles = new Map();
+function add(ids, profile) {
+  for (const id of ids) profiles.set(id, Object.freeze({
+    ...profile,
+    ...(profile.efforts ? { efforts: Object.freeze([...profile.efforts]) } : {}),
+  }));
+}
+const deepseek = {
+  contextWindow: 1048576, maxOutputTokens: 393216, images: true, reasoning: true,
+  efforts: ["low", "high", "max"],
+  source: "https://api-docs.deepseek.com/quick_start/pricing",
+};
+// Apply the named base model's documented abilities to the regional variant too.
+// This is an optimistic name mapping, not proof of identical gateway deployments.
+add(["deepseek-v4.1-flash", "deepseek-v4.1-flash-sg"], deepseek);
+for (const id of ["gemini-3.5-flash", "gemini-3.8-flash"]) add([id], {
+  contextWindow: 1048576, maxOutputTokens: 65536, images: true, reasoning: true,
+  onlyReasoning: true,
+  efforts: [...(id === "gemini-3.5-flash" ? ["minimal"] : []), "low", "medium", "high"],
+  source: "https://ai.google.dev/gemini-api/docs/models/" + id,
+});
+for (const id of ["glm-5.2", "glm-5.3", "glm-5.3-flash"]) add([id], {
+  // Vendor docs publish rounded 1M; retain larger exact values advertised by WorkBuddy.
+  contextWindow: 1000000, maxOutputTokens: 131072, images: id === "glm-5.3-flash", reasoning: true,
+  onlyReasoning: id !== "glm-5.2",
+  efforts: id === "glm-5.2" ? ["minimal", "low", "medium", "high", "xhigh", "max"] : ["low", "high", "max"],
+  off: "none", source: "https://docs.z.ai/guides/llm/" + id,
+});
+for (const id of ["gpt-5.4", "gpt-5.5", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra",
+  "gpt-6-astra", "gpt-6-luna", "gpt-6-sol", "gpt-6.1-sol"]) add([id], {
+  contextWindow: 1050000, maxOutputTokens: 128000, images: true, reasoning: true,
+  efforts: ["low", "medium", "high", "xhigh", ...(["gpt-5.4", "gpt-5.5"].includes(id) ? [] : ["max"])],
+  onlyReasoning: ["gpt-6-astra", "gpt-6.1-sol"].includes(id), off: "none",
+  source: "https://developers.openai.com/api/docs/models/" + id,
+});
+add(["grok-4.7"], {
+  contextWindow: 500000, images: true, reasoning: true, onlyReasoning: true,
+  // "No text output limit" is not a finite output number; keep WorkBuddy's numeric value.
+  efforts: ["low", "medium", "high", "xhigh"], source: "https://docs.x.ai/developers/grok-4-7",
+});
+add(["hy3"], {
+  contextWindow: 256000, maxOutputTokens: 128000, reasoning: true, efforts: ["low", "high"], off: "none",
+  source: "https://intl.cloud.tencent.com/ind/document/product/1300/80695",
+});
+add(["hy4-preview"], {
+  contextWindow: 1000000, maxOutputTokens: 64000, reasoning: true, efforts: ["high"], off: "none",
+  source: "https://intl.cloud.tencent.com/ind/document/product/1300/80695",
+});
+add(["kimi-k2.6"], {
+  contextWindow: 262144, maxOutputTokens: 262144, images: true, reasoning: true,
+  // K2.6 uses thinking.type, not reasoning_effort. Its output shares the context window.
+  thinkingFormat: "deepseek", supportsReasoningEffort: false,
+  source: "https://platform.kimi.ai/docs/api/models-overview",
+});
+add(["kimi-k2.8-preview"], {
+  // Official Kimi Code docs name K2.8 Preview but expose it as kimi-for-coding.
+  // Use that named-model reference optimistically; no published finite output cap.
+  contextWindow: 1048576, reasoning: true, efforts: ["low", "high", "max"],
+  source: "https://www.kimi.com/code/docs/en/kimi-code/models",
+});
+add(["kimi-k3"], {
+  contextWindow: 1048576, maxOutputTokens: 1048576, images: true, reasoning: true, onlyReasoning: true,
+  // This is the accepted completion-parameter ceiling, not additional independent context.
+  efforts: ["low", "high", "max"], source: "https://platform.kimi.ai/docs/guide/kimi-k3-quickstart",
+});
+add(["minimax-m3.1-flash"], {
+  contextWindow: 1000000, maxOutputTokens: 524288, images: true, reasoning: true, onlyReasoning: true,
+  efforts: ["low", "medium", "high", "xhigh", "max"],
+  source: "https://platform.minimax.io/docs/guides/models-intro",
+});
+add(["step-5-preview"], {
+  contextWindow: 1000000, maxOutputTokens: 64000, images: true, reasoning: true,
+  efforts: ["low", "medium", "high"], source: "https://platform.stepfun.ai/docs/en/guides/models/step-5-preview",
+});
+
+export function getVendorCapabilities(id) {
+  return profiles.get(id);
+}
+
+export function vendorCapabilityIds() {
+  return [...profiles.keys()];
+}

package/src/native-client.js

@@ -0,0 +1,183 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { WorkbuddyError } from "./native-errors.js";
+import { USER_AGENT } from "./client-identity.js";
+
+export const ORIGIN = "https://www.workbuddy.ai";
+export const BASE_URL = ORIGIN + "/v2";
+const BROWSER_ORIGINS = new Set([ORIGIN, "https://workbuddy.ai", "https://www.codebuddy.ai"]);
+const ACCOUNT_DOMAINS = new Set(["www.workbuddy.ai", "workbuddy.ai", "www.codebuddy.ai"]);
+const LIMIT = 2 * 1024 * 1024;
+
+export function safeHeader(value, name = "account metadata") {
+  if (typeof value !== "string" || !value || value.length > (name.includes("token") ? 16384 : 2048) || /[\r\n\0]/.test(value)) {
+    throw new WorkbuddyError("metadata", "Invalid WorkBuddy " + name + ".");
+  }
+  return value;
+}
+
+export function accountHeaders(credential) {
+  if (credential?.type !== "oauth" || credential.origin !== ORIGIN) {
+    throw new WorkbuddyError("credentials", "WorkBuddy credentials are missing or belong to a different endpoint. Run /login.");
+  }
+  validDomain({ domain: credential.domain });
+  const headers = {
+    Authorization: "Bearer " + safeHeader(credential.access, "access token"),
+    "X-User-Id": safeHeader(credential.userId, "user ID"),
+    "X-Domain": credential.domain || "www.workbuddy.ai",
+    "X-Product": "SaaS", "X-Requested-With": "XMLHttpRequest",
+    "User-Agent": USER_AGENT,
+  };
+  if (credential.enterpriseId) {
+    headers["X-Enterprise-Id"] = safeHeader(credential.enterpriseId);
+    headers["X-Tenant-Id"] = headers["X-Enterprise-Id"];
+  }
+  return headers;
+}
+
+export async function limitedJson(response, limit = LIMIT) {
+  if (!response.body) throw new WorkbuddyError("empty-response", "WorkBuddy returned an empty response.");
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > limit) throw new WorkbuddyError("response-size", "WorkBuddy response exceeds the size limit.");
+      chunks.push(value);
+    }
+  } catch (error) {
+    if (error instanceof WorkbuddyError) throw error;
+    throw new WorkbuddyError("response-read", "WorkBuddy response could not be read.");
+  } finally {
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+  catch { throw new WorkbuddyError("invalid-json", "WorkBuddy returned invalid JSON."); }
+}
+
+function validDomain(token) {
+  if (token.domain && !ACCOUNT_DOMAINS.has(token.domain)) {
+    throw new WorkbuddyError("account-domain", "WorkBuddy returned an unsupported account domain.");
+  }
+}
+
+function tokenCredential(token, account, previous, now) {
+  if (!token || typeof token !== "object") throw new Error("WorkBuddy returned no token.");
+  validDomain(token);
+  const access = safeHeader(token.accessToken, "access token");
+  const refresh = token.refreshToken === undefined ? previous?.refresh || "" : token.refreshToken;
+  if (refresh !== "") safeHeader(refresh, "refresh token");
+  const expires = Number.isFinite(token.expiresAt) ? token.expiresAt :
+    Number.isFinite(token.expiresIn) ? now + token.expiresIn * 1000 : undefined;
+  if (!Number.isSafeInteger(expires) || expires <= now) {
+    throw new Error("WorkBuddy returned missing or expired token expiry. Please sign in again.");
+  }
+  return {
+    type: "oauth", origin: ORIGIN, access, refresh, expires,
+    domain: token.domain || previous?.domain || "www.workbuddy.ai",
+    userId: safeHeader(String(account?.uid ?? previous?.userId ?? ""), "user ID"),
+    ...(account?.enterpriseId || previous?.enterpriseId ?
+      { enterpriseId: safeHeader(String(account?.enterpriseId ?? previous.enterpriseId)) } : {}),
+  };
+}
+
+export function createNativeClient({
+  fetch: fetchImpl = globalThis.fetch, requestTimeoutMs = 15000,
+  loginTimeoutMs = 300000, pollIntervalMs = 1000, now = Date.now,
+} = {}) {
+  async function request(path, { method = "GET", credential, signal, pendingCode, headers = {} } = {}) {
+    const url = new URL(path, ORIGIN);
+    if (url.origin !== ORIGIN || url.username || url.password) throw new WorkbuddyError("endpoint", "Untrusted WorkBuddy endpoint.");
+    const timed = AbortSignal.timeout(requestTimeoutMs);
+    const activeSignal = signal ? AbortSignal.any([signal, timed]) : timed;
+    // Validate credential metadata before fetch so validation failures are not mislabeled as network errors.
+    const requestHeaders = {
+      "Content-Type": "application/json", "X-Domain": "www.workbuddy.ai",
+      "X-Product": "SaaS", "X-Requested-With": "XMLHttpRequest",
+      "User-Agent": USER_AGENT,
+      ...(credential ? accountHeaders(credential) : {}), ...headers,
+    };
+    let response;
+    try {
+      response = await fetchImpl(url, {
+        method, redirect: "error", signal: activeSignal, headers: requestHeaders,
+        ...(method === "POST" ? { body: "{}" } : {}),
+      });
+    } catch {
+      if (signal?.aborted) throw new WorkbuddyError("cancelled", "WorkBuddy operation cancelled or timed out.");
+      if (timed.aborted) throw new WorkbuddyError("request-timeout", "WorkBuddy request timed out.");
+      throw new WorkbuddyError("network", "Cannot reach WorkBuddy. Check your connection or retry.");
+    }
+    let envelope;
+    try { envelope = await limitedJson(response); }
+    catch (error) {
+      if (!response.ok) throw new WorkbuddyError("http", "WorkBuddy request failed (HTTP " + response.status + ").", { status: response.status });
+      throw error;
+    }
+    if (pendingCode !== undefined && envelope?.code === pendingCode) return undefined;
+    if (!response.ok || (envelope?.code !== undefined && envelope.code !== 0)) {
+      const code = typeof envelope?.code === "number" ? "; code " + envelope.code : "";
+      throw new WorkbuddyError("http", "WorkBuddy request failed (HTTP " + response.status + code + ").", {
+        status: response.status, businessCode: typeof envelope?.code === "number" ? envelope.code : undefined,
+      });
+    }
+    if (!envelope || typeof envelope !== "object" || envelope.data === undefined) {
+      throw new WorkbuddyError("envelope", "WorkBuddy returned an unexpected response envelope.");
+    }
+    return envelope.data;
+  }
+
+  return {
+    async login(interaction) {
+      const deadline = AbortSignal.timeout(loginTimeoutMs);
+      const signal = interaction.signal ? AbortSignal.any([interaction.signal, deadline]) : deadline;
+      interaction.notify({ type: "progress", message: "Requesting WorkBuddy browser login…" });
+      const state = await request("/v2/plugin/auth/state?platform=workbuddy-ai", { method: "POST", signal });
+      if (typeof state?.state !== "string" || !state.state || state.state.length > 4096) {
+        throw new Error("WorkBuddy returned an invalid login state.");
+      }
+      let authUrl;
+      try { authUrl = new URL(state.authUrl); } catch { throw new Error("Invalid WorkBuddy login URL."); }
+      if (!BROWSER_ORIGINS.has(authUrl.origin) || authUrl.username || authUrl.password) {
+        throw new Error("WorkBuddy returned an untrusted login URL.");
+      }
+      interaction.notify({ type: "auth_url", url: authUrl.href, instructions: "Sign in with your WorkBuddy account in the browser. Pi will wait; Escape cancels." });
+      const query = encodeURIComponent(state.state);
+      let token;
+      while (!token) {
+        signal.throwIfAborted();
+        token = await request("/v2/plugin/auth/token?state=" + query, { signal, pendingCode: 11217 });
+        if (!token) await sleep(pollIntervalMs, undefined, { signal });
+      }
+      // Fetch account before creating/storing any Pi credential.
+      safeHeader(token.accessToken, "access token");
+      validDomain(token);
+      let account;
+      while (!account) {
+        signal.throwIfAborted();
+        account = await request("/v2/plugin/login/account?state=" + query, {
+          signal, pendingCode: 12151, headers: { Authorization: "Bearer " + token.accessToken },
+        });
+        if (!account) await sleep(pollIntervalMs, undefined, { signal });
+      }
+      const credential = tokenCredential(token, account, undefined, now());
+      interaction.notify({ type: "info", message: "WorkBuddy login completed. Run /workbuddy refresh, then select a model with /model." });
+      return credential;
+    },
+    async refresh(credential, signal) {
+      accountHeaders(credential); // Validate binding before any I/O.
+      if (!credential.refresh) throw new Error("WorkBuddy did not issue a refresh token. Run /login again.");
+      const token = await request("/v2/plugin/auth/token/refresh", {
+        method: "POST", credential, signal,
+        headers: { "X-Refresh-Token": safeHeader(credential.refresh), "X-Auth-Refresh-Source": "plugin" },
+      });
+      return tokenCredential(token, undefined, credential, now());
+    },
+    async catalog(credential, signal) {
+      return request("/v3/config", { credential, signal });
+    },
+  };
+}

package/src/native-errors.js

@@ -0,0 +1,47 @@
+// Only explicitly allowlisted diagnostic fields may reach the UI. Never stringify upstream errors.
+const REASONS = {
+  "credentials": "Credentials are missing or bound to a different endpoint; use /login.",
+  "account-domain": "The account domain is not supported by this provider.",
+  "metadata": "Account metadata or token has an invalid format.",
+  "endpoint": "An untrusted endpoint was rejected.",
+  "cancelled": "The operation was cancelled.",
+  "request-timeout": "The WorkBuddy request timed out.",
+  "network": "Cannot reach WorkBuddy; check connection or proxy settings.",
+  "http": "The server rejected the request.",
+  "empty-response": "The server returned an empty response.",
+  "response-size": "The response exceeded the size limit.",
+  "invalid-json": "The server response was not valid JSON.",
+  "response-read": "The response body could not be read.",
+  "envelope": "The JSON response envelope was unexpected.",
+  "catalog-shape": "The response did not contain a supported models array.",
+  "catalog-empty": "The server returned an empty model list.",
+  "catalog-filtered": "No model passed the provider's compatibility/security filters.",
+};
+export class WorkbuddyError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "WorkbuddyError";
+    this.diagnosticCode = code;
+    this.details = details;
+  }
+}
+
+export function describeFailure(error) {
+  const seen = new Set();
+  for (let current = error, depth = 0; current && depth < 6 && !seen.has(current); current = current.cause, depth++) {
+    seen.add(current);
+    if (!(current instanceof WorkbuddyError) || !Object.hasOwn(REASONS, current.diagnosticCode)) continue;
+    const { status, businessCode, total, accepted, endpoint, disabled, toolLess, unavailable, invalid, duplicate } = current.details;
+    const fields = [];
+    if (Number.isInteger(status) && status >= 100 && status <= 599) fields.push("HTTP " + status);
+    if (Number.isSafeInteger(businessCode)) fields.push("business code " + businessCode);
+    for (const [name, value] of Object.entries({ total, accepted, endpoint, disabled, toolLess, unavailable, invalid, duplicate })) {
+      if (Number.isSafeInteger(value) && value >= 0) fields.push(name + "=" + value);
+    }
+    const hint = current.diagnosticCode === "http" && businessCode === 12403 ?
+      " WorkBuddy could not parse the client version/User-Agent; reload the updated extension." : "";
+    return "[" + current.diagnosticCode + "] " + REASONS[current.diagnosticCode] +
+      (fields.length ? " (" + fields.join(", ") + ")" : "") + hint;
+  }
+  return "[unknown] Catalog refresh failed. No upstream error text was displayed to protect credentials.";
+}

package/src/native-limits.js

@@ -0,0 +1,43 @@
+const FALLBACK_CONTEXT = 32768;
+const FALLBACK_OUTPUT = 4096;
+export const isTokenLimit = value => Number.isSafeInteger(value) && value > 0;
+
+/** Use the largest advertised/documented budget, not a smaller configured default. */
+export function resolveTokenLimits(item, vendor = {}) {
+  const supported = Array.isArray(item.contextWindow?.supportedLengths) ? item.contextWindow.supportedLengths : [];
+  const contexts = [item.maxInputTokens, item.contextWindow?.defaultLength, ...supported, vendor.contextWindow].filter(isTokenLimit);
+  const contextWindow = contexts.reduce((maximum, value) => Math.max(maximum, value), 0) || FALLBACK_CONTEXT;
+  const outputs = [item.maxOutputTokens, vendor.maxOutputTokens].filter(isTokenLimit);
+  // Input and output still share Pi's context budget; never add them together.
+  const maxTokens = Math.min(outputs.length ? Math.max(...outputs) : FALLBACK_OUTPUT, contextWindow);
+  // maxAllowedSize remains excluded because its units are not established.
+  return { contextWindow, maxTokens };
+}
+
+export function resolveOutputLimit(model, requested) {
+  if (requested !== undefined && !isTokenLimit(requested)) {
+    throw new Error("WorkBuddy maxTokens must be a positive safe integer.");
+  }
+  if (!isTokenLimit(model.maxTokens) || !isTokenLimit(model.contextWindow)) {
+    throw new Error("WorkBuddy model token limits are invalid; refresh the model catalog.");
+  }
+  return Math.min(requested ?? model.maxTokens, model.maxTokens, model.contextWindow);
+}
+
+/** Apply after caller payload hooks so sampling parameters cannot silently bypass the output cap. */
+export function capPayloadOutput(payload, outputLimit) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("WorkBuddy chat payload must be an object.");
+  }
+  const fields = ["max_tokens", "max_completion_tokens"];
+  let limit = outputLimit;
+  for (const field of fields) {
+    if (payload[field] === undefined) continue;
+    if (!isTokenLimit(payload[field])) throw new Error("WorkBuddy " + field + " must be a positive safe integer.");
+    limit = Math.min(limit, payload[field]);
+  }
+  // The inspected WorkBuddy wire format uses max_tokens, not max_completion_tokens.
+  const result = { ...payload, max_tokens: limit };
+  delete result.max_completion_tokens;
+  return result;
+}

package/src/native-models.js

@@ -0,0 +1,63 @@
+import { BASE_URL } from "./native-client.js";
+import { WorkbuddyError } from "./native-errors.js";
+import { resolveTokenLimits } from "./native-limits.js";
+import { getVendorCapabilities } from "./native-capabilities.js";
+const COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+const LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"];
+const validId = value => typeof value === "string" && value.length <= 256 && /^[\w./:-]+$/.test(value);
+
+export function projectModels(config) {
+  if (!Array.isArray(config?.models) || config.models.length > 2000) {
+    throw new WorkbuddyError("catalog-shape", "Invalid WorkBuddy model catalog.");
+  }
+  const available = Array.isArray(config.availableModels) && config.availableModels.length ? new Set(config.availableModels) : undefined;
+  const seen = new Set();
+  const models = [];
+  const counts = { total: config.models.length, accepted: 0, invalid: 0, duplicate: 0,
+    disabled: 0, toolLess: 0, endpoint: 0, unavailable: 0 };
+  for (const item of config.models) {
+    // Report only counts, never model URLs, API keys, remote instructions, or full catalog bodies.
+    if (!validId(item?.id)) { counts.invalid++; continue; }
+    if (seen.has(item.id)) { counts.duplicate++; continue; }
+    if (item.disabled === true) { counts.disabled++; continue; }
+    if (item.supportsToolCall === false) { counts.toolLess++; continue; }
+    if (item.url || item.apiKey || item.useCustomProtocol) { counts.endpoint++; continue; }
+    if (available && !available.has(item.id)) { counts.unavailable++; continue; }
+    seen.add(item.id);
+    const vendor = getVendorCapabilities(item.id) ?? {};
+    const { contextWindow, maxTokens } = resolveTokenLimits(item, vendor);
+    const reasoning = item.supportsReasoning === true || vendor.reasoning === true;
+    const catalogEfforts = Array.isArray(item.reasoning?.supportedEfforts) ? item.reasoning.supportedEfforts : [];
+    const efforts = [...new Set([...catalogEfforts, ...(vendor.efforts ?? [])].filter(effort => LEVELS.includes(effort)))];
+    const onlyReasoning = item.onlyReasoning === true || item.reasoning?.canDisableThinking === false || vendor.onlyReasoning === true;
+    const thinkingLevelMap = reasoning ? {
+      ...(onlyReasoning ? { off: null } : vendor.off ? { off: vendor.off } : {}),
+      ...(efforts?.length ? Object.fromEntries(LEVELS.map(level => [level, efforts.includes(level) ? level : null])) : {}),
+    } : undefined;
+    models.push({
+      id: item.id, name: typeof item.name === "string" ? item.name.slice(0, 256) : item.id,
+      provider: "workbuddy", api: "openai-completions", baseUrl: BASE_URL,
+      // Prefer availability: retain gateway image support even when the vendor is text-only,
+      // and expose vendor-advertised image support even if gateway metadata omits/disables it.
+      reasoning, input: item.supportsImages === true || vendor.images === true ? ["text", "image"] : ["text"],
+      cost: { ...COST }, contextWindow, maxTokens,
+      ...(thinkingLevelMap ? { thinkingLevelMap } : {}),
+      samplingParams: {
+        ...(Number.isFinite(item.temperature) ? { temperature: item.temperature } : {}),
+        ...(Number.isFinite(item.top_p) ? { top_p: item.top_p } : {}),
+      },
+      // Observed in the shipped SDK: system role and max_tokens; never infer from model names.
+      compat: { supportsDeveloperRole: false, maxTokensField: "max_tokens", supportsStore: false,
+        supportsReasoningEffort: reasoning && (vendor.supportsReasoningEffort !== false || catalogEfforts.length > 0),
+        ...(vendor.thinkingFormat ? { thinkingFormat: vendor.thinkingFormat } : {}),
+      },
+    });
+  }
+  if (!models.length) throw new WorkbuddyError(config.models.length ? "catalog-filtered" : "catalog-empty",
+    "WorkBuddy returned no supported tool-capable models. Existing catalog retained.", counts);
+  return models;
+}
+
+export function fallbackModels() {
+  return projectModels({ models: [{ id: "default-model", name: "WorkBuddy Default (fallback)", maxInputTokens: 32768, maxOutputTokens: 4096 }] });
+}

package/src/native-provider.js

@@ -0,0 +1,114 @@
+import { createNativeClient, accountHeaders, BASE_URL } from "./native-client.js";
+import { fallbackModels, projectModels } from "./native-models.js";
+import { createChatFetch } from "./native-transport.js";
+import { describeFailure } from "./native-errors.js";
+import { resolveOutputLimit, capPayloadOutput } from "./native-limits.js";
+
+export function createWorkbuddyProvider({ api, client = createNativeClient(), fetch: fetchImpl, gzip = true } = {}) {
+  if (!api?.stream || !api?.streamSimple) throw new Error("Pi OpenAI streaming API is required.");
+  let models = fallbackModels();
+  let catalogSource = "fallback";
+  let lastCatalogError;
+  function prepareRequest(model, options = {}) {
+    let outputLimit = resolveOutputLimit(model, options.maxTokens);
+    const modelSampling = model.samplingParams ? { ...model.samplingParams } : undefined;
+    const requestSampling = options.samplingParams ? { ...options.samplingParams } : undefined;
+    for (const params of [modelSampling, requestSampling]) {
+      if (!params) continue;
+      for (const key of ["max_tokens", "max_completion_tokens"]) {
+        if (params[key] !== undefined) outputLimit = resolveOutputLimit({ ...model, maxTokens: outputLimit }, params[key]);
+        delete params[key];
+      }
+    }
+    return {
+      model: { ...model, baseUrl: BASE_URL, samplingParams: modelSampling },
+      options: {
+        ...options, maxTokens: outputLimit, samplingParams: requestSampling,
+        maxRetries: options.maxRetries ?? 0, timeoutMs: options.timeoutMs ?? 120000,
+        fetch: createChatFetch({ fetch: options.fetch ?? fetchImpl, gzip, sessionId: options.sessionId }),
+        async onPayload(payload, wireModel) {
+          // Preserve Pi streamSimple's remaining-context clamp before invoking caller hooks.
+          const bounded = capPayloadOutput(payload, outputLimit);
+          const ceiling = bounded.max_tokens;
+          const replacement = await options.onPayload?.(bounded, wireModel);
+          return capPayloadOutput(replacement === undefined ? bounded : replacement, ceiling);
+        },
+      },
+    };
+  }
+  return {
+    id: "workbuddy", name: "WorkBuddy AI (experimental native)", baseUrl: BASE_URL,
+    auth: {
+      oauth: {
+        name: "WorkBuddy AI", loginLabel: "Sign in with your WorkBuddy account", isSubscription: true,
+        login: interaction => client.login(interaction),
+        refresh: (credential, signal) => client.refresh(credential, signal),
+        toAuth: async credential => ({
+          apiKey: credential.access, headers: accountHeaders(credential), baseUrl: BASE_URL,
+        }),
+      },
+    },
+    getModels: () => models,
+    getCatalogStatus: () => ({ source: catalogSource, lastError: lastCatalogError }),
+    async refreshModels(context) {
+      if (!context.allowNetwork || context.credential?.type !== "oauth") return;
+      try {
+        const next = projectModels(await client.catalog(context.credential, context.signal));
+        // Generation-checked publication owned by Pi. No auth or remote instructions persisted.
+        await context.publish({ update: () => {
+          models = next; catalogSource = "remote"; lastCatalogError = undefined;
+        } });
+      } catch (error) {
+        lastCatalogError = describeFailure(error);
+        throw error;
+      }
+    },
+    stream(model, context, options) {
+      const request = prepareRequest(model, options);
+      return api.stream(request.model, context, request.options);
+    },
+    streamSimple(model, context, options) {
+      const request = prepareRequest(model, options);
+      return api.streamSimple(request.model, context, request.options);
+    },
+  };
+}
+
+export function registerNativeCommands(pi, provider) {
+  pi.registerCommand("workbuddy", {
+    description: "Native WorkBuddy provider: status/doctor (local) or refresh model catalog",
+    handler: async (args, ctx) => {
+      const action = args.trim() || "status";
+      if (action === "status" || action === "doctor") {
+        const ready = ctx.modelRegistry.hasConfiguredAuth(provider.getModels()[0]);
+        const catalog = provider.getCatalogStatus?.();
+        const active = ctx.model ? ctx.model.provider + "/" + ctx.model.id : "unknown";
+        ctx.ui.notify("WorkBuddy native (experimental): " + (ready ? "account configured" : "not logged in; use /login") +
+          ". " + provider.getModels().length + " known models; catalog=" + (catalog?.source ?? "unknown") +
+          ". Active model: " + active + "." + (catalog?.lastError ? " Last catalog failure: " + catalog.lastError : "") +
+          " No chat request sent.", "info");
+      } else if (action === "refresh") {
+        try {
+          if (!ctx.modelRegistry.hasConfiguredAuth(provider.getModels()[0])) {
+            ctx.ui.notify("Sign in to WorkBuddy using /login first.", "warning"); return;
+          }
+          const result = await ctx.modelRegistry.refresh({ providers: ["workbuddy"], allowNetwork: true, force: true, signal: ctx.signal });
+          if (result.aborted) {
+            ctx.ui.notify("[cancelled] WorkBuddy catalog refresh cancelled. Existing catalog retained. No chat request sent.", "warning");
+            return;
+          }
+          if (result.errors.has("workbuddy")) {
+            ctx.ui.notify("WorkBuddy catalog refresh failed: " + describeFailure(result.errors.get("workbuddy")) +
+              " Existing catalog retained. No chat request sent.", "warning");
+            return;
+          }
+          ctx.ui.notify("WorkBuddy catalog refreshed: " + provider.getModels().length + " models. Select with /model.", "info");
+        } catch (error) {
+          ctx.ui.notify("WorkBuddy catalog refresh failed: " +
+            (ctx.signal?.aborted ? "[cancelled] Operation cancelled." : describeFailure(error)) +
+            " Existing catalog retained. No chat request sent.", "warning");
+        }
+      } else ctx.ui.notify("Usage: /workbuddy [status|doctor|refresh]. Sign in using /login.", "warning");
+    },
+  });
+}

package/src/native-transport.js

@@ -0,0 +1,115 @@
+import { randomUUID } from "node:crypto";
+import { gzipSync } from "node:zlib";
+import { ORIGIN, limitedJson } from "./native-client.js";
+import { USER_AGENT, EXTENSION_VERSION } from "./client-identity.js";
+
+// Normalize complete SSE frames, never individual TCP/UTF-8 chunks.
+export function normalizeSse(body) {
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  let pending = "";
+  const ids = new Set();
+  const indexes = new Map();
+  let nextIndex = 0;
+  function frame(text) {
+    const lines = text.split(/\r?\n/);
+    const data = lines.filter(line => line.startsWith("data:")).map(line => line.slice(5).trimStart()).join("\n");
+    if (!data || data.trim() === "[DONE]") return encoder.encode(text + "\n\n");
+    let value;
+    try { value = JSON.parse(data); } catch { throw new Error("WorkBuddy returned malformed SSE JSON."); }
+    if (value.error || (typeof value.code === "number" && value.code !== 0)) {
+      throw new Error("WorkBuddy reported a stream error.");
+    }
+    for (const choice of value.choices ?? []) {
+      for (const call of choice.delta?.tool_calls ?? []) {
+        if (!Number.isInteger(call.index)) {
+          if (call.id && indexes.has(call.id)) call.index = indexes.get(call.id);
+          else if (!call.id && nextIndex > 0) call.index = nextIndex - 1;
+          else { call.index = nextIndex++; if (call.id) indexes.set(call.id, call.index); }
+        } else {
+          nextIndex = Math.max(nextIndex, call.index + 1);
+          if (call.id) indexes.set(call.id, call.index);
+        }
+        if (call.id) {
+          if (ids.has(call.id)) delete call.id;
+          else ids.add(call.id);
+        }
+      }
+    }
+    return encoder.encode("data: " + JSON.stringify(value) + "\n\n");
+  }
+  function drain(controller, final = false) {
+    let match;
+    while ((match = /\r?\n\r?\n/.exec(pending))) {
+      const value = pending.slice(0, match.index);
+      if (value.length > 1024 * 1024) throw new Error("WorkBuddy SSE frame is too large.");
+      pending = pending.slice(match.index + match[0].length);
+      controller.enqueue(frame(value));
+    }
+    if (pending.length > 1024 * 1024) throw new Error("WorkBuddy SSE frame is too large.");
+    if (final && pending.trim()) { controller.enqueue(frame(pending)); pending = ""; }
+  }
+  return body.pipeThrough(new TransformStream({
+    transform(bytes, controller) { pending += decoder.decode(bytes, { stream: true }); drain(controller); },
+    flush(controller) { pending += decoder.decode(); drain(controller, true); },
+  }));
+}
+
+export function createChatFetch({ fetch: fetchImpl = globalThis.fetch, gzip = true, sessionId } = {}) {
+  const conversationId = sessionId || randomUUID();
+  return async (input, init) => {
+    const request = new Request(input, init);
+    const url = new URL(request.url);
+    if (url.origin !== ORIGIN || url.pathname !== "/v2/chat/completions" || url.search ||
+      url.username || url.password || request.method !== "POST") {
+      throw new Error("Refusing to send WorkBuddy credentials to an untrusted endpoint.");
+    }
+    const headers = new Headers(request.headers);
+    const requestId = randomUUID();
+    for (const [key, value] of Object.entries({
+      "X-Conversation-ID": conversationId, "X-Conversation-Request-ID": requestId,
+      "X-Conversation-Message-ID": requestId, "X-Request-ID": requestId,
+      "X-Agent-Intent": "craft", "X-IDE-Type": "pi", "X-IDE-Name": "pi-workbuddy",
+      "X-IDE-Version": EXTENSION_VERSION, "X-Product": "SaaS", "X-Requested-With": "XMLHttpRequest",
+      "User-Agent": USER_AGENT,
+      // Conservative privacy default: do not opt prompts into model optimization.
+      "X-Private-Data": "true", "Content-Type": "application/json", Accept: "text/event-stream",
+    })) headers.set(key, value);
+    const body = Buffer.from(await request.arrayBuffer());
+    if (gzip) headers.set("Content-Encoding", "gzip");
+    else headers.delete("Content-Encoding");
+    headers.delete("Content-Length");
+    let response;
+    try {
+      response = await fetchImpl(url, {
+        method: "POST", headers, body: gzip ? gzipSync(body) : body,
+        redirect: "error", signal: request.signal,
+      });
+    } catch {
+      throw new Error(request.signal.aborted ? "WorkBuddy request cancelled." : "WorkBuddy connection failed.");
+    }
+    if (!response.ok) {
+      let code;
+      try { const value = await limitedJson(response); code = value?.error?.code ?? value?.code; } catch {}
+      // Keep status, safe business code, and retry metadata; never expose upstream bodies/tokens.
+      const contextOverflow = code === "context_length_exceeded";
+      const message = contextOverflow ? "context_length_exceeded" : "WorkBuddy request failed (HTTP " + response.status +
+        (typeof code === "number" ? "; code " + code : "") + ").";
+      const outHeaders = new Headers({ "Content-Type": "application/json" });
+      const retry = response.headers.get("retry-after");
+      if (retry) outHeaders.set("Retry-After", retry);
+      return new Response(JSON.stringify({ error: { message, ...(contextOverflow ? { code } : {}) } }), {
+        status: response.status, headers: outHeaders,
+      });
+    }
+    if (!response.headers.get("content-type")?.includes("text/event-stream") || !response.body) {
+      await response.body?.cancel();
+      throw new Error("WorkBuddy did not return an SSE stream.");
+    }
+    const responseHeaders = new Headers(response.headers);
+    // The fetch implementation has already decoded transport compression.
+    responseHeaders.delete("content-encoding");
+    responseHeaders.delete("content-length");
+    return new Response(normalizeSse(response.body), { status: response.status, headers: responseHeaders });
+  };
+}