docs: trim generated prose

packages/web/tool-web/src/fetch.ts

@@ -1,15 +1,8 @@
 /**
- * The model-facing `web_fetch` tool: retrieve the content of a specific URL.
- * Execution goes through `ctx.web` — this module owns the model-facing schema,
- * argument validation, and PRESENTATION (HTML→markdown, truncation formatting),
- * while the fetch provider owns safe retrieval (transport, redirects, caps).
- *
- * The model-facing schema exposes NO timeout knob: the tool-call budget is
- * deployment policy DECLARED via this package's `fetchTimeoutMs` config (attached
- * as `ToolDefinition.timeoutMs`) and ENFORCED by `@deepseek-ai/dsh-timeout-policy`
- * (a `tools/execute` wrapper), matching the reference-agent `WebFetch` shape. This
- * tool just forwards the (possibly deadline-derived) `exec.signal` to `ctx.web`;
- * the provider keeps its own timeout only as a resource backstop for direct callers.
+ * The model-facing `web_fetch` tool: retrieve the content of a specific URL. Execution goes
+ * through `ctx.web` — this module owns the model-facing schema, argument validation, and
+ * PRESENTATION (HTML→markdown, truncation formatting), while the fetch provider owns safe
+ * retrieval (transport, redirects, caps).
  */
 
 import type { Context } from 'cordis'

packages/web/tool-web/src/html.ts

@@ -1,11 +1,5 @@
 /**
- * Minimal, dependency-free HTML→markdown-ish text conversion for `web_fetch`
- * presentation. This is intentionally NOT a full HTML parser: it strips
- * script/style/noscript, drops tags, decodes the common named/numeric entities,
- * and collapses whitespace into a readable plain-text approximation with a few
- * markdown affordances (headings, list bullets, links). A heavier converter can
- * replace this without touching the seam or the tool schema.
- *
+ * Minimal, dependency-free HTML→markdown-ish text conversion for `web_fetch` presentation.
  * @module @deepseek-ai/dsh-tool-web/html
  */
 

packages/web/tool-web/src/index.ts

@@ -1,19 +1,7 @@
 /**
- * The model-facing web tool suite (`web_search`, `web_fetch`) over the `ctx.web`
- * seam. This root plugin registers the tools the product has ENABLED, composing
- * the per-tool registration helpers (`applyWebSearchTool`, `applyWebFetchTool`).
- *
- * The package owns model-facing concerns only — tool names, JSON schemas,
- * argument validation, prompt sections, result-cap constants, result formatting,
- * HTML→markdown presentation. All web access goes through `ctx.web`; this
- * package never imports a concrete provider package.
- *
- * Tool registration follows product/app ENABLEMENT, not backend availability: a
- * tool stays visible even when its selected provider is missing/misconfigured,
- * and execution fails with a structured `WebError` (resolved by the seam at call
- * time). That keeps the model schema stable without making plugin load order,
- * credential state, or HMR timing part of the model-facing contract.
- *
+ * The model-facing web tool suite (`web_search`, `web_fetch`) over the `ctx.web` seam. This
+ * root plugin registers the tools the product has ENABLED, composing the per-tool registration
+ * helpers (`applyWebSearchTool`, `applyWebFetchTool`).
  * @module @deepseek-ai/dsh-tool-web
  */
 

packages/web/tool-web/tests/integration.spec.ts

@@ -1,11 +1,8 @@
 /**
- * Integration: the real fetch backend (`dsh-web-fetch-local`) + a real search
- * provider (`dsh-web-search-exa`) + the real seam (`dsh-web`) + the model tool
- * (`dsh-tool-web`) + the tool-call timeout policy (`dsh-timeout-policy`),
- * exercised through `ctx.tools.execute()` — nothing bypasses the tool registry.
- * Fetch hits a real loopback HTTP server (verifying the WORLD); search runs the
- * real Exa provider over a stubbed global `fetch` (the network is the one
- * boundary we mock).
+ * Integration: the real fetch backend (`dsh-web-fetch-local`) + a real search provider
+ * (`dsh-web-search-exa`) + the real seam (`dsh-web`) + the model tool (`dsh-tool-web`) + the
+ * tool-call timeout policy (`dsh-timeout-policy`), exercised through `ctx.tools.execute()` —
+ * nothing bypasses the tool registry.
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
@@ -159,10 +156,8 @@ describe('tool-call timeout returns TOOL_TIMEOUT (deadline wins over a slow fetc
   })
 
   it('the provider backstop still protects a DIRECT ctx.web.fetch() call (no tool-call policy in that path)', async () => {
-    // A direct seam caller does not go through tools/execute, so the tool-call
-    // policy never applies; the provider's OWN timeout is the only budget. A
-    // short per-request hint proves the provider backstop is intact and classifies
-    // as WEB_FETCH_TIMEOUT (the provider-owned code), never TOOL_TIMEOUT.
+    // A direct seam caller does not go through tools/execute, so the tool-call policy never
+    // applies; the provider's own timeout is the only budget.
     const err = await tctx.web.fetch({ url: slowBase, timeoutMs: 50 }).then(
       () => undefined,
       (e: unknown) => e as { code?: string },

packages/web/tool-web/tests/load-path.spec.ts

@@ -1,17 +1,4 @@
-/**
- * Real-load-path guard for @deepseek-ai/dsh-tool-web. `tool-web` is a NAMESPACE
- * plugin with `inject` — so a stray `export default apply` would make the cordis
- * Loader's `unwrapExports` (`exports.default ?? exports`) collapse the module to
- * the bare `apply` function, DROPPING `inject`. The plugin would then read
- * `ctx.web` without having injected it and throw `cannot get property … without
- * inject` the moment it loads (postmortem 0001).
- *
- * A hand-built `ctx.plugin({ apply, inject })` mount CANNOT catch that — it
- * bypasses `unwrapExports`. So this test unwraps the module through the REAL
- * `Loader.prototype.unwrapExports` and mounts the result over `ctx.web`,
- * exercising the exact path the Loader uses. Prove the guard bites: add
- * `export default apply` to `src/index.ts`, watch this go red, revert.
- */
+/** Real Loader-path coverage for the namespace plugin's export shape. */
 
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
@@ -41,7 +28,6 @@ describe('dsh-tool-web real-load-path guard', () => {
 
     const loader = Object.create(Loader.prototype) as Loader
     const unwrapped = loader.unwrapExports(toolWeb) as Parameters<Context['plugin']>[0]
-    // A collapsed export shape (dropped inject) would throw "without inject" here.
     const fiber = await ctx.plugin(unwrapped)
     expect(ctx.tools.schemas().map(s => s.name)).toEqual(expect.arrayContaining(['web_search', 'web_fetch']))
     await fiber.dispose()