Merge remote-tracking branch 'origin/master' into codex/simp-prune-web-seam-fields

# Conflicts:
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md
#	docs/core-data-structures/web.md
#	docs/rfc/implemented/simplification/2026-07-04-drop-unconsumed-web-observation-surface.md
#	packages/web/tool-web/tests/integration.spec.ts
#	packages/web/web-fetch-local/README.md
#	packages/web/web-fetch-local/src/provider.ts
#	packages/web/web/src/types.ts

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. This module owns its schema, validation, and presentation;
+ * `ctx.web` owns retrieval. Timeout is deployment policy, not a model argument: config becomes
+ * `ToolDefinition.timeoutMs`, timeout policy enforces it, and this tool forwards the resulting
+ * signal. A provider timeout remains a backstop for direct seam callers.
  */
 
 import type { Context } from 'cordis'

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

@@ -1,11 +1,8 @@
 /**
- * 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-to-readable-text conversion for `web_fetch`, not a full parser. It
+ * removes non-content elements and tags, decodes common entities, collapses whitespace, and keeps
+ * basic headings, lists, and links. A richer converter can replace it without changing the seam or
+ * tool schema.
  * @module @deepseek-ai/dsh-tool-web/html
  */
 

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

@@ -1,19 +1,8 @@
 /**
- * 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.
- *
+ * Model-facing `web_search` and `web_fetch` tools over `ctx.web`. This package owns schemas,
+ * validation, prompt guidance, limits, and presentation, never concrete providers. Enablement
+ * controls tool registration; an enabled tool remains visible when its provider is unavailable
+ * and fails with a structured error at execution time.
  * @module @deepseek-ai/dsh-tool-web
  */
 

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

@@ -1,11 +1,9 @@
 /**
- * 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. Fetch verifies world effects against loopback HTTP; search
+ * uses the real Exa provider with only its network boundary stubbed.
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
@@ -159,10 +157,8 @@ describe('tool-call timeout returns TOOL_TIMEOUT (deadline wins over a slow fetc
   })
 
   it('the provider backstop still protects a direct provider call (no tool-call policy in that path)', async () => {
-    // A direct provider caller does not go through tools/execute, so the tool-call
-    // policy never applies; the provider's OWN timeout is the only budget. A
-    // A second direct provider with a short configured backstop proves the
-    // provider-owned deadline remains intact and distinct from TOOL_TIMEOUT.
+    // A direct provider caller bypasses tools/execute, so a short configured backstop
+    // must produce provider-owned WEB_FETCH_TIMEOUT rather than TOOL_TIMEOUT.
     const direct = new WebFetchLocal.LocalFetchProvider({
       maxUrlLength: 2048,
       maxResponseBytes: 5_000_000,

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

@@ -1,16 +1,8 @@
 /**
- * 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 guard for an injected namespace plugin. A default export would make
+ * `unwrapExports` collapse the namespace and drop `inject`, causing access to `ctx.web` to fail.
+ * Hand-built mounting bypasses that path, so this test unwraps through the real Loader first; see
+ * postmortem 0001.
  */
 
 import { describe, expect, it } from 'vitest'
@@ -41,7 +33,7 @@ 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.
+    // Mounting the collapsed shape would throw for missing injection 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()