@howaboua/pi-codex-web-run 0.0.8 → 0.0.10

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # @howaboua/pi-codex-web-run
2
2
 
3
+ ## 0.0.10
4
+
5
+ - Added an extension API for Web Run search and navigation, using the existing provider and login without adding conversation messages.
6
+
7
+ ## 0.0.9
8
+
9
+ - - Keep provider bookkeeping out of structured search results while preserving result references and content.
10
+ - Report unreadable responses and invalid tool configuration without parser or filesystem diagnostics.
11
+ - GPT mode uses note-style search-reference guidance.
12
+
3
13
  ## 0.0.8
4
14
 
5
15
  - - Added compact tool guidance for PCC GPT prompt mode. Other modes are unchanged.
@@ -22,7 +32,6 @@
22
32
  ## 0.0.4
23
33
 
24
34
  - GPT-6 Sol and Luna now share Astra's Codex support.
25
-
26
35
  - Removed `/terra`; use `/luna` instead.
27
36
  - Added Responses Lite, non-destructive reasoning changes and terse context guidance for GPT-6 Sol and Luna.
28
37
  - Image descriptions now use GPT-6 Luna directly instead of preferring older mini models.
@@ -40,6 +49,5 @@
40
49
  ## 0.0.1
41
50
 
42
51
  - Initial release of Web Run for Codex web search and page navigation in normal Pi, Code Mode, and Notebook Mode.
43
-
44
52
  - Search the web or images, open results, follow links, and find text while retaining reusable source references.
45
53
  - Use stock, renamed, or proxied Codex providers through a small JSON route file.
package/README.md CHANGED
@@ -22,12 +22,38 @@ For a proxy that renames Codex providers or models, create `pi-codex-tools.json`
22
22
 
23
23
  ```json
24
24
  {
25
- "providers": {
26
- "company-codex": {
27
- "gpt-6-luna": "company-luna"
28
- }
29
- }
25
+ "providers": {
26
+ "company-codex": {
27
+ "gpt-6-luna": "company-luna"
28
+ }
29
+ }
30
30
  }
31
31
  ```
32
32
 
33
33
  Each provider key identifies a Codex endpoint route. Its object maps the tool's canonical model names to that provider's aliases. Use an empty object when the provider renames no models.
34
+
35
+ ## Extension API
36
+
37
+ Other extensions can discover optional search and navigation through Pi's event bus on each call:
38
+
39
+ ```ts
40
+ let service: CodexWebRunService | undefined;
41
+ pi.events.emit("@howaboua/pi-codex-web-run.service/v1", {
42
+ use(candidate: CodexWebRunService) {
43
+ service = candidate;
44
+ },
45
+ });
46
+ if (!service)
47
+ throw new Error("Web search is unavailable. Install pi-codex-web-run.");
48
+ const result = await service.run(
49
+ ctx,
50
+ { search_query: [{ q: "Pi extensions" }] },
51
+ signal,
52
+ );
53
+ ```
54
+
55
+ `CodexWebRunService` is a type export from this package. Discovery is synchronous and works in either extension load order after initialisation. It does not check account access or start a request.
56
+
57
+ `run` accepts the existing `web_run` arguments, including `open`, `click` and `find`. It returns `{ text, details }` with the same source URLs and reusable result references as the tool. It uses the tool's configured provider and existing login without switching accounts. Errors reject the promise. Pass an `AbortSignal` to cancel work. Session shutdown cancels outstanding requests and invalidates retained service handles.
58
+
59
+ Results go only to the caller. The API does not add messages to Pi's conversation or change the model's tools.
package/biome.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "$schema": "https://biomejs.dev/schemas/2.5.15/schema.json",
2
+ "$schema": "https://biomejs.dev/schemas/2.6.3/schema.json",
3
3
  "vcs": {
4
4
  "enabled": true,
5
5
  "clientKind": "git",
package/index.ts CHANGED
@@ -2,22 +2,31 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
2
  import registerPackageChangelog from "./changelog.js";
3
3
  import { webRunCodeModeResult } from "./src/code-mode.js";
4
4
  import { resolveHostedCodexToolProvider } from "./src/codex-runtime/policy.js";
5
+ import type { WebSearchToolOptions } from "./src/contract.js";
6
+ import { registerCodexWebRunService } from "./src/service.js";
5
7
  import { createWebSearchTool } from "./src/tool.js";
6
8
 
7
9
  const CODE_MODE_PACKAGE = "@howaboua/pi-codex-conversion";
8
10
  const CODE_MODE_MODULE = CODE_MODE_PACKAGE + "/code-mode";
9
11
 
10
12
  export { webRunCodeModeResult } from "./src/code-mode.js";
13
+ export type { WebRunExecutionResult } from "./src/execute.js";
11
14
  export { executeCodexWebSearch } from "./src/execute.js";
15
+ export {
16
+ CODEX_WEB_RUN_SERVICE,
17
+ type CodexWebRunService,
18
+ type CodexWebRunServiceRequest,
19
+ } from "./src/service.js";
12
20
  export { createWebSearchTool } from "./src/tool.js";
13
21
 
14
22
  export default async function webRunExtension(pi: ExtensionAPI): Promise<void> {
15
23
  registerPackageChangelog(pi);
16
- const tool = createWebSearchTool("web_run", {
24
+ const options: WebSearchToolOptions = {
17
25
  allowCodexProviderFallback: true,
18
26
  resolveProvider: (ctx) => resolveHostedCodexToolProvider(pi, ctx),
19
27
  promptSnippet: false,
20
- });
28
+ };
29
+ const tool = createWebSearchTool("web_run", options);
21
30
  pi.registerTool(tool);
22
31
  let gpt = false;
23
32
  let registration: Awaited<ReturnType<typeof registerWebRunInCodeMode>>;
@@ -37,7 +46,7 @@ export default async function webRunExtension(pi: ExtensionAPI): Promise<void> {
37
46
  : ordinary.description;
38
47
  if (active)
39
48
  tool.promptGuidelines = [
40
- "web_run: Calls: returned turn refs. Final citations: Markdown result URLs, never refs or cite….",
49
+ "web_run: calls=returned turn refs; final citations=Markdown result URLs; never refs/cite…",
41
50
  ];
42
51
  else if (ordinary.guidelines)
43
52
  tool.promptGuidelines = ordinary.guidelines;
@@ -61,6 +70,7 @@ export default async function webRunExtension(pi: ExtensionAPI): Promise<void> {
61
70
  throw error;
62
71
  }
63
72
  registration = await registerWebRunInCodeMode(pi, tool, () => gpt);
73
+ registerCodexWebRunService(pi, options);
64
74
  pi.on("session_shutdown", () => registration?.unregister());
65
75
  }
66
76
 
@@ -75,7 +85,7 @@ async function registerWebRunInCodeMode(
75
85
  return registerCodeModeExtensionTools(pi, () => [
76
86
  adaptToolForCodeMode(tool, {
77
87
  usage: gpt()
78
- ? 'await tools.web__run({search_query?:[{q:string,recency?:number,domains?:string[]}],image_query?:[{q:string}],open?:[{ref_id:string,lineno?:number}],click?:[{ref_id:string,id:number}],find?:[{ref_id:string,pattern:string}],response_length?:"short"|"medium"|"long"}) // calls: returned ref_ids; final citations: Markdown result URLs, never refs/cite markers'
88
+ ? 'await tools.web__run({search_query?:[{q:string,recency?:number,domains?:string[]}],image_query?:[{q:string}],open?:[{ref_id:string,lineno?:number}],click?:[{ref_id:string,id:number}],find?:[{ref_id:string,pattern:string}],response_length?:"short"|"medium"|"long"}) // calls=returned ref_ids; final citations=Markdown result URLs; never refs/cite markers'
79
89
  : 'await tools.web__run({search_query?:[{q:string,recency?:number,domains?:string[]}],image_query?:[{q:string}],open?:[{ref_id:string,lineno?:number}],click?:[{ref_id:string,id:number}],find?:[{ref_id:string,pattern:string}],response_length?:"short"|"medium"|"long"}) // calls use returned ref_ids; final answers use Markdown result URLs, never refs/cite markers',
80
90
  promptMetadata: false,
81
91
  toolName: { namespace: "web", name: "run" },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@howaboua/pi-codex-web-run",
3
- "version": "0.0.8",
3
+ "version": "0.0.10",
4
4
  "description": "Codex web search and navigation for Pi, Code Mode and Notebook Mode.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -44,23 +44,23 @@
44
44
  },
45
45
  "dependencies": {
46
46
  "proxy-from-env": "2.1.0",
47
- "undici": "8.12.2"
47
+ "undici": "8.12.3"
48
48
  },
49
49
  "peerDependencies": {
50
50
  "@earendil-works/pi-coding-agent": ">=1.0.0",
51
51
  "@earendil-works/pi-tui": ">=1.0.0",
52
52
  "typebox": "*",
53
- "@howaboua/pi-codex-conversion": ">=4.0.2"
53
+ "@howaboua/pi-codex-conversion": ">=4.0.6"
54
54
  },
55
55
  "devDependencies": {
56
- "@biomejs/biome": "^2.5.15",
57
- "@earendil-works/pi-coding-agent": "1.3.0",
58
- "@earendil-works/pi-tui": "1.3.0",
56
+ "@biomejs/biome": "^2.6.3",
57
+ "@earendil-works/pi-coding-agent": "1.4.0",
58
+ "@earendil-works/pi-tui": "1.4.0",
59
59
  "@types/node": "^26.6.5",
60
60
  "tsx": "^4.23.15",
61
- "typebox": "1.3.37",
61
+ "typebox": "1.4.3",
62
62
  "typescript": "^7.0.2",
63
- "@howaboua/pi-codex-conversion": "4.0.2"
63
+ "@howaboua/pi-codex-conversion": "4.0.6"
64
64
  },
65
65
  "pi": {
66
66
  "extensions": [
@@ -70,16 +70,15 @@ export function readCodexToolRouteConfig(
70
70
  error.code === "ENOENT"
71
71
  )
72
72
  return { providers: Object.create(null) };
73
- throw error;
73
+ throw new Error(
74
+ "Tool configuration could not be read. Ask the user to check " + path,
75
+ );
74
76
  }
75
77
  try {
76
78
  return normalizeCodexToolRouteConfig(JSON.parse(source));
77
- } catch (error) {
79
+ } catch {
78
80
  throw new Error(
79
- "Invalid pi-codex-tools config at " +
80
- path +
81
- ": " +
82
- (error instanceof Error ? error.message : String(error)),
81
+ "Tool configuration is invalid. Ask the user to check " + path,
83
82
  );
84
83
  }
85
84
  }
package/src/execute.ts CHANGED
@@ -151,7 +151,7 @@ export async function executeCodexWebSearch(
151
151
  try {
152
152
  parsed = JSON.parse(response.text);
153
153
  } catch {
154
- throw new Error("failed to decode web_run search response");
154
+ throw new Error("Web search returned an unreadable response. Try again.");
155
155
  }
156
156
  const details = normalizeSearchResponse(parsed);
157
157
  const text =
package/src/request.ts CHANGED
@@ -34,7 +34,14 @@ export function normalizeSearchResponse(value: unknown): WebRunOutput {
34
34
  typeof parsed["output_text"] === "string" ||
35
35
  Array.isArray(parsed["search_results"])
36
36
  )
37
- return parsed as WebRunOutput;
37
+ return {
38
+ ...(typeof parsed["output_text"] === "string"
39
+ ? { output_text: parsed["output_text"] }
40
+ : {}),
41
+ ...(Array.isArray(parsed["search_results"])
42
+ ? { search_results: parsed["search_results"] }
43
+ : {}),
44
+ };
38
45
  if (typeof parsed["output"] !== "string")
39
46
  throw new Error("web_run search returned no output");
40
47
  return {
package/src/service.ts ADDED
@@ -0,0 +1,65 @@
1
+ import type {
2
+ ExtensionAPI,
3
+ ExtensionContext,
4
+ } from "@earendil-works/pi-coding-agent";
5
+ import type { WebSearchToolOptions } from "./contract.js";
6
+ import {
7
+ executeCodexWebSearch,
8
+ type WebRunExecutionResult,
9
+ } from "./execute.js";
10
+
11
+ export const CODEX_WEB_RUN_SERVICE = "@howaboua/pi-codex-web-run.service/v1";
12
+
13
+ /** Discover synchronously per use; discovery does not check auth or run a search. */
14
+ export interface CodexWebRunServiceRequest {
15
+ use(service: CodexWebRunService): void;
16
+ }
17
+
18
+ export interface CodexWebRunService {
19
+ readonly protocol: 1;
20
+ /** Explicit web_run arguments; results are returned only to the caller. */
21
+ run(
22
+ ctx: ExtensionContext,
23
+ params: Record<string, unknown>,
24
+ signal?: AbortSignal,
25
+ ): Promise<WebRunExecutionResult>;
26
+ }
27
+
28
+ export function registerCodexWebRunService(
29
+ pi: ExtensionAPI,
30
+ options: WebSearchToolOptions,
31
+ ): void {
32
+ const lifetime = new AbortController();
33
+ const service: CodexWebRunService = {
34
+ protocol: 1,
35
+ async run(ctx, params, signal) {
36
+ const operation = signal
37
+ ? AbortSignal.any([lifetime.signal, signal])
38
+ : lifetime.signal;
39
+ operation.throwIfAborted();
40
+ const result = await executeCodexWebSearch(
41
+ params,
42
+ ctx,
43
+ operation,
44
+ options,
45
+ );
46
+ operation.throwIfAborted();
47
+ return result;
48
+ },
49
+ };
50
+ const off = pi.events.on(CODEX_WEB_RUN_SERVICE, (request) => {
51
+ if (
52
+ request &&
53
+ typeof request === "object" &&
54
+ "use" in request &&
55
+ typeof request.use === "function"
56
+ )
57
+ request.use(service);
58
+ });
59
+ pi.on("session_shutdown", () => {
60
+ off();
61
+ lifetime.abort(
62
+ new Error("Web search session ended. Retry in the current session."),
63
+ );
64
+ });
65
+ }