@ssk_dev/pi-web-access-lean 0.22.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kunkun9527
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# @ssk_dev/pi-web-access-lean
+
+> **Lean Pi web access plugin, same functionality — 141 initialization tokens, 94% fewer than the original.**
+> [See my full setup for Pi](https://github.com/kunkun9527/my-lean-pi-setup)
+
+[简体中文](README.zh-CN.md)
+
+A token-lean Pi facade over [`pi-web-access`](https://github.com/nicobailon/pi-web-access). It keeps the complete upstream web runtime while presenting one compact model-facing schema.
+
+## What it keeps
+
+- Web search and result continuation.
+- Source and claim checking.
+- URL fetching and upstream provider behavior.
+- Complete advanced operation schemas, disclosed locally through `help` only when needed.
+
+## Why it is lean
+
+Instead of exposing four detailed provider-facing tools on every request, the wrapper routes them through one `web_access` tool. Simple calls use a short string; advanced parameters remain available as JSON without keeping every operation schema in the prompt.
+
+## Install
+
+```bash
+pi install npm:@ssk_dev/pi-web-access-lean
+```
+
+Do not load another `pi-web-access` wrapper at the same time, or web tools may be registered twice.
+
+## Use
+
+The model sees one tool:
+
+```text
+web_access
+```
+
+| `op` | Purpose | `input` |
+| --- | --- | --- |
+| `search` | Search the web | Query string |
+| `check` | Check a claim or source | Claim string |
+| `fetch` | Fetch a URL | URL string |
+| `get` | Continue a stored result | Response ID |
+| `help` | Show full parameters | Operation name |
+
+Simple example:
+
+```json
+{ "op": "search", "input": "Pi coding agent extensions" }
+```
+
+For batch or advanced parameters, pass a JSON object encoded as the `input` string. Use `help` only when the complete upstream schema is required.
+
+## Measured initialization footprint
+
+With only this extension enabled, its recurring model-facing initialization contribution is:
+
+| Model-facing tool | Lean | Upstream `pi-web-access@0.22.0` |
+| --- | ---: | ---: |
+| Facade / search | `web_access`: 141 | `web_search`: 994 |
+| Source checking | Included in facade | `source_check`: 413 |
+| Content fetching | Included in facade | `fetch_content`: 576 |
+| Result continuation | Included in facade | `get_search_content`: 393 |
+| **Total** | **141** | **2,376** |
+
+That is **2,235 fewer tokens (94.1%)** than the pinned upstream extension. The measurement used Pi 0.84.4 and `pi-context-view@0.4.3` in a fresh isolated session, excluding Pi built-in tools, skills, context files, messages, and unrelated extensions. Context View estimates text as `ceil(characters / 4)`, so these are reproducible context-footprint estimates rather than exact GPT tokenizer counts. Runtime-only UI and slash commands are not included because they are not sent to the model.
+
+## Versions
+
+The upstream runtime is pinned to `pi-web-access@0.22.0`.
+
+## Development
+
+```bash
+npm ci
+npm run check
+```
+
+## License and upstream
+
+MIT. This project wraps the MIT-licensed [`pi-web-access`](https://github.com/nicobailon/pi-web-access).

package/README.zh-CN.md

@@ -0,0 +1,80 @@
+# @ssk_dev/pi-web-access-lean
+
+> **Lean Pi web access 插件，功能相同：141 个初始化 tokens，较原插件减少 94%。**
+> **整套配置：** [查看 Pi Lean Setup](https://github.com/kunkun9527/my-lean-pi-setup)
+
+[English](README.md)
+
+[`pi-web-access`](https://github.com/nicobailon/pi-web-access) 的 token 精简版 Pi facade。它保留完整的上游联网运行时，同时只向模型提供一个紧凑 schema。
+
+## 保留的能力
+
+- 网页搜索和结果续取。
+- 来源与事实声明核验。
+- URL 抓取和上游供应商行为。
+- 完整高级操作 schema，仅在需要时通过 `help` 在本地披露。
+
+## 为什么更精简
+
+包装层不再让每次请求都携带四个详细的模型可见工具，而是通过一个 `web_access` 工具路由这些能力。简单调用只使用短字符串；高级参数仍可通过 JSON 使用，无需长期把每个操作 schema 放入提示词。
+
+## 安装
+
+```bash
+pi install npm:@ssk_dev/pi-web-access-lean
+```
+
+不要同时加载另一个 `pi-web-access` 包装层，否则联网工具可能被重复注册。
+
+## 使用
+
+模型只看到一个工具：
+
+```text
+web_access
+```
+
+| `op` | 作用 | `input` |
+| --- | --- | --- |
+| `search` | 搜索网页 | 查询字符串 |
+| `check` | 核验声明或来源 | 声明字符串 |
+| `fetch` | 抓取 URL | URL 字符串 |
+| `get` | 续取已保存结果 | Response ID |
+| `help` | 显示完整参数 | 操作名称 |
+
+简单示例：
+
+```json
+{ "op": "search", "input": "Pi coding agent extensions" }
+```
+
+批量或高级参数应把 JSON 对象编码为 `input` 字符串。仅在需要完整上游 schema 时使用 `help`。
+
+## 实测初始化上下文占用
+
+仅启用本扩展时，它持续贡献给模型的初始化上下文为：
+
+| 模型可见工具 | Lean | 上游 `pi-web-access@0.22.0` |
+| --- | ---: | ---: |
+| Facade / 搜索 | `web_access`：141 | `web_search`：994 |
+| 来源核验 | 已包含在 facade 中 | `source_check`：413 |
+| 内容抓取 | 已包含在 facade 中 | `fetch_content`：576 |
+| 结果续取 | 已包含在 facade 中 | `get_search_content`：393 |
+| **合计** | **141** | **2,376** |
+
+相比固定版本的上游扩展，减少 **2,235 tokens（94.1%）**。测量使用 Pi 0.84.4 和 `pi-context-view@0.4.3`，在全新隔离会话中只启用目标扩展，并排除 Pi 内置工具、skills、context files、消息及无关扩展。Context View 按 `ceil(字符数 / 4)` 估算，因此这些是可复现的上下文占用估值，不是 GPT tokenizer 的精确计数。未计入不会发送给模型的纯运行时 UI 和 slash commands。
+
+## 版本
+
+上游运行时固定为 `pi-web-access@0.22.0`。
+
+## 开发
+
+```bash
+npm ci
+npm run check
+```
+
+## 许可证与上游
+
+MIT。本项目包装了采用 MIT 许可证的 [`pi-web-access`](https://github.com/nicobailon/pi-web-access)。

package/index.ts

@@ -0,0 +1,133 @@
+// pi-web-access-lean: one provider-facing facade over the full pi-web-access runtime.
+// Detailed operation schemas stay local and are disclosed only through `help`.
+import type {
+  ExtensionAPI,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import webAccess from "pi-web-access/index.ts";
+import { Type } from "typebox";
+
+type CapturedTool = ToolDefinition<any, any, any>;
+type UpstreamExtension = (pi: ExtensionAPI) => void;
+
+const ROUTES = {
+  search: { toolName: "web_search", inputName: "query" },
+  check: { toolName: "source_check", inputName: "claim" },
+  fetch: { toolName: "fetch_content", inputName: "url" },
+  get: { toolName: "get_search_content", inputName: "responseId" },
+} as const;
+
+type Operation = keyof typeof ROUTES;
+type FacadeOperation = Operation | "help";
+
+const FACADE_PARAMETERS = Type.Object({
+  op: Type.Unsafe<FacadeOperation>({
+    type: "string",
+    enum: ["search", "check", "fetch", "get", "help"],
+  }),
+  input: Type.Optional(Type.String({
+    description: "Main query, claim, URL, or responseId; use a JSON object string for advanced parameters",
+  })),
+});
+
+function capturePi(
+  pi: ExtensionAPI,
+  tools: Map<string, CapturedTool>,
+): ExtensionAPI {
+  return new Proxy(pi, {
+    get(target, property, receiver) {
+      if (property === "registerTool") {
+        return (tool: CapturedTool) => tools.set(tool.name, tool);
+      }
+      const value = Reflect.get(target, property, receiver);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}
+
+function parseInput(input: string, inputName: string): Record<string, unknown> {
+  if (!input.trimStart().startsWith("{")) return { [inputName]: input };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(input);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`web_access input is invalid JSON: ${reason}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("web_access advanced input must be a JSON object");
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function helpResult(
+  operation: string,
+  tools: Map<string, CapturedTool>,
+) {
+  const route = ROUTES[operation as Operation];
+  if (!route) {
+    return {
+      content: [{
+        type: "text" as const,
+        text: "Operations: search(query), check(claim), fetch(URL), get(responseId). For advanced parameters, call help with input set to one operation name.",
+      }],
+      details: { operation: "help" },
+    };
+  }
+
+  const tool = tools.get(route.toolName);
+  if (!tool) throw new Error(`web_access could not find upstream tool: ${route.toolName}`);
+  const text = [
+    `${operation} routes to ${route.toolName}`,
+    tool.description,
+    "Advanced input must be a JSON object string matching this schema:",
+    JSON.stringify(tool.parameters, null, 2),
+  ].filter(Boolean).join("\n\n");
+  return {
+    content: [{ type: "text" as const, text }],
+    details: { operation, toolName: route.toolName },
+  };
+}
+
+export function createWebAccessFacade(
+  upstream: UpstreamExtension = webAccess,
+): (pi: ExtensionAPI) => void {
+  return (pi: ExtensionAPI): void => {
+    const tools = new Map<string, CapturedTool>();
+    upstream(capturePi(pi, tools));
+    const facadeTool: ToolDefinition<typeof FACADE_PARAMETERS, unknown, unknown> = {
+      name: "web_access",
+      label: "Web Access",
+      description: "Search, verify, fetch, or continue web content through one local router. Use help for advanced parameters.",
+      promptGuidelines: [
+        "web_access input is the query, claim, URL, or responseId for search, check, fetch, or get. Pass a JSON object string for batch or advanced parameters; use help only when fields are unclear.",
+      ],
+      parameters: FACADE_PARAMETERS,
+      async execute(callId, params, signal, onUpdate, ctx) {
+        if (params.op === "help") {
+          return helpResult((params.input ?? "").trim(), tools);
+        }
+
+        const route = ROUTES[params.op];
+        if (!route) {
+          throw new Error(`web_access operation is not implemented: ${params.op}`);
+        }
+        const tool = tools.get(route.toolName);
+        if (!tool) {
+          throw new Error(`web_access could not find upstream tool: ${route.toolName}`);
+        }
+        return tool.execute(
+          callId,
+          parseInput(params.input ?? "", route.inputName),
+          signal,
+          onUpdate,
+          ctx,
+        );
+      },
+    };
+    pi.registerTool(facadeTool);
+  };
+}
+
+export default createWebAccessFacade();

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@ssk_dev/pi-web-access-lean",
+  "version": "0.22.0",
+  "type": "module",
+  "description": "Lean Pi web access plugin, same functionality — 141 initialization tokens, 94% fewer than the original.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "kunkun9527",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kunkun9527/pi-web-access-lean.git"
+  },
+  "homepage": "https://github.com/kunkun9527/pi-web-access-lean#readme",
+  "bugs": {
+    "url": "https://github.com/kunkun9527/pi-web-access-lean/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "web-search",
+    "web-access",
+    "token-efficient"
+  ],
+  "files": [
+    "index.ts",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "check": "npm run typecheck && npm test"
+  },
+  "dependencies": {
+    "pi-web-access": "0.22.0",
+    "typebox": "1.3.7"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.84.1 <1.0.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.1 <1.0.0",
+    "@earendil-works/pi-tui": ">=0.84.1 <1.0.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.3",
+    "@earendil-works/pi-coding-agent": "0.84.3",
+    "@earendil-works/pi-tui": "0.84.3",
+    "jiti": "2.7.0",
+    "typescript": "5.9.3"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}