@tianshu-ai/tianshu 0.3.0

package/plugins/microsandbox/skills/microsandbox-build-use.md

@@ -0,0 +1,201 @@
+---
+name: microsandbox-build-use
+description: How to author a Sandboxfile, build a snapshot, sanity-check it, then switch the tenant to use it. Covers the build → preview → use → reset loop and the common failure modes.
+when:
+  toolPresent: build_sandbox
+---
+
+The sandbox image you customize via a Sandboxfile. Three tools cooperate:
+
+| Tool | What it does |
+|------|--------------|
+| `build_sandbox` | reads the Sandboxfile, boots a builder VM, runs the steps, captures a snapshot, writes build metadata. **Does not** affect the live sandbox. |
+| `list_sandbox_builds` | lists past builds (newest first), with which one is currently in use. |
+| `use_sandbox_build(build_id)` | switches the tenant pointer to that build. The next `reset_sandbox` (or process restart) boots the new VM `fromSnapshot(...)`. Tenant-scoped — does not publish anything outside the tenant. |
+
+## Sandboxfile location
+
+`<your-userHomeDir>/sandbox/Sandboxfile`. Use `write_file("/sandbox/Sandboxfile", "...")` to author it; `build_sandbox` reads from there by default.
+
+## Sandboxfile grammar (v0)
+
+```yaml
+image: python:3.12-slim          # required: any OCI image microsandbox can pull
+cpus: 4                          # optional, default 4
+memory_mib: 4096                 # optional, default 4096
+
+# Pre-installed layers, applied in this order. All optional.
+apt:
+  - libreoffice-writer
+  - fonts-noto-cjk
+pip:
+  - pandas
+  - numpy
+npm:
+  - tsx
+  - typescript
+
+# Free-form shell commands, run last, in array order.
+exec:
+  - sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources
+  # Multi-source fallback for the Node tarball. nodejs.org first,
+  # npmmirror as backup. --connect-timeout / --max-time keep curl
+  # from hanging when a mirror RSTs mid-download.
+  - |
+    bash -c '
+      set -eu; VER=v22.20.0; F=node-${VER}-linux-arm64.tar.xz
+      for u in https://nodejs.org/dist/${VER}/${F} \
+               https://npmmirror.com/mirrors/node/${VER}/${F} \
+               https://registry.npmmirror.com/-/binary/node/${VER}/${F}; do
+        echo "[node] trying $u"
+        if curl -fsSL --retry 3 --retry-delay 5 --retry-all-errors \
+             --connect-timeout 30 --max-time 600 "$u" \
+           | tar -xJ -C /usr/local --strip-components=1; then
+          echo "[node] installed from $u"; exit 0
+        fi
+      done
+      echo "[node] all sources exhausted" >&2; exit 1
+    '
+```
+
+The four list slots are convenience wrappers: `apt`/`pip`/`npm` produce one
+combined `apt-get install -y --no-install-recommends ...` (or pip / npm)
+call. Anything more complex goes in `exec`.
+
+## The full lifecycle
+
+```
+1. write_file("/sandbox/Sandboxfile", "...")
+2. build_sandbox()                      # 30s–10min; returns build_id
+3. (sanity-check via the admin /shell preview, or via tools below)
+4. use_sandbox_build(build_id)          # writes tenant pointer
+5. reset_sandbox()                      # live VM picks up the new snapshot
+```
+
+You can also sanity-check from the agent: tools work the same against
+the build snapshot as against any image (the agent doesn't have a
+preview-exec equivalent yet — that's an admin UI feature). For agent
+flow, the cheap heuristic is: trust the build log tail
+(`build_sandbox` returns it) for "did the install command succeed?",
+then `use_sandbox_build` + `reset_sandbox`, then run real verification
+commands via `exec`.
+
+## Common failure modes
+
+### apt step "succeeds" but the package isn't there
+Usual cause: a step like `echo node=$(node --version)` swallows the
+inner failure because `echo` exits 0 even with `$()` empty. **Verify
+with `bash -c`**:
+
+```yaml
+exec:
+  - bash -c "node --version && npm --version && libreoffice --version | head -1"
+```
+
+`bash -c` propagates the inner `&&` failure; the build fails properly.
+
+### Slow apt
+Default Debian mirrors are slow from CN. First exec step should swap to
+a regional mirror:
+
+```yaml
+exec:
+  - sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources
+  - apt-get update -qq
+  # …rest of your apt installs as a *single* exec line, or via the apt: list
+```
+
+If you're using the `apt:` list slot, the runner already issues
+`apt-get update`; the `sed` line in `exec` happens before that, so the
+update sees the fast mirror.
+
+### apt's nodejs is too old
+Debian bookworm ships Node 18; modern packages need 20+. Skip the apt
+nodejs and grab a binary from a CN mirror:
+
+```yaml
+exec:
+  - DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends curl ca-certificates xz-utils
+  # Multi-source fallback — don't rely on a single CN mirror; it
+  # WILL flake. nodejs.org first, npmmirror as backup.
+  - |
+    bash -c '
+      set -eu; VER=v22.20.0; F=node-${VER}-linux-arm64.tar.xz
+      for u in https://nodejs.org/dist/${VER}/${F} \
+               https://npmmirror.com/mirrors/node/${VER}/${F} \
+               https://registry.npmmirror.com/-/binary/node/${VER}/${F}; do
+        echo "[node] trying $u"
+        if curl -fsSL --retry 3 --retry-delay 5 --retry-all-errors \
+             --connect-timeout 30 --max-time 600 "$u" \
+           | tar -xJ -C /usr/local --strip-components=1; then
+          echo "[node] installed from $u"; exit 0
+        fi
+      done
+      echo "[node] all sources exhausted" >&2; exit 1
+    '
+  - npm config set registry https://registry.npmmirror.com
+```
+
+(`linux-arm64` because microsandbox on Apple Silicon is arm64; for
+x86_64 hosts use `linux-x64`.)
+
+### LibreOffice + CJK font rendering hangs
+You also need `fontconfig` and a fontconfig refresh:
+
+```yaml
+exec:
+  - DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends fontconfig fonts-noto-cjk libreoffice-writer
+  - fc-cache -fv
+```
+
+Without `fc-cache`, the first LibreOffice invocation can spend 30+s
+rebuilding the font index (and sometimes hangs in our setup).
+
+### Snapshot lost between sessions
+`use_sandbox_build` writes a tenant pointer; the live VM only picks
+it up on `reset_sandbox`. If you switch but skip the reset, the next
+agent turn still runs the old image. The user's admin UI has a
+one-click "Use & Reset" button that does both; from the agent always
+pair them.
+
+## Snapshot retention
+
+Snapshots live in microsandbox's local store under
+`~/.microsandbox/snapshots/<name>/`. They are *not* garbage-collected
+automatically in v0; build a lot and you'll fill the disk. Old builds
+can be removed manually with `rm -rf` on that path (no agent tool yet).
+
+The disk-format pointer file (`<tenant>/_tenant/sandbox/current.json`)
+still uses the field names `publishedAt`/`publishedBy` for backwards
+compatibility with existing tenants. The user-facing terminology is
+"in use" / "switch"; the on-disk fields are an implementation detail.
+
+## Pre-flight checklist
+
+Before calling `build_sandbox`, double-check:
+
+- [ ] You wrote the Sandboxfile (`write_file("/sandbox/Sandboxfile", ...)`),
+      not just discussed it.
+- [ ] Final verification step uses `bash -c "<chained checks>"`, not bare
+      `echo $(...)` (silent-failure trap).
+- [ ] If installing user-space binaries (Node, Go, …) you used a regional
+      mirror — default mirrors are too slow inside the sandbox network.
+- [ ] You explicitly want this image — check with the user if you're
+      switching the tenant's in-use build; that affects every future
+      agent turn.
+
+## What NOT to do
+
+- Don't call `use_sandbox_build(build_id)` without first reading
+  `list_sandbox_builds` to confirm the snapshot still exists.
+- Don't run multi-stage workflows (download → compile → install) inline
+  in the verification step — separate them. A failed download in line
+  N+1 is much easier to debug than one of three commands chained
+  through `&&`.
+- Don't rely on `apt-get install` exit code alone to confirm the
+  package works; the install can succeed but the binary may not be on
+  `PATH`. Always test with `which <bin>` or `<bin> --version`.
+- Don't `npm install -g <pkg>` immediately after `npm install -g
+  npm@latest` in the same `exec` line — npm may relink during upgrade
+  and the second call sees a half-installed registry. Split into two
+  `exec` lines.

package/plugins/microsandbox/skills/microsandbox-config.md

@@ -0,0 +1,38 @@
+---
+name: microsandbox-config
+description: How to change the sandbox VM image / cpus / memory using `update_sandbox_config`, and when a `reset_sandbox` is needed for the change to take effect.
+when:
+  toolPresent: update_sandbox_config
+---
+
+`update_sandbox_config` writes the tenant config file. The currently-running
+VM is **not** restarted automatically; call `reset_sandbox` after this if you
+want the new settings live now.
+
+## Configurable fields
+
+| Field | Default | Reset needed? |
+|-------|---------|---------------|
+| `image` | `python:3.12-slim` | yes (rebuilds VM) |
+| `cpus` | 2 | yes |
+| `memory_mib` | 2048 | yes |
+| `sandbox_name` | `tianshu-<tenantId>` | yes (rarely useful) |
+| `idle_shutdown_ms` | 14400000 (4h) | no (read live) |
+| `exec_timeout_ms` | 300000 (5min) | no (read live per call) |
+
+The result returns `reset_required: true/false` so you know whether to call
+`reset_sandbox` next.
+
+## Common changes
+
+- Need a different OS / pre-installed packages: change `image`, then
+  `reset_sandbox`. Image pulls happen on next `exec` (cold start cost).
+- Memory pressure: bump `memory_mib`, `reset_sandbox`.
+- Idle reaping too aggressive: raise `idle_shutdown_ms`. No reset needed.
+
+## What NOT to do
+
+- Don't set `image` to something you haven't verified locally first — a
+  bad image leaves the sandbox in `state: "error"` and the agent loses
+  `exec` until you fix the config.
+- Don't set `cpus` higher than the host has free.

package/plugins/microsandbox/skills/microsandbox-exec-howto.md

@@ -0,0 +1,144 @@
+---
+name: microsandbox-exec-howto
+description: How to use `exec` effectively — default workdir, timeouts, output truncation, when to call `reset_sandbox` vs retrying.
+when:
+  toolPresent: exec
+---
+
+`exec` runs a command inside a per-tenant microVM started lazily on first use.
+
+## Default working dir
+
+`exec` defaults `cwd` to your user home inside the sandbox
+(`/workspace/users/<your-userId>/`), the SAME dir `read_file`/`write_file`
+operate on. So a relative path means the same file on both sides:
+
+```
+write_file("/hello.py", "print('hi')")
+exec("python3 hello.py")     # → "hi"
+```
+
+Pass an absolute path in `workdir` to step outside (e.g. `/etc`, `/usr`,
+`/tmp`).
+
+## Timeouts
+
+- Default: 5 minutes.
+- Cap: 30 minutes (`timeout_ms` is clamped).
+- Use `timeout_ms` for slow tasks: `pip install`, `npm install`, builds,
+  data processing.
+- A timed-out call returns `timed_out: true` and `exit_code: -1`. Retry with
+  a larger timeout if the command is legitimately slow.
+
+## Starting servers / long-running processes
+
+**Don't run a foreground server with `exec`.** A command like
+`python -m http.server 8000` or `npm start` never returns; the
+`exec` call hangs until the host timeout, then your turn dies
+with no useful output AND the server keeps running, tying up
+the port for the next attempt.
+
+Three safe shapes, in order of preference:
+
+### 1. Skip the server (best)
+
+If you only need to verify the file works in a browser, write
+it and tell the user the path. Don't "verify by starting a
+server" — the user will open it themselves. This is the
+default for static sites, single-file games, demos.
+
+### 2. Background + readiness check
+
+When the verification truly needs the server up:
+
+```bash
+# detach completely so exec returns immediately
+nohup setsid python -m http.server 8000 \
+  > /tmp/srv.log 2>&1 < /dev/null &
+
+# wait briefly, then probe
+sleep 2
+curl -sS --max-time 5 http://127.0.0.1:8000/ | head -20
+```
+
+Key moves: `nohup setsid ... &` detaches from this shell;
+`> /tmp/srv.log 2>&1 < /dev/null` closes stdin and redirects
+output so the parent shell can exit cleanly. Without these the
+fd connection keeps `exec` waiting.
+
+### 3. Bounded foreground (rarely useful)
+
+If you need to capture output and the command will exit on its
+own after some short time (a one-shot test runner, a CLI tool):
+
+```bash
+timeout 30 ./run-tests.sh 2>&1 | tail -50
+```
+
+`timeout` guarantees the call returns; the trailing `tail`
+keeps stdout under the truncation cap.
+
+### Stopping a server you started
+
+```bash
+pkill -f 'python -m http.server' || true
+```
+
+Or just `reset_sandbox` if it's gotten messy — your files in
+`/workspace` survive.
+
+## Output truncation
+
+stdout/stderr each truncated at 200 lines / 8 KB. If output is bigger:
+
+```
+exec("long-running-thing > /workspace/out.log 2>&1")
+read_file("/out.log")
+```
+
+…or pipe through `tail`/`sed` inline.
+
+## Pre-installed tools (don't `apt install` / `pip install` what's already there)
+
+The sandbox image ships with these out of the box. Use them
+directly instead of installing alternatives:
+
+- **`soffice`** (LibreOffice 25.2) — headless docx / xlsx / pptx /
+  pdf conversion. See `microsandbox-libreoffice` for the full
+  conversion table, sandbox-specific gotchas (single-instance
+  lock, AF_UNIX status, font cache), and "when soffice is the
+  WRONG tool".
+- **`chromium` / Playwright MCP** — see `microsandbox-browser-howto`.
+  Don't `playwright install chromium`; the sandbox already has it
+  on CDP 9222 + MCP 3200.
+- **`node`, `npm`, `npx`** — Node 22 LTS, configured to npmmirror
+  in CN. `npm install <pkg>` works; just don't try to upgrade
+  Node itself.
+- **`fc-cache`** — already run at build time, so CJK fonts render
+  in `soffice` and `chromium` without a 30s cold start.
+- **`pdftoppm`** (Poppler) — PDF → PNG / JPEG, the right tool
+  for multi-page rasterisation (used by the LibreOffice and
+  PPTX flows).
+
+If you need something not on this list and it's a one-shot:
+`apt-get install -y <pkg>` works in the running VM but won't
+survive a `reset_sandbox`. For persistence, edit Sandboxfile
+and rebuild (see `microsandbox-build-use`).
+
+## When to reset
+
+Call `reset_sandbox` only when:
+
+- `exec` keeps timing out (process stuck, kernel deadlocked).
+- A long-running daemon (e.g. `python -m http.server`) is in your way.
+- `get_sandbox_status` shows `state: "error"`.
+- You broke something in `/etc` / `/usr` and want a clean slate.
+
+`reset_sandbox` destroys the VM and re-creates it. **Files under
+`/workspace` survive**; everything else (installed packages, `/tmp`, running
+processes) does not.
+
+## Cold start
+
+The sandbox boots on first `exec` (≈10s the first time per session).
+Subsequent calls in the same conversation are sub-second.

package/plugins/microsandbox/skills/microsandbox-libreoffice.md

@@ -0,0 +1,159 @@
+---
+name: microsandbox-libreoffice
+description: How to convert / read / extract Office documents inside the sandbox using the pre-installed LibreOffice (soffice). Covers docx / xlsx / pptx / odt round-trips, PDF rendering, slide-deck text extraction with markitdown, and the sandbox-specific gotchas (AF_UNIX shim, font cache, single-process mode, output paths).
+when:
+  toolPresent: exec
+---
+
+# LibreOffice in the sandbox
+
+The sandbox image ships LibreOffice 25.2 (`writer / calc /
+impress`) plus its CLI alias `soffice`. Use it directly — don't
+`pip install python-docx` / `openpyxl` / `python-pptx` for tasks
+that are basically format conversion. They're worth their weight
+when you need cell-level edits or programmatic slide construction;
+for "give me the text", "convert to PDF", "extract slide images",
+`soffice` is one shell call away.
+
+## Conversion table
+
+```bash
+# Office → text
+soffice --headless --convert-to txt   input.docx --outdir /tmp/
+soffice --headless --convert-to txt   input.xlsx --outdir /tmp/   # cells joined by tabs
+soffice --headless --convert-to txt   input.pptx --outdir /tmp/   # slides as paragraphs
+
+# Office → PDF (the workhorse: any → pdf, lossless layout)
+soffice --headless --convert-to pdf   input.docx  --outdir /tmp/
+soffice --headless --convert-to pdf   input.xlsx  --outdir /tmp/
+soffice --headless --convert-to pdf   input.pptx  --outdir /tmp/
+
+# Office round-trips
+soffice --headless --convert-to docx  input.odt   --outdir /tmp/
+soffice --headless --convert-to xlsx  input.csv   --outdir /tmp/
+soffice --headless --convert-to csv   input.xlsx  --outdir /tmp/
+
+# PDF → image (multi-page; use pdftoppm, NOT soffice)
+soffice --headless --convert-to pdf   input.pptx  --outdir /tmp/
+pdftoppm -jpeg -r 150 /tmp/input.pdf /tmp/slide
+# → /tmp/slide-01.jpg, /tmp/slide-02.jpg, ...
+```
+
+**`--outdir` is required.** Without it `soffice` writes the
+output next to the input, which means a relative input path that
+resolves anywhere unexpected (your `cwd` in the sandbox is
+`/workspace`, not `/tmp`). Always pass `--outdir`.
+
+## Reading content (text extraction)
+
+For "what does this document say?" — skip the conversion step
+and use `markitdown`, which understands docx / xlsx / pptx /
+pdf natively and outputs structured Markdown:
+
+```bash
+pip install --quiet "markitdown[all]"   # already in image cache; first call ~1s
+python -m markitdown report.docx
+python -m markitdown deck.pptx          # slide titles + body text + speaker notes
+python -m markitdown sheet.xlsx         # tabular Markdown
+```
+
+Markitdown is the right pick when you need to **summarise** the
+document or pass content to another LLM call. `soffice
+--convert-to txt` is the right pick when you need a raw textual
+artefact for an export pipeline.
+
+## Multi-page slide / PDF preview
+
+For visual QA of generated decks (the agent decides "did the
+bullets I generated actually fit?"), render every page to JPEG
+and inspect with the vision model:
+
+```bash
+soffice --headless --convert-to pdf deck.pptx --outdir /tmp/
+pdftoppm -jpeg -r 150 /tmp/deck.pdf /tmp/slide
+ls /tmp/slide-*.jpg
+```
+
+`-r 150` is a good visual-QA DPI; bump to 300 for print review,
+drop to 96 if you only want a thumbnail grid.
+
+To re-render a single slide after a fix:
+
+```bash
+pdftoppm -jpeg -r 150 -f 7 -l 7 /tmp/deck.pdf /tmp/slide-7-fixed
+```
+
+## Sandbox-specific gotchas
+
+### Single-instance lock
+
+`soffice` uses an X server profile + an internal lock file under
+`~/.config/libreoffice/`. If two `soffice --headless` calls run
+concurrently in the same VM, the second one waits for the first.
+Two safe options:
+
+- **Sequential calls** (default; just don't background them).
+- **Per-call user profile** when you legitimately need parallel:
+  ```bash
+  soffice --headless \
+          -env:UserInstallation=file:///tmp/lo-$$ \
+          --convert-to pdf input.docx --outdir /tmp/
+  ```
+  `$$` is the shell's PID; one fresh profile per invocation. Costs
+  ~200 ms of cold start per call.
+
+### AF_UNIX socket shim (probably NOT needed here)
+
+Some sandbox runtimes block `socket(AF_UNIX, ...)`, which makes
+`soffice --headless` hang waiting on its internal IPC. Microsandbox
+on macOS / Linux **does NOT block AF_UNIX** (verified), so you
+don't need a shim. If a future runtime change breaks this, the
+diagnostic is:
+
+```bash
+python3 -c 'import socket; socket.socket(socket.AF_UNIX); print("OK")'
+# OK   → no shim needed
+# OSError → AF_UNIX blocked, build an LD_PRELOAD shim that falls
+#          back to socketpair (see Anthropic pptx skill for the C source)
+```
+
+### Java warning is benign
+
+You'll see `Warning: failed to launch javaldx - java may not
+function correctly`. Java is only needed for the optional
+spreadsheet macro / form-controls path, which we don't use.
+Ignore.
+
+### CJK font rendering
+
+The image build runs `fc-cache -fv` so first-call rendering is
+fast and Chinese / Japanese / Korean glyphs render properly.
+If a build skips that step, the first `soffice` call eats 30+s
+synchronising fonts.
+
+### `--outdir` and absolute paths
+
+`soffice` resolves `--outdir` against the sandbox's `cwd`
+(`/workspace` by default). When the agent's `exec` runs from a
+project subdirectory, prefer absolute paths in BOTH `--outdir`
+and the input filename so the output lands where you expect.
+
+## When LibreOffice is the WRONG tool
+
+- **Cell-level editing / formulas in xlsx**: use `openpyxl` or
+  Pandas. `soffice` rewrites the whole file; structural metadata
+  (named ranges, conditional formatting) can shift.
+- **Programmatic slide creation from scratch**: use `pptxgenjs`
+  (Node) or `python-pptx`. `soffice` is for converting an
+  existing deck, not authoring one.
+- **Markdown / text reports**: don't bounce through Office. Just
+  write `.md`.
+
+## Cleanup
+
+`soffice` leaves `~/.config/libreoffice/`, `~/.cache/libreoffice/`,
+and any per-call `/tmp/lo-*` profile dirs around. Sandbox `/tmp`
+is wiped on `reset_sandbox`; `~` (root) survives. If you're
+running thousands of conversions in one session, `rm -rf
+~/.cache/libreoffice/` periodically to keep disk usage from
+creeping.

package/plugins/microsandbox/templates/README.md

@@ -0,0 +1,26 @@
+# Sandboxfile templates
+
+Each `*.yaml` here is a starting-point Sandboxfile a user can load
+into the admin Sandbox page (or the agent can author via
+`write_file`). Templates surface through the host:
+
+- `GET /api/p/microsandbox/sandboxfile/templates` returns
+  `{ templates: [{ id, displayName, description, content }, ...] }`.
+- The admin page's "Load template" dropdown reads that list and
+  pastes the picked template into the editor (replacing the
+  current draft only after the user clicks Save).
+
+Templates are not enforced — they're just curated examples that
+follow the patterns from `skills/microsandbox-build-use.md` (use
+`bash -c` for verification, regional mirrors for slow apt, etc.).
+
+## When to add a new template
+
+A new template earns its slot when:
+1. Multiple users have hit the same "what packages do I need" wall
+   for a real workload (Office automation, browser, data science),
+   AND
+2. The recipe survives a real `build & use` test on Apple Silicon
+   arm64.
+
+Otherwise leave it as a skill paragraph; less surface to maintain.

package/plugins/web-search/dist/server.d.ts

@@ -0,0 +1,4 @@
+import type { PluginServerModule } from "@tianshu/plugin-sdk";
+declare const plugin: PluginServerModule;
+export default plugin;
+//# sourceMappingURL=server.d.ts.map

package/plugins/web-search/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAGV,kBAAkB,EACnB,MAAM,qBAAqB,CAAC;AAI7B,QAAA,MAAM,MAAM,EAAE,kBA6Db,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/plugins/web-search/dist/server.js

@@ -0,0 +1,73 @@
+// Server side of the `web-search` plugin.
+//
+// One agent tool (`web_search`), backed by Tavily / Brave Search
+// JSON APIs. The plugin's `activate()` reads its API keys from
+// `ctx.pluginConfig` (cleartext at this layer; the host has
+// already merged secrets/ into pluginConfig before calling us)
+// and bakes them into a closure handed to the tool builder.
+//
+// The plugin also keeps a `ProviderHealth` cache shared by every
+// invocation in this activation, so a worker that searches ten
+// times in a row pays the round-trip on a known-bad key only
+// once. The cache is cleared automatically when the plugin
+// re-activates (any config change does this) and via the
+// `POST /health/reset` admin route below.
+import { buildWebSearchTool, readWebSearchConfig } from "./tools/index.js";
+import { ProviderHealth } from "./tools/health.js";
+const plugin = {
+    activate(ctx) {
+        const cfg = readWebSearchConfig(ctx.pluginConfig);
+        const haveTavily = !!cfg.tavilyApiKey;
+        const haveBrave = !!cfg.braveApiKey;
+        if (!haveTavily && !haveBrave) {
+            ctx.log.warn("web-search: no API keys configured. Open Settings → Plugins → Web Search and add a Tavily or Brave key.");
+        }
+        else {
+            ctx.log.info(`web-search: enabled with ${[haveTavily && "Tavily", haveBrave && "Brave"]
+                .filter(Boolean)
+                .join(" + ") || "(no providers)"}`);
+        }
+        const health = new ProviderHealth();
+        return {
+            tools: {
+                WebSearchTool: buildWebSearchTool(cfg, health),
+            },
+            routes: {
+                // GET /api/p/web-search/health
+                getHealth: (_req, res) => {
+                    res.json({
+                        ok: true,
+                        providers: {
+                            tavily: { configured: haveTavily },
+                            brave: { configured: haveBrave },
+                        },
+                        preferredProvider: cfg.preferredProvider ?? "tavily",
+                        timeoutMs: cfg.timeoutMs ?? 8000,
+                        dead: health.snapshot(),
+                    });
+                },
+                // POST /api/p/web-search/health/reset
+                // Body is optional: { provider?: "tavily" | "brave" }.
+                // Without `provider` the whole cache clears.
+                resetHealth: (req, res) => {
+                    const body = req.body;
+                    const target = body?.provider;
+                    if (target === "tavily" || target === "brave") {
+                        health.resetOne(target);
+                        res.json({ ok: true, cleared: [target] });
+                        return;
+                    }
+                    const before = health.snapshot().map((e) => e.provider);
+                    health.reset();
+                    res.json({ ok: true, cleared: before });
+                },
+            },
+        };
+    },
+    async deactivate() {
+        // ProviderHealth is per-activation; the GC takes care of it
+        // when activate() is called again (registry invalidate cycle).
+    },
+};
+export default plugin;
+//# sourceMappingURL=server.js.map

package/plugins/web-search/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}