pi-web-providers 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +69 -40
  2. package/dist/index.js +1010 -147
  3. package/package.json +7 -4
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # 🌍 pi-web-providers
2
2
 
3
- A *meta* web extension for [pi](https://pi.dev).
3
+ A _meta_ web extension for [pi](https://pi.dev).
4
4
 
5
5
  ## Why?
6
6
 
@@ -18,16 +18,22 @@ only the tools that make sense. If your active provider offers search and
18
18
  content extraction but not deep research, the agent never sees a research tool.
19
19
  Switch to a provider that supports it and the tool appears automatically.
20
20
 
21
+ The extension also separates **available tools** from the **active tool set**.
22
+ When a session starts, it can add every available managed tool. Before each
23
+ agent run, it removes tools that are no longer available but keeps any managed
24
+ tools that you explicitly removed from the active set disabled. That keeps the
25
+ tool prompt aligned with the tools that the agent can actually call.
26
+
21
27
  ## ✨ Features
22
28
 
23
29
  - **Provider-driven tool surface** — tools are injected based on what the active
24
30
  provider actually supports, not a fixed list
25
- - **Five providers**: Codex, Exa, Gemini, Parallel, Valyu — each with its own
26
- SDK, strengths, and capability set
31
+ - **Six providers**: Claude, Codex, Exa, Gemini, Parallel, Valyu — each with
32
+ its own SDK, strengths, and capability set
27
33
  - **One config command** (`/web-providers`) with a TUI that adapts to the
28
34
  selected provider
29
- - **Transparent fallback** — if no provider is explicitly enabled, the extension
30
- walks the list alphabetically and picks the first one that is available
35
+ - **Transparent fallback** — search falls back to Codex when no provider is
36
+ explicitly enabled and the local CLI is installed and authenticated
31
37
  - **Per-provider tool toggles** — disable individual capabilities you don't need
32
38
  without switching providers
33
39
  - **Truncated output with temp-file spillover** for large results
@@ -51,8 +57,9 @@ This command edits a single global config file:
51
57
 
52
58
  The flow is provider-first: pick the active provider, then configure only that
53
59
  provider's tool toggles and settings. Each provider view surfaces the knobs that
54
- actually apply—Codex shows reasoning-effort and web-search-mode toggles; Exa
55
- shows search type and text-content flags; and so on.
60
+ actually apply—Claude shows model/effort/turns settings; Codex shows
61
+ reasoning-effort and web-search-mode toggles; Exa shows search type and
62
+ text-content flags; and so on.
56
63
 
57
64
  ## 🔧 Tools
58
65
 
@@ -62,56 +69,64 @@ corresponding tool is never exposed to the agent.
62
69
 
63
70
  ### `web_search`
64
71
 
65
- Search the web and return titles, URLs, and snippets.
72
+ Find likely sources on the public web and return titles, URLs, and snippets.
66
73
 
67
- | Parameter | Type | Default | Description |
68
- |-----------|------|---------|-------------|
69
- | `query` | string | required | What to search for |
70
- | `maxResults` | integer | `5` | Result count, clamped to `1–20` |
71
- | `provider` | string | auto | Optional override: `codex`, `exa`, `gemini`, `parallel`, or `valyu` |
74
+ | Parameter | Type | Default | Description |
75
+ | ------------ | ------- | -------- | ----------------------------------------------------------------------------- |
76
+ | `query` | string | required | What to search for |
77
+ | `maxResults` | integer | `5` | Result count, clamped to `1–20` |
78
+ | `provider` | string | auto | Optional override: `claude`, `codex`, `exa`, `gemini`, `parallel`, or `valyu` |
72
79
 
73
80
  ### `web_contents`
74
81
 
75
- Extract contents for one or more URLs.
82
+ Read and extract the main contents of one or more web pages.
76
83
 
77
- | Parameter | Type | Default | Description |
78
- |-----------|------|---------|-------------|
79
- | `urls` | string[] | required | One or more URLs to extract |
80
- | `options` | object | — | Provider-specific extraction options |
81
- | `provider` | string | auto | Optional override among providers that support contents |
84
+ | Parameter | Type | Default | Description |
85
+ | ---------- | -------- | -------- | ------------------------------------------------------- |
86
+ | `urls` | string[] | required | One or more URLs to extract |
87
+ | `options` | object | — | Provider-specific extraction options |
88
+ | `provider` | string | auto | Optional override among providers that support contents |
82
89
 
83
90
  ### `web_answer`
84
91
 
85
- Get a provider-generated answer grounded in search results.
92
+ Answer a question using web-grounded evidence.
86
93
 
87
- | Parameter | Type | Default | Description |
88
- |-----------|------|---------|-------------|
89
- | `query` | string | required | Question to answer |
90
- | `options` | object | — | Provider-specific answer options |
91
- | `provider` | string | auto | Optional override among providers that support answers |
94
+ | Parameter | Type | Default | Description |
95
+ | ---------- | ------ | -------- | ------------------------------------------------------ |
96
+ | `query` | string | required | Question to answer |
97
+ | `options` | object | — | Provider-specific answer options |
98
+ | `provider` | string | auto | Optional override among providers that support answers |
92
99
 
93
100
  ### `web_research`
94
101
 
95
- Run a longer-form research task.
102
+ Investigate a topic across web sources and produce a longer report.
96
103
 
97
- | Parameter | Type | Default | Description |
98
- |-----------|------|---------|-------------|
99
- | `input` | string | required | Research brief or question |
100
- | `options` | object | — | Provider-specific research options |
101
- | `provider` | string | auto | Optional override among providers that support research |
104
+ | Parameter | Type | Default | Description |
105
+ | ---------- | ------ | -------- | ------------------------------------------------------- |
106
+ | `input` | string | required | Research brief or question |
107
+ | `options` | object | — | Provider-specific research options |
108
+ | `provider` | string | auto | Optional override among providers that support research |
102
109
 
103
110
  ## 🔌 Providers
104
111
 
105
112
  Every provider is a thin adapter around an official SDK. The table below
106
113
  summarises which capabilities each provider exposes:
107
114
 
108
- | Provider | search | contents | answer | research | Auth |
109
- |----------|:------:|:--------:|:------:|:--------:|------|
110
- | **Codex** | ✓ | | | | Local Codex CLI auth |
111
- | **Exa** | ✓ | ✓ | ✓ | ✓ | `EXA_API_KEY` |
112
- | **Gemini** | ✓ | | ✓ | ✓ | `GOOGLE_API_KEY` |
113
- | **Parallel** | ✓ | ✓ | | | `PARALLEL_API_KEY` |
114
- | **Valyu** | ✓ | ✓ | ✓ | ✓ | `VALYU_API_KEY` |
115
+ | Provider | search | contents | answer | research | Auth |
116
+ | ------------ | :----: | :------: | :----: | :------: | ---------------------- |
117
+ | **Claude** | ✓ | | ✓ | | Local Claude Code auth |
118
+ | **Codex** | ✓ | | | | Local Codex CLI auth |
119
+ | **Exa** | ✓ | ✓ | ✓ | ✓ | `EXA_API_KEY` |
120
+ | **Gemini** | ✓ | | ✓ | ✓ | `GOOGLE_API_KEY` |
121
+ | **Parallel** | ✓ | ✓ | | | `PARALLEL_API_KEY` |
122
+ | **Valyu** | ✓ | ✓ | ✓ | ✓ | `VALYU_API_KEY` |
123
+
124
+ ### Claude
125
+
126
+ - SDK: `@anthropic-ai/claude-agent-sdk`
127
+ - Uses Claude Code's built-in `WebSearch` and `WebFetch` tools behind a
128
+ structured JSON adapter
129
+ - Great for search plus grounded answers if you already use Claude Code locally
115
130
 
116
131
  ### Codex
117
132
 
@@ -148,8 +163,15 @@ summarises which capabilities each provider exposes:
148
163
  for the selected provider and `enabled: false` for the others
149
164
  - Each provider can also enable or disable its individual tools through a `tools`
150
165
  block
151
- - If a config has no explicitly enabled provider, the extension falls back to the
152
- first available provider alphabetically
166
+ - Managed tools are registered from available provider capabilities, but the
167
+ active tool set can still be narrower if you removed a tool from the session
168
+ - If no provider is explicitly enabled for search, the extension falls back to
169
+ Codex when the local CLI is installed and authenticated, unless Codex was
170
+ explicitly configured as disabled
171
+ - Tools stay inactive when no provider is available for their capability, so
172
+ they are not injected into the LLM prompt
173
+ - Before each agent run, the extension removes newly unavailable managed tools
174
+ and keeps manually pruned managed tools inactive instead of re-adding them
153
175
  - Secret-like values can be:
154
176
  - literal strings
155
177
  - environment variable names such as `EXA_API_KEY`
@@ -161,6 +183,13 @@ Example:
161
183
  {
162
184
  "version": 1,
163
185
  "providers": {
186
+ "claude": {
187
+ "enabled": false,
188
+ "tools": {
189
+ "search": true,
190
+ "answer": true
191
+ }
192
+ },
164
193
  "codex": {
165
194
  "enabled": true,
166
195
  "tools": {