refactor: replace overloaded surface terminology

packages/core/tools/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/tools/README.md
-README.md: cc7b323ae1de917e93e243e97bd5cf5937ecdca4
+README.md: 75d18712a02ecc72c2ea3a7203d2a7377cef87c7
 README.zh.md: 8d4ae42596483f77aa82b23a0b41168465e2b165

packages/core/tools/README.md

@@ -111,7 +111,7 @@ Tools optionally own pure `presentCall()` and `presentResult()` render intents,
 - Call views are `{ card: 'generic', title, kind?, rawInput?, content?, locations? }`, `{ card: 'terminal', title, description?, cwd? }`, or `{ card: 'diff', title, diffs, locations? }`.
 - Result views are `{ card: 'generic', title?, content? }`, `{ card: 'terminal', title?, output?, exitCode?, signal? }`, `{ card: 'diff', title?, diffs }`, `{ card: 'search', shape, title?, truncated, total, … }` (a completed discovery search — grouped-by-file matches for `shape: 'matches'` (grep) or a flat path list for `shape: 'paths'` (glob), with `truncated`/`total` so a UI never presents a capped result as complete; the view carries no result text and a search has no `card: 'search'` call-time analogue), `{ card: 'read', title?, path, offset, lines, totalLines, lang?, content? }` (a completed file read → a line-numbered, optionally syntax-highlighted code view; `offset` is the 1-based first line the window requested, kept even when `lines` is empty; `lines` is `{ number, text }[]` keeping each file line number, and `content` is the envelope-stripped text a UI without read support falls back to), or `{ card: 'web', kind: 'search' | 'fetch', title?, … }` (a completed web retrieval; the `kind` arms carry the structured search sources or the fetch summary, and a UI without the `web` capability falls back to the raw result content).
 
-Returning `undefined` selects generic fallback. Presenters depend only on their arguments and the durable result because UIs call them during live streaming and log replay. `output.presentationMeta(args, value)` derives JSON metadata for direct surface calls; that metadata persists with `tool/result` and returns to `presentResult`, while the canonical value itself remains execution-local and is never replayed. Nested Code dispatches do not compute metadata. `defineTool` soft-validates older logged arguments and falls back instead of crashing replay. `dsh-tool-bash` and `dsh-tool-fs` are the reference implementations; the [canonical-output Agent Note](../../../.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md) owns the value/presentation split and the [render-intent Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md) owns card vocabulary.
+Returning `undefined` selects generic fallback. Presenters depend only on their arguments and the durable result because UIs call them during live streaming and log replay. `output.presentationMeta(args, value)` derives JSON metadata for direct top-level calls; that metadata persists with `tool/result` and returns to `presentResult`, while the canonical value itself remains execution-local and is never replayed. Nested Code dispatches do not compute metadata. `defineTool` soft-validates older logged arguments and falls back instead of crashing replay. `dsh-tool-bash` and `dsh-tool-fs` are the reference implementations; the [canonical-output Agent Note](../../../.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md) owns the value/presentation split and the [render-intent Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md) owns card vocabulary.
 
 ### Code Mode
 

packages/core/tools/src/code-mode.ts

@@ -260,7 +260,7 @@ type RunCodeOutput = { logs: string[]; result?: JsonValue }
 /**
  * Registry-private capabilities the bridge receives at construction — the
  * `requireRuntime` idiom: operations only the owning registry can mint stay
- * off its public service surface and flow here as closures instead.
+ * off its public service API and flow here as closures instead.
  */
 export interface RunCodeBridgeOptions {
   /** Resolves `ctx.codeRuntime` or throws the loud misconfiguration error (shared with the registry's assembly-time checks). */
@@ -646,7 +646,7 @@ export function createRunCodeTool(registry: ToolRegistry, options: RunCodeBridge
       kind: 'execute',
       rawInput: args.code,
     }),
-    // Deliberately no presentResult: the generic surface fallback keeps this
+    // Deliberately no presentResult: the generic card fallback keeps this
     // title and reads durable result content without duplicating a large raw
     // result into the host view payload.
   })

packages/core/tools/src/index.ts

@@ -94,7 +94,7 @@ export { defineContentToolFixture, type ContentToolFixtureOptions } from './test
 
 // The render-intent vocabulary a tool declares via `presentCall`/`presentResult`
 // lives in its own UI-facing module; re-export it so `@deepseek-ai/dsh-tools`
-// stays the single public surface for tool producers and UI adapters.
+// stays the single public API for tool producers and UI adapters.
 export type {
   ToolCallKind,
   FileLocation,
@@ -200,7 +200,7 @@ export interface ToolOutputDefinition {
   readonly schema: JsonSchemaNode
   /** Pure projection from validated arguments and value to Native/model content. */
   render(args: unknown, value: JsonValue): ContentBlock[]
-  /** Pure replayable presentation projection, computed only for surface calls. */
+  /** Pure replayable presentation projection, computed only for top-level calls. */
   presentationMeta?(args: unknown, value: JsonValue): JsonValue
 }
 
@@ -1009,7 +1009,7 @@ export class ToolRegistry extends Service {
    * Restrict global tools for the calling agent scope. Empty filters, unknown
    * names, scope-local names, and reserved transport names fail. Restrictions
    * intersect; scoped registrations remain visible.
-   * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
+   * @param filter - global-tool mask: `allow` (keep only) and/or `deny` (remove).
    * @returns the exact disposer that lifts this restriction.
    */
   restrict(filter: ToolRestriction): () => void {

packages/core/tools/src/presentation.ts

@@ -60,7 +60,7 @@ export interface GenericCallView {
   /** Category for icon/treatment; defaults to `other` when omitted. */
   kind?: ToolCallKind
   /**
-   * The salient input to surface in a detail/expanded view (e.g. a background
+   * The salient input to show in a detail/expanded view (e.g. a background
    * task id). Omit to show nothing; a string renders as-is, an object as pretty
    * JSON. NOT the full raw args object unless that is genuinely what a reader wants.
    */

packages/core/tools/src/schema.ts

@@ -493,7 +493,7 @@ export interface DefineToolOptions<S extends ParameterSchemaSpec, O extends Valu
     readonly schema: O
     /** Pure Native/model rendering of one validated canonical value. */
     render(args: InferArgs<S>, value: InferValue<NoInfer<O>>): ContentBlock[]
-    /** Pure replayable presentation metadata for direct surface calls. */
+    /** Pure replayable presentation metadata for direct top-level calls. */
     presentationMeta?(args: InferArgs<S>, value: InferValue<NoInfer<O>>): JsonValue
   }
   /** Optional positive cooperative timeout budget in milliseconds. */

packages/core/tools/src/ts-types.ts

@@ -2,7 +2,7 @@
  * Code Mode codegen: the pure projection from registered tool schemas to the TypeScript SDK
  * text the model programs against (the `tools:sdk` prompt section). Sibling of
  * `json-schema.ts` — `schemas()` (native function calling) and this module (the generated
- * `declare const tools` surface) are two projections of the same store.
+ * `declare const tools` API) are two projections of the same store.
  * @module @deepseek-ai/dsh-tools/src/ts-types
  */
 

packages/core/tools/tests/code-mode.spec.ts

@@ -1229,7 +1229,7 @@ describe('the run_code dispatch bridge', () => {
     const tool = ctx.tools.get(RUN_CODE_NAME)!
 
     expect(result.content).toEqual([{ type: 'text', text }])
-    // Surfaces keep the pending program title and render this durable content
+    // Presenters keep the pending program title and render this durable content
     // through their generic fallback. Omitting a result view also prevents the
     // host frame from carrying the same raw content a second time.
     expect('presentResult' in tool).toBe(false)

packages/core/tools/tests/tools.spec.ts

@@ -2593,7 +2593,7 @@ describe('defineTool validation (the runtime-validation Agent Note, part 1)', ()
     expect(err.message).toBe('invalid arguments: missing required property "a"; "b" must be a number')
   })
 
-  it('a schema-invalid call surfaces the structured error on the result', async () => {
+  it('a schema-invalid call APIs the structured error on the result', async () => {
     const ctx = await setup()
     ctx.tools.register(defineContentToolFixture({
       name: 'reader',