From 12fe458e355115212bc0e53dfec726572a207bcf Mon Sep 17 00:00:00 2001 From: Turtle Date: Sat, 25 Jul 2026 13:31:51 +0800 Subject: [PATCH] Address comment cleanup review --- .agents/skills/dsh-prose-standard/SKILL.md | 2 ++ docs/core-data-structures/subagent.i18n.yaml | 4 ++-- docs/core-data-structures/subagent.md | 5 ++++- docs/core-data-structures/subagent.zh.md | 5 ++++- packages/subagent/subagent/src/types.ts | 5 ++++- 5 files changed, 16 insertions(+), 5 deletions(-) diff --git a/.agents/skills/dsh-prose-standard/SKILL.md b/.agents/skills/dsh-prose-standard/SKILL.md index faf234ae7c..4abf53c8e1 100644 --- a/.agents/skills/dsh-prose-standard/SKILL.md +++ b/.agents/skills/dsh-prose-standard/SKILL.md @@ -7,6 +7,8 @@ description: Use when writing, reviewing, restoring, trimming, or auditing prose Write enough to preserve the contract, then remove reasoning transcripts, repetition, and decoration. This skill owns editorial judgment and required prose coverage; use [dsh-doc-standards](../dsh-doc-standards/SKILL.md) for placement, budgets, bilingual pairs, and documentation gates. It is guidance, not a script. +comment should only describe what is not obvious in the code or not implied by the code. + ## Inputs and exclusions Require an explicit `scope`. If it is missing, report the required input and stop; do not infer a repository-wide scope or begin an interview. diff --git a/docs/core-data-structures/subagent.i18n.yaml b/docs/core-data-structures/subagent.i18n.yaml index fcd9e2f4f7..4aff0dc054 100644 --- a/docs/core-data-structures/subagent.i18n.yaml +++ b/docs/core-data-structures/subagent.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 -subagent.md: fda4b4b738c648c893c65a633e4a0d6a1761424f -subagent.zh.md: ba43789a3e4efe59b197f6454c977db52d90aca1 +subagent.md: b5e041dc54d43dcf3609885cfd3dc2c93fa09f25 +subagent.zh.md: 22fb3cd32bded30beff00a79ed4920ebacdd691a diff --git a/docs/core-data-structures/subagent.md b/docs/core-data-structures/subagent.md index fda4b4b738..b5e041dc54 100644 --- a/docs/core-data-structures/subagent.md +++ b/docs/core-data-structures/subagent.md @@ -19,7 +19,8 @@ A provider advertises its **start-time** features on a static descriptor the ser * is rejected with a typed error rather than accepted-then-ignored (the "fail loud, no silent * degradation" rule). These static flags cover features needed before a run exists; runtime * capabilities such as steering and resume are optional {@link SubagentRun} methods whose presence - * is the capability. + * is the capability. Each flag corresponds one-to-one to a {@link SubagentStartRequest} option: + * `depthLimit` to `maxDepth`; the other names match. */ interface SubagentCapabilities { readonly outputSchema: boolean @@ -125,11 +126,13 @@ interface SubagentResult { * non-`completed` result to an `isError` tool result. */ interface SubagentStopReasonMap { + /** The child finished its turn normally. */ completed: 'completed' /** Cancelled through the request signal or disposal. */ aborted: 'aborted' /** Model or transport failure. */ error: 'error' + /** The child hit its token ceiling before finishing. */ 'max-tokens': 'max-tokens' refusal: 'refusal' } diff --git a/docs/core-data-structures/subagent.zh.md b/docs/core-data-structures/subagent.zh.md index ba43789a3e..22fb3cd32b 100644 --- a/docs/core-data-structures/subagent.zh.md +++ b/docs/core-data-structures/subagent.zh.md @@ -19,7 +19,8 @@ subagent seam：一个 agent（智能体）将工作委派给子 agent。与 [ba * is rejected with a typed error rather than accepted-then-ignored (the "fail loud, no silent * degradation" rule). These static flags cover features needed before a run exists; runtime * capabilities such as steering and resume are optional {@link SubagentRun} methods whose presence - * is the capability. + * is the capability. Each flag corresponds one-to-one to a {@link SubagentStartRequest} option: + * `depthLimit` to `maxDepth`; the other names match. */ interface SubagentCapabilities { readonly outputSchema: boolean @@ -125,11 +126,13 @@ interface SubagentResult { * non-`completed` result to an `isError` tool result. */ interface SubagentStopReasonMap { + /** The child finished its turn normally. */ completed: 'completed' /** Cancelled through the request signal or disposal. */ aborted: 'aborted' /** Model or transport failure. */ error: 'error' + /** The child hit its token ceiling before finishing. */ 'max-tokens': 'max-tokens' refusal: 'refusal' } diff --git a/packages/subagent/subagent/src/types.ts b/packages/subagent/subagent/src/types.ts index d755338a5a..c4445e5d5d 100644 --- a/packages/subagent/subagent/src/types.ts +++ b/packages/subagent/subagent/src/types.ts @@ -28,7 +28,8 @@ export function SubagentRunId(id: string): SubagentRunId { * is rejected with a typed error rather than accepted-then-ignored (the "fail loud, no silent * degradation" rule). These static flags cover features needed before a run exists; runtime * capabilities such as steering and resume are optional {@link SubagentRun} methods whose presence - * is the capability. + * is the capability. Each flag corresponds one-to-one to a {@link SubagentStartRequest} option: + * `depthLimit` to `maxDepth`; the other names match. */ export interface SubagentCapabilities { readonly outputSchema: boolean @@ -98,11 +99,13 @@ export interface SubagentStartRequest { * non-`completed` result to an `isError` tool result. */ export interface SubagentStopReasonMap { + /** The child finished its turn normally. */ completed: 'completed' /** Cancelled through the request signal or disposal. */ aborted: 'aborted' /** Model or transport failure. */ error: 'error' + /** The child hit its token ceiling before finishing. */ 'max-tokens': 'max-tokens' refusal: 'refusal' }