pi-workbuddy 0.2.1 → 0.2.3

package/README.md

@@ -6,15 +6,15 @@ A **WorkBuddy AI** provider for [Pi](https://pi.dev), with browser-based account
 
 ## Getting started
 
-Requires Node.js ≥22.19 and Pi with native provider support. Tested with Pi CLI **1.3.0**.
+Requires Node.js ≥22.19 and Pi with native provider support. Tested with Pi CLI **1.3.0** and Pendant 0.41.0's bundled Pi SDK **1.2.0**.
 
-Install the npm package after the `pi-workbuddy` release is published:
+Install the published npm package:
 
 ```sh
 pi install npm:pi-workbuddy
 ```
 
-Until the npm release is available, or to install directly from GitHub:
+Or install directly from GitHub:
 
 ```sh
 pi install git:github.com/lutfi238/pi-workbuddy
@@ -50,15 +50,27 @@ Use `/reload` after updating a loaded extension. To sign out, run `/logout` and
 | `/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.
+Before discovery or cache restoration, the provider includes fallback metadata for `default-model`. Models are not available until authentication is configured. Successful catalogs are persisted through **Pi's model store** as projected public metadata, scoped by a hash of the account origin/user/domain/tenant (never access or refresh tokens). Cached models are revalidated on restoration, including removal of DeepSeek `-sg` variants. A failed refresh retains the last known catalog. The extension factory itself makes no network requests.
 
 ### 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.
+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. Starting with 0.2.2, DeepSeek variants ending in `-sg` are intentionally excluded, including after catalog refresh; the regular DeepSeek models remain available. 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.
+A `session_start` hook refreshes only WorkBuddy using the registry's default network policy and honors `PI_OFFLINE` (also set by Pi CLI `--offline`). This covers embedded hosts that re-register a provider but do not refetch an already-seen provider ID. Offline provider refreshes can restore a matching cached catalog without network access.
+
+This is refresh-based discovery, not a realtime push subscription or continuous idle polling. Reopen `/model` to check for additions during a long session. Extension updates may still be necessary if WorkBuddy changes its API, authentication, metadata schema, or wire protocol.
+
+### Pendant / VS Code stays on WorkBuddy Default (fallback)
+
+Version **0.2.3** restores cached catalogs after provider re-registration and refreshes WorkBuddy at session startup. It also replaces an active bootstrap fallback with fresh metadata for the same ID. For resumed sessions, it reads only the latest model-change record; a removed DeepSeek `-sg` selection is restored to its exact non-SG counterpart if available. It does not change another provider, overwrite a newer observed selection, edit global defaults, or send a chat request. `/workbuddy refresh` also repairs stale active-model metadata.
+
+After the 0.2.3 release is published, update the package used by the host and reload the session. Restarting an old installed copy will not pick up repository changes. `/workbuddy doctor` reports the loaded extension version and `catalog=fallback`, `cache`, or `remote`; share only this sanitized diagnostic, never credentials. A genuine network/authentication error with no usable cache still requires resolving the error; no fabricated catalog is substituted.
+
+### Package published, but absent from gallery search
+
+The [direct package page](https://pi.dev/packages/pi-workbuddy) can work before the searchable gallery includes the package. npm publication and Pi gallery discovery are separate. Confirm the public npm version and the `pi-package` keyword before assuming a publishing failure. See the [reported npm-search discovery issue](https://github.com/earendil-works/pi/issues/7885). Do not repeatedly publish identical releases just to try to trigger gallery indexing.
 
 ### Login succeeds, but discovery fails or Codex remains selected
 
@@ -86,14 +98,14 @@ To select the provider, run `/model` and search for `workbuddy`; selecting a mod
 - **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.
+- **Metadata:** live catalog metadata is supplemented with reviewed official vendor specifications for 23 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.
+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. Named preview variants use their base-model references optimistically; identical gateway deployments are not guaranteed. DeepSeek `-sg` variants are not offered. 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.
 
@@ -182,13 +194,23 @@ npm test
 node scripts/smoke-cli.mjs "C:/path/to/pi-coding-agent/dist/bundle/cli.js"
 ```
 
+To additionally test against an installed Pendant bundle (no live credentials or inference):
+
+```powershell
+$env:PI_SDK_TEST_PATH = "C:/path/to/pendant/dist/pi-sdk.cjs"
+npm test
+```
+
+Pendant integration tests instantiate its actual `ModelRuntime`, resource services, session manager, and `session_start` bindings. They cover provider re-registration, offline cache restoration in a fresh runtime, startup fallback repair, and migration of a saved DeepSeek SG selection. Cache tests cover account isolation, secret/endpoint stripping, malformed entries, failed refreshes, and generation rejection.
+
 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).
+[context-limit audit](research/context-limit-audit.md) ·
+[Pendant recovery and gallery findings](research/pendant-recovery-findings.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.
 

package/extensions/workbuddy.js

@@ -1,6 +1,7 @@
 import { openAICompletionsApi } from "@earendil-works/pi-ai/compat";
 import bridge from "../src/bridge-extension.js";
 import { createWorkbuddyProvider, registerNativeCommands } from "../src/native-provider.js";
+import { registerNativeLifecycle } from "../src/native-lifecycle.js";
 
 export default async function workbuddy(pi) {
   const mode = process.env.WORKBUDDY_MODE || "native";
@@ -12,4 +13,5 @@ export default async function workbuddy(pi) {
   const provider = createWorkbuddyProvider({ api: openAICompletionsApi(), gzip: process.env.WORKBUDDY_GZIP !== "0" });
   pi.registerProvider(provider);
   registerNativeCommands(pi, provider);
+  registerNativeLifecycle(pi, provider);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workbuddy",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Native WorkBuddy account login and direct model provider for Pi",
   "type": "module",
   "license": "MIT",

package/src/client-identity.js

@@ -1,6 +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 EXTENSION_VERSION = "0.2.3";
 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

@@ -12,9 +12,7 @@ const deepseek = {
   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);
+add(["deepseek-v4.1-flash"], 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,

package/src/native-catalog-cache.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { BASE_URL, ORIGIN } from "./native-client.js";
+import { projectModels } from "./native-models.js";
+import { WorkbuddyError } from "./native-errors.js";
+
+/** Local cache validator only; never sent as an HTTP ETag. Tokens are not hashed or stored. */
+export function catalogCacheKey(credential) {
+  if (credential?.type !== "oauth" || credential.origin !== ORIGIN || !credential.userId) return undefined;
+  const parts = [ORIGIN, credential.userId, credential.domain || "www.workbuddy.ai", credential.enterpriseId || ""];
+  if (parts.some(value => typeof value !== "string" || value.length > 2048 || /[\r\n\0]/.test(value))) return undefined;
+  return "workbuddy-catalog-v1:" + createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}
+
+/** Reproject a public metadata whitelist, never cached auth, endpoints, headers or instructions. */
+export function restoreCatalog(entry, key) {
+  if (!key || entry?.etag !== key) return undefined;
+  if (!Array.isArray(entry.models) || entry.models.length > 2000) {
+    throw new WorkbuddyError("catalog-cache", "Cached WorkBuddy model metadata is invalid.");
+  }
+  const models = entry.models.filter(model => model?.provider === "workbuddy" && model.api === "openai-completions" &&
+    model.baseUrl === BASE_URL).map(model => ({
+    id: model.id, name: model.name,
+    maxInputTokens: model.contextWindow, maxOutputTokens: model.maxTokens,
+    supportsReasoning: model.reasoning === true,
+    supportsImages: Array.isArray(model.input) && model.input.includes("image"),
+    onlyReasoning: model.thinkingLevelMap?.off === null,
+    reasoning: { supportedEfforts: model.thinkingLevelMap && typeof model.thinkingLevelMap === "object" ?
+      Object.entries(model.thinkingLevelMap).filter(([level, value]) => level !== "off" && typeof value === "string").map(([level]) => level) : [] },
+    temperature: model.samplingParams?.temperature, top_p: model.samplingParams?.top_p,
+  }));
+  try { return projectModels({ models }); }
+  catch { throw new WorkbuddyError("catalog-cache", "Cached WorkBuddy model metadata is invalid."); }
+}
+
+export function catalogCacheEntry(models, key) {
+  // Models originate from projectModels(), which emits only bounded public metadata.
+  return { models, checkedAt: Date.now(), etag: key };
+}

package/src/native-errors.js

@@ -15,6 +15,7 @@ const REASONS = {
   "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-cache": "Cached model metadata was rejected; refresh to rebuild the catalog.",
   "catalog-filtered": "No model passed the provider's compatibility/security filters.",
 };
 export class WorkbuddyError extends Error {
@@ -31,11 +32,11 @@ export function describeFailure(error) {
   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 { status, businessCode, total, accepted, endpoint, disabled, toolLess, unavailable, invalid, duplicate, excluded } = 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 })) {
+    for (const [name, value] of Object.entries({ total, accepted, endpoint, disabled, toolLess, unavailable, invalid, duplicate, excluded })) {
       if (Number.isSafeInteger(value) && value >= 0) fields.push(name + "=" + value);
     }
     const hint = current.diagnosticCode === "http" && businessCode === 12403 ?

package/src/native-lifecycle.js

@@ -0,0 +1,52 @@
+import { describeFailure } from "./native-errors.js";
+
+function definition(model) {
+  return JSON.stringify([model?.provider, model?.id, model?.name, model?.contextWindow,
+    model?.maxTokens, model?.reasoning, model?.input, model?.thinkingLevelMap]);
+}
+
+export async function recoverSelectedModel(pi, provider, ctx, selected = ctx.model) {
+  // Never switch away from another provider, race a user selection, or alter a running turn.
+  if (!selected || selected.provider !== "workbuddy" || ctx.model !== selected || ctx.isIdle?.() === false) return;
+  let previousId = selected.id;
+  const placeholder = selected.name === "WorkBuddy Default (fallback)";
+  if (placeholder) {
+    // On resume Pi can replace a missing selection before session_start; the latest
+    // model-change record still identifies it. Never scan past a newer valid choice.
+    const previous = ctx.sessionManager?.getBranch?.().findLast(entry => entry.type === "model_change");
+    if (previous?.provider === "workbuddy" && typeof previous.modelId === "string") previousId = previous.modelId;
+  }
+  const id = /^deepseek-/i.test(previousId) && /-sg$/i.test(previousId) ? previousId.slice(0, -3) : previousId;
+  const replacement = provider.getModels().find(model => model.id === id) ??
+    (placeholder ? provider.getModels().find(model => model.id === selected.id) : undefined);
+  if (!replacement || definition(selected) === definition(replacement)) return;
+  if (await pi.setModel(replacement) === false) {
+    ctx.ui?.notify?.("WorkBuddy catalog is ready; select an available model with /model.", "warning");
+  } else if (id !== selected.id && replacement.id === id) {
+    ctx.ui?.notify?.("WorkBuddy restored the available model " + replacement.id + ". No chat request sent.", "info");
+  }
+}
+
+/** Embedded hosts can re-register providers without refreshing an already-seen provider ID. */
+export function registerNativeLifecycle(pi, provider) {
+  pi.on("session_start", async (_event, ctx) => {
+    const selected = ctx.model;
+    try {
+      if (!ctx.modelRegistry.hasConfiguredAuth(provider.getModels()[0])) return;
+      const result = await ctx.modelRegistry.refresh({
+        providers: ["workbuddy"], force: true, signal: ctx.signal,
+        // Honor PI_OFFLINE; otherwise inherit the registry's default network policy.
+        ...(process.env.PI_OFFLINE !== undefined ? { allowNetwork: false } : {}),
+      });
+      if (result.aborted) return;
+      if (result.errors.has("workbuddy")) {
+        ctx.ui?.notify?.("WorkBuddy catalog refresh failed: " + describeFailure(result.errors.get("workbuddy")) +
+          " Cached models, if available, were retained. No chat request sent.", "warning");
+      }
+      await recoverSelectedModel(pi, provider, ctx, selected);
+    } catch (error) {
+      ctx.ui?.notify?.("WorkBuddy startup recovery failed: " + describeFailure(error) +
+        " Use /workbuddy refresh to retry. No chat request sent.", "warning");
+    }
+  });
+}

package/src/native-models.js

@@ -14,10 +14,12 @@ export function projectModels(config) {
   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 };
+    disabled: 0, toolLess: 0, endpoint: 0, unavailable: 0, excluded: 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; }
+    const normalizedId = item.id.toLowerCase();
+    if (normalizedId.startsWith("deepseek-") && normalizedId.endsWith("-sg")) { counts.excluded++; continue; }
     if (seen.has(item.id)) { counts.duplicate++; continue; }
     if (item.disabled === true) { counts.disabled++; continue; }
     if (item.supportsToolCall === false) { counts.toolLess++; continue; }

package/src/native-provider.js

@@ -3,12 +3,16 @@ 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";
+import { catalogCacheKey, catalogCacheEntry, restoreCatalog } from "./native-catalog-cache.js";
+import { recoverSelectedModel } from "./native-lifecycle.js";
+import { EXTENSION_VERSION } from "./client-identity.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;
+  let catalogAccountKey;
   function prepareRequest(model, options = {}) {
     let outputLimit = resolveOutputLimit(model, options.maxTokens);
     const modelSampling = model.samplingParams ? { ...model.samplingParams } : undefined;
@@ -51,13 +55,33 @@ export function createWorkbuddyProvider({ api, client = createNativeClient(), fe
     getModels: () => models,
     getCatalogStatus: () => ({ source: catalogSource, lastError: lastCatalogError }),
     async refreshModels(context) {
+      const key = catalogCacheKey(context.credential);
+      if (catalogAccountKey && catalogAccountKey !== key) {
+        if (await context.publish({ update: () => {
+          models = fallbackModels(); catalogSource = "fallback"; catalogAccountKey = undefined; lastCatalogError = undefined;
+        } }) === false) return;
+      }
+      if (catalogSource === "fallback" && context.stored) {
+        try {
+          const restored = restoreCatalog(context.stored, key);
+          if (restored && await context.publish({ update: () => {
+            models = restored; catalogSource = "cache"; catalogAccountKey = key; lastCatalogError = undefined;
+          } }) === false) return;
+        } catch (error) {
+          // Invalid or fully filtered caches must not block a fresh authenticated catalog fetch.
+          lastCatalogError = describeFailure(error);
+        }
+      }
       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;
-        } });
+        // Pi owns persistence and generation checks. Persist only projected public metadata.
+        await context.publish({
+          ...(key ? { persist: catalogCacheEntry(next, key) } : {}),
+          update: () => {
+            models = next; catalogSource = "remote"; catalogAccountKey = key; lastCatalogError = undefined;
+          },
+        });
       } catch (error) {
         lastCatalogError = describeFailure(error);
         throw error;
@@ -83,11 +107,12 @@ export function registerNativeCommands(pi, provider) {
         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") +
+        ctx.ui.notify("WorkBuddy native " + EXTENSION_VERSION + " (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") {
+        const selected = ctx.model;
         try {
           if (!ctx.modelRegistry.hasConfiguredAuth(provider.getModels()[0])) {
             ctx.ui.notify("Sign in to WorkBuddy using /login first.", "warning"); return;
@@ -102,6 +127,7 @@ export function registerNativeCommands(pi, provider) {
               " Existing catalog retained. No chat request sent.", "warning");
             return;
           }
+          await recoverSelectedModel(pi, provider, ctx, selected);
           ctx.ui.notify("WorkBuddy catalog refreshed: " + provider.getModels().length + " models. Select with /model.", "info");
         } catch (error) {
           ctx.ui.notify("WorkBuddy catalog refresh failed: " +