@jmcombs/pi-tavily-search 2.0.1 → 3.0.0

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.0.0`
 - A Tavily API key
+- Optional: the `op` (1Password) CLI for vault-backed onboarding and startup unlock
 
 ## Development
 

package/index.ts

@@ -2,16 +2,23 @@
  * @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. The Tavily API key is resolved from (in order):
- *   1. `AuthStorage` under the "tavily" key (`~/.pi/agent/auth.json`)
- *   2. The `TAVILY_API_KEY` environment variable
+ * 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.
  *
- * See README.md for configuration details and recommended secret-storage
- * patterns (env var, plain auth.json, or shell-resolved 1Password / Keychain).
+ * 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 { 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";
 
@@ -48,16 +55,6 @@ interface TavilySearchResponse {
 
 // ── Helpers ────────────────────────────────────────────────────────────
 
-const MISSING_KEY_MESSAGE = [
-  "Error: No Tavily API key configured.",
-  "",
-  "Configure one of the following:",
-  "  • Environment variable: export TAVILY_API_KEY=<your-key>",
-  '  • ~/.pi/agent/auth.json: { "tavily": { "type": "api_key", "key": "<your-key>" } }',
-  '  • Shell-resolved: { "tavily": { "type": "api_key", "key": "!security find-generic-password -ws tavily" } }',
-  '  • 1Password: { "tavily": { "type": "api_key", "key": "!op read \'op://Personal/tavily/credential\'" } }',
-].join("\n");
-
 function formatResults(data: TavilySearchResponse, query: string): string {
   const results = data.results ?? [];
   if (results.length === 0) {
@@ -75,7 +72,15 @@ function formatResults(data: TavilySearchResponse, query: string): string {
 // ── Extension factory ──────────────────────────────────────────────────
 
 export default function (pi: ExtensionAPI): void {
-  const authStorage = AuthStorage.create();
+  // 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_setup", {
+    description: "Set up or update your Tavily API key (never shown to the agent).",
+    handler: async (_args, ctx) => {
+      const result = await onboardSecret(ctx, { name: "tavily", label: "Tavily" });
+      ctx.ui.notify(result.message, result.ok ? "info" : "warning");
+    },
+  });
 
   pi.registerTool({
     name: "tavily_search",
@@ -83,13 +88,21 @@ export default function (pi: ExtensionAPI): void {
     description:
       "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) {
-      const apiKey = (await authStorage.getApiKey("tavily")) ?? process.env.TAVILY_API_KEY;
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      let apiKey = (await resolveSecret("tavily")) ?? process.env.TAVILY_API_KEY;
+
+      // Auto-onboard: run the availability-branched onboarding flow if no key is
+      // configured, then re-resolve (env fallback preserved).
+      if (!apiKey) {
+        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: MISSING_KEY_MESSAGE }],
+          content: [{ type: "text", text: "Search cancelled: no Tavily API key provided." }],
           details: { error: "missing_api_key" },
-          isError: true,
         };
       }
 
@@ -116,7 +129,6 @@ export default function (pi: ExtensionAPI): void {
               },
             ],
             details: { status: response.status, body: errorText },
-            isError: true,
           };
         }
 
@@ -130,7 +142,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.0.1",
+  "version": "3.0.0",
   "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": {
@@ -38,6 +38,9 @@
   "engines": {
     "node": ">=22.0.0"
   },
+  "dependencies": {
+    "@jmcombs/pi-1password": "^1.0.2 || ^2.0.0"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"