pi-workbuddy 0.2.2 → 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,7 +50,7 @@ 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
 
@@ -58,7 +58,19 @@ There is no hardcoded allowlist of WorkBuddy model IDs. The provider fetches `/v
 
 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
 
@@ -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.2",
+  "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.2";
+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-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 {

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-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: " +