@jmcombs/pi-tavily-search 2.1.0 → 3.0.1

package/README.md

@@ -3,6 +3,56 @@
 A [Pi coding agent](https://pi.dev) extension that adds real-time web search via the
 [Tavily API](https://tavily.com).
 
+## Breaking changes in v3.0.0
+
+- **`AuthStorage` is gone.** Pi 0.80.8 removed the `AuthStorage` API this extension used
+  to store and read its API key. Credentials now resolve through the
+  [`@jmcombs/pi-1password`](https://www.npmjs.com/package/@jmcombs/pi-1password)
+  **credential API**, which this package now depends on directly and **installs
+  automatically** — no separate install step.
+- **Availability-branched onboarding.** When the `op` CLI is installed and an account is
+  configured, setup opens a 1Password **vault → item → field picker**; when `op` is
+  unavailable it falls back to **masked manual key entry**.
+- **Existing keys keep working.** Any Tavily key already in `~/.pi/agent/auth.json` — a
+  literal value or an `!op read` reference — resolves unchanged. No migration action is
+  required.
+
+## What's New — 1Password credential integration
+
+Tavily search now handles your API key through the
+[`@jmcombs/pi-1password`](https://www.npmjs.com/package/@jmcombs/pi-1password) credential
+API, which installs automatically as a dependency. What this means for you:
+
+- **Onboarding branches on 1Password availability.** If the `op` CLI is installed and an
+  account is configured, `/tavily_setup` opens a live **vault → item → field
+  picker** (or lets you type an `op://…` reference) and stores it as a `!op read '…'`
+  entry that resolves fresh on every use. If `op` is not available, it falls back to
+  **manual API-key entry** and nudges you to enable the 1Password extension for vault
+  integration.
+- **The `TAVILY_API_KEY` environment variable still works.** It remains a supported
+  fallback, resolved after the stored `tavily` key.
+- **Existing keys keep working.** Any Tavily key already in `~/.pi/agent/auth.json` — a
+  literal key or an `!op read` reference — continues to resolve unchanged. No migration
+  action is required.
+- **The key is never exposed to the model.** Entry happens entirely in the TUI, and only
+  the resolved value is used to call the Tavily API.
+- **Enable 1Password for vault integration and startup unlock.** Install and enable the
+  [`@jmcombs/pi-1password`](https://www.npmjs.com/package/@jmcombs/pi-1password) extension:
+  it makes the vault picker available during onboarding and runs a one-time `op read` at
+  session startup, so the biometric unlock prompt lands once.
+
+```mermaid
+flowchart TD
+    A["/tavily_setup or first tool use"] --> B{"is1PasswordAvailable()<br/>(op installed AND configured)"}
+    B -- "Yes" --> C["Live vault → item → field picker<br/>or manual op:// reference"]
+    C --> D["Store !op read 'op://…' entry"]
+    B -- "No" --> E["Manual API-key entry<br/>+ nudge to enable 1Password"]
+    E --> F["Store literal api_key entry"]
+    D --> G["resolveSecret('tavily') ?? TAVILY_API_KEY<br/>resolves fresh on each tool call"]
+    F --> G
+    G --> H["api_key → Tavily API<br/>(never shown to the LLM)"]
+```
+
 ## Install
 
 ```bash
@@ -22,34 +72,48 @@ available) to get one, then configure it using one of the methods below.
   five formatted results (title, URL, content) plus the raw API response under
   `details.raw`. The tool is callable by the LLM whenever it needs current
   information from the public web.
+- **Command**: `/tavily_setup` — runs the `@jmcombs/pi-1password` onboarding flow
+  to save (or update) your Tavily key. The input is never visible to the LLM.
 
 ## Configuration
 
-You must configure a Tavily API key. Pi resolves the key in this order:
+The `tavily_search` tool resolves the key in this order:
 
-1. `AuthStorage` under the `tavily` key (`~/.pi/agent/auth.json`) — **recommended**.
-2. The `TAVILY_API_KEY` environment variable.
+1. `resolveSecret("tavily")` from `@jmcombs/pi-1password` — reads `~/.pi/agent/auth.json`
+   fresh on each call (a literal key or an `!op read` reference). **Recommended.**
+2. The `TAVILY_API_KEY` environment variable — fallback.
 
-### Option 1 — `~/.pi/agent/auth.json` (recommended)
+If neither is set, the tool automatically runs onboarding (the availability branch above)
+on first use, then re-resolves — preserving the "prompt on first use" experience.
 
-#### Plain key
+### Option 1 — `/tavily_setup` (recommended)
 
-```json
-{
-  "tavily": {
-    "type": "api_key",
-    "key": "tvly-..."
-  }
-}
+Run the command and follow the flow:
+
+```
+/tavily_setup
 ```
 
-#### Shell-resolved key (macOS Keychain)
+- When the `op` CLI is available, pick your key from the live vault picker (or paste an
+  `op://vault/item/field` reference); it is stored as a `!op read '…'` entry that resolves
+  fresh on every use.
+- When `op` is not available, enter the key on a masked prompt; it is stored as a literal
+  `api_key` entry.
+
+Either way the value is written to `~/.pi/agent/auth.json` (`0600`) and never shown to the
+model.
+
+### Option 2 — edit `~/.pi/agent/auth.json` directly
+
+The stored entry is provider-shaped under the `tavily` key. Any of these resolve:
+
+#### Plain key
 
 ```json
 {
   "tavily": {
     "type": "api_key",
-    "key": "!security find-generic-password -ws tavily"
+    "key": "tvly-..."
   }
 }
 ```
@@ -65,13 +129,13 @@ You must configure a Tavily API key. Pi resolves the key in this order:
 }
 ```
 
-#### Shell-resolved key (`pass`)
+#### Shell-resolved key (macOS Keychain / `pass`)
 
 ```json
 {
   "tavily": {
     "type": "api_key",
-    "key": "!pass show tavily"
+    "key": "!security find-generic-password -ws tavily"
   }
 }
 ```
@@ -79,7 +143,7 @@ You must configure a Tavily API key. Pi resolves the key in this order:
 The `!`-prefixed value is executed by your shell at lookup time, so no secret is
 ever stored on disk in plaintext.
 
-### Option 2 — environment variable
+### Option 3 — environment variable
 
 ```bash
 export TAVILY_API_KEY="tvly-..."
@@ -98,9 +162,10 @@ export TAVILY_API_KEY="tvly-..."
 
 ## Requirements
 
-- Pi `>= 0.72.0` (uses `AuthStorage` and `ExtensionAPI`)
-- Node `>= 20.6.0`
+- Pi `>= 0.80.8` (credentials via the `@jmcombs/pi-1password` API and `ExtensionAPI`)
+- Node `>= 22.19.0`
 - A Tavily API key
+- Optional: the `op` (1Password) CLI for vault-backed onboarding and startup unlock
 
 ## Development
 

package/index.ts

@@ -2,17 +2,24 @@
  * @jmcombs/pi-tavily-search — Real-time web search for the Pi coding agent.
  *
  * Registers a `tavily_search` tool that the LLM can call to perform a Tavily
- * web search. If no Tavily API key is configured, the tool prompts the user
- * interactively via the TUI (never leaking the key into the agent's context).
- * The key can also be set manually by running `/tavily_authenticate`.
+ * web search. Credentials are handled entirely through the imported
+ * `@jmcombs/pi-1password` credential API (`resolveSecret` / `onboardSecret`),
+ * so the key is never leaked into the agent's context.
  *
- * Supported configuration (if not using interactive prompt):
- *    1. `AuthStorage` under the "tavily" key (`~/.pi/agent/auth.json`)
- *    2. The `TAVILY_API_KEY` environment variable
+ * Credential handling:
+ *    1. `resolveSecret("tavily")` reads `~/.pi/agent/auth.json` and resolves the
+ *       stored entry (literal key or `!op read 'op://…'` reference) fresh on each
+ *       use; the `TAVILY_API_KEY` environment variable is the fallback.
+ *    2. If nothing is stored, the tool auto-invokes `onboardSecret`, which branches
+ *       on 1Password availability — the live vault picker when `op` is configured,
+ *       manual API-key entry otherwise — then re-resolves.
+ *    3. `/tavily_setup` runs the same onboarding flow on demand.
  */
 
-import { AuthStorage, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type, type Static } from "typebox";
+import type { JsonObject, JsonValue } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { onboardSecret, resolveSecret } from "@jmcombs/pi-1password";
+import { type Static, Type } from "typebox";
 
 const TAVILY_SEARCH_ENDPOINT = "https://api.tavily.com/search";
 
@@ -49,6 +56,62 @@ interface TavilySearchResponse {
 
 // ── Helpers ────────────────────────────────────────────────────────────
 
+export function isJsonValue(value: unknown): value is JsonValue {
+  if (value === null) return true;
+  switch (typeof value) {
+    case "boolean":
+    case "number":
+    case "string":
+      return true;
+    case "object": {
+      if (Array.isArray(value)) return value.every(isJsonValue);
+      const nested: unknown[] = Object.values(value);
+      return nested.every(isJsonValue);
+    }
+    default:
+      return false;
+  }
+}
+
+function asJsonObject(value: JsonValue): JsonObject | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  return value as JsonObject;
+}
+
+function toTavilySearchResponse(data: JsonValue): TavilySearchResponse {
+  const obj = asJsonObject(data);
+  if (!obj) return {};
+  const out: TavilySearchResponse = {};
+  if (typeof obj.query === "string") out.query = obj.query;
+  if (typeof obj.answer === "string") out.answer = obj.answer;
+  if (Array.isArray(obj.results)) {
+    const results: TavilySearchResult[] = [];
+    for (const item of obj.results) {
+      const entry = asJsonObject(item);
+      if (!entry) continue;
+      if (
+        typeof entry.title !== "string" ||
+        typeof entry.url !== "string" ||
+        typeof entry.content !== "string"
+      ) {
+        continue;
+      }
+      const result: TavilySearchResult = {
+        title: entry.title,
+        url: entry.url,
+        content: entry.content,
+      };
+      if (typeof entry.score === "number") result.score = entry.score;
+      if (typeof entry.raw_content === "string" || entry.raw_content === null) {
+        result.raw_content = entry.raw_content;
+      }
+      results.push(result);
+    }
+    out.results = results;
+  }
+  return out;
+}
+
 function formatResults(data: TavilySearchResponse, query: string): string {
   const results = data.results ?? [];
   if (results.length === 0) {
@@ -66,20 +129,13 @@ function formatResults(data: TavilySearchResponse, query: string): string {
 // ── Extension factory ──────────────────────────────────────────────────
 
 export default function (pi: ExtensionAPI): void {
-  const authStorage = AuthStorage.create();
-
-  // Register /tavily_authenticate command for manual key entry.
+  // Register /tavily_setup command for onboarding the key on demand.
   // The input is captured by the TUI and never enters the LLM's context.
-  pi.registerCommand("tavily_authenticate", {
-    description: "Securely save your Tavily API key (input never visible to LLM).",
+  pi.registerCommand("tavily_setup", {
+    description: "Set up or update your Tavily API key (never shown to the agent).",
     handler: async (_args, ctx) => {
-      const apiKey = await ctx.ui.input("Enter your Tavily API key:");
-      if (apiKey) {
-        authStorage.set("tavily", { type: "api_key" as const, key: apiKey });
-        ctx.ui.notify("Tavily API key saved successfully.", "info");
-      } else {
-        ctx.ui.notify("Authentication cancelled.", "warning");
-      }
+      const result = await onboardSecret(ctx, { name: "tavily", label: "Tavily" });
+      ctx.ui.notify(result.message, result.ok ? "info" : "warning");
     },
   });
 
@@ -90,33 +146,22 @@ export default function (pi: ExtensionAPI): void {
       "Performs a web search using the Tavily API to get real-time information from the internet.",
     parameters: tavilySearchSchema,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      let apiKey = (await authStorage.getApiKey("tavily")) ?? process.env.TAVILY_API_KEY;
+      let apiKey = (await resolveSecret("tavily")) ?? process.env.TAVILY_API_KEY;
 
-      // Auto-authenticate: prompt for key if none is configured
+      // Auto-onboard: run the availability-branched onboarding flow if no key is
+      // configured, then re-resolve (env fallback preserved).
       if (!apiKey) {
-        const newKey = await ctx.ui.input("Enter your Tavily API key:");
-        if (!newKey) {
-          return {
-            content: [{ type: "text", text: "Search cancelled: no Tavily API key provided." }],
-            details: { error: "missing_api_key" },
-            isError: true,
-          };
-        }
-        authStorage.set("tavily", { type: "api_key" as const, key: newKey });
-        apiKey = await authStorage.getApiKey("tavily");
-        if (!apiKey) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: "Failed to resolve Tavily API key. Check your shell configuration.",
-              },
-            ],
-            details: { error: "missing_api_key" },
-            isError: true,
-          };
+        const r = await onboardSecret(ctx, { name: "tavily", label: "Tavily" });
+        if (r.ok) {
+          apiKey = (await resolveSecret("tavily")) ?? process.env.TAVILY_API_KEY;
         }
       }
+      if (!apiKey) {
+        return {
+          content: [{ type: "text", text: "Search cancelled: no Tavily API key provided." }],
+          details: { error: "missing_api_key" },
+        };
+      }
 
       try {
         const response = await fetch(TAVILY_SEARCH_ENDPOINT, {
@@ -141,13 +186,21 @@ export default function (pi: ExtensionAPI): void {
               },
             ],
             details: { status: response.status, body: errorText },
-            isError: true,
           };
         }
 
-        const data = (await response.json()) as TavilySearchResponse;
+        const parsed: unknown = await response.json();
+        if (!isJsonValue(parsed)) {
+          return {
+            content: [{ type: "text", text: "Tavily API returned invalid JSON." }],
+            details: { error: "invalid_json" },
+          };
+        }
+        const data = parsed;
         return {
-          content: [{ type: "text", text: formatResults(data, params.query) }],
+          content: [
+            { type: "text", text: formatResults(toTavilySearchResponse(data), params.query) },
+          ],
           details: { raw: data },
         };
       } catch (error) {
@@ -155,7 +208,6 @@ export default function (pi: ExtensionAPI): void {
         return {
           content: [{ type: "text", text: `Error performing Tavily search: ${message}` }],
           details: { error: message },
-          isError: true,
         };
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmcombs/pi-tavily-search",
-  "version": "2.1.0",
+  "version": "3.0.1",
   "description": "Pi extension that performs real-time web search via the Tavily API.",
   "homepage": "https://github.com/jmcombs/pi-extensions/tree/main/packages/tavily-search",
   "repository": {
@@ -36,7 +36,10 @@
     "image": "https://raw.githubusercontent.com/jmcombs/pi-extensions/main/assets/tavily-search/preview.png"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "@jmcombs/pi-1password": "^1.0.2 || ^2.0.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",