refactor: replace overloaded surface terminology

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
  */