Trim redundant source comments

packages/subagent/subagent/src/types.ts

@@ -1,7 +1,5 @@
 /**
- * Subagent seam vocabulary: the request/result/capability types a
- * {@link SubagentProvider} consumes and produces. No runtime code — types
- * only, per the package convention.
+ * Request, result, and capability contracts for {@link SubagentProvider}.
  *
  * @module @deepseek-ai/dsh-subagent/types
  */
@@ -17,7 +15,7 @@ export type SubagentRunId = Branded<'SubagentRunId'>
 
 /**
  * Brand a string as a {@link SubagentRunId}.
- * @param id - the raw id string (the service mints UUIDs; tests may pass fixtures).
+ * @param id - the raw run id.
  * @returns the same string, branded.
  */
 export function SubagentRunId(id: string): SubagentRunId {
@@ -33,13 +31,9 @@ export function SubagentRunId(id: string): SubagentRunId {
  * is the capability.
  */
 export interface SubagentCapabilities {
-  /** Honor {@link SubagentStartRequest.outputSchema} (structured final output). */
   readonly outputSchema: boolean
-  /** Enforce {@link SubagentStartRequest.maxDepth} (recursion cap). */
   readonly depthLimit: boolean
-  /** Enforce {@link SubagentStartRequest.toolFilter} (child tool scoping). */
   readonly toolFilter: boolean
-  /** Honor {@link SubagentStartRequest.persona} (a per-child persona). */
   readonly persona: boolean
 }
 
@@ -50,16 +44,11 @@ export interface SubagentCapabilities {
  * passes it to {@link SubagentProvider.start}.
  */
 export interface SubagentStartRequest {
-  /** The task/prompt for the child agent (a user message in the child session). */
+  /** Content delivered as the child's user message. */
   readonly prompt: ContentBlock[]
   /**
-   * The spawning ("parent") agent — the one whose tool call started this
-   * subagent. REQUIRED: in-process backends read `parent.session.header` for
-   * the working directory, the `parentSession` lineage to stamp on the child,
-   * and the parent's delegation depth. The out-of-process backend (ACP) reads
-   * exactly one field — the session header's cwd, the child's workspace when
-   * no deployment `cwd` override is configured; nothing else crosses the
-   * process boundary.
+   * The spawning agent. In-process providers derive workspace, lineage, and
+   * delegation depth from its durable session state; ACP uses only its cwd.
    */
   readonly parent: Agent
   /**
@@ -70,7 +59,6 @@ export interface SubagentStartRequest {
    * afterward.
    */
   readonly signal: AbortSignal
-  /** Per-child agent options (model and plugin-defined extension fields). */
   readonly agentOptions?: AgentOptions
   /**
    * Object-rooted JSON Schema within `assertObjectJsonSchema`'s enforced subset. Start rejects
@@ -110,15 +98,12 @@ export interface SubagentStartRequest {
  * non-`completed` result to an `isError` tool result.
  */
 export interface SubagentStopReasonMap {
-  /** The child finished its turn normally. */
   completed: 'completed'
-  /** The run was cancelled by its request signal or by disposal. */
+  /** Cancelled through the request signal or disposal. */
   aborted: 'aborted'
-  /** The child failed (model error, transport error). */
+  /** Model or transport failure. */
   error: 'error'
-  /** The child hit its token ceiling before finishing. */
   'max-tokens': 'max-tokens'
-  /** The child declined the task. */
   refusal: 'refusal'
 }
 
@@ -170,9 +155,8 @@ export interface SubagentRun {
    */
   readonly result: Promise<SubagentResult>
   /**
-   * Cancel remaining work, reach child quiescence, and release the run's
-   * resources (in-process: dispose the owned agent and remove its session;
-   * ACP: kill and reap the subprocess). Idempotent.
+   * Cancel remaining work, reach child quiescence, and release resources.
+   * Idempotent.
    */
   dispose(): Promise<void>
   /**
@@ -188,12 +172,9 @@ export interface SubagentRun {
 }
 
 /**
- * A subagent backend: one transport for running a child agent (in-process
- * spawn/fork, ACP to another process, …). Implementations register under a
- * unique name via {@link SubagentService.registerProvider}; multiple providers
- * coexist in one context (unlike the single-implementation bash seam). The
- * Providers are trusted same-process implementations; callers treat their
- * descriptors and returned values as borrowed immutable data.
+ * One registered transport for running child agents. Providers are trusted
+ * same-process implementations; callers treat descriptors and returned values
+ * as borrowed immutable data.
  */
 export interface SubagentProvider {
   /** Unique registry name (e.g. `spawn`, `fork`, `acp`). */