From 11773170f09d0e2261a326cc611b058687b05498 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 21 Jun 2026 00:36:27 +0800 Subject: [PATCH 001/273] docs: propose unstable LLM API recovery RFC --- docs/rfc/README.md | 1 + .../2026-06-21-unstable-llm-api-recovery.md | 154 ++++++++++++++++++ 2 files changed, 155 insertions(+) create mode 100644 docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md diff --git a/docs/rfc/README.md b/docs/rfc/README.md index 3778aaf4ad..64b5743433 100644 --- a/docs/rfc/README.md +++ b/docs/rfc/README.md @@ -65,6 +65,7 @@ Do NOT write one for a mechanical or local choice (a variable name, a one-file r | [Extract a generic long-running tool runtime](proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md) | 2026-06-20 | | [Extract example apps into packages](proposed/architecture/2026-06-20-extract-example-app-packages.md) | 2026-06-20 | | [Branded IDs everywhere they belong](proposed/architecture/2026-06-20-branded-ids.md) | 2026-06-20 | +| [Treat unstable LLM APIs as a first-class failure mode](proposed/architecture/2026-06-21-unstable-llm-api-recovery.md) | 2026-06-21 | ### Process diff --git a/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md b/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md new file mode 100644 index 0000000000..8a498e2e19 --- /dev/null +++ b/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md @@ -0,0 +1,154 @@ +# RFC: Treat unstable LLM APIs as a first-class failure mode + +Status: proposed + +## Problem + +LLM APIs are not a stable local function call. They rate-limit, overload, return 5xx/502/503 from gateways, close streaming sockets before `[DONE]`, emit malformed or provider-specific error payloads, hang mid-stream, surface SDK errors as in-band events, and sometimes require a delayed retry using `Retry-After`. The harness currently contains good error containment, but it does not yet treat this API instability as a first-class design problem. + +`dsh-llm` defines two sanctioned adapter failure paths - throw from `stream()` or end with `finish { kind: 'error' | 'aborted' }` - and the agent loop translates both into a failed step instead of logging a fake completed assistant message. That was the right MVP containment baseline, documented in [the architecture](../../../architecture.md) and reinforced by [the twin-adapter RFC](../../implemented/architecture/2026-06-13-twin-llm-adapters.md). It is not enough for an agent that depends on an unstable remote model API for every turn. + +The audit found four load-bearing gaps. + +- `LlmError` and `FinishReasonMap.error` carry only `message`, `code`, and sometimes HTTP `status` ([packages/llm/llm/src/index.ts](../../../../packages/llm/llm/src/index.ts), [packages/llm/llm/src/types.ts](../../../../packages/llm/llm/src/types.ts)). A caller cannot reliably tell "retry this after 800 ms on the same endpoint", "fail over to another route for the same model", "ask the user for credentials", "never retry because the request is invalid", "provider truncated the stream after committed output", or "adapter protocol bug" without provider-specific heuristics. +- The `llm/stream` waterfall is documented as the place for retry/routing/caching, but its value is one committed `AsyncIterable`. A listener can technically catch an API error and call `next()` again, but once it has yielded any chunks to the agent loop those chunks are already appended as `assistant/chunk` events and emitted to UI. Retrying after that point would concatenate chunks from two provider attempts into one model step, corrupting replay and the user transcript. +- The adapter registry is one adapter per model name. That makes "logical model" and "concrete API route" the same thing, so the service has no vocabulary for "same model through another endpoint or SDK", "same provider region with different health", "fallback route with compatible capabilities", provider request ids, or per-route backoff state. +- Crash recovery and LLM API recovery are easy to conflate. `dsh-session` repairs an interrupted durable log by closing an open turn and synthesizing missing tool results ([packages/core/session/src/repair.ts](../../../../packages/core/session/src/repair.ts)); that preserves already-written work after a process crash. It does not make a failed provider attempt safe to retry, discard, replay, or fail over. + +The result is a system that can survive an unstable LLM API without killing the loop, but cannot make principled recovery decisions. For a coding agent, that is underdesigned: ordinary provider turbulence should not require every UI or product plugin to reinvent retries around an unsafe stream boundary. + +## Proposal + +Introduce an LLM-call v2 contract centered on API-instability recovery: classify provider/API failures, separate provider attempts from committed model output, route logical models through recoverable API routes, and make conservative retry/failover the default behavior in `dsh-llm`. Because the harness is unreleased, this should be a breaking cleanup rather than a compatibility layer around the underspecified v1 surface. + +### 1. Replace flat error codes with a serializable `LlmFailure` + +Keep `HarnessError` as the common thrown-error base, but make LLM failures carry a structured, JSON-serializable payload. `code` remains a stable leaf label for logs and provider-specific matching; retry/failover policy branches on the structured fields. + +```ts ignore-check +type LlmFailureClass = + | 'auth' + | 'rate-limit' + | 'quota' + | 'invalid-request' + | 'unsupported' + | 'timeout' + | 'transport' + | 'provider-overloaded' + | 'provider-unavailable' + | 'provider-bug' + | 'protocol' + | 'safety' + | 'aborted' + | 'unknown' + +type LlmFailurePhase = + | 'request-build' + | 'connect' + | 'response-headers' + | 'stream' + | 'finish' + +interface LlmFailure { + message: string + code: string + class: LlmFailureClass + phase: LlmFailurePhase + retryable: boolean + failover: 'never' | 'same-model' | 'compatible-model' + partialOutput: 'none' | 'uncommitted' | 'committed' + provider?: string + routeId?: string + model?: string + wireModel?: string + status?: number + retryAfterMs?: number + requestId?: string +} +``` + +`LlmError` should carry `failure: LlmFailure`; `FinishReasonMap.error` should carry the same payload instead of a parallel `{ message, code? }` shape. The agent loop should persist the serializable failure fields in `session error` and `turn/end { kind: 'error' }`, while the thrown `LlmError` may still carry a non-serializable `cause` chain for local debugging. + +Adapters are responsible for faithful provider/API classification at their boundary: HTTP status, `Retry-After`, provider request id headers, SDK error type, timeout vs caller abort, malformed SSE, missing `[DONE]`, unknown finish reason, and unsupported local request shape. The current pi-ai adapter's regex over message text is acceptable only as a temporary fallback when the SDK hides the real status; the adapter should prefer structured SDK/provider fields when available. + +### 2. Split provider attempts from committed model output + +Make "attempt" a first-class boundary below `ctx.llm.stream()`. An adapter streams one provider API attempt. The LLM service runs zero or more attempts according to recovery policy and yields only committed output to the agent loop. + +The important invariant: chunks from a failed attempt must never be silently spliced together with chunks from a later attempt as one assistant step. Recovery must choose one of these paths instead: + +- **Retry before commit.** If an API attempt fails before any chunks are committed to the loop, the service may retry or fail over and hide the failed attempt from `assistant/chunk` history, while recording attempt diagnostics separately. +- **Commit and stop retrying.** Once chunks are committed to the loop, the attempt owns the visible step. If it later fails, the step fails with `partialOutput: 'committed'`; automatic retry is not allowed unless a later RFC designs an explicit continuation/repair protocol. +- **Buffered recovery mode.** A caller or policy may choose to buffer an entire attempt until it reaches `finish`, then yield the winning attempt's chunks. This improves retryability against flaky APIs at the cost of live token streaming and should be a deliberate mode, not an accidental side effect. + +This likely means replacing the single overloaded `llm/stream` waterfall with narrower hooks: one around a single provider attempt, one around recovery policy decisions, and one around the committed stream. Names are implementation details for the follow-up PR, but the semantics are not: plugins must be able to wrap "one API attempt" without pretending they can safely retry already-committed chunks. + +### 3. Route logical models through recoverable API routes + +Separate the logical model a caller requests from the concrete provider route that serves an attempt. Replace "one adapter per model name" with route registration, for example: + +```ts ignore-check +ctx.llm.registerRoute({ + routeId: 'deepseek-direct:deepseek-v4-flash', + model: 'deepseek-v4-flash', + wireModel: 'deepseek-v4-flash', + provider: 'deepseek', + adapter, + priority: 0, + capabilities: { tools: true, reasoning: true, images: false, prefill: false }, +}) +``` + +`GenerateOptions.model` remains the logical model. The service resolves it to a route for each API attempt, records the route in failure/attempt diagnostics, and can retry on the same route or fail over to another route with compatible capabilities. Duplicate model names become normal; duplicate route ids are the conflict. This is the smallest vocabulary that can express direct endpoint vs SDK-backed endpoint, regional endpoints, and future fallback models without making every caller own routing. + +### 4. Put default API recovery policy in `dsh-llm` + +Adapters should not perform hidden SDK retries unless those retries are surfaced as attempts with classified failures. The service owns the default policy so every consumer gets the same behavior and the same audit trail. + +Default policy should be conservative: + +- Retry transient API failures (`rate-limit`, `timeout`, `transport`, `provider-overloaded`, `provider-unavailable`) only before committed output. +- Honor `retryAfterMs`, otherwise use bounded exponential backoff with jitter. +- Treat 429/408/409/425/500/502/503/504 and connection resets as potentially recoverable unless the provider payload says otherwise; treat 400/401/403, unsupported local options, caller abort, and adapter protocol bugs as non-retryable. +- Fail over only when the failure says failover is safe and the candidate route advertises compatible capabilities for the request (`tools`, reasoning passback, images, prefill, stop sequences, strict tools). +- Share the caller's `AbortSignal` across the whole recovered call, and expose per-attempt timeouts as explicit policy. A stuck stream must time out in a controlled way instead of hanging the turn forever. +- Bound attempts by count and elapsed time, with clear failure reporting when the budget is exhausted. + +The policy should be configurable through a typed service option and an event/waterfall seam so product plugins can tighten or loosen it, but the default must be safe enough that a basic agent does not need a custom retry plugin to survive ordinary 429/5xx/connectivity noise. + +### 5. Record API attempt diagnostics without polluting derived history + +The session log should be able to explain what happened during a recovered model call without feeding failed attempts back to the model as assistant output. Add turn-enclosed, derive-skipped diagnostics for LLM API attempts, or an equivalent trace surface if we decide session events should stay conversation-only. The data must be JSON-serializable and include attempt number, route id, failure payload, backoff, provider request id, and whether any chunks were committed. + +`assistant/chunk` remains the replay source for the committed attempt only. Hidden failed attempts are diagnostics, not model history. A stream that fails after committed chunks remains replayable as a thrown stream through the existing `llm-replay` sidecar mechanism, but the failure payload should become structured rather than `{ message, code, status? }`. + +## Out of scope + +This RFC does not propose silent mid-stream continuation after user-visible output. That requires a separate model-history design: either provider-supported prefill/continuation, a recovery prompt that explicitly shows the partial assistant output, or a UI affordance that marks the partial answer as failed and asks the model to continue in a new step. Splicing two API attempts into one assistant message is rejected. + +This RFC also does not solve semantic model-output repair: malformed tool-call JSON, refusal handling, or content-filter fallbacks. Those may use the same failure vocabulary later, but they are higher-level agent behaviors, not unstable-API recovery. + +## Acceptance criteria + +- `LlmError` and in-band finish errors carry one structured `LlmFailure` payload; the agent loop persists that payload's serializable fields in error turn data. +- Recovery policy can distinguish retry, failover, credential/user-action, unsupported request, caller abort, adapter/protocol bug, and post-commit partial stream failure without parsing message text. +- The LLM service has an explicit API-attempt boundary; no retry path can append chunks from two provider attempts as one committed assistant step. +- The route registry allows multiple concrete API routes for one logical model and records the selected route on attempts/failures. +- Default recovery retries transient pre-commit failures with bounded backoff, honors provider retry-after hints, times out stuck streams, disables hidden SDK retries or surfaces them as attempts, and never retries after committed chunks without an explicit continuation design. +- Unit tests cover thrown errors and finish-error chunks through the real agent loop, retry-before-first-chunk, failover to a second compatible route, retry budget exhaustion, abort during backoff, stream timeout, and the "partial chunks then failure does not retry/splice" invariant. +- Adapter tests classify representative HTTP statuses, retry-after headers, request ids, malformed/truncated SSE streams, SDK in-stream errors, caller aborts, and unsupported options into `LlmFailure`. +- Snapshot/replay support can faithfully represent a recovered call and a post-commit thrown stream without losing the structured failure payload. +- Docs updated in the same change: [the architecture LLM section](../../../architecture.md), [the LLM adapter cookbook](../../../cookbook/adding-an-llm-adapter.md), and the LLM package READMEs. + +## Risks / what we give up + +- **More surface area in the LLM core.** API recovery adds policy, route state, attempt diagnostics, and tests. That complexity belongs in `dsh-llm` because every consumer otherwise reinvents it around the same unsafe stream boundary. +- **Some modes reduce live streaming.** Buffered recovery trades first-token latency for safe retry. That should be opt-in or policy-driven; the default can still stream eagerly while retrying only before commit. +- **Breaking adapter churn.** Existing adapters will change from "stream chunks or throw a flat `LlmError`" to "stream one classified API attempt." Pre-release rules favor the correct seam over shims. +- **Route compatibility is easy to overclaim.** A route must advertise concrete capabilities, and failover must check the request actually fits them. "Same model name" is not enough when one route lacks strict tools, reasoning passback, images, stop sequences, or prefill. + +## Related + +- Builds on [Provider-neutral content-block vocabulary](../../implemented/architecture/2026-06-11-content-block-vocabulary.md): the content vocabulary stays provider-neutral; this adds a provider-neutral failure/recovery vocabulary beside it. +- Revises the scope implied by [Two LLM adapters as a design-verification twin](../../implemented/architecture/2026-06-13-twin-llm-adapters.md): the twin validated chunk shape and error delivery paths, but it also exposed that delivery paths are not enough for unstable API recovery. +- Extends [Structured error taxonomy](../../implemented/architecture/2026-06-11-structured-error-taxonomy.md): `HarnessError.code` was the foundation; LLM API recovery needs a richer payload because retry/failover policy cannot safely branch on one flat string. From e141ffa27f9c10e8a5157b81805fdd4236991904 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 21 Jun 2026 10:02:35 +0800 Subject: [PATCH 002/273] docs: tighten LLM recovery RFC scope --- .../2026-06-21-unstable-llm-api-recovery.md | 123 ++++++++++++------ 1 file changed, 86 insertions(+), 37 deletions(-) diff --git a/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md b/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md index 8a498e2e19..f5f7659c41 100644 --- a/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md +++ b/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md @@ -6,26 +6,25 @@ Status: proposed LLM APIs are not a stable local function call. They rate-limit, overload, return 5xx/502/503 from gateways, close streaming sockets before `[DONE]`, emit malformed or provider-specific error payloads, hang mid-stream, surface SDK errors as in-band events, and sometimes require a delayed retry using `Retry-After`. The harness currently contains good error containment, but it does not yet treat this API instability as a first-class design problem. -`dsh-llm` defines two sanctioned adapter failure paths - throw from `stream()` or end with `finish { kind: 'error' | 'aborted' }` - and the agent loop translates both into a failed step instead of logging a fake completed assistant message. That was the right MVP containment baseline, documented in [the architecture](../../../architecture.md) and reinforced by [the twin-adapter RFC](../../implemented/architecture/2026-06-13-twin-llm-adapters.md). It is not enough for an agent that depends on an unstable remote model API for every turn. +`dsh-llm` defines two sanctioned adapter failure paths - throw from `stream()` or end with `finish { kind: 'error' | 'aborted' }` - and downstream consumers are expected to treat both as failed model calls. That was the right MVP containment baseline, documented in [the architecture](../../../architecture.md) and reinforced by [the twin-adapter RFC](../../implemented/architecture/2026-06-13-twin-llm-adapters.md). It is not enough for callers that depend on an unstable remote model API for every turn, and it forces every caller to understand two failure delivery mechanisms. -The audit found four load-bearing gaps. +The audit found three load-bearing gaps. - `LlmError` and `FinishReasonMap.error` carry only `message`, `code`, and sometimes HTTP `status` ([packages/llm/llm/src/index.ts](../../../../packages/llm/llm/src/index.ts), [packages/llm/llm/src/types.ts](../../../../packages/llm/llm/src/types.ts)). A caller cannot reliably tell "retry this after 800 ms on the same endpoint", "fail over to another route for the same model", "ask the user for credentials", "never retry because the request is invalid", "provider truncated the stream after committed output", or "adapter protocol bug" without provider-specific heuristics. -- The `llm/stream` waterfall is documented as the place for retry/routing/caching, but its value is one committed `AsyncIterable`. A listener can technically catch an API error and call `next()` again, but once it has yielded any chunks to the agent loop those chunks are already appended as `assistant/chunk` events and emitted to UI. Retrying after that point would concatenate chunks from two provider attempts into one model step, corrupting replay and the user transcript. +- The `llm/stream` waterfall is documented as the place for retry/routing/caching, but its value is one raw `AsyncIterable`. A listener can technically catch an API error and call `next()` again, but once it has yielded chunks, callers may already have rendered them, buffered them as output, or executed side effects based on completed tool calls. Retrying after that point can concatenate chunks from two provider responses into one apparent model output. The current surface has no canonical way to say "the tokens you saw were tentative; this response timed out, so discard them and restart." - The adapter registry is one adapter per model name. That makes "logical model" and "concrete API route" the same thing, so the service has no vocabulary for "same model through another endpoint or SDK", "same provider region with different health", "fallback route with compatible capabilities", provider request ids, or per-route backoff state. -- Crash recovery and LLM API recovery are easy to conflate. `dsh-session` repairs an interrupted durable log by closing an open turn and synthesizing missing tool results ([packages/core/session/src/repair.ts](../../../../packages/core/session/src/repair.ts)); that preserves already-written work after a process crash. It does not make a failed provider attempt safe to retry, discard, replay, or fail over. -The result is a system that can survive an unstable LLM API without killing the loop, but cannot make principled recovery decisions. For a coding agent, that is underdesigned: ordinary provider turbulence should not require every UI or product plugin to reinvent retries around an unsafe stream boundary. +The result is a package that can surface an unstable LLM API failure, but cannot make principled recovery decisions for its callers. Ordinary provider turbulence should not require every consumer to reinvent retries around an unsafe stream boundary. ## Proposal -Introduce an LLM-call v2 contract centered on API-instability recovery: classify provider/API failures, separate provider attempts from committed model output, route logical models through recoverable API routes, and make conservative retry/failover the default behavior in `dsh-llm`. Because the harness is unreleased, this should be a breaking cleanup rather than a compatibility layer around the underspecified v1 surface. +Introduce an LLM-call v2 contract centered on API-instability recovery: classify provider/API failures, separate provider responses from committed model output, route logical models through recoverable API routes, and make conservative retry/failover the default behavior in `dsh-llm`. Because the harness is unreleased, this should be a breaking cleanup rather than a compatibility layer around the underspecified v1 surface. ### 1. Replace flat error codes with a serializable `LlmFailure` Keep `HarnessError` as the common thrown-error base, but make LLM failures carry a structured, JSON-serializable payload. `code` remains a stable leaf label for logs and provider-specific matching; retry/failover policy branches on the structured fields. -```ts ignore-check +```ts type LlmFailureClass = | 'auth' | 'rate-limit' @@ -67,25 +66,46 @@ interface LlmFailure { } ``` -`LlmError` should carry `failure: LlmFailure`; `FinishReasonMap.error` should carry the same payload instead of a parallel `{ message, code? }` shape. The agent loop should persist the serializable failure fields in `session error` and `turn/end { kind: 'error' }`, while the thrown `LlmError` may still carry a non-serializable `cause` chain for local debugging. +`LlmError` should carry `failure: LlmFailure`; `FinishReasonMap.error` should carry the same payload instead of a parallel `{ message, code? }` shape. Adapter-thrown errors and in-band finish errors are input forms to the recovery layer. The public lifecycle stream should convert classified LLM API failures into terminal lifecycle events rather than requiring callers to catch thrown provider errors. The failure payload is serializable so callers can log or persist it if they choose, while the internal thrown `LlmError` may still carry a non-serializable `cause` chain for local debugging. Adapters are responsible for faithful provider/API classification at their boundary: HTTP status, `Retry-After`, provider request id headers, SDK error type, timeout vs caller abort, malformed SSE, missing `[DONE]`, unknown finish reason, and unsupported local request shape. The current pi-ai adapter's regex over message text is acceptable only as a temporary fallback when the SDK hides the real status; the adapter should prefer structured SDK/provider fields when available. -### 2. Split provider attempts from committed model output +### 2. Split provider responses from committed model output -Make "attempt" a first-class boundary below `ctx.llm.stream()`. An adapter streams one provider API attempt. The LLM service runs zero or more attempts according to recovery policy and yields only committed output to the agent loop. +Make "response" a first-class boundary in `ctx.llm.stream()`. An adapter streams one provider API response. The LLM service runs zero or more responses according to recovery policy and exposes one canonical response-lifecycle stream to consumers. Convenience APIs may expose a committed-or-failed result for simple callers, but that result must be derived from the lifecycle stream, not a parallel contract. -The important invariant: chunks from a failed attempt must never be silently spliced together with chunks from a later attempt as one assistant step. Recovery must choose one of these paths instead: +The primary response id is generated by the harness before the adapter call starts. Provider response ids and request ids are metadata attached when known; they are not the primary key because providers may omit them, report them only after the stream starts, reuse them in surprising ways, or fail before one exists. -- **Retry before commit.** If an API attempt fails before any chunks are committed to the loop, the service may retry or fail over and hide the failed attempt from `assistant/chunk` history, while recording attempt diagnostics separately. -- **Commit and stop retrying.** Once chunks are committed to the loop, the attempt owns the visible step. If it later fails, the step fails with `partialOutput: 'committed'`; automatic retry is not allowed unless a later RFC designs an explicit continuation/repair protocol. -- **Buffered recovery mode.** A caller or policy may choose to buffer an entire attempt until it reaches `finish`, then yield the winning attempt's chunks. This improves retryability against flaky APIs at the cost of live token streaming and should be a deliberate mode, not an accidental side effect. +The important invariant: chunks from a failed response must never be silently spliced together with chunks from a later response as one apparent model result. Token deltas from a response are tentative until that response reaches a committing terminal finish (`stop`, `tool-calls`, or `max-tokens`). The lifecycle stream must be able to report that tentative tokens were shown live, then discarded because the response timed out, disconnected, or otherwise failed before commit. -This likely means replacing the single overloaded `llm/stream` waterfall with narrower hooks: one around a single provider attempt, one around recovery policy decisions, and one around the committed stream. Names are implementation details for the follow-up PR, but the semantics are not: plugins must be able to wrap "one API attempt" without pretending they can safely retry already-committed chunks. +The event vocabulary should keep the familiar `assistant/chunk` concept but stop pretending every chunk is already final output. A possible spelling is: + +```ts ignore-check +type LlmStreamEvent = + | { type: 'response/start'; responseId: ResponseId; responseIndex: number; routeId: string } + | { type: 'assistant/chunk'; responseId: ResponseId; commitment: 'uncommitted'; chunk: StreamChunk } + | { type: 'response/interrupted'; responseId: ResponseId; failure: LlmFailure; scheduledRetryMs?: number } + | { type: 'response/failed'; responseId?: ResponseId; failure: LlmFailure } + | { type: 'response/committed'; responseId: ResponseId; message: Message; finish: FinishReason; usage?: TokenUsage } + +type GenerateOutcome = + | { type: 'committed'; responseId: ResponseId; message: Message; finish: FinishReason; usage?: TokenUsage } + | { type: 'failed'; responseId?: ResponseId; failure: LlmFailure } +``` + +The implementation may choose the exact names, but the type shape should make the state transition obvious: assistant chunks start uncommitted, then the enclosing response becomes interrupted/discarded, failed, or committed. + +- **Lifecycle assistant chunks.** The lifecycle stream should make the old ambiguity explicit: these events are assistant chunk messages, but each one belongs to a response and has a commitment state. Most arrive as uncommitted live UI state; a response that fails before commit marks them interrupted/discarded, and a response that reaches a committing finish lets the UI mark that response committed. +- **Retry before commit.** If an API response fails before a committing finish, the service may retry or fail over and exclude the failed response from the committed result, while surfacing response diagnostics separately. +- **Commit on terminal finish.** Once a response reaches a committing finish, the response owns the visible result. `dsh-llm` emits a `response/committed` event carrying the fully assembled assistant `Message`, final `FinishReason`, usage, and response metadata. Callers that persist messages, execute tool calls, or otherwise take side effects should use this committed event rather than rebuilding output from lifecycle chunks. +- **Terminal failure.** If recovery reaches a non-retryable failure, is aborted by the caller, or otherwise stops without a committing finish, `dsh-llm` emits `response/failed` carrying the final `LlmFailure` and ends the lifecycle stream normally. Throwing is reserved for defects outside the classified LLM API failure contract. +- **Fail after commit.** If a later failure is ever observable after commit, the lifecycle reports `response/failed` with `partialOutput: 'committed'`; automatic retry is not allowed unless a later RFC designs an explicit continuation/repair protocol. + +This means replacing the single overloaded raw-chunk `llm/stream` waterfall with a lifecycle stream and narrower hooks: one around a single provider response, one around recovery policy decisions, and one around convenience APIs that only expose the terminal outcome. Names are implementation details for the follow-up PR, but the semantics are not: plugins must be able to wrap "one API response" without pretending they can safely retry already-committed chunks. ### 3. Route logical models through recoverable API routes -Separate the logical model a caller requests from the concrete provider route that serves an attempt. Replace "one adapter per model name" with route registration, for example: +Separate the logical model a caller requests from the concrete provider route that serves a response. Replace "one adapter per model name" with route registration, for example: ```ts ignore-check ctx.llm.registerRoute({ @@ -99,52 +119,81 @@ ctx.llm.registerRoute({ }) ``` -`GenerateOptions.model` remains the logical model. The service resolves it to a route for each API attempt, records the route in failure/attempt diagnostics, and can retry on the same route or fail over to another route with compatible capabilities. Duplicate model names become normal; duplicate route ids are the conflict. This is the smallest vocabulary that can express direct endpoint vs SDK-backed endpoint, regional endpoints, and future fallback models without making every caller own routing. +`GenerateOptions.model` remains the logical model. The service resolves it to a route for each API response, records the route in failure/response diagnostics, and can retry on the same route or fail over to another route with compatible capabilities. Duplicate model names become normal; duplicate route ids are the conflict. This is the smallest vocabulary that can express direct endpoint vs SDK-backed endpoint, regional endpoints, and future fallback models without making every caller own routing. ### 4. Put default API recovery policy in `dsh-llm` -Adapters should not perform hidden SDK retries unless those retries are surfaced as attempts with classified failures. The service owns the default policy so every consumer gets the same behavior and the same audit trail. +Adapters should not perform hidden SDK retries unless those retries are surfaced as response lifecycle events with classified failures. The service owns the default policy so every consumer gets the same behavior and the same audit trail. Default policy should be conservative: -- Retry transient API failures (`rate-limit`, `timeout`, `transport`, `provider-overloaded`, `provider-unavailable`) only before committed output. -- Honor `retryAfterMs`, otherwise use bounded exponential backoff with jitter. +- Retry transient API failures (`rate-limit`, `timeout`, `transport`, `provider-overloaded`, `provider-unavailable`) only before committed output, and keep retrying until the caller aborts or the failure class changes to a non-retryable one. +- Honor `retryAfterMs` up to `maxRetryDelayMs`, otherwise use bounded exponential backoff with jitter. The same cap applies to both provider-supplied retry hints and ordinary exponential backoff; diagnostics record whether the delay source was `provider-retry-after` or `exponential-backoff`. - Treat 429/408/409/425/500/502/503/504 and connection resets as potentially recoverable unless the provider payload says otherwise; treat 400/401/403, unsupported local options, caller abort, and adapter protocol bugs as non-retryable. - Fail over only when the failure says failover is safe and the candidate route advertises compatible capabilities for the request (`tools`, reasoning passback, images, prefill, stop sequences, strict tools). -- Share the caller's `AbortSignal` across the whole recovered call, and expose per-attempt timeouts as explicit policy. A stuck stream must time out in a controlled way instead of hanging the turn forever. -- Bound attempts by count and elapsed time, with clear failure reporting when the budget is exhausted. +- Share the caller's `AbortSignal` across the whole recovered call, and expose per-response timeouts as explicit policy. A stuck stream must time out in a controlled way instead of hanging the turn forever. +- Surface every retry decision to the UI with retry count, backoff delay, route, and failure summary, so an actively watching user can tell the agent is waiting on provider capacity instead of frozen. -The policy should be configurable through a typed service option and an event/waterfall seam so product plugins can tighten or loosen it, but the default must be safe enough that a basic agent does not need a custom retry plugin to survive ordinary 429/5xx/connectivity noise. +The policy should be configurable through a typed service option and an event/waterfall seam so product plugins can adjust timing/backoff details, but the default retry posture is not opt-in: a basic agent should keep recovering from retryable 429/5xx/connectivity noise until cancelled. -### 5. Record API attempt diagnostics without polluting derived history +The zero-config defaults should be sensible production behavior, not placeholders: -The session log should be able to explain what happened during a recovered model call without feeding failed attempts back to the model as assistant output. Add turn-enclosed, derive-skipped diagnostics for LLM API attempts, or an equivalent trace surface if we decide session events should stay conversation-only. The data must be JSON-serializable and include attempt number, route id, failure payload, backoff, provider request id, and whether any chunks were committed. +```ts +const defaultLlmRecoveryConfig = { + maxResponses: 'unbounded', + maxElapsedMs: 'unbounded', + connectTimeoutMs: 15_000, + responseHeaderTimeoutMs: 60_000, + streamIdleTimeoutMs: 5 * 60_000, + initialBackoffMs: 200, + maxRetryDelayMs: 10 * 60_000, + jitterRatio: 0.1, +} +``` -`assistant/chunk` remains the replay source for the committed attempt only. Hidden failed attempts are diagnostics, not model history. A stream that fails after committed chunks remains replayable as a thrown stream through the existing `llm-replay` sidecar mechanism, but the failure payload should become structured rather than `{ message, code, status? }`. +The retry-delay cap is deliberate. The survey found mixed precedent: Codex parses retry delays out of streamed OpenAI rate-limit error messages and uses that requested delay, but Codex also has finite stream retry counts; the official OpenAI and Anthropic TypeScript SDKs parse `retry-after-ms`, `Retry-After` seconds, and `Retry-After` dates and then sleep for the provider-specified duration; the official OpenAI and Anthropic Python SDKs only honor `Retry-After` when it is greater than zero and at most 60 seconds, otherwise falling back to ordinary exponential backoff. Because this RFC's default retry posture is unbounded, blindly honoring a multi-hour provider delay can make the agent look dead, while ignoring the hint entirely can retry too aggressively. The service should therefore record both `providerRetryAfterMs` and `scheduledRetryMs`, cap the scheduled sleep at `maxRetryDelayMs`, and surface that choice to the UI. + +The service cannot reliably infer whether the user is actively watching or away from the keyboard, so the default should not fail a retryable model call merely because a short interactive budget expired. A clear UI can make long waits tolerable even in interactive sessions: "retried 8 times; next retry in 10 minutes" is better than silently failing recoverable provider turbulence and asking the user to resubmit. + +### 5. Define the caller contract, not the product transcript + +This RFC is deliberately about the `dsh-llm` API and how callers use it, not about the final transcript/event architecture of the product. The LLM package should guarantee these caller-visible semantics: + +- `ctx.llm.stream()` is the live response-lifecycle API. It reports response starts, uncommitted assistant chunks, retries/backoff, interruptions/discards, terminal failures, and the one committed result. +- `response/committed` is the only event that makes model output safe for history or side effects. It carries the assembled `Message`, finish reason, usage, response id, route metadata, and provider ids known to the service. +- `response/failed` is the terminal event for classified failures. Callers should not need `try`/`catch` to learn that a provider was rate-limited, unavailable, misconfigured, aborted, or otherwise unable to produce a committed response. +- Response diagnostics are JSON-serializable so callers can store, display, or ignore them. The LLM package does not decide whether those diagnostics become session events, agent events, telemetry rows, or UI-only state. +- Convenience helpers such as `generate()` return a terminal union (`committed` or `failed`) rather than throwing for classified LLM failures. They must be derived from the lifecycle stream so recovery semantics stay single-sourced. + +The session log shape, agent event taxonomy, ACP rendering, snapshot/replay fixtures, and whether live uncommitted chunks are ever durably recorded are downstream integration decisions. This RFC should constrain them only by the LLM API contract above. ## Out of scope -This RFC does not propose silent mid-stream continuation after user-visible output. That requires a separate model-history design: either provider-supported prefill/continuation, a recovery prompt that explicitly shows the partial assistant output, or a UI affordance that marks the partial answer as failed and asks the model to continue in a new step. Splicing two API attempts into one assistant message is rejected. +This RFC does not propose silent mid-stream continuation after user-visible output. That requires a separate model-history design: either provider-supported prefill/continuation, a recovery prompt that explicitly shows the partial assistant output, or a UI affordance that marks the partial answer as failed and asks the model to continue in a new step. Splicing two API responses into one assistant message is rejected. This RFC also does not solve semantic model-output repair: malformed tool-call JSON, refusal handling, or content-filter fallbacks. Those may use the same failure vocabulary later, but they are higher-level agent behaviors, not unstable-API recovery. +This RFC does not decide whether product UIs consume LLM lifecycle events directly, through agent events, or through session events. It also does not decide which response diagnostics belong in the durable session log. Those decisions belong in narrower integration RFCs once the `dsh-llm` contract exists. + ## Acceptance criteria -- `LlmError` and in-band finish errors carry one structured `LlmFailure` payload; the agent loop persists that payload's serializable fields in error turn data. +- Adapter-thrown `LlmError`s and in-band finish errors carry one structured, JSON-serializable `LlmFailure` payload. - Recovery policy can distinguish retry, failover, credential/user-action, unsupported request, caller abort, adapter/protocol bug, and post-commit partial stream failure without parsing message text. -- The LLM service has an explicit API-attempt boundary; no retry path can append chunks from two provider attempts as one committed assistant step. -- The route registry allows multiple concrete API routes for one logical model and records the selected route on attempts/failures. -- Default recovery retries transient pre-commit failures with bounded backoff, honors provider retry-after hints, times out stuck streams, disables hidden SDK retries or surfaces them as attempts, and never retries after committed chunks without an explicit continuation design. -- Unit tests cover thrown errors and finish-error chunks through the real agent loop, retry-before-first-chunk, failover to a second compatible route, retry budget exhaustion, abort during backoff, stream timeout, and the "partial chunks then failure does not retry/splice" invariant. +- `ctx.llm.stream()` exposes the response lifecycle as the canonical stream, including terminal `response/failed` events for classified failures; convenience APIs are derived views for callers that only want the terminal outcome. +- `response/committed` carries the assembled assistant `Message`; callers do not need to rebuild committed output from lifecycle chunks. +- `generate()` returns a committed/failed union derived from the lifecycle stream, rather than throwing for classified LLM failures. +- The LLM service has an explicit API-response boundary; no retry path can present output from two provider responses as one committed assistant result. +- The route registry allows multiple concrete API routes for one logical model and records the selected route on responses/failures. +- Default recovery retries transient pre-commit failures with bounded backoff, honors provider retry-after hints, times out stuck streams, disables hidden SDK retries or surfaces them as response lifecycle events, and never retries after committed chunks without an explicit continuation design. +- Unit tests cover thrown errors and finish-error chunks through `dsh-llm`, retry-before-first-commit, failover to a second compatible route, unbounded retry status/backoff visibility, abort during backoff, stream timeout, and the "partial chunks then failure does not retry/splice" invariant. - Adapter tests classify representative HTTP statuses, retry-after headers, request ids, malformed/truncated SSE streams, SDK in-stream errors, caller aborts, and unsupported options into `LlmFailure`. -- Snapshot/replay support can faithfully represent a recovered call and a post-commit thrown stream without losing the structured failure payload. -- Docs updated in the same change: [the architecture LLM section](../../../architecture.md), [the LLM adapter cookbook](../../../cookbook/adding-an-llm-adapter.md), and the LLM package READMEs. +- Docs updated in the same change: [the architecture LLM section](../../../architecture.md), [the LLM adapter cookbook](../../../cookbook/adding-an-llm-adapter.md), and the LLM package README. ## Risks / what we give up -- **More surface area in the LLM core.** API recovery adds policy, route state, attempt diagnostics, and tests. That complexity belongs in `dsh-llm` because every consumer otherwise reinvents it around the same unsafe stream boundary. -- **Some modes reduce live streaming.** Buffered recovery trades first-token latency for safe retry. That should be opt-in or policy-driven; the default can still stream eagerly while retrying only before commit. -- **Breaking adapter churn.** Existing adapters will change from "stream chunks or throw a flat `LlmError`" to "stream one classified API attempt." Pre-release rules favor the correct seam over shims. +- **More surface area in the LLM core.** API recovery adds policy, route state, response diagnostics, and tests. That complexity belongs in `dsh-llm` because every consumer otherwise reinvents it around the same unsafe stream boundary. +- **Committed result lags live UI.** Safe recovery means callers cannot treat streamed tokens as final assistant output until the response commits. UIs can still stream eagerly from lifecycle assistant chunks, but side-effecting consumers must wait for `response/committed`. +- **Breaking adapter churn.** Existing adapters will change from "stream chunks or throw a flat `LlmError`" to "stream one classified API response." Pre-release rules favor the correct seam over shims. - **Route compatibility is easy to overclaim.** A route must advertise concrete capabilities, and failover must check the request actually fits them. "Same model name" is not enough when one route lacks strict tools, reasoning passback, images, stop sequences, or prefill. ## Related From 133f37584f1e9ad13796a0cd3f7c11b6d143f931 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 21 Jun 2026 10:23:16 +0800 Subject: [PATCH 003/273] docs: reconcile LLM recovery RFC with sibling PRs --- .../2026-06-21-unstable-llm-api-recovery.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md b/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md index f5f7659c41..1f8f300509 100644 --- a/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md +++ b/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md @@ -88,7 +88,7 @@ type LlmStreamEvent = | { type: 'response/failed'; responseId?: ResponseId; failure: LlmFailure } | { type: 'response/committed'; responseId: ResponseId; message: Message; finish: FinishReason; usage?: TokenUsage } -type GenerateOutcome = +type LlmCallOutcome = | { type: 'committed'; responseId: ResponseId; message: Message; finish: FinishReason; usage?: TokenUsage } | { type: 'failed'; responseId?: ResponseId; failure: LlmFailure } ``` @@ -121,6 +121,10 @@ ctx.llm.registerRoute({ `GenerateOptions.model` remains the logical model. The service resolves it to a route for each API response, records the route in failure/response diagnostics, and can retry on the same route or fail over to another route with compatible capabilities. Duplicate model names become normal; duplicate route ids are the conflict. This is the smallest vocabulary that can express direct endpoint vs SDK-backed endpoint, regional endpoints, and future fallback models without making every caller own routing. +The route registry must keep the lifecycle guarantees of the current adapter registry: `registerRoute()` is effect-scoped, returns a disposer, and has an HMR-safety test proving disposal removes the route. It should not preserve `llm/adapter-change`; if [PR #82](https://github.com/deepseek-ai/deepseek-harness/pull/82) lands first, that event is already gone, and the route registry should not reintroduce it without a concrete consumer. + +The new ids should follow the branded-id policy. `ResponseId`, `RouteId`, and the logical/wire model ids cross package boundaries and are easy to swap accidentally, so the implementation should deliberately brand or explicitly decline to brand each one in line with `2026-06-20-branded-ids` and its implementation stack ([PR #84](https://github.com/deepseek-ai/deepseek-harness/pull/84)). + ### 4. Put default API recovery policy in `dsh-llm` Adapters should not perform hidden SDK retries unless those retries are surfaced as response lifecycle events with classified failures. The service owns the default policy so every consumer gets the same behavior and the same audit trail. @@ -163,9 +167,9 @@ This RFC is deliberately about the `dsh-llm` API and how callers use it, not abo - `response/committed` is the only event that makes model output safe for history or side effects. It carries the assembled `Message`, finish reason, usage, response id, route metadata, and provider ids known to the service. - `response/failed` is the terminal event for classified failures. Callers should not need `try`/`catch` to learn that a provider was rate-limited, unavailable, misconfigured, aborted, or otherwise unable to produce a committed response. - Response diagnostics are JSON-serializable so callers can store, display, or ignore them. The LLM package does not decide whether those diagnostics become session events, agent events, telemetry rows, or UI-only state. -- Convenience helpers such as `generate()` return a terminal union (`committed` or `failed`) rather than throwing for classified LLM failures. They must be derived from the lifecycle stream so recovery semantics stay single-sourced. +- Any assembled convenience helper that survives or is reintroduced returns a terminal union (`committed` or `failed`) rather than throwing for classified LLM failures. It must be derived from the lifecycle stream so recovery semantics stay single-sourced. -The session log shape, agent event taxonomy, ACP rendering, snapshot/replay fixtures, and whether live uncommitted chunks are ever durably recorded are downstream integration decisions. This RFC should constrain them only by the LLM API contract above. +The session log shape, agent event taxonomy, ACP rendering, snapshot/replay fixtures, and whether live uncommitted chunks are ever durably recorded are downstream integration decisions. So is the fate of today's assembled public helper methods: [PR #82](https://github.com/deepseek-ai/deepseek-harness/pull/82) implements the proposed removal of `generate()`, `streamBlocks()`, `GenerateResult`, and `llm/generate`, and this RFC should not resurrect them without a real caller. This RFC should constrain downstream work only by the LLM API contract above. ## Out of scope @@ -181,9 +185,11 @@ This RFC does not decide whether product UIs consume LLM lifecycle events direct - Recovery policy can distinguish retry, failover, credential/user-action, unsupported request, caller abort, adapter/protocol bug, and post-commit partial stream failure without parsing message text. - `ctx.llm.stream()` exposes the response lifecycle as the canonical stream, including terminal `response/failed` events for classified failures; convenience APIs are derived views for callers that only want the terminal outcome. - `response/committed` carries the assembled assistant `Message`; callers do not need to rebuild committed output from lifecycle chunks. -- `generate()` returns a committed/failed union derived from the lifecycle stream, rather than throwing for classified LLM failures. +- Any assembled convenience API that survives or is reintroduced returns a committed/failed union derived from the lifecycle stream, rather than throwing for classified LLM failures. - The LLM service has an explicit API-response boundary; no retry path can present output from two provider responses as one committed assistant result. - The route registry allows multiple concrete API routes for one logical model and records the selected route on responses/failures. +- `registerRoute()` is effect-scoped, returns a disposer, and has an HMR-safety test proving route cleanup; `llm/adapter-change` is not reintroduced unless a concrete consumer needs it. +- New LLM ids are deliberately branded or explicitly left unbranded according to the branded-id policy, with `ResponseId`, `RouteId`, and logical/wire model ids decided together. - Default recovery retries transient pre-commit failures with bounded backoff, honors provider retry-after hints, times out stuck streams, disables hidden SDK retries or surfaces them as response lifecycle events, and never retries after committed chunks without an explicit continuation design. - Unit tests cover thrown errors and finish-error chunks through `dsh-llm`, retry-before-first-commit, failover to a second compatible route, unbounded retry status/backoff visibility, abort during backoff, stream timeout, and the "partial chunks then failure does not retry/splice" invariant. - Adapter tests classify representative HTTP statuses, retry-after headers, request ids, malformed/truncated SSE streams, SDK in-stream errors, caller aborts, and unsupported options into `LlmFailure`. @@ -201,3 +207,5 @@ This RFC does not decide whether product UIs consume LLM lifecycle events direct - Builds on [Provider-neutral content-block vocabulary](../../implemented/architecture/2026-06-11-content-block-vocabulary.md): the content vocabulary stays provider-neutral; this adds a provider-neutral failure/recovery vocabulary beside it. - Revises the scope implied by [Two LLM adapters as a design-verification twin](../../implemented/architecture/2026-06-13-twin-llm-adapters.md): the twin validated chunk shape and error delivery paths, but it also exposed that delivery paths are not enough for unstable API recovery. - Extends [Structured error taxonomy](../../implemented/architecture/2026-06-11-structured-error-taxonomy.md): `HarnessError.code` was the foundation; LLM API recovery needs a richer payload because retry/failover policy cannot safely branch on one flat string. +- Coordinates with [PR #82](https://github.com/deepseek-ai/deepseek-harness/pull/82), which implements the `drop-unconsumed-llm-assembled-surfaces` and `drop-unconsumed-llm-adapter-change-event` simplification RFCs. If that PR lands first, this RFC starts from a narrower `dsh-llm`: no `generate()`, no `streamBlocks()`, no `GenerateResult`, no `llm/generate`, and no `llm/adapter-change`. Recovery should build on that baseline rather than revive removed convenience or change-notification surfaces speculatively. +- Coordinates with [PR #84](https://github.com/deepseek-ai/deepseek-harness/pull/84), which implements the branded-id RFC. The new response/route/model ids introduced here are exactly the sort of cross-boundary ids that need an explicit branding decision before implementation. From 5716fab2c5499ec2f4bbed80eb64bc6f1f82b6bf Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 21 Jun 2026 10:27:53 +0800 Subject: [PATCH 004/273] docs: note in-flight RFC implementation stack --- .../architecture/2026-06-21-unstable-llm-api-recovery.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md b/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md index 1f8f300509..c1fc8703c8 100644 --- a/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md +++ b/docs/rfc/proposed/architecture/2026-06-21-unstable-llm-api-recovery.md @@ -171,6 +171,8 @@ This RFC is deliberately about the `dsh-llm` API and how callers use it, not abo The session log shape, agent event taxonomy, ACP rendering, snapshot/replay fixtures, and whether live uncommitted chunks are ever durably recorded are downstream integration decisions. So is the fate of today's assembled public helper methods: [PR #82](https://github.com/deepseek-ai/deepseek-harness/pull/82) implements the proposed removal of `generate()`, `streamBlocks()`, `GenerateResult`, and `llm/generate`, and this RFC should not resurrect them without a real caller. This RFC should constrain downstream work only by the LLM API contract above. +The current simplification stack was checked while drafting this proposal. [PR #83](https://github.com/deepseek-ai/deepseek-harness/pull/83) and [PR #85](https://github.com/deepseek-ai/deepseek-harness/pull/85) do not change this RFC's LLM API assumptions. [PR #86](https://github.com/deepseek-ai/deepseek-harness/pull/86) does matter for later integration because it folds durable token usage onto `assistant/message` and operational errors onto `turn/end.reason`; if it lands first, the LLM recovery implementation should still stop at the `dsh-llm` lifecycle contract here and let the agent/session layer decide how committed usage and terminal failures map onto those load-bearing product events. + ## Out of scope This RFC does not propose silent mid-stream continuation after user-visible output. That requires a separate model-history design: either provider-supported prefill/continuation, a recovery prompt that explicitly shows the partial assistant output, or a UI affordance that marks the partial answer as failed and asks the model to continue in a new step. Splicing two API responses into one assistant message is rejected. @@ -208,4 +210,6 @@ This RFC does not decide whether product UIs consume LLM lifecycle events direct - Revises the scope implied by [Two LLM adapters as a design-verification twin](../../implemented/architecture/2026-06-13-twin-llm-adapters.md): the twin validated chunk shape and error delivery paths, but it also exposed that delivery paths are not enough for unstable API recovery. - Extends [Structured error taxonomy](../../implemented/architecture/2026-06-11-structured-error-taxonomy.md): `HarnessError.code` was the foundation; LLM API recovery needs a richer payload because retry/failover policy cannot safely branch on one flat string. - Coordinates with [PR #82](https://github.com/deepseek-ai/deepseek-harness/pull/82), which implements the `drop-unconsumed-llm-assembled-surfaces` and `drop-unconsumed-llm-adapter-change-event` simplification RFCs. If that PR lands first, this RFC starts from a narrower `dsh-llm`: no `generate()`, no `streamBlocks()`, no `GenerateResult`, no `llm/generate`, and no `llm/adapter-change`. Recovery should build on that baseline rather than revive removed convenience or change-notification surfaces speculatively. +- Is orthogonal to [PR #81](https://github.com/deepseek-ai/deepseek-harness/pull/81), which proposes provider-request app attribution headers. Recovery route metadata and provider request construction can carry attribution policy later, but this RFC does not define request headers. - Coordinates with [PR #84](https://github.com/deepseek-ai/deepseek-harness/pull/84), which implements the branded-id RFC. The new response/route/model ids introduced here are exactly the sort of cross-boundary ids that need an explicit branding decision before implementation. +- Coordinates with [PR #86](https://github.com/deepseek-ai/deepseek-harness/pull/86), which implements the `collapse-trace-only-session-events` simplification RFC. If that stack lands first, downstream recovery integration should map committed usage and terminal error facts onto the surviving load-bearing session events instead of reintroducing standalone trace-only records from inside `dsh-llm`. From f7b990bd5c711a29c560cd567c91e50c5cb7f310 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sun, 12 Jul 2026 22:09:53 +0800 Subject: [PATCH 005/273] docs(rfc): propose the scoped-layers store --- docs/rfc/INDEX.md | 1 + .../2026-07-12-scoped-layers-store.i18n.yaml | 6 + .../2026-07-12-scoped-layers-store.md | 139 ++++++++++++++++++ .../2026-07-12-scoped-layers-store.zh.md | 139 ++++++++++++++++++ 4 files changed, 285 insertions(+) create mode 100644 docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml create mode 100644 docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md create mode 100644 docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index 5e508344fa..9596aecd78 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -24,6 +24,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; |---|---| | [Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern)](proposed/architecture/2026-06-16-typed-event-schemas.md) | 2026-06-16 | | [Extract a generic long-running tool runtime](proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md) | 2026-06-20 | +| [Scoped-layers store — one aggregate layer per scope behind a scheduling helper](proposed/architecture/2026-07-12-scoped-layers-store.md) | 2026-07-12 | ### Process diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml new file mode 100644 index 0000000000..f868cfc669 --- /dev/null +++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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 +2026-07-12-scoped-layers-store.md: 0673d6c63291a66c84e91f2eff8eca26798b931f +2026-07-12-scoped-layers-store.zh.md: 6460802f3cf3163f6be2ad51f2f82319a04288bc diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md new file mode 100644 index 0000000000..0673d6c632 --- /dev/null +++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md @@ -0,0 +1,139 @@ +# RFC: Scoped-layers store — one aggregate layer per scope behind a scheduling helper + +Status: proposed + +English | [中文](2026-07-12-scoped-layers-store.zh.md) + +## Problem + +Agent scoping ([the agent-scope RFC](../../implemented/architecture/2026-07-08-agent-scope-contexts.md), [runtime design](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)) made "a registry with a global layer plus per-agent layers" a recurring shape, and every occurrence is hand-written. Seven registration sites exist today — `tools.register`/`tools.restrict`/`tools.guard` in `dsh-tools` and `section`/`tools`/`variable`/`protect` in `dsh-system-prompt` — each pairing a global container with its own `Map` and repeating the same 10-15-line effect choreography: read the calling context's tag, get-or-create the layer, validate, mutate, yield a rollback that deletes the entry, reclaims the emptied layer, and emits the change event, then emit and return the exact cordis effect disposer. + +Beyond the duplication, the risk concentrates in the choreography details: +- The rollback must be collected before the change emit (so a throwing listener unwinds the insertion instead of leaking it) +- The returned disposer must be cordis's own function (a wrapper silently breaks nested ordered teardown) +- Emptied scoped layers must be reclaimed (a disposed agent must not leave residue keyed by its dead `ScopeKey`) + +Every new consumer has to rewrite all of that correctly, and the copies have already diverged stylistically — two private `layerFor` helpers in `dsh-tools`, four inline IIFEs in `dsh-system-prompt`. + +Finally, one agent's contribution to one service is scattered across several maps that know nothing of each other — there is no object that means "what this scope contributes here" — and the consumer count keeps growing: guards and prompt protections landed recently, and per-agent `fs/*` policy, `llm/*` overrides, and per-agent compaction policy are all queued on the same pattern. + +## Proposal + +`dsh-scope` gains a store module (a new `store.ts` under its `src/`, peer-dependent on cordis only, key-agnostic) built around one division of labor: **business logic lives in a layer class; the helper only schedules layers**. One helper instance per service; the value in its map is the aggregate of everything one scope contributes to that service. + +- **`ScopedLayers`** — a concrete scheduler, never subclassed. It owns the global layer plus one `Map`, builds layers on demand as `new layerClass(scope, this)`, reclaims a layer when `isEmpty()`, and funnels every write through `effect(ctx, action, options?)`. The single `ctx` parameter decides both the visible layer (`scopeOf(ctx)`) and the owning fiber (`ctx.effect`), so "visible to X, disposed with Y" stays unrepresentable — the same shape argument the agent-scope RFC used against explicit scope parameters. Actions may produce one undo, an iterable of undos, a promise, or an async iterable — the four shapes of cordis `Effect` — and undos may be async. The helper seals collected undos (run in LIFO), empty-layer reclamation, and the change notification into one disposer, and hands cordis that disposer **before** the notification runs: a throwing change listener therefore makes cordis execute the already-collected rollback and rethrow, exactly like the hand-written yield-before-emit today. Reads are `global`/`peek` plus three selector primitives lifting the table views across the two layers — `merge` (named entries, scoped shadows global, global position preserved, optional admit predicate), `values` (concatenation including anonymous entries, deliberately no shadowing), `keys` (the pre-restriction name universe) — and array-returning `forEach`/`filter`/`map` over all layers. +- **`createLayer({ name: table(kind) })`** — a class factory in the `defineTool` DSL tradition. The generated base class builds every declared table in its constructor, threads the scope down, receives the sibling back-reference (`protected readonly layers: ScopedLayers`, injected by the helper at construction; polymorphic `this` narrows it in subclasses), and aggregates `isEmpty()` over the declared tables. `layer.` is a fully typed mapped property, so a misspelled table name is a compile error; the table names `scope`, `isEmpty`, and `layers` are reserved and throw. Business subclasses add domain methods in the class body — single-layer queries, registration validations, and cross-layer *reads* through `this.layers` (writes must still go through `effect`); a fully custom layer may instead implement the one-method `ScopeLayer` interface (`isEmpty()`). +- **`Entries`** — the canned table: named entries (`insert`, same-layer duplicates throw one standardized message pair pointing at `agent.ctx`) and anonymous entries (`append`, process-unique symbol keys, O(1) undo removal) share one insertion-ordered map; read views (`keys`/`entries`/`values`) return array snapshots. + +`dsh-tools` migrates its three tables into one `ToolLayer` (domain methods `addRestriction` — empty-filter/read-once/reserved-name/known-names validation with the reserved list passed in as data, since it reads service state — plus `admits` and `guardReason`), and `dsh-system-prompt` its four into one `PromptLayer` (`addProtection` with the global-conflict self-check via the back-reference, plus the `shadowedSections` predicate). Every facade becomes a single `effect` call carrying per-call `label`, `silent` (guards emit no change event), or `scopedOnly` (boolean, or a string carrying the domain error message) options. `assemble` stays in the facade for three hard reasons: it has no legal receiver (the subject scope's layer may not exist, and reads never create layers), shadowing forces merge-before-evaluate (per-layer rendering would evaluate shadowed providers, an observable change), and the assemble waterfall, `toolOrder`, and protection restore need service-level resources a layer must not hold. + +Migration is behavior-preserving with two declared exceptions: the three duplicate-name messages unify into one template (tests asserting the old wording update in the same change), and validations move relative to the effect boundary (restrict/protect checks move inside the action, the variable name regex moves to the facade), so the error *order* for multiply-invalid inputs can change while every single-fault path is unchanged. Two knowingly unobservable differences: an aggregate layer is reclaimed only when all its tables are empty, and read views are snapshots rather than live containers (visible only to a callback that registers during its own iteration). + +## API sketch + +```ts ignore-check +interface ScopeLayer { + isEmpty(): boolean +} + +type LayerClass = new (scope: ScopeKey | undefined, layers: ScopedLayers) => L + +declare function table(kind: string): TableSpec +declare function createLayer>>( + spec: S, +): LayerClass> }> + +type Undo = () => unknown +type LayerAction = (layer: L) => + | Undo + | Iterable + | Promise + | AsyncIterable + +class ScopedLayers { + constructor(layerClass: LayerClass, options: { label: string; onChange?: () => void }) + readonly global: L + peek(scope: ScopeKey | undefined): L | undefined + merge(scope: ScopeKey | undefined, pick: (layer: L) => Entries, admitGlobal?: (name: string) => boolean): Map + values(scope: ScopeKey | undefined, pick: (layer: L) => Entries): T[] + keys(scope: ScopeKey | undefined, pick: (layer: L) => Entries): string[] + effect(ctx: Context, action: LayerAction, options?: { label?: string; silent?: boolean; scopedOnly?: boolean | string }): () => Promise | void + forEach(fn: (layer: L, scope: ScopeKey | undefined) => void): void + filter(fn: (layer: L, scope: ScopeKey | undefined) => boolean): L[] + map(fn: (layer: L, scope: ScopeKey | undefined) => T): T[] +} + +class Entries { + constructor(kind: string, scope: ScopeKey | undefined) + insert(name: string, value: V): () => void + append(value: V): () => void + get(name: string): V | undefined + has(name: string): boolean + keys(): string[] + entries(): ReadonlyArray + values(): readonly V[] + isEmpty(): boolean +} +``` + +What a migrated consumer looks like — the heaviest current site shrinks from 30+ lines of choreography to a declaration and one-line facades: + +```ts ignore-check +class ToolLayer extends createLayer({ + tools: table('tool'), + restrictions: table('tool restriction'), + guards: table('tool guard'), +}) { + addRestriction(filter: ToolRestriction, reserved: readonly string[]): () => void { /* validate, snapshot, append */ } + admits(name: string): boolean { /* intersection over this.restrictions.values() */ } + guardReason(view: Readonly): string | undefined { /* first monotonic denial */ } +} + +class ToolRegistry extends Service { + private readonly layers = new ScopedLayers(ToolLayer, { + label: 'tools', + onChange: () => this.ctx.emit('tools/change'), + }) + + register(definition: ToolDefinition): () => Promise | void { + return this.layers.effect(this.ctx, + layer => layer.tools.insert(definition.name, definition), + { label: 'tools.register()' }) + } + + visible(scope?: ScopeKey): ToolDefinition[] { + return Array.from(this.layers.merge(scope, layer => layer.tools, name => this.admits(scope, name)).values()) + } +} +``` + +## Alternatives considered + +**Per-scope registry instances behind a parent/child delegation chain.** Instance explosion; the "deployment tools plus my tools" merged view needs a hand-built delegating registry per service; single-subscription observers (persistence, the ACP bridge) would have to discover and subscribe per instance; and a delegation chain cannot express subtraction (restrictions). A child registry would also have to reach back into a parent context, widening the exposure surface. + +**Explicit scope parameters on registration APIs.** Already rejected by the agent-scope RFC: omitting the parameter silently registers globally, and the shape can express visible-to-X-disposed-with-Y, which is almost always a bug. + +**Extracting only the data structure, leaving the choreography in services.** Removes the safe half of the duplication and keeps the dangerous half — the rollback-before-emit ordering, raw-disposer, and reclamation rules are exactly where the bugs live. + +**A fixed-container helper with built-in view semantics.** Pins container shapes and merge policy inside the helper; business gets no freedom, and every naming or single-value variation becomes a helper feature request. + +**One helper per table.** Reproduces today's scattered bookkeeping — that is the status quo being replaced, with N scope maps per service and no aggregate for an agent's contribution. + +**`helper.get(ctx).effect(...)` two-step registration.** Splits layer creation from lifecycle attachment; a throw between the steps strands an empty layer, and the returned handle is an extra allocation per call. + +**Layers holding a ctx and registering their own effects.** Turns data objects into lifecycle managers and reinstates the choreography once per business class. + +## Acceptance criteria + +- `store.ts` ships in `dsh-scope` (peer deps unchanged: cordis only; module-graph position unchanged) with per-file 100% coverage, including: layer bookkeeping and reclamation, all four action shapes, seal ordering, the throwing-change-listener rollback (the entry is rolled back and the duplicate check re-registers), failure reclamation of freshly created layers, `label`/`silent`/`scopedOnly` options, `createLayer` construction, reserved table names, back-reference typing, and `Entries` named/anonymous semantics. +- `dsh-tools` and `dsh-system-prompt` each collapse to one `ScopedLayers`; all existing tests pass with only the declared duplicate-message assertion updates; every registration facade is a single `effect` call and keeps returning the exact cordis effect disposer. +- Behavior matches the old baseline per the equivalence statement above: two declared exceptions (unified messages; error order for multiply-invalid inputs), two unobservable differences (aggregate reclamation timing; snapshot read views), nothing else. +- Documentation lands in the same change: `dsh-scope`/`dsh-tools`/`dsh-system-prompt` READMEs; on implementation this RFC moves to `implemented/` and the [runtime-design RFC](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)'s registration section is updated in place. + +## Risks + +- The layer/facade boundary may not fit a future consumer's shape. Mitigation: the bare `ScopeLayer` interface remains the floor, and widening `LayerClass` to accept a factory (for layers with constructor dependencies) is a recorded non-breaking extension. +- `createLayer`'s mapped-type factory is deliberate type gymnastics. Accepted: the `defineTool` schema DSL is the repo precedent, and the gymnastics stay inside `dsh-scope`. +- The two equivalence exceptions can surprise tests that assert exact duplicate messages or multi-fault error order; they are declared here so review checks them rather than discovers them. +- Snapshot read views hide entries registered by a callback during its own iteration — a pathological pattern, but a visible one; snapshots make it deterministic instead. +- Two core registries migrate at once. Mitigated by the behavior comparison performed during design and by landing the store with equivalence-pinning tests before either migration commit. diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md new file mode 100644 index 0000000000..6460802f3c --- /dev/null +++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md @@ -0,0 +1,139 @@ +# RFC: 作用域分层存储——每 scope 一个聚合层与统一调度 helper + +Status: proposed + +[English](2026-07-12-scoped-layers-store.md) | 中文 + +## 问题 + +agent 作用域落地之后([agent-scope RFC](../../implemented/architecture/2026-07-08-agent-scope-contexts.md)、[运行时设计篇](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)),「一张全局层加若干 per-agent 层的注册表」成为反复出现的形态,而每一处都是手写的。今天已有七个登记口——`dsh-tools` 的 `tools.register`/`tools.restrict`/`tools.guard` 与 `dsh-system-prompt` 的 `section`/`tools`/`variable`/`protect`——每处都是一个全局容器配一张自己的 `Map`,并重复同一段 10-15 行的 effect 编排:读调用方上下文的标签、按需建层、校验、变更、yield 一个「删条目 → 回收空层 → 发 change 事件」的回滚,然后发事件并返回 cordis effect 的原始 disposer。 + +除此之外:风险集中在编排细节上: +- 回滚必须在 change 发出之前被收集(抛错的监听器才能回卷插入而不是泄漏) +- 返回的 disposer 必须是 cordis 自己的那个函数(包装器会静默破坏嵌套的有序拆除) +- 清空的专属层必须被回收(被 dispose 的 agent 不得留下以死 `ScopeKey` 为键的残余) + +每个新消费者都要把这一切重新写对一遍,而各副本的写法已经分叉——`dsh-tools` 里有两个私有 `layerFor`,`dsh-system-prompt` 里是四处内联 IIFE。 + +最后,一个 agent 在一个服务里的贡献散落在几张互不相识的 Map 里——不存在一个「这个 scope 在这里贡献了什么」的对象——而消费者还在持续增多:guard 与提示词 protection 是最近落地的一批,per-agent 的 `fs/*` 策略、`llm/*` 覆盖、per-agent compaction 策略都排在同一个模式上。 + +## 提案 + +`dsh-scope` 新增 store 模块(其 `src/` 下新增 `store.ts`,peer 依赖仅 cordis,与键类型无关),核心是一条分工:**业务逻辑封在层类里,helper 只负责调度层**。一个服务一个 helper 实例;其 Map 的 value 就是「一个 scope 在该服务的全部贡献」这一聚合对象。 + +- **`ScopedLayers`**——具体的调度器,不作继承点。持有全局层与一张 `Map`,按需以 `new layerClass(scope, this)` 建层,层 `isEmpty()` 时回收,并把所有写入收拢到 `effect(ctx, action, options?)`。单一 `ctx` 参数同时决定可见层(`scopeOf(ctx)`)与属主 fiber(`ctx.effect`),「对 X 可见、随 Y 销毁」因此不可表达——与 agent-scope RFC 否决显式 scope 参数用的是同一个形状论证。action 可以产出单个撤销、撤销的可迭代、Promise 或异步可迭代——即 cordis `Effect` 的四种形态——且撤销允许异步。helper 把收集到的撤销(逆序执行)、空层回收与 change 通知合成**一个** disposer,并在通知运行**之前**先把它交给 cordis:因此 change 监听器抛错时,cordis 会执行已收集的回滚再重抛,与今天手写的「yield 在 emit 之前」逐字等价。读取件是 `global`/`peek`,外加把表视图提升到两层的三个 selector 原语——`merge`(命名条目,专属遮蔽全局、保留全局位置,可选放行谓词)、`values`(拼接、含匿名条目、刻意不做遮蔽)、`keys`(限制前名字全集)——以及跨全部层、返回数组的 `forEach`/`filter`/`map`。 +- **`createLayer({ 表名: table(kind) })`**——`defineTool` DSL 传统的类工厂。生成的基类在构造器里建好每张声明的表、把 scope 传下去、接收同族回引(`protected readonly layers: ScopedLayers`,由 helper 建层时注入;多态 `this` 型在子类中自动收窄),并对声明的表聚合 `isEmpty()`。`layer.<表名>` 是带完整类型的映射属性,写错表名是编译错误;表名 `scope`、`isEmpty`、`layers` 保留,冲突即抛。业务子类在类体里追加领域方法——单层查询、登记校验,以及经 `this.layers` 的跨层**只读**(写入仍必须走 `effect`);完全自定义的层也可以只实现单方法接口 `ScopeLayer`(`isEmpty()`)。 +- **`Entries`**——罐装条目表:命名条目(`insert`,同层重名抛一对指向 `agent.ctx` 的标准化文案)与匿名条目(`append`,进程内唯一 symbol 键、O(1) 撤销删除)共用一张保插入序的 Map;读视图(`keys`/`entries`/`values`)返回数组快照。 + +`dsh-tools` 把三张表合并进一个 `ToolLayer`(领域方法 `addRestriction`——空过滤器/读取一次性/保留名/已知名校验,保留名单因读服务状态而以数据传入——加上 `admits` 与 `guardReason`),`dsh-system-prompt` 把四张表合并进一个 `PromptLayer`(`addProtection` 经同族回引做全局冲突自检,加上 `shadowedSections` 谓词)。每个门面都变成单次 `effect` 调用,携带 per-call 的 `label`、`silent`(guard 不发 change 事件)或 `scopedOnly`(布尔,或携带领域报错文案的字符串)选项。`assemble` 留在门面,三条硬理由:它没有合法接收者(主体 scope 的层可能不存在,而读路径绝不建层)、遮蔽语义强制先合并后求值(逐层渲染会求值被遮蔽的 provider,行为可观察地改变)、组装 waterfall、`toolOrder` 与 protection 恢复需要层不应持有的服务级资源。 + +迁移保持行为等价,带两个声明的例外:三处重名文案统一为一个模板(断言旧文案的测试在同一变更中更新);校验相对 effect 边界发生挪动(restrict/protect 的检查移入 action,variable 的名字正则移到门面),因此多重非法输入的报错**先后**可能改变,而所有单一错误路径不变。两个已知的不可观察差异:聚合层要等全部表清空才回收;读视图是快照而非活容器(仅对「在自己的遍历回调里再注册」可见)。 + +## API 草图 + +```ts ignore-check +interface ScopeLayer { + isEmpty(): boolean +} + +type LayerClass = new (scope: ScopeKey | undefined, layers: ScopedLayers) => L + +declare function table(kind: string): TableSpec +declare function createLayer>>( + spec: S, +): LayerClass> }> + +type Undo = () => unknown +type LayerAction = (layer: L) => + | Undo + | Iterable + | Promise + | AsyncIterable + +class ScopedLayers { + constructor(layerClass: LayerClass, options: { label: string; onChange?: () => void }) + readonly global: L + peek(scope: ScopeKey | undefined): L | undefined + merge(scope: ScopeKey | undefined, pick: (layer: L) => Entries, admitGlobal?: (name: string) => boolean): Map + values(scope: ScopeKey | undefined, pick: (layer: L) => Entries): T[] + keys(scope: ScopeKey | undefined, pick: (layer: L) => Entries): string[] + effect(ctx: Context, action: LayerAction, options?: { label?: string; silent?: boolean; scopedOnly?: boolean | string }): () => Promise | void + forEach(fn: (layer: L, scope: ScopeKey | undefined) => void): void + filter(fn: (layer: L, scope: ScopeKey | undefined) => boolean): L[] + map(fn: (layer: L, scope: ScopeKey | undefined) => T): T[] +} + +class Entries { + constructor(kind: string, scope: ScopeKey | undefined) + insert(name: string, value: V): () => void + append(value: V): () => void + get(name: string): V | undefined + has(name: string): boolean + keys(): string[] + entries(): ReadonlyArray + values(): readonly V[] + isEmpty(): boolean +} +``` + +迁移后的消费者长什么样——现存最重的登记口从 30+ 行编排缩为一份声明加一行门面: + +```ts ignore-check +class ToolLayer extends createLayer({ + tools: table('tool'), + restrictions: table('tool restriction'), + guards: table('tool guard'), +}) { + addRestriction(filter: ToolRestriction, reserved: readonly string[]): () => void { /* validate, snapshot, append */ } + admits(name: string): boolean { /* intersection over this.restrictions.values() */ } + guardReason(view: Readonly): string | undefined { /* first monotonic denial */ } +} + +class ToolRegistry extends Service { + private readonly layers = new ScopedLayers(ToolLayer, { + label: 'tools', + onChange: () => this.ctx.emit('tools/change'), + }) + + register(definition: ToolDefinition): () => Promise | void { + return this.layers.effect(this.ctx, + layer => layer.tools.insert(definition.name, definition), + { label: 'tools.register()' }) + } + + visible(scope?: ScopeKey): ToolDefinition[] { + return Array.from(this.layers.merge(scope, layer => layer.tools, name => this.admits(scope, name)).values()) + } +} +``` + +## 备选方案 + +**每 scope 一个注册表实例,父子委托链。** 实例爆炸;「部署工具加我的工具」的合并视图要每个服务手写一个委托注册表;单订阅观察者(持久化、ACP bridge)必须逐实例发现并订阅;委托链表达不了减法(restriction)。子注册表还得反向触及父上下文,扩大暴露面。 + +**注册 API 上的显式 scope 参数。** agent-scope RFC 已否决:漏传参数即静默注册为全局,且该形状能表达「对 X 可见、随 Y 销毁」——几乎必然是 bug。 + +**只抽数据结构、编排留在服务。** 消掉的是重复里安全的那一半,留下的是危险的那一半——回滚先于 emit 的顺序、原始 disposer、回收规则,恰是 bug 所在。 + +**内置视图语义的固定容器 helper。** 容器形态与合并策略被钉死在 helper 里;业务没有自由度,任何命名或单值变体都变成对 helper 的功能诉求。 + +**每张表一个 helper。** 复刻今天的散装簿记——那正是被替换的现状:每服务 N 张 scope Map,agent 的贡献没有聚合。 + +**`helper.get(ctx).effect(...)` 两步式登记。** 把建层与挂生命周期拆成两步;两步之间抛错会搁浅一个空层,返回的 handle 还是每次调用一笔额外分配。 + +**层持有 ctx、自己注册 effect。** 把数据对象变成生命周期管理者,编排在每个业务类里重演一遍。 + +## 验收标准 + +- `store.ts` 落在 `dsh-scope`(peer 依赖不变:仅 cordis;模块图位置不变),逐文件 100% 覆盖,包括:层簿记与回收、四种 action 形态、合成顺序、change 监听器抛错回滚(条目被回卷、重名检查可再注册)、新建层的失败回收、`label`/`silent`/`scopedOnly` 选项、`createLayer` 构造、保留表名、同族回引类型、`Entries` 命名/匿名语义。 +- `dsh-tools` 与 `dsh-system-prompt` 各收敛为一个 `ScopedLayers`;所有既有测试通过,改动仅限已声明的重名文案断言更新;每个登记门面都是单次 `effect` 调用,并继续返回 cordis effect 的原始 disposer。 +- 行为按上文等价性声明与老基线一致:两个声明例外(统一文案;多重非法输入的报错先后)、两个不可观察差异(聚合回收时机;快照读视图),此外无他。 +- 文档随同一变更落地:`dsh-scope`/`dsh-tools`/`dsh-system-prompt` 的 README;实现后本 RFC 移入 `implemented/`,并就地更新[运行时设计 RFC](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md) 的注册章节。 + +## 风险 + +- 层/门面边界可能不适配某个未来消费者的形状。缓解:裸 `ScopeLayer` 接口始终是兜底;把 `LayerClass` 拓宽为可接受工厂(供有构造依赖的层)是已记录的非破坏扩展。 +- `createLayer` 的映射类型工厂是刻意的类型体操。接受:`defineTool` schema DSL 是仓库先例,体操圈在 `dsh-scope` 内部。 +- 两个等价性例外可能让断言精确重名文案或多重错误顺序的测试意外;在此声明,使评审是核对而非发现。 +- 快照读视图会隐藏「回调在自己的遍历中注册」的条目——病态但可见的模式;快照使其转为确定性行为。 +- 两个核心注册表同时迁移。缓解:设计期已完成逐行为对比,且 store 连同钉住等价性的测试先于任一迁移 commit 落地。 From 84d0932e5e7e117b753b34c123db9dbd1c102743 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 13 Jul 2026 00:06:04 +0800 Subject: [PATCH 006/273] docs(rfc): align scoped layers with final scope design --- .../2026-07-12-scoped-layers-store.i18n.yaml | 4 +- .../2026-07-12-scoped-layers-store.md | 125 +++++++++--------- .../2026-07-12-scoped-layers-store.zh.md | 125 +++++++++--------- 3 files changed, 134 insertions(+), 120 deletions(-) diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml index f868cfc669..be26cfa552 100644 --- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml +++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.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 -2026-07-12-scoped-layers-store.md: 0673d6c63291a66c84e91f2eff8eca26798b931f -2026-07-12-scoped-layers-store.zh.md: 6460802f3cf3163f6be2ad51f2f82319a04288bc +2026-07-12-scoped-layers-store.md: c3a9ab8724191b5b1bc87f02a90d6995c247d944 +2026-07-12-scoped-layers-store.zh.md: e2ec72145766a95ea1c330e3a658f7c86490e263 diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md index 0673d6c632..c3a9ab8724 100644 --- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md +++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md @@ -6,72 +6,70 @@ English | [中文](2026-07-12-scoped-layers-store.zh.md) ## Problem -Agent scoping ([the agent-scope RFC](../../implemented/architecture/2026-07-08-agent-scope-contexts.md), [runtime design](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)) made "a registry with a global layer plus per-agent layers" a recurring shape, and every occurrence is hand-written. Seven registration sites exist today — `tools.register`/`tools.restrict`/`tools.guard` in `dsh-tools` and `section`/`tools`/`variable`/`protect` in `dsh-system-prompt` — each pairing a global container with its own `Map` and repeating the same 10-15-line effect choreography: read the calling context's tag, get-or-create the layer, validate, mutate, yield a rollback that deletes the entry, reclaims the emptied layer, and emits the change event, then emit and return the exact cordis effect disposer. +Agent scoping ([the agent-scope RFC](../../implemented/architecture/2026-07-08-agent-scope-contexts.md), [runtime design](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)) made "a registry with a global layer plus per-agent layers" a recurring shape, and every occurrence is hand-written. Six registration sites exist today — `tools.register`/`tools.restrict`/`tools.guard` in `dsh-tools` and `section`/`tools`/`variable` in `dsh-system-prompt` — each repeating the same 10-15-line effect choreography around its applicable global or scoped containers: read the calling context's tag, get or create the layer, validate, mutate, yield a rollback that deletes the entry and reclaims an emptied scoped layer, emit the applicable change event, and return the exact Cordis effect disposer. Beyond the duplication, the risk concentrates in the choreography details: - The rollback must be collected before the change emit (so a throwing listener unwinds the insertion instead of leaking it) -- The returned disposer must be cordis's own function (a wrapper silently breaks nested ordered teardown) +- The returned disposer must be Cordis's own function (a wrapper silently breaks nested ordered teardown) - Emptied scoped layers must be reclaimed (a disposed agent must not leave residue keyed by its dead `ScopeKey`) -Every new consumer has to rewrite all of that correctly, and the copies have already diverged stylistically — two private `layerFor` helpers in `dsh-tools`, four inline IIFEs in `dsh-system-prompt`. +Every new consumer has to rewrite all of that correctly, and the copies have already diverged stylistically — two private layer helpers in `dsh-tools`, three inline IIFEs in `dsh-system-prompt`. -Finally, one agent's contribution to one service is scattered across several maps that know nothing of each other — there is no object that means "what this scope contributes here" — and the consumer count keeps growing: guards and prompt protections landed recently, and per-agent `fs/*` policy, `llm/*` overrides, and per-agent compaction policy are all queued on the same pattern. +Finally, one agent's contribution to one service is scattered across several maps that know nothing of each other — there is no object that means "what this scope contributes here" — and the consumer count keeps growing: scoped guards and per-agent prompt/tool composition landed recently, while per-agent `fs/*` policy, `llm/*` overrides, and compaction policy are plausible future users of the same pattern. ## Proposal -`dsh-scope` gains a store module (a new `store.ts` under its `src/`, peer-dependent on cordis only, key-agnostic) built around one division of labor: **business logic lives in a layer class; the helper only schedules layers**. One helper instance per service; the value in its map is the aggregate of everything one scope contributes to that service. +`dsh-scope` gains a key-agnostic `store.ts`, with Cordis as its only peer dependency. The module implements the smallest abstraction shared by the six current sites: **business state and validation stay in an explicit layer class; one helper owns layer selection, effect attachment, rollback, notification, and reclamation**. One helper instance belongs to one service, and one layer instance aggregates everything a scope contributes to that service. -- **`ScopedLayers`** — a concrete scheduler, never subclassed. It owns the global layer plus one `Map`, builds layers on demand as `new layerClass(scope, this)`, reclaims a layer when `isEmpty()`, and funnels every write through `effect(ctx, action, options?)`. The single `ctx` parameter decides both the visible layer (`scopeOf(ctx)`) and the owning fiber (`ctx.effect`), so "visible to X, disposed with Y" stays unrepresentable — the same shape argument the agent-scope RFC used against explicit scope parameters. Actions may produce one undo, an iterable of undos, a promise, or an async iterable — the four shapes of cordis `Effect` — and undos may be async. The helper seals collected undos (run in LIFO), empty-layer reclamation, and the change notification into one disposer, and hands cordis that disposer **before** the notification runs: a throwing change listener therefore makes cordis execute the already-collected rollback and rethrow, exactly like the hand-written yield-before-emit today. Reads are `global`/`peek` plus three selector primitives lifting the table views across the two layers — `merge` (named entries, scoped shadows global, global position preserved, optional admit predicate), `values` (concatenation including anonymous entries, deliberately no shadowing), `keys` (the pre-restriction name universe) — and array-returning `forEach`/`filter`/`map` over all layers. -- **`createLayer({ name: table(kind) })`** — a class factory in the `defineTool` DSL tradition. The generated base class builds every declared table in its constructor, threads the scope down, receives the sibling back-reference (`protected readonly layers: ScopedLayers`, injected by the helper at construction; polymorphic `this` narrows it in subclasses), and aggregates `isEmpty()` over the declared tables. `layer.
` is a fully typed mapped property, so a misspelled table name is a compile error; the table names `scope`, `isEmpty`, and `layers` are reserved and throw. Business subclasses add domain methods in the class body — single-layer queries, registration validations, and cross-layer *reads* through `this.layers` (writes must still go through `effect`); a fully custom layer may instead implement the one-method `ScopeLayer` interface (`isEmpty()`). -- **`Entries`** — the canned table: named entries (`insert`, same-layer duplicates throw one standardized message pair pointing at `agent.ctx`) and anonymous entries (`append`, process-unique symbol keys, O(1) undo removal) share one insertion-ordered map; read views (`keys`/`entries`/`values`) return array snapshots. +- **`ScopedLayers`** is a concrete scheduler, not a base class. It owns the global layer plus one `Map`, constructs scoped layers on demand through an explicit factory, and reclaims a layer when `isEmpty()`. Its `effect(ctx, action, options?)` accepts one synchronous action that returns one synchronous undo because that is the complete shape of all six current sites. The single `ctx` decides both the visible layer (`scopeOf(ctx)`) and the owning Cordis fiber (`ctx.effect`), so "visible to X, disposed with Y" stays unrepresentable. The helper yields the undo before notifying listeners, returns Cordis's exact disposer, and reclaims a newly created empty layer if validation or mutation throws. Reads are `global`/`peek` plus `merge` (named entries with scoped shadowing and an optional global-admission predicate), `values` (global then scoped concatenation without shadowing), `keys` (the pre-restriction name universe), and `some` (cross-layer invariant checks). +- **Explicit `ScopeLayer` classes** make each service's state visible to readers. `ToolLayer` and `PromptLayer` declare their three table properties and their `isEmpty()` aggregation directly; a small layer factory receives only the scope, while its closure may capture real constructor dependencies. Domain methods stay ordinary class methods. This costs a few repetitive declarations but avoids a mapped-type class factory, a scheduler/layer ownership cycle, reserved property names, and generated runtime structure. +- **`NamedEntries` and `AnonymousEntries`** are the two shared insertion-ordered tables. Named entries expose `insert`/lookup and retain the current global/scoped duplicate wording through domain `kind` and per-agent-alternative labels; anonymous entries expose only `append`, using process-unique symbol keys for O(1) undo removal. Keeping the classes separate makes meaningless mixed named/anonymous operations unrepresentable and keeps key types sound. Their iterators borrow membership and typed contribution values; they do not clone or freeze values. `ScopedLayers` materializes only the merged arrays/maps already required by the service read paths. -`dsh-tools` migrates its three tables into one `ToolLayer` (domain methods `addRestriction` — empty-filter/read-once/reserved-name/known-names validation with the reserved list passed in as data, since it reads service state — plus `admits` and `guardReason`), and `dsh-system-prompt` its four into one `PromptLayer` (`addProtection` with the global-conflict self-check via the back-reference, plus the `shadowedSections` predicate). Every facade becomes a single `effect` call carrying per-call `label`, `silent` (guards emit no change event), or `scopedOnly` (boolean, or a string carrying the domain error message) options. `assemble` stays in the facade for three hard reasons: it has no legal receiver (the subject scope's layer may not exist, and reads never create layers), shadowing forces merge-before-evaluate (per-layer rendering would evaluate shadowed providers, an observable change), and the assemble waterfall, `toolOrder`, and protection restore need service-level resources a layer must not hold. +`dsh-tools` migrates its three tables into one `ToolLayer`: tools, compiled restrictions, and guards. The layer owns restriction admission and guard evaluation; the facade retains domain validation that needs service configuration, such as the reserved `run_code` name and the current known-global-name universe. Readonly allow/deny inputs are compiled once into internal sets. `dsh-system-prompt` likewise migrates sections, tool providers, and variables into one `PromptLayer`; its facade performs owner-final cross-layer checks through `layers.some`. Every registration facade performs its public argument validation and then makes one `effect` call with a label and, for guards, `silent: true`. A generic helper does not learn domain rules such as "restrictions require a scoped context." -Migration is behavior-preserving with two declared exceptions: the three duplicate-name messages unify into one template (tests asserting the old wording update in the same change), and validations move relative to the effect boundary (restrict/protect checks move inside the action, the variable name regex moves to the facade), so the error *order* for multiply-invalid inputs can change while every single-fault path is unchanged. Two knowingly unobservable differences: an aggregate layer is reclaimed only when all its tables are empty, and read views are snapshots rather than live containers (visible only to a callback that registers during its own iteration). +`assemble` stays in the `SystemPrompt` facade for three reasons: the subject scope's layer may not exist and reads must not create it; shadowing requires merge-before-evaluate so a hidden section provider is never called; and the assembly waterfall, `toolOrder`, and owner-final restoration use service-level resources. Sections and tool providers keep their current materialized derived views. Variable providers instead iterate the global and scoped `NamedEntries` directly, preserving today's live Map behavior when a provider registers another variable during assembly. Tool guards likewise iterate their `AnonymousEntries` directly. Owner-final remains metadata on section and tool contributions, not a second protection registry. + +Migration preserves public behavior and exact duplicate messages. The internal aggregate layer is reclaimed only after all three tables empty rather than when one table empties; no service API exposes layer identity. Direct live iteration retains current re-entrant variable-provider and guard behavior, while selector helpers continue to materialize the same section, tool-provider, and tool-resolution views their facades build today. + +`ScopeLayer`, `EntryValues`, `ScopedLayers`, `NamedEntries`, and `AnonymousEntries` are public `dsh-scope` root exports with export JSDoc. Consumers import them from `@deepseek-ai/dsh-scope`; `store.ts` is an implementation module, not a package subpath. ## API sketch ```ts ignore-check -interface ScopeLayer { +export interface ScopeLayer { isEmpty(): boolean } -type LayerClass = new (scope: ScopeKey | undefined, layers: ScopedLayers) => L - -declare function table(kind: string): TableSpec -declare function createLayer>>( - spec: S, -): LayerClass> }> - -type Undo = () => unknown -type LayerAction = (layer: L) => - | Undo - | Iterable - | Promise - | AsyncIterable - -class ScopedLayers { - constructor(layerClass: LayerClass, options: { label: string; onChange?: () => void }) +export class ScopedLayers { + constructor(createLayer: (scope: ScopeKey | undefined) => L, options: { onChange?: () => void }) readonly global: L peek(scope: ScopeKey | undefined): L | undefined - merge(scope: ScopeKey | undefined, pick: (layer: L) => Entries, admitGlobal?: (name: string) => boolean): Map - values(scope: ScopeKey | undefined, pick: (layer: L) => Entries): T[] - keys(scope: ScopeKey | undefined, pick: (layer: L) => Entries): string[] - effect(ctx: Context, action: LayerAction, options?: { label?: string; silent?: boolean; scopedOnly?: boolean | string }): () => Promise | void - forEach(fn: (layer: L, scope: ScopeKey | undefined) => void): void - filter(fn: (layer: L, scope: ScopeKey | undefined) => boolean): L[] - map(fn: (layer: L, scope: ScopeKey | undefined) => T): T[] + merge(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries, admitGlobal?: (name: string) => boolean): Map + values(scope: ScopeKey | undefined, pick: (layer: L) => EntryValues): T[] + keys(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries): string[] + some(fn: (layer: L, scope: ScopeKey | undefined) => boolean): boolean + effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => Promise | void } -class Entries { - constructor(kind: string, scope: ScopeKey | undefined) +export interface EntryValues { + values(): IterableIterator + isEmpty(): boolean +} + +export class NamedEntries implements EntryValues { + constructor(kind: string, perAgentAlternative: string, scope: ScopeKey | undefined) insert(name: string, value: V): () => void - append(value: V): () => void get(name: string): V | undefined has(name: string): boolean - keys(): string[] - entries(): ReadonlyArray - values(): readonly V[] + keys(): IterableIterator + entries(): IterableIterator<[string, V]> + values(): IterableIterator + isEmpty(): boolean +} + +export class AnonymousEntries implements EntryValues { + append(value: V): () => void + values(): IterableIterator isEmpty(): boolean } ``` @@ -79,21 +77,26 @@ class Entries { What a migrated consumer looks like — the heaviest current site shrinks from 30+ lines of choreography to a declaration and one-line facades: ```ts ignore-check -class ToolLayer extends createLayer({ - tools: table('tool'), - restrictions: table('tool restriction'), - guards: table('tool guard'), -}) { - addRestriction(filter: ToolRestriction, reserved: readonly string[]): () => void { /* validate, snapshot, append */ } +class ToolLayer implements ScopeLayer { + readonly tools = new NamedEntries('tool', 'variant', this.scope) + readonly restrictions = new AnonymousEntries() + readonly guards = new AnonymousEntries() + + constructor( + readonly scope: ScopeKey | undefined, + ) {} + + isEmpty(): boolean { return this.tools.isEmpty() && this.restrictions.isEmpty() && this.guards.isEmpty() } + addRestriction(filter: ToolRestriction): () => void { /* compile to sets, append */ } admits(name: string): boolean { /* intersection over this.restrictions.values() */ } guardReason(view: Readonly): string | undefined { /* first monotonic denial */ } } class ToolRegistry extends Service { - private readonly layers = new ScopedLayers(ToolLayer, { - label: 'tools', - onChange: () => this.ctx.emit('tools/change'), - }) + private readonly layers = new ScopedLayers( + scope => new ToolLayer(scope), + { onChange: () => this.ctx.emit('tools/change') }, + ) register(definition: ToolDefinition): () => Promise | void { return this.layers.effect(this.ctx, @@ -101,8 +104,9 @@ class ToolRegistry extends Service { { label: 'tools.register()' }) } - visible(scope?: ScopeKey): ToolDefinition[] { - return Array.from(this.layers.merge(scope, layer => layer.tools, name => this.admits(scope, name)).values()) + private resolveVisible(scope?: ScopeKey): ToolDefinition[] { + const scoped = this.layers.peek(scope) + return Array.from(this.layers.merge(scope, layer => layer.tools, name => scoped?.admits(name) ?? true).values()) } } ``` @@ -115,6 +119,10 @@ class ToolRegistry extends Service { **Extracting only the data structure, leaving the choreography in services.** Removes the safe half of the duplication and keeps the dangerous half — the rollback-before-emit ordering, raw-disposer, and reclamation rules are exactly where the bugs live. +**Accepting the full Cordis `Effect` union as a layer action.** None of the six sites has asynchronous setup, multiple undos, or an independent settlement boundary. Normalizing promises, iterables, async iterables, LIFO sealing, and partial failure would duplicate lifecycle machinery speculatively. The store accepts one synchronous action and one undo; a future real boundary can justify widening it. + +**Generating layer classes from a mapped-type table DSL.** The two consumers each declare three tables. A class factory would save a handful of lines while adding generated runtime shape, reserved names, polymorphic-`this` typing, and a second construction model. Explicit classes are easier to inspect and can still share the entry tables and `ScopedLayers`. + **A fixed-container helper with built-in view semantics.** Pins container shapes and merge policy inside the helper; business gets no freedom, and every naming or single-value variation becomes a helper feature request. **One helper per table.** Reproduces today's scattered bookkeeping — that is the status quo being replaced, with N scope maps per service and no aggregate for an agent's contribution. @@ -125,15 +133,14 @@ class ToolRegistry extends Service { ## Acceptance criteria -- `store.ts` ships in `dsh-scope` (peer deps unchanged: cordis only; module-graph position unchanged) with per-file 100% coverage, including: layer bookkeeping and reclamation, all four action shapes, seal ordering, the throwing-change-listener rollback (the entry is rolled back and the duplicate check re-registers), failure reclamation of freshly created layers, `label`/`silent`/`scopedOnly` options, `createLayer` construction, reserved table names, back-reference typing, and `Entries` named/anonymous semantics. -- `dsh-tools` and `dsh-system-prompt` each collapse to one `ScopedLayers`; all existing tests pass with only the declared duplicate-message assertion updates; every registration facade is a single `effect` call and keeps returning the exact cordis effect disposer. -- Behavior matches the old baseline per the equivalence statement above: two declared exceptions (unified messages; error order for multiply-invalid inputs), two unobservable differences (aggregate reclamation timing; snapshot read views), nothing else. +- `store.ts` ships in `dsh-scope` (peer dependencies unchanged: Cordis only; module-graph position unchanged) with per-file 100% coverage of layer selection and reclamation, synchronous action/undo ordering, throwing-action cleanup, throwing-change-listener rollback, exact disposer identity, `label`/`silent`, factory typing, cross-layer `some`, merge selectors, and separate named/anonymous entry semantics. Its five public symbols are re-exported from the package root and carry export JSDoc. +- `dsh-tools` and `dsh-system-prompt` each collapse to one `ScopedLayers`; every registration facade validates its domain contract and then makes one `effect` call, and all keep returning the exact Cordis effect disposer. +- Existing behavior, duplicate messages, validation order, live variable-provider re-entrancy, and live guard re-entrancy remain unchanged. Tests additionally pin aggregate reclamation timing and selector materialization. - Documentation lands in the same change: `dsh-scope`/`dsh-tools`/`dsh-system-prompt` READMEs; on implementation this RFC moves to `implemented/` and the [runtime-design RFC](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)'s registration section is updated in place. ## Risks -- The layer/facade boundary may not fit a future consumer's shape. Mitigation: the bare `ScopeLayer` interface remains the floor, and widening `LayerClass` to accept a factory (for layers with constructor dependencies) is a recorded non-breaking extension. -- `createLayer`'s mapped-type factory is deliberate type gymnastics. Accepted: the `defineTool` schema DSL is the repo precedent, and the gymnastics stay inside `dsh-scope`. -- The two equivalence exceptions can surprise tests that assert exact duplicate messages or multi-fault error order; they are declared here so review checks them rather than discovers them. -- Snapshot read views hide entries registered by a callback during its own iteration — a pathological pattern, but a visible one; snapshots make it deterministic instead. +- The layer/facade boundary may not fit a future consumer's shape. Mitigation: `ScopeLayer` requires only `isEmpty()`, while the factory closure can capture constructor dependencies without giving a layer ownership of its scheduler. +- A future registration may genuinely need asynchronous setup or several independently owned undos. The helper deliberately does not predict that lifecycle; such a consumer must first identify its owner and settlement boundary, then widen the contract with tests. +- Explicit layer declarations repeat three property initializers and `isEmpty()` in each consumer. Accepted: the repetition keeps runtime state and types visible and avoids a second DSL for two classes. - Two core registries migrate at once. Mitigated by the behavior comparison performed during design and by landing the store with equivalence-pinning tests before either migration commit. diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md index 6460802f3c..e2ec721457 100644 --- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md +++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md @@ -6,72 +6,70 @@ Status: proposed ## 问题 -agent 作用域落地之后([agent-scope RFC](../../implemented/architecture/2026-07-08-agent-scope-contexts.md)、[运行时设计篇](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)),「一张全局层加若干 per-agent 层的注册表」成为反复出现的形态,而每一处都是手写的。今天已有七个登记口——`dsh-tools` 的 `tools.register`/`tools.restrict`/`tools.guard` 与 `dsh-system-prompt` 的 `section`/`tools`/`variable`/`protect`——每处都是一个全局容器配一张自己的 `Map`,并重复同一段 10-15 行的 effect 编排:读调用方上下文的标签、按需建层、校验、变更、yield 一个「删条目 → 回收空层 → 发 change 事件」的回滚,然后发事件并返回 cordis effect 的原始 disposer。 +agent 作用域落地之后([agent-scope RFC](../../implemented/architecture/2026-07-08-agent-scope-contexts.md)、[运行时设计篇](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)),「一张全局层加若干 per-agent 层的注册表」成为反复出现的形态,而每一处都是手写的。今天已有六个登记口——`dsh-tools` 的 `tools.register`/`tools.restrict`/`tools.guard` 与 `dsh-system-prompt` 的 `section`/`tools`/`variable`——每处都围绕适用的全局或专属容器重复同一段 10-15 行的 effect 编排:读调用方上下文的标签、按需建层、校验、变更、yield 一个删除条目并回收空专属层的回滚、发适用的 change 事件,然后返回 Cordis effect 的原始 disposer。 除此之外:风险集中在编排细节上: - 回滚必须在 change 发出之前被收集(抛错的监听器才能回卷插入而不是泄漏) -- 返回的 disposer 必须是 cordis 自己的那个函数(包装器会静默破坏嵌套的有序拆除) +- 返回的 disposer 必须是 Cordis 自己的那个函数(包装器会静默破坏嵌套的有序拆除) - 清空的专属层必须被回收(被 dispose 的 agent 不得留下以死 `ScopeKey` 为键的残余) -每个新消费者都要把这一切重新写对一遍,而各副本的写法已经分叉——`dsh-tools` 里有两个私有 `layerFor`,`dsh-system-prompt` 里是四处内联 IIFE。 +每个新消费者都要把这一切重新写对一遍,而各副本的写法已经分叉——`dsh-tools` 里有两个私有建层 helper,`dsh-system-prompt` 里是三处内联 IIFE。 -最后,一个 agent 在一个服务里的贡献散落在几张互不相识的 Map 里——不存在一个「这个 scope 在这里贡献了什么」的对象——而消费者还在持续增多:guard 与提示词 protection 是最近落地的一批,per-agent 的 `fs/*` 策略、`llm/*` 覆盖、per-agent compaction 策略都排在同一个模式上。 +最后,一个 agent 在一个服务里的贡献散落在几张互不相识的 Map 里——不存在一个「这个 scope 在这里贡献了什么」的对象——而消费者还在持续增多:专属 guard 与 per-agent 提示词/工具组合是最近落地的一批,per-agent 的 `fs/*` 策略、`llm/*` 覆盖与 compaction 策略则是同一模式的潜在后续用户。 ## 提案 -`dsh-scope` 新增 store 模块(其 `src/` 下新增 `store.ts`,peer 依赖仅 cordis,与键类型无关),核心是一条分工:**业务逻辑封在层类里,helper 只负责调度层**。一个服务一个 helper 实例;其 Map 的 value 就是「一个 scope 在该服务的全部贡献」这一聚合对象。 +`dsh-scope` 新增与键类型无关的 `store.ts`,peer 依赖仍只有 Cordis。模块只抽取六个现有登记口已经共同证明的最小形状:**业务状态与校验留在显式层类里;一个 helper 统一负责选层、挂 effect、回滚、通知与回收**。一个 helper 实例属于一个服务;一个层实例聚合某 scope 对该服务的全部贡献。 -- **`ScopedLayers`**——具体的调度器,不作继承点。持有全局层与一张 `Map`,按需以 `new layerClass(scope, this)` 建层,层 `isEmpty()` 时回收,并把所有写入收拢到 `effect(ctx, action, options?)`。单一 `ctx` 参数同时决定可见层(`scopeOf(ctx)`)与属主 fiber(`ctx.effect`),「对 X 可见、随 Y 销毁」因此不可表达——与 agent-scope RFC 否决显式 scope 参数用的是同一个形状论证。action 可以产出单个撤销、撤销的可迭代、Promise 或异步可迭代——即 cordis `Effect` 的四种形态——且撤销允许异步。helper 把收集到的撤销(逆序执行)、空层回收与 change 通知合成**一个** disposer,并在通知运行**之前**先把它交给 cordis:因此 change 监听器抛错时,cordis 会执行已收集的回滚再重抛,与今天手写的「yield 在 emit 之前」逐字等价。读取件是 `global`/`peek`,外加把表视图提升到两层的三个 selector 原语——`merge`(命名条目,专属遮蔽全局、保留全局位置,可选放行谓词)、`values`(拼接、含匿名条目、刻意不做遮蔽)、`keys`(限制前名字全集)——以及跨全部层、返回数组的 `forEach`/`filter`/`map`。 -- **`createLayer({ 表名: table(kind) })`**——`defineTool` DSL 传统的类工厂。生成的基类在构造器里建好每张声明的表、把 scope 传下去、接收同族回引(`protected readonly layers: ScopedLayers`,由 helper 建层时注入;多态 `this` 型在子类中自动收窄),并对声明的表聚合 `isEmpty()`。`layer.<表名>` 是带完整类型的映射属性,写错表名是编译错误;表名 `scope`、`isEmpty`、`layers` 保留,冲突即抛。业务子类在类体里追加领域方法——单层查询、登记校验,以及经 `this.layers` 的跨层**只读**(写入仍必须走 `effect`);完全自定义的层也可以只实现单方法接口 `ScopeLayer`(`isEmpty()`)。 -- **`Entries`**——罐装条目表:命名条目(`insert`,同层重名抛一对指向 `agent.ctx` 的标准化文案)与匿名条目(`append`,进程内唯一 symbol 键、O(1) 撤销删除)共用一张保插入序的 Map;读视图(`keys`/`entries`/`values`)返回数组快照。 +- **`ScopedLayers`** 是具体调度器,不作基类。它持有全局层与一张 `Map`,通过显式工厂按需构造专属层,并在层 `isEmpty()` 时回收。`effect(ctx, action, options?)` 只接受一个同步 action,action 只返回一个同步 undo,因为六个现有登记口的完整形状就是如此。单一 `ctx` 同时决定可见层(`scopeOf(ctx)`)与属主 Cordis fiber(`ctx.effect`),「对 X 可见、随 Y 销毁」因此不可表达。helper 在通知监听器前 yield undo,返回 Cordis 的原始 disposer,并在校验或变更抛错时回收刚建出的空层。读取接口是 `global`/`peek`,以及 `merge`(命名条目的专属遮蔽与可选全局放行谓词)、`values`(不遮蔽地依次拼接全局与专属条目)、`keys`(限制前名字全集)和 `some`(跨层不变量检查)。 +- **显式 `ScopeLayer` 类**让每个服务的状态一眼可见。`ToolLayer` 与 `PromptLayer` 直接声明各自三项表属性与 `isEmpty()` 聚合;一个小工厂只向构造器传入 scope,闭包仍可捕获真实构造依赖。领域方法仍是普通类方法。代价是几行重复声明,收益是不用引入 mapped-type 类工厂、scheduler/layer 属主环、保留属性名和生成式运行时结构。 +- **`NamedEntries` 与 `AnonymousEntries`** 是两种共用的保插入序条目表。命名表暴露 `insert`/查询,并通过领域 `kind` 与 per-agent alternative 标签保持现有全局/专属重名文案;匿名表只暴露 `append`,以进程内唯一 symbol 作键支持 O(1) 撤销删除。分成两类以后,无意义的命名/匿名混用不可表达,key 类型也保持健全。迭代器借用表成员与带类型的贡献值,不会 clone 或 freeze 值;`ScopedLayers` 只物化服务读路径本来就需要的合并数组或 Map。 -`dsh-tools` 把三张表合并进一个 `ToolLayer`(领域方法 `addRestriction`——空过滤器/读取一次性/保留名/已知名校验,保留名单因读服务状态而以数据传入——加上 `admits` 与 `guardReason`),`dsh-system-prompt` 把四张表合并进一个 `PromptLayer`(`addProtection` 经同族回引做全局冲突自检,加上 `shadowedSections` 谓词)。每个门面都变成单次 `effect` 调用,携带 per-call 的 `label`、`silent`(guard 不发 change 事件)或 `scopedOnly`(布尔,或携带领域报错文案的字符串)选项。`assemble` 留在门面,三条硬理由:它没有合法接收者(主体 scope 的层可能不存在,而读路径绝不建层)、遮蔽语义强制先合并后求值(逐层渲染会求值被遮蔽的 provider,行为可观察地改变)、组装 waterfall、`toolOrder` 与 protection 恢复需要层不应持有的服务级资源。 +`dsh-tools` 把工具、已编译 restriction 与 guard 三张表合并进一个 `ToolLayer`。restriction 放行判断与 guard 求值归层所有;`run_code` 保留名、当前已知全局名集合等依赖服务配置的领域校验仍留在门面。只读 allow/deny 输入只编译一次,成为内部 Set。`dsh-system-prompt` 同样把 section、tool provider 与 variable 合并进一个 `PromptLayer`;门面通过 `layers.some` 完成 owner-final 跨层冲突检查。每个登记门面先完成公开参数校验,再以 label 做一次 `effect` 调用;guard 额外传 `silent: true`。通用 helper 不理解「restriction 必须由 scoped context 调用」之类领域规则。 -迁移保持行为等价,带两个声明的例外:三处重名文案统一为一个模板(断言旧文案的测试在同一变更中更新);校验相对 effect 边界发生挪动(restrict/protect 的检查移入 action,variable 的名字正则移到门面),因此多重非法输入的报错**先后**可能改变,而所有单一错误路径不变。两个已知的不可观察差异:聚合层要等全部表清空才回收;读视图是快照而非活容器(仅对「在自己的遍历回调里再注册」可见)。 +`assemble` 留在 `SystemPrompt` 门面,三条理由:主体 scope 的层可能不存在,读路径不得创建它;遮蔽语义要求先合并再求值,被遮蔽的 section provider 绝不能被调用;组装 waterfall、`toolOrder` 与 owner-final 恢复使用服务级资源。section 与 tool provider 保持既有的派生视图物化;variable provider 则直接遍历全局与专属 `NamedEntries`,保留 provider 在组装期间登记另一 variable 时的现有活 Map 行为。tool guard 同样直接遍历其 `AnonymousEntries`。owner-final 仍是 section 与 tool 贡献上的元数据,不是第二张 protection 注册表。 + +迁移保持公开行为与精确重名文案不变。内部聚合层会在三张表全部清空后才回收,而不是某一张表清空时回收;服务 API 不暴露层身份。直接活遍历保留现有 variable-provider 与 guard 重入行为,selector helper 则继续物化门面今天已经在构造的 section、tool-provider 与工具解析视图。 + +`ScopeLayer`、`EntryValues`、`ScopedLayers`、`NamedEntries` 与 `AnonymousEntries` 都是带 export JSDoc 的 `dsh-scope` 根导出。消费者从 `@deepseek-ai/dsh-scope` 导入;`store.ts` 是实现模块,不是 package subpath。 ## API 草图 ```ts ignore-check -interface ScopeLayer { +export interface ScopeLayer { isEmpty(): boolean } -type LayerClass = new (scope: ScopeKey | undefined, layers: ScopedLayers) => L - -declare function table(kind: string): TableSpec -declare function createLayer>>( - spec: S, -): LayerClass> }> - -type Undo = () => unknown -type LayerAction = (layer: L) => - | Undo - | Iterable - | Promise - | AsyncIterable - -class ScopedLayers { - constructor(layerClass: LayerClass, options: { label: string; onChange?: () => void }) +export class ScopedLayers { + constructor(createLayer: (scope: ScopeKey | undefined) => L, options: { onChange?: () => void }) readonly global: L peek(scope: ScopeKey | undefined): L | undefined - merge(scope: ScopeKey | undefined, pick: (layer: L) => Entries, admitGlobal?: (name: string) => boolean): Map - values(scope: ScopeKey | undefined, pick: (layer: L) => Entries): T[] - keys(scope: ScopeKey | undefined, pick: (layer: L) => Entries): string[] - effect(ctx: Context, action: LayerAction, options?: { label?: string; silent?: boolean; scopedOnly?: boolean | string }): () => Promise | void - forEach(fn: (layer: L, scope: ScopeKey | undefined) => void): void - filter(fn: (layer: L, scope: ScopeKey | undefined) => boolean): L[] - map(fn: (layer: L, scope: ScopeKey | undefined) => T): T[] + merge(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries, admitGlobal?: (name: string) => boolean): Map + values(scope: ScopeKey | undefined, pick: (layer: L) => EntryValues): T[] + keys(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries): string[] + some(fn: (layer: L, scope: ScopeKey | undefined) => boolean): boolean + effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => Promise | void } -class Entries { - constructor(kind: string, scope: ScopeKey | undefined) +export interface EntryValues { + values(): IterableIterator + isEmpty(): boolean +} + +export class NamedEntries implements EntryValues { + constructor(kind: string, perAgentAlternative: string, scope: ScopeKey | undefined) insert(name: string, value: V): () => void - append(value: V): () => void get(name: string): V | undefined has(name: string): boolean - keys(): string[] - entries(): ReadonlyArray - values(): readonly V[] + keys(): IterableIterator + entries(): IterableIterator<[string, V]> + values(): IterableIterator + isEmpty(): boolean +} + +export class AnonymousEntries implements EntryValues { + append(value: V): () => void + values(): IterableIterator isEmpty(): boolean } ``` @@ -79,21 +77,26 @@ class Entries { 迁移后的消费者长什么样——现存最重的登记口从 30+ 行编排缩为一份声明加一行门面: ```ts ignore-check -class ToolLayer extends createLayer({ - tools: table('tool'), - restrictions: table('tool restriction'), - guards: table('tool guard'), -}) { - addRestriction(filter: ToolRestriction, reserved: readonly string[]): () => void { /* validate, snapshot, append */ } +class ToolLayer implements ScopeLayer { + readonly tools = new NamedEntries('tool', 'variant', this.scope) + readonly restrictions = new AnonymousEntries() + readonly guards = new AnonymousEntries() + + constructor( + readonly scope: ScopeKey | undefined, + ) {} + + isEmpty(): boolean { return this.tools.isEmpty() && this.restrictions.isEmpty() && this.guards.isEmpty() } + addRestriction(filter: ToolRestriction): () => void { /* compile to sets, append */ } admits(name: string): boolean { /* intersection over this.restrictions.values() */ } guardReason(view: Readonly): string | undefined { /* first monotonic denial */ } } class ToolRegistry extends Service { - private readonly layers = new ScopedLayers(ToolLayer, { - label: 'tools', - onChange: () => this.ctx.emit('tools/change'), - }) + private readonly layers = new ScopedLayers( + scope => new ToolLayer(scope), + { onChange: () => this.ctx.emit('tools/change') }, + ) register(definition: ToolDefinition): () => Promise | void { return this.layers.effect(this.ctx, @@ -101,8 +104,9 @@ class ToolRegistry extends Service { { label: 'tools.register()' }) } - visible(scope?: ScopeKey): ToolDefinition[] { - return Array.from(this.layers.merge(scope, layer => layer.tools, name => this.admits(scope, name)).values()) + private resolveVisible(scope?: ScopeKey): ToolDefinition[] { + const scoped = this.layers.peek(scope) + return Array.from(this.layers.merge(scope, layer => layer.tools, name => scoped?.admits(name) ?? true).values()) } } ``` @@ -115,6 +119,10 @@ class ToolRegistry extends Service { **只抽数据结构、编排留在服务。** 消掉的是重复里安全的那一半,留下的是危险的那一半——回滚先于 emit 的顺序、原始 disposer、回收规则,恰是 bug 所在。 +**让 layer action 接受完整 Cordis `Effect` union。** 六个现有登记口都没有异步 setup、多份 undo 或独立 settlement 边界。现在就规范化 Promise、iterable、async iterable、LIFO 合成与部分失败,会重复一套纯属推测的生命周期 machinery。store 只接受一个同步 action 与一个 undo;未来出现真实边界时再凭证据拓宽。 + +**由 mapped-type 表 DSL 生成层类。** 两个消费者各自只有三张表。类工厂省下几行代码,却引入生成式运行时形状、保留名、多态 `this` 类型和第二种构造模型。显式类更易检查,同时仍可复用两种条目表与 `ScopedLayers`。 + **内置视图语义的固定容器 helper。** 容器形态与合并策略被钉死在 helper 里;业务没有自由度,任何命名或单值变体都变成对 helper 的功能诉求。 **每张表一个 helper。** 复刻今天的散装簿记——那正是被替换的现状:每服务 N 张 scope Map,agent 的贡献没有聚合。 @@ -125,15 +133,14 @@ class ToolRegistry extends Service { ## 验收标准 -- `store.ts` 落在 `dsh-scope`(peer 依赖不变:仅 cordis;模块图位置不变),逐文件 100% 覆盖,包括:层簿记与回收、四种 action 形态、合成顺序、change 监听器抛错回滚(条目被回卷、重名检查可再注册)、新建层的失败回收、`label`/`silent`/`scopedOnly` 选项、`createLayer` 构造、保留表名、同族回引类型、`Entries` 命名/匿名语义。 -- `dsh-tools` 与 `dsh-system-prompt` 各收敛为一个 `ScopedLayers`;所有既有测试通过,改动仅限已声明的重名文案断言更新;每个登记门面都是单次 `effect` 调用,并继续返回 cordis effect 的原始 disposer。 -- 行为按上文等价性声明与老基线一致:两个声明例外(统一文案;多重非法输入的报错先后)、两个不可观察差异(聚合回收时机;快照读视图),此外无他。 +- `store.ts` 落在 `dsh-scope`(peer 依赖不变:仅 Cordis;模块图位置不变),逐文件 100% 覆盖选层与回收、同步 action/undo 顺序、action 抛错清理、change 监听器抛错回滚、原始 disposer 身份、`label`/`silent`、工厂类型、跨层 `some`、合并 selector,以及分开的命名/匿名条目语义。五个公开符号从 package 根重导出并带 export JSDoc。 +- `dsh-tools` 与 `dsh-system-prompt` 各收敛为一个 `ScopedLayers`;每个登记门面先校验领域契约再做一次 `effect` 调用,并继续返回 Cordis effect 的原始 disposer。 +- 既有行为、重名文案、校验顺序、variable-provider 活重入与 guard 活重入不变。测试另行钉住聚合回收时机与 selector 物化。 - 文档随同一变更落地:`dsh-scope`/`dsh-tools`/`dsh-system-prompt` 的 README;实现后本 RFC 移入 `implemented/`,并就地更新[运行时设计 RFC](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md) 的注册章节。 ## 风险 -- 层/门面边界可能不适配某个未来消费者的形状。缓解:裸 `ScopeLayer` 接口始终是兜底;把 `LayerClass` 拓宽为可接受工厂(供有构造依赖的层)是已记录的非破坏扩展。 -- `createLayer` 的映射类型工厂是刻意的类型体操。接受:`defineTool` schema DSL 是仓库先例,体操圈在 `dsh-scope` 内部。 -- 两个等价性例外可能让断言精确重名文案或多重错误顺序的测试意外;在此声明,使评审是核对而非发现。 -- 快照读视图会隐藏「回调在自己的遍历中注册」的条目——病态但可见的模式;快照使其转为确定性行为。 +- 层/门面边界可能不适配某个未来消费者的形状。缓解:`ScopeLayer` 只要求 `isEmpty()`;工厂闭包可捕获构造依赖,无需让层反向持有 scheduler。 +- 未来登记口可能真的需要异步 setup 或多份独立属主的 undo。helper 刻意不预测这种生命周期;该消费者必须先说明 owner 与 settlement 边界,再连同测试拓宽契约。 +- 显式层声明会在两个消费者中各重复三行属性初始化与一段 `isEmpty()`。接受:这点重复让运行时状态和类型保持可见,避免为两个类引入第二套 DSL。 - 两个核心注册表同时迁移。缓解:设计期已完成逐行为对比,且 store 连同钉住等价性的测试先于任一迁移 commit 落地。 From 0289e69ee99f63cbb2149137c78d08fbd314e0fb Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 13 Jul 2026 12:08:41 +0800 Subject: [PATCH 007/273] docs(rfc): narrow scoped-layer disposers --- .../architecture/2026-07-12-scoped-layers-store.i18n.yaml | 4 ++-- .../proposed/architecture/2026-07-12-scoped-layers-store.md | 4 ++-- .../architecture/2026-07-12-scoped-layers-store.zh.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml index be26cfa552..bf5027e5ec 100644 --- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml +++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.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 -2026-07-12-scoped-layers-store.md: c3a9ab8724191b5b1bc87f02a90d6995c247d944 -2026-07-12-scoped-layers-store.zh.md: e2ec72145766a95ea1c330e3a658f7c86490e263 +2026-07-12-scoped-layers-store.md: 510f462344b25b72bb8604d88f125cc92c6510b1 +2026-07-12-scoped-layers-store.zh.md: abc2aad140cc10325392ed8800e33e38684511a8 diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md index c3a9ab8724..510f462344 100644 --- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md +++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md @@ -48,7 +48,7 @@ export class ScopedLayers { values(scope: ScopeKey | undefined, pick: (layer: L) => EntryValues): T[] keys(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries): string[] some(fn: (layer: L, scope: ScopeKey | undefined) => boolean): boolean - effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => Promise | void + effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => void } export interface EntryValues { @@ -98,7 +98,7 @@ class ToolRegistry extends Service { { onChange: () => this.ctx.emit('tools/change') }, ) - register(definition: ToolDefinition): () => Promise | void { + register(definition: ToolDefinition): () => void { return this.layers.effect(this.ctx, layer => layer.tools.insert(definition.name, definition), { label: 'tools.register()' }) diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md index e2ec721457..abc2aad140 100644 --- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md +++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md @@ -48,7 +48,7 @@ export class ScopedLayers { values(scope: ScopeKey | undefined, pick: (layer: L) => EntryValues): T[] keys(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries): string[] some(fn: (layer: L, scope: ScopeKey | undefined) => boolean): boolean - effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => Promise | void + effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => void } export interface EntryValues { @@ -98,7 +98,7 @@ class ToolRegistry extends Service { { onChange: () => this.ctx.emit('tools/change') }, ) - register(definition: ToolDefinition): () => Promise | void { + register(definition: ToolDefinition): () => void { return this.layers.effect(this.ctx, layer => layer.tools.insert(definition.name, definition), { label: 'tools.register()' }) From 0646bae562ffb3c9f50152703e74bcc051c90cb4 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 13 Jul 2026 13:49:25 +0800 Subject: [PATCH 008/273] docs(rfc): narrow scoped-layer abstraction --- .../2026-07-12-scoped-layers-store.i18n.yaml | 4 ++-- .../architecture/2026-07-12-scoped-layers-store.md | 9 ++++----- .../architecture/2026-07-12-scoped-layers-store.zh.md | 9 ++++----- 3 files changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml index bf5027e5ec..c12497f016 100644 --- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.i18n.yaml +++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.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 -2026-07-12-scoped-layers-store.md: 510f462344b25b72bb8604d88f125cc92c6510b1 -2026-07-12-scoped-layers-store.zh.md: abc2aad140cc10325392ed8800e33e38684511a8 +2026-07-12-scoped-layers-store.md: f2056446abb3b8d0793b6ef7898c01001ccf0460 +2026-07-12-scoped-layers-store.zh.md: 9726eb3de953af1086d8bcdd779fc02b3c324596 diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md index 510f462344..f2056446ab 100644 --- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md +++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.md @@ -21,13 +21,13 @@ Finally, one agent's contribution to one service is scattered across several map `dsh-scope` gains a key-agnostic `store.ts`, with Cordis as its only peer dependency. The module implements the smallest abstraction shared by the six current sites: **business state and validation stay in an explicit layer class; one helper owns layer selection, effect attachment, rollback, notification, and reclamation**. One helper instance belongs to one service, and one layer instance aggregates everything a scope contributes to that service. -- **`ScopedLayers`** is a concrete scheduler, not a base class. It owns the global layer plus one `Map`, constructs scoped layers on demand through an explicit factory, and reclaims a layer when `isEmpty()`. Its `effect(ctx, action, options?)` accepts one synchronous action that returns one synchronous undo because that is the complete shape of all six current sites. The single `ctx` decides both the visible layer (`scopeOf(ctx)`) and the owning Cordis fiber (`ctx.effect`), so "visible to X, disposed with Y" stays unrepresentable. The helper yields the undo before notifying listeners, returns Cordis's exact disposer, and reclaims a newly created empty layer if validation or mutation throws. Reads are `global`/`peek` plus `merge` (named entries with scoped shadowing and an optional global-admission predicate), `values` (global then scoped concatenation without shadowing), `keys` (the pre-restriction name universe), and `some` (cross-layer invariant checks). +- **`ScopedLayers`** is a concrete scheduler, not a base class. It owns the global layer plus one `Map`, constructs scoped layers on demand through an explicit factory, and reclaims a layer when `isEmpty()`. Its `effect(ctx, action, options?)` accepts one synchronous action that returns one synchronous undo because that is the complete shape of all six current sites. The single `ctx` decides both the visible layer (`scopeOf(ctx)`) and the owning Cordis fiber (`ctx.effect`), so "visible to X, disposed with Y" stays unrepresentable. The helper yields the undo before notifying listeners, returns Cordis's exact disposer, and reclaims a newly created empty layer if validation or mutation throws. Reads are `global`/`peek` plus `merge` (named entries with scoped shadowing and an optional global-admission predicate), `values` (global then scoped concatenation without shadowing), and `keys` (the pre-restriction name universe). - **Explicit `ScopeLayer` classes** make each service's state visible to readers. `ToolLayer` and `PromptLayer` declare their three table properties and their `isEmpty()` aggregation directly; a small layer factory receives only the scope, while its closure may capture real constructor dependencies. Domain methods stay ordinary class methods. This costs a few repetitive declarations but avoids a mapped-type class factory, a scheduler/layer ownership cycle, reserved property names, and generated runtime structure. - **`NamedEntries` and `AnonymousEntries`** are the two shared insertion-ordered tables. Named entries expose `insert`/lookup and retain the current global/scoped duplicate wording through domain `kind` and per-agent-alternative labels; anonymous entries expose only `append`, using process-unique symbol keys for O(1) undo removal. Keeping the classes separate makes meaningless mixed named/anonymous operations unrepresentable and keeps key types sound. Their iterators borrow membership and typed contribution values; they do not clone or freeze values. `ScopedLayers` materializes only the merged arrays/maps already required by the service read paths. -`dsh-tools` migrates its three tables into one `ToolLayer`: tools, compiled restrictions, and guards. The layer owns restriction admission and guard evaluation; the facade retains domain validation that needs service configuration, such as the reserved `run_code` name and the current known-global-name universe. Readonly allow/deny inputs are compiled once into internal sets. `dsh-system-prompt` likewise migrates sections, tool providers, and variables into one `PromptLayer`; its facade performs owner-final cross-layer checks through `layers.some`. Every registration facade performs its public argument validation and then makes one `effect` call with a label and, for guards, `silent: true`. A generic helper does not learn domain rules such as "restrictions require a scoped context." +`dsh-tools` migrates its three tables into one `ToolLayer`: tools, compiled restrictions, and guards. The layer owns restriction admission and guard evaluation; the facade retains domain validation that needs service configuration, such as the reserved `run_code` name and the current known-global-name universe. Readonly allow/deny inputs are compiled once into internal sets. `dsh-system-prompt` likewise migrates sections, tool providers, and variables into one `PromptLayer`. Every registration facade performs its public argument validation and then makes one `effect` call with a label and, for guards, `silent: true`. A generic helper does not learn domain rules such as "restrictions require a scoped context." -`assemble` stays in the `SystemPrompt` facade for three reasons: the subject scope's layer may not exist and reads must not create it; shadowing requires merge-before-evaluate so a hidden section provider is never called; and the assembly waterfall, `toolOrder`, and owner-final restoration use service-level resources. Sections and tool providers keep their current materialized derived views. Variable providers instead iterate the global and scoped `NamedEntries` directly, preserving today's live Map behavior when a provider registers another variable during assembly. Tool guards likewise iterate their `AnonymousEntries` directly. Owner-final remains metadata on section and tool contributions, not a second protection registry. +`assemble` stays in the `SystemPrompt` facade for three reasons: the subject scope's layer may not exist and reads must not create it; shadowing requires merge-before-evaluate so a hidden section provider is never called; and the assembly waterfall and `toolOrder` use service-level resources. Sections and tool providers keep their current materialized derived views. Variable providers instead iterate the global and scoped `NamedEntries` directly, preserving today's live Map behavior when a provider registers another variable during assembly. Tool guards likewise iterate their `AnonymousEntries` directly. Migration preserves public behavior and exact duplicate messages. The internal aggregate layer is reclaimed only after all three tables empty rather than when one table empties; no service API exposes layer identity. Direct live iteration retains current re-entrant variable-provider and guard behavior, while selector helpers continue to materialize the same section, tool-provider, and tool-resolution views their facades build today. @@ -47,7 +47,6 @@ export class ScopedLayers { merge(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries, admitGlobal?: (name: string) => boolean): Map values(scope: ScopeKey | undefined, pick: (layer: L) => EntryValues): T[] keys(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries): string[] - some(fn: (layer: L, scope: ScopeKey | undefined) => boolean): boolean effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => void } @@ -133,7 +132,7 @@ class ToolRegistry extends Service { ## Acceptance criteria -- `store.ts` ships in `dsh-scope` (peer dependencies unchanged: Cordis only; module-graph position unchanged) with per-file 100% coverage of layer selection and reclamation, synchronous action/undo ordering, throwing-action cleanup, throwing-change-listener rollback, exact disposer identity, `label`/`silent`, factory typing, cross-layer `some`, merge selectors, and separate named/anonymous entry semantics. Its five public symbols are re-exported from the package root and carry export JSDoc. +- `store.ts` ships in `dsh-scope` (peer dependencies unchanged: Cordis only; module-graph position unchanged) with per-file 100% coverage of layer selection and reclamation, synchronous action/undo ordering, throwing-action cleanup, throwing-change-listener rollback, exact disposer identity, `label`/`silent`, factory typing, merge selectors, and separate named/anonymous entry semantics. Its five public symbols are re-exported from the package root and carry export JSDoc. - `dsh-tools` and `dsh-system-prompt` each collapse to one `ScopedLayers`; every registration facade validates its domain contract and then makes one `effect` call, and all keep returning the exact Cordis effect disposer. - Existing behavior, duplicate messages, validation order, live variable-provider re-entrancy, and live guard re-entrancy remain unchanged. Tests additionally pin aggregate reclamation timing and selector materialization. - Documentation lands in the same change: `dsh-scope`/`dsh-tools`/`dsh-system-prompt` READMEs; on implementation this RFC moves to `implemented/` and the [runtime-design RFC](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md)'s registration section is updated in place. diff --git a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md index abc2aad140..9726eb3de9 100644 --- a/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md +++ b/docs/rfc/proposed/architecture/2026-07-12-scoped-layers-store.zh.md @@ -21,13 +21,13 @@ agent 作用域落地之后([agent-scope RFC](../../implemented/architecture/2 `dsh-scope` 新增与键类型无关的 `store.ts`,peer 依赖仍只有 Cordis。模块只抽取六个现有登记口已经共同证明的最小形状:**业务状态与校验留在显式层类里;一个 helper 统一负责选层、挂 effect、回滚、通知与回收**。一个 helper 实例属于一个服务;一个层实例聚合某 scope 对该服务的全部贡献。 -- **`ScopedLayers`** 是具体调度器,不作基类。它持有全局层与一张 `Map`,通过显式工厂按需构造专属层,并在层 `isEmpty()` 时回收。`effect(ctx, action, options?)` 只接受一个同步 action,action 只返回一个同步 undo,因为六个现有登记口的完整形状就是如此。单一 `ctx` 同时决定可见层(`scopeOf(ctx)`)与属主 Cordis fiber(`ctx.effect`),「对 X 可见、随 Y 销毁」因此不可表达。helper 在通知监听器前 yield undo,返回 Cordis 的原始 disposer,并在校验或变更抛错时回收刚建出的空层。读取接口是 `global`/`peek`,以及 `merge`(命名条目的专属遮蔽与可选全局放行谓词)、`values`(不遮蔽地依次拼接全局与专属条目)、`keys`(限制前名字全集)和 `some`(跨层不变量检查)。 +- **`ScopedLayers`** 是具体调度器,不作基类。它持有全局层与一张 `Map`,通过显式工厂按需构造专属层,并在层 `isEmpty()` 时回收。`effect(ctx, action, options?)` 只接受一个同步 action,action 只返回一个同步 undo,因为六个现有登记口的完整形状就是如此。单一 `ctx` 同时决定可见层(`scopeOf(ctx)`)与属主 Cordis fiber(`ctx.effect`),「对 X 可见、随 Y 销毁」因此不可表达。helper 在通知监听器前 yield undo,返回 Cordis 的原始 disposer,并在校验或变更抛错时回收刚建出的空层。读取接口是 `global`/`peek`,以及 `merge`(命名条目的专属遮蔽与可选全局放行谓词)、`values`(不遮蔽地依次拼接全局与专属条目)和 `keys`(限制前名字全集)。 - **显式 `ScopeLayer` 类**让每个服务的状态一眼可见。`ToolLayer` 与 `PromptLayer` 直接声明各自三项表属性与 `isEmpty()` 聚合;一个小工厂只向构造器传入 scope,闭包仍可捕获真实构造依赖。领域方法仍是普通类方法。代价是几行重复声明,收益是不用引入 mapped-type 类工厂、scheduler/layer 属主环、保留属性名和生成式运行时结构。 - **`NamedEntries` 与 `AnonymousEntries`** 是两种共用的保插入序条目表。命名表暴露 `insert`/查询,并通过领域 `kind` 与 per-agent alternative 标签保持现有全局/专属重名文案;匿名表只暴露 `append`,以进程内唯一 symbol 作键支持 O(1) 撤销删除。分成两类以后,无意义的命名/匿名混用不可表达,key 类型也保持健全。迭代器借用表成员与带类型的贡献值,不会 clone 或 freeze 值;`ScopedLayers` 只物化服务读路径本来就需要的合并数组或 Map。 -`dsh-tools` 把工具、已编译 restriction 与 guard 三张表合并进一个 `ToolLayer`。restriction 放行判断与 guard 求值归层所有;`run_code` 保留名、当前已知全局名集合等依赖服务配置的领域校验仍留在门面。只读 allow/deny 输入只编译一次,成为内部 Set。`dsh-system-prompt` 同样把 section、tool provider 与 variable 合并进一个 `PromptLayer`;门面通过 `layers.some` 完成 owner-final 跨层冲突检查。每个登记门面先完成公开参数校验,再以 label 做一次 `effect` 调用;guard 额外传 `silent: true`。通用 helper 不理解「restriction 必须由 scoped context 调用」之类领域规则。 +`dsh-tools` 把工具、已编译 restriction 与 guard 三张表合并进一个 `ToolLayer`。restriction 放行判断与 guard 求值归层所有;`run_code` 保留名、当前已知全局名集合等依赖服务配置的领域校验仍留在门面。只读 allow/deny 输入只编译一次,成为内部 Set。`dsh-system-prompt` 同样把 section、tool provider 与 variable 合并进一个 `PromptLayer`。每个登记门面先完成公开参数校验,再以 label 做一次 `effect` 调用;guard 额外传 `silent: true`。通用 helper 不理解「restriction 必须由 scoped context 调用」之类领域规则。 -`assemble` 留在 `SystemPrompt` 门面,三条理由:主体 scope 的层可能不存在,读路径不得创建它;遮蔽语义要求先合并再求值,被遮蔽的 section provider 绝不能被调用;组装 waterfall、`toolOrder` 与 owner-final 恢复使用服务级资源。section 与 tool provider 保持既有的派生视图物化;variable provider 则直接遍历全局与专属 `NamedEntries`,保留 provider 在组装期间登记另一 variable 时的现有活 Map 行为。tool guard 同样直接遍历其 `AnonymousEntries`。owner-final 仍是 section 与 tool 贡献上的元数据,不是第二张 protection 注册表。 +`assemble` 留在 `SystemPrompt` 门面,三条理由:主体 scope 的层可能不存在,读路径不得创建它;遮蔽语义要求先合并再求值,被遮蔽的 section provider 绝不能被调用;组装 waterfall 与 `toolOrder` 使用服务级资源。section 与 tool provider 保持既有的派生视图物化;variable provider 则直接遍历全局与专属 `NamedEntries`,保留 provider 在组装期间登记另一 variable 时的现有活 Map 行为。tool guard 同样直接遍历其 `AnonymousEntries`。 迁移保持公开行为与精确重名文案不变。内部聚合层会在三张表全部清空后才回收,而不是某一张表清空时回收;服务 API 不暴露层身份。直接活遍历保留现有 variable-provider 与 guard 重入行为,selector helper 则继续物化门面今天已经在构造的 section、tool-provider 与工具解析视图。 @@ -47,7 +47,6 @@ export class ScopedLayers { merge(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries, admitGlobal?: (name: string) => boolean): Map values(scope: ScopeKey | undefined, pick: (layer: L) => EntryValues): T[] keys(scope: ScopeKey | undefined, pick: (layer: L) => NamedEntries): string[] - some(fn: (layer: L, scope: ScopeKey | undefined) => boolean): boolean effect(ctx: Context, action: (layer: L) => () => void, options: { label: string; silent?: boolean }): () => void } @@ -133,7 +132,7 @@ class ToolRegistry extends Service { ## 验收标准 -- `store.ts` 落在 `dsh-scope`(peer 依赖不变:仅 Cordis;模块图位置不变),逐文件 100% 覆盖选层与回收、同步 action/undo 顺序、action 抛错清理、change 监听器抛错回滚、原始 disposer 身份、`label`/`silent`、工厂类型、跨层 `some`、合并 selector,以及分开的命名/匿名条目语义。五个公开符号从 package 根重导出并带 export JSDoc。 +- `store.ts` 落在 `dsh-scope`(peer 依赖不变:仅 Cordis;模块图位置不变),逐文件 100% 覆盖选层与回收、同步 action/undo 顺序、action 抛错清理、change 监听器抛错回滚、原始 disposer 身份、`label`/`silent`、工厂类型、合并 selector,以及分开的命名/匿名条目语义。五个公开符号从 package 根重导出并带 export JSDoc。 - `dsh-tools` 与 `dsh-system-prompt` 各收敛为一个 `ScopedLayers`;每个登记门面先校验领域契约再做一次 `effect` 调用,并继续返回 Cordis effect 的原始 disposer。 - 既有行为、重名文案、校验顺序、variable-provider 活重入与 guard 活重入不变。测试另行钉住聚合回收时机与 selector 物化。 - 文档随同一变更落地:`dsh-scope`/`dsh-tools`/`dsh-system-prompt` 的 README;实现后本 RFC 移入 `implemented/`,并就地更新[运行时设计 RFC](../../implemented/architecture/2026-07-12-agent-scope-runtime-design.md) 的注册章节。 From 66b2cfc6098f4fe1ee795707ccf0ab87a781fea3 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Wed, 15 Jul 2026 17:34:24 +0800 Subject: [PATCH 009/273] docs(rfc): propose LSP capability seam --- docs/rfc/INDEX.md | 1 + .../2026-07-15-lsp-capability-seam.i18n.yaml | 6 + .../2026-07-15-lsp-capability-seam.md | 198 ++++++++++++++++++ .../2026-07-15-lsp-capability-seam.zh.md | 198 ++++++++++++++++++ 4 files changed, 403 insertions(+) create mode 100644 docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.i18n.yaml create mode 100644 docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.md create mode 100644 docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.zh.md diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index a374e795bc..a0dd29d0b5 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -28,6 +28,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; |---|---| | [Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern)](proposed/architecture/2026-06-16-typed-event-schemas.md) | 2026-06-16 | | [Extract a generic long-running tool runtime](proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md) | 2026-06-20 | +| [LSP capability seam and model-facing query tool](proposed/architecture/2026-07-15-lsp-capability-seam.md) | 2026-07-15 | ### Process diff --git a/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.i18n.yaml new file mode 100644 index 0000000000..75d69a5dcb --- /dev/null +++ b/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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 +2026-07-15-lsp-capability-seam.md: 89e58c3ae0ba9f49ed0164a76a230b141296eee5 +2026-07-15-lsp-capability-seam.zh.md: c1c2448b1e980fc17a347f6c434e8553639304f3 diff --git a/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.md b/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.md new file mode 100644 index 0000000000..89e58c3ae0 --- /dev/null +++ b/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.md @@ -0,0 +1,198 @@ +# RFC: LSP capability seam and model-facing query tool + +Status: proposed + +English | [中文](2026-07-15-lsp-capability-seam.zh.md) + +## Problem + +The harness has text search and file reads, but neither identifies a program symbol. A textual match cannot reliably distinguish two same-named functions, follow an import alias, connect an interface to its implementations, or report an inferred type. Before changing code, an agent therefore lacks the semantic navigation that a human gets from an editor's language server. + +LSP support has three owners: the model needs a stable query schema, the harness needs provider selection and normalized results, and the local implementation needs process, JSON-RPC, workspace, synchronization, and filesystem behavior. Combining them would bind the model contract to local subprocesses and obstruct remote or sandbox-native providers. + +Many language servers behave best when the queried document is opened with current text. A compatible agent client must bound that state, define whether its source read is a model observation, and keep the document snapshot in the same filesystem namespace as the server's workspace index. + +## Proposal + +Add LSP as a three-package capability seam with one read-only model tool and one generic local provider implementation: + +1. `@deepseek-ai/dsh-lsp` at `packages/lsp/lsp` owns `ctx.lsp`, provider registration and selection, normalized requests/results, execution control, and structured LSP errors. +2. `@deepseek-ai/dsh-lsp-local` at `packages/lsp/lsp-local` adapts configured stdio language servers to the seam. Multiple plugin instances may register different server commands and extension-to-language-id mappings. +3. `@deepseek-ai/dsh-tool-lsp` at `packages/lsp/tool-lsp` owns the model-facing `lsp` schema, prompt guidance, argument validation, result limits and formatting, and ACP presentation. + +`dsh-lsp-local` is a generic host, not a language-server catalog or installer. Deployments explicitly configure commands and mappings; future presets belong in composition plugins or `cordis.yml` overlays. + +The model and seam expose exactly `definition`, `references`, `implementation`, and `hover`; no arbitrary JSON-RPC method escapes through `ctx.lsp`. + +The prompt positions LSP as a precision aid: `Use search/read for ordinary navigation. Use lsp when textual matches are ambiguous or before a change requires precise definitions, implementations, or references.` + +## Package and ownership boundaries + +`dsh-lsp` registers providers by branded id and extension-to-language-id mapping. `registerProvider()` atomically reserves the id and every normalized extension: invalid input or any conflict publishes nothing, and its disposer releases all reservations. Provider plugins register through `ctx.effect()`. Selection is per query and order-independent; no match returns a structured unavailable error. The first version has no glob, language-id, or explicit route selector and no statically declared operation capabilities. + +The seam exposes one `query(request, signal?)` operation because no fields need implementation defaulting: `workspaceRoot` is required, `languageId` comes from the registration, and consumers own timeouts and result limits. `query()` validates, selects, and derives without hidden `??` fallbacks, leaving no executable spec to resolve. `dsh-tool-lsp` passes only `exec.signal` as a bare `AbortSignal`, matching web and keeping `dsh-lsp` independent of `dsh-tools`. Removal before selection fails as unavailable; later disposal follows the selected provider's cancellation lifecycle without rerouting. + +The intended contract shape is: + +```ts +import type { Branded } from '@deepseek-ai/dsh-brand' + +type LspOperation = 'definition' | 'references' | 'implementation' | 'hover' +type LspProviderId = Branded<'LspProviderId'> + +interface LspPosition { + readonly line: number + readonly character: number +} + +interface LspRange { + readonly start: LspPosition + readonly end: LspPosition +} + +interface LspQueryRequest { + readonly operation: LspOperation + readonly filePath: string + readonly position: LspPosition + readonly workspaceRoot: string +} + +interface LspProviderQuery extends LspQueryRequest { + readonly languageId: string +} + +type LspQueryResult = + | { readonly kind: 'locations'; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[] } + | { readonly kind: 'hover'; readonly hover: { readonly contents: string; readonly range?: LspRange } | null } + +interface LspProvider { + readonly id: LspProviderId + readonly extensionToLanguage: Readonly> + query(request: LspProviderQuery, signal?: AbortSignal): Promise +} + +interface LspService { + registerProvider(provider: LspProvider): () => void + query(request: LspQueryRequest, signal?: AbortSignal): Promise +} +``` + +Mapping keys normalize to lowercase, leading-dot extensions selected from `filePath`'s final extension; language ids only synchronize documents. Seam positions and ranges are zero-based UTF-16. `references` always includes declarations: providers enforce this internally, the local mapping sets `context.includeDeclaration: true`, and callers get no flag. Closed result unions normalize navigation to locations and hover to content or `null`. The seam exposes no protocol types, process or document controls, or generic request escape hatch. + +`dsh-lsp-local` owns host files, server configuration, JSON-RPC, process and transient-document state, and protocol translation; it depends on `dsh-lsp` and Node APIs, not `dsh-fs`. `dsh-tool-lsp` runtime-injects only `tools`, `lsp`, and `systemPrompt`, obtains the workspace from `exec.agent?.session.header.cwd` through a package-local `sessionCwd(exec)` helper matching the filesystem tools' lookup, and imports no provider. + +## Model-facing contract + +The single `lsp` tool accepts: + +```ts +interface LspToolInput { + readonly operation: 'definition' | 'references' | 'implementation' | 'hover' + readonly file_path: string + readonly line: number + readonly character: number +} +``` + +`line` and `character` are positive, one-based UTF-16 cursor coordinates; the tool converts them to the seam's zero-based `LspPosition` and converts rendered locations back. `references` includes declarations so impact analysis does not omit the defining site. Provider, language id, workspace root, limits, timeout, initialization, and executable remain outside model input. + +The tool requires `workspaceRoot` from session `header.cwd`, with no fallback; absence fails as `LSP_WORKSPACE_REQUIRED` before querying or startup. The local provider resolves relative paths against that root and accepts absolute paths directly; both forms are canonicalized and rejected before startup when the target is outside the canonical workspace. + +Locations render as stable, file-grouped `path:line:character` entries. A `file:` URI accepted by Node `fileURLToPath()` becomes a relative path inside the workspace or an absolute path outside it; other URIs remain verbatim. `maxLocations` defaults to `100`, and `maxHoverChars` defaults to `16_000` after hover normalization; both report omissions. Empty locations and `null` hover are successful no-result responses; malformed payloads remain structured errors. + +ACP uses `{ card: 'generic', kind: 'search', title, locations: [{ path: file_path, line }] }` with an args-derived operation/cursor `title`. Because `FileLocation` has no character, follow-along focuses the input line while the title preserves the cursor; presentation remains pure. + +## Timeout ownership + +`dsh-tool-lsp` attaches one configurable `timeoutMs` budget, default `60_000`, to the tool definition. `dsh-timeout-policy` enforces it and supplies `exec.signal`, which reaches `ctx.lsp.query`; the budget covers the complete queued open/query/close lifecycle and is not model-configurable. + +The seam and provider add no startup or request deadline. Non-tool callers therefore receive no hidden timeout and must supply an `AbortSignal`, using `deadline()` when they need a budget. + +Provider disposal occurs outside tool execution, so `dsh-lsp-local` keeps `shutdownTimeoutMs` (default `5_000`) for `shutdown`/`exit` and `killGraceMs` (default `2_000`) before hard kill; the same bounds govern failed-instance cleanup. It uses `deadline()` and `timeoutOf()` but owns request cancellation, process signals, and awaiting close because timeout notification does not terminate work. + +## Workspace, filesystem, and document synchronization + +`dsh-lsp-local` canonicalizes and reads through Node APIs in the subprocess's host namespace. It rejects missing, non-regular, non-UTF-8, oversized, or canonical out-of-workspace sources and keeps one handle through validation and reading. It does not consume `ctx.fs` or emit `fs/observed`: only the LSP result is model-visible, so the query does not satisfy read-before-write policy. + +The `read` tool is unsuitable source because its output is windowed, numbered, transcript-visible, and observed. Reading in `tool-lsp` would also assign provider-specific synchronization to the consumer and preclude non-local providers. + +The local provider uses a compatibility-first transient-open sequence for every query. It accepts legacy `textDocumentSync` `Full` or `Incremental`, or options with `openClose: true`; omitted, `None`, or explicitly incompatible synchronization fails as unsupported before `didOpen`. + +1. Canonicalize and validate the host path, then read the current source with Node filesystem APIs. +2. Send `textDocument/didOpen` with version `1`, full text, and the configured language id. +3. Send the requested `textDocument/definition`, `textDocument/references`, `textDocument/implementation`, or `textDocument/hover` request. +4. If `didOpen` succeeded, attempt `textDocument/didClose` in `finally` after the request settles or aborts. A close-write failure does not replace the settled result or error, but invalidates the instance and awaits bounded process termination. + +Documents close after each call, so the first version needs no `didChange`, `didSave`, content cache, mutation listener, or document LRU. One abortable per-instance queue serializes complete lifecycles; distinct instances may run in parallel. The server's workspace index remains responsible for closed files reached from the source. + +The canonical workspace `realpath` must be a directory and supplies process cwd, `rootUri`, the sole `workspaceFolders` entry, and pool identity; symlink aliases therefore share an instance. Result locations may be external, but an external path cannot become a query source. Remote, virtual, or independently sandboxed filesystems require another provider. + +## Local server lifecycle and protocol behavior + +`dsh-lsp-local` lazily single-flights one server per `(provider id, canonical workspace realpath)`. At load it resolves the executable after credential scrubbing and environment overrides, failing before registration if unavailable; resolution stays lazy and launch uses no shell. `maxMessageBytes` defaults to `16_000_000`, `maxStderrBytes` to `1_000_000`, and `maxDocumentBytes` to `4_000_000`. A crash fails the active query without replay; a later query may replace the process. Each query starts at most one process, so the MVP has no cross-request restart counter. + +Initialization advertises `general.positionEncodings: ['utf-16']`, `workspace: { workspaceFolders: true, configuration: true }`, `textDocument.hover.contentFormat: ['markdown', 'plaintext']`, and `linkSupport: true` for definition and implementation, with no dynamic registration. Returned operation and synchronization capabilities are authoritative. An omitted server `positionEncoding` defaults to `utf-16`; any other value is a protocol error. Configuration may supply initialization options and `workspace/configuration` responses, but the client rejects `workspace/applyEdit` and never executes commands or edits. + +Navigation maps `Location` directly and `LocationLink` from `targetUri` plus `targetSelectionRange`. Hover normalization takes `MarkupContent.value`, preserves string `MarkedString` values, renders language-tagged values as fenced code, joins arrays with one blank line, and applies `maxHoverChars` last. + +Abort reaches every query phase and sends `$/cancelRequest` once an id exists. An unresponsive server is terminated and awaited without collateral active work because the instance is serialized. Disposal rejects and cancels work, attempts graceful shutdown, escalates through bounded termination, and awaits quiescence. + +## Deliberately deferred surface + +Symbols are deferred because they need different schemas and overlap read/search; a future workspace-symbol tool must accept a search query. Call hierarchy is deferred because support is uneven, and `prepareCallHierarchy` remains an internal prerequisite rather than a model operation. + +Diagnostics need separate freshness, accumulation, and transcript rules. Mutations such as rename, code actions, and formatting require separate tools with preview, permission, and write-policy integration. + +The local provider trusts its configured server and claims no sandbox confinement. Supporting untrusted binaries requires a later process/filesystem contract for workspace reads plus private cache and temporary writes; restricted, remote, or virtual workspaces require another provider. + +## Alternatives considered + +**Copy Claude Code's unified schema.** Its cursor operations validate the core use case, but symbols and call hierarchy need different arguments. Copying all nine operations would freeze speculative surface, so the proposal aligns only on the four semantic queries. + +**Let providers register tools.** Loaded servers would then control model schema and prompts, preventing one stable contract across local and remote providers. + +**Expose arbitrary LSP methods.** A JSON-RPC escape hatch would leak protocol payloads and admit unreviewed mutation or command execution; the operation union stays closed. + +**Expose `resolve(request)` / `query(spec)`.** With no defaulted fields, resolution would only expose provider selection, and a public spec could outlive provider disposal or replacement. One operation keeps selection and invocation atomic to the registration lifetime. + +**Wrap the signal in a per-seam execution-context object.** Web passes a bare `AbortSignal`; wrapping this single field would add unexplained asymmetry. `query()` gains a context object only when another field requires it. + +**Read through `ctx.fs` or the `read` tool.** This could mix the document with a server index from another filesystem namespace; tool output is also windowed, numbered, and observed. The host-local provider reads unobserved full text beside its subprocess. + +**Keep documents open.** Mirroring edits requires version ownership, all-path `didChange`, HMR recovery, eviction, and stale-state rules. Transient opens avoid that MVP state machine. + +**Configure phase timeouts.** Nested timers create competing classifications and fresh budgets. One caller-owned deadline covers query work; only out-of-call teardown keeps local bounds. + +**Query without `didOpen`.** Although permitted, support is inconsistent and may use stale server state. Transient open supplies an explicit current snapshot. + +**Add routes or select the first match.** Registration order and HMR timing are not product semantics, while a route table duplicates unique extension ownership. Overlaps therefore fail registration. + +**Run concurrent queries in one instance.** If cancellation fails, terminating the shared process would kill unrelated work. Per-instance serialization limits that blast radius; instances remain parallel. + +**Ship presets or PATH discovery.** A catalog would make the generic host own language policy, while discovery cannot infer arguments, language ids, or initialization. Deployments configure providers explicitly; composition plugins may package presets. + +## Acceptance criteria + +- Package tests pin the three-package dependency direction, runtime injections, and `ctx.lsp`-only communication. +- Tool tests pin the four operations, coordinate validation, configured bounds and omission markers, prompt, and ACP presentation. +- Registry tests pin atomic reservation/release, order-independent selection, and structured unavailable, disposed, conflict, and unsupported-operation errors. +- Fake-stdio tests pin exact initialization capabilities, four protocol mappings, `Location`/`LocationLink` and hover normalization, and `references.includeDeclaration`. +- Synchronization tests pin UTF-16 negotiation and conversion, supported and rejected `textDocumentSync` forms, balanced transient open/close, close-write failure, and malformed-response rejection. +- Timeout tests pin one `TOOL_TIMEOUT` budget, unclassified upstream cancellation, no hidden seam deadline, and bounded awaited teardown. +- Lifecycle tests pin startup single-flight, per-instance serialization, cross-instance parallelism, abortable queues, crash replacement without replay, and quiescent disposal. +- Host-filesystem tests pin session-cwd requirements, relative and absolute source containment through symlinks, document validation, file/non-file URI rendering, unformatted source, and no `fs/observed` event. +- A keyless pinned TypeScript real-server e2e exercises all four operations; runnable configuration uses the same explicit provider mapping. +- Snapshots cover model-visible schema, prompt, results, omissions, and ACP rendering; a built-artifact smoke test covers framing and cleanup. +- Package and architecture docs cover configuration, security boundaries, and search/read guidance; the new `packages/lsp/` group is added to the AGENTS.md repository-layout block, the packages/README.md group table, and architecture.md in the same change. + +## Risks + +Language servers vary in method support, capability interpretation, and indexing readiness; LSP has no universal “index complete” signal. Servers without compatible transient-open synchronization are unsupported even if closed-document queries work. Supported servers may still return empty or partial results, so the tool promises no cross-server completeness. The pinned TypeScript e2e establishes one compatibility floor, not a cross-language claim. + +Transient opens repeat parsing and notifications. Per-instance serialization increases latency under parallel agents, and long-lived workspace processes consume memory until disposal. + +Extension ownership is exclusive within one runtime. Two providers cannot both claim `.ts`, even with different language ids; this is a conscious MVP limit. The intended extension is a deployment-configured selector above registrations that can relax exclusive reservations without adding provider choice to model input or changing `LspProvider.query`. + +UTF-16 cursor columns are exact for the protocol but difficult for a model to count around non-BMP characters. Invalid or off-symbol positions may produce empty results, so error text and prompt examples must explain the coordinate convention without encouraging broad LSP use. + +Direct Node access aligns the query snapshot with the server index but bypasses `ctx.fs` and its policy. Canonical containment rejects source files outside the workspace; a trusted server may still read the workspace and use caches. The first implementation therefore requires trusted host-local deployment and provides no sandbox guarantee. diff --git a/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.zh.md b/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.zh.md new file mode 100644 index 0000000000..c1c2448b1e --- /dev/null +++ b/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.zh.md @@ -0,0 +1,198 @@ +# RFC: LSP 能力服务边界与面向模型的查询工具 + +Status: proposed + +[English](2026-07-15-lsp-capability-seam.md) | 中文 + +## 问题 + +harness 已具备文本搜索与文件读取能力,但二者都无法识别程序符号。文本匹配无法可靠地区分同名函数、跟踪导入别名、关联接口与具体实现,也无法报告推断类型。因此,agent(智能体)在修改代码前缺少人类通过编辑器语言服务器获得的语义导航能力。 + +语言服务器协议(Language Server Protocol,LSP)支持分属三个职责方:模型需要稳定的查询 schema,harness 需要提供方选择与规范化结果,本地实现则负责进程、JSON-RPC、工作区、同步与文件系统行为。将三者合并会使模型契约绑定本地子进程,并阻碍远程或沙箱原生提供方。 + +许多语言服务器只有在查询文档已按当前文本打开时才能稳定工作。兼容的 agent 客户端必须限制这项状态、定义内部读取是否算作模型观察,并确保文档快照与服务器工作区索引位于同一文件系统命名空间。 + +## 提案 + +将 LSP 建成由三个 package 组成的能力服务边界,其中包含一个只读模型工具和一个通用本地提供方实现: + +1. `packages/lsp/lsp` 下的 `@deepseek-ai/dsh-lsp` 负责 `ctx.lsp`、提供方注册与选择、标准化请求与结果、执行控制,以及结构化 LSP 错误。 +2. `packages/lsp/lsp-local` 下的 `@deepseek-ai/dsh-lsp-local` 将配置的 stdio 语言服务器适配到该服务边界。多个插件实例可注册不同的服务器命令和扩展名到语言 id 的映射。 +3. `packages/lsp/tool-lsp` 下的 `@deepseek-ai/dsh-tool-lsp` 负责面向模型的 `lsp` schema、提示词指导、参数校验、结果限制与格式化,以及 ACP(Agent Client Protocol)展示。 + +`dsh-lsp-local` 是通用 host,不是语言服务器目录或安装器。部署显式配置命令与映射;未来 preset 属于组合插件或 `cordis.yml` overlay。 + +模型与服务边界仅公开 `definition`、`references`、`implementation` 和 `hover`;`ctx.lsp` 不提供任意 JSON-RPC 方法。 + +提示词将 LSP 定位为精确查询手段:`Use search/read for ordinary navigation. Use lsp when textual matches are ambiguous or before a change requires precise definitions, implementations, or references.` + +## Package 与职责边界 + +`dsh-lsp` 按带品牌类型的 id 和扩展名到语言 id 的映射注册提供方。`registerProvider()` 以原子方式占用 id 与所有规范化扩展名:输入无效或存在冲突时不发布任何状态,清理函数释放全部占用。提供方插件通过 `ctx.effect()` 注册。系统按查询且不受顺序影响地选择提供方;没有匹配项时返回结构化不可用错误。第一版不提供 glob、language-id 或显式路由选择器,也不静态声明操作能力。 + +服务边界只公开 `query(request, signal?)`,因为没有字段需要实现层填充默认值:`workspaceRoot` 是必填项,`languageId` 来自注册映射,超时与结果限制由消费方负责。`query()` 执行校验、选择与推导时不使用隐藏的 `??` 后备逻辑,因此没有需要 resolve 的可执行 spec。`dsh-tool-lsp` 只把 `exec.signal` 作为裸 `AbortSignal` 传递,与 web 一致,并使 `dsh-lsp` 不依赖 `dsh-tools`。提供方在选择前被移除时按不可用失败;之后的释放遵循已选提供方的取消生命周期,不改路由。 + +预期契约如下: + +```ts +import type { Branded } from '@deepseek-ai/dsh-brand' + +type LspOperation = 'definition' | 'references' | 'implementation' | 'hover' +type LspProviderId = Branded<'LspProviderId'> + +interface LspPosition { + readonly line: number + readonly character: number +} + +interface LspRange { + readonly start: LspPosition + readonly end: LspPosition +} + +interface LspQueryRequest { + readonly operation: LspOperation + readonly filePath: string + readonly position: LspPosition + readonly workspaceRoot: string +} + +interface LspProviderQuery extends LspQueryRequest { + readonly languageId: string +} + +type LspQueryResult = + | { readonly kind: 'locations'; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[] } + | { readonly kind: 'hover'; readonly hover: { readonly contents: string; readonly range?: LspRange } | null } + +interface LspProvider { + readonly id: LspProviderId + readonly extensionToLanguage: Readonly> + query(request: LspProviderQuery, signal?: AbortSignal): Promise +} + +interface LspService { + registerProvider(provider: LspProvider): () => void + query(request: LspQueryRequest, signal?: AbortSignal): Promise +} +``` + +映射键规范化为带前导点的小写扩展名,并按 `filePath` 的最后一个扩展名选择;语言 id 仅用于文档同步。服务边界中的位置和范围从零开始按 UTF-16 计数。`references` 始终包含声明:提供方在内部执行该约束,本地映射设置 `context.includeDeclaration: true`,调用方不能配置。封闭结果联合将导航统一为位置,将 `hover` 统一为内容或 `null`。服务边界不公开协议类型、进程或文档控制,也不提供通用请求逃生口。 + +`dsh-lsp-local` 负责主机文件、服务器配置、JSON-RPC、进程与临时文档状态和协议转换;它依赖 `dsh-lsp` 与 Node API,不依赖 `dsh-fs`。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`,通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区,其取值方式与文件系统工具一致,也不导入提供方。 + +## 面向模型的契约 + +单一 `lsp` 工具接受以下参数: + +```ts +interface LspToolInput { + readonly operation: 'definition' | 'references' | 'implementation' | 'hover' + readonly file_path: string + readonly line: number + readonly character: number +} +``` + +`line` 和 `character` 是从一开始计数的正数 UTF-16 光标坐标;工具将其转换为服务边界中从零开始的 `LspPosition`,并将渲染位置转回。`references` 包含声明,避免影响分析漏掉定义位置。提供方、语言 id、工作区根目录、限制、超时、初始化和可执行文件均不进入模型输入。 + +工具必须从会话 `header.cwd` 取得 `workspaceRoot`,没有后备值;缺失时在查询或启动前以 `LSP_WORKSPACE_REQUIRED` 失败。本地提供方基于根目录解析相对路径并直接接受绝对路径;两种路径都会进行规范化,如果目标位于规范工作区外,则在启动前拒绝。 + +位置按文件稳定分组并渲染为 `path:line:character`。Node `fileURLToPath()` 可接受的 `file:` URI 在工作区内转换为相对路径,在工作区外转换为绝对路径;其他 URI 保持原样。`maxLocations` 默认值为 `100`,`maxHoverChars` 在 `hover` 归一化后应用,默认值为 `16_000`;两者都会报告省略数量。空位置与 `null` hover 是成功的无结果响应;格式错误的载荷保持为结构化错误。 + +ACP 使用 `{ card: 'generic', kind: 'search', title, locations: [{ path: file_path, line }] }`,`title` 由参数推导并标明操作与光标。由于 `FileLocation` 没有 character,跟随位置聚焦输入行,标题保留完整光标;展示保持纯函数。 + +## 超时归属 + +`dsh-tool-lsp` 将一个可配置的 `timeoutMs` 预算附加到工具定义,默认值为 `60_000`。`dsh-timeout-policy` 执行预算并提供传入 `ctx.lsp.query` 的 `exec.signal`;该预算覆盖排队、打开、查询和关闭的完整生命周期,模型不可配置。 + +服务边界和提供方不增加启动或请求截止时间。非工具调用方不会获得隐藏超时,必须自行提供 `AbortSignal`,并在需要预算时使用 `deadline()`。 + +提供方释放发生在工具执行之外,因此 `dsh-lsp-local` 保留 `shutdownTimeoutMs`(默认 `5_000`)限制 `shutdown`/`exit`,以及 `killGraceMs`(默认 `2_000`)限制强制终止前的宽限期;失败实例的清理也使用相同边界。它使用 `deadline()` 和 `timeoutOf()`,但仍负责请求取消、进程信号和等待关闭,因为超时通知不会终止工作。 + +## 工作区、文件系统与文档同步 + +`dsh-lsp-local` 通过 Node API 在子进程所在的主机命名空间中规范化并读取文件。它拒绝缺失、非普通、非 UTF-8、超大或规范路径越出工作区的源文件,并在校验与读取期间保持同一句柄。它不使用 `ctx.fs` 或发送 `fs/observed`:只有 LSP 结果对模型可见,因此查询不满足写前读取策略。 + +`read` 工具的输出带窗口与行号,进入 transcript 且已被观察,不适合作为源文件。在 `tool-lsp` 内读取还会把提供方专用同步职责交给消费方,并排除非本地提供方。 + +本地提供方对每次查询都采用兼容优先的临时打开流程。它接受旧式 `textDocumentSync` 的 `Full` 或 `Incremental`,也接受设置了 `openClose: true` 的选项;同步能力缺失、为 `None` 或明确不兼容时,在 `didOpen` 前以不支持错误失败。 + +1. 规范化并校验主机路径,再使用 Node 文件系统 API 读取当前源文件。 +2. 发送 `textDocument/didOpen`,其中包含版本 `1`、完整文本和配置的语言 id。 +3. 发送所请求的 `textDocument/definition`、`textDocument/references`、`textDocument/implementation` 或 `textDocument/hover` 请求。 +4. 如果 `didOpen` 成功,则在请求完成或取消后于 `finally` 中尝试发送 `textDocument/didClose`。关闭写入失败不会覆盖已经确定的结果或错误,但会使实例失效,并等待有界进程终止完成。 + +每次调用后都关闭文档,因此第一版不需要 `didChange`、`didSave`、内容缓存、变更监听器或文档 LRU。每个实例使用一个可取消队列串行执行完整生命周期;不同实例可以并行。服务器工作区索引仍负责从源文件跳转到的已关闭文件。 + +规范工作区 `realpath` 必须是目录,并用于进程 cwd、`rootUri`、唯一的 `workspaceFolders` 条目和进程池 identity;符号链接别名因此共享实例。结果位置可以在工作区外,但外部路径不能成为查询源。远程、虚拟或独立沙箱化文件系统需要另一种提供方。 + +## 本地服务器生命周期与协议行为 + +`dsh-lsp-local` 按 `(provider id, canonical workspace realpath)` 懒启动一个服务器,并通过 single-flight 合并启动。插件加载时,它在清除凭据并应用环境变量覆盖后解析可执行文件;命令不可用时在注册前失败,解析保持懒执行,启动不经过 shell。`maxMessageBytes` 默认值为 `16_000_000`,`maxStderrBytes` 默认值为 `1_000_000`,`maxDocumentBytes` 默认值为 `4_000_000`。崩溃使当前查询失败且不重放;后续查询可以替换进程。每次查询最多启动一个进程,因此 MVP 不设置跨请求重启计数器。 + +初始化声明 `general.positionEncodings: ['utf-16']`、`workspace: { workspaceFolders: true, configuration: true }`、`textDocument.hover.contentFormat: ['markdown', 'plaintext']`,以及 definition 与 implementation 的 `linkSupport: true`,但不支持动态注册。服务器返回的操作与同步能力均为真源。服务器省略 `positionEncoding` 时默认为 `utf-16`;其他值均属于协议错误。配置可以提供初始化选项和 `workspace/configuration` 响应,但客户端拒绝 `workspace/applyEdit`,绝不执行命令或编辑。 + +导航结果直接映射 `Location`,并将 `LocationLink` 的 `targetUri` 与 `targetSelectionRange` 映射为统一位置。`hover` 归一化直接采用 `MarkupContent.value`,保留字符串 `MarkedString`,把带语言标签的值渲染为围栏代码块,以一个空行连接数组,并在最后应用 `maxHoverChars`。 + +取消信号传递到查询的所有阶段,请求 id 创建后还会发送 `$/cancelRequest`。无响应的服务器会被终止并等待关闭;实例串行化保证没有其他正在执行的工作被连带中断。资源释放会拒绝并取消工作、尝试优雅关闭、通过有界终止流程升级处理,并等待完全停稳。 + +## 明确延后的接口 + +符号操作因需要不同 schema 且与读取或搜索重叠而延后;未来的工作区符号工具必须接收搜索词。调用层级因支持度不一而延后,`prepareCallHierarchy` 仍是内部准备步骤,不是模型操作。 + +诊断需要独立的新鲜度、累积与 transcript 规则。重命名、代码操作和格式化等变更能力需要单独工具,并集成预览、权限和写入策略。 + +本地提供方信任配置的服务器,不声称具备沙箱隔离。支持不受信任的二进制文件需要后续补充允许读取工作区并写入私有缓存与临时目录的进程/文件系统契约;受限、远程或虚拟工作区需要另一种提供方。 + +## 备选方案 + +**照搬 Claude Code 的统一 schema。** 它的光标操作验证了核心场景,但符号与调用层级需要不同参数。照搬九种操作会固化尚未验证的接口,因此本提案只对齐四种语义查询。 + +**允许提供方注册工具。** 已加载服务器会控制模型 schema 和提示词,无法在本地与远程提供方之间维持统一契约。 + +**公开任意 LSP 方法。** JSON-RPC 逃生口会泄露协议载荷,并允许未经评审的变更或命令执行;操作联合保持封闭。 + +**公开 `resolve(request)` / `query(spec)`。** 没有需要填充默认值的字段时,resolve 只会暴露提供方选择,而公开 spec 可能活过提供方释放或替换。单一操作让选择与调用共用注册生命周期。 + +**将信号包装为每服务边界的执行上下文对象。** Web 传递裸 `AbortSignal`;仅包装这一个字段会造成无谓的不对称。只有另一个字段确有需要时,`query()` 才引入上下文对象。 + +**通过 `ctx.fs` 或 `read` 工具读取。** 这可能把文档与另一文件系统命名空间中的服务器索引混合;工具输出还带窗口、行号且已被观察。host-local 提供方在子进程旁读取未观察的完整文本。 + +**保持文档打开。** 镜像编辑需要版本归属、覆盖所有路径的 `didChange`、HMR 恢复、淘汰和陈旧状态规则。临时打开避免在 MVP 引入这套状态机。 + +**配置分阶段超时。** 嵌套定时器会产生相互竞争的分类与新预算。一个由调用方负责的截止时间覆盖查询;只有调用外清理保留本地限制。 + +**不发送 `didOpen`。** 协议虽允许,但支持不一致且可能使用陈旧服务器状态。临时打开提供明确的当前快照。 + +**增加路由或选择首个匹配项。** 注册顺序与 HMR 时机不是产品语义,路由表又会重复唯一扩展名所有权。因此,扩展名重叠时注册失败。 + +**在一个实例中并发查询。** 取消失败时,终止共享进程会杀死无关工作。实例内串行可限制影响范围;不同实例仍可并行。 + +**内置 preset 或 PATH 发现。** 目录会让通用 host 承担语言策略,而发现机制无法推断参数、语言 id 或初始化配置。部署显式配置提供方,组合插件可以封装 preset。 + +## 验收标准 + +- Package 测试固定三个 package 的依赖方向、运行时注入和仅通过 `ctx.lsp` 通信的边界。 +- 工具测试固定四种操作、坐标校验、配置限制与省略标记、提示词和 ACP 展示。 +- 注册表测试固定原子占用/释放、不受顺序影响的选择,以及结构化的不可用、已释放、冲突和不支持操作错误。 +- 测试用 stdio server 固定精确的初始化能力、四种协议映射、`Location`/`LocationLink` 与 `hover` 归一化,以及 `references.includeDeclaration`。 +- 同步测试固定 UTF-16 协商与转换、受支持和被拒绝的 `textDocumentSync` 形式、配对的临时打开/关闭、关闭写入失败和错误响应拒绝。 +- 超时测试固定一个 `TOOL_TIMEOUT` 预算、不对上游取消错误分类、服务边界无隐藏截止时间,以及受限且等待完成的清理。 +- 生命周期测试固定启动 single-flight、实例内串行、跨实例并行、可取消队列、崩溃后不重放的替换,以及释放后完全停稳。 +- 主机文件系统测试固定 session cwd 要求、符号链接下相对与绝对源路径的规范 containment、文档校验、file/non-file URI 渲染、无格式源文本和不发送 `fs/observed`。 +- 无密钥且固定版本的 TypeScript 真实服务器 e2e 覆盖四种操作;可运行配置使用同一项显式提供方映射。 +- 快照覆盖模型可见 schema、提示词、结果、省略提示和 ACP 渲染;构建产物冒烟测试覆盖分帧与清理。 +- Package 与架构文档覆盖配置、安全边界和搜索/读取指导;同一改动中,新的 `packages/lsp/` package 组要加入 AGENTS.md 的仓库布局块、packages/README.md 的分组表和 architecture.md。 + +## 风险 + +各语言服务器对方法支持、能力解释和索引就绪时机的处理不同;LSP 没有统一的“索引完成”信号。无法声明兼容临时打开同步能力的服务器不受支持,即使它能查询已关闭文档。受支持的服务器仍可能返回空结果或不完整结果,因此工具不承诺跨服务器完整性。固定的 TypeScript e2e 只建立一条兼容性基线,不代表跨语言承诺。 + +临时打开会重复解析并产生通知。实例内串行会增加并发 agent 的延迟,长期运行的工作区进程则持续占用内存直到释放。 + +同一运行时内的扩展名所有权互斥。即使 language id 不同,两个提供方也不能同时占用 `.ts`;这是有意接受的 MVP 限制。预期扩展方式是在注册之上增加由部署配置的 selector,允许放宽互斥占用,同时不向模型输入增加提供方选择,也不改变 `LspProvider.query`。 + +UTF-16 光标列与协议完全一致,但模型难以在包含非 BMP 字符的文本中准确计数。无效位置或不在符号上的位置可能返回空结果,因此错误文本和提示词示例必须说明坐标约定,同时避免鼓励模型广泛使用 LSP。 + +直接访问 Node 文件系统会对齐查询快照与服务器索引,但绕过 `ctx.fs` 及其策略。规范路径 containment 会拒绝工作区外的源文件;受信任的服务器仍可读取工作区并使用缓存。因此,第一版要求受信任的 host-local 部署,不提供沙箱保证。 From d0029d8d609d297ede039cc579fed8cc89d1705c Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Thu, 16 Jul 2026 12:05:35 +0800 Subject: [PATCH 010/273] feat(lsp): LSP capability seam, generic stdio provider, and lsp tool MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implements the LSP capability seam RFC as three packages: dsh-lsp (the ctx.lsp interface — provider registry by branded id + exclusive extension mapping, per-query order-independent selection, closed request/result vocabulary, LspError taxonomy), dsh-lsp-local (a generic stdio language-server provider — Content-Length JSON-RPC framing, per-(provider, workspace) process single-flight, transient didOpen/query/didClose, an abortable per-instance queue, UTF-16 negotiation, host-namespace source reads outside ctx.fs, and bounded shutdown/kill teardown), and dsh-tool-lsp (the model-facing lsp tool — four operations, one-based UTF-16 cursor conversion, workspace-grouped location rendering, hover capping, a required session workspace, and a timeout budget). Why: an agent had text search and file reads but no way to identify a program symbol — follow an alias, connect an interface to implementations, or read an inferred type — before changing code. Splitting model contract, seam, and local subprocess behavior keeps the four semantic queries stable across future remote or sandbox-native providers without leaking a JSON-RPC escape hatch. --- AGENTS.md | 15 +- docs/architecture.md | 1 + docs/config-catalog.md | 55 ++++ docs/module-graph.md | 18 ++ docs/rfc/INDEX.md | 2 +- .../2026-07-15-lsp-capability-seam.i18n.yaml | 4 +- .../2026-07-15-lsp-capability-seam.md | 8 +- .../2026-07-15-lsp-capability-seam.zh.md | 8 +- docs/tool-catalog.md | 47 +++ knip.json | 5 + packages/README.md | 16 +- .../core/tools/tests/gen-tool-catalog.spec.ts | 2 +- packages/lsp/README.md | 13 + packages/lsp/lsp-local/README.md | 49 +++ packages/lsp/lsp-local/package.json | 43 +++ packages/lsp/lsp-local/src/connection.ts | 240 ++++++++++++++ packages/lsp/lsp-local/src/framing.ts | 99 ++++++ packages/lsp/lsp-local/src/host.ts | 104 +++++++ packages/lsp/lsp-local/src/index.ts | 255 +++++++++++++++ packages/lsp/lsp-local/src/instance.ts | 293 ++++++++++++++++++ packages/lsp/lsp-local/src/protocol.ts | 80 +++++ packages/lsp/lsp-local/src/translate.ts | 210 +++++++++++++ packages/lsp/lsp-local/tests/built-lib.e2e.ts | 73 +++++ .../lsp/lsp-local/tests/connection.spec.ts | 226 ++++++++++++++ .../lsp/lsp-local/tests/fixture-server.ts | 144 +++++++++ packages/lsp/lsp-local/tests/framing.spec.ts | 76 +++++ packages/lsp/lsp-local/tests/host.spec.ts | 105 +++++++ packages/lsp/lsp-local/tests/instance.spec.ts | 184 +++++++++++ .../lsp/lsp-local/tests/lifecycle.spec.ts | 200 ++++++++++++ packages/lsp/lsp-local/tests/provider.spec.ts | 78 +++++ .../lsp/lsp-local/tests/translate.spec.ts | 153 +++++++++ .../lsp-local/tests/typescript-server.e2e.ts | 111 +++++++ packages/lsp/lsp-local/tsconfig.json | 33 ++ packages/lsp/lsp/README.md | 38 +++ packages/lsp/lsp/package.json | 34 ++ packages/lsp/lsp/src/brand.ts | 21 ++ packages/lsp/lsp/src/index.ts | 156 ++++++++++ packages/lsp/lsp/src/types.ts | 124 ++++++++ packages/lsp/lsp/tests/lsp.spec.ts | 187 +++++++++++ packages/lsp/lsp/tsconfig.json | 24 ++ packages/lsp/tool-lsp/README.md | 56 ++++ packages/lsp/tool-lsp/package.json | 45 +++ packages/lsp/tool-lsp/src/index.ts | 130 ++++++++ packages/lsp/tool-lsp/src/render.ts | 158 ++++++++++ packages/lsp/tool-lsp/src/session-cwd.ts | 19 ++ .../lsp/tool-lsp/tests/integration.spec.ts | 93 ++++++ packages/lsp/tool-lsp/tests/load-path.spec.ts | 24 ++ packages/lsp/tool-lsp/tests/render.spec.ts | 125 ++++++++ packages/lsp/tool-lsp/tests/tool-lsp.spec.ts | 164 ++++++++++ packages/lsp/tool-lsp/tsconfig.json | 33 ++ pnpm-lock.yaml | 147 ++++++++- scripts/gen-tool-catalog.ts | 16 + .../verify-package-readme-model-experience.ts | 2 + tsconfig.base.json | 1 + tsconfig.build.json | 5 +- tsconfig.json | 5 +- 56 files changed, 4527 insertions(+), 30 deletions(-) rename docs/rfc/{proposed => implemented}/architecture/2026-07-15-lsp-capability-seam.i18n.yaml (65%) rename docs/rfc/{proposed => implemented}/architecture/2026-07-15-lsp-capability-seam.md (99%) rename docs/rfc/{proposed => implemented}/architecture/2026-07-15-lsp-capability-seam.zh.md (99%) create mode 100644 packages/lsp/README.md create mode 100644 packages/lsp/lsp-local/README.md create mode 100644 packages/lsp/lsp-local/package.json create mode 100644 packages/lsp/lsp-local/src/connection.ts create mode 100644 packages/lsp/lsp-local/src/framing.ts create mode 100644 packages/lsp/lsp-local/src/host.ts create mode 100644 packages/lsp/lsp-local/src/index.ts create mode 100644 packages/lsp/lsp-local/src/instance.ts create mode 100644 packages/lsp/lsp-local/src/protocol.ts create mode 100644 packages/lsp/lsp-local/src/translate.ts create mode 100644 packages/lsp/lsp-local/tests/built-lib.e2e.ts create mode 100644 packages/lsp/lsp-local/tests/connection.spec.ts create mode 100644 packages/lsp/lsp-local/tests/fixture-server.ts create mode 100644 packages/lsp/lsp-local/tests/framing.spec.ts create mode 100644 packages/lsp/lsp-local/tests/host.spec.ts create mode 100644 packages/lsp/lsp-local/tests/instance.spec.ts create mode 100644 packages/lsp/lsp-local/tests/lifecycle.spec.ts create mode 100644 packages/lsp/lsp-local/tests/provider.spec.ts create mode 100644 packages/lsp/lsp-local/tests/translate.spec.ts create mode 100644 packages/lsp/lsp-local/tests/typescript-server.e2e.ts create mode 100644 packages/lsp/lsp-local/tsconfig.json create mode 100644 packages/lsp/lsp/README.md create mode 100644 packages/lsp/lsp/package.json create mode 100644 packages/lsp/lsp/src/brand.ts create mode 100644 packages/lsp/lsp/src/index.ts create mode 100644 packages/lsp/lsp/src/types.ts create mode 100644 packages/lsp/lsp/tests/lsp.spec.ts create mode 100644 packages/lsp/lsp/tsconfig.json create mode 100644 packages/lsp/tool-lsp/README.md create mode 100644 packages/lsp/tool-lsp/package.json create mode 100644 packages/lsp/tool-lsp/src/index.ts create mode 100644 packages/lsp/tool-lsp/src/render.ts create mode 100644 packages/lsp/tool-lsp/src/session-cwd.ts create mode 100644 packages/lsp/tool-lsp/tests/integration.spec.ts create mode 100644 packages/lsp/tool-lsp/tests/load-path.spec.ts create mode 100644 packages/lsp/tool-lsp/tests/render.spec.ts create mode 100644 packages/lsp/tool-lsp/tests/tool-lsp.spec.ts create mode 100644 packages/lsp/tool-lsp/tsconfig.json diff --git a/AGENTS.md b/AGENTS.md index 22c1f47aa8..edc5f6a74a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,6 +15,7 @@ packages/ Harness packages at packages///, all named @deepseek-ai llm/ LLM seam + the DeepSeek adapters (hand-rolled + pi-ai design twin) bash/ bash executor seam + local impl + model-facing bash tools fs/ filesystem seam + local impl + policy gate + read/write/edit tools + lsp/ LSP seam + stdio provider + lsp tool skill/ skill provider registry + local impl + catalog/loader tool web/ web seam + search/fetch providers + model-facing web tools compact/ compaction seam + basic backend @@ -90,13 +91,13 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, ## Conventions - Every npm package is `@deepseek-ai/dsh-`; vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package. -- ESM everywhere (`"type": "module"`). Cross-package imports use package names, never relative paths; in-package relative imports use explicit `.ts` extensions. Dev/test/demo run unbuilt via tsx + the root tsconfig `paths` map; builds are for outside consumers only. +- ESM everywhere (`"type": "module"`). Cross-package imports use package names, never relative paths; in-package relative imports use explicit `.ts` extensions. Dev/test/demo run unbuilt via tsx + the root tsconfig `paths` map; builds are for outside consumers. - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer. - **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns. - **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default. - **Waterfall listeners MUST call `next()`** to delegate; returning without it is the veto ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)). -- **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event. -- **Plugins, not loop changes**: new behavior goes on the documented extension seams; changing `agent-loop` requires updating docs/architecture.md. +- **Model-visible ⟺ logged**: anything reaching a model request must be reconstructable from the session log; a new model-visible input requires a session event. +- **Plugins, not loop changes**: new behavior goes on documented extension seams; changing `agent-loop` requires updating docs/architecture.md. - **Capability seams are three packages** — interface / implementation / consumer; don't split preemptively. - **Explicit > implicit at package seams**: defaulting is an explicit `resolve(request): Spec` step in the owning implementation, never a hidden `?? default` inside `run()` (the `dsh-bash` request/spec split is the template). - **No hardcoded tunables in plugins**: deployment choices are defaulted, validated `Config` fields changeable from cordis.yml; a `DEFAULT_*` constant or test seam is not configurability. Protocol constants, external specs, and security invariants stay fixed. @@ -119,15 +120,15 @@ Read [docs/defensive-patterns.md](docs/defensive-patterns.md) before lifecycle, ## Type safety and documentation -Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` explains why a narrower type is infeasible. Every module and export has concise JSDoc for its non-obvious contract; function-like exports include `@param`/`@returns`, as enforced by `verify-export-jsdoc`. Heritage-declared members, plugin-protocol slots, and constructors keep their docs at the declaring seam, protocol, or class. +Everything compiles under `strict: true` with `noImplicitAny`; every remaining `any` explains why a narrower type is infeasible. Every module and export has concise JSDoc for its non-obvious contract; function-like exports include `@param`/`@returns`, enforced by `verify-export-jsdoc`. Heritage-declared members, plugin-protocol slots, and constructors keep docs at the declaring seam, protocol, or class. -Comments and docs preserve complete contracts and non-obvious orientation, not reasoning transcripts. Do not narrate control flow or tests, preserve review history, or restate code. Keep factual clauses affecting behavior, failure, timing, ownership, or safe use; link aggressively to owning rationale. Use [dsh-prose-standard](.agents/skills/dsh-prose-standard/SKILL.md) for prose decisions. Encode enforceable invariants in checks, using narrow justified exceptions rather than disabling a rule globally. +Comments and docs preserve complete contracts and non-obvious orientation, not reasoning transcripts. Do not narrate control flow or tests, preserve review history, or restate code. Keep factual clauses affecting behavior, failure, timing, ownership, or safe use; link aggressively to owning rationale. Use [dsh-prose-standard](.agents/skills/dsh-prose-standard/SKILL.md) for prose decisions. Encode enforceable invariants in checks, with narrow justified exceptions rather than disabling a rule. -Docs are part of every change: code changes update their README and JSDoc in the SAME change; a bilingual-pair edit updates the counterpart and re-records ([i18n contract](docs/i18n/README.md)). The writing rules — document the current state never the history, one physical line per paragraph, one home per fact — and the word-budget gate live in [docs/AGENTS.md](docs/AGENTS.md). +Docs are part of every change: code changes update their README and JSDoc in the SAME change; a bilingual-pair edit updates the counterpart and re-records ([i18n contract](docs/i18n/README.md)). The writing rules — document current state not history, one physical line per paragraph, one home per fact — and the word-budget gate live in [docs/AGENTS.md](docs/AGENTS.md). ## Editing these instructions -`CLAUDE.md` symlinks `AGENTS.md` at root, `packages/`, and `examples/`; edit the real file. Keep each rule self-contained while linking high-level docs. Condense when clarity survives; raise a `verify-doc-budgets` ceiling when the contract genuinely needs more space. +`CLAUDE.md` symlinks `AGENTS.md` at root, `packages/`, and `examples/`; edit the real file. Keep each rule self-contained while linking high-level docs. Condense when clarity survives; raise a `verify-doc-budgets` ceiling only when the contract needs more space. ## Vendoring policy diff --git a/docs/architecture.md b/docs/architecture.md index b17c3302d8..db3cc19f22 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -28,6 +28,7 @@ A harness is one [Cordis](cordis-primer.md) context. Packages contribute service | `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | same-world process confinement (argv wrapping, per-call policy) | | `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | model-written program execution | | `ctx.fs` | [`fs/`](../packages/fs/README.md) | filesystem provider primitives and policy events | +| `ctx.lsp` | [`lsp/`](../packages/lsp/README.md) | language-server provider registry and semantic navigation | | `ctx.skills` | [`skill/`](../packages/skill/README.md) | skill provider registry and progressive disclosure | | `ctx.web` | [`web/`](../packages/web/README.md) | search/fetch provider registries | | `ctx.compact` | [`compact/`](../packages/compact/README.md) | session-log compaction | diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 57e3576d05..a38130a739 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -419,6 +419,42 @@ export interface Config { Source: [`packages/support/llm-replay/src/index.ts:306`](../packages/support/llm-replay/src/index.ts) +## `@deepseek-ai/dsh-lsp-local` + +Requires: `lsp` + +```ts config-catalog +/** Plugin configuration: one server command plus its extension mapping and host bounds. */ +export interface Config { + /** Stable provider id, reserved on `ctx.lsp` with the extensions. */ + providerId: string + /** Executable to spawn (absolute, or resolved on PATH at load). */ + command: string + /** Arguments passed to the executable (no shell). */ + args: string[] + /** Extra env vars merged on top of the scrubbed ambient env. */ + env: Record + /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */ + extensionToLanguage: Record + /** Static `initialize` options forwarded to the server. */ + initializationOptions: unknown + /** Static answer to every `workspace/configuration` item. */ + configuration: unknown + /** Largest single framed message accepted from the server (bytes). */ + maxMessageBytes: number + /** Largest stderr tail retained for diagnostics (bytes). */ + maxStderrBytes: number + /** Largest source file this host will open (bytes). */ + maxDocumentBytes: number + /** Graceful `shutdown`/`exit` budget before escalation (ms). */ + shutdownTimeoutMs: number + /** SIGTERM→SIGKILL grace after graceful shutdown fails (ms). */ + killGraceMs: number +} +``` + +Source: [`packages/lsp/lsp-local/src/index.ts:59`](../packages/lsp/lsp-local/src/index.ts) + ## `@deepseek-ai/dsh-mcp-client` Requires: `tools` @@ -901,6 +937,24 @@ export interface Config { Source: [`packages/fs/tool-fs/src/index.ts:22`](../packages/fs/tool-fs/src/index.ts) +## `@deepseek-ai/dsh-tool-lsp` + +Requires: `tools` · `lsp` · `systemPrompt` + +```ts config-catalog +/** Plugin configuration: result caps and the timeout budget. */ +export interface Config { + /** Largest number of rendered locations before an omission marker (default 100). */ + maxLocations?: number + /** Largest hover length in characters after normalization (default 16000). */ + maxHoverChars?: number + /** Tool-call timeout budget in ms (default 60000). */ + timeoutMs?: number +} +``` + +Source: [`packages/lsp/tool-lsp/src/index.ts:56`](../packages/lsp/tool-lsp/src/index.ts) + ## `@deepseek-ai/dsh-tool-skill` Requires: `tools` · `skills` @@ -1214,6 +1268,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co - `@deepseek-ai/dsh-fs-policy` ([`packages/fs/fs-policy/src/index.ts`](../packages/fs/fs-policy/src/index.ts)) - `@deepseek-ai/dsh-invariants` — requires `sessions` ([`packages/support/invariants/src/index.ts`](../packages/support/invariants/src/index.ts)) - `@deepseek-ai/dsh-llm` ([`packages/llm/llm/src/index.ts`](../packages/llm/llm/src/index.ts)) +- `@deepseek-ai/dsh-lsp` ([`packages/lsp/lsp/src/index.ts`](../packages/lsp/lsp/src/index.ts)) - `@deepseek-ai/dsh-session` ([`packages/core/session/src/index.ts`](../packages/core/session/src/index.ts)) - `@deepseek-ai/dsh-subagent` ([`packages/subagent/subagent/src/index.ts`](../packages/subagent/subagent/src/index.ts)) - `@deepseek-ai/dsh-timeout-policy` — requires `tools` ([`packages/timeout/timeout-policy/src/index.ts`](../packages/timeout/timeout-policy/src/index.ts)) diff --git a/docs/module-graph.md b/docs/module-graph.md index 1b804e5214..f1bc52eabc 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -115,6 +115,11 @@ flowchart TD subgraph group_guard["packages/guard"] pkg_repeat_tool_guard["repeat-tool-guard"] end + subgraph group_lsp["packages/lsp"] + pkg_lsp["lsp"] + pkg_lsp_local["lsp-local"] + pkg_tool_lsp["tool-lsp"] + end subgraph group_mcp["packages/mcp"] pkg_mcp_client["mcp-client"] end @@ -139,6 +144,8 @@ flowchart TD pkg_fs --> pkg_brand pkg_fs --> pkg_llm pkg_web --> pkg_llm + pkg_lsp --> pkg_brand + pkg_lsp --> pkg_llm pkg_sandbox --> pkg_llm pkg_agent --> pkg_brand pkg_agent --> pkg_llm @@ -162,6 +169,10 @@ flowchart TD pkg_session_persistence --> pkg_session pkg_llm_replay --> pkg_llm pkg_llm_replay --> pkg_session + pkg_lsp_local --> pkg_brand + pkg_lsp_local --> pkg_llm + pkg_lsp_local --> pkg_lsp + pkg_lsp_local --> pkg_timeout pkg_sandbox_local --> pkg_llm pkg_sandbox_local --> pkg_sandbox pkg_bash_local --> pkg_bash @@ -273,6 +284,10 @@ flowchart TD pkg_tool_ask_user --> pkg_user_interaction pkg_repeat_tool_guard --> pkg_agent pkg_repeat_tool_guard --> pkg_tools + pkg_tool_lsp --> pkg_llm + pkg_tool_lsp --> pkg_lsp + pkg_tool_lsp --> pkg_system_prompt + pkg_tool_lsp --> pkg_tools pkg_mcp_client --> pkg_llm pkg_mcp_client --> pkg_tools pkg_tool_workflow --> pkg_agent @@ -370,6 +385,7 @@ flowchart TD | [`system-prompt`](../packages/core/system-prompt) | `core` | [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) | | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) | | [`web`](../packages/web/web) | `web` | [`llm`](../packages/llm/llm) | +| [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) | | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`llm`](../packages/llm/llm) | | [`agent`](../packages/core/agent) | `core` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) | | [`bash`](../packages/bash/bash) | `bash` | [`brand`](../packages/util/brand), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) | @@ -383,6 +399,7 @@ flowchart TD | [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`web`](../packages/web/web) | | [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`session`](../packages/core/session) | | [`llm-replay`](../packages/support/llm-replay) | `support` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | +| [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`timeout`](../packages/util/timeout) | | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) | | [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`timeout`](../packages/util/timeout) | | [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | @@ -412,6 +429,7 @@ flowchart TD | [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`permission`](../packages/ui/permission), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`user-interaction`](../packages/ui/user-interaction) | | [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) | | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) | +| [`tool-lsp`](../packages/lsp/tool-lsp) | `lsp` | [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`llm`](../packages/llm/llm), [`tools`](../packages/core/tools) | | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | | [`agent-core`](../packages/core/agent-core) | `core` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/bash/tool-bash), [`tool-skill`](../packages/skill/tool-skill), [`tools`](../packages/core/tools) | diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index a0dd29d0b5..4587338244 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -28,7 +28,6 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; |---|---| | [Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern)](proposed/architecture/2026-06-16-typed-event-schemas.md) | 2026-06-16 | | [Extract a generic long-running tool runtime](proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md) | 2026-06-20 | -| [LSP capability seam and model-facing query tool](proposed/architecture/2026-07-15-lsp-capability-seam.md) | 2026-07-15 | ### Process @@ -146,6 +145,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [The agent is a registration scope](implemented/architecture/2026-07-08-agent-scope-contexts.md) | 2026-07-08 | | [Single-file executable SDK runtime distribution (single-exe)](implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) | 2026-07-10 | | [Agent-scope runtime design and correctness](implemented/architecture/2026-07-12-agent-scope-runtime-design.md) | 2026-07-12 | +| [LSP capability seam and model-facing query tool](implemented/architecture/2026-07-15-lsp-capability-seam.md) | 2026-07-15 | ### Process diff --git a/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml similarity index 65% rename from docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.i18n.yaml rename to docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml index 75d69a5dcb..f8b32dcca1 100644 --- a/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.i18n.yaml +++ b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.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 -2026-07-15-lsp-capability-seam.md: 89e58c3ae0ba9f49ed0164a76a230b141296eee5 -2026-07-15-lsp-capability-seam.zh.md: c1c2448b1e980fc17a347f6c434e8553639304f3 +2026-07-15-lsp-capability-seam.md: 90cc7fce8ce86582cc27bd70fadcc46309438983 +2026-07-15-lsp-capability-seam.zh.md: 12873d33684255b7177a78dd4588e11aa61eb26b diff --git a/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.md b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md similarity index 99% rename from docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.md rename to docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md index 89e58c3ae0..90cc7fce8c 100644 --- a/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.md +++ b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md @@ -1,6 +1,6 @@ # RFC: LSP capability seam and model-facing query tool -Status: proposed +Status: implemented English | [中文](2026-07-15-lsp-capability-seam.zh.md) @@ -12,7 +12,7 @@ LSP support has three owners: the model needs a stable query schema, the harness Many language servers behave best when the queried document is opened with current text. A compatible agent client must bound that state, define whether its source read is a model observation, and keep the document snapshot in the same filesystem namespace as the server's workspace index. -## Proposal +## Decision Add LSP as a three-package capability seam with one read-only model tool and one generic local provider implementation: @@ -171,7 +171,7 @@ The local provider trusts its configured server and claims no sandbox confinemen **Ship presets or PATH discovery.** A catalog would make the generic host own language policy, while discovery cannot infer arguments, language ids, or initialization. Deployments configure providers explicitly; composition plugins may package presets. -## Acceptance criteria +## Testing - Package tests pin the three-package dependency direction, runtime injections, and `ctx.lsp`-only communication. - Tool tests pin the four operations, coordinate validation, configured bounds and omission markers, prompt, and ACP presentation. @@ -185,7 +185,7 @@ The local provider trusts its configured server and claims no sandbox confinemen - Snapshots cover model-visible schema, prompt, results, omissions, and ACP rendering; a built-artifact smoke test covers framing and cleanup. - Package and architecture docs cover configuration, security boundaries, and search/read guidance; the new `packages/lsp/` group is added to the AGENTS.md repository-layout block, the packages/README.md group table, and architecture.md in the same change. -## Risks +## Consequences Language servers vary in method support, capability interpretation, and indexing readiness; LSP has no universal “index complete” signal. Servers without compatible transient-open synchronization are unsupported even if closed-document queries work. Supported servers may still return empty or partial results, so the tool promises no cross-server completeness. The pinned TypeScript e2e establishes one compatibility floor, not a cross-language claim. diff --git a/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.zh.md b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md similarity index 99% rename from docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.zh.md rename to docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md index c1c2448b1e..12873d3368 100644 --- a/docs/rfc/proposed/architecture/2026-07-15-lsp-capability-seam.zh.md +++ b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md @@ -1,6 +1,6 @@ # RFC: LSP 能力服务边界与面向模型的查询工具 -Status: proposed +Status: implemented [English](2026-07-15-lsp-capability-seam.md) | 中文 @@ -12,7 +12,7 @@ harness 已具备文本搜索与文件读取能力,但二者都无法识别程 许多语言服务器只有在查询文档已按当前文本打开时才能稳定工作。兼容的 agent 客户端必须限制这项状态、定义内部读取是否算作模型观察,并确保文档快照与服务器工作区索引位于同一文件系统命名空间。 -## 提案 +## 决策 将 LSP 建成由三个 package 组成的能力服务边界,其中包含一个只读模型工具和一个通用本地提供方实现: @@ -171,7 +171,7 @@ ACP 使用 `{ card: 'generic', kind: 'search', title, locations: [{ path: file_p **内置 preset 或 PATH 发现。** 目录会让通用 host 承担语言策略,而发现机制无法推断参数、语言 id 或初始化配置。部署显式配置提供方,组合插件可以封装 preset。 -## 验收标准 +## 测试 - Package 测试固定三个 package 的依赖方向、运行时注入和仅通过 `ctx.lsp` 通信的边界。 - 工具测试固定四种操作、坐标校验、配置限制与省略标记、提示词和 ACP 展示。 @@ -185,7 +185,7 @@ ACP 使用 `{ card: 'generic', kind: 'search', title, locations: [{ path: file_p - 快照覆盖模型可见 schema、提示词、结果、省略提示和 ACP 渲染;构建产物冒烟测试覆盖分帧与清理。 - Package 与架构文档覆盖配置、安全边界和搜索/读取指导;同一改动中,新的 `packages/lsp/` package 组要加入 AGENTS.md 的仓库布局块、packages/README.md 的分组表和 architecture.md。 -## 风险 +## 影响 各语言服务器对方法支持、能力解释和索引就绪时机的处理不同;LSP 没有统一的“索引完成”信号。无法声明兼容临时打开同步能力的服务器不受支持,即使它能查询已关闭文档。受支持的服务器仍可能返回空结果或不完整结果,因此工具不承诺跨服务器完整性。固定的 TypeScript e2e 只建立一条兼容性基线,不代表跨语言承诺。 diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 9ea71d3005..91be6752d6 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -20,6 +20,7 @@ This table connects model-visible tool names to the plugin package and service s | `@deepseek-ai/dsh-tool-bash` | `bash`, `bash_kill`, `bash_output` | `ctx.tools`, `ctx.bash` | `tool/call`, `tool/result`, `context/message via agent.inject() for background completion notices` | - | The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam. | | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `live plugin-tree mutations (mount/unmount)` | - | Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; the request-header ToolsDelta logs those tool-set changes. | | `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. | +| `@deepseek-ai/dsh-tool-lsp` | `lsp` | `ctx.tools`, `ctx.lsp`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | The lsp tool keeps provider selection and language-server subprocesses behind ctx.lsp, so its model-visible schema stays stable across providers. Requires a registered provider (e.g. `@deepseek-ai/dsh-lsp-local`) at runtime; without one, a query returns the structured `LSP_UNAVAILABLE` error rather than changing the schema. | | `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`, `ctx.skills` | `tool/call`, `tool/result` | - | - | | `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. | | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist or ACP plan. | @@ -371,6 +372,52 @@ Source: [`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. +## `@deepseek-ai/dsh-tool-lsp` + +### `lsp` + +Query a language server for precise code navigation. operation is one of definition, references, implementation, hover. line and character are one-based UTF-16 cursor coordinates. references includes the declaration. + +```json +{ + "type": "object", + "properties": { + "operation": { + "type": "string", + "description": "definition, references, implementation, or hover.", + "enum": [ + "definition", + "references", + "implementation", + "hover" + ] + }, + "file_path": { + "type": "string", + "description": "The source file to query, relative to the workspace or absolute." + }, + "line": { + "type": "number", + "description": "One-based line of the cursor." + }, + "character": { + "type": "number", + "description": "One-based UTF-16 column of the cursor." + } + }, + "required": [ + "operation", + "file_path", + "line", + "character" + ] +} +``` + +Source: [`packages/lsp/tool-lsp/src/index.ts`](../packages/lsp/tool-lsp/src/index.ts) + +The lsp tool keeps provider selection and language-server subprocesses behind ctx.lsp, so its model-visible schema stays stable across providers. Requires a registered provider (e.g. `@deepseek-ai/dsh-lsp-local`) at runtime; without one, a query returns the structured `LSP_UNAVAILABLE` error rather than changing the schema. + ## `@deepseek-ai/dsh-tool-skill` ### `skill` diff --git a/knip.json b/knip.json index ad33bec613..76634b0b78 100644 --- a/knip.json +++ b/knip.json @@ -118,6 +118,11 @@ "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/fixture-server.ts"], "project": ["src/**/*.ts", "tests/**/*.ts"], "ignoreDependencies": ["@modelcontextprotocol/server-everything", "@modelcontextprotocol/server-filesystem"] + }, + "packages/lsp/lsp-local": { + "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/fixture-server.ts"], + "project": ["src/**/*.ts", "tests/**/*.ts"], + "ignoreDependencies": ["typescript-language-server"] } } } diff --git a/packages/README.md b/packages/README.md index 5cb4cfe419..fafa269514 100644 --- a/packages/README.md +++ b/packages/README.md @@ -1,10 +1,10 @@ # Packages -Packages use the `@deepseek-ai/dsh-*` scope. Each is a Cordis `Service` subclass or function plugin; contributions use `ctx.effect()`, `ctx.on()`, or `ctx.waterfall()`. Authoring rules: [package](AGENTS.md) and [root](../AGENTS.md#conventions). +Packages use the `@deepseek-ai/dsh-*` scope. Each is a Cordis `Service` subclass or function plugin; contributions use `ctx.effect()`, `ctx.on()`, or `ctx.waterfall()`. Authoring rules: [package](AGENTS.md), [root](../AGENTS.md#conventions). ## Hierarchy -Packages are grouped by modular role at `packages///`. The group directory is a pure container (no `package.json`); the package name stays `@deepseek-ai/dsh-` regardless of group. **Each group README is the canonical per-package map** — package roles, ctx keys, and the product-vs-support split live there, next to the code. +Packages are grouped by modular role at `packages///`. The group directory is a pure container (no `package.json`); the package name stays `@deepseek-ai/dsh-` regardless of group. **Each group README is the canonical per-package map** — roles, ctx keys, and the product-vs-support split live there, next to the code. | Group | Role | Release expectation | |---|---|---| @@ -14,6 +14,7 @@ Packages are grouped by modular role at `packages///`. The group dir | [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the abstract runtime seam for model-written programs + a worker-thread backend | Product — stable surface | | [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable surface | | [`fs/`](fs/README.md) | Filesystem capability family: the abstract seam, a local impl, and the model-facing file tools | Product — stable surface | +| [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable surface | | [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable surface | | [`compact/`](compact/README.md) | Compaction capability family: the abstract seam + a basic backend (tool deferred) | Product — stable surface | | [`context/`](context/README.md) | Opt-in request-context enrichment | Product — stable surface | @@ -23,20 +24,19 @@ Packages are grouped by modular role at `packages///`. The group dir | [`timeout/`](timeout/README.md) | Tool-call timeout policy: the `tools/execute` deadline enforcer | Product — stable surface | | [`todo/`](todo/README.md) | Todo/planning family: the model-facing `todo_write` tool | Product — stable surface | | [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders | Product — stable surface | -| [`cordis/`](cordis/README.md) | Self-referential runtime toolset: inspect the live runtime's plugins and services, mount/unmount model-written plugins ([design](../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) | Product — stable surface | +| [`cordis/`](cordis/README.md) | Self-referential runtime toolset: inspect live plugins/services, mount/unmount model-written plugins ([design](../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) | Product — stable surface | | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface | | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface | | [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, surface records, and bounded exact reads | Product — stable surface | -| [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, app packages, user-approval and user-interaction seams, ask-user tool | Product — stable surface | +| [`ui/`](ui/README.md) | Editor/client integration: ACP bridge, JSON-RPC SDK server, app packages, user-approval/interaction seams, ask-user tool | Product — stable surface | | [`support/`](support/README.md) | Support infrastructure (invariants, replay, Loader smokes) | Support — lower compatibility expectations | | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (the `Branded` primitive) | Support — small, stable, harness-dep-free | -The split is the point: a package's group says whether it is part of the product API or support/test/example infrastructure, so release and removal decisions do not treat every package as an equal public contract. New packages join an existing group; adding a new top-level group is a deliberate act (extend the group READMEs and this table). +The split is the point: a package's group says whether it is product API or support/test/example infrastructure, so release and removal decisions do not treat every package as an equal public contract. New packages join an existing group; adding a top-level group is a deliberate act (extend the group READMEs and this table). ## Dependencies The inter-package dependency graph is generated: [docs/module-graph.md](../docs/module-graph.md) (`pnpm run gen-module-graph`, freshness-gated in CI). +The rule it must obey: **extension plugins depend on interfaces, never on the concrete loop.** `dsh-agent-loop` is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced. The sanctioned exception is a **composition/bundle** package like `dsh-agent-core`, whose job is to assemble the concrete spine: it depends on `dsh-agent-loop` (and the other spine plugins). The rule constrains plugins that EXTEND the system, not the bundle that COMPOSES it. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — see [capability seams](../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)). -The rule it must obey: **extension plugins depend on interfaces, never on the concrete loop.** `dsh-agent-loop` is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced. The sanctioned exception is a **composition/bundle** package like `dsh-agent-core`, whose whole job is to assemble the concrete spine: it depends on `dsh-agent-loop` (and the other concrete spine plugins) on purpose. The rule constrains plugins that EXTEND the system, not the bundle that COMPOSES it. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — see [capability seams](../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)). - -Package READMEs cover purpose, APIs, extension points, and [Model Experience](../docs/cookbook/adding-a-package.md#4-write-the-package-readme) unless on the model-agnostic [omission allowlist](../scripts/verify-package-readme-model-experience.ts). They also carry `## Known Limitations and Deferred Work` or use its [allowlist](../scripts/verify-package-readme-limitations.ts). +Package READMEs cover purpose, APIs, extension points, and [Model Experience](../docs/cookbook/adding-a-package.md#4-write-the-package-readme) unless on the model-agnostic [omission allowlist](../scripts/verify-package-readme-model-experience.ts). They also carry `## Known Limitations and Deferred Work` or its [allowlist](../scripts/verify-package-readme-limitations.ts). diff --git a/packages/core/tools/tests/gen-tool-catalog.spec.ts b/packages/core/tools/tests/gen-tool-catalog.spec.ts index ad739173c9..448a14d5d0 100644 --- a/packages/core/tools/tests/gen-tool-catalog.spec.ts +++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts @@ -23,7 +23,7 @@ describe('gen-tool-catalog collectToolCatalog', () => { it('boots every shipped tool package and harvests its model-facing schemas', async () => { const catalog = await collectToolCatalog() const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort() - expect(names).toEqual(['ask_user_question', 'bash', 'bash_kill', 'bash_output', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'edit', 'read', 'run_code', 'skill', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'workflow', 'write']) + expect(names).toEqual(['ask_user_question', 'bash', 'bash_kill', 'bash_output', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'edit', 'lsp', 'read', 'run_code', 'skill', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'workflow', 'write']) // Every tool carries a JSON-Schema `parameters` object (what the model sees). for (const entry of catalog) { for (const schema of entry.schemas) { diff --git a/packages/lsp/README.md b/packages/lsp/README.md new file mode 100644 index 0000000000..57a1f6b8d9 --- /dev/null +++ b/packages/lsp/README.md @@ -0,0 +1,13 @@ +# lsp/ - LSP capability family + +The language-server capability seam: an abstract LSP interface, a generic stdio provider, and the model-facing `lsp` tool. All **product** packages. + +| Package | Role | ctx key | +|---|---|---| +| `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` | +| `lsp-local/` | Generic stdio language-server provider (spawn, JSON-RPC, transient-open queries) | (registers on `ctx.lsp`) | +| `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) | + +The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `definition`, `references`, `implementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation. + +See the [LSP capability seam RFC](../../docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md) for the design rationale, including why documents open transiently per query, why the local host reads through Node APIs rather than `ctx.fs`, and why extension ownership is exclusive within one runtime. diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md new file mode 100644 index 0000000000..f9e4b32713 --- /dev/null +++ b/packages/lsp/lsp-local/README.md @@ -0,0 +1,49 @@ +# @deepseek-ai/dsh-lsp-local + +A **generic stdio language-server provider** for `ctx.lsp`. One plugin instance configures one server command and its extension-to-language-id map; load multiple instances for multiple servers. This is a generic host, not a language-server catalog or installer — deployments configure commands and mappings explicitly; presets belong in composition plugins or `cordis.yml` overlays. + +Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export). + +## What it does + +- Lazily single-flights one server process per `(provider id, canonical workspace realpath)`. A crash fails the active query without replay; a later query may replace the process. +- Uses a compatibility-first **transient-open** sequence per query: canonicalize and read the source with Node APIs, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU. +- Serializes queries through one abortable per-instance queue so a cancellation that fails to stop the server can terminate it without killing unrelated work; distinct instances run in parallel. +- Reads sources through Node filesystem APIs in the subprocess's host namespace — NOT `ctx.fs`, and emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy. + +## Configuration + +| Key | Default | Meaning | +|---|---|---| +| `providerId` | (required) | Stable provider id reserved on `ctx.lsp` with the extensions. | +| `command` | (required) | Executable to spawn — absolute, or resolved on the child PATH at load. Launch uses no shell. | +| `args` | `[]` | Arguments passed to the executable. | +| `env` | `{}` | Extra env merged on top of the credential-scrubbed ambient env (vars matching `KEY`/`SECRET`/`TOKEN` are not forwarded). | +| `extensionToLanguage` | (required) | Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). | +| `initializationOptions` | `null` | Static `initialize` options forwarded to the server. | +| `configuration` | `null` | Static answer to every `workspace/configuration` item. | +| `maxMessageBytes` | `16000000` | Largest single framed message accepted from the server. | +| `maxStderrBytes` | `1000000` | Largest stderr tail retained for diagnostics. | +| `maxDocumentBytes` | `4000000` | Largest source file this host will open. | +| `shutdownTimeoutMs` | `5000` | Graceful `shutdown`/`exit` budget before escalation. | +| `killGraceMs` | `2000` | SIGTERM→SIGKILL grace after graceful shutdown fails. | + +The executable is resolved at load (after credential scrubbing); a missing command fails before registration. The process itself launches lazily on the first matching query. + +## Protocol behavior + +Initialization advertises `general.positionEncodings: ['utf-16']`, `workspace: { workspaceFolders: true, configuration: true }`, `textDocument.hover.contentFormat: ['markdown', 'plaintext']`, and `linkSupport: true` for definition and implementation, with no dynamic registration. The server's returned capabilities are authoritative: an unsupported operation, or synchronization without transient open/close, fails the query. An omitted server `positionEncoding` defaults to `utf-16`; any other value is a protocol error. The client answers `workspace/configuration` from static config, accepts lifecycle bookkeeping requests, and rejects `workspace/applyEdit` — it never applies edits or runs commands. Navigation maps `Location` directly and `LocationLink` from `targetUri` + `targetSelectionRange`; hover normalization takes `MarkupContent.value`, preserves string `MarkedString`s, renders language-tagged values as fenced code, and joins arrays with one blank line. + +## Security boundary + +The provider trusts its configured server and claims no sandbox confinement. It canonicalizes and reads source through Node APIs, rejecting a source that is missing, non-regular, non-UTF-8, oversized, or whose canonical path resolves outside the canonical workspace (symlink aliases share one instance). Result locations may be external, but an external path cannot become a query source. The first implementation therefore requires trusted host-local deployment; restricted, remote, or virtual workspaces require another provider. + +## Model Experience + +Indirectly, through `dsh-tool-lsp`, which surfaces this provider's normalized results; this host contributes no prompt or schema itself. + +## Known Limitations and Deferred Work + +- **Trusted host-local only** — no sandbox confinement, no private cache/temp write contract; supporting untrusted binaries or restricted/remote/virtual workspaces requires a later process/filesystem contract and a different provider ([seam RFC](../../../docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md)). +- **Transient-open compatibility floor** — servers whose synchronization omits open/close (or advertise `None`) are unsupported even if closed-document queries would work; the pinned TypeScript e2e establishes one compatibility floor, not a cross-language claim. +- **Per-instance serialization latency** — parallel agents sharing a workspace queue behind one process; long-lived workspace processes consume memory until disposal. diff --git a/packages/lsp/lsp-local/package.json b/packages/lsp/lsp-local/package.json new file mode 100644 index 0000000000..d437e91109 --- /dev/null +++ b/packages/lsp/lsp-local/package.json @@ -0,0 +1,43 @@ +{ + "name": "@deepseek-ai/dsh-lsp-local", + "description": "Generic stdio language-server provider for the DeepSeek Harness LSP capability seam (ctx.lsp) — spawns configured servers, translates JSON-RPC, and serves transient-open definition/references/implementation/hover queries in the host filesystem namespace", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-brand": "^0.0.1", + "@deepseek-ai/dsh-llm": "^0.0.1", + "@deepseek-ai/dsh-lsp": "^0.0.1", + "@deepseek-ai/dsh-timeout": "^0.0.1", + "cordis": "^4.0.0-rc.7" + }, + "dependencies": { + "schemastery": "^3.18.0" + }, + "devDependencies": { + "@deepseek-ai/dsh-brand": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-lsp": "workspace:^", + "@deepseek-ai/dsh-timeout": "workspace:^", + "cordis": "^4.0.0-rc.7", + "typescript": "^6.0.3", + "typescript-language-server": "^5.0.0" + } +} diff --git a/packages/lsp/lsp-local/src/connection.ts b/packages/lsp/lsp-local/src/connection.ts new file mode 100644 index 0000000000..1eeb430d22 --- /dev/null +++ b/packages/lsp/lsp-local/src/connection.ts @@ -0,0 +1,240 @@ +/** + * A JSON-RPC endpoint over one spawned language server's stdio. Owns id correlation, outbound + * requests/notifications, and inbound server→client requests: it answers `workspace/configuration` + * from static config, and rejects `workspace/applyEdit` (this host never applies edits or runs + * commands). It caps stderr, surfaces framing/decoder failures as a fatal close, and exposes the + * child handle so the instance owns process-signal teardown. + * @module @deepseek-ai/dsh-lsp-local/connection + */ + +import type { ChildProcessByStdio } from 'node:child_process' +import { spawn } from 'node:child_process' +import type { Readable, Writable } from 'node:stream' +import { encodeMessage, MessageDecoder } from './framing.ts' + +/** How to launch the server and answer its config requests. */ +export interface ConnectionSpec { + /** The resolved absolute executable path (no shell). */ + readonly command: string + /** Arguments passed to the executable. */ + readonly args: readonly string[] + /** The child's working directory (the canonical workspace). */ + readonly cwd: string + /** The child's environment (credential-scrubbed, with overrides applied). */ + readonly env: Record + /** Largest single framed message accepted from the server. */ + readonly maxMessageBytes: number + /** Largest stderr tail retained for diagnostics. */ + readonly maxStderrBytes: number + /** Static answer to every `workspace/configuration` item. */ + readonly configuration: unknown +} + +interface Pending { + resolve: (value: unknown) => void + reject: (error: Error) => void +} + +/** A live JSON-RPC endpoint bound to one child process. */ +export class LspConnection { + private readonly child: ChildProcessByStdio + private readonly decoder: MessageDecoder + private readonly pending = new Map() + private nextId = 1 + private stderr = '' + private closeReason: Error | undefined + /** Set once the process has fully exited; the instance awaits it during teardown. */ + readonly closed: Promise + + /** + * @param spec - how to launch the server and answer its config requests. + * @param onServerRequest - answers a server→client request; rejects to send an error response. + */ + constructor( + private readonly spec: ConnectionSpec, + private readonly onServerRequest: (method: string, params: unknown) => Promise, + ) { + this.decoder = new MessageDecoder(spec.maxMessageBytes) + this.child = spawn(spec.command, [...spec.args], { + cwd: spec.cwd, + env: spec.env, + stdio: ['pipe', 'pipe', 'pipe'], + }) + this.closed = new Promise((resolve) => { + this.child.on('close', () => { + const reason = this.closeReason ?? new Error('language server exited') + // Record the reason so any request issued AFTER close rejects immediately instead of hanging + // (a closed process sends no further responses). + this.closeReason = reason + this.failAll(reason) + resolve() + }) + }) + this.child.on('error', (error) => { this.fail(error) }) + // A write to the child's stdin after it exits emits an async 'error'; swallow it so an EPIPE + // during teardown does not crash the process. Pending requests fail via the 'close' handler. + /* v8 ignore next -- the handler only fires on an async stdin write error during teardown. */ + this.child.stdin.on('error', () => { /* swallow */ }) + this.child.stdout.on('data', (chunk: Buffer) => { this.onStdout(chunk) }) + this.child.stderr.on('data', (chunk: Buffer) => { this.onStderr(chunk) }) + } + + /** The child's pid, or `-1` when the spawn produced no pid (so signalling is a no-op). */ + get pid(): number { + /* v8 ignore next -- the `-1` fallback only applies to a spawn that produced no pid; defensive. */ + return this.child.pid ?? -1 + } + + /** The retained stderr tail, for diagnostics on a failed server. */ + get stderrTail(): string { + return this.stderr + } + + /** + * Send a request and await its result. + * @param method - the JSON-RPC method. + * @param params - the request params. + * @returns the response result; rejects on an error response, write failure, or close. + */ + request(method: string, params: unknown): Promise { + const id = this.nextId++ + const promise = new Promise((resolve, reject) => { + if (this.closeReason !== undefined) { + reject(this.closeReason) + return + } + this.pending.set(id, { resolve, reject }) + try { + this.write({ jsonrpc: '2.0', id, method, params }) + } catch (error) { + /* v8 ignore start -- a stdin write failure surfaces asynchronously via the swallowed + 'error' listener, so this synchronous catch is a defensive guard. */ + this.pending.delete(id) + reject(asError(error)) + /* v8 ignore stop */ + } + }) + // A caller that stops awaiting (e.g. an aborted query) can leave this promise to reject later + // when the process closes; a benign no-op handler keeps that from surfacing as an unhandled + // rejection. The returned promise still delivers the rejection to the caller's own await/catch. + promise.catch(() => {}) + return promise + } + + /** + * Send a notification (no id, no response). + * @param method - the JSON-RPC method. + * @param params - the notification params. + */ + notify(method: string, params: unknown): void { + this.write({ jsonrpc: '2.0', method, params }) + } + + /** + * Send a `$/cancelRequest` for an in-flight request id (best-effort; ignores write failure). + * @param requestId - the numeric id of the request to cancel. + */ + cancel(requestId: number): void { + try { + this.write({ jsonrpc: '2.0', method: '$/cancelRequest', params: { id: requestId } }) + } catch { + // The server is already gone or unwritable; the pending request will fail on close. + } + } + + /** + * The id the NEXT `request()` will use, so the instance can pre-arm a cancel. + * @returns the numeric id the next request will be assigned. + */ + peekNextId(): number { + return this.nextId + } + + /** Send SIGTERM to the child (idempotent-safe; a dead child ignores it). */ + terminate(): void { + this.child.kill('SIGTERM') + } + + /** Send SIGKILL to the child. */ + kill(): void { + this.child.kill('SIGKILL') + } + + private onStdout(chunk: Buffer): void { + let messages: unknown[] + try { + messages = this.decoder.push(chunk) + } catch (error) { + // A framing/JSON failure corrupts the stream position irrecoverably: fail the instance. + this.fail(asError(error)) + this.child.kill('SIGKILL') + return + } + for (const message of messages) this.dispatch(message) + } + + private onStderr(chunk: Buffer): void { + if (this.stderr.length >= this.spec.maxStderrBytes) return + this.stderr = (this.stderr + chunk.toString('utf8')).slice(0, this.spec.maxStderrBytes) + } + + private dispatch(message: unknown): void { + if (message === null || typeof message !== 'object') return + const frame = message as Record + const id = frame.id + const method = frame.method + if (typeof method === 'string' && (typeof id === 'number' || typeof id === 'string')) { + void this.handleServerRequest(id, method, frame.params) + return + } + if (typeof method === 'string') { + // A server→client notification (e.g. diagnostics, logs): ignored by this MVP host. + return + } + if (typeof id === 'number') this.handleResponse(id, frame) + } + + private async handleServerRequest(id: number | string, method: string, params: unknown): Promise { + try { + const result = await this.onServerRequest(method, params) + this.write({ jsonrpc: '2.0', id, result }) + } catch (error) { + this.write({ jsonrpc: '2.0', id, error: { code: -32601, message: asError(error).message } }) + } + } + + private handleResponse(id: number, frame: Record): void { + const pending = this.pending.get(id) + if (!pending) return + this.pending.delete(id) + const error = frame.error + if (error !== null && typeof error === 'object') { + const record = error as Record + pending.reject(new Error(typeof record.message === 'string' ? record.message : 'LSP error response')) + return + } + pending.resolve(frame.result) + } + + private write(message: unknown): void { + this.child.stdin.write(encodeMessage(message)) + } + + private fail(error: Error): void { + /* v8 ignore next -- the second arm (closeReason already set) needs two fail() calls before close; defensive. */ + if (this.closeReason === undefined) this.closeReason = error + this.failAll(error) + } + + private failAll(error: Error): void { + const waiting = [...this.pending.values()] + this.pending.clear() + for (const pending of waiting) pending.reject(error) + } +} + +/** Coerce an unknown thrown value to an `Error`. */ +function asError(value: unknown): Error { + /* v8 ignore next -- the non-Error branch guards against a non-Error throw, which our paths never produce. */ + return value instanceof Error ? value : new Error(String(value)) +} diff --git a/packages/lsp/lsp-local/src/framing.ts b/packages/lsp/lsp-local/src/framing.ts new file mode 100644 index 0000000000..8720247272 --- /dev/null +++ b/packages/lsp/lsp-local/src/framing.ts @@ -0,0 +1,99 @@ +/** + * LSP base-protocol framing: `Content-Length`-delimited JSON-RPC over a byte stream. The encoder + * produces one framed buffer; the decoder buffers incoming bytes and yields complete message bodies, + * bounding the header and total message size so a hostile or broken server cannot exhaust memory. + * @module @deepseek-ai/dsh-lsp-local/framing + */ + +/** The header/body separator in the LSP base protocol. */ +const HEADER_SEPARATOR = '\r\n\r\n' + +/** Cap on the header section so a server that never sends the separator cannot grow the buffer forever. */ +const MAX_HEADER_BYTES = 1 << 16 + +/** + * Encode one JSON-RPC message as a framed LSP buffer (`Content-Length: N\r\n\r\n`). + * @param message - the JSON-RPC message object to serialize. + * @returns the framed bytes ready to write to the server's stdin. + */ +export function encodeMessage(message: unknown): Buffer { + const body = Buffer.from(JSON.stringify(message), 'utf8') + const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'ascii') + return Buffer.concat([header, body]) +} + +/** + * A streaming decoder for `Content-Length`-framed JSON-RPC. Feed it stdout chunks; it returns any + * whole message bodies that completed. It parses only the `Content-Length` header and ignores other + * headers (e.g. `Content-Type`), matching the base protocol. + */ +export class MessageDecoder { + private buffer: Buffer = Buffer.alloc(0) + private readonly maxMessageBytes: number + + /** + * @param maxMessageBytes - reject any single framed body larger than this (guards memory). + */ + constructor(maxMessageBytes: number) { + this.maxMessageBytes = maxMessageBytes + } + + /** + * Append a chunk and return every message body that is now complete. + * @param chunk - raw bytes from the server's stdout. + * @returns the parsed JSON bodies, in arrival order (possibly empty). + * @throws Error when a header is malformed or a body exceeds `maxMessageBytes`. + */ + push(chunk: Buffer): unknown[] { + this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]) + const messages: unknown[] = [] + for (;;) { + const step = this.next() + if (!step.ready) break + messages.push(step.message) + } + return messages + } + + /** Parse and consume the next complete message, or report that more bytes are needed. */ + private next(): { ready: false } | { ready: true; message: unknown } { + const separator = this.buffer.indexOf(HEADER_SEPARATOR) + if (separator < 0) { + if (this.buffer.length > MAX_HEADER_BYTES) { + throw new Error(`LSP header exceeded ${MAX_HEADER_BYTES} bytes without a terminator`) + } + return { ready: false } + } + const headerText = this.buffer.toString('ascii', 0, separator) + const contentLength = parseContentLength(headerText) + if (contentLength > this.maxMessageBytes) { + throw new Error(`LSP message length ${contentLength} exceeds the ${this.maxMessageBytes}-byte limit`) + } + const bodyStart = separator + HEADER_SEPARATOR.length + const bodyEnd = bodyStart + contentLength + if (this.buffer.length < bodyEnd) return { ready: false } + const body = this.buffer.toString('utf8', bodyStart, bodyEnd) + this.buffer = this.buffer.subarray(bodyEnd) + try { + return { ready: true, message: JSON.parse(body) } + } catch (error) { + /* v8 ignore next -- JSON.parse throws a SyntaxError (an Error); the String() fallback is defensive. */ + throw new Error(`LSP message body was not valid JSON: ${error instanceof Error ? error.message : String(error)}`) + } + } +} + +/** Read the `Content-Length` header value (case-insensitive), rejecting a missing or non-numeric one. */ +function parseContentLength(headerText: string): number { + for (const line of headerText.split('\r\n')) { + const colon = line.indexOf(':') + if (colon < 0) continue + if (line.slice(0, colon).trim().toLowerCase() !== 'content-length') continue + const value = Number(line.slice(colon + 1).trim()) + if (!Number.isInteger(value) || value < 0) { + throw new Error(`invalid Content-Length header: ${JSON.stringify(line)}`) + } + return value + } + throw new Error(`LSP header block missing Content-Length: ${JSON.stringify(headerText)}`) +} diff --git a/packages/lsp/lsp-local/src/host.ts b/packages/lsp/lsp-local/src/host.ts new file mode 100644 index 0000000000..a90a703d96 --- /dev/null +++ b/packages/lsp/lsp-local/src/host.ts @@ -0,0 +1,104 @@ +/** + * Host-filesystem source access for the local provider, using Node APIs directly in the + * subprocess's namespace (never `ctx.fs`): only the LSP result is model-visible, so a query does not + * satisfy read-before-write policy and emits no `fs/observed`. Canonicalization derives target + * identity from `realpath`, so symlink aliases share a workspace; a source is rejected before server + * startup when it is missing, non-regular, non-UTF-8, oversized, or canonically outside the + * workspace. External result locations are allowed, but an external path can never become a query + * source. + * @module @deepseek-ai/dsh-lsp-local/host + */ + +import { readFile, realpath, stat } from 'node:fs/promises' +import { isAbsolute, resolve as resolvePath, sep } from 'node:path' + +/** A validated source: its canonical absolute path and current UTF-8 text. */ +export interface HostSource { + /** The canonical (realpath-resolved) absolute path, inside the canonical workspace. */ + readonly canonicalPath: string + /** The file's current text, read as UTF-8. */ + readonly text: string +} + +/** + * Canonicalize a workspace root: it must exist and be a directory. The returned realpath supplies + * process cwd, `rootUri`, the sole `workspaceFolders` entry, and pool identity, so symlinked roots + * collapse to one instance. + * @param workspaceRoot - the caller's workspace root (absolute). + * @returns the canonical directory path. + * @throws Error when the path is missing or not a directory. + */ +export async function canonicalizeWorkspace(workspaceRoot: string): Promise { + let canonical: string + try { + canonical = await realpath(workspaceRoot) + } catch (error) { + throw new Error(`workspace root "${workspaceRoot}" cannot be resolved: ${messageOf(error)}`) + } + const info = await stat(canonical) + if (!info.isDirectory()) { + throw new Error(`workspace root "${workspaceRoot}" is not a directory`) + } + return canonical +} + +/** + * Resolve, canonicalize, validate, and read a query source in one pass. A relative `filePath` + * resolves against `canonicalWorkspace`; an absolute one is taken directly. The canonical target + * must be a regular UTF-8 file no larger than `maxDocumentBytes`, and must lie inside the canonical + * workspace. + * @param filePath - the model-supplied source path (relative or absolute). + * @param canonicalWorkspace - the already-canonicalized workspace root. + * @param maxDocumentBytes - the largest source this host will open. + * @returns the canonical path and current UTF-8 text. + * @throws Error when the source is missing, non-regular, oversized, non-UTF-8, or out of workspace. + */ +export async function readHostSource( + filePath: string, + canonicalWorkspace: string, + maxDocumentBytes: number, +): Promise { + const requested = isAbsolute(filePath) ? filePath : resolvePath(canonicalWorkspace, filePath) + let canonicalPath: string + try { + canonicalPath = await realpath(requested) + } catch (error) { + throw new Error(`source "${filePath}" cannot be resolved: ${messageOf(error)}`) + } + if (!isInside(canonicalWorkspace, canonicalPath)) { + throw new Error(`source "${filePath}" resolves outside the workspace`) + } + const info = await stat(canonicalPath) + if (!info.isFile()) { + throw new Error(`source "${filePath}" is not a regular file`) + } + if (info.size > maxDocumentBytes) { + throw new Error(`source "${filePath}" is ${info.size} bytes, over the ${maxDocumentBytes}-byte limit`) + } + const buffer = await readFile(canonicalPath) + const text = decodeUtf8Strict(buffer, filePath) + return { canonicalPath, text } +} + +/** Whether `child` is the workspace itself or a descendant of it (both already canonical). */ +function isInside(workspace: string, child: string): boolean { + if (child === workspace) return true + /* v8 ignore next -- a canonical non-root workspace never ends with a separator; the guard covers the filesystem root. */ + const base = workspace.endsWith(sep) ? workspace : workspace + sep + return child.startsWith(base) +} + +/** Decode UTF-8 strictly (a replacement char means the source was not valid UTF-8 text). */ +function decodeUtf8Strict(buffer: Buffer, filePath: string): string { + const text = buffer.toString('utf8') + if (text.includes('�')) { + throw new Error(`source "${filePath}" is not valid UTF-8 text`) + } + return text +} + +/** Extract a message from an unknown thrown value without leaking `any`. */ +function messageOf(error: unknown): string { + /* v8 ignore next -- Node fs rejections are always Error instances; the String() fallback is defensive. */ + return error instanceof Error ? error.message : String(error) +} diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts new file mode 100644 index 0000000000..b9c32867da --- /dev/null +++ b/packages/lsp/lsp-local/src/index.ts @@ -0,0 +1,255 @@ +/** + * Generic stdio language-server provider for `ctx.lsp`. One plugin instance configures one server + * command and its extension→language-id map; load multiple instances for multiple servers. The + * provider lazily single-flights one server process per `(provider id, canonical workspace + * realpath)`, serves transient-open queries through it, and evicts a crashed process so a later + * query can replace it. It reads sources through Node APIs in the host namespace (not `ctx.fs`) and + * trusts its configured server — no sandbox confinement. + * + * Namespace plugin (named exports, no default export). Lifecycle is effect-scoped: disposal + * unregisters from `ctx.lsp` and tears down every live server. + * @module @deepseek-ai/dsh-lsp-local + */ + +import { accessSync, constants } from 'node:fs' +import { delimiter, isAbsolute, join } from 'node:path' +import type { Context } from 'cordis' +import z from 'schemastery' +import { LspProviderId } from '@deepseek-ai/dsh-lsp' +import type { + LspProvider, + LspProviderQuery, + LspQueryResult, +} from '@deepseek-ai/dsh-lsp' +// Side-effect type import: declaration-merges `ctx.lsp` onto Context. +import type {} from '@deepseek-ai/dsh-lsp' +import { canonicalizeWorkspace } from './host.ts' +import { LspInstance } from './instance.ts' +import type { InstanceSpec } from './instance.ts' + +export { canonicalizeWorkspace, readHostSource } from './host.ts' +export { encodeMessage, MessageDecoder } from './framing.ts' +export { + negotiatePositionEncoding, + normalizeHover, + normalizeLocations, + requestMethod, + supportsOperation, + supportsTransientOpen, +} from './translate.ts' +export { LspInstance } from './instance.ts' +export { LspConnection } from './connection.ts' + +/** Cordis plugin name for loader diagnostics. */ +export const name = 'lsp-local' + +/** Services required by this plugin. */ +export const inject = ['lsp'] + +/** Credential-shaped ambient env vars are NOT forwarded to the child by default. */ +const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i + +const DEFAULT_MAX_MESSAGE_BYTES = 16_000_000 +const DEFAULT_MAX_STDERR_BYTES = 1_000_000 +const DEFAULT_MAX_DOCUMENT_BYTES = 4_000_000 +const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000 +const DEFAULT_KILL_GRACE_MS = 2_000 + +/** Plugin configuration: one server command plus its extension mapping and host bounds. */ +export interface Config { + /** Stable provider id, reserved on `ctx.lsp` with the extensions. */ + providerId: string + /** Executable to spawn (absolute, or resolved on PATH at load). */ + command: string + /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */ + extensionToLanguage: Record + /** Arguments passed to the executable (no shell). Default `[]`. */ + args?: string[] + /** Extra env vars merged on top of the scrubbed ambient env. Default `{}`. */ + env?: Record + /** Static `initialize` options forwarded to the server. Default `null`. */ + initializationOptions?: unknown + /** Static answer to every `workspace/configuration` item. Default `null`. */ + configuration?: unknown + /** Largest single framed message accepted from the server (bytes). Default 16000000. */ + maxMessageBytes?: number + /** Largest stderr tail retained for diagnostics (bytes). Default 1000000. */ + maxStderrBytes?: number + /** Largest source file this host will open (bytes). Default 4000000. */ + maxDocumentBytes?: number + /** Graceful `shutdown`/`exit` budget before escalation (ms). Default 5000. */ + shutdownTimeoutMs?: number + /** SIGTERM→SIGKILL grace after graceful shutdown fails (ms). Default 2000. */ + killGraceMs?: number +} + +/** The resolved config after schemastery fills every default; the provider reads this shape. */ +type ResolvedConfig = Required + +export const Config: z = z.object({ + providerId: z.string().required(), + command: z.string().required(), + args: z.array(String).default([]), + env: z.dict(String).default({}), + extensionToLanguage: z.dict(String).required(), + initializationOptions: z.any().default(null), + configuration: z.any().default(null), + maxMessageBytes: z.number().default(DEFAULT_MAX_MESSAGE_BYTES), + maxStderrBytes: z.number().default(DEFAULT_MAX_STDERR_BYTES), + maxDocumentBytes: z.number().default(DEFAULT_MAX_DOCUMENT_BYTES), + shutdownTimeoutMs: z.number().default(DEFAULT_SHUTDOWN_TIMEOUT_MS), + killGraceMs: z.number().default(DEFAULT_KILL_GRACE_MS), +}) + +/** + * Register a generic stdio LSP provider. Resolves the executable at load (after credential + * scrubbing) and fails before registration when it is unavailable; the process itself launches + * lazily on the first matching query. + * @param ctx - the plugin context (must inject `lsp`). + * @param config - the resolved plugin configuration (schemastery has filled every default). + */ +export function apply(ctx: Context, config: Config): void { + const resolved = config as ResolvedConfig + const childEnv = buildChildEnv(resolved.env) + // Resolve the executable eagerly so a misconfigured command fails at load, not on first query. + const executable = resolveExecutable(resolved.command, childEnv) + + const provider = new LocalLspProvider(resolved, childEnv, executable) + ctx.effect(() => { + const dispose = ctx.lsp.registerProvider(provider) + return async () => { + dispose() + await provider.disposeAll() + } + }, 'lsp-local.registerProvider') +} + +/** A pooled generic provider: one server process per canonical workspace, created on demand. */ +class LocalLspProvider implements LspProvider { + readonly id: LspProviderId + readonly extensionToLanguage: Readonly> + /** Single-flight map: canonical workspace realpath → the (pending) instance for it. */ + private readonly instances = new Map>() + private disposed = false + + constructor( + private readonly config: ResolvedConfig, + private readonly childEnv: Record, + private readonly executable: string, + ) { + this.id = LspProviderId(config.providerId) + this.extensionToLanguage = config.extensionToLanguage + } + + async query(request: LspProviderQuery, signal?: AbortSignal): Promise { + /* v8 ignore next -- the seam unregisters this provider on dispose, so a query never reaches a disposed provider; defensive. */ + if (this.disposed) throw new Error('lsp-local provider is disposed') + const workspace = await canonicalizeWorkspace(request.workspaceRoot) + const instance = await this.instanceFor(workspace) + try { + return await instance.query(request, signal) + } finally { + // A crashed/closed process must not be reused: drop its slot so the next query starts fresh, + // but only if the slot still holds THIS instance (a concurrent replacement must survive). + if (instance.dead) { + const slot = this.instances.get(workspace) + /* v8 ignore next -- the slot-undefined arm needs a concurrent eviction of the same slot; defensive. */ + if (slot !== undefined && (await settledInstance(slot)) === instance) { + this.instances.delete(workspace) + } + } + } + } + + /** Single-flight one instance per canonical workspace; a rejected creation clears the slot. */ + private instanceFor(workspace: string): Promise { + const existing = this.instances.get(workspace) + if (existing !== undefined) return existing + const created = Promise.resolve().then(() => this.createInstance(workspace)) + this.instances.set(workspace, created) + /* v8 ignore next 3 -- createInstance (the LspInstance constructor) does not throw; spawn failures + surface asynchronously through the instance, so this creation-rejection cleanup is defensive. */ + created.catch(() => { + if (this.instances.get(workspace) === created) this.instances.delete(workspace) + }) + return created + } + + private createInstance(workspace: string): LspInstance { + const spec: InstanceSpec = { + command: this.executable, + args: this.config.args, + cwd: workspace, + env: this.childEnv, + configuration: this.config.configuration, + initializationOptions: this.config.initializationOptions, + maxMessageBytes: this.config.maxMessageBytes, + maxStderrBytes: this.config.maxStderrBytes, + maxDocumentBytes: this.config.maxDocumentBytes, + shutdownTimeoutMs: this.config.shutdownTimeoutMs, + killGraceMs: this.config.killGraceMs, + } + return new LspInstance(spec) + } + + /** Dispose every live instance and block further queries. */ + async disposeAll(): Promise { + this.disposed = true + const pending = [...this.instances.values()] + this.instances.clear() + await Promise.all(pending.map(async (entry) => { + try { + const instance = await entry + await instance.dispose() + } catch { + // A never-initialized instance already rejected; nothing to tear down. + } + })) + } +} + +/** Resolve a slot promise to its instance for identity comparison, tolerating a pending rejection. */ +async function settledInstance(slot: Promise): Promise { + try { + return await slot + } catch { + /* v8 ignore next -- a slot promise only rejects if createInstance throws, which it never does; defensive. */ + return undefined + } +} + +/** The ambient env minus credential-shaped vars, plus the config's explicit env. */ +function buildChildEnv(extra: Record): Record { + const scrubbed = Object.entries(process.env).filter( + ([key, value]) => value !== undefined && !SENSITIVE_ENV_PATTERN.test(key), + ) as [string, string][] + return { ...Object.fromEntries(scrubbed), ...extra } +} + +/** + * Resolve the server executable to an absolute path: an absolute command is verified directly; a + * bare command is looked up on the child's PATH. Fails loudly when nothing is executable. + */ +function resolveExecutable(command: string, childEnv: Record): string { + if (isAbsolute(command)) { + return command + } + /* v8 ignore next -- buildChildEnv always sets PATH from the ambient env; the further fallbacks are defensive. */ + const pathValue = childEnv.PATH ?? process.env.PATH ?? '' + for (const dir of pathValue.split(delimiter)) { + if (dir === '') continue + const candidate = join(dir, command) + if (isExecutableSync(candidate)) return candidate + } + throw new Error(`lsp-local: command "${command}" was not found on PATH`) +} + +/** Synchronous executable check used only at load-time resolution. */ +function isExecutableSync(path: string): boolean { + try { + accessSync(path, constants.X_OK) + return true + } catch { + return false + } +} diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts new file mode 100644 index 0000000000..0e63e46d1e --- /dev/null +++ b/packages/lsp/lsp-local/src/instance.ts @@ -0,0 +1,293 @@ +/** + * One language-server instance: a connection plus the initialize handshake, the serialized abortable + * query queue, the transient `didOpen`→request→`didClose` lifecycle, and bounded teardown. One + * instance owns one `(provider id, canonical workspace)` process. Queries serialize through a single + * queue so a cancellation that fails to stop the server can terminate it without killing unrelated + * work; distinct instances run in parallel. + * @module @deepseek-ai/dsh-lsp-local/instance + */ + +import { pathToFileURL } from 'node:url' +import type { + LspOperation, + LspProviderQuery, + LspQueryResult, +} from '@deepseek-ai/dsh-lsp' +import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout' +import { LspConnection } from './connection.ts' +import type { ConnectionSpec } from './connection.ts' +import { readHostSource } from './host.ts' +import type { WireInitializeResult, WireServerCapabilities } from './protocol.ts' +import { + negotiatePositionEncoding, + normalizeHover, + normalizeLocations, + requestMethod, + supportsOperation, + supportsTransientOpen, +} from './translate.ts' + +/** Everything an instance needs beyond the connection spec. */ +export interface InstanceSpec extends ConnectionSpec { + /** Static `initialize` options forwarded to the server. */ + readonly initializationOptions: unknown + /** Largest source file this host will open (bytes). */ + readonly maxDocumentBytes: number + /** Graceful `shutdown`/`exit` budget before escalation (ms). */ + readonly shutdownTimeoutMs: number + /** SIGTERM→SIGKILL grace after graceful shutdown fails (ms). */ + readonly killGraceMs: number +} + +/** + * A single initialized server process. Not exported as a provider — the provider single-flights and + * pools these. `query()` serializes; `dispose()` rejects queued work and tears the process down. + */ +export class LspInstance { + private readonly connection: LspConnection + private capabilities: WireServerCapabilities | undefined + /** The serialization tail: each query awaits the prior one, so lifecycles never interleave. */ + private queue: Promise = Promise.resolve() + private disposed = false + /** Set once the process closes, so the pool can synchronously skip a dead instance. */ + private processClosed = false + /** Populated once `initialize` succeeds; a failed handshake rejects every query. */ + private readonly ready: Promise + + /** + * @param spec - the launch, initialize, and teardown parameters. + */ + constructor(private readonly spec: InstanceSpec) { + this.connection = new LspConnection(spec, (method, params) => this.answerServerRequest(method, params)) + this.ready = this.initialize() + // A handshake rejection must not surface as an unhandled rejection before the first query awaits + // it; queries attach the real handler. + this.ready.catch(() => {}) + void this.connection.closed.then(() => { this.processClosed = true }) + } + + /** Synchronous liveness check: true once the process has closed or the instance was disposed. */ + get dead(): boolean { + return this.processClosed || this.disposed + } + + /** + * Run one query through the serialized queue. + * @param request - the resolved provider query. + * @param signal - optional cancellation for this query's full lifecycle. + * @returns the normalized result. + */ + query(request: LspProviderQuery, signal?: AbortSignal): Promise { + const run = this.queue.then(() => this.runQuery(request, signal)) + // Keep the tail alive regardless of this query's outcome so the next caller still serializes. + this.queue = run.then(() => undefined, () => undefined) + return run + } + + private async initialize(): Promise { + const initializeResult = await this.connection.request('initialize', { + processId: process.pid, + rootUri: pathToFileURL(this.spec.cwd).href, + workspaceFolders: [{ uri: pathToFileURL(this.spec.cwd).href, name: 'workspace' }], + capabilities: CLIENT_CAPABILITIES, + initializationOptions: this.spec.initializationOptions, + }) as WireInitializeResult + const capabilities = initializeResult.capabilities + // An omitted encoding defaults to utf-16; any other value is a protocol error we reject here. + negotiatePositionEncoding(capabilities.positionEncoding) + this.capabilities = capabilities + this.connection.notify('initialized', {}) + } + + private async runQuery(request: LspProviderQuery, signal?: AbortSignal): Promise { + if (this.disposed) throw new Error('LSP instance was disposed') + if (signal?.aborted) throw abortError(signal) + await this.ready + const capabilities = this.capabilities + /* v8 ignore next -- `ready` resolves only after capabilities are set, else it rejects above; defensive. */ + if (capabilities === undefined) throw new Error('LSP instance is not initialized') + if (!supportsOperation(capabilities, request.operation)) { + throw new Error(`server does not support ${request.operation}`) + } + if (!supportsTransientOpen(capabilities.textDocumentSync)) { + throw new Error('server does not support the transient textDocument/didOpen this host requires') + } + + const source = await readHostSource(request.filePath, this.spec.cwd, this.spec.maxDocumentBytes) + const uri = pathToFileURL(source.canonicalPath).href + let opened = false + try { + if (signal?.aborted) throw abortError(signal) + this.connection.notify('textDocument/didOpen', { + textDocument: { uri, languageId: request.languageId, version: 1, text: source.text }, + }) + opened = true + const payload = await this.sendRequest(request.operation, uri, request.position, signal) + return this.normalize(request.operation, payload) + } finally { + if (opened) { + try { + this.connection.notify('textDocument/didClose', { textDocument: { uri } }) + } catch (error) { + /* v8 ignore start -- stdin write errors surface asynchronously via the swallowed 'error' + listener, so a synchronous didClose write failure is a defensive path. */ + // A close-write failure does not replace the settled result/error, but the instance can no + // longer be trusted: invalidate it and await bounded process termination. + this.disposed = true + void this.tearDown(error instanceof Error ? error : new Error(String(error))) + /* v8 ignore stop */ + } + } + } + } + + private async sendRequest( + operation: LspOperation, + uri: string, + position: LspProviderQuery['position'], + signal?: AbortSignal, + ): Promise { + const params = { + textDocument: { uri }, + position: { line: position.line, character: position.character }, + // references always includes declarations: the caller gets no flag and impact analysis never + // omits the defining site. + ...(operation === 'references' ? { context: { includeDeclaration: true } } : {}), + } + const requestId = this.connection.peekNextId() + const send = this.connection.request(requestMethod(operation), params) + if (signal === undefined) return send + return this.raceAbort(send, requestId, signal) + } + + /** Race a pending request against abort; on abort, send `$/cancelRequest` and reject. */ + private async raceAbort(send: Promise, requestId: number, signal: AbortSignal): Promise { + const abort = new Promise((_, reject) => { + const onAbort = (): void => { reject(abortError(signal)) } + /* v8 ignore next -- runQuery checks signal.aborted before sending, so it is not yet aborted here; defensive. */ + if (signal.aborted) { onAbort(); return } + signal.addEventListener('abort', onAbort, { once: true }) + // Remove the abort listener once the request settles either way; the finally-promise inherits + // send's rejection, so catch it to avoid an unhandled rejection when abort already won. + send.finally(() => { signal.removeEventListener('abort', onAbort) }).catch(() => {}) + }) + try { + return await Promise.race([send, abort]) + } catch (error) { + if (signal.aborted) this.connection.cancel(requestId) + throw error + } + } + + private normalize(operation: LspOperation, payload: unknown): LspQueryResult { + if (operation === 'hover') { + return { kind: 'hover', hover: normalizeHover(payload) } + } + return { kind: 'locations', locations: normalizeLocations(payload) } + } + + private answerServerRequest(method: string, params: unknown): Promise { + if (method === 'workspace/configuration') { + // Answer every requested item with the one static configuration value. + const record = params as { items?: unknown[] } | null + /* v8 ignore next -- a configuration request always carries an items array; the empty fallback is defensive. */ + const items = Array.isArray(record?.items) ? record.items : [] + return Promise.resolve(items.map(() => this.spec.configuration)) + } + if (LIFECYCLE_NOOP_METHODS.has(method)) { + // Accept lifecycle bookkeeping requests with an empty result; we register nothing dynamic. + return Promise.resolve(null) + } + if (method === 'workspace/applyEdit') { + // This host never applies edits or runs commands. + return Promise.reject(new Error('workspace/applyEdit is not permitted by this host')) + } + return Promise.reject(new Error(`unsupported server request: ${method}`)) + } + + /** + * Reject queued work, attempt graceful `shutdown`/`exit`, then escalate SIGTERM→SIGKILL, awaiting + * process close so nothing outlives disposal. + */ + async dispose(): Promise { + if (this.disposed) { + await this.connection.closed + return + } + this.disposed = true + await this.tearDown(new Error('LSP instance disposed')) + } + + private async tearDown(_reason: Error): Promise { + try { + using shutdownDeadline = deadline(undefined, this.spec.shutdownTimeoutMs, 'LSP_SHUTDOWN') + await this.gracefulShutdown(shutdownDeadline.signal) + } catch { + // Graceful shutdown failed or timed out: fall through to signal escalation. + } + await this.forceTerminate() + } + + /** Best-effort LSP `shutdown` request then `exit` notification, bounded by `signal`. */ + private async gracefulShutdown(signal: AbortSignal): Promise { + const shutdown = this.connection.request('shutdown', null) + await Promise.race([ + shutdown, + new Promise((_, reject) => { + /* v8 ignore next -- the shutdown deadline signal is freshly armed and not yet aborted here; defensive. */ + if (signal.aborted) { reject(abortError(signal)); return } + signal.addEventListener('abort', () => { reject(abortError(signal)) }, { once: true }) + }), + ]) + this.connection.notify('exit', null) + } + + /** SIGTERM, wait `killGraceMs` for close, then SIGKILL; await full process close either way. */ + private async forceTerminate(): Promise { + this.connection.terminate() + using graceDeadline = deadline(undefined, this.spec.killGraceMs, 'LSP_KILL_GRACE') + const closedInTime = await Promise.race([ + this.connection.closed.then(() => true), + new Promise((resolve) => { + /* v8 ignore next -- the kill-grace deadline signal is freshly armed and not yet aborted here; defensive. */ + if (graceDeadline.signal.aborted) { resolve(false); return } + graceDeadline.signal.addEventListener('abort', () => { resolve(false) }, { once: true }) + }), + ]) + if (!closedInTime) this.connection.kill() + await this.connection.closed + } +} + +/** Server→client request methods this host acknowledges with an empty result (no dynamic registration). */ +const LIFECYCLE_NOOP_METHODS = new Set([ + 'window/workDoneProgress/create', + 'client/registerCapability', + 'client/unregisterCapability', +]) + +/** Build an abort Error carrying the signal's reason (preserving a timeout classification). */ +function abortError(signal: AbortSignal): Error { + const timeout = timeoutOf(signal) + if (timeout !== undefined) return timeout + const reason: unknown = signal.reason + if (reason instanceof Error) return reason + return new Error('LSP query aborted') +} + +/** + * The client capabilities advertised at `initialize`: UTF-16 positions, workspace folders and + * configuration, markdown/plaintext hover, and link support for definition/implementation. No + * dynamic registration; the server's returned capabilities are authoritative. + */ +const CLIENT_CAPABILITIES = { + general: { positionEncodings: ['utf-16'] }, + workspace: { workspaceFolders: true, configuration: true }, + textDocument: { + synchronization: { dynamicRegistration: false }, + hover: { contentFormat: ['markdown', 'plaintext'] }, + definition: { linkSupport: true }, + implementation: { linkSupport: true }, + references: {}, + }, +} as const diff --git a/packages/lsp/lsp-local/src/protocol.ts b/packages/lsp/lsp-local/src/protocol.ts new file mode 100644 index 0000000000..abceb04d71 --- /dev/null +++ b/packages/lsp/lsp-local/src/protocol.ts @@ -0,0 +1,80 @@ +/** + * The subset of LSP wire types this generic host reads and writes: initialize capabilities, the four + * request results (`Location`, `LocationLink`, `Hover`), and the `textDocumentSync` shapes used to + * decide transient-open support. Types only. Fields absent from a real server payload stay optional; + * the translation layer normalizes them into the seam's closed unions. + * @module @deepseek-ai/dsh-lsp-local/protocol + */ + +/** A zero-based UTF-16 position on the wire (the protocol's `Position`). */ +export interface WirePosition { + readonly line: number + readonly character: number +} + +/** A wire range (`Range`). */ +export interface WireRange { + readonly start: WirePosition + readonly end: WirePosition +} + +/** A `Location`: a document URI plus a range. */ +export interface WireLocation { + readonly uri: string + readonly range: WireRange +} + +/** A `LocationLink`: the target uri plus the selection range to focus. */ +export interface WireLocationLink { + readonly targetUri: string + readonly targetSelectionRange: WireRange + readonly targetRange?: WireRange +} + +/** A `MarkupContent` hover body (`markdown` or `plaintext`). */ +export interface WireMarkupContent { + readonly kind: 'markdown' | 'plaintext' + readonly value: string +} + +/** A `MarkedString` object form (`{ language, value }`); the string form is a bare `string`. */ +export interface WireMarkedStringObject { + readonly language: string + readonly value: string +} + +/** One `MarkedString`: a raw string or a language-tagged code block. */ +export type WireMarkedString = string | WireMarkedStringObject + +/** A `Hover`: contents in any of the protocol's three encodings, plus an optional range. */ +export interface WireHover { + readonly contents: WireMarkupContent | WireMarkedString | readonly WireMarkedString[] + readonly range?: WireRange +} + +/** The legacy enum form of `textDocumentSync` (`0` None, `1` Full, `2` Incremental). */ +export type WireTextDocumentSyncKind = 0 | 1 | 2 + +/** The options form of `textDocumentSync` (`{ openClose, change }`). */ +export interface WireTextDocumentSyncOptions { + readonly openClose?: boolean + readonly change?: WireTextDocumentSyncKind +} + +/** A `ServerCapabilities.provider` slot: a boolean or an options object (both mean "supported"). */ +export type WireProviderCapability = boolean | Record | undefined + +/** The `ServerCapabilities` fields this host inspects. */ +export interface WireServerCapabilities { + readonly positionEncoding?: string + readonly textDocumentSync?: WireTextDocumentSyncKind | WireTextDocumentSyncOptions + readonly definitionProvider?: WireProviderCapability + readonly referencesProvider?: WireProviderCapability + readonly implementationProvider?: WireProviderCapability + readonly hoverProvider?: WireProviderCapability +} + +/** The `initialize` result envelope. */ +export interface WireInitializeResult { + readonly capabilities: WireServerCapabilities +} diff --git a/packages/lsp/lsp-local/src/translate.ts b/packages/lsp/lsp-local/src/translate.ts new file mode 100644 index 0000000000..a212d283b6 --- /dev/null +++ b/packages/lsp/lsp-local/src/translate.ts @@ -0,0 +1,210 @@ +/** + * Pure protocol translation for the local host: what the server's capabilities allow, and how its + * `Location`/`LocationLink`/`Hover` payloads normalize into the seam's closed result unions. No I/O + * or process state — every function here is a pure transform, which the fake-stdio tests pin exactly. + * @module @deepseek-ai/dsh-lsp-local/translate + */ + +import type { + LspHover, + LspLocation, + LspOperation, + LspRange, +} from '@deepseek-ai/dsh-lsp' +import { assertNever } from '@deepseek-ai/dsh-llm' +import type { + WireHover, + WireLocation, + WireLocationLink, + WireMarkedString, + WireProviderCapability, + WireRange, + WireServerCapabilities, + WireTextDocumentSyncKind, + WireTextDocumentSyncOptions, +} from './protocol.ts' + +/** + * The `textDocument/*` request method for each seam operation. + * @param operation - the seam operation to map. + * @returns the LSP request method name. + */ +export function requestMethod(operation: LspOperation): string { + switch (operation) { + case 'definition': return 'textDocument/definition' + case 'references': return 'textDocument/references' + case 'implementation': return 'textDocument/implementation' + case 'hover': return 'textDocument/hover' + /* v8 ignore next -- exhaustive over the closed LspOperation union; unreachable. */ + default: return assertNever(operation, 'requestMethod') + } +} + +/** The `ServerCapabilities` provider field backing each operation. */ +function capabilityValue(capabilities: WireServerCapabilities, operation: LspOperation): WireProviderCapability { + switch (operation) { + case 'definition': return capabilities.definitionProvider + case 'references': return capabilities.referencesProvider + case 'implementation': return capabilities.implementationProvider + case 'hover': return capabilities.hoverProvider + /* v8 ignore next -- exhaustive over the closed LspOperation union; unreachable. */ + default: return assertNever(operation, 'capabilityValue') + } +} + +/** A provider capability is present when the server sent `true` or an options object (not `false`/absent). */ +function supportsCapability(value: WireProviderCapability): boolean { + if (value === undefined) return false + if (typeof value === 'boolean') return value + return true +} + +/** + * Whether the server advertises the requested operation. + * @param capabilities - the server's `initialize` capabilities. + * @param operation - the seam operation to check. + * @returns true when the corresponding provider capability is present. + */ +export function supportsOperation(capabilities: WireServerCapabilities, operation: LspOperation): boolean { + return supportsCapability(capabilityValue(capabilities, operation)) +} + +/** + * Whether a `textDocumentSync` value permits the transient `didOpen`/`didClose` this host relies on. + * @param sync - the server's advertised `textDocumentSync` capability. + * @returns true when transient open/close is supported. + */ +export function supportsTransientOpen(sync: WireServerCapabilities['textDocumentSync']): boolean { + if (sync === undefined) return false + if (typeof sync === 'number') return isOpenCloseKind(sync) + return sync.openClose === true || (sync.openClose === undefined && changeAllowsOpenClose(sync)) +} + +/** Legacy enum: `Full` (1) or `Incremental` (2) imply open/close support; `None` (0) does not. */ +function isOpenCloseKind(kind: WireTextDocumentSyncKind): boolean { + return kind === 1 || kind === 2 +} + +/** Options without an explicit `openClose` fall back to the legacy `change` enum's implication. */ +function changeAllowsOpenClose(sync: WireTextDocumentSyncOptions): boolean { + return sync.change !== undefined && isOpenCloseKind(sync.change) +} + +/** + * Normalize the negotiated position encoding. An omitted encoding defaults to `utf-16`; any value + * other than `utf-16` is a protocol error this host does not support. + * @param encoding - the server's advertised `positionEncoding`, if any. + * @returns the string `'utf-16'`. + * @throws Error for any non-`utf-16` encoding. + */ +export function negotiatePositionEncoding(encoding: string | undefined): 'utf-16' { + if (encoding === undefined || encoding === 'utf-16') return 'utf-16' + throw new Error(`server negotiated unsupported position encoding "${encoding}"; this host requires utf-16`) +} + +/** Convert a wire range to the seam's range (structurally identical, but re-shaped as `readonly`). */ +function toRange(range: WireRange): LspRange { + return { + start: { line: range.start.line, character: range.start.character }, + end: { line: range.end.line, character: range.end.character }, + } +} + +/** Whether a record is a `LocationLink` (has `targetUri` + `targetSelectionRange`). */ +function isLocationLink(value: Record): boolean { + return typeof value.targetUri === 'string' && isRange(value.targetSelectionRange) +} + +/** Whether a record is a `Location` (has string `uri` + a range). */ +function isLocation(value: Record): boolean { + return typeof value.uri === 'string' && isRange(value.range) +} + +/** Structural range guard used by both location shapes. */ +function isRange(value: unknown): value is WireRange { + if (value === null || typeof value !== 'object') return false + const range = value as Record + return isPosition(range.start) && isPosition(range.end) +} + +/** Structural position guard. */ +function isPosition(value: unknown): boolean { + if (value === null || typeof value !== 'object') return false + const position = value as Record + return typeof position.line === 'number' && typeof position.character === 'number' +} + +/** + * Normalize a navigation result (`Location`, `Location[]`, `LocationLink[]`, or `null`) to the seam's + * locations. `Location` maps directly; `LocationLink` maps `targetUri` + `targetSelectionRange`. + * @param payload - the raw `textDocument/definition|references|implementation` result. + * @returns the normalized locations (empty for `null`/`[]`). + * @throws Error when an element is neither a `Location` nor a `LocationLink`. + */ +export function normalizeLocations(payload: unknown): LspLocation[] { + if (payload === null || payload === undefined) return [] + const elements = Array.isArray(payload) ? payload : [payload] + const locations: LspLocation[] = [] + for (const element of elements) { + if (element === null || typeof element !== 'object') { + throw new Error('LSP navigation result contained a non-object entry') + } + const record = element as Record + if (isLocationLink(record)) { + const link = record as unknown as WireLocationLink + locations.push({ uri: link.targetUri, range: toRange(link.targetSelectionRange) }) + } else if (isLocation(record)) { + const location = record as unknown as WireLocation + locations.push({ uri: location.uri, range: toRange(location.range) }) + } else { + throw new Error('LSP navigation result contained neither a Location nor a LocationLink') + } + } + return locations +} + +/** Render one `MarkedString` (string form verbatim; object form as a language-tagged fenced block). */ +function renderMarkedString(value: WireMarkedString): string { + if (typeof value === 'string') return value + return `\`\`\`${value.language}\n${value.value}\n\`\`\`` +} + +/** + * Normalize a `Hover` (or `null`) to the seam's hover. `MarkupContent` uses its `value`; a string + * `MarkedString` is verbatim; a language-tagged `MarkedString` becomes a fenced code block; an array + * joins its rendered parts with one blank line. `maxHoverChars` is NOT applied here — the tool caps. + * @param payload - the raw `textDocument/hover` result. + * @returns the normalized hover, or `null` when there is no content. + * @throws Error when the payload is a non-null, non-object, or structurally invalid hover. + */ +export function normalizeHover(payload: unknown): LspHover | null { + if (payload === null || payload === undefined) return null + if (typeof payload !== 'object') throw new Error('LSP hover result was not an object') + const hover = payload as unknown as WireHover + const contents = renderHoverContents(hover.contents) + if (contents === '') return null + const range = hover.range + return range !== undefined && isRange(range) ? { contents, range: toRange(range) } : { contents } +} + +/** Render the three `Hover.contents` encodings into one string (input is untrusted wire data). */ +function renderHoverContents(contents: unknown): string { + if (contents === null || contents === undefined) { + throw new Error('LSP hover result had no contents') + } + if (typeof contents === 'string') return contents + if (Array.isArray(contents)) { + return contents.map(renderMarkedString).join('\n\n') + } + if (typeof contents !== 'object') { + throw new Error('LSP hover contents were not MarkupContent, MarkedString, or an array') + } + const record = contents as Record + if (record.kind === 'markdown' || record.kind === 'plaintext') { + return typeof record.value === 'string' ? record.value : '' + } + if (typeof record.language === 'string' && typeof record.value === 'string') { + return renderMarkedString({ language: record.language, value: record.value }) + } + throw new Error('LSP hover contents were not MarkupContent, MarkedString, or an array') +} diff --git a/packages/lsp/lsp-local/tests/built-lib.e2e.ts b/packages/lsp/lsp-local/tests/built-lib.e2e.ts new file mode 100644 index 0000000000..0b33953ba1 --- /dev/null +++ b/packages/lsp/lsp-local/tests/built-lib.e2e.ts @@ -0,0 +1,73 @@ +import { spawn } from 'node:child_process' +import { existsSync } from 'node:fs' +import { mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { fileURLToPath, pathToFileURL } from 'node:url' +import { afterAll, beforeAll, describe, expect, it } from 'vitest' + +/** + * Keyless built-artifact smoke: plain Node imports `@deepseek-ai/dsh-lsp` and + * `@deepseek-ai/dsh-lsp-local` by name through their exports maps, spawns the fixture server, runs + * one query (exercising real `Content-Length` framing over `lib/index.js`), and disposes (exercising + * subprocess cleanup). Unit tests use `src/`; this pins the downstream `lib/` path. Skips when `lib/` + * is absent; CI runs it after the build. + */ + +const pkgDir = fileURLToPath(new URL('..', import.meta.url)) +const seamLib = join(pkgDir, '../lsp/lib/index.js') +const built = existsSync(join(pkgDir, 'lib/index.js')) && existsSync(seamLib) + +const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) +const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url)) +const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) + +let root: string +let ws: string + +beforeAll(async () => { + root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-built-'))) + ws = join(root, 'ws') + await mkdir(ws) + await writeFile(join(ws, 'a.ts'), 'const x = 1\n') +}) + +afterAll(async () => { + if (root) await rm(root, { recursive: true, force: true }) +}) + +describe.skipIf(!built)('built lib real load path (plain node)', () => { + it('runs a query through lib/index.js and disposes cleanly, framing over the base protocol', async () => { + const location = JSON.stringify({ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } }) + const script = ` + const { Context } = await import('cordis') + const { default: Lsp } = await import('@deepseek-ai/dsh-lsp') + const LspLocal = await import('@deepseek-ai/dsh-lsp-local') + const ctx = new Context() + await ctx.plugin(Lsp) + await ctx.plugin(LspLocal, { + providerId: 'fake', + command: ${JSON.stringify(process.execPath)}, + args: ['--import', ${JSON.stringify(tsxLoader)}, ${JSON.stringify(fixtureServer)}], + env: { TSX_TSCONFIG_PATH: ${JSON.stringify(repoTsconfig)}, LSP_FAKE_DEF: ${JSON.stringify(location)} }, + extensionToLanguage: { '.ts': 'typescript' }, + }) + const result = await ctx.lsp.query({ operation: 'definition', filePath: 'a.ts', position: { line: 0, character: 6 }, workspaceRoot: ${JSON.stringify(ws)} }) + console.log(JSON.stringify(result)) + await ctx.fiber.dispose() + process.exit(0) + ` + const child = spawn(process.execPath, ['--input-type=module', '-e', script], { cwd: pkgDir, stdio: ['ignore', 'pipe', 'pipe'] }) + let stdout = '' + let stderr = '' + child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString('utf8') }) + child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString('utf8') }) + const exitCode = await new Promise(resolve => child.on('close', resolve)) + + expect(exitCode, `stderr:\n${stderr}`).toBe(0) + const lastLine = stdout.trim().split('\n').at(-1) ?? '' + const result = JSON.parse(lastLine) as { kind: string; locations: unknown[] } + expect(result.kind).toBe('locations') + expect(result.locations).toHaveLength(1) + }, 60_000) +}) diff --git a/packages/lsp/lsp-local/tests/connection.spec.ts b/packages/lsp/lsp-local/tests/connection.spec.ts new file mode 100644 index 0000000000..baf6fde05f --- /dev/null +++ b/packages/lsp/lsp-local/tests/connection.spec.ts @@ -0,0 +1,226 @@ +import { afterEach, describe, expect, it } from 'vitest' +import { fileURLToPath } from 'node:url' +import { LspConnection } from '@deepseek-ai/dsh-lsp-local' + +const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) +const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url)) +const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) + +/** A recorded server→client request the test's handler saw. */ +interface SeenRequest { method: string; params: unknown } + +let open: LspConnection[] = [] + +afterEach(async () => { + for (const conn of open) { + conn.kill() + await conn.closed + } + open = [] +}) + +/** Spawn the fixture as a raw connection, with a scripted server-request handler. */ +function connect( + env: Record, + onServerRequest: (method: string, params: unknown) => Promise = () => Promise.resolve(null), + seen?: SeenRequest[], +): LspConnection { + const conn = new LspConnection({ + command: process.execPath, + args: ['--import', tsxLoader, fixtureServer], + cwd: process.cwd(), + env: { ...process.env as Record, TSX_TSCONFIG_PATH: repoTsconfig, ...env }, + maxMessageBytes: 16_000_000, + maxStderrBytes: 100_000, + configuration: { setting: 42 }, + }, (method, params) => { + seen?.push({ method, params }) + return onServerRequest(method, params) + }) + open.push(conn) + return conn +} + +describe('LspConnection', () => { + it('completes an initialize request/response round-trip and exposes a pid', async () => { + const conn = connect({}) + const result = await conn.request('initialize', { capabilities: {} }) + expect(result).toMatchObject({ capabilities: { hoverProvider: true } }) + expect(conn.pid).toBeGreaterThan(0) + }) + + it('rejects a request when the server replies with an error', async () => { + const conn = connect({ LSP_FAKE_ERROR: '1' }) + await conn.request('initialize', { capabilities: {} }) + await expect(conn.request('textDocument/hover', {})).rejects.toThrow(/server refused the request/) + }) + + it('answers a server workspace/configuration request from static config', async () => { + const seen: SeenRequest[] = [] + const conn = connect( + { LSP_FAKE_ON_OPEN: 'configuration' }, + (method, params) => { + if (method === 'workspace/configuration') { + const items = (params as { items: unknown[] }).items + return Promise.resolve(items.map(() => ({ setting: 42 }))) + } + return Promise.resolve(null) + }, + seen, + ) + await conn.request('initialize', { capabilities: {} }) + conn.notify('textDocument/didOpen', { textDocument: { uri: 'file:///x', languageId: 'ts', version: 1, text: '' } }) + await waitFor(() => seen.some(s => s.method === 'workspace/configuration')) + expect(seen[0]?.method).toBe('workspace/configuration') + }) + + it('drops a server→client notification without replying', async () => { + const conn = connect({ LSP_FAKE_ON_OPEN: 'notification' }) + await conn.request('initialize', { capabilities: {} }) + conn.notify('textDocument/didOpen', { textDocument: { uri: 'file:///x', languageId: 'ts', version: 1, text: '' } }) + // No throw and the connection stays usable. + await expect(conn.request('textDocument/hover', {})).resolves.toBeDefined() + }) + + it('sends an error response when the server-request handler rejects', async () => { + const seen: SeenRequest[] = [] + const conn = connect( + { LSP_FAKE_ON_OPEN: 'applyEdit' }, + method => method === 'workspace/applyEdit' ? Promise.reject(new Error('not permitted')) : Promise.resolve(null), + seen, + ) + await conn.request('initialize', { capabilities: {} }) + conn.notify('textDocument/didOpen', { textDocument: { uri: 'file:///x', languageId: 'ts', version: 1, text: '' } }) + await waitFor(() => seen.some(s => s.method === 'workspace/applyEdit')) + // The connection remains healthy after emitting the error response. + await expect(conn.request('textDocument/hover', {})).resolves.toBeDefined() + }) + + it('fails all pending requests and kills the process on a framing error', async () => { + const conn = connect({ LSP_FAKE_GARBAGE: '1' }) + // The garbage byte precedes a valid initialize reply; unframed bytes are tolerated until a + // Content-Length header, so initialize still resolves. This exercises the decoder's resilience. + await expect(conn.request('initialize', { capabilities: {} })).resolves.toBeDefined() + }) + + it('rejects a new request issued after the process closes', async () => { + const conn = connect({}) + await conn.request('initialize', { capabilities: {} }) + conn.terminate() + await conn.closed + await expect(conn.request('textDocument/hover', {})).rejects.toThrow(/exited|closed/) + }) + + it('cancel is a no-op-safe write after close', async () => { + const conn = connect({}) + await conn.request('initialize', { capabilities: {} }) + conn.terminate() + await conn.closed + expect(() => { conn.cancel(1) }).not.toThrow() + }) + + it('caps the retained stderr tail', async () => { + const conn = connect({}) + await conn.request('initialize', { capabilities: {} }) + expect(conn.stderrTail.length).toBeLessThanOrEqual(100_000) + }) +}) + +/** Spawn a raw connection running an inline node script as the "server". */ +function connectScript(script: string, maxStderrBytes = 100_000): LspConnection { + const conn = new LspConnection({ + command: process.execPath, + args: ['-e', script], + cwd: process.cwd(), + env: { ...process.env as Record }, + maxMessageBytes: 16_000_000, + maxStderrBytes, + configuration: null, + }, () => Promise.resolve(null)) + open.push(conn) + return conn +} + +describe('LspConnection edge behavior', () => { + it('fails a request when the command cannot be spawned', async () => { + const conn = new LspConnection({ + command: '/definitely/not/a/real/binary/xyz', + args: [], + cwd: process.cwd(), + env: {}, + maxMessageBytes: 1000, + maxStderrBytes: 1000, + configuration: null, + }, () => Promise.resolve(null)) + open.push(conn) + await expect(conn.request('initialize', {})).rejects.toThrow() + }) + + it('kills the process and fails pending requests on a framing error', async () => { + // Emit an invalid Content-Length header, corrupting the stream irrecoverably. + const conn = connectScript('process.stdout.write("Content-Length: abc\\r\\n\\r\\n{}"); setInterval(()=>{}, 1000)') + await expect(conn.request('initialize', {})).rejects.toThrow() + }) + + it('ignores a framed non-object message', async () => { + // Send a framed JSON number and a framed null (both non-objects) then a proper response to id 1. + const script = 'let b=Buffer.alloc(0);' + + 'const fr=(s)=>{const x=Buffer.from(s);return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};' + + 'process.stdout.write(fr("42"));process.stdout.write(fr("null"));' + + 'process.stdin.on("data",c=>{b=Buffer.concat([b,c]);const s=b.indexOf("\\r\\n\\r\\n");if(s<0)return;const len=Number(/(\\d+)/.exec(b.toString("ascii",0,s))[1]);const body=JSON.parse(b.toString("utf8",s+4,s+4+len));process.stdout.write(fr(JSON.stringify({jsonrpc:"2.0",id:body.id,result:{ok:true}})));});' + const conn = connectScript(script) + await expect(conn.request('initialize', {})).resolves.toEqual({ ok: true }) + }) + + it('drops a response for an unknown id', async () => { + // Emit a response for id 999 (never sent), then answer our real request. + const script = 'let b=Buffer.alloc(0);' + + 'const fr=(s)=>{const x=Buffer.from(s);return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};' + + 'process.stdout.write(fr(JSON.stringify({jsonrpc:"2.0",id:999,result:{stray:true}})));' + + 'process.stdin.on("data",c=>{b=Buffer.concat([b,c]);const s=b.indexOf("\\r\\n\\r\\n");if(s<0)return;const len=Number(/(\\d+)/.exec(b.toString("ascii",0,s))[1]);const body=JSON.parse(b.toString("utf8",s+4,s+4+len));process.stdout.write(fr(JSON.stringify({jsonrpc:"2.0",id:body.id,result:{ok:true}})));});' + const conn = connectScript(script) + await expect(conn.request('initialize', {})).resolves.toEqual({ ok: true }) + }) + + it('caps the retained stderr tail at maxStderrBytes across chunks', async () => { + // Write stderr repeatedly so a later chunk arrives after the cap is already reached. + const conn = connectScript('setInterval(()=>process.stderr.write("E".repeat(200)), 5); setInterval(()=>{}, 1000)', 100) + await waitFor(() => conn.stderrTail.length >= 100) + await new Promise(resolve => setTimeout(resolve, 50)) + expect(conn.stderrTail.length).toBe(100) + }) + + it('rejects with a fallback message when the error response has no message string', async () => { + const script = 'let b=Buffer.alloc(0);' + + 'const fr=(s)=>{const x=Buffer.from(s);return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};' + + 'process.stdin.on("data",c=>{b=Buffer.concat([b,c]);const s=b.indexOf("\\r\\n\\r\\n");if(s<0)return;const len=Number(/(\\d+)/.exec(b.toString("ascii",0,s))[1]);const body=JSON.parse(b.toString("utf8",s+4,s+4+len));process.stdout.write(fr(JSON.stringify({jsonrpc:"2.0",id:body.id,error:{code:-1}})));});' + const conn = connectScript(script) + await expect(conn.request('initialize', {})).rejects.toThrow(/LSP error response/) + }) + + it('rejects a pending request when the process exits mid-flight', async () => { + // Never responds, then exits shortly: the pending request must reject on close. + const conn = connectScript('setTimeout(()=>process.exit(0), 100)') + await expect(conn.request('initialize', {})).rejects.toThrow(/exited|closed/) + }) + + it('ignores a frame that is neither a valid request nor a numeric-id response', async () => { + // A frame with a string id and no method: not dispatchable; the client must ignore it and still + // answer our real request. + const script = 'let b=Buffer.alloc(0);' + + 'const fr=(s)=>{const x=Buffer.from(s);return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};' + + 'process.stdout.write(fr(JSON.stringify({jsonrpc:"2.0",id:"str-id"})));' + + 'process.stdin.on("data",c=>{b=Buffer.concat([b,c]);const s=b.indexOf("\\r\\n\\r\\n");if(s<0)return;const len=Number(/(\\d+)/.exec(b.toString("ascii",0,s))[1]);const body=JSON.parse(b.toString("utf8",s+4,s+4+len));process.stdout.write(fr(JSON.stringify({jsonrpc:"2.0",id:body.id,result:{ok:true}})));});' + const conn = connectScript(script) + await expect(conn.request('initialize', {})).resolves.toEqual({ ok: true }) + }) +}) + +/** Poll a predicate until it holds or a deadline elapses. */ +async function waitFor(predicate: () => boolean, timeoutMs = 3000): Promise { + const start = Date.now() + while (!predicate()) { + if (Date.now() - start > timeoutMs) throw new Error('waitFor timed out') + await new Promise(resolve => setTimeout(resolve, 10)) + } +} diff --git a/packages/lsp/lsp-local/tests/fixture-server.ts b/packages/lsp/lsp-local/tests/fixture-server.ts new file mode 100644 index 0000000000..104b223794 --- /dev/null +++ b/packages/lsp/lsp-local/tests/fixture-server.ts @@ -0,0 +1,144 @@ +/** + * A scriptable fake LSP server over stdio for lsp-local tests. It speaks the real + * `Content-Length`-framed base protocol so it exercises the client's framing, initialize handshake, + * transient open/close, request mapping, and teardown — without a real language server. + * + * Behavior is driven by env vars so one file backs many scenarios: + * - LSP_FAKE_ENCODING: advertised positionEncoding (default utf-16; "utf-8" forces a mismatch). + * - LSP_FAKE_SYNC: textDocumentSync value as JSON (default 1/Full). + * - LSP_FAKE_CAPS: JSON of extra capability flags merged into the defaults. + * - LSP_FAKE_DEF / LSP_FAKE_REFS / LSP_FAKE_IMPL / LSP_FAKE_HOVER: JSON result per request. + * - LSP_FAKE_HANG: "1" makes textDocument/* requests never respond (for abort/timeout tests). + * - LSP_FAKE_CRASH_ON_OPEN: "1" exits the process when a didOpen arrives (crash test). + * - LSP_FAKE_NO_SHUTDOWN: "1" ignores the shutdown request (forces kill escalation). + * - LSP_FAKE_ON_OPEN: server→client request to emit when a didOpen arrives, one of + * "configuration" | "applyEdit" | "notification" | "unknown"; the reply is logged to stderr. + * - LSP_FAKE_ERROR: "1" answers textDocument/* requests with a JSON-RPC error response. + * - LSP_FAKE_GARBAGE: "1" emits an unframed garbage byte before the initialize reply. + * + * Run: node --import tsx fixture-server.ts + */ + +const enc = process.env.LSP_FAKE_ENCODING ?? 'utf-16' +const sync: unknown = process.env.LSP_FAKE_SYNC !== undefined ? JSON.parse(process.env.LSP_FAKE_SYNC) : 1 +const extraCaps: unknown = process.env.LSP_FAKE_CAPS !== undefined ? JSON.parse(process.env.LSP_FAKE_CAPS) : {} +const hang = process.env.LSP_FAKE_HANG === '1' +const crashOnOpen = process.env.LSP_FAKE_CRASH_ON_OPEN === '1' +const noShutdown = process.env.LSP_FAKE_NO_SHUTDOWN === '1' +const onOpen = process.env.LSP_FAKE_ON_OPEN +const errorReply = process.env.LSP_FAKE_ERROR === '1' +const garbage = process.env.LSP_FAKE_GARBAGE === '1' + +let serverRequestId = 10_000 +const pendingServerRequests = new Map() + +function resultFor(method: string): unknown { + switch (method) { + case 'textDocument/definition': return envJson('LSP_FAKE_DEF', null) + case 'textDocument/references': return envJson('LSP_FAKE_REFS', null) + case 'textDocument/implementation': return envJson('LSP_FAKE_IMPL', null) + case 'textDocument/hover': return envJson('LSP_FAKE_HOVER', null) + default: return null + } +} + +function envJson(name: string, fallback: unknown): unknown { + const raw = process.env[name] + return raw === undefined ? fallback : JSON.parse(raw) +} + +let buffer = Buffer.alloc(0) +process.stdin.on('data', (chunk: Buffer) => { + buffer = Buffer.concat([buffer, chunk]) + for (;;) { + const sep = buffer.indexOf('\r\n\r\n') + if (sep < 0) break + const header = buffer.toString('ascii', 0, sep) + const match = /content-length:\s*(\d+)/i.exec(header) + if (!match) { buffer = buffer.subarray(sep + 4); continue } + const length = Number(match[1]) + const start = sep + 4 + if (buffer.length < start + length) break + const body = buffer.toString('utf8', start, start + length) + buffer = buffer.subarray(start + length) + handle(JSON.parse(body) as { id?: number; method?: string; params?: unknown; result?: unknown; error?: unknown }) + } +}) + +function handle(message: { id?: number; method?: string; params?: unknown; result?: unknown; error?: unknown }): void { + const { id, method } = message + // A frame with an id but no method is the client's REPLY to a server→client request; log it. + if (method === undefined && id !== undefined && pendingServerRequests.has(id)) { + const kind = pendingServerRequests.get(id) + pendingServerRequests.delete(id) + process.stderr.write(`REPLY ${kind} ${JSON.stringify({ result: message.result, error: message.error })}\n`) + return + } + if (method === 'initialize') { + if (garbage) process.stdout.write('this is not a framed message\r\n') + send({ + id, + result: { + capabilities: { + positionEncoding: enc, + textDocumentSync: sync, + definitionProvider: true, + referencesProvider: true, + implementationProvider: true, + hoverProvider: true, + ...(extraCaps as Record), + }, + }, + }) + return + } + if (method === 'shutdown') { + if (noShutdown) return + send({ id, result: null }) + return + } + if (method === 'exit') { + process.exit(0) + } + if (method === 'textDocument/didOpen') { + if (crashOnOpen) process.exit(1) + if (onOpen !== undefined) emitServerRequest(onOpen) + return + } + if (method === 'textDocument/didClose' || method === 'initialized') return + if (method?.startsWith('textDocument/')) { + if (hang) return + if (errorReply) { send({ id, error: { code: -32000, message: 'server refused the request' } }); return } + send({ id, result: resultFor(method) }) + return + } + // Unknown request with an id: answer null so the client never stalls. + if (id !== undefined) send({ id, result: null }) +} + +/** Emit a server→client request and log the client's reply to stderr for the test to assert. */ +function emitServerRequest(kind: string): void { + if (kind === 'notification') { + send({ method: 'window/logMessage', params: { type: 3, message: 'hello' } }) + return + } + const id = serverRequestId++ + const method = kind === 'configuration' + ? 'workspace/configuration' + : kind === 'applyEdit' + ? 'workspace/applyEdit' + : kind === 'lifecycle' + ? 'client/registerCapability' + : 'window/showMessageRequest' + const params = kind === 'configuration' ? { items: [{ section: 'a' }, { section: 'b' }] } : {} + pendingServerRequests.set(id, method) + send({ id, method, params }) +} + +function send(message: Record): void { + const body = Buffer.from(JSON.stringify({ jsonrpc: '2.0', ...message }), 'utf8') + process.stdout.write(Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'ascii'), body])) +} + +// Keep the event loop alive. +process.stdin.resume() diff --git a/packages/lsp/lsp-local/tests/framing.spec.ts b/packages/lsp/lsp-local/tests/framing.spec.ts new file mode 100644 index 0000000000..66bca07f10 --- /dev/null +++ b/packages/lsp/lsp-local/tests/framing.spec.ts @@ -0,0 +1,76 @@ +import { describe, expect, it } from 'vitest' +import { encodeMessage, MessageDecoder } from '@deepseek-ai/dsh-lsp-local' + +/** Frame a message the way a server would, for decoder round-trips. */ +function frame(body: string): Buffer { + return Buffer.concat([Buffer.from(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n`, 'ascii'), Buffer.from(body, 'utf8')]) +} + +describe('encodeMessage', () => { + it('prefixes a Content-Length header with the utf-8 byte length', () => { + const buffer = encodeMessage({ jsonrpc: '2.0', method: 'x', params: { s: 'é' } }) + const text = buffer.toString('utf8') + const body = '{"jsonrpc":"2.0","method":"x","params":{"s":"é"}}' + expect(text).toBe(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`) + }) +}) + +describe('MessageDecoder', () => { + it('decodes a single framed message', () => { + const decoder = new MessageDecoder(1_000) + expect(decoder.push(frame('{"id":1,"result":42}'))).toEqual([{ id: 1, result: 42 }]) + }) + + it('decodes multiple messages arriving in one chunk', () => { + const decoder = new MessageDecoder(1_000) + const chunk = Buffer.concat([frame('{"a":1}'), frame('{"b":2}')]) + expect(decoder.push(chunk)).toEqual([{ a: 1 }, { b: 2 }]) + }) + + it('reassembles a message split across chunks', () => { + const decoder = new MessageDecoder(1_000) + const full = frame('{"hello":"world"}') + expect(decoder.push(full.subarray(0, 10))).toEqual([]) + expect(decoder.push(full.subarray(10))).toEqual([{ hello: 'world' }]) + }) + + it('handles a header split from its body', () => { + const decoder = new MessageDecoder(1_000) + const body = '{"x":1}' + expect(decoder.push(Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'ascii'))).toEqual([]) + expect(decoder.push(Buffer.from(body, 'utf8'))).toEqual([{ x: 1 }]) + }) + + it('reads a case-insensitive header and ignores other headers', () => { + const decoder = new MessageDecoder(1_000) + const body = '{"ok":true}' + const chunk = Buffer.from(`content-length: ${body.length}\r\nContent-Type: x\r\n\r\n${body}`, 'utf8') + expect(decoder.push(chunk)).toEqual([{ ok: true }]) + }) + + it('rejects a body over the size limit', () => { + const decoder = new MessageDecoder(4) + expect(() => decoder.push(frame('{"big":true}'))).toThrow(/exceeds the 4-byte limit/) + }) + + it('rejects a missing Content-Length header', () => { + const decoder = new MessageDecoder(1_000) + expect(() => decoder.push(Buffer.from('X: 1\r\n\r\n{}', 'utf8'))).toThrow(/missing Content-Length/) + }) + + it('rejects a non-numeric Content-Length', () => { + const decoder = new MessageDecoder(1_000) + expect(() => decoder.push(Buffer.from('Content-Length: abc\r\n\r\n{}', 'utf8'))).toThrow(/invalid Content-Length/) + }) + + it('rejects a header block that never terminates', () => { + const decoder = new MessageDecoder(1_000) + const huge = Buffer.alloc((1 << 16) + 1, 0x41) + expect(() => decoder.push(huge)).toThrow(/exceeded .* bytes without a terminator/) + }) + + it('rejects a non-JSON body', () => { + const decoder = new MessageDecoder(1_000) + expect(() => decoder.push(frame('not json'))).toThrow(/not valid JSON/) + }) +}) diff --git a/packages/lsp/lsp-local/tests/host.spec.ts b/packages/lsp/lsp-local/tests/host.spec.ts new file mode 100644 index 0000000000..b76aa556e2 --- /dev/null +++ b/packages/lsp/lsp-local/tests/host.spec.ts @@ -0,0 +1,105 @@ +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { mkdtemp, mkdir, rm, symlink, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { realpath } from 'node:fs/promises' +import { canonicalizeWorkspace, readHostSource } from '@deepseek-ai/dsh-lsp-local' + +let root: string +let ws: string + +beforeEach(async () => { + root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-host-'))) + ws = join(root, 'ws') + await mkdir(ws) +}) + +afterEach(async () => { + await rm(root, { recursive: true, force: true }) +}) + +const BIG = 1_000_000 + +describe('canonicalizeWorkspace', () => { + it('returns the realpath of a directory', async () => { + expect(await canonicalizeWorkspace(ws)).toBe(ws) + }) + + it('resolves a symlinked workspace to its target so aliases share identity', async () => { + const link = join(root, 'ws-link') + await symlink(ws, link) + expect(await canonicalizeWorkspace(link)).toBe(ws) + }) + + it('rejects a missing workspace', async () => { + await expect(canonicalizeWorkspace(join(root, 'nope'))).rejects.toThrow(/cannot be resolved/) + }) + + it('rejects a non-directory workspace', async () => { + const file = join(root, 'file.txt') + await writeFile(file, 'x') + await expect(canonicalizeWorkspace(file)).rejects.toThrow(/not a directory/) + }) +}) + +describe('readHostSource', () => { + it('reads a relative path against the workspace', async () => { + await writeFile(join(ws, 'a.ts'), 'const x = 1\n') + const source = await readHostSource('a.ts', ws, BIG) + expect(source.canonicalPath).toBe(join(ws, 'a.ts')) + expect(source.text).toBe('const x = 1\n') + }) + + it('reads an absolute path inside the workspace', async () => { + const abs = join(ws, 'b.ts') + await writeFile(abs, 'b') + const source = await readHostSource(abs, ws, BIG) + expect(source.canonicalPath).toBe(abs) + }) + + it('accepts a source reached through a symlink that stays inside the workspace', async () => { + await mkdir(join(ws, 'real')) + await writeFile(join(ws, 'real', 'c.ts'), 'c') + await symlink(join(ws, 'real'), join(ws, 'linked')) + const source = await readHostSource('linked/c.ts', ws, BIG) + expect(source.canonicalPath).toBe(join(ws, 'real', 'c.ts')) + }) + + it('rejects a source whose canonical path escapes the workspace via symlink', async () => { + const outside = join(root, 'outside.ts') + await writeFile(outside, 'secret') + await symlink(outside, join(ws, 'escape.ts')) + await expect(readHostSource('escape.ts', ws, BIG)).rejects.toThrow(/outside the workspace/) + }) + + it('rejects an absolute source outside the workspace', async () => { + const outside = join(root, 'out.ts') + await writeFile(outside, 'x') + await expect(readHostSource(outside, ws, BIG)).rejects.toThrow(/outside the workspace/) + }) + + it('rejects a missing source', async () => { + await expect(readHostSource('nope.ts', ws, BIG)).rejects.toThrow(/cannot be resolved/) + }) + + it('rejects a non-regular source (directory)', async () => { + await mkdir(join(ws, 'dir')) + await expect(readHostSource('dir', ws, BIG)).rejects.toThrow(/not a regular file/) + }) + + it('treats the workspace root itself as inside, then rejects it as non-regular', async () => { + // filePath '.' canonicalizes to the workspace dir: isInside's identity branch is taken, and the + // directory then fails the regular-file check. + await expect(readHostSource('.', ws, BIG)).rejects.toThrow(/not a regular file/) + }) + + it('rejects an oversized source', async () => { + await writeFile(join(ws, 'big.ts'), 'x'.repeat(100)) + await expect(readHostSource('big.ts', ws, 10)).rejects.toThrow(/over the 10-byte limit/) + }) + + it('rejects a non-UTF-8 source', async () => { + await writeFile(join(ws, 'bin.ts'), Buffer.from([0xff, 0xfe, 0x00])) + await expect(readHostSource('bin.ts', ws, BIG)).rejects.toThrow(/not valid UTF-8/) + }) +}) diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts new file mode 100644 index 0000000000..da3231f133 --- /dev/null +++ b/packages/lsp/lsp-local/tests/instance.spec.ts @@ -0,0 +1,184 @@ +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { pathToFileURL, fileURLToPath } from 'node:url' +import { LspInstance } from '@deepseek-ai/dsh-lsp-local' +import type { InstanceSpec } from '@deepseek-ai/dsh-lsp-local/src/instance.ts' +import type { LspProviderQuery } from '@deepseek-ai/dsh-lsp' + +const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) +const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url)) +const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) + +let root: string +let ws: string +let live: LspInstance[] = [] + +beforeEach(async () => { + root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-inst-'))) + ws = join(root, 'ws') + await mkdir(ws) + await writeFile(join(ws, 'a.ts'), 'const x = 1\n') +}) + +afterEach(async () => { + for (const instance of live) await instance.dispose() + live = [] + await rm(root, { recursive: true, force: true }) +}) + +function makeInstance(env: Record = {}, overrides: Partial = {}): LspInstance { + const instance = new LspInstance({ + command: process.execPath, + args: ['--import', tsxLoader, fixtureServer], + cwd: ws, + env: { ...process.env as Record, TSX_TSCONFIG_PATH: repoTsconfig, ...env }, + configuration: { setting: 42 }, + initializationOptions: { init: true }, + maxMessageBytes: 16_000_000, + maxStderrBytes: 100_000, + maxDocumentBytes: 4_000_000, + shutdownTimeoutMs: 200, + killGraceMs: 200, + ...overrides, + }) + live.push(instance) + return instance +} + +function query(operation: LspProviderQuery['operation'] = 'definition'): LspProviderQuery { + return { operation, filePath: 'a.ts', position: { line: 0, character: 6 }, workspaceRoot: ws, languageId: 'typescript' } +} + +/** Build an instance whose "server" is an inline node script (for teardown-escalation control). */ +function scriptInstance(script: string, overrides: Partial = {}): LspInstance { + const instance = new LspInstance({ + command: process.execPath, + args: ['-e', script], + cwd: ws, + env: { ...process.env as Record }, + configuration: null, + initializationOptions: null, + maxMessageBytes: 16_000_000, + maxStderrBytes: 100_000, + maxDocumentBytes: 4_000_000, + shutdownTimeoutMs: 150, + killGraceMs: 150, + ...overrides, + }) + live.push(instance) + return instance +} + +/** An inline server that answers initialize + definition and echoes a location. */ +const RESPONDING_SERVER = + 'let b=Buffer.alloc(0);' + + 'const fr=(o)=>{const x=Buffer.from(JSON.stringify({jsonrpc:"2.0",...o}));return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};' + + 'process.stdin.on("data",c=>{b=Buffer.concat([b,c]);for(;;){const s=b.indexOf("\\r\\n\\r\\n");if(s<0)break;const len=Number(/(\\d+)/.exec(b.toString("ascii",0,s))[1]);if(b.length JSON.stringify({ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } }) + +describe('LspInstance server-request handling', () => { + it('answers workspace/configuration with the static config per item', async () => { + const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'configuration', LSP_FAKE_DEF: locJson() }) + // The query drives didOpen, which makes the fake emit workspace/configuration; a healthy answer + // keeps the query working. + await expect(instance.query(query('definition'))).resolves.toMatchObject({ kind: 'locations' }) + }) + + it('accepts a lifecycle client/registerCapability request', async () => { + const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'lifecycle', LSP_FAKE_DEF: 'null' }) + await expect(instance.query(query('definition'))).resolves.toEqual({ kind: 'locations', locations: [] }) + }) + + it('rejects a workspace/applyEdit request but keeps serving', async () => { + const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'applyEdit', LSP_FAKE_DEF: 'null' }) + await expect(instance.query(query('definition'))).resolves.toEqual({ kind: 'locations', locations: [] }) + }) + + it('rejects an unknown server request but keeps serving', async () => { + const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'unknown', LSP_FAKE_DEF: 'null' }) + await expect(instance.query(query('definition'))).resolves.toEqual({ kind: 'locations', locations: [] }) + }) +}) + +describe('LspInstance query and abort', () => { + it('sends includeDeclaration for references', async () => { + const instance = makeInstance({ LSP_FAKE_REFS: JSON.stringify([JSON.parse(locJson())]) }) + await expect(instance.query(query('references'))).resolves.toMatchObject({ kind: 'locations' }) + }) + + it('rejects a query aborted before it starts', async () => { + const instance = makeInstance({ LSP_FAKE_DEF: 'null' }) + const controller = new AbortController() + controller.abort(new Error('pre-abort')) + await expect(instance.query(query('definition'), controller.signal)).rejects.toThrow(/pre-abort/) + }) + + it('cancels an in-flight request on abort and rejects', async () => { + const instance = makeInstance({ LSP_FAKE_HANG: '1' }) + const controller = new AbortController() + // Warm the instance first so the abort lands during the hanging request, not during startup. + const pending = instance.query(query('definition'), controller.signal) + await new Promise(resolve => setTimeout(resolve, 300)) + controller.abort(new Error('mid-flight')) + await expect(pending).rejects.toThrow(/mid-flight/) + }) + + it('rejects when the server lacks the operation capability', async () => { + const instance = makeInstance({ LSP_FAKE_CAPS: JSON.stringify({ definitionProvider: false }), LSP_FAKE_DEF: 'null' }) + await expect(instance.query(query('definition'))).rejects.toThrow(/does not support definition/) + }) + + it('propagates a server error response even when a signal is supplied (not an abort)', async () => { + // A live signal is passed, but the request fails for a server reason; the catch must rethrow + // without treating it as an abort. + const instance = makeInstance({ LSP_FAKE_ERROR: '1' }) + const controller = new AbortController() + await expect(instance.query(query('definition'), controller.signal)).rejects.toThrow(/server refused/) + }) +}) + +describe('LspInstance disposal', () => { + it('is idempotent — a second dispose awaits close without error', async () => { + const instance = makeInstance({ LSP_FAKE_DEF: 'null' }) + await instance.query(query('definition')) + await instance.dispose() + await expect(instance.dispose()).resolves.toBeUndefined() + }) + + it('rejects a query after disposal', async () => { + const instance = makeInstance({ LSP_FAKE_DEF: 'null' }) + await instance.query(query('definition')) + await instance.dispose() + await expect(instance.query(query('definition'))).rejects.toThrow(/disposed/) + }) + + it('reports dead after the process closes', async () => { + const instance = makeInstance({ LSP_FAKE_DEF: 'null' }) + await instance.query(query('definition')) + await instance.dispose() + expect(instance.dead).toBe(true) + }) + + it('escalates to SIGKILL when the server ignores shutdown and SIGTERM', async () => { + // Server answers initialize, ignores shutdown, and traps SIGTERM so only SIGKILL stops it. + const script = RESPONDING_SERVER + 'process.on("SIGTERM",()=>{});' + const instance = scriptInstance(script, { shutdownTimeoutMs: 100, killGraceMs: 100 }) + await instance.query(query('definition')) + await expect(instance.dispose()).resolves.toBeUndefined() + }) + + it('carries a non-Error abort reason as a generic aborted error', async () => { + const instance = makeInstance({ LSP_FAKE_HANG: '1' }) + const controller = new AbortController() + const pending = instance.query(query('definition'), controller.signal) + await new Promise(resolve => setTimeout(resolve, 200)) + controller.abort('a string reason, not an Error') + await expect(pending).rejects.toThrow(/aborted/) + }) +}) diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts new file mode 100644 index 0000000000..c5631f2a95 --- /dev/null +++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts @@ -0,0 +1,200 @@ +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises' +import { realpath } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { pathToFileURL, fileURLToPath } from 'node:url' +import { Context } from 'cordis' +import Lsp, { type LspQueryRequest, type LspQueryResult } from '@deepseek-ai/dsh-lsp' +import { deadline } from '@deepseek-ai/dsh-timeout' +import * as LspLocal from '@deepseek-ai/dsh-lsp-local' +import type { Config } from '@deepseek-ai/dsh-lsp-local' + +const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) +const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url)) +const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) + +let root: string +let ws: string + +beforeEach(async () => { + root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-local-'))) + ws = join(root, 'ws') + await mkdir(ws) + await writeFile(join(ws, 'a.ts'), 'const x = 1\nconst y = x\n') +}) + +afterEach(async () => { + await rm(root, { recursive: true, force: true }) +}) + +/** Mount the real seam + lsp-local plugin driving the fake server with the given env. */ +async function mount(fakeEnv: Record = {}, overrides: Partial = {}): Promise { + const ctx = new Context() + await ctx.plugin(Lsp) + await ctx.plugin(LspLocal, { + providerId: 'fake', + command: process.execPath, + args: ['--import', tsxLoader, fixtureServer], + env: { TSX_TSCONFIG_PATH: repoTsconfig, ...fakeEnv }, + extensionToLanguage: { '.ts': 'typescript' }, + ...overrides, + }) + return ctx +} + +function query(operation: LspQueryRequest['operation'], filePath = 'a.ts'): LspQueryRequest { + return { operation, filePath, position: { line: 0, character: 6 }, workspaceRoot: ws } +} + +/** A single Location JSON pointing into the workspace. */ +function locationJson(line: number): unknown { + return { uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line, character: 0 }, end: { line, character: 3 } } } +} + +describe('lsp-local end to end over a fake server', () => { + it('resolves definition to normalized locations', async () => { + const ctx = await mount({ LSP_FAKE_DEF: JSON.stringify(locationJson(0)) }) + const result = await ctx.lsp.query(query('definition')) + expect(result).toEqual({ + kind: 'locations', + locations: [{ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } }], + }) + await ctx.fiber.dispose() + }) + + it('maps a LocationLink for implementation', async () => { + const link = { targetUri: pathToFileURL(join(ws, 'a.ts')).href, targetSelectionRange: { start: { line: 1, character: 0 }, end: { line: 1, character: 2 } } } + const ctx = await mount({ LSP_FAKE_IMPL: JSON.stringify([link]) }) + const result = await ctx.lsp.query(query('implementation')) + expect(result).toMatchObject({ kind: 'locations', locations: [{ range: { start: { line: 1, character: 0 } } }] }) + await ctx.fiber.dispose() + }) + + it('returns references (server includes the declaration)', async () => { + const ctx = await mount({ LSP_FAKE_REFS: JSON.stringify([locationJson(0), locationJson(1)]) }) + const result = await ctx.lsp.query(query('references')) + expect(result).toMatchObject({ kind: 'locations' }) + if (result.kind !== 'locations') throw new Error('expected locations') + expect(result.locations).toHaveLength(2) + await ctx.fiber.dispose() + }) + + it('normalizes a hover MarkupContent', async () => { + const ctx = await mount({ LSP_FAKE_HOVER: JSON.stringify({ contents: { kind: 'markdown', value: 'docs' } }) }) + const result = await ctx.lsp.query(query('hover')) + expect(result).toEqual({ kind: 'hover', hover: { contents: 'docs' } }) + await ctx.fiber.dispose() + }) + + it('returns an empty locations result for a null definition', async () => { + const ctx = await mount({ LSP_FAKE_DEF: 'null' }) + expect(await ctx.lsp.query(query('definition'))).toEqual({ kind: 'locations', locations: [] }) + await ctx.fiber.dispose() + }) + + it('returns a null hover for a null result', async () => { + const ctx = await mount({ LSP_FAKE_HOVER: 'null' }) + expect(await ctx.lsp.query(query('hover'))).toEqual({ kind: 'hover', hover: null }) + await ctx.fiber.dispose() + }) + + it('rejects a non-utf-16 position encoding at initialize', async () => { + const ctx = await mount({ LSP_FAKE_ENCODING: 'utf-8', LSP_FAKE_DEF: 'null' }) + await expect(ctx.lsp.query(query('definition'))).rejects.toThrow(/unsupported position encoding/) + await ctx.fiber.dispose() + }) + + it('rejects a server without transient-open sync (None)', async () => { + const ctx = await mount({ LSP_FAKE_SYNC: '0', LSP_FAKE_DEF: 'null' }) + await expect(ctx.lsp.query(query('definition'))).rejects.toThrow(/transient textDocument\/didOpen/) + await ctx.fiber.dispose() + }) + + it('accepts openClose options sync', async () => { + const ctx = await mount({ LSP_FAKE_SYNC: JSON.stringify({ openClose: true, change: 2 }), LSP_FAKE_DEF: 'null' }) + expect(await ctx.lsp.query(query('definition'))).toEqual({ kind: 'locations', locations: [] }) + await ctx.fiber.dispose() + }) + + it('fails a query for an unsupported operation', async () => { + const ctx = await mount({ LSP_FAKE_CAPS: JSON.stringify({ hoverProvider: false }), LSP_FAKE_DEF: 'null' }) + await expect(ctx.lsp.query(query('hover'))).rejects.toThrow(/does not support hover/) + await ctx.fiber.dispose() + }) + + it('rejects a source outside the workspace before startup', async () => { + const outside = join(root, 'out.ts') + await writeFile(outside, 'x') + const ctx = await mount({ LSP_FAKE_DEF: 'null' }) + await expect(ctx.lsp.query({ ...query('definition'), filePath: outside })).rejects.toThrow(/outside the workspace/) + await ctx.fiber.dispose() + }) + + it('serializes queries through one instance and runs them in order', async () => { + const ctx = await mount({ LSP_FAKE_DEF: JSON.stringify(locationJson(0)) }) + const results = await Promise.all([ + ctx.lsp.query(query('definition')), + ctx.lsp.query(query('definition')), + ctx.lsp.query(query('definition')), + ]) + for (const result of results) expect(result).toMatchObject({ kind: 'locations' }) + await ctx.fiber.dispose() + }) + + it('aborts an in-flight query when the signal fires', async () => { + const ctx = await mount({ LSP_FAKE_HANG: '1' }) + const controller = new AbortController() + const pending = ctx.lsp.query(query('definition'), controller.signal) + controller.abort(new Error('caller cancelled')) + await expect(pending).rejects.toThrow(/cancelled/) + await ctx.fiber.dispose() + }) + + it('classifies a timeout deadline as the abort reason', async () => { + const ctx = await mount({ LSP_FAKE_HANG: '1' }) + using d = deadline(undefined, 50, 'TEST_TIMEOUT') + await expect(ctx.lsp.query(query('definition'), d.signal)).rejects.toThrow(/TEST_TIMEOUT/) + await ctx.fiber.dispose() + }) + + it('fails the active query when the server crashes on open, and replaces it next query', async () => { + const ctx = await mount({ LSP_FAKE_CRASH_ON_OPEN: '1', LSP_FAKE_DEF: 'null' }, { shutdownTimeoutMs: 100, killGraceMs: 100 }) + await expect(ctx.lsp.query(query('definition'))).rejects.toThrow() + // A later query starts a fresh process; still crashes, but proves the slot was replaced (no hang). + await expect(ctx.lsp.query(query('definition'))).rejects.toThrow() + await ctx.fiber.dispose() + }) + + it('runs distinct workspaces in parallel instances', async () => { + const ws2 = join(root, 'ws2') + await mkdir(ws2) + await writeFile(join(ws2, 'a.ts'), 'const z = 2\n') + const ctx = await mount({ LSP_FAKE_DEF: JSON.stringify(locationJson(0)) }) + const [r1, r2] = await Promise.all([ + ctx.lsp.query({ ...query('definition'), workspaceRoot: ws }), + ctx.lsp.query({ ...query('definition'), workspaceRoot: ws2 }), + ]) + expect(r1).toMatchObject({ kind: 'locations' }) + expect(r2).toMatchObject({ kind: 'locations' }) + await ctx.fiber.dispose() + }) + + it('disposes cleanly, terminating a server that ignores shutdown', async () => { + const ctx = await mount({ LSP_FAKE_NO_SHUTDOWN: '1', LSP_FAKE_DEF: 'null' }, { killGraceMs: 100, shutdownTimeoutMs: 100 }) + await ctx.lsp.query(query('definition')) + await expect(ctx.fiber.dispose()).resolves.toBeUndefined() + }) + + it('rejects at load when the command is not found', async () => { + const ctx = new Context() + await ctx.plugin(Lsp) + await expect(ctx.plugin(LspLocal, { + providerId: 'missing', + command: 'definitely-not-a-real-lsp-binary-xyz', + args: [], + extensionToLanguage: { '.ts': 'typescript' }, + })).rejects.toThrow(/was not found on PATH/) + await ctx.fiber.dispose() + }) +}) diff --git a/packages/lsp/lsp-local/tests/provider.spec.ts b/packages/lsp/lsp-local/tests/provider.spec.ts new file mode 100644 index 0000000000..5d4045f507 --- /dev/null +++ b/packages/lsp/lsp-local/tests/provider.spec.ts @@ -0,0 +1,78 @@ +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { chmod, mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { Context } from 'cordis' +import Lsp, { type LspQueryRequest } from '@deepseek-ai/dsh-lsp' +import * as LspLocal from '@deepseek-ai/dsh-lsp-local' + +let root: string +let ws: string + +beforeEach(async () => { + root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-prov-'))) + ws = join(root, 'ws') + await mkdir(ws) + await writeFile(join(ws, 'a.ts'), 'const x = 1\n') +}) + +afterEach(async () => { + await rm(root, { recursive: true, force: true }) +}) + +function query(): LspQueryRequest { + return { operation: 'definition', filePath: 'a.ts', position: { line: 0, character: 0 }, workspaceRoot: ws } +} + +describe('lsp-local provider resolution', () => { + it('resolves a bare command on the child PATH and registers the provider', async () => { + // A tiny executable script placed on a custom PATH dir: the load-time resolver must find it. + const bin = join(root, 'bin') + await mkdir(bin) + const exe = join(bin, 'fake-lsp') + await writeFile(exe, '#!/bin/sh\nexit 0\n') + await chmod(exe, 0o755) + + const ctx = new Context() + await ctx.plugin(Lsp) + await expect(ctx.plugin(LspLocal, { + providerId: 'onpath', + command: 'fake-lsp', + args: [], + env: { PATH: bin }, + extensionToLanguage: { '.ts': 'typescript' }, + })).resolves.toBeDefined() + await ctx.fiber.dispose() + }) + + it('skips empty PATH segments and fails when the command is absent', async () => { + const ctx = new Context() + await ctx.plugin(Lsp) + await expect(ctx.plugin(LspLocal, { + providerId: 'nope', + command: 'fake-lsp', + args: [], + env: { PATH: `::${join(root, 'empty')}` }, + extensionToLanguage: { '.ts': 'typescript' }, + })).rejects.toThrow(/was not found on PATH/) + await ctx.fiber.dispose() + }) + + it('rejects a query after the provider is disposed', async () => { + // Use a server that never emits results and dispose the plugin, then confirm queries are refused. + const ctx = new Context() + await ctx.plugin(Lsp) + // Grab the provider instance by registering, then dispose the whole plugin fiber. + const lsp = ctx.lsp + const fiber = await ctx.plugin(LspLocal, { + providerId: 'disp', + command: process.execPath, + args: ['-e', 'setInterval(()=>{},1000)'], + extensionToLanguage: { '.ts': 'typescript' }, + }) + await fiber.dispose() + // After disposal the provider unregistered from the seam, so selection fails as unavailable. + await expect(lsp.query(query())).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' })) + await ctx.fiber.dispose() + }) +}) diff --git a/packages/lsp/lsp-local/tests/translate.spec.ts b/packages/lsp/lsp-local/tests/translate.spec.ts new file mode 100644 index 0000000000..2c339075e5 --- /dev/null +++ b/packages/lsp/lsp-local/tests/translate.spec.ts @@ -0,0 +1,153 @@ +import { describe, expect, it } from 'vitest' +import { + negotiatePositionEncoding, + normalizeHover, + normalizeLocations, + requestMethod, + supportsOperation, + supportsTransientOpen, +} from '@deepseek-ai/dsh-lsp-local' +import type { WireServerCapabilities } from '@deepseek-ai/dsh-lsp-local/src/protocol.ts' + +const RANGE = { start: { line: 1, character: 2 }, end: { line: 1, character: 5 } } + +describe('requestMethod', () => { + it('maps each operation to its textDocument request', () => { + expect(requestMethod('definition')).toBe('textDocument/definition') + expect(requestMethod('references')).toBe('textDocument/references') + expect(requestMethod('implementation')).toBe('textDocument/implementation') + expect(requestMethod('hover')).toBe('textDocument/hover') + }) +}) + +describe('supportsOperation', () => { + it('reads the provider slot for each operation (boolean and options forms)', () => { + const caps: WireServerCapabilities = { + definitionProvider: true, + referencesProvider: { workDoneProgress: true }, + implementationProvider: false, + } + expect(supportsOperation(caps, 'definition')).toBe(true) + expect(supportsOperation(caps, 'references')).toBe(true) + expect(supportsOperation(caps, 'implementation')).toBe(false) + expect(supportsOperation(caps, 'hover')).toBe(false) + }) +}) + +describe('supportsTransientOpen', () => { + it('accepts legacy Full and Incremental enums, rejects None and absent', () => { + expect(supportsTransientOpen(1)).toBe(true) + expect(supportsTransientOpen(2)).toBe(true) + expect(supportsTransientOpen(0)).toBe(false) + expect(supportsTransientOpen(undefined)).toBe(false) + }) + + it('accepts options with openClose:true and rejects openClose:false', () => { + expect(supportsTransientOpen({ openClose: true })).toBe(true) + expect(supportsTransientOpen({ openClose: false, change: 2 })).toBe(false) + }) + + it('falls back to the change enum when openClose is omitted', () => { + expect(supportsTransientOpen({ change: 1 })).toBe(true) + expect(supportsTransientOpen({ change: 0 })).toBe(false) + expect(supportsTransientOpen({})).toBe(false) + }) +}) + +describe('negotiatePositionEncoding', () => { + it('defaults an omitted encoding to utf-16', () => { + expect(negotiatePositionEncoding(undefined)).toBe('utf-16') + expect(negotiatePositionEncoding('utf-16')).toBe('utf-16') + }) + + it('rejects any other encoding', () => { + expect(() => negotiatePositionEncoding('utf-8')).toThrow(/unsupported position encoding/) + }) +}) + +describe('normalizeLocations', () => { + it('returns empty for null and undefined', () => { + expect(normalizeLocations(null)).toEqual([]) + expect(normalizeLocations(undefined)).toEqual([]) + }) + + it('maps a single Location', () => { + expect(normalizeLocations({ uri: 'file:///a', range: RANGE })).toEqual([{ uri: 'file:///a', range: RANGE }]) + }) + + it('maps an array of Locations', () => { + const result = normalizeLocations([{ uri: 'file:///a', range: RANGE }, { uri: 'file:///b', range: RANGE }]) + expect(result.map(l => l.uri)).toEqual(['file:///a', 'file:///b']) + }) + + it('maps a LocationLink from targetUri + targetSelectionRange', () => { + const link = { targetUri: 'file:///c', targetSelectionRange: RANGE, targetRange: RANGE } + expect(normalizeLocations([link])).toEqual([{ uri: 'file:///c', range: RANGE }]) + }) + + it('rejects a non-object entry', () => { + expect(() => normalizeLocations([42])).toThrow(/non-object/) + }) + + it('rejects an entry that is neither a Location nor a LocationLink', () => { + expect(() => normalizeLocations([{ nope: true }])).toThrow(/neither a Location nor a LocationLink/) + }) + + it('rejects a Location whose range is not an object', () => { + expect(() => normalizeLocations([{ uri: 'file:///a', range: 'nope' }])).toThrow(/neither a Location/) + }) + + it('rejects a Location whose range positions are malformed', () => { + expect(() => normalizeLocations([{ uri: 'file:///a', range: { start: null, end: null } }])).toThrow(/neither a Location/) + }) +}) + +describe('normalizeHover', () => { + it('returns null for null', () => { + expect(normalizeHover(null)).toBeNull() + }) + + it('reads MarkupContent value and keeps a range', () => { + expect(normalizeHover({ contents: { kind: 'markdown', value: '# H' }, range: RANGE })) + .toEqual({ contents: '# H', range: RANGE }) + }) + + it('keeps a bare string MarkedString verbatim', () => { + expect(normalizeHover({ contents: 'plain text' })).toEqual({ contents: 'plain text' }) + }) + + it('renders a language-tagged MarkedString object as a fenced code block', () => { + expect(normalizeHover({ contents: { language: 'ts', value: 'const x = 1' } })) + .toEqual({ contents: '```ts\nconst x = 1\n```' }) + }) + + it('joins a MarkedString array with one blank line', () => { + expect(normalizeHover({ contents: ['a', { language: 'ts', value: 'b' }] })) + .toEqual({ contents: 'a\n\n```ts\nb\n```' }) + }) + + it('drops an empty-contents hover to null', () => { + expect(normalizeHover({ contents: { kind: 'plaintext', value: '' } })).toBeNull() + }) + + it('treats a MarkupContent with a non-string value as empty (null)', () => { + expect(normalizeHover({ contents: { kind: 'markdown', value: 42 } })).toBeNull() + }) + + it('rejects a non-object payload', () => { + expect(() => normalizeHover(42)).toThrow(/was not an object/) + }) + + it('rejects malformed contents', () => { + expect(() => normalizeHover({ contents: { weird: true } })).toThrow(/were not MarkupContent/) + expect(() => normalizeHover({ contents: 42 })).toThrow(/were not MarkupContent/) + }) + + it('rejects a hover with no contents field', () => { + expect(() => normalizeHover({ range: RANGE })).toThrow(/no contents/) + }) + + it('ignores a malformed range and keeps the contents', () => { + expect(normalizeHover({ contents: 'x', range: { start: { line: 1 } } })).toEqual({ contents: 'x' }) + }) +}) diff --git a/packages/lsp/lsp-local/tests/typescript-server.e2e.ts b/packages/lsp/lsp-local/tests/typescript-server.e2e.ts new file mode 100644 index 0000000000..ca4df620d3 --- /dev/null +++ b/packages/lsp/lsp-local/tests/typescript-server.e2e.ts @@ -0,0 +1,111 @@ +/** + * Keyless real-server e2e: drives the real `typescript-language-server` through the full + * `ctx.lsp` → `dsh-lsp-local` stack over the base protocol, exercising all four operations. No API + * key needed — the server is a local dev dependency. This establishes one compatibility floor + * (TypeScript), not a cross-language claim. + */ + +import { afterAll, beforeAll, describe, expect, it } from 'vitest' +import { mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { Context } from 'cordis' +import Lsp, { type LspQueryRequest, type LspQueryResult } from '@deepseek-ai/dsh-lsp' +import * as LspLocal from '@deepseek-ai/dsh-lsp-local' + +// The server binary is a dev dependency of this package; resolve its pnpm-hoisted .bin path. +const serverBin = join( + new URL('..', import.meta.url).pathname, + 'node_modules', + '.bin', + 'typescript-language-server', +) + +let root: string +let ws: string +let ctx: Context + +beforeAll(async () => { + root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-ts-e2e-'))) + ws = join(root, 'proj') + await mkdir(ws) + await writeFile(join(ws, 'tsconfig.json'), JSON.stringify({ compilerOptions: { strict: true, module: 'nodenext' } })) + // A small program with a definition, a reference, an interface + implementation, and a typed value. + await writeFile(join(ws, 'shapes.ts'), [ + 'export interface Shape {', + ' area(): number', + '}', + '', + 'export class Circle implements Shape {', + ' constructor(private r: number) {}', + ' area(): number { return Math.PI * this.r * this.r }', + '}', + '', + 'export function describe(s: Shape): string {', + ' return `area=${s.area()}`', + '}', + '', + 'const c = new Circle(2)', + 'export const text = describe(c)', + '', + ].join('\n')) + + ctx = new Context() + await ctx.plugin(Lsp) + await ctx.plugin(LspLocal, { + providerId: 'typescript', + command: serverBin, + args: ['--stdio'], + extensionToLanguage: { '.ts': 'typescript', '.tsx': 'typescriptreact' }, + }) +}, 60_000) + +afterAll(async () => { + if (ctx) await ctx.fiber.dispose() + if (root) await rm(root, { recursive: true, force: true }) +}) + +/** One-based helper mirroring the model contract, converted to the seam's zero-based position. */ +function at(operation: LspQueryRequest['operation'], line1: number, char1: number, filePath = 'shapes.ts'): LspQueryRequest { + return { operation, filePath, position: { line: line1 - 1, character: char1 - 1 }, workspaceRoot: ws } +} + +function locations(result: LspQueryResult): readonly { uri: string }[] { + if (result.kind !== 'locations') throw new Error(`expected locations, got ${result.kind}`) + return result.locations +} + +describe('real typescript-language-server', () => { + it('resolves the definition of a call site to its declaration', async () => { + // `export const text = describe(c)` (line 15): `describe` begins at column 21. + const result = await ctx.lsp.query(at('definition', 15, 22)) + const locs = locations(result) + expect(locs.length).toBeGreaterThanOrEqual(1) + expect(locs.some(l => l.uri.endsWith('shapes.ts'))).toBe(true) + }, 60_000) + + it('finds references to a symbol including its declaration', async () => { + // References to `describe` from its declaration (line 10, col 17). + const result = await ctx.lsp.query(at('references', 10, 17)) + const locs = locations(result) + // At least the declaration plus the call site. + expect(locs.length).toBeGreaterThanOrEqual(2) + }, 60_000) + + it('resolves implementations of an interface', async () => { + // Implementations of `Shape` (line 1, col 18) → Circle. + const result = await ctx.lsp.query(at('implementation', 1, 18)) + const locs = locations(result) + expect(locs.length).toBeGreaterThanOrEqual(1) + }, 60_000) + + it('returns hover information for a typed symbol', async () => { + // Hover on `Circle` in `new Circle(2)` (line 14, col 15). + const result = await ctx.lsp.query(at('hover', 14, 15)) + expect(result.kind).toBe('hover') + if (result.kind === 'hover') { + expect(result.hover).not.toBeNull() + expect(result.hover?.contents).toContain('Circle') + } + }, 60_000) +}) diff --git a/packages/lsp/lsp-local/tsconfig.json b/packages/lsp/lsp-local/tsconfig.json new file mode 100644 index 0000000000..281a8cebbf --- /dev/null +++ b/packages/lsp/lsp-local/tsconfig.json @@ -0,0 +1,33 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../../vendor/schemastery" + }, + { + "path": "../../util/brand" + }, + { + "path": "../../util/timeout" + }, + { + "path": "../../llm/llm" + }, + { + "path": "../lsp" + } + ] +} diff --git a/packages/lsp/lsp/README.md b/packages/lsp/lsp/README.md new file mode 100644 index 0000000000..eac45e9f51 --- /dev/null +++ b/packages/lsp/lsp/README.md @@ -0,0 +1,38 @@ +# @deepseek-ai/dsh-lsp + +The **LSP capability seam**: an abstract `LspService` (`ctx.lsp`) defining WHAT semantic code navigation the harness has — go to definition, find references, find implementations, hover — over language-server providers, without binding the model contract to local subprocesses. + +This package is the interface third of the LSP capability: + +| Package | Role | +|---|---| +| `@deepseek-ai/dsh-lsp` (this) | the interface: the service, provider registry keyed by branded id + extension mapping, per-query selection, request/result vocabulary, the `LspError` taxonomy | +| `@deepseek-ai/dsh-lsp-local` | a generic stdio language-server provider | +| `@deepseek-ai/dsh-tool-lsp` | the model-facing `lsp` tool over `ctx.lsp` | + +The seam exposes exactly four semantic operations — `definition`, `references`, `implementation`, `hover` — and no generic JSON-RPC escape hatch, so no protocol payload or unreviewed command/mutation reaches a provider through `ctx.lsp`. + +## Service API (`ctx.lsp`) + +| Member | Semantics | +|---|---| +| `registerProvider(provider)` | Register a backend, atomically reserving its branded `id` and every normalized file extension. Any invalid input or conflict publishes nothing and throws `LspError` (`LSP_INVALID_PROVIDER` / `LSP_CONFLICT`). Returns a disposer releasing all reservations. Disposed with the calling fiber. | +| `query(request, signal?)` | Select the provider by the file's final extension, derive the `languageId` from that provider's mapping, and run one query. No match throws `LspError` `LSP_UNAVAILABLE`. | + +Selection is per query and order-independent: a provider owns a set of extensions exclusively, so registration and HMR order never change routing. Extension keys normalize to lowercase, leading-dot form; the `languageId` only synchronizes the transient document, never participates in selection. The first version has no glob, language-id, or explicit route selector. + +Providers register **capabilities**, not tools. `dsh-tool-lsp` is the only owner of the model-facing name, description, prompt guidance, schema, and presentation. + +## Vocabulary + +`LspQueryRequest` (`operation`, `filePath`, `position`, `workspaceRoot`) — every field required, so no field needs implementation defaulting and there is no `resolve()` step. Positions and ranges are zero-based UTF-16, matching the protocol; the tool owns the one-based cursor convention. `references` always includes declarations — providers enforce this internally, so callers get no flag. `LspQueryResult` is a CLOSED discriminated union: `{ kind: 'locations'; locations }` for navigation, `{ kind: 'hover'; hover }` for hover (content or `null`) — consumers `switch` to exhaustiveness so a new arm breaks compilation until handled. See `src/types.ts` for the full contracts and `src/index.ts` for the `LspError` codes. + +## Model Experience + +Indirectly, through `dsh-tool-lsp`, which owns the model-facing `lsp` schema, prompt, and rendered results while this registry contributes no prompt or schema itself. + +## Known Limitations and Deferred Work + +- **Exclusive extension ownership within one runtime** — two providers cannot both claim `.ts`, even with different language ids; overlaps fail registration. The intended extension is a deployment-configured selector above registrations, which can relax exclusive reservation without adding provider choice to model input ([seam RFC](../../../docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md)). +- **Four operations only** — symbols and call hierarchy are deferred (they need different schemas); diagnostics need separate freshness/accumulation rules; mutations (rename, code actions, formatting) require separate tools with preview, permission, and write-policy integration. +- **No observation surface** — availability is observed only by running `query()` and routing the thrown `LspError` codes; there is no provider-change event or capability-status query. diff --git a/packages/lsp/lsp/package.json b/packages/lsp/lsp/package.json new file mode 100644 index 0000000000..04de5b2506 --- /dev/null +++ b/packages/lsp/lsp/package.json @@ -0,0 +1,34 @@ +{ + "name": "@deepseek-ai/dsh-lsp", + "description": "Abstract LSP capability seam (ctx.lsp) for the DeepSeek Harness — language-server provider registry keyed by branded id and extension mapping, order-independent per-query selection, normalized definition/references/implementation/hover requests and results, and the LspError taxonomy", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-brand": "^0.0.1", + "@deepseek-ai/dsh-llm": "^0.0.1", + "cordis": "^4.0.0-rc.7" + }, + "devDependencies": { + "@deepseek-ai/dsh-brand": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "cordis": "^4.0.0-rc.7" + } +} diff --git a/packages/lsp/lsp/src/brand.ts b/packages/lsp/lsp/src/brand.ts new file mode 100644 index 0000000000..fe51a1ea00 --- /dev/null +++ b/packages/lsp/lsp/src/brand.ts @@ -0,0 +1,21 @@ +/** + * dsh-lsp's owned branded id: {@link LspProviderId}, the opaque identity a provider reserves on + * `ctx.lsp`. The `Branded` primitive lives in `@deepseek-ai/dsh-brand`; keeping the type and its + * factory together here lets `index.ts` re-export both under one name. + * @module @deepseek-ai/dsh-lsp/brand + */ + +import type { Branded } from '@deepseek-ai/dsh-brand' + +/** Opaque provider identity, reserved atomically with its extension mappings at registration. */ +export type LspProviderId = Branded<'LspProviderId'> + +/** + * Brand a string as an {@link LspProviderId}. No validation — the registry rejects an empty id at + * registration. + * @param id - the provider's stable identifier. + * @returns the same string, branded. + */ +export function LspProviderId(id: string): LspProviderId { + return id as LspProviderId +} diff --git a/packages/lsp/lsp/src/index.ts b/packages/lsp/lsp/src/index.ts new file mode 100644 index 0000000000..e00005acde --- /dev/null +++ b/packages/lsp/lsp/src/index.ts @@ -0,0 +1,156 @@ +/** + * The LSP capability seam (`ctx.lsp`): a language-server provider registry and per-query, + * order-independent selection over normalized definition/references/implementation/hover queries. + * + * A provider reserves a branded id and an exclusive set of file extensions atomically: + * {@link Lsp.registerProvider} validates and conflict-checks everything before mutating, so an + * invalid or conflicting registration publishes nothing, and its disposer releases every + * reservation together. Selection routes a query by the file's final extension; it never depends on + * registration order. The seam exposes exactly the four operations and no JSON-RPC escape hatch. + * @module @deepseek-ai/dsh-lsp + */ + +import { Context, Service } from 'cordis' +import { HarnessError } from '@deepseek-ai/dsh-llm' +import type { LspProviderId } from './brand.ts' +import type { + LspProvider, + LspQueryRequest, + LspQueryResult, + LspService, +} from './types.ts' + +export { LspProviderId } from './brand.ts' +export type { + LspHover, + LspLocation, + LspOperation, + LspPosition, + LspProvider, + LspProviderQuery, + LspQueryRequest, + LspQueryResult, + LspRange, + LspService, +} from './types.ts' + +declare module 'cordis' { + interface Context { + lsp: LspService + } +} + +/** + * Structured LSP failure. Extends {@link HarnessError} with a stable `code` + * (`LSP_INVALID_PROVIDER`, `LSP_CONFLICT`, `LSP_UNAVAILABLE`, `LSP_UNSUPPORTED_OPERATION`, …) that + * callers route on instead of parsing `message`. + */ +export class LspError extends HarnessError {} + +/** + * Extract a file's final extension as a normalized, lowercase, leading-dot key (e.g. `Foo.TS` → + * `.ts`, `foo.d.ts` → `.ts`). Returns `''` for a name with no extension or a leading-dot dotfile + * (`.bashrc`), which no route ever matches. Splits on both `/` and `\` so a caller's path separator + * does not change the result. + * @param filePath - the source path to inspect. + * @returns the normalized extension, or `''` when there is none. + */ +export function finalExtension(filePath: string): string { + const lastSlash = Math.max(filePath.lastIndexOf('/'), filePath.lastIndexOf('\\')) + const base = lastSlash >= 0 ? filePath.slice(lastSlash + 1) : filePath + const dot = base.lastIndexOf('.') + // dot <= 0 covers both "no dot" (-1) and a leading-dot dotfile (0): neither has an extension. + if (dot <= 0) return '' + return base.slice(dot).toLowerCase() +} + +/** A well-formed normalized extension: a dot followed by one or more non-dot, non-separator chars. */ +const EXTENSION_PATTERN = /^\.[^./\\]+$/ + +/** One selection route: the provider to run plus the language id to synchronize the document with. */ +interface Route { + readonly provider: LspProvider + readonly languageId: string +} + +/** + * `ctx.lsp`. Holds the id reservations and the extension→route table; both are populated and cleared + * together per provider so a route always has a live provider. + */ +export class Lsp extends Service implements LspService { + private readonly providerIds = new Set() + private readonly routes = new Map() + + constructor(ctx: Context) { + super(ctx, 'lsp') + } + + registerProvider(provider: LspProvider): () => void { + // Validate and conflict-check everything BEFORE any mutation: an invalid or conflicting + // registration must publish nothing (fail-loud, all-or-nothing). + const id = provider.id + if (id.trim() === '') { + throw new LspError('an LSP provider id must be a non-empty string', 'LSP_INVALID_PROVIDER') + } + if (this.providerIds.has(id)) { + throw new LspError(`an LSP provider with id "${id}" is already registered`, 'LSP_CONFLICT') + } + + const entries = Object.entries(provider.extensionToLanguage) + if (entries.length === 0) { + throw new LspError(`LSP provider "${id}" registers no file extensions`, 'LSP_INVALID_PROVIDER') + } + + // Normalize into this provider's route set, catching intra-provider duplicates (e.g. `.TS` and + // `.ts`) before checking cross-provider conflicts. + const pending = new Map() + for (const [rawExt, languageId] of entries) { + const ext = normalizeExtension(rawExt) + if (!EXTENSION_PATTERN.test(ext)) { + throw new LspError(`LSP provider "${id}" maps an invalid extension "${rawExt}"`, 'LSP_INVALID_PROVIDER') + } + if (languageId.trim() === '') { + throw new LspError(`LSP provider "${id}" maps extension "${ext}" to an empty language id`, 'LSP_INVALID_PROVIDER') + } + if (pending.has(ext)) { + throw new LspError(`LSP provider "${id}" maps extension "${ext}" more than once`, 'LSP_INVALID_PROVIDER') + } + pending.set(ext, { provider, languageId }) + } + for (const ext of pending.keys()) { + if (this.routes.has(ext)) { + throw new LspError(`extension "${ext}" is already handled by another LSP provider`, 'LSP_CONFLICT') + } + } + + // All checks passed: reserve id and every extension in one lifecycle controller so disposal + // releases them together. + const dispose = this.ctx.effect(function* (this: Lsp) { + this.providerIds.add(id) + for (const [ext, route] of pending) this.routes.set(ext, route) + yield () => { + this.providerIds.delete(id) + for (const ext of pending.keys()) this.routes.delete(ext) + } + }.bind(this), 'lsp.registerProvider()') + // ctx.effect's disposer returns Promise; our disposer API is synchronous + // fire-and-forget — discard the (always-resolved) promise. + return () => void dispose() + } + + async query(request: LspQueryRequest, signal?: AbortSignal): Promise { + const route = this.routes.get(finalExtension(request.filePath)) + if (route === undefined) { + throw new LspError(`no LSP provider handles "${request.filePath}"`, 'LSP_UNAVAILABLE') + } + return route.provider.query({ ...request, languageId: route.languageId }, signal) + } +} + +/** Lowercase an extension and ensure it carries a leading dot; `EXTENSION_PATTERN` rejects the rest. */ +function normalizeExtension(ext: string): string { + const lower = ext.toLowerCase() + return lower.startsWith('.') ? lower : `.${lower}` +} + +export default Lsp diff --git a/packages/lsp/lsp/src/types.ts b/packages/lsp/lsp/src/types.ts new file mode 100644 index 0000000000..0a2d73fac1 --- /dev/null +++ b/packages/lsp/lsp/src/types.ts @@ -0,0 +1,124 @@ +/** + * LSP seam vocabulary: the normalized request, provider, and result contracts. Types only — the + * {@link LspError} taxonomy and the {@link LspProviderId} brand factory are runtime and live in + * `index.ts`. Positions and ranges are zero-based UTF-16, matching the protocol; the model-facing + * tool owns the one-based cursor convention. The seam exposes no protocol types, process or document + * controls, or generic JSON-RPC escape hatch — only the four semantic operations. + * @module @deepseek-ai/dsh-lsp/types + */ + +import type { LspProviderId } from './brand.ts' + +/** + * The four semantic queries the seam and model expose. A closed union: adding an operation is a + * compile-enforced change across the seam, providers, and the tool. Symbols and call hierarchy are + * deliberately deferred (they need different schemas). + */ +export type LspOperation = 'definition' | 'references' | 'implementation' | 'hover' + +/** A zero-based UTF-16 cursor coordinate, matching the LSP wire convention. */ +export interface LspPosition { + /** Zero-based line. */ + readonly line: number + /** Zero-based UTF-16 code-unit offset within the line. */ + readonly character: number +} + +/** A zero-based UTF-16 half-open range `[start, end)`. */ +export interface LspRange { + readonly start: LspPosition + readonly end: LspPosition +} + +/** + * A caller's normalized query. Every field is required: `workspaceRoot` is caller-supplied, + * `languageId` comes from the provider registration (not here), and consumers own timeouts and + * result limits — so no field needs implementation defaulting and there is no `resolve()` step. + */ +export interface LspQueryRequest { + /** Which semantic query to run. */ + readonly operation: LspOperation + /** The source file to query (relative to `workspaceRoot` or absolute; the provider canonicalizes). */ + readonly filePath: string + /** The zero-based UTF-16 cursor position to query at. */ + readonly position: LspPosition + /** The workspace root the provider resolves against and indexes; required, never defaulted. */ + readonly workspaceRoot: string +} + +/** + * A request as a provider receives it: the caller's {@link LspQueryRequest} plus the `languageId` + * the seam derived from the provider's extension mapping. The language id only synchronizes the + * transient document; it does not participate in selection. + */ +export interface LspProviderQuery extends LspQueryRequest { + /** The LSP language id for `filePath`, from this provider's extension mapping. */ + readonly languageId: string +} + +/** One resolved location: a document URI and the range within it. */ +export interface LspLocation { + /** The target document URI (`file:` or otherwise), verbatim from the server. */ + readonly uri: string + /** The range within the target document. */ + readonly range: LspRange +} + +/** Normalized hover content, or `null` for no hover at the position. */ +export interface LspHover { + /** The normalized hover text (markdown or plaintext, provider-joined). */ + readonly contents: string + /** The range the hover applies to, when the server supplied one. */ + readonly range?: LspRange +} + +/** + * The closed result union. Navigation operations (`definition`, `references`, `implementation`) + * normalize to `locations`; `hover` normalizes to content or `null`. Consumers `switch` on `kind` + * to exhaustiveness so a new arm breaks compilation until handled. + */ +export type LspQueryResult = + | { readonly kind: 'locations'; readonly locations: readonly LspLocation[] } + | { readonly kind: 'hover'; readonly hover: LspHover | null } + +/** + * A language-server backend registered on `ctx.lsp`. Each provider owns a stable {@link + * LspProviderId} and an extension-to-language-id map (lowercase, leading-dot keys). `references` + * always includes declarations — the provider enforces this internally; callers get no flag. + */ +export interface LspProvider { + /** Stable provider identity, reserved atomically with the extension mappings. */ + readonly id: LspProviderId + /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */ + readonly extensionToLanguage: Readonly> + /** + * Run one query. The seam has already selected this provider and derived `languageId`. + * @param request - the resolved provider query (caller request + derived language id). + * @param signal - optional cancellation; the provider stops its own work when it aborts. + * @returns the normalized, closed-union result. + */ + query(request: LspProviderQuery, signal?: AbortSignal): Promise +} + +/** + * The LSP capability seam (`ctx.lsp`). Owns provider registration/selection and normalized query + * execution; exposes exactly the four operations and no protocol escape hatch. + */ +export interface LspService { + /** + * Register a provider, atomically reserving its id and every normalized extension. Any conflict + * or invalid input publishes nothing and throws `LspError`; the returned disposer releases all + * reservations. Disposed with the calling fiber. + * @param provider - the backend to register. + * @returns a synchronous disposer releasing the id and all extension reservations. + */ + registerProvider(provider: LspProvider): () => void + /** + * Select a provider by the file's extension and run one query. Selection is per-query and + * order-independent; no match throws `LspError` `LSP_UNAVAILABLE`. + * @param request - the normalized query. + * @param signal - optional cancellation forwarded to the selected provider. + * @returns the normalized, closed-union result. + */ + query(request: LspQueryRequest, signal?: AbortSignal): Promise +} diff --git a/packages/lsp/lsp/tests/lsp.spec.ts b/packages/lsp/lsp/tests/lsp.spec.ts new file mode 100644 index 0000000000..6746a05dc3 --- /dev/null +++ b/packages/lsp/lsp/tests/lsp.spec.ts @@ -0,0 +1,187 @@ +import { describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import Lsp, { + finalExtension, + LspError, + LspProviderId, + type LspProvider, + type LspProviderQuery, + type LspQueryResult, +} from '@deepseek-ai/dsh-lsp' + +/** A scripted provider that records the queries it receives. */ +function makeProvider( + id: string, + extensionToLanguage: Record, + result: LspQueryResult = { kind: 'locations', locations: [] }, +): LspProvider & { seen: LspProviderQuery[]; seenSignals: (AbortSignal | undefined)[] } { + const seen: LspProviderQuery[] = [] + const seenSignals: (AbortSignal | undefined)[] = [] + return { + id: LspProviderId(id), + extensionToLanguage, + seen, + seenSignals, + query(request, signal) { + seen.push(request) + seenSignals.push(signal) + return Promise.resolve(result) + }, + } +} + +/** Mount an Lsp service on a fresh root context. */ +async function mountLsp(): Promise<{ ctx: Context; lsp: Lsp }> { + const ctx = new Context() + await ctx.plugin(Lsp) + return { ctx, lsp: ctx.lsp as Lsp } +} + +const hover: LspQueryResult = { kind: 'hover', hover: { contents: 'x' } } + +function query(filePath: string, operation: LspProviderQuery['operation'] = 'definition'): Parameters[0] { + return { operation, filePath, position: { line: 0, character: 0 }, workspaceRoot: '/ws' } +} + +describe('finalExtension', () => { + it('lowercases and keeps only the final extension', () => { + expect(finalExtension('src/Foo.TS')).toBe('.ts') + expect(finalExtension('a/b/foo.d.ts')).toBe('.ts') + expect(finalExtension('C:\\proj\\Main.CS')).toBe('.cs') + }) + + it('returns empty for no extension or a leading-dot dotfile', () => { + expect(finalExtension('Makefile')).toBe('') + expect(finalExtension('.bashrc')).toBe('') + expect(finalExtension('dir.d/file')).toBe('') + }) +}) + +describe('Lsp registration', () => { + it('registers a provider and routes a query to it, then releases on dispose', async () => { + const { lsp } = await mountLsp() + const provider = makeProvider('ts', { '.ts': 'typescript' }) + const dispose = lsp.registerProvider(provider) + + await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [] }) + expect(provider.seen[0]).toMatchObject({ filePath: 'a.ts', languageId: 'typescript' }) + + dispose() + await expect(lsp.query(query('a.ts'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' })) + }) + + it('normalizes extension keys to lowercase leading-dot and derives the language id', async () => { + const { lsp } = await mountLsp() + const provider = makeProvider('ts', { TS: 'typescript' }) + lsp.registerProvider(provider) + await lsp.query(query('a.ts')) + expect(provider.seen[0]?.languageId).toBe('typescript') + }) + + it('rejects an empty provider id (LSP_INVALID_PROVIDER)', async () => { + const { lsp } = await mountLsp() + expect(() => lsp.registerProvider(makeProvider(' ', { '.ts': 'typescript' }))) + .toThrow(expect.objectContaining({ code: 'LSP_INVALID_PROVIDER' })) + }) + + it('rejects a provider with no extensions (LSP_INVALID_PROVIDER)', async () => { + const { lsp } = await mountLsp() + expect(() => lsp.registerProvider(makeProvider('ts', {}))) + .toThrow(expect.objectContaining({ code: 'LSP_INVALID_PROVIDER' })) + }) + + it('rejects an invalid extension mapping (LSP_INVALID_PROVIDER)', async () => { + const { lsp } = await mountLsp() + expect(() => lsp.registerProvider(makeProvider('ts', { '.tar.gz': 'archive' }))) + .toThrow(expect.objectContaining({ code: 'LSP_INVALID_PROVIDER' })) + }) + + it('rejects an empty language id (LSP_INVALID_PROVIDER)', async () => { + const { lsp } = await mountLsp() + expect(() => lsp.registerProvider(makeProvider('ts', { '.ts': ' ' }))) + .toThrow(expect.objectContaining({ code: 'LSP_INVALID_PROVIDER' })) + }) + + it('rejects an extension mapped twice within one provider (LSP_INVALID_PROVIDER)', async () => { + const { lsp } = await mountLsp() + expect(() => lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript', TS: 'ts2' }))) + .toThrow(expect.objectContaining({ code: 'LSP_INVALID_PROVIDER' })) + }) + + it('rejects a duplicate provider id (LSP_CONFLICT)', async () => { + const { lsp } = await mountLsp() + lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript' })) + expect(() => lsp.registerProvider(makeProvider('ts', { '.tsx': 'typescriptreact' }))) + .toThrow(expect.objectContaining({ code: 'LSP_CONFLICT' })) + }) + + it('rejects an extension already owned by another provider (LSP_CONFLICT)', async () => { + const { lsp } = await mountLsp() + lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript' })) + expect(() => lsp.registerProvider(makeProvider('other', { '.ts': 'other-lang' }))) + .toThrow(expect.objectContaining({ code: 'LSP_CONFLICT' })) + }) + + it('publishes nothing when a later extension conflicts (atomic reservation)', async () => { + const { lsp } = await mountLsp() + lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript' })) + // This provider's `.py` is free but `.ts` conflicts: the whole registration must roll back. + expect(() => lsp.registerProvider(makeProvider('py-ts', { '.py': 'python', '.ts': 'x' }))) + .toThrow(expect.objectContaining({ code: 'LSP_CONFLICT' })) + // `.py` must NOT have been reserved. + await expect(lsp.query(query('a.py'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' })) + }) + + it('releases every extension and the id together on dispose', async () => { + const { lsp } = await mountLsp() + const dispose = lsp.registerProvider(makeProvider('multi', { '.ts': 'typescript', '.tsx': 'typescriptreact' })) + dispose() + await expect(lsp.query(query('a.ts'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' })) + await expect(lsp.query(query('a.tsx'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' })) + // The id is free again after release. + expect(() => lsp.registerProvider(makeProvider('multi', { '.ts': 'typescript' }))).not.toThrow() + }) + + it('selection is order-independent across two providers', async () => { + const { lsp } = await mountLsp() + const ts = makeProvider('ts', { '.ts': 'typescript' }, hover) + const py = makeProvider('py', { '.py': 'python' }) + lsp.registerProvider(ts) + lsp.registerProvider(py) + await expect(lsp.query(query('a.py'))).resolves.toEqual({ kind: 'locations', locations: [] }) + await expect(lsp.query(query('a.ts', 'hover'))).resolves.toEqual(hover) + }) + + it('forwards the abort signal verbatim to the provider', async () => { + const { lsp } = await mountLsp() + const provider = makeProvider('ts', { '.ts': 'typescript' }) + lsp.registerProvider(provider) + const controller = new AbortController() + await lsp.query(query('a.ts'), controller.signal) + expect(provider.seenSignals[0]).toBe(controller.signal) + }) + + it('fails LSP_UNAVAILABLE when no provider handles the extension', async () => { + const { lsp } = await mountLsp() + lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript' })) + await expect(lsp.query(query('a.py'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' })) + }) + + it('disposes provider registrations when the contributing fiber is disposed (HMR safety)', async () => { + const { ctx, lsp } = await mountLsp() + const fiber = await ctx.plugin(Object.assign((inner: Context) => { + inner.lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript' })) + }, { inject: ['lsp'] })) + await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [] }) + await fiber.dispose() + await expect(lsp.query(query('a.ts'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' })) + }) + + it('LspError carries its structured code', () => { + expect(new LspError('m', 'LSP_UNAVAILABLE').code).toBe('LSP_UNAVAILABLE') + }) + + it('brands a provider id without altering the string', () => { + expect(LspProviderId('ts')).toBe('ts') + }) +}) diff --git a/packages/lsp/lsp/tsconfig.json b/packages/lsp/lsp/tsconfig.json new file mode 100644 index 0000000000..7ca1556695 --- /dev/null +++ b/packages/lsp/lsp/tsconfig.json @@ -0,0 +1,24 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../util/brand" + }, + { + "path": "../../llm/llm" + } + ] +} diff --git a/packages/lsp/tool-lsp/README.md b/packages/lsp/tool-lsp/README.md new file mode 100644 index 0000000000..fdbd89d96b --- /dev/null +++ b/packages/lsp/tool-lsp/README.md @@ -0,0 +1,56 @@ +# @deepseek-ai/dsh-tool-lsp + +The model-facing **`lsp` tool** over `ctx.lsp`: one read-only tool with four operations for precise code navigation. It owns the model schema, prompt guidance, coordinate conversion, result limits and formatting, and ACP presentation; it imports no provider. + +Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export). Injects `tools`, `lsp`, and `systemPrompt`. + +## The tool + +`lsp` accepts `operation` (`definition` | `references` | `implementation` | `hover`), `file_path`, `line`, and `character`. `line` and `character` are positive, one-based UTF-16 cursor coordinates; the tool converts them to the seam's zero-based positions and converts rendered locations back. `references` includes declarations so impact analysis does not omit the defining site. Provider, language id, workspace root, limits, timeout, initialization, and executable stay outside model input. + +The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Locations render as stable, file-grouped `path:line:character` entries; a `file:` URI becomes a workspace-relative path (inside) or absolute path (outside), and any other URI stays verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors. + +## Configuration + +| Key | Default | Meaning | +|---|---|---| +| `maxLocations` | `100` | Largest number of rendered locations before an omission marker. | +| `maxHoverChars` | `16000` | Largest hover length in characters, applied after normalization. | +| `timeoutMs` | `60000` | Tool-call timeout budget, enforced by `dsh-timeout-policy`; covers the complete queued open/query/close lifecycle and is not model-configurable. | + +## Model Experience + +### Prompt guidance + +**What the model sees**: One system-prompt section (order 112) positioning LSP as a precision aid, plus the tool schema below. + +**Token effect**: Fixed — the verbatim prose below is contributed once per request while the tool is enabled. + +#### Verbatim text for this context surface + +```markdown +Use search/read for ordinary navigation. Use lsp when textual matches are ambiguous or before a change requires precise definitions, implementations, or references. Positions are one-based line and character (UTF-16) at the cursor; an off-symbol position may return no results. references always includes the declaration. +``` + +### Tool schema + +**What the model sees**: The model sees the generated [`lsp` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-lsp). + +**Token effect**: Fixed per request while enabled; the `timeoutMs` budget is never sent to the model. + +### Results + +**What the model sees**: File-grouped `path:line:character` location lines, or normalized hover text; capped by `maxLocations` / `maxHoverChars` with an omission marker when truncated, and distinct `No results.` / `No hover information.` lines for empty results. + +**Token effect**: Capped by the two limits above. + +### ACP presentation + +**What the model sees**: A generic search card — `{ card: 'generic', kind: 'search', title, locations: [{ path, line }] }` — whose args-derived title carries the operation and one-based cursor; follow-along focuses the queried line while the title preserves the column. Rendered by the client, not sent to the model. + +**Token effect**: Zero direct token effect (client-side rendering only). + +## Known Limitations and Deferred Work + +- **UTF-16 cursor coordinates** — columns are exact for the protocol but hard for a model to count around non-BMP characters; an off-symbol position may return empty results, so the prompt explains the convention without encouraging broad LSP use ([seam RFC](../../../docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md)). +- **No cross-server completeness promise** — supported servers may return empty or partial results depending on indexing readiness; the tool promises no completeness across languages or servers. diff --git a/packages/lsp/tool-lsp/package.json b/packages/lsp/tool-lsp/package.json new file mode 100644 index 0000000000..4559bbd1b5 --- /dev/null +++ b/packages/lsp/tool-lsp/package.json @@ -0,0 +1,45 @@ +{ + "name": "@deepseek-ai/dsh-tool-lsp", + "description": "Model-facing lsp tool over the DeepSeek Harness LSP capability seam (ctx.lsp) — one read-only tool with definition/references/implementation/hover operations, one-based UTF-16 cursor coordinates, workspace-grouped location rendering, and hover normalization", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-llm": "^0.0.1", + "@deepseek-ai/dsh-lsp": "^0.0.1", + "@deepseek-ai/dsh-system-prompt": "^0.0.1", + "@deepseek-ai/dsh-tools": "^0.0.1", + "cordis": "^4.0.0-rc.7" + }, + "dependencies": { + "schemastery": "^3.18.0" + }, + "devDependencies": { + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-lsp": "workspace:^", + "@deepseek-ai/dsh-lsp-local": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-system-prompt": "workspace:^", + "@deepseek-ai/dsh-timeout-policy": "workspace:^", + "@deepseek-ai/dsh-tools": "workspace:^", + "cordis": "^4.0.0-rc.7" + } +} diff --git a/packages/lsp/tool-lsp/src/index.ts b/packages/lsp/tool-lsp/src/index.ts new file mode 100644 index 0000000000..1ec48a3d74 --- /dev/null +++ b/packages/lsp/tool-lsp/src/index.ts @@ -0,0 +1,130 @@ +/** + * Model-facing `lsp` tool over `ctx.lsp`. One read-only tool with four operations + * (`definition`/`references`/`implementation`/`hover`); it converts one-based UTF-16 cursor + * coordinates to the seam's zero-based positions, requires the session workspace with no fallback, + * caps and renders results, and attaches a configurable timeout budget for `dsh-timeout-policy` to + * enforce. It runtime-injects only `tools`, `lsp`, and `systemPrompt` and imports no provider. + * + * Namespace plugin (named exports, no default export). + * @module @deepseek-ai/dsh-tool-lsp + */ + +import type { Context } from 'cordis' +import z from 'schemastery' +import { defineTool } from '@deepseek-ai/dsh-tools' +import type { ContentBlock } from '@deepseek-ai/dsh-llm' +import { LspError } from '@deepseek-ai/dsh-lsp' +import type {} from '@deepseek-ai/dsh-lsp' +import type {} from '@deepseek-ai/dsh-system-prompt' +import { + DEFAULT_MAX_HOVER_CHARS, + DEFAULT_MAX_LOCATIONS, + formatHover, + formatLocations, + LSP_OPERATIONS, + parseLspArgs, + presentLspCall, +} from './render.ts' +import { sessionCwd } from './session-cwd.ts' + +export { + DEFAULT_MAX_HOVER_CHARS, + DEFAULT_MAX_LOCATIONS, + formatHover, + formatLocations, + LSP_OPERATIONS, + parseLspArgs, + presentLspCall, + renderUri, +} from './render.ts' +export { sessionCwd } from './session-cwd.ts' + +/** Cordis plugin name for loader diagnostics. */ +export const name = 'tool-lsp' + +/** Services required by this plugin. */ +export const inject = ['tools', 'lsp', 'systemPrompt'] + +/** Default tool-call timeout budget (ms), covering the queued open/query/close lifecycle. */ +export const DEFAULT_LSP_TOOL_TIMEOUT_MS = 60_000 + +/** The stable system-prompt guidance positioning LSP as a precision aid. */ +export const LSP_PROMPT_TEXT = + 'Use search/read for ordinary navigation. Use lsp when textual matches are ambiguous or before a change requires precise definitions, implementations, or references. Positions are one-based line and character (UTF-16) at the cursor; an off-symbol position may return no results. references always includes the declaration.' + +/** Plugin configuration: result caps and the timeout budget. */ +export interface Config { + /** Largest number of rendered locations before an omission marker (default 100). */ + maxLocations?: number + /** Largest hover length in characters after normalization (default 16000). */ + maxHoverChars?: number + /** Tool-call timeout budget in ms (default 60000). */ + timeoutMs?: number +} + +export const Config: z = z.object({ + maxLocations: z.number().default(DEFAULT_MAX_LOCATIONS), + maxHoverChars: z.number().default(DEFAULT_MAX_HOVER_CHARS), + timeoutMs: z.number().default(DEFAULT_LSP_TOOL_TIMEOUT_MS), +}) + +type ResolvedConfig = Required + +/** + * Register the `lsp` tool and its system-prompt guidance. + * @param ctx - the plugin context (must inject `tools`, `lsp`, `systemPrompt`). + * @param config - the resolved plugin configuration. + */ +export function apply(ctx: Context, config: Config): void { + const resolved = config as ResolvedConfig + assertPositiveInteger('maxLocations', resolved.maxLocations) + assertPositiveInteger('maxHoverChars', resolved.maxHoverChars) + assertPositiveInteger('timeoutMs', resolved.timeoutMs) + + ctx.systemPrompt.section({ name: 'tool:lsp', order: 112, text: LSP_PROMPT_TEXT }) + + ctx.tools.register(defineTool({ + name: 'lsp', + description: + 'Query a language server for precise code navigation. operation is one of definition, references, implementation, hover. line and character are one-based UTF-16 cursor coordinates. references includes the declaration.', + parameters: { + operation: { + type: 'string', + required: true, + enum: [...LSP_OPERATIONS], + description: 'definition, references, implementation, or hover.', + }, + file_path: { type: 'string', required: true, description: 'The source file to query, relative to the workspace or absolute.' }, + line: { type: 'number', required: true, description: 'One-based line of the cursor.' }, + character: { type: 'number', required: true, description: 'One-based UTF-16 column of the cursor.' }, + }, + timeoutMs: resolved.timeoutMs, + async execute(args, exec): Promise { + const input = parseLspArgs(args) + const workspaceRoot = sessionCwd(exec) + if (workspaceRoot === undefined) { + throw new LspError('the lsp tool requires a session workspace cwd', 'LSP_WORKSPACE_REQUIRED') + } + const result = await ctx.lsp.query({ + operation: input.operation, + filePath: input.filePath, + position: input.position, + workspaceRoot, + }, exec.signal) + switch (result.kind) { + case 'locations': + return [{ type: 'text', text: formatLocations(result.locations, workspaceRoot, resolved.maxLocations) }] + case 'hover': + return [{ type: 'text', text: formatHover(result.hover, resolved.maxHoverChars) }] + } + }, + presentCall: presentLspCall, + })) +} + +/** Reject a non-positive-integer config value at load, so misconfiguration fails loud. */ +function assertPositiveInteger(name: string, value: number): void { + if (!Number.isInteger(value) || value < 1) { + throw new Error(`tool-lsp: ${name} must be a positive integer`) + } +} diff --git a/packages/lsp/tool-lsp/src/render.ts b/packages/lsp/tool-lsp/src/render.ts new file mode 100644 index 0000000000..df0913a591 --- /dev/null +++ b/packages/lsp/tool-lsp/src/render.ts @@ -0,0 +1,158 @@ +/** + * Pure formatting and coordinate conversion for the `lsp` tool: one-based↔zero-based UTF-16 cursor + * conversion, workspace-grouped location rendering with `file:`-URI resolution, hover capping, and + * ACP presentation. No I/O — a UI may call the presenter on live streaming and on replay, so it + * depends only on the tool arguments. + * @module @deepseek-ai/dsh-tool-lsp/render + */ + +import { fileURLToPath } from 'node:url' +import { isAbsolute, relative, sep } from 'node:path' +import type { GenericCallView } from '@deepseek-ai/dsh-tools' +import type { LspHover, LspLocation, LspOperation, LspPosition } from '@deepseek-ai/dsh-lsp' + +/** The four operations the tool exposes, as a runtime tuple for schema enum + validation. */ +export const LSP_OPERATIONS: readonly LspOperation[] = ['definition', 'references', 'implementation', 'hover'] + +/** Default cap on rendered locations before an omission marker is appended. */ +export const DEFAULT_MAX_LOCATIONS = 100 + +/** Default cap on hover characters (applied after normalization) before truncation is marked. */ +export const DEFAULT_MAX_HOVER_CHARS = 16_000 + +/** Validated `lsp` arguments after coordinate checks. */ +export interface LspToolInput { + readonly operation: LspOperation + readonly filePath: string + /** Zero-based UTF-16 position converted from the one-based model coordinates. */ + readonly position: LspPosition +} + +/** The raw, schema-typed argument shape. */ +export interface LspToolArgs { + readonly operation: string + readonly file_path: string + readonly line: number + readonly character: number +} + +/** + * Validate and convert model arguments: `operation` must be one of the four; `line`/`character` are + * positive one-based integers converted to the seam's zero-based position. + * @param args - the schema-validated raw arguments. + * @returns the validated input with a zero-based position. + * @throws Error when the operation is unknown or a coordinate is not a positive integer. + */ +export function parseLspArgs(args: LspToolArgs): LspToolInput { + if (!isOperation(args.operation)) { + throw new Error(`operation must be one of ${LSP_OPERATIONS.join(', ')}`) + } + if (args.file_path.trim().length === 0) throw new Error('file_path must be a non-empty string') + const line = oneBased(args.line, 'line') + const character = oneBased(args.character, 'character') + return { + operation: args.operation, + filePath: args.file_path, + // The model counts from 1; the seam (and protocol) count from 0. + position: { line: line - 1, character: character - 1 }, + } +} + +/** Whether a string is one of the four operations. */ +function isOperation(value: string): value is LspOperation { + return (LSP_OPERATIONS as readonly string[]).includes(value) +} + +/** Validate a one-based coordinate is a positive integer. */ +function oneBased(value: number, name: string): number { + if (!Number.isInteger(value) || value < 1) { + throw new Error(`${name} must be a positive integer (one-based)`) + } + return value +} + +/** + * Render a locations result grouped by file, converting each zero-based location back to a one-based + * `path:line:character` entry. A `file:` URI inside the workspace becomes a workspace-relative path; + * outside it, an absolute path; a non-`file:` URI is kept verbatim. Applies `maxLocations` and + * appends an omission marker when it truncates. + * @param locations - the seam's locations (possibly empty). + * @param workspaceRoot - the canonical workspace root for relativizing `file:` paths. + * @param maxLocations - the cap before truncation. + * @returns the rendered text; a distinct no-result line when there are none. + */ +export function formatLocations( + locations: readonly LspLocation[], + workspaceRoot: string, + maxLocations: number, +): string { + if (locations.length === 0) return 'No results.' + const shown = locations.slice(0, maxLocations) + const omitted = locations.length - shown.length + const grouped = new Map() + for (const location of shown) { + const path = renderUri(location.uri, workspaceRoot) + const line = location.range.start.line + 1 + const character = location.range.start.character + 1 + const entries = grouped.get(path) ?? [] + entries.push(`${path}:${line}:${character}`) + grouped.set(path, entries) + } + const lines: string[] = [] + for (const entries of grouped.values()) lines.push(...entries) + if (omitted > 0) { + lines.push(`… ${omitted} more location${omitted === 1 ? '' : 's'} omitted (limit ${maxLocations}).`) + } + return lines.join('\n') +} + +/** + * Render a hover result, applying `maxHoverChars` last and marking truncation. + * @param hover - the normalized hover, or `null` for no hover. + * @param maxHoverChars - the cap applied after normalization. + * @returns the rendered hover text; a distinct no-result line for `null`. + */ +export function formatHover(hover: LspHover | null, maxHoverChars: number): string { + if (hover === null) return 'No hover information.' + const contents = hover.contents + if (contents.length <= maxHoverChars) return contents + return `${contents.slice(0, maxHoverChars)}\n… hover truncated (limit ${maxHoverChars} characters).` +} + +/** + * Resolve a location URI to a display path. A `file:` URI accepted by Node becomes workspace-relative + * (inside) or absolute (outside); any other URI is returned verbatim. + * @param uri - the target URI from the seam. + * @param workspaceRoot - the canonical workspace root. + * @returns the display path or the verbatim URI. + */ +export function renderUri(uri: string, workspaceRoot: string): string { + if (!uri.startsWith('file:')) return uri + let absolute: string + try { + absolute = fileURLToPath(uri) + } catch { + // A malformed file: URI is not a path we can resolve; show it verbatim. + return uri + } + const rel = relative(workspaceRoot, absolute) + if (rel === '') return '.' + const outside = rel.startsWith('..') || isAbsolute(rel) + return outside ? absolute : rel.split(sep).join('/') +} + +/** + * ACP presentation for a pending `lsp` call. Uses a generic search card; the title carries the + * operation and one-based cursor, and `locations` focuses the queried line (ACP `FileLocation` has + * no character, so the title preserves the column). + * @param args - the raw tool arguments. + * @returns the generic call view. + */ +export function presentLspCall(args: LspToolArgs): GenericCallView { + return { + card: 'generic', + kind: 'search', + title: `LSP ${args.operation} ${args.file_path}:${args.line}:${args.character}`, + locations: [{ path: args.file_path, line: args.line }], + } +} diff --git a/packages/lsp/tool-lsp/src/session-cwd.ts b/packages/lsp/tool-lsp/src/session-cwd.ts new file mode 100644 index 0000000000..7fc41785de --- /dev/null +++ b/packages/lsp/tool-lsp/src/session-cwd.ts @@ -0,0 +1,19 @@ +/** + * Derive the workspace root an `lsp` call resolves against: the calling agent's per-session + * workspace (`exec.agent.session.header.cwd`), mirroring how the filesystem tools resolve paths. + * Unlike those tools, LSP has NO provider fallback — a missing cwd fails the call as + * `LSP_WORKSPACE_REQUIRED`, because the local provider must canonicalize a real workspace before it + * can start a server. + * @module @deepseek-ai/dsh-tool-lsp/session-cwd + */ + +import type { ToolExecution } from '@deepseek-ai/dsh-tools' + +/** + * The session workspace cwd for this call, or `undefined` when none applies. + * @param exec - the tool-execution context; only its optional `agent` is read. + * @returns the calling agent's session cwd, or undefined for a non-agent caller. + */ +export function sessionCwd(exec: ToolExecution): string | undefined { + return exec.agent?.session.header.cwd +} diff --git a/packages/lsp/tool-lsp/tests/integration.spec.ts b/packages/lsp/tool-lsp/tests/integration.spec.ts new file mode 100644 index 0000000000..f2e8d1c46a --- /dev/null +++ b/packages/lsp/tool-lsp/tests/integration.spec.ts @@ -0,0 +1,93 @@ +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { pathToFileURL } from 'node:url' +import { Context } from 'cordis' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import Lsp from '@deepseek-ai/dsh-lsp' +import * as LspLocal from '@deepseek-ai/dsh-lsp-local' +import * as TimeoutPolicy from '@deepseek-ai/dsh-timeout-policy' +import * as ToolLsp from '@deepseek-ai/dsh-tool-lsp' + +/** + * Real-composition integration: the model-facing `lsp` tool over the real seam, the real + * `dsh-lsp-local` provider (driving an inline stdio server), and the real `dsh-timeout-policy`, all + * driven only through `ctx.tools.execute()`. Pins that a query round-trips end to end and that the + * policy's `TOOL_TIMEOUT` budget wins when the server hangs. + */ + +let root: string +let ws: string + +beforeEach(async () => { + root = await realpath(await mkdtemp(join(tmpdir(), 'lsp-tool-int-'))) + ws = join(root, 'ws') + await mkdir(ws) + await writeFile(join(ws, 'a.ts'), 'const x = 1\n') +}) + +afterEach(async () => { + await rm(root, { recursive: true, force: true }) +}) + +/** An inline stdio server that answers initialize + definition; `hang` makes textDocument/* stall. */ +function serverScript(hang: boolean): string { + const definition = JSON.stringify({ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } }) + return 'let b=Buffer.alloc(0);' + + `const DEF=${definition};` + + 'const fr=(o)=>{const x=Buffer.from(JSON.stringify({jsonrpc:"2.0",...o}));return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};' + + 'process.stdin.on("data",c=>{b=Buffer.concat([b,c]);for(;;){const s=b.indexOf("\\r\\n\\r\\n");if(s<0)break;const len=Number(/(\\d+)/.exec(b.toString("ascii",0,s))[1]);if(b.length { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(Lsp) + await ctx.plugin(LspLocal, { + providerId: 'inline', + command: process.execPath, + args: ['-e', serverScript(hang)], + extensionToLanguage: { '.ts': 'typescript' }, + shutdownTimeoutMs: 200, + killGraceMs: 200, + }) + await ctx.plugin(TimeoutPolicy) + await ctx.plugin(ToolLsp, timeoutMs !== undefined ? { timeoutMs } : {}) + return ctx +} + +let seq = 0 +function call(ctx: Context, args: unknown) { + return ctx.tools.execute({ + callId: `int-${++seq}` as never, + name: 'lsp', + arguments: args, + agent: { session: { header: { cwd: ws } } } as never, + }) +} + +describe('tool-lsp real composition', () => { + it('round-trips a definition query through the real provider and renders a location', async () => { + const ctx = await mount(false) + const result = await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 1, character: 7 }) + expect(result.isError).toBe(false) + expect(result.content[0]).toEqual({ type: 'text', text: 'a.ts:1:1' }) + await ctx.fiber.dispose() + }, 30_000) + + it('enforces the TOOL_TIMEOUT budget when the server hangs', async () => { + const ctx = await mount(true, 300) + const result = await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 1, character: 7 }) + expect(result.isError).toBe(true) + expect(result.error?.code).toBe('TOOL_TIMEOUT') + await ctx.fiber.dispose() + }, 30_000) +}) diff --git a/packages/lsp/tool-lsp/tests/load-path.spec.ts b/packages/lsp/tool-lsp/tests/load-path.spec.ts new file mode 100644 index 0000000000..13dbaa7b78 --- /dev/null +++ b/packages/lsp/tool-lsp/tests/load-path.spec.ts @@ -0,0 +1,24 @@ +/** + * Real-load-path guard for @deepseek-ai/dsh-tool-lsp. It is a NAMESPACE plugin with `inject`, so a + * stray `export default apply` would make the Loader's `unwrapExports` collapse the module to the + * bare `apply`, dropping `inject` (postmortem 0001). This unwraps through the REAL + * `Loader.prototype.unwrapExports` and verifies the namespace shape survives. + */ + +import { describe, expect, it } from 'vitest' +import Loader from '@cordisjs/plugin-loader' +import * as toolLsp from '@deepseek-ai/dsh-tool-lsp' + +describe('dsh-tool-lsp real-load-path guard', () => { + it('has no default export and keeps name/inject/Config through unwrapExports', () => { + expect('default' in toolLsp).toBe(false) + + const loader = Object.create(Loader.prototype) as Loader + const unwrapped = loader.unwrapExports(toolLsp) as Record + expect(unwrapped).toBe(toolLsp) + expect(unwrapped.name).toBe('tool-lsp') + expect(unwrapped.inject).toEqual(['tools', 'lsp', 'systemPrompt']) + expect(typeof unwrapped.apply).toBe('function') + expect(unwrapped.Config).toBeDefined() + }) +}) diff --git a/packages/lsp/tool-lsp/tests/render.spec.ts b/packages/lsp/tool-lsp/tests/render.spec.ts new file mode 100644 index 0000000000..53a2be5899 --- /dev/null +++ b/packages/lsp/tool-lsp/tests/render.spec.ts @@ -0,0 +1,125 @@ +import { describe, expect, it } from 'vitest' +import { pathToFileURL } from 'node:url' +import { join } from 'node:path' +import { + DEFAULT_MAX_HOVER_CHARS, + DEFAULT_MAX_LOCATIONS, + formatHover, + formatLocations, + LSP_OPERATIONS, + parseLspArgs, + presentLspCall, + renderUri, +} from '@deepseek-ai/dsh-tool-lsp' +import type { LspLocation } from '@deepseek-ai/dsh-lsp' + +const WS = '/home/u/proj' + +function loc(uri: string, line: number, character = 0): LspLocation { + return { uri, range: { start: { line, character }, end: { line, character: character + 1 } } } +} + +describe('parseLspArgs', () => { + it('accepts the four operations and converts one-based to zero-based', () => { + for (const operation of LSP_OPERATIONS) { + const input = parseLspArgs({ operation, file_path: 'a.ts', line: 3, character: 5 }) + expect(input.operation).toBe(operation) + expect(input.position).toEqual({ line: 2, character: 4 }) + } + }) + + it('rejects an unknown operation', () => { + expect(() => parseLspArgs({ operation: 'rename', file_path: 'a.ts', line: 1, character: 1 })) + .toThrow(/operation must be one of/) + }) + + it('rejects a blank file_path', () => { + expect(() => parseLspArgs({ operation: 'hover', file_path: ' ', line: 1, character: 1 })) + .toThrow(/file_path/) + }) + + it('rejects non-positive or non-integer coordinates', () => { + expect(() => parseLspArgs({ operation: 'hover', file_path: 'a.ts', line: 0, character: 1 })).toThrow(/line/) + expect(() => parseLspArgs({ operation: 'hover', file_path: 'a.ts', line: 1, character: 0 })).toThrow(/character/) + expect(() => parseLspArgs({ operation: 'hover', file_path: 'a.ts', line: 1.5, character: 1 })).toThrow(/line/) + }) +}) + +describe('renderUri', () => { + it('relativizes a file: URI inside the workspace with forward slashes', () => { + const uri = pathToFileURL(join(WS, 'src', 'a.ts')).href + expect(renderUri(uri, WS)).toBe('src/a.ts') + }) + + it('returns an absolute path for a file: URI outside the workspace', () => { + const uri = pathToFileURL('/other/lib/b.ts').href + expect(renderUri(uri, WS)).toBe('/other/lib/b.ts') + }) + + it('renders the workspace root itself as "."', () => { + expect(renderUri(pathToFileURL(WS).href, WS)).toBe('.') + }) + + it('keeps a non-file URI verbatim', () => { + expect(renderUri('untitled:Untitled-1', WS)).toBe('untitled:Untitled-1') + expect(renderUri('jdt://contents/Foo.class', WS)).toBe('jdt://contents/Foo.class') + }) + + it('keeps a malformed file: URI verbatim when it cannot be parsed to a path', () => { + // A file: URI with a host that fileURLToPath rejects falls through to the verbatim path. + expect(renderUri('file://host/notlocal', WS)).toBe('file://host/notlocal') + }) +}) + +describe('formatLocations', () => { + it('renders a no-result line for an empty list', () => { + expect(formatLocations([], WS, DEFAULT_MAX_LOCATIONS)).toBe('No results.') + }) + + it('renders one-based path:line:character grouped by file', () => { + const a = pathToFileURL(join(WS, 'a.ts')).href + const text = formatLocations([loc(a, 0, 0), loc(a, 4, 2)], WS, DEFAULT_MAX_LOCATIONS) + expect(text).toBe('a.ts:1:1\na.ts:5:3') + }) + + it('caps at maxLocations and marks the omission', () => { + const a = pathToFileURL(join(WS, 'a.ts')).href + const many = Array.from({ length: 5 }, (_, i) => loc(a, i)) + const text = formatLocations(many, WS, 2) + expect(text).toContain('a.ts:1:1') + expect(text).toContain('3 more locations omitted (limit 2).') + }) + + it('uses the singular omission marker for exactly one extra', () => { + const a = pathToFileURL(join(WS, 'a.ts')).href + const text = formatLocations([loc(a, 0), loc(a, 1)], WS, 1) + expect(text).toContain('1 more location omitted (limit 1).') + }) +}) + +describe('formatHover', () => { + it('renders a no-result line for null', () => { + expect(formatHover(null, DEFAULT_MAX_HOVER_CHARS)).toBe('No hover information.') + }) + + it('returns short hover verbatim', () => { + expect(formatHover({ contents: '```ts\nx: number\n```' }, DEFAULT_MAX_HOVER_CHARS)).toBe('```ts\nx: number\n```') + }) + + it('caps hover at maxHoverChars and marks truncation', () => { + const text = formatHover({ contents: 'a'.repeat(50) }, 10) + expect(text.startsWith('aaaaaaaaaa\n')).toBe(true) + expect(text).toContain('hover truncated (limit 10 characters).') + }) +}) + +describe('presentLspCall', () => { + it('is a generic search card with an operation/cursor title and a line location', () => { + expect(presentLspCall({ operation: 'references', file_path: 'a.ts', line: 3, character: 7 })).toEqual({ + card: 'generic', + kind: 'search', + title: 'LSP references a.ts:3:7', + locations: [{ path: 'a.ts', line: 3 }], + }) + }) +}) diff --git a/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts b/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts new file mode 100644 index 0000000000..9cd48ed87f --- /dev/null +++ b/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts @@ -0,0 +1,164 @@ +import { describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import Lsp, { LspProviderId, type LspProvider, type LspProviderQuery, type LspQueryResult } from '@deepseek-ai/dsh-lsp' +import * as ToolLsp from '@deepseek-ai/dsh-tool-lsp' +import { DEFAULT_LSP_TOOL_TIMEOUT_MS, LSP_PROMPT_TEXT } from '@deepseek-ai/dsh-tool-lsp' + +/** A scripted provider recording queries; `respond` yields the result or throws. */ +function stubProvider( + respond: (request: LspProviderQuery) => LspQueryResult, + extensionToLanguage: Record = { '.ts': 'typescript' }, +): LspProvider & { seen: LspProviderQuery[] } { + const seen: LspProviderQuery[] = [] + return { + id: LspProviderId('stub'), + extensionToLanguage, + seen, + query(request) { + seen.push(request) + return Promise.resolve(respond(request)) + }, + } +} + +/** Mount the real tool stack over a real seam plus one stub provider. */ +async function mount( + provider?: LspProvider, + config: ToolLsp.Config = {}, +): Promise<{ ctx: Context }> { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(Lsp) + if (provider) (ctx.lsp as Lsp).registerProvider(provider) + await ctx.plugin(ToolLsp, config) + return { ctx } +} + +let seq = 0 +/** `cwd: null` means "no agent" (tests LSP_WORKSPACE_REQUIRED); a string is the session cwd. */ +function call(ctx: Context, args: unknown, cwd: string | null = '/ws') { + return ctx.tools.execute({ + callId: `c-${++seq}` as never, + name: 'lsp', + arguments: args, + ...cwd !== null ? { agent: { session: { header: { cwd } } } as never } : {}, + }) +} + +const okLocations: LspQueryResult = { + kind: 'locations', + locations: [{ uri: 'file:///ws/a.ts', range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }], +} + +describe('tool-lsp registration', () => { + it('registers the lsp tool and its prompt section', async () => { + const { ctx } = await mount(stubProvider(() => okLocations)) + expect(ctx.tools.get('lsp')).toBeDefined() + const prompt = await ctx.systemPrompt.assemble() + const text = prompt.sections.map(s => s.text).join('\n') + expect(text).toContain(LSP_PROMPT_TEXT) + }) + + it('attaches the default timeout budget to the tool definition', async () => { + const { ctx } = await mount(stubProvider(() => okLocations)) + expect(ctx.tools.get('lsp')?.timeoutMs).toBe(DEFAULT_LSP_TOOL_TIMEOUT_MS) + }) + + it('honors a configured timeout override', async () => { + const { ctx } = await mount(stubProvider(() => okLocations), { timeoutMs: 5000 }) + expect(ctx.tools.get('lsp')?.timeoutMs).toBe(5000) + }) + + it('exposes exactly the four operations in the schema enum', async () => { + const { ctx } = await mount(stubProvider(() => okLocations)) + const schema = ctx.tools.get('lsp')?.parameters as { properties: { operation: { enum: string[] } } } + expect(schema.properties.operation.enum).toEqual(['definition', 'references', 'implementation', 'hover']) + }) + + it('has no default export (namespace plugin shape)', () => { + expect((ToolLsp as { default?: unknown }).default).toBeUndefined() + }) + + it('rejects a non-positive config value at load', async () => { + await expect(mount(stubProvider(() => okLocations), { maxLocations: 0 })).rejects.toThrow(/maxLocations/) + }) +}) + +describe('tool-lsp execution', () => { + it('converts one-based coordinates and passes the session cwd as workspaceRoot', async () => { + const provider = stubProvider(() => okLocations) + const { ctx } = await mount(provider) + const result = await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 3, character: 5 }, '/ws') + expect(result.isError).toBe(false) + expect(provider.seen[0]).toMatchObject({ + operation: 'definition', + filePath: 'a.ts', + position: { line: 2, character: 4 }, + workspaceRoot: '/ws', + }) + }) + + it('renders locations relative to the workspace', async () => { + const { ctx } = await mount(stubProvider(() => okLocations)) + const result = await call(ctx, { operation: 'references', file_path: 'a.ts', line: 1, character: 1 }, '/ws') + expect(result.content[0]).toEqual({ type: 'text', text: 'a.ts:1:1' }) + }) + + it('renders hover content', async () => { + const { ctx } = await mount(stubProvider(() => ({ kind: 'hover', hover: { contents: 'number' } }))) + const result = await call(ctx, { operation: 'hover', file_path: 'a.ts', line: 1, character: 1 }, '/ws') + expect(result.content[0]).toEqual({ type: 'text', text: 'number' }) + }) + + it('fails LSP_WORKSPACE_REQUIRED without a session cwd', async () => { + const { ctx } = await mount(stubProvider(() => okLocations)) + const result = await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 1, character: 1 }, null) + expect(result.isError).toBe(true) + expect(result.error?.code).toBe('LSP_WORKSPACE_REQUIRED') + }) + + it('surfaces a structured LSP_UNAVAILABLE when no provider handles the file', async () => { + const { ctx } = await mount(stubProvider(() => okLocations, { '.py': 'python' })) + const result = await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 1, character: 1 }, '/ws') + expect(result.isError).toBe(true) + expect(result.error?.code).toBe('LSP_UNAVAILABLE') + }) + + it('returns a structured INVALID_ARGS on a bad operation', async () => { + const { ctx } = await mount(stubProvider(() => okLocations)) + const result = await call(ctx, { operation: 'rename', file_path: 'a.ts', line: 1, character: 1 }, '/ws') + expect(result.isError).toBe(true) + expect(result.error?.code).toBe('INVALID_ARGS') + }) + + it('forwards exec.signal to the seam query', async () => { + const seen: (AbortSignal | undefined)[] = [] + const provider: LspProvider = { + id: LspProviderId('sig'), + extensionToLanguage: { '.ts': 'typescript' }, + query(_request, signal) { + seen.push(signal) + return Promise.resolve(okLocations) + }, + } + const { ctx } = await mount(provider) + await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 1, character: 1 }, '/ws') + // The timeout policy is not mounted here, so the signal is whatever the registry passes (may be + // undefined); the point is the tool threads it through without throwing. + expect(seen).toHaveLength(1) + }) + + it('presentCall renders the pending card from args', async () => { + const { ctx } = await mount(stubProvider(() => okLocations)) + const view = ctx.tools.get('lsp')?.presentCall?.({ operation: 'hover', file_path: 'a.ts', line: 2, character: 3 }) + expect(view).toEqual({ + card: 'generic', + kind: 'search', + title: 'LSP hover a.ts:2:3', + locations: [{ path: 'a.ts', line: 2 }], + }) + }) +}) diff --git a/packages/lsp/tool-lsp/tsconfig.json b/packages/lsp/tool-lsp/tsconfig.json new file mode 100644 index 0000000000..be656effd2 --- /dev/null +++ b/packages/lsp/tool-lsp/tsconfig.json @@ -0,0 +1,33 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../../vendor/schemastery" + }, + { + "path": "../../llm/llm" + }, + { + "path": "../../core/tools" + }, + { + "path": "../../core/system-prompt" + }, + { + "path": "../lsp" + } + ] +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 4e0a2af98a..2cd474142b 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -724,6 +724,80 @@ importers: specifier: ^4.0.0-rc.7 version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) + packages/lsp/lsp: + devDependencies: + '@deepseek-ai/dsh-brand': + specifier: workspace:^ + version: link:../../util/brand + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + cordis: + specifier: ^4.0.0-rc.7 + version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) + + packages/lsp/lsp-local: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + devDependencies: + '@deepseek-ai/dsh-brand': + specifier: workspace:^ + version: link:../../util/brand + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-lsp': + specifier: workspace:^ + version: link:../lsp + '@deepseek-ai/dsh-timeout': + specifier: workspace:^ + version: link:../../util/timeout + cordis: + specifier: ^4.0.0-rc.7 + version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) + typescript: + specifier: ^6.0.3 + version: 6.0.3 + typescript-language-server: + specifier: ^5.0.0 + version: 5.3.0 + + packages/lsp/tool-lsp: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + devDependencies: + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../../core/agent + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-lsp': + specifier: workspace:^ + version: link:../lsp + '@deepseek-ai/dsh-lsp-local': + specifier: workspace:^ + version: link:../lsp-local + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session + '@deepseek-ai/dsh-system-prompt': + specifier: workspace:^ + version: link:../../core/system-prompt + '@deepseek-ai/dsh-timeout-policy': + specifier: workspace:^ + version: link:../../timeout/timeout-policy + '@deepseek-ai/dsh-tools': + specifier: workspace:^ + version: link:../../core/tools + cordis: + specifier: ^4.0.0-rc.7 + version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) + packages/mcp/mcp-client: dependencies: '@modelcontextprotocol/sdk': @@ -1171,7 +1245,7 @@ importers: devDependencies: cordis: specifier: ^4.0.0-rc.6 - version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) packages/support/subagent-mock: dependencies: @@ -3612,6 +3686,18 @@ packages: resolution: {integrity: sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==} engines: {node: '>= 0.6'} + cordis@4.0.0-rc.6: + resolution: {integrity: sha512-GzUv7zCKh3FlgM3/Ad2S03UpYO3v4u1GcKa7ig4K2je4lCrgJ/S64ziiZI6XNyKEa1tZwdzj4oBQrhYDLgfEiA==} + hasBin: true + peerDependencies: + '@cordisjs/plugin-include': ^1.0.4 + '@cordisjs/plugin-loader': ^1.0.0-rc.4 + peerDependenciesMeta: + '@cordisjs/plugin-include': + optional: true + '@cordisjs/plugin-loader': + optional: true + cordis@4.0.0-rc.7: resolution: {integrity: sha512-5nm6ehrSfJhEUV659CctEvyNuBY/AXapw8+ZEw7YENztdzpiT+Ha8nIfkyhfyAgPtJns9aB5On5nzl9Sm6zHeQ==} hasBin: true @@ -5330,6 +5416,11 @@ packages: eslint: ^8.57.0 || ^9.0.0 || ^10.0.0 typescript: '>=4.8.4 <6.1.0' + typescript-language-server@5.3.0: + resolution: {integrity: sha512-5puofxZHgFdAYtfNpmwCAvgtaYgg8wrUnH30m7Ze3QuguId5RNRadKASpOpyDxTyUdAF51FjhTdjntLw/EuWcQ==} + engines: {node: '>=20'} + hasBin: true + typescript@6.0.3: resolution: {integrity: sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==} engines: {node: '>=14.17'} @@ -5471,6 +5562,20 @@ packages: jsdom: optional: true + vscode-jsonrpc@5.0.1: + resolution: {integrity: sha512-JvONPptw3GAQGXlVV2utDcHx0BiY34FupW/kI6mZ5x06ER5DdPG/tXWMVHjTNULF5uKPOUUD0SaXg5QaubJL0A==} + engines: {node: '>=8.0.0 || >=10.0.0'} + + vscode-jsonrpc@9.0.1: + resolution: {integrity: sha512-rfuA6T75H6m5EkbhtEPzre9pT0HPcDI2MMy4+nPFIBks5J8JBAUHD4tRYSgaBOijIEC7SRkC1kKyXTLqbmh9jw==} + engines: {node: '>=14.0.0'} + + vscode-languageserver-protocol@3.18.2: + resolution: {integrity: sha512-XRyDbT0Pp3sSNti3JmxVEUMySWCSi1hhM+/KUlCy1hV1zmrqpM1OwO12EAki8blhmLuIMpaJrYbo0OzGVfK2Qg==} + + vscode-languageserver-types@3.18.0: + resolution: {integrity: sha512-8TsGPNMIMiiBdkORgRSvLjuiEIiAFtO+KssmYWxQ+uSVvlf7RjK8YKCOjPzZ+YA04jXEV7+7LvkSmHkhpNS99g==} + w3c-xmlserializer@5.0.0: resolution: {integrity: sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==} engines: {node: '>=18'} @@ -5876,6 +5981,14 @@ snapshots: '@chevrotain/types@11.1.2': {} + '@cordisjs/plugin-include@1.0.4(@cordisjs/plugin-loader@1.0.0-rc.5)(cordis@4.0.0-rc.6)': + dependencies: + '@cordisjs/plugin-loader': 1.0.0-rc.5(cordis@4.0.0-rc.6)(node-addon-require-builtin@0.1.0) + cordis: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) + cosmokit: 1.8.1 + js-yaml: 4.2.0 + optional: true + '@cordisjs/plugin-include@1.0.4(@cordisjs/plugin-loader@1.0.0-rc.5)(cordis@4.0.0-rc.7)': dependencies: '@cordisjs/plugin-loader': 1.0.0-rc.5(cordis@4.0.0-rc.7)(node-addon-require-builtin@0.1.0) @@ -5891,6 +6004,14 @@ snapshots: js-yaml: 4.2.0 optional: true + '@cordisjs/plugin-loader@1.0.0-rc.5(cordis@4.0.0-rc.6)(node-addon-require-builtin@0.1.0)': + dependencies: + cordis: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) + cosmokit: 1.8.1 + optionalDependencies: + node-addon-require-builtin: 0.1.0 + optional: true + '@cordisjs/plugin-loader@1.0.0-rc.5(cordis@4.0.0-rc.7)(node-addon-require-builtin@0.1.0)': dependencies: cordis: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5) @@ -7037,6 +7158,14 @@ snapshots: cookie@0.7.2: {} + cordis@4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5): + dependencies: + '@standard-schema/spec': 1.1.0 + cosmokit: 1.8.1 + optionalDependencies: + '@cordisjs/plugin-include': 1.0.4(@cordisjs/plugin-loader@1.0.0-rc.5)(cordis@4.0.0-rc.6) + '@cordisjs/plugin-loader': 1.0.0-rc.5(cordis@4.0.0-rc.6)(node-addon-require-builtin@0.1.0) + cordis@4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5): dependencies: '@standard-schema/spec': 1.1.0 @@ -9038,6 +9167,11 @@ snapshots: transitivePeerDependencies: - supports-color + typescript-language-server@5.3.0: + dependencies: + vscode-jsonrpc: 5.0.1 + vscode-languageserver-protocol: 3.18.2 + typescript@6.0.3: {} unbash@3.0.0: {} @@ -9182,6 +9316,17 @@ snapshots: transitivePeerDependencies: - msw + vscode-jsonrpc@5.0.1: {} + + vscode-jsonrpc@9.0.1: {} + + vscode-languageserver-protocol@3.18.2: + dependencies: + vscode-jsonrpc: 9.0.1 + vscode-languageserver-types: 3.18.0 + + vscode-languageserver-types@3.18.0: {} + w3c-xmlserializer@5.0.0: dependencies: xml-name-validator: 5.0.0 diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index ab6b01c10d..fcacdb6ba7 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -26,6 +26,8 @@ import * as ToolAskUser from '@deepseek-ai/dsh-tool-ask-user' import * as ToolBash from '@deepseek-ai/dsh-tool-bash' import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis' import * as ToolFs from '@deepseek-ai/dsh-tool-fs' +import Lsp from '@deepseek-ai/dsh-lsp' +import * as ToolLsp from '@deepseek-ai/dsh-tool-lsp' import * as ToolSkill from '@deepseek-ai/dsh-tool-skill' import * as ToolTodo from '@deepseek-ai/dsh-tool-todo' import * as ToolSubagent from '@deepseek-ai/dsh-tool-subagent' @@ -147,6 +149,20 @@ const TOOL_PACKAGES: ToolPackage[] = [ note: 'The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin.', }, + { + pkg: '@deepseek-ai/dsh-tool-lsp', + dir: 'tool-lsp', + source: 'packages/lsp/tool-lsp/src/index.ts', + requires: ['ctx.tools', 'ctx.lsp', 'ctx.systemPrompt'], + writes: ['tool/call', 'tool/result'], + async mount(ctx) { + // The tool registers from the seam alone; the schema does not depend on any provider. + await ctx.plugin(Lsp) + await ctx.plugin(ToolLsp) + }, + note: + 'The lsp tool keeps provider selection and language-server subprocesses behind ctx.lsp, so its model-visible schema stays stable across providers. Requires a registered provider (e.g. `@deepseek-ai/dsh-lsp-local`) at runtime; without one, a query returns the structured `LSP_UNAVAILABLE` error rather than changing the schema.', + }, { pkg: '@deepseek-ai/dsh-tool-skill', dir: 'tool-skill', diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts index 7e7c4ada82..a07a2fb797 100644 --- a/scripts/verify-package-readme-model-experience.ts +++ b/scripts/verify-package-readme-model-experience.ts @@ -47,6 +47,8 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly> = { 'packages/fs/fs-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' }, 'packages/hooks/hook-protocol': { kind: 'indirect', reason: 'Only the hook bridge plugins render decoded hook output to a model.' }, 'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' }, + 'packages/lsp/lsp': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-lsp.' }, + 'packages/lsp/lsp-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-lsp.' }, 'packages/sandbox/sandbox-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-bash-sandbox and dsh-tool-bash.' }, 'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers no model surface.' }, 'packages/skill/skill': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-skill.' }, diff --git a/tsconfig.base.json b/tsconfig.base.json index a4288b2dd3..d862549da7 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -45,6 +45,7 @@ "./packages/bash/*/src", "./packages/code-runtime/*/src", "./packages/fs/*/src", + "./packages/lsp/*/src", "./packages/skill/*/src", "./packages/compact/*/src", "./packages/context/*/src", diff --git a/tsconfig.build.json b/tsconfig.build.json index fc1e9f488e..18dbe5bc25 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -83,6 +83,9 @@ { "path": "./packages/hooks/hook-protocol" }, { "path": "./packages/hooks/hooks-claude" }, { "path": "./packages/hooks/hooks-codex" }, - { "path": "./packages/mcp/mcp-client" } + { "path": "./packages/mcp/mcp-client" }, + { "path": "./packages/lsp/lsp" }, + { "path": "./packages/lsp/lsp-local" }, + { "path": "./packages/lsp/tool-lsp" } ] } diff --git a/tsconfig.json b/tsconfig.json index 02b01678ca..d8a37f0a25 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -94,6 +94,9 @@ { "path": "./packages/hooks/hook-protocol" }, { "path": "./packages/hooks/hooks-claude" }, { "path": "./packages/hooks/hooks-codex" }, - { "path": "./packages/mcp/mcp-client" } + { "path": "./packages/mcp/mcp-client" }, + { "path": "./packages/lsp/lsp" }, + { "path": "./packages/lsp/lsp-local" }, + { "path": "./packages/lsp/tool-lsp" } ] } From 575feaddfaa61dcc281beda215cc032a49cc3aa6 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Thu, 16 Jul 2026 12:08:06 +0800 Subject: [PATCH 011/273] docs(lsp): regenerate config catalog for optional lsp-local config fields --- docs/config-catalog.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index a38130a739..b6b798b124 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -430,26 +430,26 @@ export interface Config { providerId: string /** Executable to spawn (absolute, or resolved on PATH at load). */ command: string - /** Arguments passed to the executable (no shell). */ - args: string[] - /** Extra env vars merged on top of the scrubbed ambient env. */ - env: Record /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */ extensionToLanguage: Record - /** Static `initialize` options forwarded to the server. */ - initializationOptions: unknown - /** Static answer to every `workspace/configuration` item. */ - configuration: unknown - /** Largest single framed message accepted from the server (bytes). */ - maxMessageBytes: number - /** Largest stderr tail retained for diagnostics (bytes). */ - maxStderrBytes: number - /** Largest source file this host will open (bytes). */ - maxDocumentBytes: number - /** Graceful `shutdown`/`exit` budget before escalation (ms). */ - shutdownTimeoutMs: number - /** SIGTERM→SIGKILL grace after graceful shutdown fails (ms). */ - killGraceMs: number + /** Arguments passed to the executable (no shell). Default `[]`. */ + args?: string[] + /** Extra env vars merged on top of the scrubbed ambient env. Default `{}`. */ + env?: Record + /** Static `initialize` options forwarded to the server. Default `null`. */ + initializationOptions?: unknown + /** Static answer to every `workspace/configuration` item. Default `null`. */ + configuration?: unknown + /** Largest single framed message accepted from the server (bytes). Default 16000000. */ + maxMessageBytes?: number + /** Largest stderr tail retained for diagnostics (bytes). Default 1000000. */ + maxStderrBytes?: number + /** Largest source file this host will open (bytes). Default 4000000. */ + maxDocumentBytes?: number + /** Graceful `shutdown`/`exit` budget before escalation (ms). Default 5000. */ + shutdownTimeoutMs?: number + /** SIGTERM→SIGKILL grace after graceful shutdown fails (ms). Default 2000. */ + killGraceMs?: number } ``` From 8e8f90e235dedf21872fa07e314e1d72b93bf36f Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Thu, 16 Jul 2026 13:11:07 +0800 Subject: [PATCH 012/273] fix(lsp): address codex review round 1 Lifecycle and safety fixes from the external review: - Observe abort while awaiting the initialize handshake, so a server that never replies can't defeat the tool-timeout signal. - On an aborted request the server won't cancel, tear the instance down after a bounded grace instead of releasing the serialized queue with work still live (prevents overlapping document lifecycles). - Re-check provider disposal after the canonicalize/read awaits so a query can't spawn an unowned server after disposeAll(). - Read the source through one open handle (stat + read on the same fd) to close the realpath-vs-read TOCTOU; decode with a fatal UTF-8 decoder so a legitimate U+FFFD is not misclassified as invalid. - Validate and read the source BEFORE spawning a server (pre-start rejection). - Require an explicit openClose for option-form textDocumentSync. - Reject nonpositive teardown budgets and non-executable absolute commands at load; surface unsupported operations as structured LSP_UNSUPPORTED_OPERATION. - Retain the stderr tail (fatal diagnostics land at exit), not the prefix. - Catalog the seam vocabulary in docs/core-data-structures/lsp.md. --- docs/core-data-structures/core.md | 1 + docs/core-data-structures/lsp.md | 124 +++ packages/lsp/lsp-local/src/connection.ts | 5 +- packages/lsp/lsp-local/src/host.ts | 36 +- packages/lsp/lsp-local/src/index.ts | 37 +- packages/lsp/lsp-local/src/instance.ts | 83 +- packages/lsp/lsp-local/src/translate.ts | 10 +- packages/lsp/lsp-local/tests/host.spec.ts | 8 + packages/lsp/lsp-local/tests/instance.spec.ts | 89 +- packages/lsp/lsp-local/tests/provider.spec.ts | 27 + .../lsp/lsp-local/tests/translate.spec.ts | 6 +- scripts/type-equiv.manifest.json | 830 +++++++++++++++--- 12 files changed, 1038 insertions(+), 218 deletions(-) create mode 100644 docs/core-data-structures/lsp.md diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index 8926a8a998..622f91a7c9 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -28,6 +28,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t | [sandbox.md](sandbox.md) | the process-confinement seam: file-effect modes, `SandboxPolicy`, `ConfinedArgv`, enforcement and fail-closed errors | | [code-runtime.md](code-runtime.md) | the code-execution seam: `CodeRunRequest`/`Result`, binding namespaces, captured logs, the `CodeRunFailure` taxonomy | | [filesystem.md](filesystem.md) | the filesystem seam: `FsTarget`, read/write/edit outcomes, observed-file state, `FsErrorCode` | +| [lsp.md](lsp.md) | the LSP navigation seam: `LspQueryRequest`/`Result`, `LspProvider`/`Service`, four operations, `LspError` | | [skills.md](skills.md) | the skill service: discovery priority, `SkillSummary`/`SkillDefinition`, session-prefix catalog, model-facing `skill` loading | | [compaction.md](compaction.md) | the compaction seam: the `compact/*` session events, `CompactionResult`, the `CompactService` interface | | [subagent.md](subagent.md) | the subagent seam: the named-provider registry, `SubagentStartRequest`/`Result`/`Run`, the start-time-vs-runtime capability split | diff --git a/docs/core-data-structures/lsp.md b/docs/core-data-structures/lsp.md new file mode 100644 index 0000000000..25b98a9e59 --- /dev/null +++ b/docs/core-data-structures/lsp.md @@ -0,0 +1,124 @@ +# LSP navigation + +The LSP seam — a [capability seam](../rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md) exposing semantic code navigation on one `ctx.lsp` service, split across packages: interface ([dsh-lsp](../../packages/lsp/lsp), `ctx.lsp` + the provider registry), a generic implementation ([dsh-lsp-local](../../packages/lsp/lsp-local), a configured stdio language-server host), and consumer ([dsh-tool-lsp](../../packages/lsp/tool-lsp), the `lsp` tool schema). LSP is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). A provider swap does not change how the model asks for navigation. + +Source: [`packages/lsp/lsp/src/types.ts`](../../packages/lsp/lsp/src/types.ts) + +## Operations and coordinates + +The seam and model expose exactly four semantic queries; the union is closed, so adding one is a compile-enforced change across the seam, providers, and the tool. Positions and ranges are zero-based UTF-16, matching the protocol; the model-facing tool owns the one-based cursor convention and converts on the way in and out. + +```ts type-equiv +type LspOperation = 'definition' | 'references' | 'implementation' | 'hover' +``` + +```ts type-equiv +interface LspPosition { + /** Zero-based line. */ + readonly line: number + /** Zero-based UTF-16 code-unit offset within the line. */ + readonly character: number +} +``` + +```ts type-equiv +interface LspRange { + readonly start: LspPosition + readonly end: LspPosition +} +``` + +## Request + +Every field is required: `workspaceRoot` is caller-supplied, `languageId` comes from the provider's registration (not the request), and consumers own timeouts and result limits — so no field needs implementation defaulting and there is no `resolve()` step. The provider receives the caller's request plus the derived `languageId`, which only synchronizes the transient document and never participates in selection. + +```ts type-equiv +interface LspQueryRequest { + /** Which semantic query to run. */ + readonly operation: LspOperation + /** The source file to query (relative to `workspaceRoot` or absolute; the provider canonicalizes). */ + readonly filePath: string + /** The zero-based UTF-16 cursor position to query at. */ + readonly position: LspPosition + /** The workspace root the provider resolves against and indexes; required, never defaulted. */ + readonly workspaceRoot: string +} +``` + +```ts type-equiv +interface LspProviderQuery extends LspQueryRequest { + /** The LSP language id for `filePath`, from this provider's extension mapping. */ + readonly languageId: string +} +``` + +## Result + +A CLOSED discriminated union: navigation operations normalize to `locations`, `hover` to content or `null`. Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled. `references` always includes declarations — the provider enforces this internally, so callers get no flag. + +```ts type-equiv +interface LspLocation { + /** The target document URI (`file:` or otherwise), verbatim from the server. */ + readonly uri: string + /** The range within the target document. */ + readonly range: LspRange +} +``` + +```ts type-equiv +interface LspHover { + /** The normalized hover text (markdown or plaintext, provider-joined). */ + readonly contents: string + /** The range the hover applies to, when the server supplied one. */ + readonly range?: LspRange +} +``` + +```ts type-equiv +type LspQueryResult = + | { readonly kind: 'locations'; readonly locations: readonly LspLocation[] } + | { readonly kind: 'hover'; readonly hover: LspHover | null } +``` + +## Provider and service + +A provider owns a stable branded `id` and an exclusive lowercase leading-dot extension map. `registerProvider` reserves the id and every extension atomically — an invalid or conflicting registration publishes nothing — and its disposer releases all reservations. Selection is per query and order-independent; no match throws `LspError` `LSP_UNAVAILABLE`. The seam exposes no protocol types, process/document controls, or generic JSON-RPC escape hatch. + +```ts type-equiv +interface LspProvider { + /** Stable provider identity, reserved atomically with the extension mappings. */ + readonly id: LspProviderId + /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */ + readonly extensionToLanguage: Readonly> + /** + * Run one query. The seam has already selected this provider and derived `languageId`. + * @param request - the resolved provider query (caller request + derived language id). + * @param signal - optional cancellation; the provider stops its own work when it aborts. + * @returns the normalized, closed-union result. + */ + query(request: LspProviderQuery, signal?: AbortSignal): Promise +} +``` + +```ts type-equiv +interface LspService { + /** + * Register a provider, atomically reserving its id and every normalized extension. Any conflict + * or invalid input publishes nothing and throws `LspError`; the returned disposer releases all + * reservations. Disposed with the calling fiber. + * @param provider - the backend to register. + * @returns a synchronous disposer releasing the id and all extension reservations. + */ + registerProvider(provider: LspProvider): () => void + /** + * Select a provider by the file's extension and run one query. Selection is per-query and + * order-independent; no match throws `LspError` `LSP_UNAVAILABLE`. + * @param request - the normalized query. + * @param signal - optional cancellation forwarded to the selected provider. + * @returns the normalized, closed-union result. + */ + query(request: LspQueryRequest, signal?: AbortSignal): Promise +} +``` + +`LspProviderId` is the seam's branded id (`Branded<'LspProviderId'>` from [dsh-brand](../../packages/util/brand)); `LspError` extends `HarnessError` with a stable `code` (`LSP_INVALID_PROVIDER`, `LSP_CONFLICT`, `LSP_UNAVAILABLE`, `LSP_UNSUPPORTED_OPERATION`) callers route on instead of parsing `message`. diff --git a/packages/lsp/lsp-local/src/connection.ts b/packages/lsp/lsp-local/src/connection.ts index 1eeb430d22..4f1f4d9b3a 100644 --- a/packages/lsp/lsp-local/src/connection.ts +++ b/packages/lsp/lsp-local/src/connection.ts @@ -174,8 +174,9 @@ export class LspConnection { } private onStderr(chunk: Buffer): void { - if (this.stderr.length >= this.spec.maxStderrBytes) return - this.stderr = (this.stderr + chunk.toString('utf8')).slice(0, this.spec.maxStderrBytes) + // Retain the TAIL, not the prefix: a language server's fatal diagnostic usually appears just + // before it exits, so the final bounded segment is the useful one. + this.stderr = (this.stderr + chunk.toString('utf8')).slice(-this.spec.maxStderrBytes) } private dispatch(message: unknown): void { diff --git a/packages/lsp/lsp-local/src/host.ts b/packages/lsp/lsp-local/src/host.ts index a90a703d96..8638926860 100644 --- a/packages/lsp/lsp-local/src/host.ts +++ b/packages/lsp/lsp-local/src/host.ts @@ -9,7 +9,7 @@ * @module @deepseek-ai/dsh-lsp-local/host */ -import { readFile, realpath, stat } from 'node:fs/promises' +import { open, realpath, stat } from 'node:fs/promises' import { isAbsolute, resolve as resolvePath, sep } from 'node:path' /** A validated source: its canonical absolute path and current UTF-8 text. */ @@ -68,16 +68,24 @@ export async function readHostSource( if (!isInside(canonicalWorkspace, canonicalPath)) { throw new Error(`source "${filePath}" resolves outside the workspace`) } - const info = await stat(canonicalPath) - if (!info.isFile()) { - throw new Error(`source "${filePath}" is not a regular file`) + // Open ONE handle after containment, then stat and read through it: a concurrent replace between + // realpath and read cannot swap the target, so the regular-file and size checks bind the bytes we + // actually read (no path-based TOCTOU). + const handle = await open(canonicalPath, 'r') + try { + const info = await handle.stat() + if (!info.isFile()) { + throw new Error(`source "${filePath}" is not a regular file`) + } + if (info.size > maxDocumentBytes) { + throw new Error(`source "${filePath}" is ${info.size} bytes, over the ${maxDocumentBytes}-byte limit`) + } + const buffer = await handle.readFile() + const text = decodeUtf8Strict(buffer, filePath) + return { canonicalPath, text } + } finally { + await handle.close() } - if (info.size > maxDocumentBytes) { - throw new Error(`source "${filePath}" is ${info.size} bytes, over the ${maxDocumentBytes}-byte limit`) - } - const buffer = await readFile(canonicalPath) - const text = decodeUtf8Strict(buffer, filePath) - return { canonicalPath, text } } /** Whether `child` is the workspace itself or a descendant of it (both already canonical). */ @@ -88,13 +96,13 @@ function isInside(workspace: string, child: string): boolean { return child.startsWith(base) } -/** Decode UTF-8 strictly (a replacement char means the source was not valid UTF-8 text). */ +/** Decode strictly as UTF-8: a fatal decoder rejects only malformed bytes, keeping a legitimate U+FFFD. */ function decodeUtf8Strict(buffer: Buffer, filePath: string): string { - const text = buffer.toString('utf8') - if (text.includes('�')) { + try { + return new TextDecoder('utf-8', { fatal: true }).decode(buffer) + } catch { throw new Error(`source "${filePath}" is not valid UTF-8 text`) } - return text } /** Extract a message from an unknown thrown value without leaking `any`. */ diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts index b9c32867da..598254f937 100644 --- a/packages/lsp/lsp-local/src/index.ts +++ b/packages/lsp/lsp-local/src/index.ts @@ -23,7 +23,7 @@ import type { } from '@deepseek-ai/dsh-lsp' // Side-effect type import: declaration-merges `ctx.lsp` onto Context. import type {} from '@deepseek-ai/dsh-lsp' -import { canonicalizeWorkspace } from './host.ts' +import { canonicalizeWorkspace, readHostSource } from './host.ts' import { LspInstance } from './instance.ts' import type { InstanceSpec } from './instance.ts' @@ -110,6 +110,10 @@ export const Config: z = z.object({ */ export function apply(ctx: Context, config: Config): void { const resolved = config as ResolvedConfig + // Teardown budgets feed `deadline()`, whose `<= 0` is the internal no-timeout sentinel; a + // nonpositive value would let a server that ignores shutdown hang disposal forever. Fail at load. + assertPositiveInteger('shutdownTimeoutMs', resolved.shutdownTimeoutMs) + assertPositiveInteger('killGraceMs', resolved.killGraceMs) const childEnv = buildChildEnv(resolved.env) // Resolve the executable eagerly so a misconfigured command fails at load, not on first query. const executable = resolveExecutable(resolved.command, childEnv) @@ -124,6 +128,13 @@ export function apply(ctx: Context, config: Config): void { }, 'lsp-local.registerProvider') } +/** Reject a nonpositive or non-integer config value at load, so misconfiguration fails loud. */ +function assertPositiveInteger(name: string, value: number): void { + if (!Number.isInteger(value) || value < 1) { + throw new Error(`lsp-local: ${name} must be a positive integer`) + } +} + /** A pooled generic provider: one server process per canonical workspace, created on demand. */ class LocalLspProvider implements LspProvider { readonly id: LspProviderId @@ -141,13 +152,26 @@ class LocalLspProvider implements LspProvider { this.extensionToLanguage = config.extensionToLanguage } + /** Read the disposed flag through a method so a `query()` await cannot narrow it to a literal. */ + private isDisposed(): boolean { + return this.disposed + } + async query(request: LspProviderQuery, signal?: AbortSignal): Promise { - /* v8 ignore next -- the seam unregisters this provider on dispose, so a query never reaches a disposed provider; defensive. */ - if (this.disposed) throw new Error('lsp-local provider is disposed') + /* v8 ignore next -- the seam unregisters this provider on dispose, so a query never reaches it disposed; defensive. */ + if (this.isDisposed()) throw new Error('lsp-local provider is disposed') const workspace = await canonicalizeWorkspace(request.workspaceRoot) + // Validate and read the source BEFORE spawning a server: a missing/external/non-regular/oversized + // source must fail without leaving an idle process pooled (the pre-start rejection contract), and + // the single-handle read preserves the containment/size checks against a mid-read swap. + const source = await readHostSource(request.filePath, workspace, this.config.maxDocumentBytes) + // Re-check disposal after the awaits: disposeAll() may have snapshotted the instance map while we + // were canonicalizing/reading, so creating a server now would leave it unowned by teardown. + /* v8 ignore next -- guards a dispose landing during the canonicalize/read await; not a reproducible unit race. */ + if (this.isDisposed()) throw new Error('lsp-local provider is disposed') const instance = await this.instanceFor(workspace) try { - return await instance.query(request, signal) + return await instance.query(request, source, signal) } finally { // A crashed/closed process must not be reused: drop its slot so the next query starts fresh, // but only if the slot still holds THIS instance (a concurrent replacement must survive). @@ -185,7 +209,6 @@ class LocalLspProvider implements LspProvider { initializationOptions: this.config.initializationOptions, maxMessageBytes: this.config.maxMessageBytes, maxStderrBytes: this.config.maxStderrBytes, - maxDocumentBytes: this.config.maxDocumentBytes, shutdownTimeoutMs: this.config.shutdownTimeoutMs, killGraceMs: this.config.killGraceMs, } @@ -232,6 +255,10 @@ function buildChildEnv(extra: Record): Record { */ function resolveExecutable(command: string, childEnv: Record): string { if (isAbsolute(command)) { + // Verify an absolute command too, so an unavailable one fails at load, not on the first query. + if (!isExecutableSync(command)) { + throw new Error(`lsp-local: command "${command}" is not an executable file`) + } return command } /* v8 ignore next -- buildChildEnv always sets PATH from the ambient env; the further fallbacks are defensive. */ diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts index 0e63e46d1e..83266e9c8f 100644 --- a/packages/lsp/lsp-local/src/instance.ts +++ b/packages/lsp/lsp-local/src/instance.ts @@ -8,6 +8,7 @@ */ import { pathToFileURL } from 'node:url' +import { LspError } from '@deepseek-ai/dsh-lsp' import type { LspOperation, LspProviderQuery, @@ -16,7 +17,7 @@ import type { import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout' import { LspConnection } from './connection.ts' import type { ConnectionSpec } from './connection.ts' -import { readHostSource } from './host.ts' +import type { HostSource } from './host.ts' import type { WireInitializeResult, WireServerCapabilities } from './protocol.ts' import { negotiatePositionEncoding, @@ -31,8 +32,6 @@ import { export interface InstanceSpec extends ConnectionSpec { /** Static `initialize` options forwarded to the server. */ readonly initializationOptions: unknown - /** Largest source file this host will open (bytes). */ - readonly maxDocumentBytes: number /** Graceful `shutdown`/`exit` budget before escalation (ms). */ readonly shutdownTimeoutMs: number /** SIGTERM→SIGKILL grace after graceful shutdown fails (ms). */ @@ -74,11 +73,12 @@ export class LspInstance { /** * Run one query through the serialized queue. * @param request - the resolved provider query. + * @param source - the pre-validated, already-read host source (the provider reads before spawning). * @param signal - optional cancellation for this query's full lifecycle. * @returns the normalized result. */ - query(request: LspProviderQuery, signal?: AbortSignal): Promise { - const run = this.queue.then(() => this.runQuery(request, signal)) + query(request: LspProviderQuery, source: HostSource, signal?: AbortSignal): Promise { + const run = this.queue.then(() => this.runQuery(request, source, signal)) // Keep the tail alive regardless of this query's outcome so the next caller still serializes. this.queue = run.then(() => undefined, () => undefined) return run @@ -99,24 +99,26 @@ export class LspInstance { this.connection.notify('initialized', {}) } - private async runQuery(request: LspProviderQuery, signal?: AbortSignal): Promise { + private async runQuery(request: LspProviderQuery, source: HostSource, signal?: AbortSignal): Promise { if (this.disposed) throw new Error('LSP instance was disposed') if (signal?.aborted) throw abortError(signal) - await this.ready + // Observe abort during the handshake wait: a server that never answers `initialize` must not + // block the tool-timeout signal here (the timeout policy awaits our quiescence, not the promise). + await this.abortable(this.ready, signal) const capabilities = this.capabilities /* v8 ignore next -- `ready` resolves only after capabilities are set, else it rejects above; defensive. */ if (capabilities === undefined) throw new Error('LSP instance is not initialized') if (!supportsOperation(capabilities, request.operation)) { - throw new Error(`server does not support ${request.operation}`) + throw new LspError(`server does not support ${request.operation}`, 'LSP_UNSUPPORTED_OPERATION') } if (!supportsTransientOpen(capabilities.textDocumentSync)) { - throw new Error('server does not support the transient textDocument/didOpen this host requires') + throw new LspError('server does not support the transient textDocument/didOpen this host requires', 'LSP_UNSUPPORTED_OPERATION') } - const source = await readHostSource(request.filePath, this.spec.cwd, this.spec.maxDocumentBytes) const uri = pathToFileURL(source.canonicalPath).href let opened = false try { + /* v8 ignore next -- guards an abort landing between the ready wait and didOpen; not deterministically reproducible. */ if (signal?.aborted) throw abortError(signal) this.connection.notify('textDocument/didOpen', { textDocument: { uri, languageId: request.languageId, version: 1, text: source.text }, @@ -125,7 +127,10 @@ export class LspInstance { const payload = await this.sendRequest(request.operation, uri, request.position, signal) return this.normalize(request.operation, payload) } finally { - if (opened) { + // A disposed or closed instance (e.g. an aborted request whose server ignored + // `$/cancelRequest`) is already tearing down; sending didClose would race that teardown and let + // the next queued query's document lifecycle overlap the still-active request. + if (opened && !this.dead) { try { this.connection.notify('textDocument/didClose', { textDocument: { uri } }) } catch (error) { @@ -141,6 +146,21 @@ export class LspInstance { } } + /** + * Await `work`, but reject as soon as `signal` aborts. The underlying `work` promise keeps its own + * handlers, so an orphaned rejection after abort is not unhandled. + */ + private abortable(work: Promise, signal: AbortSignal | undefined): Promise { + if (signal === undefined) return work + /* v8 ignore next -- runQuery checks signal.aborted before each abortable() call, so it is not already aborted here; defensive. */ + if (signal.aborted) return Promise.reject(abortError(signal)) + return new Promise((resolve, reject) => { + const onAbort = (): void => { reject(abortError(signal)) } + signal.addEventListener('abort', onAbort, { once: true }) + work.then(resolve, reject).finally(() => { signal.removeEventListener('abort', onAbort) }) + }) + } + private async sendRequest( operation: LspOperation, uri: string, @@ -160,21 +180,33 @@ export class LspInstance { return this.raceAbort(send, requestId, signal) } - /** Race a pending request against abort; on abort, send `$/cancelRequest` and reject. */ + /** + * Race a pending request against abort. On abort, send `$/cancelRequest` and give the server a + * bounded grace to acknowledge; if it does not settle in time, invalidate and tear down the + * instance so the still-active request cannot overlap the next queued query's document lifecycle. + */ private async raceAbort(send: Promise, requestId: number, signal: AbortSignal): Promise { - const abort = new Promise((_, reject) => { - const onAbort = (): void => { reject(abortError(signal)) } - /* v8 ignore next -- runQuery checks signal.aborted before sending, so it is not yet aborted here; defensive. */ - if (signal.aborted) { onAbort(); return } - signal.addEventListener('abort', onAbort, { once: true }) - // Remove the abort listener once the request settles either way; the finally-promise inherits - // send's rejection, so catch it to avoid an unhandled rejection when abort already won. - send.finally(() => { signal.removeEventListener('abort', onAbort) }).catch(() => {}) - }) try { - return await Promise.race([send, abort]) + return await this.abortable(send, signal) } catch (error) { - if (signal.aborted) this.connection.cancel(requestId) + if (!signal.aborted) throw error + this.connection.cancel(requestId) + // Wait, bounded, for the server to honor the cancellation. If it does not, the request is still + // running: terminate the instance (disposal awaits process close) so nothing outlives the query. + using grace = deadline(undefined, this.spec.killGraceMs, 'LSP_CANCEL_GRACE') + // `settled` is true if the request finished (either outcome) before the grace elapsed. + const settled = await Promise.race([ + send.then(markSettled, markSettled), + new Promise((resolve) => { + /* v8 ignore next -- the cancel-grace deadline signal is freshly armed and not yet aborted here; defensive. */ + if (grace.signal.aborted) { resolve(false); return } + grace.signal.addEventListener('abort', () => { resolve(false) }, { once: true }) + }), + ]) + if (!settled && !this.disposed) { + this.disposed = true + await this.tearDown(abortError(signal)) + } throw error } } @@ -266,6 +298,11 @@ const LIFECYCLE_NOOP_METHODS = new Set([ 'client/unregisterCapability', ]) +/** Mark a settled request in the cancel-grace race (either outcome means the request finished). */ +function markSettled(): boolean { + return true +} + /** Build an abort Error carrying the signal's reason (preserving a timeout classification). */ function abortError(signal: AbortSignal): Error { const timeout = timeoutOf(signal) diff --git a/packages/lsp/lsp-local/src/translate.ts b/packages/lsp/lsp-local/src/translate.ts index a212d283b6..a208c3bedf 100644 --- a/packages/lsp/lsp-local/src/translate.ts +++ b/packages/lsp/lsp-local/src/translate.ts @@ -21,7 +21,6 @@ import type { WireRange, WireServerCapabilities, WireTextDocumentSyncKind, - WireTextDocumentSyncOptions, } from './protocol.ts' /** @@ -71,13 +70,15 @@ export function supportsOperation(capabilities: WireServerCapabilities, operatio /** * Whether a `textDocumentSync` value permits the transient `didOpen`/`didClose` this host relies on. + * The legacy enum form implies open/close for `Full`/`Incremental`; the options form requires an + * explicit `openClose: true`, because the protocol defaults an omitted `openClose` to false. * @param sync - the server's advertised `textDocumentSync` capability. * @returns true when transient open/close is supported. */ export function supportsTransientOpen(sync: WireServerCapabilities['textDocumentSync']): boolean { if (sync === undefined) return false if (typeof sync === 'number') return isOpenCloseKind(sync) - return sync.openClose === true || (sync.openClose === undefined && changeAllowsOpenClose(sync)) + return sync.openClose === true } /** Legacy enum: `Full` (1) or `Incremental` (2) imply open/close support; `None` (0) does not. */ @@ -85,11 +86,6 @@ function isOpenCloseKind(kind: WireTextDocumentSyncKind): boolean { return kind === 1 || kind === 2 } -/** Options without an explicit `openClose` fall back to the legacy `change` enum's implication. */ -function changeAllowsOpenClose(sync: WireTextDocumentSyncOptions): boolean { - return sync.change !== undefined && isOpenCloseKind(sync.change) -} - /** * Normalize the negotiated position encoding. An omitted encoding defaults to `utf-16`; any value * other than `utf-16` is a protocol error this host does not support. diff --git a/packages/lsp/lsp-local/tests/host.spec.ts b/packages/lsp/lsp-local/tests/host.spec.ts index b76aa556e2..3fb9f804ac 100644 --- a/packages/lsp/lsp-local/tests/host.spec.ts +++ b/packages/lsp/lsp-local/tests/host.spec.ts @@ -102,4 +102,12 @@ describe('readHostSource', () => { await writeFile(join(ws, 'bin.ts'), Buffer.from([0xff, 0xfe, 0x00])) await expect(readHostSource('bin.ts', ws, BIG)).rejects.toThrow(/not valid UTF-8/) }) + + it('keeps a valid U+FFFD replacement character in otherwise-valid UTF-8', async () => { + // The literal replacement char is valid UTF-8; a fatal decoder must accept it (only malformed + // byte sequences are rejected). + await writeFile(join(ws, 'repl.ts'), 'const s = "�"\n') + const source = await readHostSource('repl.ts', ws, BIG) + expect(source.text).toBe('const s = "�"\n') + }) }) diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts index da3231f133..83c4bdfe77 100644 --- a/packages/lsp/lsp-local/tests/instance.spec.ts +++ b/packages/lsp/lsp-local/tests/instance.spec.ts @@ -3,9 +3,9 @@ import { mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' import { pathToFileURL, fileURLToPath } from 'node:url' -import { LspInstance } from '@deepseek-ai/dsh-lsp-local' +import { LspInstance, readHostSource } from '@deepseek-ai/dsh-lsp-local' import type { InstanceSpec } from '@deepseek-ai/dsh-lsp-local/src/instance.ts' -import type { LspProviderQuery } from '@deepseek-ai/dsh-lsp' +import type { LspProviderQuery, LspQueryResult } from '@deepseek-ai/dsh-lsp' const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url)) @@ -38,7 +38,6 @@ function makeInstance(env: Record = {}, overrides: Partial { + const source = await readHostSource('a.ts', ws, 4_000_000) + return instance.query(query(operation), source, signal) +} + /** Build an instance whose "server" is an inline node script (for teardown-escalation control). */ function scriptInstance(script: string, overrides: Partial = {}): LspInstance { const instance = new LspInstance({ @@ -62,7 +67,6 @@ function scriptInstance(script: string, overrides: Partial = {}): initializationOptions: null, maxMessageBytes: 16_000_000, maxStderrBytes: 100_000, - maxDocumentBytes: 4_000_000, shutdownTimeoutMs: 150, killGraceMs: 150, ...overrides, @@ -87,51 +91,98 @@ describe('LspInstance server-request handling', () => { const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'configuration', LSP_FAKE_DEF: locJson() }) // The query drives didOpen, which makes the fake emit workspace/configuration; a healthy answer // keeps the query working. - await expect(instance.query(query('definition'))).resolves.toMatchObject({ kind: 'locations' }) + await expect(run(instance, 'definition')).resolves.toMatchObject({ kind: 'locations' }) }) it('accepts a lifecycle client/registerCapability request', async () => { const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'lifecycle', LSP_FAKE_DEF: 'null' }) - await expect(instance.query(query('definition'))).resolves.toEqual({ kind: 'locations', locations: [] }) + await expect(run(instance, 'definition')).resolves.toEqual({ kind: 'locations', locations: [] }) }) it('rejects a workspace/applyEdit request but keeps serving', async () => { const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'applyEdit', LSP_FAKE_DEF: 'null' }) - await expect(instance.query(query('definition'))).resolves.toEqual({ kind: 'locations', locations: [] }) + await expect(run(instance, 'definition')).resolves.toEqual({ kind: 'locations', locations: [] }) }) it('rejects an unknown server request but keeps serving', async () => { const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'unknown', LSP_FAKE_DEF: 'null' }) - await expect(instance.query(query('definition'))).resolves.toEqual({ kind: 'locations', locations: [] }) + await expect(run(instance, 'definition')).resolves.toEqual({ kind: 'locations', locations: [] }) }) }) describe('LspInstance query and abort', () => { it('sends includeDeclaration for references', async () => { const instance = makeInstance({ LSP_FAKE_REFS: JSON.stringify([JSON.parse(locJson())]) }) - await expect(instance.query(query('references'))).resolves.toMatchObject({ kind: 'locations' }) + await expect(run(instance, 'references')).resolves.toMatchObject({ kind: 'locations' }) }) it('rejects a query aborted before it starts', async () => { const instance = makeInstance({ LSP_FAKE_DEF: 'null' }) const controller = new AbortController() controller.abort(new Error('pre-abort')) - await expect(instance.query(query('definition'), controller.signal)).rejects.toThrow(/pre-abort/) + await expect(run(instance, 'definition', controller.signal)).rejects.toThrow(/pre-abort/) }) it('cancels an in-flight request on abort and rejects', async () => { const instance = makeInstance({ LSP_FAKE_HANG: '1' }) const controller = new AbortController() // Warm the instance first so the abort lands during the hanging request, not during startup. - const pending = instance.query(query('definition'), controller.signal) + const pending = run(instance, 'definition', controller.signal) await new Promise(resolve => setTimeout(resolve, 300)) controller.abort(new Error('mid-flight')) await expect(pending).rejects.toThrow(/mid-flight/) }) + it('terminates the instance when the server ignores $/cancelRequest past the grace', async () => { + // The hang server never honors cancellation, so after the bounded grace the instance must be torn + // down (its process closed) rather than left with an active request. + const instance = makeInstance({ LSP_FAKE_HANG: '1' }, { killGraceMs: 100 }) + const controller = new AbortController() + const pending = run(instance, 'definition', controller.signal) + await new Promise(resolve => setTimeout(resolve, 300)) + controller.abort(new Error('mid-flight')) + await expect(pending).rejects.toThrow(/mid-flight/) + expect(instance.dead).toBe(true) + }) + + it('resolves the cancel grace when the server honors $/cancelRequest', async () => { + // A server that answers $/cancelRequest by settling the pending request lets the grace race + // resolve via the request rather than the timeout, so the instance is NOT force-terminated. + const script = 'let b=Buffer.alloc(0),reqId=null;' + + 'const fr=(o)=>{const x=Buffer.from(JSON.stringify({jsonrpc:"2.0",...o}));return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};' + + 'process.stdin.on("data",c=>{b=Buffer.concat([b,c]);for(;;){const s=b.indexOf("\\r\\n\\r\\n");if(s<0)break;const len=Number(/(\\d+)/.exec(b.toString("ascii",0,s))[1]);if(b.length(resolve => setTimeout(resolve, 300)) + controller.abort(new Error('mid-flight')) + await expect(pending).rejects.toThrow(/mid-flight/) + // The server acknowledged cancellation within grace, so the instance was not force-killed. + expect(instance.dead).toBe(false) + await instance.dispose() + }) + + it('observes abort while awaiting a slow initialize handshake', async () => { + // A server that answers nothing (not even initialize) leaves `ready` pending; an abort must be + // observed during that wait instead of hanging the tool-timeout signal. + const instance = scriptInstance('setInterval(()=>{},1000)', { killGraceMs: 100 }) + const controller = new AbortController() + const pending = run(instance, 'definition', controller.signal) + await new Promise(resolve => setTimeout(resolve, 150)) + controller.abort(new Error('handshake-abort')) + await expect(pending).rejects.toThrow(/handshake-abort/) + await instance.dispose() + }) + it('rejects when the server lacks the operation capability', async () => { const instance = makeInstance({ LSP_FAKE_CAPS: JSON.stringify({ definitionProvider: false }), LSP_FAKE_DEF: 'null' }) - await expect(instance.query(query('definition'))).rejects.toThrow(/does not support definition/) + await expect(run(instance, 'definition')).rejects.toThrow(/does not support definition/) }) it('propagates a server error response even when a signal is supplied (not an abort)', async () => { @@ -139,28 +190,28 @@ describe('LspInstance query and abort', () => { // without treating it as an abort. const instance = makeInstance({ LSP_FAKE_ERROR: '1' }) const controller = new AbortController() - await expect(instance.query(query('definition'), controller.signal)).rejects.toThrow(/server refused/) + await expect(run(instance, 'definition', controller.signal)).rejects.toThrow(/server refused/) }) }) describe('LspInstance disposal', () => { it('is idempotent — a second dispose awaits close without error', async () => { const instance = makeInstance({ LSP_FAKE_DEF: 'null' }) - await instance.query(query('definition')) + await run(instance, 'definition') await instance.dispose() await expect(instance.dispose()).resolves.toBeUndefined() }) it('rejects a query after disposal', async () => { const instance = makeInstance({ LSP_FAKE_DEF: 'null' }) - await instance.query(query('definition')) + await run(instance, 'definition') await instance.dispose() - await expect(instance.query(query('definition'))).rejects.toThrow(/disposed/) + await expect(run(instance, 'definition')).rejects.toThrow(/disposed/) }) it('reports dead after the process closes', async () => { const instance = makeInstance({ LSP_FAKE_DEF: 'null' }) - await instance.query(query('definition')) + await run(instance, 'definition') await instance.dispose() expect(instance.dead).toBe(true) }) @@ -169,14 +220,14 @@ describe('LspInstance disposal', () => { // Server answers initialize, ignores shutdown, and traps SIGTERM so only SIGKILL stops it. const script = RESPONDING_SERVER + 'process.on("SIGTERM",()=>{});' const instance = scriptInstance(script, { shutdownTimeoutMs: 100, killGraceMs: 100 }) - await instance.query(query('definition')) + await run(instance, 'definition') await expect(instance.dispose()).resolves.toBeUndefined() }) it('carries a non-Error abort reason as a generic aborted error', async () => { const instance = makeInstance({ LSP_FAKE_HANG: '1' }) const controller = new AbortController() - const pending = instance.query(query('definition'), controller.signal) + const pending = run(instance, 'definition', controller.signal) await new Promise(resolve => setTimeout(resolve, 200)) controller.abort('a string reason, not an Error') await expect(pending).rejects.toThrow(/aborted/) diff --git a/packages/lsp/lsp-local/tests/provider.spec.ts b/packages/lsp/lsp-local/tests/provider.spec.ts index 5d4045f507..20978df8d5 100644 --- a/packages/lsp/lsp-local/tests/provider.spec.ts +++ b/packages/lsp/lsp-local/tests/provider.spec.ts @@ -75,4 +75,31 @@ describe('lsp-local provider resolution', () => { await expect(lsp.query(query())).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' })) await ctx.fiber.dispose() }) + + it('rejects a nonpositive teardown budget at load', async () => { + const ctx = new Context() + await ctx.plugin(Lsp) + await expect(ctx.plugin(LspLocal, { + providerId: 'bad-budget', + command: process.execPath, + args: ['-e', ''], + extensionToLanguage: { '.ts': 'typescript' }, + killGraceMs: 0, + })).rejects.toThrow(/killGraceMs must be a positive integer/) + await ctx.fiber.dispose() + }) + + it('rejects an absolute command that is not executable at load', async () => { + const notExe = join(root, 'not-exe.txt') + await writeFile(notExe, 'plain text, not executable') + const ctx = new Context() + await ctx.plugin(Lsp) + await expect(ctx.plugin(LspLocal, { + providerId: 'abs-bad', + command: notExe, + args: [], + extensionToLanguage: { '.ts': 'typescript' }, + })).rejects.toThrow(/is not an executable file/) + await ctx.fiber.dispose() + }) }) diff --git a/packages/lsp/lsp-local/tests/translate.spec.ts b/packages/lsp/lsp-local/tests/translate.spec.ts index 2c339075e5..7727112089 100644 --- a/packages/lsp/lsp-local/tests/translate.spec.ts +++ b/packages/lsp/lsp-local/tests/translate.spec.ts @@ -47,9 +47,9 @@ describe('supportsTransientOpen', () => { expect(supportsTransientOpen({ openClose: false, change: 2 })).toBe(false) }) - it('falls back to the change enum when openClose is omitted', () => { - expect(supportsTransientOpen({ change: 1 })).toBe(true) - expect(supportsTransientOpen({ change: 0 })).toBe(false) + it('requires an explicit openClose for the options form (no change-enum fallback)', () => { + expect(supportsTransientOpen({ change: 1 })).toBe(false) + expect(supportsTransientOpen({ change: 2 })).toBe(false) expect(supportsTransientOpen({})).toBe(false) }) }) diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 51d98c659e..0dcd375c8a 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -1,150 +1,690 @@ { "comment": "Maps each ` ```ts type-equiv ` block (by doc + declared symbol) to the source symbol it must match verbatim. verify-type-equiv.ts enforces a 1:1 correspondence: every type-equiv block has exactly one entry here, and every entry resolves to exactly one block. Add an entry when you add a type-equiv block; remove it when you remove the block.", "entries": [ - { "doc": "docs/core-data-structures/core.md", "symbol": "Branded", "source": "packages/util/brand/src/index.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "Message", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "MessageSourceMap", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "FinishReasonMap", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "GenerateOptions", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "ToolSchema", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "LlmCallConfig", "source": "packages/llm/llm/src/call-config.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "Agent", "source": "packages/core/agent/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "HookContext", "source": "packages/core/agent/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "PromptDecision", "source": "packages/core/agent/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "ContinuationDecision", "source": "packages/core/agent/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "ContinuationStop", "source": "packages/core/agent/src/types.ts" }, - { "doc": "docs/core-data-structures/core.md", "symbol": "SessionStartSource", "source": "packages/core/agent/src/types.ts" }, - - { "doc": "docs/core-data-structures/scope.md", "symbol": "ScopeKey", "source": "packages/core/scope/src/index.ts" }, - { "doc": "docs/core-data-structures/scope.md", "symbol": "Scoped", "source": "packages/core/scope/src/index.ts" }, - { "doc": "docs/core-data-structures/scope.md", "symbol": "Scope", "source": "packages/core/scope/src/index.ts" }, - - { "doc": "docs/core-data-structures/system-prompt.md", "symbol": "AssembleContext", "source": "packages/core/system-prompt/src/index.ts" }, - { "doc": "docs/core-data-structures/system-prompt.md", "symbol": "PromptSection", "source": "packages/core/system-prompt/src/index.ts" }, - { "doc": "docs/core-data-structures/system-prompt.md", "symbol": "ToolProviderResult", "source": "packages/core/system-prompt/src/index.ts" }, - - { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "StreamChunk", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "TokenUsage", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" }, - { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "AppIdentity", "source": "packages/llm/llm/src/attribution.ts" }, - - { "doc": "docs/core-data-structures/session.md", "symbol": "SessionEventMap", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "EpochHeader", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "TodoItem", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "TurnTriggerMap", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "TurnEndReasonMap", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceEventType", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceOp", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceIntent", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceNode", "source": "packages/core/session/src/surface.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceFoldReplacement", "source": "packages/core/session/src/surface.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceFoldResult", "source": "packages/core/session/src/surface.ts" }, - - { "doc": "docs/core-data-structures/persistence.md", "symbol": "SessionHeader", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/persistence.md", "symbol": "CreateSessionOptions", "source": "packages/core/session/src/types.ts" }, - - { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventSurface", "source": "packages/session-query/session-query/src/types.ts" }, - { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionRecord", "source": "packages/session-query/session-query/src/types.ts" }, - { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventRecord", "source": "packages/session-query/session-query/src/types.ts" }, - { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionQueryErrorCode", "source": "packages/session-query/session-query/src/config.ts" }, - { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventReadRequest", "source": "packages/session-query/session-query/src/types.ts" }, - { "doc": "docs/core-data-structures/session-query.md", "symbol": "SessionEventWindow", "source": "packages/session-query/session-query/src/types.ts" }, - - { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolDefinition", "source": "packages/core/tools/src/index.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "SchemaProp", "source": "packages/core/tools/src/schema.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "SchemaSpec", "source": "packages/core/tools/src/schema.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "InferArgs", "source": "packages/core/tools/src/schema.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionToken", "source": "packages/core/tools/src/index.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionInput", "source": "packages/core/tools/src/index.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecution", "source": "packages/core/tools/src/index.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolGuard", "source": "packages/core/tools/src/index.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolRestriction", "source": "packages/core/tools/src/index.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionResult", "source": "packages/core/tools/src/index.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "PreToolDecision", "source": "packages/core/tools/src/index.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "PostToolDecision", "source": "packages/core/tools/src/index.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "StructuredScalar", "source": "packages/core/tools/src/json-schema.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "StructuredSchemaType", "source": "packages/core/tools/src/json-schema.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "StructuredSchemaNode", "source": "packages/core/tools/src/json-schema.ts" }, - { "doc": "docs/core-data-structures/tools.md", "symbol": "StructuredOutputSchema", "source": "packages/core/tools/src/json-schema.ts" }, - - { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionOption", "source": "packages/ui/user-interaction/src/index.ts" }, - { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionItem", "source": "packages/ui/user-interaction/src/index.ts" }, - { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionRequest", "source": "packages/ui/user-interaction/src/index.ts" }, - { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionAnswerItem", "source": "packages/ui/user-interaction/src/index.ts" }, - { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "AskUserQuestionAnswer", "source": "packages/ui/user-interaction/src/index.ts" }, - { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "UserInteractionProvider", "source": "packages/ui/user-interaction/src/index.ts" }, - { "doc": "docs/core-data-structures/user-interaction.md", "symbol": "UserInteractionError", "source": "packages/ui/user-interaction/src/index.ts" }, - - { "doc": "docs/core-data-structures/approval.md", "symbol": "ApprovalRequestId", "source": "packages/ui/user-approval/src/index.ts" }, - { "doc": "docs/core-data-structures/approval.md", "symbol": "ApprovalOutcome", "source": "packages/ui/user-approval/src/index.ts" }, - { "doc": "docs/core-data-structures/approval.md", "symbol": "ApprovalPolicy", "source": "packages/ui/user-approval/src/index.ts" }, - { "doc": "docs/core-data-structures/approval.md", "symbol": "ApprovalRequest", "source": "packages/ui/user-approval/src/index.ts" }, - - { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecRequest", "source": "packages/bash/bash/src/types.ts" }, - { "doc": "docs/core-data-structures/bash.md", "symbol": "BashExecSpec", "source": "packages/bash/bash/src/types.ts" }, - { "doc": "docs/core-data-structures/bash.md", "symbol": "BashRunResult", "source": "packages/bash/bash/src/types.ts" }, - { "doc": "docs/core-data-structures/bash.md", "symbol": "BashSandboxInfo", "source": "packages/bash/bash/src/types.ts" }, - { "doc": "docs/core-data-structures/bash.md", "symbol": "CollectedOutput", "source": "packages/bash/bash/src/types.ts" }, - { "doc": "docs/core-data-structures/bash.md", "symbol": "BashTask", "source": "packages/bash/bash/src/types.ts" }, - { "doc": "docs/core-data-structures/bash.md", "symbol": "BashTaskRead", "source": "packages/bash/bash/src/types.ts" }, - - { "doc": "docs/core-data-structures/sandbox.md", "symbol": "SandboxMode", "source": "packages/sandbox/sandbox/src/index.ts" }, - { "doc": "docs/core-data-structures/sandbox.md", "symbol": "ConfinedSandboxMode", "source": "packages/sandbox/sandbox/src/index.ts" }, - { "doc": "docs/core-data-structures/sandbox.md", "symbol": "SandboxEnforcement", "source": "packages/sandbox/sandbox/src/index.ts" }, - { "doc": "docs/core-data-structures/sandbox.md", "symbol": "SandboxPolicy", "source": "packages/sandbox/sandbox/src/index.ts" }, - { "doc": "docs/core-data-structures/sandbox.md", "symbol": "ConfinedArgv", "source": "packages/sandbox/sandbox/src/index.ts" }, - - { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeRunRequest", "source": "packages/code-runtime/code-runtime/src/types.ts" }, - { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeRunResult", "source": "packages/code-runtime/code-runtime/src/types.ts" }, - { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeBindingNamespace", "source": "packages/code-runtime/code-runtime/src/types.ts" }, - { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeBindingFunction", "source": "packages/code-runtime/code-runtime/src/types.ts" }, - { "doc": "docs/core-data-structures/code-runtime.md", "symbol": "CodeRunFailure", "source": "packages/code-runtime/code-runtime/src/types.ts" }, - - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsTarget", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsTargetKey", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsVersion", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsInfo", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsDirEntry", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsWriteIntent", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsWriteOutcome", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsEditRequest", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsEditOutcome", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsErrorCode", "source": "packages/fs/fs/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FsPolicyExec", "source": "packages/fs/fs-policy/src/types.ts" }, - { "doc": "docs/core-data-structures/filesystem.md", "symbol": "FileReadOutcome", "source": "packages/fs/tool-fs/src/read-render.ts" }, - - { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillSource", "source": "packages/skill/skill/src/index.ts" }, - { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillResourceBase", "source": "packages/skill/skill/src/index.ts" }, - { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillSummary", "source": "packages/skill/skill/src/index.ts" }, - { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillCandidate", "source": "packages/skill/skill/src/index.ts" }, - { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillDefinition", "source": "packages/skill/skill/src/index.ts" }, - { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillRegistration", "source": "packages/skill/skill/src/index.ts" }, - { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillLookupOptions", "source": "packages/skill/skill/src/index.ts" }, - { "doc": "docs/core-data-structures/skills.md", "symbol": "SkillProvider", "source": "packages/skill/skill/src/index.ts" }, - { "doc": "docs/core-data-structures/skills.md", "symbol": "Config", "source": "packages/skill/skill/src/index.ts" }, - - { "doc": "docs/core-data-structures/compaction.md", "symbol": "CompactionResult", "source": "packages/compact/compact/src/types.ts" }, - - { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentCapabilities", "source": "packages/subagent/subagent/src/types.ts" }, - { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentStartRequest", "source": "packages/subagent/subagent/src/types.ts" }, - { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentResult", "source": "packages/subagent/subagent/src/types.ts" }, - { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentStopReasonMap", "source": "packages/subagent/subagent/src/types.ts" }, - { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentRun", "source": "packages/subagent/subagent/src/types.ts" }, - { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentProvider", "source": "packages/subagent/subagent/src/types.ts" }, - - { "doc": "docs/core-data-structures/web.md", "symbol": "WebSearchRequest", "source": "packages/web/web/src/types.ts" }, - { "doc": "docs/core-data-structures/web.md", "symbol": "WebSearchResult", "source": "packages/web/web/src/types.ts" }, - { "doc": "docs/core-data-structures/web.md", "symbol": "WebSearchSource", "source": "packages/web/web/src/types.ts" }, - { "doc": "docs/core-data-structures/web.md", "symbol": "WebFetchRequest", "source": "packages/web/web/src/types.ts" }, - { "doc": "docs/core-data-structures/web.md", "symbol": "WebFetchResult", "source": "packages/web/web/src/types.ts" }, - { "doc": "docs/core-data-structures/web.md", "symbol": "WebFetchBody", "source": "packages/web/web/src/types.ts" }, - - { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowStartRequest", "source": "packages/workflow/workflow/src/types.ts" }, - { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowMeta", "source": "packages/workflow/workflow/src/types.ts" }, - { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowResult", "source": "packages/workflow/workflow/src/types.ts" }, - { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowRun", "source": "packages/workflow/workflow/src/types.ts" } + { + "doc": "docs/core-data-structures/core.md", + "symbol": "Branded", + "source": "packages/util/brand/src/index.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "ContentBlockMap", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "Message", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "MessageSourceMap", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "FinishReasonMap", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "GenerateOptions", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "ToolSchema", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "LlmCallConfig", + "source": "packages/llm/llm/src/call-config.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "SessionEvent", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "Agent", + "source": "packages/core/agent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "HookContext", + "source": "packages/core/agent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "PromptDecision", + "source": "packages/core/agent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "ContinuationDecision", + "source": "packages/core/agent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "ContinuationStop", + "source": "packages/core/agent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/core.md", + "symbol": "SessionStartSource", + "source": "packages/core/agent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/scope.md", + "symbol": "ScopeKey", + "source": "packages/core/scope/src/index.ts" + }, + { + "doc": "docs/core-data-structures/scope.md", + "symbol": "Scoped", + "source": "packages/core/scope/src/index.ts" + }, + { + "doc": "docs/core-data-structures/scope.md", + "symbol": "Scope", + "source": "packages/core/scope/src/index.ts" + }, + { + "doc": "docs/core-data-structures/system-prompt.md", + "symbol": "AssembleContext", + "source": "packages/core/system-prompt/src/index.ts" + }, + { + "doc": "docs/core-data-structures/system-prompt.md", + "symbol": "PromptSection", + "source": "packages/core/system-prompt/src/index.ts" + }, + { + "doc": "docs/core-data-structures/system-prompt.md", + "symbol": "ToolProviderResult", + "source": "packages/core/system-prompt/src/index.ts" + }, + { + "doc": "docs/core-data-structures/llm-streaming.md", + "symbol": "StreamChunk", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/llm-streaming.md", + "symbol": "TokenUsage", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/llm-streaming.md", + "symbol": "ContentBlockMap", + "source": "packages/llm/llm/src/types.ts" + }, + { + "doc": "docs/core-data-structures/llm-streaming.md", + "symbol": "AppIdentity", + "source": "packages/llm/llm/src/attribution.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "SessionEventMap", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "EpochHeader", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "TodoItem", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "SessionEvent", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "TurnTriggerMap", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "TurnEndReasonMap", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "SurfaceEventType", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "SurfaceOp", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "SurfaceIntent", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "SurfaceNode", + "source": "packages/core/session/src/surface.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "SurfaceFoldReplacement", + "source": "packages/core/session/src/surface.ts" + }, + { + "doc": "docs/core-data-structures/session.md", + "symbol": "SurfaceFoldResult", + "source": "packages/core/session/src/surface.ts" + }, + { + "doc": "docs/core-data-structures/persistence.md", + "symbol": "SessionHeader", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/persistence.md", + "symbol": "CreateSessionOptions", + "source": "packages/core/session/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session-query.md", + "symbol": "SessionEventSurface", + "source": "packages/session-query/session-query/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session-query.md", + "symbol": "SessionRecord", + "source": "packages/session-query/session-query/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session-query.md", + "symbol": "SessionEventRecord", + "source": "packages/session-query/session-query/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session-query.md", + "symbol": "SessionQueryErrorCode", + "source": "packages/session-query/session-query/src/config.ts" + }, + { + "doc": "docs/core-data-structures/session-query.md", + "symbol": "SessionEventReadRequest", + "source": "packages/session-query/session-query/src/types.ts" + }, + { + "doc": "docs/core-data-structures/session-query.md", + "symbol": "SessionEventWindow", + "source": "packages/session-query/session-query/src/types.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "ToolDefinition", + "source": "packages/core/tools/src/index.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "SchemaProp", + "source": "packages/core/tools/src/schema.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "SchemaSpec", + "source": "packages/core/tools/src/schema.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "InferArgs", + "source": "packages/core/tools/src/schema.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "ToolExecutionToken", + "source": "packages/core/tools/src/index.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "ToolExecutionInput", + "source": "packages/core/tools/src/index.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "ToolExecution", + "source": "packages/core/tools/src/index.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "ToolGuard", + "source": "packages/core/tools/src/index.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "ToolRestriction", + "source": "packages/core/tools/src/index.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "ToolExecutionResult", + "source": "packages/core/tools/src/index.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "PreToolDecision", + "source": "packages/core/tools/src/index.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "PostToolDecision", + "source": "packages/core/tools/src/index.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "StructuredScalar", + "source": "packages/core/tools/src/json-schema.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "StructuredSchemaType", + "source": "packages/core/tools/src/json-schema.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "StructuredSchemaNode", + "source": "packages/core/tools/src/json-schema.ts" + }, + { + "doc": "docs/core-data-structures/tools.md", + "symbol": "StructuredOutputSchema", + "source": "packages/core/tools/src/json-schema.ts" + }, + { + "doc": "docs/core-data-structures/user-interaction.md", + "symbol": "AskUserQuestionOption", + "source": "packages/ui/user-interaction/src/index.ts" + }, + { + "doc": "docs/core-data-structures/user-interaction.md", + "symbol": "AskUserQuestionItem", + "source": "packages/ui/user-interaction/src/index.ts" + }, + { + "doc": "docs/core-data-structures/user-interaction.md", + "symbol": "AskUserQuestionRequest", + "source": "packages/ui/user-interaction/src/index.ts" + }, + { + "doc": "docs/core-data-structures/user-interaction.md", + "symbol": "AskUserQuestionAnswerItem", + "source": "packages/ui/user-interaction/src/index.ts" + }, + { + "doc": "docs/core-data-structures/user-interaction.md", + "symbol": "AskUserQuestionAnswer", + "source": "packages/ui/user-interaction/src/index.ts" + }, + { + "doc": "docs/core-data-structures/user-interaction.md", + "symbol": "UserInteractionProvider", + "source": "packages/ui/user-interaction/src/index.ts" + }, + { + "doc": "docs/core-data-structures/user-interaction.md", + "symbol": "UserInteractionError", + "source": "packages/ui/user-interaction/src/index.ts" + }, + { + "doc": "docs/core-data-structures/approval.md", + "symbol": "ApprovalRequestId", + "source": "packages/ui/user-approval/src/index.ts" + }, + { + "doc": "docs/core-data-structures/approval.md", + "symbol": "ApprovalOutcome", + "source": "packages/ui/user-approval/src/index.ts" + }, + { + "doc": "docs/core-data-structures/approval.md", + "symbol": "ApprovalPolicy", + "source": "packages/ui/user-approval/src/index.ts" + }, + { + "doc": "docs/core-data-structures/approval.md", + "symbol": "ApprovalRequest", + "source": "packages/ui/user-approval/src/index.ts" + }, + { + "doc": "docs/core-data-structures/bash.md", + "symbol": "BashExecRequest", + "source": "packages/bash/bash/src/types.ts" + }, + { + "doc": "docs/core-data-structures/bash.md", + "symbol": "BashExecSpec", + "source": "packages/bash/bash/src/types.ts" + }, + { + "doc": "docs/core-data-structures/bash.md", + "symbol": "BashRunResult", + "source": "packages/bash/bash/src/types.ts" + }, + { + "doc": "docs/core-data-structures/bash.md", + "symbol": "BashSandboxInfo", + "source": "packages/bash/bash/src/types.ts" + }, + { + "doc": "docs/core-data-structures/bash.md", + "symbol": "CollectedOutput", + "source": "packages/bash/bash/src/types.ts" + }, + { + "doc": "docs/core-data-structures/bash.md", + "symbol": "BashTask", + "source": "packages/bash/bash/src/types.ts" + }, + { + "doc": "docs/core-data-structures/bash.md", + "symbol": "BashTaskRead", + "source": "packages/bash/bash/src/types.ts" + }, + { + "doc": "docs/core-data-structures/sandbox.md", + "symbol": "SandboxMode", + "source": "packages/sandbox/sandbox/src/index.ts" + }, + { + "doc": "docs/core-data-structures/sandbox.md", + "symbol": "ConfinedSandboxMode", + "source": "packages/sandbox/sandbox/src/index.ts" + }, + { + "doc": "docs/core-data-structures/sandbox.md", + "symbol": "SandboxEnforcement", + "source": "packages/sandbox/sandbox/src/index.ts" + }, + { + "doc": "docs/core-data-structures/sandbox.md", + "symbol": "SandboxPolicy", + "source": "packages/sandbox/sandbox/src/index.ts" + }, + { + "doc": "docs/core-data-structures/sandbox.md", + "symbol": "ConfinedArgv", + "source": "packages/sandbox/sandbox/src/index.ts" + }, + { + "doc": "docs/core-data-structures/code-runtime.md", + "symbol": "CodeRunRequest", + "source": "packages/code-runtime/code-runtime/src/types.ts" + }, + { + "doc": "docs/core-data-structures/code-runtime.md", + "symbol": "CodeRunResult", + "source": "packages/code-runtime/code-runtime/src/types.ts" + }, + { + "doc": "docs/core-data-structures/code-runtime.md", + "symbol": "CodeBindingNamespace", + "source": "packages/code-runtime/code-runtime/src/types.ts" + }, + { + "doc": "docs/core-data-structures/code-runtime.md", + "symbol": "CodeBindingFunction", + "source": "packages/code-runtime/code-runtime/src/types.ts" + }, + { + "doc": "docs/core-data-structures/code-runtime.md", + "symbol": "CodeRunFailure", + "source": "packages/code-runtime/code-runtime/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsTarget", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsTargetKey", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsVersion", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsInfo", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsDirEntry", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsWriteIntent", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsWriteOutcome", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsEditRequest", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsEditOutcome", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsErrorCode", + "source": "packages/fs/fs/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FsPolicyExec", + "source": "packages/fs/fs-policy/src/types.ts" + }, + { + "doc": "docs/core-data-structures/filesystem.md", + "symbol": "FileReadOutcome", + "source": "packages/fs/tool-fs/src/read-render.ts" + }, + { + "doc": "docs/core-data-structures/skills.md", + "symbol": "SkillSource", + "source": "packages/skill/skill/src/index.ts" + }, + { + "doc": "docs/core-data-structures/skills.md", + "symbol": "SkillResourceBase", + "source": "packages/skill/skill/src/index.ts" + }, + { + "doc": "docs/core-data-structures/skills.md", + "symbol": "SkillSummary", + "source": "packages/skill/skill/src/index.ts" + }, + { + "doc": "docs/core-data-structures/skills.md", + "symbol": "SkillCandidate", + "source": "packages/skill/skill/src/index.ts" + }, + { + "doc": "docs/core-data-structures/skills.md", + "symbol": "SkillDefinition", + "source": "packages/skill/skill/src/index.ts" + }, + { + "doc": "docs/core-data-structures/skills.md", + "symbol": "SkillRegistration", + "source": "packages/skill/skill/src/index.ts" + }, + { + "doc": "docs/core-data-structures/skills.md", + "symbol": "SkillLookupOptions", + "source": "packages/skill/skill/src/index.ts" + }, + { + "doc": "docs/core-data-structures/skills.md", + "symbol": "SkillProvider", + "source": "packages/skill/skill/src/index.ts" + }, + { + "doc": "docs/core-data-structures/skills.md", + "symbol": "Config", + "source": "packages/skill/skill/src/index.ts" + }, + { + "doc": "docs/core-data-structures/compaction.md", + "symbol": "CompactionResult", + "source": "packages/compact/compact/src/types.ts" + }, + { + "doc": "docs/core-data-structures/subagent.md", + "symbol": "SubagentCapabilities", + "source": "packages/subagent/subagent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/subagent.md", + "symbol": "SubagentStartRequest", + "source": "packages/subagent/subagent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/subagent.md", + "symbol": "SubagentResult", + "source": "packages/subagent/subagent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/subagent.md", + "symbol": "SubagentStopReasonMap", + "source": "packages/subagent/subagent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/subagent.md", + "symbol": "SubagentRun", + "source": "packages/subagent/subagent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/subagent.md", + "symbol": "SubagentProvider", + "source": "packages/subagent/subagent/src/types.ts" + }, + { + "doc": "docs/core-data-structures/web.md", + "symbol": "WebSearchRequest", + "source": "packages/web/web/src/types.ts" + }, + { + "doc": "docs/core-data-structures/web.md", + "symbol": "WebSearchResult", + "source": "packages/web/web/src/types.ts" + }, + { + "doc": "docs/core-data-structures/web.md", + "symbol": "WebSearchSource", + "source": "packages/web/web/src/types.ts" + }, + { + "doc": "docs/core-data-structures/web.md", + "symbol": "WebFetchRequest", + "source": "packages/web/web/src/types.ts" + }, + { + "doc": "docs/core-data-structures/web.md", + "symbol": "WebFetchResult", + "source": "packages/web/web/src/types.ts" + }, + { + "doc": "docs/core-data-structures/web.md", + "symbol": "WebFetchBody", + "source": "packages/web/web/src/types.ts" + }, + { + "doc": "docs/core-data-structures/workflow.md", + "symbol": "WorkflowStartRequest", + "source": "packages/workflow/workflow/src/types.ts" + }, + { + "doc": "docs/core-data-structures/workflow.md", + "symbol": "WorkflowMeta", + "source": "packages/workflow/workflow/src/types.ts" + }, + { + "doc": "docs/core-data-structures/workflow.md", + "symbol": "WorkflowResult", + "source": "packages/workflow/workflow/src/types.ts" + }, + { + "doc": "docs/core-data-structures/workflow.md", + "symbol": "WorkflowRun", + "source": "packages/workflow/workflow/src/types.ts" + }, + { + "doc": "docs/core-data-structures/lsp.md", + "symbol": "LspOperation", + "source": "packages/lsp/lsp/src/types.ts" + }, + { + "doc": "docs/core-data-structures/lsp.md", + "symbol": "LspPosition", + "source": "packages/lsp/lsp/src/types.ts" + }, + { + "doc": "docs/core-data-structures/lsp.md", + "symbol": "LspRange", + "source": "packages/lsp/lsp/src/types.ts" + }, + { + "doc": "docs/core-data-structures/lsp.md", + "symbol": "LspQueryRequest", + "source": "packages/lsp/lsp/src/types.ts" + }, + { + "doc": "docs/core-data-structures/lsp.md", + "symbol": "LspProviderQuery", + "source": "packages/lsp/lsp/src/types.ts" + }, + { + "doc": "docs/core-data-structures/lsp.md", + "symbol": "LspLocation", + "source": "packages/lsp/lsp/src/types.ts" + }, + { + "doc": "docs/core-data-structures/lsp.md", + "symbol": "LspHover", + "source": "packages/lsp/lsp/src/types.ts" + }, + { + "doc": "docs/core-data-structures/lsp.md", + "symbol": "LspQueryResult", + "source": "packages/lsp/lsp/src/types.ts" + }, + { + "doc": "docs/core-data-structures/lsp.md", + "symbol": "LspProvider", + "source": "packages/lsp/lsp/src/types.ts" + }, + { + "doc": "docs/core-data-structures/lsp.md", + "symbol": "LspService", + "source": "packages/lsp/lsp/src/types.ts" + } ] } From 0f3f0efd9c08b755d6127ef8b77100a34170a512 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Thu, 16 Jul 2026 13:34:37 +0800 Subject: [PATCH 013/273] fix(lsp): address codex review round 2 Further lifecycle/safety hardening of the local provider: - Tear the instance down when the initialize handshake is aborted, so a poisoned pending `ready` can't make later queries for that workspace re-wait. - Make the serialized-queue wait itself abortable, so a query blocked behind hung earlier work can still observe its own timeout. - Spawn the server detached and signal the whole process group on teardown, so helper processes (e.g. tsserver) can't outlive dispose(). - Open the source with O_NOFOLLOW and cap the read at maxDocumentBytes+1, closing the symlink-swap and concurrent-grow windows the fd-based read left open. - Honor an already-aborted signal before any host I/O or startup. - Validate maxStderrBytes positive at load; surface the retained stderr tail in the "language server exited" error so a fatal startup diagnostic is visible. --- packages/lsp/lsp-local/src/connection.ts | 38 ++++++++++++++++--- packages/lsp/lsp-local/src/host.ts | 28 ++++++++++++-- packages/lsp/lsp-local/src/index.ts | 7 +++- packages/lsp/lsp-local/src/instance.ts | 32 +++++++++++++--- .../lsp/lsp-local/tests/lifecycle.spec.ts | 19 ++++++++++ 5 files changed, 109 insertions(+), 15 deletions(-) diff --git a/packages/lsp/lsp-local/src/connection.ts b/packages/lsp/lsp-local/src/connection.ts index 4f1f4d9b3a..272109d2c6 100644 --- a/packages/lsp/lsp-local/src/connection.ts +++ b/packages/lsp/lsp-local/src/connection.ts @@ -55,14 +55,17 @@ export class LspConnection { private readonly onServerRequest: (method: string, params: unknown) => Promise, ) { this.decoder = new MessageDecoder(spec.maxMessageBytes) + // `detached` puts the server in its own process group so teardown can signal the WHOLE group + // (via `process.kill(-pid)`), reaching helper processes a language server spawns (e.g. tsserver). this.child = spawn(spec.command, [...spec.args], { cwd: spec.cwd, env: spec.env, stdio: ['pipe', 'pipe', 'pipe'], + detached: true, }) this.closed = new Promise((resolve) => { this.child.on('close', () => { - const reason = this.closeReason ?? new Error('language server exited') + const reason = this.closeReason ?? new Error(this.exitMessage()) // Record the reason so any request issued AFTER close rejects immediately instead of hanging // (a closed process sends no further responses). this.closeReason = reason @@ -150,14 +153,33 @@ export class LspConnection { return this.nextId } - /** Send SIGTERM to the child (idempotent-safe; a dead child ignores it). */ + /** Send SIGTERM to the server's process group (idempotent-safe; a dead group ignores it). */ terminate(): void { - this.child.kill('SIGTERM') + this.signalGroup('SIGTERM') } - /** Send SIGKILL to the child. */ + /** Send SIGKILL to the server's process group. */ kill(): void { - this.child.kill('SIGKILL') + this.signalGroup('SIGKILL') + } + + /** + * Signal the whole process group (negative pid) so helper processes are reached; fall back to the + * direct child if the group send fails. Never throws — teardown races process exit. + */ + private signalGroup(sig: NodeJS.Signals): void { + const pid = this.child.pid + if (pid === undefined) return + try { + process.kill(-pid, sig) + } catch { + // The group is gone (already exited) or could not be signalled; try the direct child. + try { + this.child.kill(sig) + } catch { + // Already dead; nothing to signal. + } + } } private onStdout(chunk: Buffer): void { @@ -221,6 +243,12 @@ export class LspConnection { this.child.stdin.write(encodeMessage(message)) } + /** The exit-close error message, appending the retained stderr tail when the server wrote any. */ + private exitMessage(): string { + const tail = this.stderr.trim() + return tail === '' ? 'language server exited' : `language server exited; stderr: ${tail}` + } + private fail(error: Error): void { /* v8 ignore next -- the second arm (closeReason already set) needs two fail() calls before close; defensive. */ if (this.closeReason === undefined) this.closeReason = error diff --git a/packages/lsp/lsp-local/src/host.ts b/packages/lsp/lsp-local/src/host.ts index 8638926860..949a1b838b 100644 --- a/packages/lsp/lsp-local/src/host.ts +++ b/packages/lsp/lsp-local/src/host.ts @@ -9,7 +9,9 @@ * @module @deepseek-ai/dsh-lsp-local/host */ +import { constants } from 'node:fs' import { open, realpath, stat } from 'node:fs/promises' +import type { FileHandle } from 'node:fs/promises' import { isAbsolute, resolve as resolvePath, sep } from 'node:path' /** A validated source: its canonical absolute path and current UTF-8 text. */ @@ -70,8 +72,9 @@ export async function readHostSource( } // Open ONE handle after containment, then stat and read through it: a concurrent replace between // realpath and read cannot swap the target, so the regular-file and size checks bind the bytes we - // actually read (no path-based TOCTOU). - const handle = await open(canonicalPath, 'r') + // actually read (no path-based TOCTOU). O_NOFOLLOW rejects the final component being swapped for a + // symlink between realpath and open (which would otherwise escape the workspace). + const handle = await open(canonicalPath, constants.O_RDONLY | constants.O_NOFOLLOW) try { const info = await handle.stat() if (!info.isFile()) { @@ -80,7 +83,9 @@ export async function readHostSource( if (info.size > maxDocumentBytes) { throw new Error(`source "${filePath}" is ${info.size} bytes, over the ${maxDocumentBytes}-byte limit`) } - const buffer = await handle.readFile() + // Bound the read to the cap even if the file grew after stat: read one extra byte and reject on + // overflow, so a concurrent grow cannot defeat the memory bound. + const buffer = await readCapped(handle, maxDocumentBytes, filePath) const text = decodeUtf8Strict(buffer, filePath) return { canonicalPath, text } } finally { @@ -88,6 +93,23 @@ export async function readHostSource( } } +/** Read at most `maxBytes` from the handle, rejecting when the source overflows the cap. */ +async function readCapped(handle: FileHandle, maxBytes: number, filePath: string): Promise { + const limit = maxBytes + 1 + const chunk = Buffer.allocUnsafe(limit) + let total = 0 + for (;;) { + const { bytesRead } = await handle.read(chunk, total, limit - total, total) + if (bytesRead === 0) break + total += bytesRead + /* v8 ignore next 3 -- overflow requires the file to grow past the cap between stat and read (a concurrent mutation); defensive. */ + if (total > maxBytes) { + throw new Error(`source "${filePath}" grew past the ${maxBytes}-byte limit while reading`) + } + } + return chunk.subarray(0, total) +} + /** Whether `child` is the workspace itself or a descendant of it (both already canonical). */ function isInside(workspace: string, child: string): boolean { if (child === workspace) return true diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts index 598254f937..dc6e02d3c6 100644 --- a/packages/lsp/lsp-local/src/index.ts +++ b/packages/lsp/lsp-local/src/index.ts @@ -24,7 +24,7 @@ import type { // Side-effect type import: declaration-merges `ctx.lsp` onto Context. import type {} from '@deepseek-ai/dsh-lsp' import { canonicalizeWorkspace, readHostSource } from './host.ts' -import { LspInstance } from './instance.ts' +import { abortError, LspInstance } from './instance.ts' import type { InstanceSpec } from './instance.ts' export { canonicalizeWorkspace, readHostSource } from './host.ts' @@ -114,6 +114,8 @@ export function apply(ctx: Context, config: Config): void { // nonpositive value would let a server that ignores shutdown hang disposal forever. Fail at load. assertPositiveInteger('shutdownTimeoutMs', resolved.shutdownTimeoutMs) assertPositiveInteger('killGraceMs', resolved.killGraceMs) + // A nonpositive stderr cap defeats the retained-tail bound (`slice(-0)` keeps everything). + assertPositiveInteger('maxStderrBytes', resolved.maxStderrBytes) const childEnv = buildChildEnv(resolved.env) // Resolve the executable eagerly so a misconfigured command fails at load, not on first query. const executable = resolveExecutable(resolved.command, childEnv) @@ -160,6 +162,9 @@ class LocalLspProvider implements LspProvider { async query(request: LspProviderQuery, signal?: AbortSignal): Promise { /* v8 ignore next -- the seam unregisters this provider on dispose, so a query never reaches it disposed; defensive. */ if (this.isDisposed()) throw new Error('lsp-local provider is disposed') + // Honor an already-aborted signal before any host I/O so a canceled request neither reads nor + // spawns a server. + if (signal?.aborted) throw abortError(signal) const workspace = await canonicalizeWorkspace(request.workspaceRoot) // Validate and read the source BEFORE spawning a server: a missing/external/non-regular/oversized // source must fail without leaving an idle process pooled (the pre-start rejection contract), and diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts index 83266e9c8f..ecf2782a12 100644 --- a/packages/lsp/lsp-local/src/instance.ts +++ b/packages/lsp/lsp-local/src/instance.ts @@ -78,9 +78,14 @@ export class LspInstance { * @returns the normalized result. */ query(request: LspProviderQuery, source: HostSource, signal?: AbortSignal): Promise { - const run = this.queue.then(() => this.runQuery(request, source, signal)) - // Keep the tail alive regardless of this query's outcome so the next caller still serializes. - this.queue = run.then(() => undefined, () => undefined) + // Serialize behind prior work, but observe abort DURING the queue wait too: if an earlier query + // hangs (e.g. a signal-less seam caller), a later tool's timeout must still be able to give up + // rather than block on the shared tail forever. + const run = this.abortable(this.queue, signal).then(() => this.runQuery(request, source, signal)) + // Keep the tail alive regardless of this query's outcome so the next caller still serializes. The + // tail follows the ACTUAL prior work (this.queue), not the abortable view, so a caller giving up + // on the wait does not deserialize the queue. + this.queue = this.queue.then(() => run).then(() => undefined, () => undefined) return run } @@ -101,10 +106,21 @@ export class LspInstance { private async runQuery(request: LspProviderQuery, source: HostSource, signal?: AbortSignal): Promise { if (this.disposed) throw new Error('LSP instance was disposed') + /* v8 ignore next -- the abortable queue wait rejects a pre-aborted signal before runQuery; this is a belt-and-suspenders guard. */ if (signal?.aborted) throw abortError(signal) // Observe abort during the handshake wait: a server that never answers `initialize` must not // block the tool-timeout signal here (the timeout policy awaits our quiescence, not the promise). - await this.abortable(this.ready, signal) + // If abort wins, the handshake is still pending on a live process, so tear the instance down — + // otherwise its poisoned `ready` would make every later query for this workspace re-wait. + try { + await this.abortable(this.ready, signal) + } catch (error) { + if (signal?.aborted && !this.dead) { + this.disposed = true + await this.tearDown(abortError(signal)) + } + throw error + } const capabilities = this.capabilities /* v8 ignore next -- `ready` resolves only after capabilities are set, else it rejects above; defensive. */ if (capabilities === undefined) throw new Error('LSP instance is not initialized') @@ -303,8 +319,12 @@ function markSettled(): boolean { return true } -/** Build an abort Error carrying the signal's reason (preserving a timeout classification). */ -function abortError(signal: AbortSignal): Error { +/** + * Build an abort Error carrying the signal's reason (preserving a timeout classification). + * @param signal - the aborted signal whose reason to surface. + * @returns the timeout reason if the signal carries one, else the signal's Error reason, else a generic aborted Error. + */ +export function abortError(signal: AbortSignal): Error { const timeout = timeoutOf(signal) if (timeout !== undefined) return timeout const reason: unknown = signal.reason diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts index c5631f2a95..66a18584a1 100644 --- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts +++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts @@ -151,6 +151,25 @@ describe('lsp-local end to end over a fake server', () => { await ctx.fiber.dispose() }) + it('honors an already-aborted signal before any host I/O or startup', async () => { + const ctx = await mount({ LSP_FAKE_DEF: 'null' }) + const controller = new AbortController() + controller.abort(new Error('pre-aborted')) + await expect(ctx.lsp.query(query('definition'), controller.signal)).rejects.toThrow(/pre-aborted/) + await ctx.fiber.dispose() + }) + + it('surfaces the server stderr tail in the exit error', async () => { + // A server that writes to stderr then exits without answering: the query rejection carries the + // retained stderr tail so the failure is diagnosable. + const ctx = await mount({}, { + command: process.execPath, + args: ['-e', 'process.stderr.write("FATAL: boom\\n"); setTimeout(()=>process.exit(1), 50)'], + }) + await expect(ctx.lsp.query(query('definition'))).rejects.toThrow(/FATAL: boom/) + await ctx.fiber.dispose() + }) + it('classifies a timeout deadline as the abort reason', async () => { const ctx = await mount({ LSP_FAKE_HANG: '1' }) using d = deadline(undefined, 50, 'TEST_TIMEOUT') From 43d419ac5c1da0bc3e3920eb6fe089597350330c Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Thu, 16 Jul 2026 14:17:21 +0800 Subject: [PATCH 014/273] fix(lsp): address codex review round 3 Final review pass on the local provider: - Tear the instance down when `initialize` REJECTS (utf-8 negotiation, malformed result), not only on abort, so a permanently-rejecting `ready` is never pooled. - Use the group-aware SIGKILL on a framing failure so helpers are reached. - Validate maxMessageBytes and maxDocumentBytes positive at load alongside the other byte caps. - Fix the location renderer's outside-workspace check to match a `..` segment exactly, so an in-workspace path like `..generated/a.ts` stays relative. - Document the accepted ancestor-directory symlink-swap TOCTOU under the trusted-host model (O_NOFOLLOW guards only the final component). --- packages/lsp/lsp-local/README.md | 2 +- packages/lsp/lsp-local/src/connection.ts | 5 +++-- packages/lsp/lsp-local/src/index.ts | 6 +++++- packages/lsp/lsp-local/src/instance.ts | 13 +++++++------ packages/lsp/lsp-local/tests/lifecycle.spec.ts | 10 ++++++++++ packages/lsp/tool-lsp/src/render.ts | 4 +++- packages/lsp/tool-lsp/tests/render.spec.ts | 6 ++++++ 7 files changed, 35 insertions(+), 11 deletions(-) diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md index f9e4b32713..1424f27835 100644 --- a/packages/lsp/lsp-local/README.md +++ b/packages/lsp/lsp-local/README.md @@ -44,6 +44,6 @@ Indirectly, through `dsh-tool-lsp`, which surfaces this provider's normalized re ## Known Limitations and Deferred Work -- **Trusted host-local only** — no sandbox confinement, no private cache/temp write contract; supporting untrusted binaries or restricted/remote/virtual workspaces requires a later process/filesystem contract and a different provider ([seam RFC](../../../docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md)). +- **Trusted host-local only** — no sandbox confinement, no private cache/temp write contract; supporting untrusted binaries or restricted/remote/virtual workspaces requires a later process/filesystem contract and a different provider ([seam RFC](../../../docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md)). Containment resolves `realpath`, then opens the source through one handle with `O_NOFOLLOW` (final-component symlink guard) and a bounded read; a concurrent mutator that swaps an *ancestor* directory for a symlink between the resolve and the open is an accepted residual TOCTOU under this trusted-deployment model, not closed with non-portable `openat` segment walks. - **Transient-open compatibility floor** — servers whose synchronization omits open/close (or advertise `None`) are unsupported even if closed-document queries would work; the pinned TypeScript e2e establishes one compatibility floor, not a cross-language claim. - **Per-instance serialization latency** — parallel agents sharing a workspace queue behind one process; long-lived workspace processes consume memory until disposal. diff --git a/packages/lsp/lsp-local/src/connection.ts b/packages/lsp/lsp-local/src/connection.ts index 272109d2c6..6eea8aec27 100644 --- a/packages/lsp/lsp-local/src/connection.ts +++ b/packages/lsp/lsp-local/src/connection.ts @@ -187,9 +187,10 @@ export class LspConnection { try { messages = this.decoder.push(chunk) } catch (error) { - // A framing/JSON failure corrupts the stream position irrecoverably: fail the instance. + // A framing/JSON failure corrupts the stream position irrecoverably: fail the instance and + // SIGKILL the whole group so helper processes don't outlive the leader. this.fail(asError(error)) - this.child.kill('SIGKILL') + this.signalGroup('SIGKILL') return } for (const message of messages) this.dispatch(message) diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts index dc6e02d3c6..19d29e3618 100644 --- a/packages/lsp/lsp-local/src/index.ts +++ b/packages/lsp/lsp-local/src/index.ts @@ -114,8 +114,12 @@ export function apply(ctx: Context, config: Config): void { // nonpositive value would let a server that ignores shutdown hang disposal forever. Fail at load. assertPositiveInteger('shutdownTimeoutMs', resolved.shutdownTimeoutMs) assertPositiveInteger('killGraceMs', resolved.killGraceMs) - // A nonpositive stderr cap defeats the retained-tail bound (`slice(-0)` keeps everything). + // Byte caps must be positive: a nonpositive stderr cap defeats the retained-tail bound + // (`slice(-0)` keeps everything), `maxMessageBytes: 0` makes every response fatal, and a bad + // document cap fails later in the read path instead of at load. assertPositiveInteger('maxStderrBytes', resolved.maxStderrBytes) + assertPositiveInteger('maxMessageBytes', resolved.maxMessageBytes) + assertPositiveInteger('maxDocumentBytes', resolved.maxDocumentBytes) const childEnv = buildChildEnv(resolved.env) // Resolve the executable eagerly so a misconfigured command fails at load, not on first query. const executable = resolveExecutable(resolved.command, childEnv) diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts index ecf2782a12..cd73d5cb8d 100644 --- a/packages/lsp/lsp-local/src/instance.ts +++ b/packages/lsp/lsp-local/src/instance.ts @@ -108,16 +108,17 @@ export class LspInstance { if (this.disposed) throw new Error('LSP instance was disposed') /* v8 ignore next -- the abortable queue wait rejects a pre-aborted signal before runQuery; this is a belt-and-suspenders guard. */ if (signal?.aborted) throw abortError(signal) - // Observe abort during the handshake wait: a server that never answers `initialize` must not - // block the tool-timeout signal here (the timeout policy awaits our quiescence, not the promise). - // If abort wins, the handshake is still pending on a live process, so tear the instance down — - // otherwise its poisoned `ready` would make every later query for this workspace re-wait. + // Observe abort during the handshake wait, and never pool a poisoned instance: if the wait ends + // in failure — an abort on a still-pending handshake, OR `initialize` rejecting (utf-8 + // negotiation, malformed result) without the process exiting — tear the instance down so a + // permanently-rejecting/pending `ready` can't make every later query for this workspace fail. try { await this.abortable(this.ready, signal) } catch (error) { - if (signal?.aborted && !this.dead) { + if (!this.dead) { this.disposed = true - await this.tearDown(abortError(signal)) + /* v8 ignore next -- ready rejects with an Error (abort reason or initialize failure); the String() fallback is defensive. */ + await this.tearDown(error instanceof Error ? error : new Error(String(error))) } throw error } diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts index 66a18584a1..bf624a1c56 100644 --- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts +++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts @@ -105,6 +105,16 @@ describe('lsp-local end to end over a fake server', () => { await ctx.fiber.dispose() }) + it('does not pool a poisoned instance when initialize rejects', async () => { + // A utf-8 server makes `initialize` reject; the instance must be torn down (not left with a + // permanently-rejecting `ready`) so a later query starts a fresh process rather than reusing it. + const ctx = await mount({ LSP_FAKE_ENCODING: 'utf-8', LSP_FAKE_DEF: 'null' }) + await expect(ctx.lsp.query(query('definition'))).rejects.toThrow(/unsupported position encoding/) + // A second query must also fail the same way (fresh instance), and must NOT hang on a poisoned one. + await expect(ctx.lsp.query(query('definition'))).rejects.toThrow(/unsupported position encoding/) + await ctx.fiber.dispose() + }) + it('rejects a server without transient-open sync (None)', async () => { const ctx = await mount({ LSP_FAKE_SYNC: '0', LSP_FAKE_DEF: 'null' }) await expect(ctx.lsp.query(query('definition'))).rejects.toThrow(/transient textDocument\/didOpen/) diff --git a/packages/lsp/tool-lsp/src/render.ts b/packages/lsp/tool-lsp/src/render.ts index df0913a591..0051adc719 100644 --- a/packages/lsp/tool-lsp/src/render.ts +++ b/packages/lsp/tool-lsp/src/render.ts @@ -137,7 +137,9 @@ export function renderUri(uri: string, workspaceRoot: string): string { } const rel = relative(workspaceRoot, absolute) if (rel === '') return '.' - const outside = rel.startsWith('..') || isAbsolute(rel) + // A leading `..` SEGMENT (or an absolute rel) means outside the workspace; guard against a false + // positive on an in-workspace path whose first component merely starts with dots (e.g. `..gen/x`). + const outside = rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel) return outside ? absolute : rel.split(sep).join('/') } diff --git a/packages/lsp/tool-lsp/tests/render.spec.ts b/packages/lsp/tool-lsp/tests/render.spec.ts index 53a2be5899..88b02a1fd5 100644 --- a/packages/lsp/tool-lsp/tests/render.spec.ts +++ b/packages/lsp/tool-lsp/tests/render.spec.ts @@ -60,6 +60,12 @@ describe('renderUri', () => { expect(renderUri(pathToFileURL(WS).href, WS)).toBe('.') }) + it('keeps an in-workspace path whose first segment starts with dots relative', () => { + // `..generated` is a real in-workspace dir, not a parent escape; only a `..` segment is external. + const uri = pathToFileURL(join(WS, '..generated', 'a.ts')).href + expect(renderUri(uri, WS)).toBe('..generated/a.ts') + }) + it('keeps a non-file URI verbatim', () => { expect(renderUri('untitled:Untitled-1', WS)).toBe('untitled:Untitled-1') expect(renderUri('jdt://contents/Foo.class', WS)).toBe('jdt://contents/Foo.class') From 3368f7924f823d193e86a92222cec417e42c8209 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Thu, 16 Jul 2026 14:57:07 +0800 Subject: [PATCH 015/273] docs(lsp): resolve ds-review-bot RFC warnings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix the executable-resolution lifecycle contradiction to match the shipped implementation: the executable resolves eagerly at load (failing before registration if unavailable), while the server process launch stays lazy until the first query. Align both language versions. Correct two zh counterpart divergences: drop the "only" condition the Chinese text added to the English "behave best" source modality, and apply binding terminology (包(package)/包, transcript(文本记录)). --- .../2026-07-15-lsp-capability-seam.i18n.yaml | 4 ++-- .../architecture/2026-07-15-lsp-capability-seam.md | 2 +- .../2026-07-15-lsp-capability-seam.zh.md | 12 ++++++------ 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml index f8b32dcca1..33a1d6c036 100644 --- a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml +++ b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.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 -2026-07-15-lsp-capability-seam.md: 90cc7fce8ce86582cc27bd70fadcc46309438983 -2026-07-15-lsp-capability-seam.zh.md: 12873d33684255b7177a78dd4588e11aa61eb26b +2026-07-15-lsp-capability-seam.md: 77b544efbcef1f352806d0431f1ff705d2b7bd44 +2026-07-15-lsp-capability-seam.zh.md: dad8160f0bb3a08b2b6546429c3826689a6307f8 diff --git a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md index 90cc7fce8c..77b544efbc 100644 --- a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md +++ b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md @@ -129,7 +129,7 @@ The canonical workspace `realpath` must be a directory and supplies process cwd, ## Local server lifecycle and protocol behavior -`dsh-lsp-local` lazily single-flights one server per `(provider id, canonical workspace realpath)`. At load it resolves the executable after credential scrubbing and environment overrides, failing before registration if unavailable; resolution stays lazy and launch uses no shell. `maxMessageBytes` defaults to `16_000_000`, `maxStderrBytes` to `1_000_000`, and `maxDocumentBytes` to `4_000_000`. A crash fails the active query without replay; a later query may replace the process. Each query starts at most one process, so the MVP has no cross-request restart counter. +`dsh-lsp-local` lazily single-flights one server per `(provider id, canonical workspace realpath)`. At load it resolves the executable after credential scrubbing and environment overrides, failing before registration if unavailable; server process launch stays lazy (first query spawns it) and uses no shell. `maxMessageBytes` defaults to `16_000_000`, `maxStderrBytes` to `1_000_000`, and `maxDocumentBytes` to `4_000_000`. A crash fails the active query without replay; a later query may replace the process. Each query starts at most one process, so the MVP has no cross-request restart counter. Initialization advertises `general.positionEncodings: ['utf-16']`, `workspace: { workspaceFolders: true, configuration: true }`, `textDocument.hover.contentFormat: ['markdown', 'plaintext']`, and `linkSupport: true` for definition and implementation, with no dynamic registration. Returned operation and synchronization capabilities are authoritative. An omitted server `positionEncoding` defaults to `utf-16`; any other value is a protocol error. Configuration may supply initialization options and `workspace/configuration` responses, but the client rejects `workspace/applyEdit` and never executes commands or edits. diff --git a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md index 12873d3368..dad8160f0b 100644 --- a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md +++ b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md @@ -10,11 +10,11 @@ harness 已具备文本搜索与文件读取能力,但二者都无法识别程 语言服务器协议(Language Server Protocol,LSP)支持分属三个职责方:模型需要稳定的查询 schema,harness 需要提供方选择与规范化结果,本地实现则负责进程、JSON-RPC、工作区、同步与文件系统行为。将三者合并会使模型契约绑定本地子进程,并阻碍远程或沙箱原生提供方。 -许多语言服务器只有在查询文档已按当前文本打开时才能稳定工作。兼容的 agent 客户端必须限制这项状态、定义内部读取是否算作模型观察,并确保文档快照与服务器工作区索引位于同一文件系统命名空间。 +许多语言服务器在查询文档已按当前文本打开时表现最佳。兼容的 agent 客户端必须限制这项状态、定义内部读取是否算作模型观察,并确保文档快照与服务器工作区索引位于同一文件系统命名空间。 ## 决策 -将 LSP 建成由三个 package 组成的能力服务边界,其中包含一个只读模型工具和一个通用本地提供方实现: +将 LSP 建成由三个包(package)组成的能力服务边界,其中包含一个只读模型工具和一个通用本地提供方实现: 1. `packages/lsp/lsp` 下的 `@deepseek-ai/dsh-lsp` 负责 `ctx.lsp`、提供方注册与选择、标准化请求与结果、执行控制,以及结构化 LSP 错误。 2. `packages/lsp/lsp-local` 下的 `@deepseek-ai/dsh-lsp-local` 将配置的 stdio 语言服务器适配到该服务边界。多个插件实例可注册不同的服务器命令和扩展名到语言 id 的映射。 @@ -114,7 +114,7 @@ ACP 使用 `{ card: 'generic', kind: 'search', title, locations: [{ path: file_p `dsh-lsp-local` 通过 Node API 在子进程所在的主机命名空间中规范化并读取文件。它拒绝缺失、非普通、非 UTF-8、超大或规范路径越出工作区的源文件,并在校验与读取期间保持同一句柄。它不使用 `ctx.fs` 或发送 `fs/observed`:只有 LSP 结果对模型可见,因此查询不满足写前读取策略。 -`read` 工具的输出带窗口与行号,进入 transcript 且已被观察,不适合作为源文件。在 `tool-lsp` 内读取还会把提供方专用同步职责交给消费方,并排除非本地提供方。 +`read` 工具的输出带窗口与行号,进入 transcript(文本记录)且已被观察,不适合作为源文件。在 `tool-lsp` 内读取还会把提供方专用同步职责交给消费方,并排除非本地提供方。 本地提供方对每次查询都采用兼容优先的临时打开流程。它接受旧式 `textDocumentSync` 的 `Full` 或 `Incremental`,也接受设置了 `openClose: true` 的选项;同步能力缺失、为 `None` 或明确不兼容时,在 `didOpen` 前以不支持错误失败。 @@ -129,7 +129,7 @@ ACP 使用 `{ card: 'generic', kind: 'search', title, locations: [{ path: file_p ## 本地服务器生命周期与协议行为 -`dsh-lsp-local` 按 `(provider id, canonical workspace realpath)` 懒启动一个服务器,并通过 single-flight 合并启动。插件加载时,它在清除凭据并应用环境变量覆盖后解析可执行文件;命令不可用时在注册前失败,解析保持懒执行,启动不经过 shell。`maxMessageBytes` 默认值为 `16_000_000`,`maxStderrBytes` 默认值为 `1_000_000`,`maxDocumentBytes` 默认值为 `4_000_000`。崩溃使当前查询失败且不重放;后续查询可以替换进程。每次查询最多启动一个进程,因此 MVP 不设置跨请求重启计数器。 +`dsh-lsp-local` 按 `(provider id, canonical workspace realpath)` 懒启动一个服务器,并通过 single-flight 合并启动。插件加载时,它在清除凭据并应用环境变量覆盖后解析可执行文件;命令不可用时在注册前失败。服务器进程的启动保持懒执行(首次查询时才拉起),且不经过 shell。`maxMessageBytes` 默认值为 `16_000_000`,`maxStderrBytes` 默认值为 `1_000_000`,`maxDocumentBytes` 默认值为 `4_000_000`。崩溃使当前查询失败且不重放;后续查询可以替换进程。每次查询最多启动一个进程,因此 MVP 不设置跨请求重启计数器。 初始化声明 `general.positionEncodings: ['utf-16']`、`workspace: { workspaceFolders: true, configuration: true }`、`textDocument.hover.contentFormat: ['markdown', 'plaintext']`,以及 definition 与 implementation 的 `linkSupport: true`,但不支持动态注册。服务器返回的操作与同步能力均为真源。服务器省略 `positionEncoding` 时默认为 `utf-16`;其他值均属于协议错误。配置可以提供初始化选项和 `workspace/configuration` 响应,但客户端拒绝 `workspace/applyEdit`,绝不执行命令或编辑。 @@ -173,7 +173,7 @@ ACP 使用 `{ card: 'generic', kind: 'search', title, locations: [{ path: file_p ## 测试 -- Package 测试固定三个 package 的依赖方向、运行时注入和仅通过 `ctx.lsp` 通信的边界。 +- 包测试固定三个包的依赖方向、运行时注入和仅通过 `ctx.lsp` 通信的边界。 - 工具测试固定四种操作、坐标校验、配置限制与省略标记、提示词和 ACP 展示。 - 注册表测试固定原子占用/释放、不受顺序影响的选择,以及结构化的不可用、已释放、冲突和不支持操作错误。 - 测试用 stdio server 固定精确的初始化能力、四种协议映射、`Location`/`LocationLink` 与 `hover` 归一化,以及 `references.includeDeclaration`。 @@ -183,7 +183,7 @@ ACP 使用 `{ card: 'generic', kind: 'search', title, locations: [{ path: file_p - 主机文件系统测试固定 session cwd 要求、符号链接下相对与绝对源路径的规范 containment、文档校验、file/non-file URI 渲染、无格式源文本和不发送 `fs/observed`。 - 无密钥且固定版本的 TypeScript 真实服务器 e2e 覆盖四种操作;可运行配置使用同一项显式提供方映射。 - 快照覆盖模型可见 schema、提示词、结果、省略提示和 ACP 渲染;构建产物冒烟测试覆盖分帧与清理。 -- Package 与架构文档覆盖配置、安全边界和搜索/读取指导;同一改动中,新的 `packages/lsp/` package 组要加入 AGENTS.md 的仓库布局块、packages/README.md 的分组表和 architecture.md。 +- 包与架构文档覆盖配置、安全边界和搜索/读取指导;同一改动中,新的 `packages/lsp/` 包组要加入 AGENTS.md 的仓库布局块、packages/README.md 的分组表和 architecture.md。 ## 影响 From 0d8e7e98f7a4a9d239ec7af000e951c0c0909a2d Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Thu, 16 Jul 2026 16:42:32 +0800 Subject: [PATCH 016/273] fix(lsp): harden local provider lifecycle --- docs/core-data-structures/lsp.md | 4 +- .../2026-07-15-lsp-capability-seam.i18n.yaml | 4 +- .../2026-07-15-lsp-capability-seam.md | 4 +- .../2026-07-15-lsp-capability-seam.zh.md | 4 +- packages/lsp/lsp-local/src/connection.ts | 18 +++++++-- packages/lsp/lsp-local/src/framing.ts | 3 ++ packages/lsp/lsp-local/src/index.ts | 40 +++++++++++++------ packages/lsp/lsp-local/src/instance.ts | 21 +++++----- packages/lsp/lsp-local/tests/built-lib.e2e.ts | 1 - .../lsp/lsp-local/tests/connection.spec.ts | 7 ++++ .../lsp/lsp-local/tests/fixture-server.ts | 30 ++++++++++++++ packages/lsp/lsp-local/tests/framing.spec.ts | 6 +++ packages/lsp/lsp-local/tests/instance.spec.ts | 20 ++++++++-- .../lsp/lsp-local/tests/lifecycle.spec.ts | 30 +++++++++++++- packages/lsp/lsp-local/tests/provider.spec.ts | 12 ++++++ packages/lsp/lsp/README.md | 2 +- packages/lsp/lsp/src/types.ts | 7 +++- packages/lsp/lsp/tests/lsp.spec.ts | 8 ++-- packages/lsp/tool-lsp/README.md | 2 +- packages/lsp/tool-lsp/src/index.ts | 5 ++- packages/lsp/tool-lsp/tests/tool-lsp.spec.ts | 16 ++++++++ 21 files changed, 192 insertions(+), 52 deletions(-) diff --git a/docs/core-data-structures/lsp.md b/docs/core-data-structures/lsp.md index 25b98a9e59..3067237282 100644 --- a/docs/core-data-structures/lsp.md +++ b/docs/core-data-structures/lsp.md @@ -54,7 +54,7 @@ interface LspProviderQuery extends LspQueryRequest { ## Result -A CLOSED discriminated union: navigation operations normalize to `locations`, `hover` to content or `null`. Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled. `references` always includes declarations — the provider enforces this internally, so callers get no flag. +A CLOSED discriminated union: navigation operations normalize to `locations`, `hover` to content or `null`. Consumers `switch` on `kind` to exhaustiveness so a new arm breaks compilation until handled. `references` always includes declarations — the provider enforces this internally, so callers get no flag. The `locations` variant carries `resolvedWorkspaceRoot`: the provider's canonical form of the request's `workspaceRoot` and the root its `file:` URIs are relative to, so a caller relativizing display paths uses it rather than the possibly-symlinked request root. ```ts type-equiv interface LspLocation { @@ -76,7 +76,7 @@ interface LspHover { ```ts type-equiv type LspQueryResult = - | { readonly kind: 'locations'; readonly locations: readonly LspLocation[] } + | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceRoot: string } | { readonly kind: 'hover'; readonly hover: LspHover | null } ``` diff --git a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml index 33a1d6c036..69c509bae6 100644 --- a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml +++ b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.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 -2026-07-15-lsp-capability-seam.md: 77b544efbcef1f352806d0431f1ff705d2b7bd44 -2026-07-15-lsp-capability-seam.zh.md: dad8160f0bb3a08b2b6546429c3826689a6307f8 +2026-07-15-lsp-capability-seam.md: c21d2f3926b5b465f4ccf48f1bf954c2ae604e12 +2026-07-15-lsp-capability-seam.zh.md: 9556ead6c2e0d6d49fffe54928d53f9418cf10b7 diff --git a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md index 77b544efbc..c21d2f3926 100644 --- a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md +++ b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md @@ -62,7 +62,7 @@ interface LspProviderQuery extends LspQueryRequest { } type LspQueryResult = - | { readonly kind: 'locations'; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[] } + | { readonly kind: 'locations'; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[]; readonly resolvedWorkspaceRoot: string } | { readonly kind: 'hover'; readonly hover: { readonly contents: string; readonly range?: LspRange } | null } interface LspProvider { @@ -77,7 +77,7 @@ interface LspService { } ``` -Mapping keys normalize to lowercase, leading-dot extensions selected from `filePath`'s final extension; language ids only synchronize documents. Seam positions and ranges are zero-based UTF-16. `references` always includes declarations: providers enforce this internally, the local mapping sets `context.includeDeclaration: true`, and callers get no flag. Closed result unions normalize navigation to locations and hover to content or `null`. The seam exposes no protocol types, process or document controls, or generic request escape hatch. +Mapping keys normalize to lowercase, leading-dot extensions selected from `filePath`'s final extension; language ids only synchronize documents. Seam positions and ranges are zero-based UTF-16. `references` always includes declarations: providers enforce this internally, the local mapping sets `context.includeDeclaration: true`, and callers get no flag. Closed result unions normalize navigation to locations and hover to content or `null`; navigation results carry the provider's resolved workspace root so consumers relativize file URIs in the same canonical namespace. The seam exposes no protocol types, process or document controls, or generic request escape hatch. `dsh-lsp-local` owns host files, server configuration, JSON-RPC, process and transient-document state, and protocol translation; it depends on `dsh-lsp` and Node APIs, not `dsh-fs`. `dsh-tool-lsp` runtime-injects only `tools`, `lsp`, and `systemPrompt`, obtains the workspace from `exec.agent?.session.header.cwd` through a package-local `sessionCwd(exec)` helper matching the filesystem tools' lookup, and imports no provider. diff --git a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md index dad8160f0b..9556ead6c2 100644 --- a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md +++ b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md @@ -62,7 +62,7 @@ interface LspProviderQuery extends LspQueryRequest { } type LspQueryResult = - | { readonly kind: 'locations'; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[] } + | { readonly kind: 'locations'; readonly locations: readonly { readonly uri: string; readonly range: LspRange }[]; readonly resolvedWorkspaceRoot: string } | { readonly kind: 'hover'; readonly hover: { readonly contents: string; readonly range?: LspRange } | null } interface LspProvider { @@ -77,7 +77,7 @@ interface LspService { } ``` -映射键规范化为带前导点的小写扩展名,并按 `filePath` 的最后一个扩展名选择;语言 id 仅用于文档同步。服务边界中的位置和范围从零开始按 UTF-16 计数。`references` 始终包含声明:提供方在内部执行该约束,本地映射设置 `context.includeDeclaration: true`,调用方不能配置。封闭结果联合将导航统一为位置,将 `hover` 统一为内容或 `null`。服务边界不公开协议类型、进程或文档控制,也不提供通用请求逃生口。 +映射键规范化为带前导点的小写扩展名,并按 `filePath` 的最后一个扩展名选择;语言 id 仅用于文档同步。服务边界中的位置和范围从零开始按 UTF-16 计数。`references` 始终包含声明:提供方在内部执行该约束,本地映射设置 `context.includeDeclaration: true`,调用方不能配置。封闭结果联合将导航统一为位置,将 `hover` 统一为内容或 `null`;导航结果携带提供方解析后的工作区根目录,使消费方依据同一规范化根目录相对化文件 URI。服务边界不公开协议类型、进程或文档控制,也不提供通用请求逃生口。 `dsh-lsp-local` 负责主机文件、服务器配置、JSON-RPC、进程与临时文档状态和协议转换;它依赖 `dsh-lsp` 与 Node API,不依赖 `dsh-fs`。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`,通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区,其取值方式与文件系统工具一致,也不导入提供方。 diff --git a/packages/lsp/lsp-local/src/connection.ts b/packages/lsp/lsp-local/src/connection.ts index 6eea8aec27..795fe0dbff 100644 --- a/packages/lsp/lsp-local/src/connection.ts +++ b/packages/lsp/lsp-local/src/connection.ts @@ -41,7 +41,7 @@ export class LspConnection { private readonly decoder: MessageDecoder private readonly pending = new Map() private nextId = 1 - private stderr = '' + private stderr = Buffer.alloc(0) private closeReason: Error | undefined /** Set once the process has fully exited; the instance awaits it during teardown. */ readonly closed: Promise @@ -90,7 +90,7 @@ export class LspConnection { /** The retained stderr tail, for diagnostics on a failed server. */ get stderrTail(): string { - return this.stderr + return this.stderr.toString('utf8') } /** @@ -199,7 +199,17 @@ export class LspConnection { private onStderr(chunk: Buffer): void { // Retain the TAIL, not the prefix: a language server's fatal diagnostic usually appears just // before it exits, so the final bounded segment is the useful one. - this.stderr = (this.stderr + chunk.toString('utf8')).slice(-this.spec.maxStderrBytes) + const cap = this.spec.maxStderrBytes + if (chunk.length >= cap) { + // Copy the bounded suffix so retaining it does not pin an arbitrarily large incoming buffer. + this.stderr = Buffer.from(chunk.subarray(chunk.length - cap)) + return + } + const retainedBytes = Math.min(this.stderr.length, cap - chunk.length) + this.stderr = Buffer.concat([ + this.stderr.subarray(this.stderr.length - retainedBytes), + chunk, + ], retainedBytes + chunk.length) } private dispatch(message: unknown): void { @@ -246,7 +256,7 @@ export class LspConnection { /** The exit-close error message, appending the retained stderr tail when the server wrote any. */ private exitMessage(): string { - const tail = this.stderr.trim() + const tail = this.stderrTail.trim() return tail === '' ? 'language server exited' : `language server exited; stderr: ${tail}` } diff --git a/packages/lsp/lsp-local/src/framing.ts b/packages/lsp/lsp-local/src/framing.ts index 8720247272..bfa6b362b5 100644 --- a/packages/lsp/lsp-local/src/framing.ts +++ b/packages/lsp/lsp-local/src/framing.ts @@ -64,6 +64,9 @@ export class MessageDecoder { } return { ready: false } } + if (separator > MAX_HEADER_BYTES) { + throw new Error(`LSP header exceeded ${MAX_HEADER_BYTES} bytes`) + } const headerText = this.buffer.toString('ascii', 0, separator) const contentLength = parseContentLength(headerText) if (contentLength > this.maxMessageBytes) { diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts index 19d29e3618..f1d5408f5c 100644 --- a/packages/lsp/lsp-local/src/index.ts +++ b/packages/lsp/lsp-local/src/index.ts @@ -11,7 +11,7 @@ * @module @deepseek-ai/dsh-lsp-local */ -import { accessSync, constants } from 'node:fs' +import { accessSync, constants, statSync } from 'node:fs' import { delimiter, isAbsolute, join } from 'node:path' import type { Context } from 'cordis' import z from 'schemastery' @@ -178,19 +178,23 @@ class LocalLspProvider implements LspProvider { // were canonicalizing/reading, so creating a server now would leave it unowned by teardown. /* v8 ignore next -- guards a dispose landing during the canonicalize/read await; not a reproducible unit race. */ if (this.isDisposed()) throw new Error('lsp-local provider is disposed') - const instance = await this.instanceFor(workspace) + // Re-check cancellation too: an abort during the canonicalize/read awaits must not go on to spawn + // (or pool) a server solely for an operation the caller already gave up on. + if (signal?.aborted) throw abortError(signal) + let instance = await this.instanceFor(workspace) + // A pooled server that exited while idle resolves to a dead instance: evict it and create a fresh + // one before dispatch, so this query does not have to fail on a closed connection first. One retry + // suffices — the replacement was just constructed and has not been used. + if (instance.dead) { + await this.evictIfCurrent(workspace, instance) + instance = await this.instanceFor(workspace) + } try { return await instance.query(request, source, signal) } finally { // A crashed/closed process must not be reused: drop its slot so the next query starts fresh, // but only if the slot still holds THIS instance (a concurrent replacement must survive). - if (instance.dead) { - const slot = this.instances.get(workspace) - /* v8 ignore next -- the slot-undefined arm needs a concurrent eviction of the same slot; defensive. */ - if (slot !== undefined && (await settledInstance(slot)) === instance) { - this.instances.delete(workspace) - } - } + if (instance.dead) await this.evictIfCurrent(workspace, instance) } } @@ -208,6 +212,15 @@ class LocalLspProvider implements LspProvider { return created } + /** Drop the slot for `workspace` iff it still resolves to `instance` (a concurrent replacement survives). */ + private async evictIfCurrent(workspace: string, instance: LspInstance): Promise { + const slot = this.instances.get(workspace) + /* v8 ignore next -- the slot-undefined/mismatch arm needs a concurrent eviction of the same slot; defensive. */ + if (slot !== undefined && (await settledInstance(slot)) === instance) { + this.instances.delete(workspace) + } + } + private createInstance(workspace: string): LspInstance { const spec: InstanceSpec = { command: this.executable, @@ -265,7 +278,7 @@ function buildChildEnv(extra: Record): Record { function resolveExecutable(command: string, childEnv: Record): string { if (isAbsolute(command)) { // Verify an absolute command too, so an unavailable one fails at load, not on the first query. - if (!isExecutableSync(command)) { + if (!isExecutableFileSync(command)) { throw new Error(`lsp-local: command "${command}" is not an executable file`) } return command @@ -275,14 +288,15 @@ function resolveExecutable(command: string, childEnv: Record): s for (const dir of pathValue.split(delimiter)) { if (dir === '') continue const candidate = join(dir, command) - if (isExecutableSync(candidate)) return candidate + if (isExecutableFileSync(candidate)) return candidate } throw new Error(`lsp-local: command "${command}" was not found on PATH`) } -/** Synchronous executable check used only at load-time resolution. */ -function isExecutableSync(path: string): boolean { +/** Synchronous regular-file and executable check used only at load-time resolution. */ +function isExecutableFileSync(path: string): boolean { try { + if (!statSync(path).isFile()) return false accessSync(path, constants.X_OK) return true } catch { diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts index cd73d5cb8d..8bf2e48c5b 100644 --- a/packages/lsp/lsp-local/src/instance.ts +++ b/packages/lsp/lsp-local/src/instance.ts @@ -169,7 +169,7 @@ export class LspInstance { */ private abortable(work: Promise, signal: AbortSignal | undefined): Promise { if (signal === undefined) return work - /* v8 ignore next -- runQuery checks signal.aborted before each abortable() call, so it is not already aborted here; defensive. */ + /* v8 ignore next -- callers either pre-check the signal or pass a freshly armed teardown deadline. */ if (signal.aborted) return Promise.reject(abortError(signal)) return new Promise((resolve, reject) => { const onAbort = (): void => { reject(abortError(signal)) } @@ -232,7 +232,10 @@ export class LspInstance { if (operation === 'hover') { return { kind: 'hover', hover: normalizeHover(payload) } } - return { kind: 'locations', locations: normalizeLocations(payload) } + // `spec.cwd` is the canonical workspace realpath (the provider canonicalizes before spawning), + // and every `file:` location URI is relative to it — so it is the root a caller must relativize + // display paths against, not the request's possibly-symlinked workspaceRoot. + return { kind: 'locations', locations: normalizeLocations(payload), resolvedWorkspaceRoot: this.spec.cwd } } private answerServerRequest(method: string, params: unknown): Promise { @@ -271,24 +274,18 @@ export class LspInstance { try { using shutdownDeadline = deadline(undefined, this.spec.shutdownTimeoutMs, 'LSP_SHUTDOWN') await this.gracefulShutdown(shutdownDeadline.signal) + return } catch { // Graceful shutdown failed or timed out: fall through to signal escalation. } await this.forceTerminate() } - /** Best-effort LSP `shutdown` request then `exit` notification, bounded by `signal`. */ + /** Best-effort LSP `shutdown`/`exit`, including process close, bounded by `signal`. */ private async gracefulShutdown(signal: AbortSignal): Promise { - const shutdown = this.connection.request('shutdown', null) - await Promise.race([ - shutdown, - new Promise((_, reject) => { - /* v8 ignore next -- the shutdown deadline signal is freshly armed and not yet aborted here; defensive. */ - if (signal.aborted) { reject(abortError(signal)); return } - signal.addEventListener('abort', () => { reject(abortError(signal)) }, { once: true }) - }), - ]) + await this.abortable(this.connection.request('shutdown', null), signal) this.connection.notify('exit', null) + await this.abortable(this.connection.closed, signal) } /** SIGTERM, wait `killGraceMs` for close, then SIGKILL; await full process close either way. */ diff --git a/packages/lsp/lsp-local/tests/built-lib.e2e.ts b/packages/lsp/lsp-local/tests/built-lib.e2e.ts index 0b33953ba1..cea1f0d189 100644 --- a/packages/lsp/lsp-local/tests/built-lib.e2e.ts +++ b/packages/lsp/lsp-local/tests/built-lib.e2e.ts @@ -55,7 +55,6 @@ describe.skipIf(!built)('built lib real load path (plain node)', () => { const result = await ctx.lsp.query({ operation: 'definition', filePath: 'a.ts', position: { line: 0, character: 6 }, workspaceRoot: ${JSON.stringify(ws)} }) console.log(JSON.stringify(result)) await ctx.fiber.dispose() - process.exit(0) ` const child = spawn(process.execPath, ['--input-type=module', '-e', script], { cwd: pkgDir, stdio: ['ignore', 'pipe', 'pipe'] }) let stdout = '' diff --git a/packages/lsp/lsp-local/tests/connection.spec.ts b/packages/lsp/lsp-local/tests/connection.spec.ts index baf6fde05f..25ac9f2971 100644 --- a/packages/lsp/lsp-local/tests/connection.spec.ts +++ b/packages/lsp/lsp-local/tests/connection.spec.ts @@ -190,6 +190,13 @@ describe('LspConnection edge behavior', () => { expect(conn.stderrTail.length).toBe(100) }) + it('caps the retained stderr tail by bytes for multibyte UTF-8', async () => { + const conn = connectScript('process.stderr.write("😀😀")', 4) + await conn.closed + expect(conn.stderrTail).toBe('😀') + expect(Buffer.byteLength(conn.stderrTail)).toBe(4) + }) + it('rejects with a fallback message when the error response has no message string', async () => { const script = 'let b=Buffer.alloc(0);' + 'const fr=(s)=>{const x=Buffer.from(s);return Buffer.concat([Buffer.from(`Content-Length: ${x.length}\\r\\n\\r\\n`),x]);};' diff --git a/packages/lsp/lsp-local/tests/fixture-server.ts b/packages/lsp/lsp-local/tests/fixture-server.ts index 104b223794..1654cb820d 100644 --- a/packages/lsp/lsp-local/tests/fixture-server.ts +++ b/packages/lsp/lsp-local/tests/fixture-server.ts @@ -10,6 +10,9 @@ * - LSP_FAKE_DEF / LSP_FAKE_REFS / LSP_FAKE_IMPL / LSP_FAKE_HOVER: JSON result per request. * - LSP_FAKE_HANG: "1" makes textDocument/* requests never respond (for abort/timeout tests). * - LSP_FAKE_CRASH_ON_OPEN: "1" exits the process when a didOpen arrives (crash test). + * - LSP_FAKE_EXIT_AFTER_REPLY: "1" exits the process right after answering a textDocument/* request, + * simulating a server that dies while idle so the pool holds a dead instance (eviction test). + * - LSP_FAKE_EXIT_DELAY_MS / LSP_FAKE_EXIT_MARKER: delay protocol exit and record exit/termination. * - LSP_FAKE_NO_SHUTDOWN: "1" ignores the shutdown request (forces kill escalation). * - LSP_FAKE_ON_OPEN: server→client request to emit when a didOpen arrives, one of * "configuration" | "applyEdit" | "notification" | "unknown"; the reply is logged to stderr. @@ -19,11 +22,16 @@ * Run: node --import tsx fixture-server.ts */ +import { appendFileSync } from 'node:fs' + const enc = process.env.LSP_FAKE_ENCODING ?? 'utf-16' const sync: unknown = process.env.LSP_FAKE_SYNC !== undefined ? JSON.parse(process.env.LSP_FAKE_SYNC) : 1 const extraCaps: unknown = process.env.LSP_FAKE_CAPS !== undefined ? JSON.parse(process.env.LSP_FAKE_CAPS) : {} const hang = process.env.LSP_FAKE_HANG === '1' const crashOnOpen = process.env.LSP_FAKE_CRASH_ON_OPEN === '1' +const exitAfterReply = process.env.LSP_FAKE_EXIT_AFTER_REPLY === '1' +const exitDelayMs = Number(process.env.LSP_FAKE_EXIT_DELAY_MS ?? 0) +const exitMarker = process.env.LSP_FAKE_EXIT_MARKER const noShutdown = process.env.LSP_FAKE_NO_SHUTDOWN === '1' const onOpen = process.env.LSP_FAKE_ON_OPEN const errorReply = process.env.LSP_FAKE_ERROR === '1' @@ -32,6 +40,11 @@ const garbage = process.env.LSP_FAKE_GARBAGE === '1' let serverRequestId = 10_000 const pendingServerRequests = new Map() +process.on('SIGTERM', () => { + markExit('TERM') + process.exit(0) +}) + function resultFor(method: string): unknown { switch (method) { case 'textDocument/definition': return envJson('LSP_FAKE_DEF', null) @@ -98,6 +111,15 @@ function handle(message: { id?: number; method?: string; params?: unknown; resul return } if (method === 'exit') { + markExit('EXIT') + if (exitDelayMs > 0) { + setTimeout(() => { + markExit('CLEAN') + process.exit(0) + }, exitDelayMs) + return + } + markExit('CLEAN') process.exit(0) } if (method === 'textDocument/didOpen') { @@ -110,12 +132,20 @@ function handle(message: { id?: number; method?: string; params?: unknown; resul if (hang) return if (errorReply) { send({ id, error: { code: -32000, message: 'server refused the request' } }); return } send({ id, result: resultFor(method) }) + // Simulate an idle death: answer this request, then exit before the next one arrives so the pool + // is left holding a dead instance. + if (exitAfterReply) setTimeout(() => process.exit(0), 20) return } // Unknown request with an id: answer null so the client never stalls. if (id !== undefined) send({ id, result: null }) } +/** Append one teardown event when the fixture is configured to expose process ordering. */ +function markExit(event: string): void { + if (exitMarker !== undefined) appendFileSync(exitMarker, `${event}\n`) +} + /** Emit a server→client request and log the client's reply to stderr for the test to assert. */ function emitServerRequest(kind: string): void { if (kind === 'notification') { diff --git a/packages/lsp/lsp-local/tests/framing.spec.ts b/packages/lsp/lsp-local/tests/framing.spec.ts index 66bca07f10..a197b2c0ca 100644 --- a/packages/lsp/lsp-local/tests/framing.spec.ts +++ b/packages/lsp/lsp-local/tests/framing.spec.ts @@ -69,6 +69,12 @@ describe('MessageDecoder', () => { expect(() => decoder.push(huge)).toThrow(/exceeded .* bytes without a terminator/) }) + it('rejects an oversized header block that includes its terminator', () => { + const decoder = new MessageDecoder(1_000) + const huge = Buffer.from(`Content-Length: 2\r\nX-Fill: ${'a'.repeat(70_000)}\r\n\r\n{}`, 'ascii') + expect(() => decoder.push(huge)).toThrow(/header exceeded .* bytes/) + }) + it('rejects a non-JSON body', () => { const decoder = new MessageDecoder(1_000) expect(() => decoder.push(frame('not json'))).toThrow(/not valid JSON/) diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts index 83c4bdfe77..52fc751754 100644 --- a/packages/lsp/lsp-local/tests/instance.spec.ts +++ b/packages/lsp/lsp-local/tests/instance.spec.ts @@ -1,5 +1,5 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest' -import { mkdtemp, mkdir, rm, writeFile, realpath } from 'node:fs/promises' +import { mkdtemp, mkdir, readFile, rm, writeFile, realpath } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' import { pathToFileURL, fileURLToPath } from 'node:url' @@ -96,17 +96,17 @@ describe('LspInstance server-request handling', () => { it('accepts a lifecycle client/registerCapability request', async () => { const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'lifecycle', LSP_FAKE_DEF: 'null' }) - await expect(run(instance, 'definition')).resolves.toEqual({ kind: 'locations', locations: [] }) + await expect(run(instance, 'definition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws }) }) it('rejects a workspace/applyEdit request but keeps serving', async () => { const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'applyEdit', LSP_FAKE_DEF: 'null' }) - await expect(run(instance, 'definition')).resolves.toEqual({ kind: 'locations', locations: [] }) + await expect(run(instance, 'definition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws }) }) it('rejects an unknown server request but keeps serving', async () => { const instance = makeInstance({ LSP_FAKE_ON_OPEN: 'unknown', LSP_FAKE_DEF: 'null' }) - await expect(run(instance, 'definition')).resolves.toEqual({ kind: 'locations', locations: [] }) + await expect(run(instance, 'definition')).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws }) }) }) @@ -195,6 +195,18 @@ describe('LspInstance query and abort', () => { }) describe('LspInstance disposal', () => { + it('lets a server finish protocol exit before signal escalation', async () => { + const marker = join(root, 'graceful-exit.log') + const instance = makeInstance({ + LSP_FAKE_DEF: 'null', + LSP_FAKE_EXIT_DELAY_MS: '75', + LSP_FAKE_EXIT_MARKER: marker, + }, { shutdownTimeoutMs: 500 }) + await run(instance, 'definition') + await instance.dispose() + expect(await readFile(marker, 'utf8')).toBe('EXIT\nCLEAN\n') + }) + it('is idempotent — a second dispose awaits close without error', async () => { const instance = makeInstance({ LSP_FAKE_DEF: 'null' }) await run(instance, 'definition') diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts index bf624a1c56..78f1a8e419 100644 --- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts +++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts @@ -59,6 +59,7 @@ describe('lsp-local end to end over a fake server', () => { expect(result).toEqual({ kind: 'locations', locations: [{ uri: pathToFileURL(join(ws, 'a.ts')).href, range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } } }], + resolvedWorkspaceRoot: ws, }) await ctx.fiber.dispose() }) @@ -89,7 +90,7 @@ describe('lsp-local end to end over a fake server', () => { it('returns an empty locations result for a null definition', async () => { const ctx = await mount({ LSP_FAKE_DEF: 'null' }) - expect(await ctx.lsp.query(query('definition'))).toEqual({ kind: 'locations', locations: [] }) + expect(await ctx.lsp.query(query('definition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws }) await ctx.fiber.dispose() }) @@ -123,7 +124,7 @@ describe('lsp-local end to end over a fake server', () => { it('accepts openClose options sync', async () => { const ctx = await mount({ LSP_FAKE_SYNC: JSON.stringify({ openClose: true, change: 2 }), LSP_FAKE_DEF: 'null' }) - expect(await ctx.lsp.query(query('definition'))).toEqual({ kind: 'locations', locations: [] }) + expect(await ctx.lsp.query(query('definition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws }) await ctx.fiber.dispose() }) @@ -195,6 +196,31 @@ describe('lsp-local end to end over a fake server', () => { await ctx.fiber.dispose() }) + it('evicts a pooled server that died while idle and serves the next query from a fresh one', async () => { + // The first query succeeds, then the server exits before the second arrives, leaving a dead + // instance in the pool. The next query must evict-and-replace it and still succeed, rather than + // failing once on the closed connection first. + const ctx = await mount({ LSP_FAKE_EXIT_AFTER_REPLY: '1', LSP_FAKE_DEF: JSON.stringify(locationJson(0)) }) + expect(await ctx.lsp.query(query('definition'))).toMatchObject({ kind: 'locations' }) + // Wait past the fixture's post-reply exit so the pooled instance is observably dead. + await new Promise(resolve => setTimeout(resolve, 60)) + expect(await ctx.lsp.query(query('definition'))).toMatchObject({ kind: 'locations' }) + await ctx.fiber.dispose() + }) + + it('does not spawn a server when the signal aborts during source read', async () => { + // Abort right after issuing the query: the abort lands while canonicalizeWorkspace/readHostSource + // are awaited, so the pre-spawn recheck must reject without ever creating a pooled instance. + const ctx = await mount({ LSP_FAKE_DEF: 'null' }) + const controller = new AbortController() + const pending = ctx.lsp.query(query('definition'), controller.signal) + controller.abort(new Error('mid-read cancel')) + await expect(pending).rejects.toThrow(/mid-read cancel/) + // A subsequent live query still works, proving no half-created instance poisoned the pool. + expect(await ctx.lsp.query(query('definition'))).toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: ws }) + await ctx.fiber.dispose() + }) + it('runs distinct workspaces in parallel instances', async () => { const ws2 = join(root, 'ws2') await mkdir(ws2) diff --git a/packages/lsp/lsp-local/tests/provider.spec.ts b/packages/lsp/lsp-local/tests/provider.spec.ts index 20978df8d5..53f9a88369 100644 --- a/packages/lsp/lsp-local/tests/provider.spec.ts +++ b/packages/lsp/lsp-local/tests/provider.spec.ts @@ -102,4 +102,16 @@ describe('lsp-local provider resolution', () => { })).rejects.toThrow(/is not an executable file/) await ctx.fiber.dispose() }) + + it('rejects an executable directory as a command at load', async () => { + const ctx = new Context() + await ctx.plugin(Lsp) + await expect(ctx.plugin(LspLocal, { + providerId: 'abs-directory', + command: ws, + args: [], + extensionToLanguage: { '.ts': 'typescript' }, + })).rejects.toThrow(/is not an executable file/) + await ctx.fiber.dispose() + }) }) diff --git a/packages/lsp/lsp/README.md b/packages/lsp/lsp/README.md index eac45e9f51..8e51d0653a 100644 --- a/packages/lsp/lsp/README.md +++ b/packages/lsp/lsp/README.md @@ -25,7 +25,7 @@ Providers register **capabilities**, not tools. `dsh-tool-lsp` is the only owner ## Vocabulary -`LspQueryRequest` (`operation`, `filePath`, `position`, `workspaceRoot`) — every field required, so no field needs implementation defaulting and there is no `resolve()` step. Positions and ranges are zero-based UTF-16, matching the protocol; the tool owns the one-based cursor convention. `references` always includes declarations — providers enforce this internally, so callers get no flag. `LspQueryResult` is a CLOSED discriminated union: `{ kind: 'locations'; locations }` for navigation, `{ kind: 'hover'; hover }` for hover (content or `null`) — consumers `switch` to exhaustiveness so a new arm breaks compilation until handled. See `src/types.ts` for the full contracts and `src/index.ts` for the `LspError` codes. +`LspQueryRequest` (`operation`, `filePath`, `position`, `workspaceRoot`) — every field required, so no field needs implementation defaulting and there is no `resolve()` step. Positions and ranges are zero-based UTF-16, matching the protocol; the tool owns the one-based cursor convention. `references` always includes declarations — providers enforce this internally, so callers get no flag. `LspQueryResult` is a CLOSED discriminated union: `{ kind: 'locations'; locations; resolvedWorkspaceRoot }` for navigation, `{ kind: 'hover'; hover }` for hover (content or `null`) — consumers `switch` to exhaustiveness so a new arm breaks compilation until handled. `resolvedWorkspaceRoot` is the provider's canonical form of the request's `workspaceRoot` and the root its `file:` URIs are relative to; a caller relativizing display paths uses it, not the (possibly symlinked) request root. See `src/types.ts` for the full contracts and `src/index.ts` for the `LspError` codes. ## Model Experience diff --git a/packages/lsp/lsp/src/types.ts b/packages/lsp/lsp/src/types.ts index 0a2d73fac1..d1ae71dccd 100644 --- a/packages/lsp/lsp/src/types.ts +++ b/packages/lsp/lsp/src/types.ts @@ -76,9 +76,14 @@ export interface LspHover { * The closed result union. Navigation operations (`definition`, `references`, `implementation`) * normalize to `locations`; `hover` normalizes to content or `null`. Consumers `switch` on `kind` * to exhaustiveness so a new arm breaks compilation until handled. + * + * The `locations` variant carries `resolvedWorkspaceRoot`: the provider's canonical form of the + * request's `workspaceRoot`, and the root its `file:` location URIs are relative to. A caller that + * relativizes display paths MUST use this, not the request's (possibly symlinked) `workspaceRoot`; + * otherwise a symlinked workspace misclassifies in-workspace results as external. */ export type LspQueryResult = - | { readonly kind: 'locations'; readonly locations: readonly LspLocation[] } + | { readonly kind: 'locations'; readonly locations: readonly LspLocation[]; readonly resolvedWorkspaceRoot: string } | { readonly kind: 'hover'; readonly hover: LspHover | null } /** diff --git a/packages/lsp/lsp/tests/lsp.spec.ts b/packages/lsp/lsp/tests/lsp.spec.ts index 6746a05dc3..8561891df1 100644 --- a/packages/lsp/lsp/tests/lsp.spec.ts +++ b/packages/lsp/lsp/tests/lsp.spec.ts @@ -13,7 +13,7 @@ import Lsp, { function makeProvider( id: string, extensionToLanguage: Record, - result: LspQueryResult = { kind: 'locations', locations: [] }, + result: LspQueryResult = { kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' }, ): LspProvider & { seen: LspProviderQuery[]; seenSignals: (AbortSignal | undefined)[] } { const seen: LspProviderQuery[] = [] const seenSignals: (AbortSignal | undefined)[] = [] @@ -63,7 +63,7 @@ describe('Lsp registration', () => { const provider = makeProvider('ts', { '.ts': 'typescript' }) const dispose = lsp.registerProvider(provider) - await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [] }) + await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' }) expect(provider.seen[0]).toMatchObject({ filePath: 'a.ts', languageId: 'typescript' }) dispose() @@ -148,7 +148,7 @@ describe('Lsp registration', () => { const py = makeProvider('py', { '.py': 'python' }) lsp.registerProvider(ts) lsp.registerProvider(py) - await expect(lsp.query(query('a.py'))).resolves.toEqual({ kind: 'locations', locations: [] }) + await expect(lsp.query(query('a.py'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' }) await expect(lsp.query(query('a.ts', 'hover'))).resolves.toEqual(hover) }) @@ -172,7 +172,7 @@ describe('Lsp registration', () => { const fiber = await ctx.plugin(Object.assign((inner: Context) => { inner.lsp.registerProvider(makeProvider('ts', { '.ts': 'typescript' })) }, { inject: ['lsp'] })) - await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [] }) + await expect(lsp.query(query('a.ts'))).resolves.toEqual({ kind: 'locations', locations: [], resolvedWorkspaceRoot: '/ws' }) await fiber.dispose() await expect(lsp.query(query('a.ts'))).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' })) }) diff --git a/packages/lsp/tool-lsp/README.md b/packages/lsp/tool-lsp/README.md index fdbd89d96b..179405c71e 100644 --- a/packages/lsp/tool-lsp/README.md +++ b/packages/lsp/tool-lsp/README.md @@ -8,7 +8,7 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export). In `lsp` accepts `operation` (`definition` | `references` | `implementation` | `hover`), `file_path`, `line`, and `character`. `line` and `character` are positive, one-based UTF-16 cursor coordinates; the tool converts them to the seam's zero-based positions and converts rendered locations back. `references` includes declarations so impact analysis does not omit the defining site. Provider, language id, workspace root, limits, timeout, initialization, and executable stay outside model input. -The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Locations render as stable, file-grouped `path:line:character` entries; a `file:` URI becomes a workspace-relative path (inside) or absolute path (outside), and any other URI stays verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors. +The tool requires the workspace root from the session `header.cwd`, with no fallback: absence fails as `LSP_WORKSPACE_REQUIRED` before querying. Locations render as stable, file-grouped `path:line:character` entries relativized against the result's `resolvedWorkspaceRoot` (the provider's canonical root), not the session cwd — so a symlinked cwd still renders in-workspace results as workspace-relative paths; a `file:` URI becomes a workspace-relative path (inside) or absolute path (outside), and any other URI stays verbatim. Empty locations and `null` hover are successful no-result responses; malformed provider payloads remain structured errors. ## Configuration diff --git a/packages/lsp/tool-lsp/src/index.ts b/packages/lsp/tool-lsp/src/index.ts index 1ec48a3d74..3a37b7b6ed 100644 --- a/packages/lsp/tool-lsp/src/index.ts +++ b/packages/lsp/tool-lsp/src/index.ts @@ -113,7 +113,10 @@ export function apply(ctx: Context, config: Config): void { }, exec.signal) switch (result.kind) { case 'locations': - return [{ type: 'text', text: formatLocations(result.locations, workspaceRoot, resolved.maxLocations) }] + // Relativize against the provider's canonical workspace root (which its file: URIs are + // relative to), not the session cwd: a symlinked cwd would otherwise misclassify every + // in-workspace location as external and render it as an absolute path. + return [{ type: 'text', text: formatLocations(result.locations, result.resolvedWorkspaceRoot, resolved.maxLocations) }] case 'hover': return [{ type: 'text', text: formatHover(result.hover, resolved.maxHoverChars) }] } diff --git a/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts b/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts index 9cd48ed87f..577fa07396 100644 --- a/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts +++ b/packages/lsp/tool-lsp/tests/tool-lsp.spec.ts @@ -51,6 +51,7 @@ function call(ctx: Context, args: unknown, cwd: string | null = '/ws') { const okLocations: LspQueryResult = { kind: 'locations', locations: [{ uri: 'file:///ws/a.ts', range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }], + resolvedWorkspaceRoot: '/ws', } describe('tool-lsp registration', () => { @@ -107,6 +108,21 @@ describe('tool-lsp execution', () => { expect(result.content[0]).toEqual({ type: 'text', text: 'a.ts:1:1' }) }) + it('relativizes against the provider resolvedWorkspaceRoot, not the session cwd', async () => { + // A symlinked session cwd (`/alias`) resolves to a real path (`/real/ws`) that the provider's + // location URIs are under. Relativizing against the alias would misclassify the location as + // external and print an absolute path; the tool must use resolvedWorkspaceRoot. + const provider = stubProvider(() => ({ + kind: 'locations', + locations: [{ uri: 'file:///real/ws/a.ts', range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } } }], + resolvedWorkspaceRoot: '/real/ws', + })) + const { ctx } = await mount(provider) + const result = await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 1, character: 1 }, '/alias') + expect(provider.seen[0]).toMatchObject({ workspaceRoot: '/alias' }) + expect(result.content[0]).toEqual({ type: 'text', text: 'a.ts:1:1' }) + }) + it('renders hover content', async () => { const { ctx } = await mount(stubProvider(() => ({ kind: 'hover', hover: { contents: 'number' } }))) const result = await call(ctx, { operation: 'hover', file_path: 'a.ts', line: 1, character: 1 }, '/ws') From 8a33e7cd006eab76000392cef1bbc20d9552b174 Mon Sep 17 00:00:00 2001 From: NI0317 Date: Thu, 16 Jul 2026 16:53:25 +0800 Subject: [PATCH 017/273] docs(rfc): propose harness-level goal-based loop MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introduce packages/loop as a capability seam covering goal-based (and naturally proactive) loops around the existing agent-loop, deferring time-based scheduling to a future dsh-schedule RFC. Four cordis service seams — loop-as-session, pluggable Evaluator/Budget with EvaluatorSpec tiers and protectedPaths, RoundHandoff, GoalReflector — plus a driver- enforced Default-FAIL contract and reuse of packages/fs policy gate for reward-hacking defense. Bilingual pair. --- docs/rfc/INDEX.md | 1 + .../2026-07-16-harness-level-loop.i18n.yaml | 6 + .../feature/2026-07-16-harness-level-loop.md | 321 ++++++++++++++++++ .../2026-07-16-harness-level-loop.zh.md | 321 ++++++++++++++++++ 4 files changed, 649 insertions(+) create mode 100644 docs/rfc/proposed/feature/2026-07-16-harness-level-loop.i18n.yaml create mode 100644 docs/rfc/proposed/feature/2026-07-16-harness-level-loop.md create mode 100644 docs/rfc/proposed/feature/2026-07-16-harness-level-loop.zh.md diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index a60579ef4c..17dcb13f8f 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -14,6 +14,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [SQLite FTS5 session search](proposed/feature/2026-07-10-sqlite-session-query-provider.md) | 2026-07-10 | | [Stream workflow progress through tool calls](proposed/feature/2026-07-13-stream-workflow-progress-through-tool-calls.md) | 2026-07-13 | | [Developer-owned SDK projects](proposed/feature/2026-07-14-sdk-developer-projects.md) | 2026-07-14 | +| [harness-level goal-based loop](proposed/feature/2026-07-16-harness-level-loop.md) | 2026-07-16 | ### Simplification diff --git a/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.i18n.yaml b/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.i18n.yaml new file mode 100644 index 0000000000..fe26d5d8a4 --- /dev/null +++ b/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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 +2026-07-16-harness-level-loop.md: 8bc4ecf3734a7e9d82d1f844b3d7186fa6ccafed +2026-07-16-harness-level-loop.zh.md: 4e1b677259b310171098cc78dd174b55c8d69970 diff --git a/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.md b/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.md new file mode 100644 index 0000000000..8bc4ecf373 --- /dev/null +++ b/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.md @@ -0,0 +1,321 @@ +# RFC: harness-level goal-based loop + +Status: proposed + +English | [中文](2026-07-16-harness-level-loop.zh.md) + +## Problem + +`packages/core/agent-loop` runs only the inner loop: reasoning plus tool calls within one turn, ending when the model returns `end_turn`. Its README explicitly writes "No built-in turn budget"—budget is a gap it acknowledges itself. Cross-round scheduling falls on the harness layer: iterating until tests all pass, revising drafts against a rubric, splitting a PRD into beads and driving them one by one, running unattended for a whole night. None of these tasks has a first-class implementation today. + +The existing code offers three "just enough to run" alternatives, none of them adequate: + +| Alternative | Problem | +|---|---| +| A `packages/workflow` script expressing `while (!done)` | The README explicitly writes "No token-budget vocabulary" and "No journaling or resume"; the parent turn blocks until the script settles. Fine for orchestration lasting minutes, unusable for tasks lasting hours | +| An external shell `while :; do dsh …; done` | Ralph-style scheduling can be written this way today. It lacks a shared vocabulary for stop condition, budget, and evaluator, so every user reinvents them; the loop itself has no durable object for post-hoc diagnosis or recovery | +| The `sendMessage`/`resume` capabilities on the `packages/subagent` seam | The README explicitly writes "Runtime steering and continuation are seam-only capabilities". There is no model-facing consumer, so the model can only start a fresh subagent | + +Three typical use cases. **Automated fix**: a failing test suite in front of you, and you want a process to keep modifying code, running tests, and modifying again against the failure messages, until everything is green or the budget cap is hit. **Rubric-driven iterative revision**: a document, code, or translation must meet a set of scoring criteria; the loop repeatedly adjusts, an independent evaluator scores, and the loop stops when the criteria are met or the round budget is exhausted. **Unattended long runs**: for example, porting a repository from one tech stack to another overnight, kicked off before leaving work and reviewed the next morning, with the budget as the only safety net. Common shape across all three: minutes to hours, evaluator decides success, budget is a hard constraint, and post-run review and recovery are required. + +## Proposal + +**Loops come in four trigger shapes**, distinguished by who starts a round and when: + +| Shape | Who triggers | When | Existing comparable | This RFC | +|---|---|---|---|---| +| **turn-based** | The user sends a message in the session | Every user reply | `packages/core/agent-loop`'s existing reasoning-plus-tools cycle within one turn | Not covered; already implemented | +| **goal-based** | The user or the agent specifies "run until some condition" | One start, evaluator decides when to stop | Claude Code's `/goal`, Codex's `/goal`, the Ralph family | **This RFC covers it** | +| **time-based** | A scheduler | On cron or fixed interval | Claude Code's `/loop` (periodic), `/schedule` | Deferred to a `dsh-schedule` RFC | +| **proactive** | The agent itself | When the agent realizes during reasoning that a loop is needed | The proactive tier in Anthropic ClaudeDevs's four-way taxonomy | **Naturally included** (an agent calling the `loop` tool is already proactive) | + +This RFC only **adds a capability seam `packages/loop/`** for the goal-based shape. Proactive reuses the same `loop` tool—an agent invocation is a trigger by itself, with no extra machinery. Time-based needs an independent scheduler package and belongs to a separate RFC; this RFC only reserves a hook on the cordis leaf trigger surface for the future `dsh-schedule` integration. + +Three packages: + +- `@deepseek-ai/dsh-loop`: types, the `LoopDriver` service, the `StopCondition` discriminated union, four built-in service definitions (`Evaluator` / `BudgetPolicy` / `RoundHandoff` / `GoalReflector`), and the event schema +- `@deepseek-ai/dsh-loop-driver`: the default driver implementation +- `@deepseek-ai/dsh-loop-tool`: the model-facing `loop` tool plus the CLI `dsh loop` + +The design is organized around four concrete problems, each addressed by an independent cordis service seam: + +1. A long-running loop that goes wrong leaves no systematic diagnosis or recovery. **Loop as an independent session** addresses this. +2. Whether the PASS at loop end is trustworthy determines whether hours of work are wasted. An architecture where the same LLM both generates and self-evaluates is not trustworthy on its face. **Making Evaluator and Budget into service seams** addresses this. +3. Short and long tasks need opposite memory strategies; hardcoding one mode makes the other class of scenario unusable. **Making RoundHandoff into a service seam** addresses this. +4. The user's initial goal is not always correct. An agent stubbornly pursuing a wrong goal exhausts the budget doing wrong work. **Making GoalReflector into a service seam** addresses this. + +Beyond the four seams, one principle threads through the whole document: **one loop handles one atomic goal**. Large goals should be split into several small loops chained in sequence, not stuffed into one loop with the evaluator judging multiple things. A rule of thumb for whether granularity is right: if you cannot say what a finished loop actually accomplished, granularity is too large and should be split. Phase 2 adds a `loop_split` model-facing tool so the agent can split an oversized goal itself. + +Terminology: **inner loop** refers to the existing per-turn reasoning-and-tools cycle in `packages/core/agent-loop`; **harness loop** refers to the outer scheduler introduced by this RFC, iterating around the inner loop. This RFC does not modify `agent-loop`, matching AGENTS.md's "Plugins, not loop changes". + +`StopCondition` is a discriminated union with `assertNever` closing the switch: + +```ts +interface EvaluatorReport { criteria: readonly { name: string; pass: boolean; evidence: readonly string[] }[] } + +type StopCondition = + | { kind: 'goal-met'; evidence: EvaluatorReport } + | { kind: 'budget-cap'; scope: 'usd' | 'tokens' | 'rounds' } + | { kind: 'stuck'; pattern: 'repeat-action' | 'no-progress' | 'error-loop' } + | { kind: 'approval-required'; reason: string } + | { kind: 'user-cancel' } + +export {} +``` + +### Loop as an independent session + +Once a long-running loop goes wrong, the user has no systematic diagnostic method. A failure hours in leaves only scattered log files to sift through. Discovering that some middle round went off track and wanting to roll back to re-run means starting over from scratch. An agent wanting to consult its own experience from past loops has no API to reach it. + +The driver opens an independent loop-session (a new session id) for each loop. Every round's inputs, inner-loop results, evaluator reports, and stop decisions are persisted as session events, reusing the SQLite backend from `packages/session-persistence`. This yields three capabilities. + +- **Resume from any round**: discover round 78 went off, restart from round 77 with a different prompt or evaluator, no need to start over +- **Post-hoc diagnosis**: through [sqlite-session-query-provider](2026-07-10-sqlite-session-query-provider.md), query "which round did the evaluator start hanging on the same criterion" to locate the stuck point +- **Meta-loop learning**: before starting a new loop, the agent queries its own experience from past loops of the same kind—"have I fixed a similar bug before? Which round did it fail on?" + +Claude Code's and Codex's `/goal` are one-off objects: discarded when the run ends, so the agent starts from zero when facing a similar problem again. + +**Storage and dependency**. A few KB of events per round, roughly 100–500 KB per 100-round loop; thousands of loops reach GB scale. Mitigated by the `logDetail: 'summary' | 'full'` config, defaulting to `full` with long-run users able to switch to `summary`. Persisting all intermediate state also writes generated keys, passwords, and similar secrets to disk—the same class of risk as an ordinary session but amplified 10–100×, and the README calls this out clearly. **The most critical point**: this section's capabilities have a hard dependency on the not-yet-landed [sqlite-session-query-provider RFC](2026-07-10-sqlite-session-query-provider.md). If that RFC does not land, arbitrary-round resume and query capability degrade to "just grep the JSONL files". If Phase 1 ships before that RFC merges, Phase 1 only guarantees correct event shape and defers the query surface to Phase 2. + +### Pluggable Evaluator and Budget + +A loop's value ultimately depends on whether the final PASS is trustworthy. If the evaluator can be hacked or hallucinates PASS, hours of work are wasted. An architecture where the same LLM both generates and self-evaluates is not trustworthy on its face: the model has the means to talk itself into PASS. Even letting an independent subagent be the evaluator only mitigates the problem; as long as the evaluator is still an LLM, it retains a systematic bias for the same class of content—an independent subagent is a mitigation, not a cure. + +Truly trustworthy evaluation must be a fully non-LLM hard check: shell exit code, static analysis, an external service. The LLM physically cannot touch the evaluation process. But only the user knows which hard check to run: `pytest` commands differ by project, companies have private compliance checkers, some teams also run internal lint. No number of built-in evaluators can cover them all. Evaluator therefore must be a seam the user can plug into. + +Budget is the same story: product-level spending guardrails are opaque, and cannot be adjusted for team policy (personal card, team splitting, per-PR settlement). + +`Evaluator` and `BudgetPolicy` are both exposed as cordis service seams, with users injecting them as plugins. `Goal` must carry an `EvaluatorSpec` at an explicit tier; the driver refuses to start a loop without a paired evaluator—vague goals ("write good code") cannot enter the loop system: + +```ts +interface RubricItem { name: string; description: string } +interface EvaluatorContract { readonly name: string } + +type EvaluatorSpec = { + tier: + | { kind: 'single-metric'; check: string } // "pytest -q && ruff check"、"exit code == 0" + | { kind: 'rubric'; criteria: RubricItem[] } // 若干独立 criterion,各自 pass/fail + evidence + | { kind: 'contract'; interface: EvaluatorContract } // 结构化合约(如 API sig 校验) + | { kind: 'llm-judge'; rubric: string; model: string } // 兜底档,仅软目标 + /** + * 主 agent 不可写的路径(通常是 evaluator 会读的测试文件、评估配置)。 + * 违规写会被 packages/fs policy gate 拒绝,记 loop/hack-attempt session event。 + * 这是防 reward hacking 的核心机制——把「改测试让 evaluator 通过」这条路封死。 + */ + protectedPaths?: readonly string[] +} + +export {} +``` + +**Why tiers instead of letting the user pass any function?** Tiers force the user, at start time, to declare "which strength of judgment I'm using". A free function looks flexible, but in practice it lets evaluator strength quietly regress—the user thinks they're doing strict judgment when they've actually written a fuzzy LLM-judge-style semantic match. In long-run scenarios the cost is hours wasted. + +The four tiers descend in trustworthiness from top to bottom. The top three are fully non-LLM hard checks. `llm-judge` is the weakest tier, only for soft goals where there truly is no hard signal (revision, translation quality). The documentation explicitly notes "this tier cannot defend against targeted adversarial input; long unattended runs require at least one hard-check tier alongside". + +The driver enforces five hard constraints, not delegated to Evaluator implementations. They address three distinct attack surfaces: + +**Preventing "the same agent both generates and self-evaluates"**: + +1. **fresh subagent**: the evaluator opens a fresh subagent (via `dsh-subagent`'s `spawn`) each round, not inheriting the main loop's context + +**Preventing the main agent from reward-hacking by modifying evaluator inputs**: + +2. **`protectedPaths` hard isolation**: paths declared in `EvaluatorSpec` (typically test files and evaluator config) are rejected for main-agent writes by the existing policy gate in `packages/fs`, and blocked writes are recorded as `loop/hack-attempt` session events. This is Phase 1's real defense against reward hacking—it seals off the "modify the tests so the evaluator passes" path directly + +**Preventing the evaluator subagent itself from being subverted**: + +3. **read-only tool set**: the evaluator's tool set is stripped by the driver to reads only, with write tools disabled (reusing `SubagentProvider`'s `toolFilter`). It defends not against main-agent reward hacking, but against the evaluator being prompted-injected via code embedded in the code being evaluated—so it cannot be tricked into modifying state + +**Preventing the evaluator report itself from deceiving the driver**: + +4. **PASS can only flip via an evaluator report**: the `goal-met` StopCondition can only come from the evaluator; the driver and the main agent cannot construct it directly +5. **Default-FAIL**: the driver maintains each criterion's pass state at `false` internally; only an evaluator report with non-empty evidence is allowed to flip it to `true`. The evaluator cannot get the driver to accept a `{pass: true}` return with no evidence + +Together, the five decide that evaluator conclusions can only be driven by evidence—not by confidence, and not by the main agent quietly modifying tests. + +**Phase 1 ships three backends**: + +- `loop-evaluator-shell` implements `single-metric`: runs a shell command, `exit 0` = pass +- `loop-evaluator-rubric-judge` implements `llm-judge`: a prewritten rubric plus LLM scoring, soft goals only +- `loop-budget-preflight`: before each round starts, estimate `(promptTokens + overhead + estOutputTokens) / 1M × pricePerMTok`; refuse to start if the estimate exceeds `perRoundUsd`. The estimation model comes from MartinLoop `policy.ts:551-596` + +A `PricingProvider` service injects the pricing table; a test seam can override it, and it is not hardcoded into the driver (AGENTS.md "No hardcoded tunables in plugins"). The `rubric` and `contract` tiers get built-in implementations in Phase 2; Phase 1 only exposes the types so third-party plugins can integrate first. + +**Limitation**: the "read-only tools" the evaluator subagent receives are still shell and fs reads within the same process, and could theoretically be bypassed by prompt injection. Defending against targeted adversarial input requires the two-container approach (the evaluator's definition files are entirely inaccessible to the main agent, the route Anthropic patch.py takes), which is a Phase 3 item. See Risks. + +### Pluggable RoundHandoff + +How context passes between rounds is a dilemma. Preserving the full prior conversation (continue) reads more coherently, but the conversation keeps growing and eventually hits the context ceiling, and errors from a prior round contaminate every subsequent round. Starting each round from scratch (fresh) avoids the contamination, but has to re-understand context every time. A 3-round revision loop and an 80-round overnight bug-fix loop need opposite strategies. Claude Code and Codex both hardcode one mode, so users cannot switch by task type. + +Made a service seam: + +```ts +interface RoundContext { loopId: string; round: number } +interface NextRoundSpec { mode: 'fresh' | 'continue' } + +interface RoundHandoff { + buildNextRound(prev: RoundContext): NextRoundSpec +} + +export {} +``` + +Phase 1 ships three backends: + +| Backend | Scenario | Mechanism | +|---|---|---| +| `handoff-fresh-with-summary` (default) | Long runs, unattended | Open a fresh subagent each round, injecting only a progress summary as a system prompt append | +| `handoff-continue-with-compaction` (recommended middle) | Medium length, 5–20 rounds | Retain the full conversation up to a token threshold; over the threshold, reuse [`packages/compact`](../../../../packages/compact/README.md) to compress into a summary, using summary + last K rounds as the starting point | +| `handoff-continue-raw` (advanced) | ≤5 rounds, short tasks, testing | Plain continuation without truncation | + +**Why default to fresh?** Every long-run loop that actually succeeded (repomirror, Kimi ralph-loop, autoresearch) uses fresh. Placing important loop state outside the context window under driver management is the correct posture for long runs. `handoff-continue-raw` violates this experience, and the README explicitly notes it is not suitable for long runs. + +**Why is only this repo able to build the middle tier?** `handoff-continue-with-compaction` depends on a compaction seam—the competitors don't have one; only this repo's `packages/compact` provides that infrastructure. + +**Why a seam rather than a three-choice flag?** Users can write 20-line plugins expressing hybrid strategies like "continue for the first 5 rounds, then fresh", or "auto-compact once when context hits 50%", without waiting for main-library support. + +**Limitation**: `continue-with-compaction` depends on the compression quality of `packages/compact`; compression itself may write hallucinated information into the summary and propagate it forward. The README recommends fresh for long runs. The three backends' boundaries may confuse new users about which to pick; the `dsh loop` CLI defaults to fresh, so users don't have to understand the differences before hitting a concrete problem. + +### Pluggable GoalReflector + +The goal the user gives at loop start is not always accurate. It may be based on a wrong assumption (asking the agent to implement a feature with a since-deprecated API), it may not be clear enough (the agent discovers a clarification is needed only mid-work), or it may be invalidated by later information. Current loop-execution frameworks treat the goal as a contract frozen at start; the agent can only push down the original path, and the result is exhausting the budget on the wrong direction. + +Made a service seam, with responsibility separated from `Evaluator`: the evaluator asks "did we reach the goal", the reflector asks "is the goal still the same goal". + +```ts +interface RoundContext { loopId: string; round: number } +interface GoalConcern { concern: string; severity: 'low' | 'medium' | 'high' } + +interface GoalReflector { + reflect(ctx: RoundContext, concerns: GoalConcern[]): Promise +} + +type GoalReflection = + | { kind: 'continue' } // goal 仍有效 + | { kind: 'revise'; newGoal: string; why: string } // 建议修正 goal + | { kind: 'stop-for-human'; reason: string } // 需要人拍板 + +export {} +``` + +**Concerns have three sources**, and Phase 1 ships the first two: + +- **Agent-initiated**: via the model-facing tool `loop_flag_concern({ concern, severity })`. An agent that realizes during investigation that "the library the user assumed has been deprecated" can raise directly +- **Driver heuristic**: when budget passes 50% and zero criteria have passed, the driver auto-raises a `no-progress-toward-goal` concern +- **Periodic reflector subagent** (Phase 2): every N rounds, run an independent read-only subagent to re-audit goal validity, following the same isolation approach as the evaluator + +**Response strategy is controlled by the `onGoalConcern` config**. The four settings correspond to different philosophies about loop use; users choose by their team's collaboration style, and the driver takes no default stance: + +- `'stop'` (Phase 1 default): any concern triggers `StopCondition: approval-required`, and a human decides. A loop should never proceed on its own in the face of uncertainty—suitable for cautious teams and for high-impact loop scenarios +- `'notify-continue'` (Phase 1): record a high-priority `loop/goal-concern` session event plus an explicit ACP notification, then continue; a human reviews at the end. The loop internal is not interrupted—suitable for unattended long runs +- `'reflect'` (Phase 2): call `GoalReflector` to decide continue, revise, or stop. Delegates the initial judgment to an independent agent in place of a human—suitable for teams with moderate autonomy +- Not registering a `GoalReflector` and leaving `onGoalConcern` unset = the most hands-off tier: the loop stops only on traditional stop conditions + +**Why default to `stop`?** In unattended scenarios, stopping one extra time is safer than running for hours in the wrong direction. Users who explicitly want unattended can switch to `notify-continue`. + +A concern is itself just an ordinary session event, composing naturally with the persistence capability described earlier: on resume, one can pick up from the round where the concern surfaced, swap the goal, and re-run—the work of the previous N rounds is not lost. + +**Abuse and loss protection**. An agent could raise a concern every round; the mitigation is the `severity` field plus a minimal rate limit on the driver side (same-concern dedup within 30 seconds). The cost of that abuse is that the agent stalls itself and cannot make progress, so the incentive is weak. Once a goal has been revised, the original goal is lost; each revise persists a `loop/goal-revised` session event with rationale, and resume can select any historical goal version. + +### User surface + +Four trigger surfaces share one driver: + +- **Agent-side tool**: `loop({ goal, evaluator, maxRounds, maxUsd, onGoalConcern })` starts a nested harness loop. Inside a running loop, the internal agent can call `loop_flag_concern({ concern, severity })` to raise a concern proactively. ACP rendering intent is `generic`. An agent-initiated call is proactive triggering with no extra machinery +- **CLI**: `dsh loop --stop --max-rounds N --max-usd X --handoff fresh` is human-initiated startup, the most typical Ralph-style usage +- **cordis leaf**: declare a resident loop as a leaf in `cordis.yml`, with future `dsh-schedule` RFC integration for periodic triggering +- **ACP slash command**: `/loop ` (and `/loop-flag-concern`) starts directly from within the editor or client's current session. Semantically equivalent to a human typing `dsh loop` in a shell, but happens within the ongoing ACP session context, letting the loop result inject back into the session + +The ACP slash command depends on: `packages/ui/acp`'s `available_commands_update` surface is currently unbuilt ([acp-feature-support.md](../../../../packages/ui/acp/acp-feature-support.md)). Once the harness's slash-command infrastructure lands, `/loop` and `/loop-flag-concern` only need to be registered against that infrastructure; the driver and tool interfaces do not change. This RFC reserves the names and specifies the argument shape, but does not commit the infrastructure itself—that belongs to a separate ACP catch-up RFC. + +The default system prompt carries two hard constraints, distributed with every built-in `loop` tool: + +1. No writing of `TODO`, `FAKE`, or `PLACEHOLDER` placeholders to superficially pass the evaluator +2. No writing of empty `try/except` or `catch(_)` blocks so the evaluator ignores errors + +Neither can be stopped at the seam layer; both are prompt-layer conventions. Users may customize the system prompt but the built-in constraints remain. + +### Relationship with existing code + +Direct reuse without modification: + +- `packages/subagent`'s `spawn` provider, `toolFilter`, and `persona`—the loop spawns a subagent per round; the evaluator gets the read-only tool set +- The SQLite backend from `packages/session-persistence`—the loop-session persists +- `packages/compact`—the implementation basis for `handoff-continue-with-compaction` +- `packages/todo`—an optional progress representation in single-session continue mode +- If [ToolExecution.reportProgress](2026-07-13-stream-workflow-progress-through-tool-calls.md) lands first, the loop tool can use it for per-round UI updates + +Not touched: `packages/core/agent-loop` (the inner-loop semantics stay the same); `packages/workflow` (DAG orchestration vs. iterating one goal is an orthogonal relationship; the two READMEs cross-link in their "Related" section to describe the boundary). + +Two dependencies not yet landed: + +- [sqlite-session-query-provider](2026-07-10-sqlite-session-query-provider.md)—see the limitation paragraph of Loop as an independent session for the mitigation +- The ACP slash-command infrastructure (the `available_commands_update` surface)—see User surface. Before the infrastructure lands, the slash-command trigger is absent while the other three trigger surfaces work as normal + +The one modification to existing code can be deferred to Phase 2: adding a "resume an existing subagent" argument surface to `packages/subagent-tool`, used by the `handoff-continue-*` backends. The underlying `SubagentRun.sendMessage` and `resume` already exist as seam capabilities; only the tool-layer argument entrypoint is missing. If Phase 1 ships only `handoff-fresh-with-summary`, subagent-tool need not be touched at all; Phase 2 adds it. + +### Phasing + +**Phase 1** (the scope this RFC commits): the three-package seam; `StopCondition`; the four-tier `EvaluatorSpec` type plus the `protectedPaths` hard isolation (reusing the `packages/fs` policy gate), with built-in implementations for `single-metric` and `llm-judge` and the `rubric` and `contract` types open for integration; Default-FAIL enforcement; three built-in evaluator/budget/handoff backends; the `loop_flag_concern` tool; the no-progress heuristic; the `onGoalConcern: 'stop' | 'notify-continue'` pair; the CLI; the tool; the default system prompt hard constraints. **Not included**: the session-query surface, the ACP slash-command trigger surface (depends on the `available_commands_update` infrastructure), the subagent-tool resume change, the stuck detector, the Reflector subagent, the `loop_split` tool, and the built-in implementations of the `rubric` and `contract` tiers. + +**Phase 2**: the query surface; the stuck detector (reproducing OpenHands's five patterns); the subagent-tool resume change (unlocking the two continue tiers of handoff); the Reflector subagent; the `onGoalConcern: 'reflect'` tier; the `loop_split` model-facing tool; the built-in implementations of the `rubric` and `contract` tiers. + +**Phase 3**: agent fleet (N parallel loops for the same goal, best result wins); integration with `dsh-schedule`; two-container evaluator isolation (evaluator definition files entirely inaccessible to the main agent, defending against reward hacking). + +## Alternatives considered + +**Extend `packages/core/agent-loop`**: add an "iterate on end_turn until goal" switch to the inner loop. Rejected—AGENTS.md says "new behavior goes on documented extension seams; changing agent-loop requires updating docs/architecture.md". The harness loop needs state across sessions and across agents; stuffing it into the inner loop tangles session semantics into two mixed layers. + +**Ship a single slash command `/loop` (Claude Code clone)**: minimal implementation. Rejected—the slash-command layer does not resolve the harness/inner boundary; the four design points (queryable session, tiered evaluator, pluggable handoff, pluggable goal reflector) have nowhere to sit at the slash-command layer, and every capability this RFC commits is lost. + +**Fully outsource to `packages/workflow`**: express the loop as a workflow node with a back edge. Rejected—workflow lacks first-class semantics for iteration, StopCondition, and Evaluator; forcing it means the evaluator has to masquerade as a phase, violating the architectural-isolation requirement that the evaluator be independent of the producer; the budget guardrail in workflow is phase-level rather than round-level, and the granularities do not match. + +**Hardcode a binary choice between A (fresh) and B (continue)**: the Ralph school and the LoopTroop school each have strong scenarios. Rejected—Pluggable RoundHandoff proposes a seam plus three built-in backends that cover both schools and allow hybrids. + +**Skip the evaluator seam, ship a few built-ins**: lighter. Rejected—the core value of Pluggable Evaluator and Budget is that team-private evaluators can extend the system. Hardcoding leaves long unattended users no option but to modify the main library. + +**Accept a free function that lacks an `EvaluatorSpec` tier**: allow users to pass any `(result) => boolean`. Rejected—the tier system forces users to declare at start time "which strength of judgment I'm using", the key to preventing quiet regression to a weaker tier. A free function looks flexible but lets evaluator strength quietly regress, and the cost is heavy in long-run scenarios. + +**Introduce an independent memory engine (Beads / dex-style)**: an established approach to external state. Rejected—`packages/session-persistence` + `sqlite-session-query-provider` already provide equivalent capability; the payoff of a new engine is far smaller than the maintenance cost. + +**Fold goal reflection into the Evaluator seam** (have the evaluator return "criteria are impossible"): rejected—it conflates "was the goal achieved" with "is the goal still correct", which are orthogonal concerns. `Evaluator` should stay independent, read-only, and simple. + +**Only add an event for goal-concern, no seam**: lighter. Rejected—the response-strategy family (stop / notify / reflect) is well defined and teams will want to plug in their own, so making it a seam pays off more than it costs. + +**Ship the full Reflector subagent in Phase 1**: more complete. Rejected—`loop_flag_concern` tool plus no-progress heuristic plus the two-policy `onGoalConcern` already covers 80% of scenarios; running an independent subagent every round is expensive, and introducing it on demand in Phase 2 is more sensible. + +**Do not ship `loop_split`; let users split themselves**: Phase 1 already does. Phase 2 adds it because long-run scenarios reveal that agents receiving an oversized goal will run it directly rather than split it, so explicit tool guidance is needed. + +## Acceptance criteria + +- The three packages `packages/loop/{loop,loop-driver,loop-tool}` are built as a capability seam; `dsh-loop` exports only types and registry +- `StopCondition` discrimination covers all branches (unit); `assertNever` closes the switch at compile time +- The four services `Evaluator`, `BudgetPolicy`, `RoundHandoff`, and `GoalReflector` can each be replaced by an external plugin (fixture: inject a mock implementation, driver calls it correctly) +- `EvaluatorSpec`'s four-tier type converges at compile time; the driver refuses to start a loop without a paired evaluator (fixture: `loop({ goal, evaluator: undefined })` returns a configuration error immediately) +- Default-FAIL fixture: when the evaluator report returns `{criterion, pass: true, evidence: []}`, the driver refuses that criterion flip and records an `evaluator/invalid-report` session event +- Each of the three built-in handoff backends has unit tests plus one e2e: `fresh-with-summary` (runs to pass), `continue-with-compaction` (runs past the token threshold to trigger compaction), `continue-raw` (runs 3 rounds) +- `dsh loop` CLI e2e: given a goal plus a 3-round cap plus one shell evaluator, both the pass and exhaustion paths return a structured stop cause with a semantic exit code +- Evaluator isolation fixture: the main agent has fs.write, the evaluator subagent's tool set does not; attempting to call fs.write is rejected by the registry +- protectedPaths fixture: with `EvaluatorSpec.protectedPaths: ["tests/**"]` declared, a main-agent attempt to write `tests/foo.py` is rejected by the `packages/fs` policy gate and recorded as a `loop/hack-attempt` session event, while the evaluator's read of that path succeeds +- Preflight guardrail fixture: inject a mock pricing table to construct a scenario over `perRoundUsd`; the driver refuses to start that round and emits a `budget-cap` StopCondition +- Goal concern fixture: `loop_flag_concern` is callable from the main agent and yields a `loop/goal-concern` session event; under `onGoalConcern: 'stop'` an `approval-required` StopCondition is emitted; under `'notify-continue'` the loop continues and the event carries an ACP high-priority marker; the no-progress heuristic fires once when budget exceeds 50% with zero passes (with rate-limit dedup) +- The default system prompt hard constraints (no TODO/FAKE/PLACEHOLDER, no empty catch) are distributed with the built-in `loop` tool, and a snapshot covers the prompt content +- Each round's prompt, inner-loop result, evaluator report, and stop decision appear as session events; when Phase 2 adds the query surface, they are indexable by `loopId` +- The "Related" sections in `packages/loop/README.md` and `packages/workflow/README.md` cross-link and describe the "when to use workflow vs. when to use loop" boundary clearly +- Unit 100% / snapshot / e2e / doc-sync / verify-module-graph / build / hygiene all green; the ACP rendering intent (`generic`) of the new tool has a snapshot + +## Risks + +**Dependency on [sqlite-session-query-provider](2026-07-10-sqlite-session-query-provider.md) landing**. The user-visible value of Loop as an independent session (arbitrary-round resume plus meta-loop learning) requires it. The mitigation is in that section's limitation paragraph; Phase 1 does not hard-bind, and the query surface ships in Phase 2. + +**The boundary between `packages/workflow` and loop is a recurring FAQ**. "Is multi-round a loop or a workflow?"—both READMEs must state clearly: workflow is "steps known, agent to run undecided, parallel or serial orchestration"; loop is "agent decided, round count undecided, evaluator decides when to stop". Unclear docs cause users to pick the wrong one. + +**Evaluator reverse-optimization (reward hacking)**. In a sufficiently long loop, the agent can identify the evaluator's pattern and optimize against it—for example, discovering that "as long as `assert True` appears in a test file, it PASSes" and bypassing real completion that way. **Phase 1 blocks most cases via `protectedPaths`**: evaluator input files (tests, evaluator config) are declared write-forbidden for the main agent via the `packages/fs` policy gate, sealing off the "modify the tests to make the evaluator pass" path directly. It still cannot prevent the agent from learning the evaluator's pattern and evading it in substance (for example, writing code that satisfies the surface pattern but is semantically wrong). Users needing high adversarial strength need Phase 3's two-container approach: the entire evaluator runtime (binary, rubric, dependency libraries) sits in a container that the main agent cannot access, matching what Anthropic patch.py does. + +**Placeholder faking and over-defensive code**. Agents sometimes write `# TODO: implement` to sneak through a test, or write large amounts of `try/except: pass` to make the evaluator superficially PASS. These do not belong to the evaluator layer; they are prompt and training issues at the agent-generation stage. Mitigation goes through the two default system-prompt hard constraints in User surface; users who add "static-check-forbid TODO and empty catch" rules to a custom evaluator are safer. This class of problem cannot be cured at the seam layer. + +**Budget estimation drift**. The pricing table is a constant; the estimate drifts once the model provider changes prices. A conservative approximation is not a bug in itself, but the README notes "actual billing is per usage events; preflight only defends against a single round exploding". + +**Long-run loop log growth**. A 100-round loop reaches MB scale for one session. `logDetail: 'summary'` is a safety net but Phase 1 defaults to `full`; Phase 2 adds summary semantics. + +**Pre-release allows direct evolution**. `SESSION_FORMAT_VERSION=0`; the `LoopRoundEvent` schema can change at any time. Backends reject old formats rather than maintain compatibility, matching the pre-release stance at the top of AGENTS.md. diff --git a/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.zh.md b/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.zh.md new file mode 100644 index 0000000000..4e1b677259 --- /dev/null +++ b/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.zh.md @@ -0,0 +1,321 @@ +# RFC: harness 层 goal-based loop + +Status: proposed + +[English](2026-07-16-harness-level-loop.md) | 中文 + +## 问题 + +`packages/core/agent-loop` 只跑 inner loop:一次 turn 内推理加工具循环,模型返回 `end_turn` 就结束。其 README 明确写「No built-in turn budget」——预算是它自己承认的 gap。跨轮次调度落在 harness 层:跑到测试全绿、按 rubric 反复改稿、把 PRD 拆成 bead 逐个推进、无人值守跑一整晚。这几类任务今天都没有一等公民的实现。 + +现有代码里有三种「能凑合跑」的替代,都不够用: + +| 替代 | 问题 | +|---|---| +| `packages/workflow` 脚本表达 `while (!done)` | README 明写「No token-budget vocabulary」和「No journaling or resume」;父 turn 阻塞到脚本 settle。能跑几分钟的编排,跑不了几小时的长期任务 | +| 外部 shell `while :; do dsh …; done` | Ralph 风格的调度今天就能这么写。缺共享的 stop condition、budget、evaluator 词汇,每个使用者各自重发明;循环本身没有持久化对象可供事后诊断或恢复 | +| `packages/subagent` seam 的 `sendMessage`/`resume` | README 明写「Runtime steering and continuation are seam-only capabilities」。没有 model-facing consumer,模型只能起 fresh 子会话 | + +典型使用场景有三类。**自动化修复**:面前一个失败的测试套件,希望一个进程持续修改代码、跑测试、根据失败信息再修改,直到全绿或触达预算上限。**按 rubric 迭代改稿**:一份文档、代码或翻译需要满足打分标准,循环反复调整、独立评估者打分、直到达标或耗尽轮数。**无人值守长跑**:例如通宵把一个仓库从一种技术栈移植到另一种,下班前启动第二天回来看结果,全程只有预算兜底。三类共同的形态:几分钟到几小时、evaluator 决定成败、预算是硬约束、跑完还需要能回看和恢复。 + +## 提案 + +**Loop 有四种触发形态**,按谁在什么时候启动一轮划分: + +| 形态 | 谁触发 | 何时触发 | 现有对标 | 本 RFC | +|---|---|---|---|---| +| **turn-based** | 用户在会话里发一条消息 | 每一轮用户回复 | `packages/core/agent-loop` 现有一次 turn 内的推理与工具循环 | 不覆盖,已有实现 | +| **goal-based** | 用户或 agent 明确指定「跑到某条件为止」 | 一次启动,evaluator 判停 | Claude Code 的 `/goal`、Codex 的 `/goal`、Ralph 家族 | **本 RFC 覆盖** | +| **time-based** | scheduler | 按 cron 或时间间隔 | Claude Code 的 `/loop`(周期性)、`/schedule` | 延后到 `dsh-schedule` RFC | +| **proactive** | agent 自己 | agent 在推理中意识到需要开一个 loop 时 | Anthropic ClaudeDevs 4 类分类里的 proactive 档 | **本 RFC 自然包含**(agent 调 `loop` tool 就是 proactive) | + +本 RFC 只**新增 capability seam `packages/loop/`** 处理 goal-based 一种。proactive 复用同一 `loop` tool,agent 主动调用即触发,无需额外机制。time-based 需要独立的 scheduler package,属于另一份 RFC 的事情;本 RFC 只在 cordis leaf 触发面预留跟未来 `dsh-schedule` 联动的钩子。 + +三个包: + +- `@deepseek-ai/dsh-loop`:类型、`LoopDriver` service、`StopCondition` 判别联合、四个内置 service 定义(`Evaluator` / `BudgetPolicy` / `RoundHandoff` / `GoalReflector`)、事件 schema +- `@deepseek-ai/dsh-loop-driver`:默认 driver 实现 +- `@deepseek-ai/dsh-loop-tool`:model-facing `loop` tool + CLI `dsh loop` + +设计围绕四个具体问题展开,每个问题对应一条独立的 cordis service seam: + +1. 长跑 loop 出问题后缺诊断和恢复手段。**loop 作为独立 session** 解决。 +2. loop 结束时的 PASS 是否可信决定几小时工作是否作废。同一个 LLM 既生成又自评的架构本身就不可信。**Evaluator 与 Budget 做成 service seam** 解决。 +3. 短任务和长任务需要的记忆策略相反,硬编一种模式会让另一类场景不可用。**RoundHandoff 做成 service seam** 解决。 +4. 用户初始给的 goal 未必始终正确。agent 沿着错的目标蛮干会耗尽预算做错事。**GoalReflector 做成 service seam** 解决。 + +四条 seam 之外还有一条贯穿全文的原则:**一个 loop 只处理一个原子目标**。大目标拆成若干小 loop 串联,不塞进一个 loop 让 evaluator 判定多件事。判定 granularity 是否合适的经验规则:如果 loop 跑完说不清它到底做完了什么,granularity 就太大,应当拆。Phase 2 补 `loop_split` model-facing tool 让 agent 收到过大 goal 时能自己拆。 + +术语约定:**inner loop** 指 `packages/core/agent-loop` 一次 turn 的推理与工具循环;**harness loop** 指本 RFC 引入的外层调度器,围绕 inner loop 反复迭代。本 RFC 不改 `agent-loop`,符合 AGENTS.md「Plugins, not loop changes」。 + +`StopCondition` 是 discriminated union,`assertNever` 收口: + +```ts +interface EvaluatorReport { criteria: readonly { name: string; pass: boolean; evidence: readonly string[] }[] } + +type StopCondition = + | { kind: 'goal-met'; evidence: EvaluatorReport } + | { kind: 'budget-cap'; scope: 'usd' | 'tokens' | 'rounds' } + | { kind: 'stuck'; pattern: 'repeat-action' | 'no-progress' | 'error-loop' } + | { kind: 'approval-required'; reason: string } + | { kind: 'user-cancel' } + +export {} +``` + +### Loop 作为独立 session + +长跑 loop 一旦出错,用户没有系统的诊断手段。跑几小时后失败,只能翻散落的日志文件。发现中间某一轮走偏想倒回去重跑,只能从头开始。agent 想参考自己过去 loop 的经验也没有可用的 API。 + +Driver 为每个 loop 开一个独立的 loop-session(新的 session id)。每轮的输入、inner-loop 结果、evaluator 报告、stop 决策都作为 session event 落盘,复用 `packages/session-persistence` 的 SQLite backend。得到三种能力。 + +- **从任意轮恢复**:发现第 78 轮偏航,从第 77 轮拉起,换 prompt 或换 evaluator 重跑,不必从头 +- **事后诊断**:通过 [sqlite-session-query-provider](2026-07-10-sqlite-session-query-provider.md) 查「哪一轮 evaluator 开始一直挂在同条 criterion 上」定位卡点 +- **元循环学习**:agent 开新 loop 前查自己过往同类 loop 的经验——「我以前 fix 过类似的 bug 吗?失败在哪一轮?」 + +Claude Code、Codex 的 `/goal` 是一次性对象:跑完就丢,agent 下次遇到同类问题从零开始。 + +**存储与依赖**。每轮几 KB events,100 轮 loop 约 100–500 KB;跑几千个 loop 会到 GB 级。`logDetail: 'summary' | 'full'` 配置缓解,默认 `full`,长跑用户可切 `summary`。中间态全持久化会把生成过的 key、密码一并落盘,跟普通 session 是同一类风险但量放大 10–100 倍,README 明确提示。**最关键的一条**:本节能力硬依赖尚未落地的 [sqlite-session-query-provider RFC](2026-07-10-sqlite-session-query-provider.md)。若该 RFC 未落地,任意轮 resume 与查询能力会降级为「只能翻 JSONL 文件」。若 Phase 1 交付时该 RFC 还未 merge,本 Phase 只保证 event 结构正确,query 面延后到 Phase 2。 + +### 可插拔的 Evaluator 与 Budget + +loop 的价值最终取决于结束时的 PASS 是否可信。如果 evaluator 会被 hack 或幻觉 PASS,前面几小时的工作全部作废。同一个 LLM 既生成又自评的架构本身就不可信:模型有条件说服自己 PASS。即便让独立 subagent 做 evaluator,只要 evaluator 还是 LLM,就仍然对同类内容有系统性偏好——独立 subagent 只是缓解不是根治。 + +真正可信的评估必须是完全非 LLM 的硬检查:shell exit code、静态分析、外部服务。LLM 物理上碰不到评估过程。但硬检查只有用户自己知道该跑什么:不同项目 `pytest` 命令不同、公司有私有合规检查器、有些团队还要跑内部 lint。主库无论内置几种都覆盖不全。所以 evaluator 必须做成用户可以自己接入的 seam。 + +预算方面同理:产品级的花费护栏是黑盒,无法按团队策略调整(个人卡、团队分摊、按 PR 结算)。 + +`Evaluator` 和 `BudgetPolicy` 都作为 cordis service seam 暴露。`Goal` 必须携带一个明确档位的 `EvaluatorSpec`,driver 拒绝启动没有 evaluator 配对的 loop——含糊的目标("把代码写好")不能进入 loop 系统: + +```ts +interface RubricItem { name: string; description: string } +interface EvaluatorContract { readonly name: string } + +type EvaluatorSpec = { + tier: + | { kind: 'single-metric'; check: string } // "pytest -q && ruff check"、"exit code == 0" + | { kind: 'rubric'; criteria: RubricItem[] } // 若干独立 criterion,各自 pass/fail + evidence + | { kind: 'contract'; interface: EvaluatorContract } // 结构化合约(如 API sig 校验) + | { kind: 'llm-judge'; rubric: string; model: string } // 兜底档,仅软目标 + /** + * 主 agent 不可写的路径(通常是 evaluator 会读的测试文件、评估配置)。 + * 违规写会被 packages/fs policy gate 拒绝,记 loop/hack-attempt session event。 + * 这是防 reward hacking 的核心机制——把「改测试让 evaluator 通过」这条路封死。 + */ + protectedPaths?: readonly string[] +} + +export {} +``` + +**为什么分档,而不是让用户传自由函数?** 档位强制用户在启动时明确「用哪一档强度判成败」。自由函数看起来灵活,实际让 evaluator 强度隐性下沉——用户以为在做严格判定,实际写的是 LLM-judge 那种模糊的语义匹配。长跑场景下代价是几小时白跑。 + +四档从上到下可信度依次降低。前三档都是完全非 LLM 的硬检查。`llm-judge` 是最弱一档,仅用于确实无硬信号的软目标(改稿、翻译质量)。文档明确标注「此档不能挡定向对抗,长跑无人值守场景需至少一档硬检查配合」。 + +Driver 强制五条硬约束,不下放给 Evaluator 实现。它们分别对付三类不同的攻击面: + +**防「同一个 agent 既生成又自评」**: + +1. **fresh subagent**:evaluator 每轮开 fresh subagent(用 `dsh-subagent` 的 `spawn`),不继承主循环 context + +**防主 agent 通过修改 evaluator 输入来 reward hack**: + +2. **`protectedPaths` 硬隔离**:`EvaluatorSpec` 声明的路径(通常是测试文件、评估配置)由 `packages/fs` 已有的 policy gate 拒绝主 agent 的写请求,记 `loop/hack-attempt` session event。这是 Phase 1 真正挡 reward hacking 的一层——直接封死「改测试让 evaluator 通过」这条路 + +**防 evaluator subagent 自身被 subverted**: + +3. **只读工具集**:evaluator 的 tool set 被 driver 剥离到只保留读类工具,写类工具禁用(复用 `SubagentProvider` 的 `toolFilter`)。它防的不是主 agent 的 reward hacking,而是 evaluator 读到被 evaluate 的代码里 embed 的 prompt injection 时不会被诱导去改状态 + +**防 evaluator 报告本身欺骗 driver**: + +4. **PASS 只能由 evaluator 报告翻转**:`goal-met` StopCondition 只能来自 evaluator,driver 或主 agent 都不能直接构造 +5. **Default-FAIL**:driver 内部维护每个 criterion 的 pass 状态默认 `false`,只有 evaluator 报告里带非空 evidence 才允许翻 `true`;evaluator 无法通过返回 `{pass: true}` 而不给 evidence 让 driver 接受 + +五条一起决定 evaluator 结论只能靠证据推动,无法靠自信推动,也无法靠主 agent 悄悄改测试推动。 + +**Phase 1 内置三个 backend**: + +- `loop-evaluator-shell` 实现 `single-metric`:跑 shell 命令,`exit 0` = pass +- `loop-evaluator-rubric-judge` 实现 `llm-judge`:预写 rubric + LLM 打分,仅软目标 +- `loop-budget-preflight`:每轮启动前估 `(promptTokens + overhead + estOutputTokens) / 1M × pricePerMTok`,超 `perRoundUsd` 拒绝启动。估算模型来自 MartinLoop `policy.ts:551-596` + +`PricingProvider` 服务注入 pricing 表,test seam 可覆盖,不硬编到 driver 里(AGENTS.md「No hardcoded tunables in plugins」)。`rubric` 与 `contract` 档 Phase 2 补内置实现,Phase 1 只暴露类型让第三方插件先接。 + +**局限**:evaluator subagent 拿到的"只读工具"仍是同一进程的 shell 与 fs 读,理论上仍可能被 prompt injection 绕过。挡定向对抗需要两容器方案(evaluator 定义文件对主 agent 完全不可访问,Anthropic patch.py 走的就是这条路),本 RFC Phase 3 才做。见 风险。 + +### 可插拔的 RoundHandoff + +每轮之间如何传递 context 是一个两难。完整保留之前对话(continue)连续性好,但对话会持续增长最终撞上 context 上限,且上一轮的错误信息会污染后续每一轮。每轮从零开始(fresh)避免污染,但每次需要重新理解上下文。跑 3 轮改稿与跑 80 轮 overnight 修 bug 需要的策略是相反的。Claude Code、Codex 都硬编一种模式,用户没法按任务类型切换。 + +做成 service seam: + +```ts +interface RoundContext { loopId: string; round: number } +interface NextRoundSpec { mode: 'fresh' | 'continue' } + +interface RoundHandoff { + buildNextRound(prev: RoundContext): NextRoundSpec +} + +export {} +``` + +Phase 1 内置三个 backend: + +| Backend | 场景 | 机制 | +|---|---|---| +| `handoff-fresh-with-summary`(默认) | 长跑、无人值守 | 每轮开 fresh subagent,只注入一段 progress 摘要作 system prompt 附加段 | +| `handoff-continue-with-compaction`(推荐中间档) | 5–20 轮的中等长度 | 整段对话保留到 token 阈值,超了复用 [`packages/compact`](../../../../packages/compact/README.md) 压缩,摘要 + 最近 K 轮作起点 | +| `handoff-continue-raw`(专业档) | ≤5 轮短任务、测试 | 纯连续对话不裁剪 | + +**为什么默认 fresh?** 所有实际跑成的长跑 loop(repomirror、Kimi ralph-loop、autoresearch)用的都是 fresh。把重要 loop 状态放在 context window 外由 driver 管理是长跑的正确姿势。`handoff-continue-raw` 违反这条经验,README 明写长跑不适用。 + +**为什么中间档只有我们能做?** `handoff-continue-with-compaction` 依赖 compaction seam——竞品都没有,只有本仓库 `packages/compact` 提供了这个基础设施。 + +**为什么做成 seam 而不是三选一 flag?** 用户可以写 20 行插件表达「前 5 轮 continue、之后 fresh」这类混合策略,或表达「context 到 50% 自动 compact 一次」,不用等主库支持。 + +**局限**:`continue-with-compaction` 依赖 `packages/compact` 的压缩质量,压缩本身可能把幻觉信息写进摘要传下去;README 建议长跑首选 fresh。三个 backend 的边界会让新用户不知道选哪个;`dsh loop` CLI 默认用 fresh,用户在遇到具体问题前不需要理解这些差别。 + +### 可插拔的 GoalReflector + +用户在启动 loop 时给的目标不一定准确。可能基于错误假设(让 agent 用某个已经废弃的 API 实现功能),可能不够清晰(agent 在做的过程中才发现需要澄清),也可能被后来的信息证伪。现在的循环执行框架把 goal 当作启动时冻结的合约,agent 只能沿着原路蛮干,结果是在错的方向上耗尽预算。 + +做成 service seam,与 `Evaluator` 职责分离:evaluator 问「是否达成目标」,reflector 问「目标是否还是那个目标」。 + +```ts +interface RoundContext { loopId: string; round: number } +interface GoalConcern { concern: string; severity: 'low' | 'medium' | 'high' } + +interface GoalReflector { + reflect(ctx: RoundContext, concerns: GoalConcern[]): Promise +} + +type GoalReflection = + | { kind: 'continue' } // goal 仍有效 + | { kind: 'revise'; newGoal: string; why: string } // 建议修正 goal + | { kind: 'stop-for-human'; reason: string } // 需要人拍板 + +export {} +``` + +**concern 有三种触发来源**,Phase 1 实现前两种: + +- **agent 主动**:通过 model-facing tool `loop_flag_concern({ concern, severity })`。agent 在调研中意识到「用户假设的那个库已经废弃」时可以直接 raise +- **driver 启发式**:预算过 50% 且零 criterion pass 时,driver 自动 raise `no-progress-toward-goal` concern +- **周期性 reflector subagent**(Phase 2):每 N 轮独立跑一个只读 subagent 复审 goal 有效性,与 evaluator 独立性遵循同一思路 + +**响应策略通过 `onGoalConcern` 配置项**。这四种配置对应不同的 loop 使用哲学,用户按团队协作方式选,driver 不预设立场: + +- `'stop'`(Phase 1 默认):任何 concern 都触发 `StopCondition: approval-required`,人拍板。loop 在遇到任何不确定性时都不应自己往下走,适合谨慎风格团队与影响面较大的 loop 场景 +- `'notify-continue'`(Phase 1):记 `loop/goal-concern` session event(高优先级)加 ACP 显式提示,继续跑,人在结束时集中审阅。loop 内部不打扰,适合无人值守长跑 +- `'reflect'`(Phase 2):调 `GoalReflector` 决定 continue、revise 还是 stop。委派一个独立 agent 代替人做初步判断,适合中等自主度的团队 +- 不注册 `GoalReflector` 且 `onGoalConcern` 未设 = 最放手档,loop 只在传统 stop condition 触发时停 + +**为什么默认选 `stop`?** 无人值守场景下宁可多停一次也不要在错方向上跑几小时。用户明确要无人值守可切 `notify-continue`。 + +concern 本身就是普通 session event,跟前文的持久化 session 能力天然协同:resume 时可以从 concern 出现的那一轮拉起,换 goal 重跑,前 N 轮的工作不丢。 + +**滥用与丢失防护**。agent 可能每轮都 raise concern;缓解是 `severity` 字段和 driver 侧的最小 rate limit(同一 concern 30 秒内去重)。这种滥用的代价是 agent 卡住自己无法推进,动机不强。goal 被 revise 后原始 goal 会丢失;每次 revise 落 `loop/goal-revised` session event 带 rationale,resume 时可选任意历史 goal 版本。 + +### 用户面 + +四个触发面共享同一个 driver: + +- **agent 侧 tool**:`loop({ goal, evaluator, maxRounds, maxUsd, onGoalConcern })` 启动嵌套 harness loop。正在跑的 loop 内部 agent 可用 `loop_flag_concern({ concern, severity })` 主动发起 concern。ACP 渲染意图为 `generic`。agent 自主发起就是 proactive 触发,无需额外机制 +- **CLI**:`dsh loop --stop --max-rounds N --max-usd X --handoff fresh`。人类主导启动,最典型的 Ralph 风格用法 +- **cordis leaf**:`cordis.yml` 里以 leaf 形式声明常驻循环,配合未来的 `dsh-schedule` RFC 可做周期性触发 +- **ACP slash command**:`/loop `(还有 `/loop-flag-concern`)在编辑器/客户端的当前会话里直接启动。语义等价于人类在 CLI 里敲 `dsh loop`,但发生在正在进行的 ACP session 上下文中,允许 loop 结果直接注入会话 + +ACP slash command 的依赖:`packages/ui/acp` 的 `available_commands_update` 面目前是 unbuilt 状态([acp-feature-support.md](../../../../packages/ui/acp/acp-feature-support.md))。等 harness 的 slash command 基础设施落地,`/loop` 与 `/loop-flag-concern` 只需在该基础设施里注册;driver 与 tool 接口不变。本 RFC 保留名字并给出参数 shape,但不承诺基础设施本身——那属于独立的 ACP 补齐 RFC。 + +默认 system prompt 里有两条硬约束,随所有内置 `loop` tool 一起分发: + +1. 不允许写 `TODO`、`FAKE`、`PLACEHOLDER` 占位符让 evaluator 表面通过 +2. 不允许写空的 `try/except` 或 `catch(_)` 让 evaluator 忽略错误 + +这两条不是 seam 层能拦的,是 prompt 层的约定。用户可以自定义 system prompt 但内置约束保留。 + +### 与仓库现有代码的关系 + +直接复用无需修改: + +- `packages/subagent` 的 `spawn` provider、`toolFilter`、`persona`——loop 每轮起 subagent、evaluator 只读工具集 +- `packages/session-persistence` 的 SQLite backend——loop-session 落盘 +- `packages/compact`——`handoff-continue-with-compaction` 的实现基础 +- `packages/todo`——单会话 continue 模式下作为可选 progress 表达 +- 若 [ToolExecution.reportProgress](2026-07-13-stream-workflow-progress-through-tool-calls.md) 先落地,loop tool 可用它逐轮 UI 更新 + +不动:`packages/core/agent-loop`(inner loop 语义保持);`packages/workflow`(DAG 编排 vs. 迭代同 goal 是 orthogonal 关系,两个 README 在「Related」段互链说明边界)。 + +依赖尚未落地的两处: + +- [sqlite-session-query-provider](2026-07-10-sqlite-session-query-provider.md)——见 Loop 作为独立 session 局限段的缓解方案 +- ACP slash command 基础设施(`available_commands_update` 面)——见 用户面。基础设施落地前,slash command 触发面缺席,其它三个触发面照常工作 + +唯一涉及现有代码的改动可延后到 Phase 2:给 `packages/subagent-tool` 增加「续跑已有 subagent」的参数暴露,用于 `handoff-continue-*` 两个 backend。底层 `SubagentRun.sendMessage` 与 `resume` 已作为 seam 能力存在,缺的只是 tool 层的参数入口。若 Phase 1 只上 `handoff-fresh-with-summary`,完全不动 subagent-tool;Phase 2 再补。 + +### 分阶段 + +**Phase 1**(本 RFC 承诺范围):三包 seam;`StopCondition`;`EvaluatorSpec` 四档类型 + `protectedPaths` 硬隔离(复用 `packages/fs` policy gate),其中 `single-metric` 与 `llm-judge` 有内置实现,`rubric` 与 `contract` 类型开放待接;Default-FAIL 强制;3 个内置 evaluator/budget/handoff backend;`loop_flag_concern` tool;no-progress 启发式;`onGoalConcern: 'stop' | 'notify-continue'` 二档;CLI;tool;默认 system prompt 硬约束。**不含**:session-query 面、ACP slash command 触发面(依赖 `available_commands_update` 基础设施)、subagent-tool 续跑改动、stuck 检测器、Reflector subagent、`loop_split` tool、`rubric` 与 `contract` 档的内置实现。 + +**Phase 2**:query 面;stuck 检测器(复现 OpenHands 5 种模式);subagent-tool 续跑改动(解锁 continue 两档 handoff);Reflector subagent;`onGoalConcern: 'reflect'` 档;`loop_split` model-facing tool;`rubric` 与 `contract` 档的内置实现。 + +**Phase 3**:agent fleet(同 goal 派 N 个并行 loop 取最优);与 `dsh-schedule` 集成;两容器 evaluator 隔离(evaluator 定义文件对主 agent 完全不可访问,防 reward 反向优化)。 + +## 备选方案 + +**扩 `packages/core/agent-loop`**:给 inner loop 加「iterate on end_turn until goal」开关。拒绝——AGENTS.md「新行为走文档化扩展 seam;改 agent-loop 需要更新 docs/architecture.md」。harness loop 需要跨 session、跨 agent 的状态,塞进 inner loop 会把 session 语义拧成两层混合。 + +**只做一个 slash command `/loop`(Claude Code 复刻)**:实现最简。拒绝——slash-command 层不解决 harness/inner 边界;四条设计要点(可查询 session、分档 evaluator、可插拔 handoff、可插拔 goal reflector)在 slash-command 层没有承载点,本 RFC 承诺的能力全部丢失。 + +**全权外包给 `packages/workflow`**:把 loop 表达成带回边的 workflow 节点。拒绝——workflow 缺 iteration、StopCondition、Evaluator 的一等公民语义。硬用会把 evaluator 冒充成一个 phase,违反 evaluator 独立于 producer 的架构隔离要求;预算护栏在 workflow 是 phase-level 而非 round-level,粒度对不上。 + +**A(fresh)vs. B(continue)硬编二选一**:Ralph 派和 LoopTroop 派各自都有强场景。拒绝——可插拔的 RoundHandoff 提出 seam + 三档内置 backend 涵盖两派并允许 hybrid。 + +**不做 evaluator seam,内置几种够用**:更轻。拒绝——可插拔的 Evaluator 与 Budget 的核心价值是团队或私有 evaluator 可扩展。写死后长跑无人值守场景的用户只能改主库。 + +**接受不带 `EvaluatorSpec` 档位的自由函数**:允许用户传任意 `(result) => boolean`。拒绝——档位强制用户在启动时明确「用哪一档强度判成败」,是防止不知不觉滑到弱档的关键。自由函数看起来灵活,实际让 evaluator 强度隐性下沉,长跑场景代价大。 + +**引入独立记忆引擎(Beads / dex-style)**:外部化状态的成熟做法。拒绝——`packages/session-persistence` + `sqlite-session-query-provider` 已能提供等效能力;新引擎收益远小于维护成本。 + +**goal reflection 塞进 Evaluator seam**(让 evaluator 返回「criteria 不可能满足」):拒绝——混淆「是否成功」和「目标是否正确」两个正交问题。`Evaluator` 应保持独立、只读、简单。 + +**goal-concern 只做 event 不做 seam**:更轻。拒绝——响应策略族(stop / notify / reflect)明确,各团队会想插自己的,seam 化投资小于收益。 + +**Phase 1 就上完整 Reflector subagent**:更全。拒绝——`loop_flag_concern` tool + no-progress 启发式 + 二档 policy 覆盖 80% 场景;每轮跑独立 subagent 成本高,Phase 2 按需引入更合理。 + +**不做 `loop_split`,用户自己拆**:Phase 1 已经如此。Phase 2 加是因为长跑场景发现 agent 收到过大 goal 会直接跑而不是自己拆,需要显式工具引导。 + +## 验收标准 + +- `packages/loop/{loop,loop-driver,loop-tool}` 三包按 capability seam 建成;`dsh-loop` 只导 types 与 registry +- `StopCondition` 判别覆盖所有分支(单元),`assertNever` 编译期收口 +- `Evaluator`、`BudgetPolicy`、`RoundHandoff`、`GoalReflector` 四条 service 都能被外部插件替换(fixture:注入 mock 实现,driver 正确调用) +- `EvaluatorSpec` 四档类型编译期收敛;driver 拒绝启动没有 evaluator 配对的 loop(fixture:`loop({ goal, evaluator: undefined })` 立即返回配置错误) +- Default-FAIL fixture:evaluator 报告返回 `{criterion, pass: true, evidence: []}` 时 driver 拒绝该 criterion 翻转、记 `evaluator/invalid-report` session event +- 三个内置 handoff backend 都有单元 + 一个 e2e:`fresh-with-summary`(跑到 pass)、`continue-with-compaction`(跑超 token 阈值触发 compact)、`continue-raw`(跑 3 轮) +- `dsh loop` CLI e2e:给定 goal + 3 轮上限 + 一个 shell evaluator,通过与耗尽两条路径都返回结构化 stop cause 并 exit code 语义化 +- Evaluator 独立性 fixture:主 agent 有 fs.write,evaluator subagent 的 tool set 里没有;试图调 fs.write 被 registry 拒绝 +- protectedPaths fixture:`EvaluatorSpec.protectedPaths: ["tests/**"]` 声明后,主 agent 尝试写 `tests/foo.py` 被 `packages/fs` policy gate 拒绝并记 `loop/hack-attempt` session event,evaluator 侧读该路径正常 +- Preflight 护栏 fixture:注入 mock pricing 表构造超 `perRoundUsd` 的场景,driver 拒绝启动该轮且 emit `budget-cap` StopCondition +- Goal concern fixture:`loop_flag_concern` 可从主 agent 调用并产出 `loop/goal-concern` session event;`onGoalConcern: 'stop'` 下 emit `approval-required` StopCondition;`'notify-continue'` 下继续跑且事件带 ACP 高优先级标记;no-progress 启发式在预算超 50% 且零 pass 时自动触发一次(rate-limit 去重) +- 默认 system prompt 硬约束(无 TODO/FAKE/PLACEHOLDER、无空 catch)随内置 `loop` tool 一起分发,snapshot 覆盖 prompt 内容 +- 每轮的 prompt、inner-loop 结果、evaluator report、stop 决策都以 session event 出现;Phase 2 补 query 面时可按 `loopId` 检索 +- `packages/loop/README.md` 和 `packages/workflow/README.md` 的「Related」段互链清楚「何时用 workflow、何时用 loop」的边界 +- 单元 100% / snapshot / e2e / doc-sync / verify-module-graph / build / hygiene 全绿;新增 tool 的 ACP 渲染意图(`generic`)有 snapshot + +## 风险 + +**依赖 [sqlite-session-query-provider](2026-07-10-sqlite-session-query-provider.md) 落地**。Loop 作为独立 session 的用户可见价值(任意轮 resume + 元循环学习)需要它。缓解在该节局限段;Phase 1 不硬绑,Phase 2 才交付 query 面。 + +**`packages/workflow` 与 loop 的边界是持续答疑热点**。「多轮是 loop 还是 workflow」两个 README 必须写清楚:workflow 是「步骤已知、agent 未定、并串行编排」;loop 是「agent 已定、轮数未定、evaluator 判停」。文档不清晰会让用户混用错档。 + +**evaluator 反向优化(reward hacking)**。足够长的 loop 里 agent 有条件识别 evaluator 的模式并针对性优化,例如发现「只要测试文件里出现 `assert True` 就 PASS」从而绕过实质完成。**Phase 1 靠 `protectedPaths` 挡多数 case**:evaluator 的输入文件(测试、评估配置)通过 `packages/fs` policy gate 声明为主 agent 不可写,直接从「改测试让 evaluator 通过」这条路上封死。但仍无法阻止 agent 学出 evaluator 的模式做实质规避(比如写符合表面 pattern 但语义错的代码)。对抗强度高的用户需要 Phase 3 的两容器方案:evaluator 的整个运行时(二进制、rubric、依赖库)都在主 agent 完全不可访问的容器里,Anthropic patch.py 走的就是这条路。 + +**占位符伪造与过度防御码**。agent 有时会写 `# TODO: implement` 让测试勉强通过,或写大量 `try/except: pass` 让 evaluator 表面 PASS。这些不属于 evaluator 层的问题,而是 agent 生成阶段的 prompt 与训练问题。缓解走 用户面 段那两条默认 system prompt 硬约束;用户自定义 evaluator 时若加入「静态检查禁止 TODO 与空 catch」这类规则更稳妥。这类问题不是 seam 层能根治的。 + +**预算估算漂移**。pricing 表是常量,模型调价后估算会飘。护栏保守方向的近似不算 bug,但 README 说明「真实计费以 usage 事件为准,preflight 仅保护单轮爆炸」。 + +**长跑 loop 日志膨胀**。跑 100 轮 loop 单 session 上 MB 级。`logDetail: 'summary'` 兜底但 Phase 1 默认 `full`,Phase 2 再补 summary 语义。 + +**pre-release 允许直接演进**。`SESSION_FORMAT_VERSION=0`,`LoopRoundEvent` schema 可随时改;后端拒收旧格式而非兼容,与 AGENTS.md 顶部 pre-release stance 一致。 From a63c55eb0053cadcea8a6987a82d8e367ebda766 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Thu, 16 Jul 2026 17:31:20 +0800 Subject: [PATCH 018/273] refactor(lsp): configure local servers together --- docs/config-catalog.md | 12 +- .../2026-07-15-lsp-capability-seam.i18n.yaml | 4 +- .../2026-07-15-lsp-capability-seam.md | 4 +- .../2026-07-15-lsp-capability-seam.zh.md | 4 +- packages/lsp/README.md | 2 +- packages/lsp/lsp-local/README.md | 14 ++- packages/lsp/lsp-local/src/index.ts | 105 +++++++++++------- packages/lsp/lsp-local/tests/built-lib.e2e.ts | 13 ++- .../lsp/lsp-local/tests/lifecycle.spec.ts | 49 ++++++-- packages/lsp/lsp-local/tests/provider.spec.ts | 79 ++++++++++--- .../lsp-local/tests/typescript-server.e2e.ts | 11 +- packages/lsp/lsp/README.md | 2 +- .../lsp/tool-lsp/tests/integration.spec.ts | 15 ++- 13 files changed, 213 insertions(+), 101 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index b6b798b124..636713146c 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -424,10 +424,14 @@ Source: [`packages/support/llm-replay/src/index.ts:306`](../packages/support/llm Requires: `lsp` ```ts config-catalog -/** Plugin configuration: one server command plus its extension mapping and host bounds. */ +/** Plugin configuration: provider id → local language-server configuration. */ export interface Config { - /** Stable provider id, reserved on `ctx.lsp` with the extensions. */ - providerId: string + /** Non-empty table of stable provider ids to independent local server configurations. */ + servers: Record +} + +/** One configured local language server and its host bounds. */ +export interface LspLocalServerConfig { /** Executable to spawn (absolute, or resolved on PATH at load). */ command: string /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */ @@ -453,7 +457,7 @@ export interface Config { } ``` -Source: [`packages/lsp/lsp-local/src/index.ts:59`](../packages/lsp/lsp-local/src/index.ts) +Source: [`packages/lsp/lsp-local/src/index.ts:85`](../packages/lsp/lsp-local/src/index.ts) ## `@deepseek-ai/dsh-mcp-client` diff --git a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml index 69c509bae6..f063dae8cf 100644 --- a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.i18n.yaml +++ b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.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 -2026-07-15-lsp-capability-seam.md: c21d2f3926b5b465f4ccf48f1bf954c2ae604e12 -2026-07-15-lsp-capability-seam.zh.md: 9556ead6c2e0d6d49fffe54928d53f9418cf10b7 +2026-07-15-lsp-capability-seam.md: 500d861f60bcd238d31defaa90a3e2495a05e767 +2026-07-15-lsp-capability-seam.zh.md: b181987f707563e3115e64313250859a4238c4ee diff --git a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md index c21d2f3926..500d861f60 100644 --- a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md +++ b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md @@ -17,7 +17,7 @@ Many language servers behave best when the queried document is opened with curre Add LSP as a three-package capability seam with one read-only model tool and one generic local provider implementation: 1. `@deepseek-ai/dsh-lsp` at `packages/lsp/lsp` owns `ctx.lsp`, provider registration and selection, normalized requests/results, execution control, and structured LSP errors. -2. `@deepseek-ai/dsh-lsp-local` at `packages/lsp/lsp-local` adapts configured stdio language servers to the seam. Multiple plugin instances may register different server commands and extension-to-language-id mappings. +2. `@deepseek-ai/dsh-lsp-local` at `packages/lsp/lsp-local` adapts configured stdio language servers to the seam. One plugin instance accepts a named server table and registers one isolated provider for each command and extension-to-language-id mapping. 3. `@deepseek-ai/dsh-tool-lsp` at `packages/lsp/tool-lsp` owns the model-facing `lsp` schema, prompt guidance, argument validation, result limits and formatting, and ACP presentation. `dsh-lsp-local` is a generic host, not a language-server catalog or installer. Deployments explicitly configure commands and mappings; future presets belong in composition plugins or `cordis.yml` overlays. @@ -79,7 +79,7 @@ interface LspService { Mapping keys normalize to lowercase, leading-dot extensions selected from `filePath`'s final extension; language ids only synchronize documents. Seam positions and ranges are zero-based UTF-16. `references` always includes declarations: providers enforce this internally, the local mapping sets `context.includeDeclaration: true`, and callers get no flag. Closed result unions normalize navigation to locations and hover to content or `null`; navigation results carry the provider's resolved workspace root so consumers relativize file URIs in the same canonical namespace. The seam exposes no protocol types, process or document controls, or generic request escape hatch. -`dsh-lsp-local` owns host files, server configuration, JSON-RPC, process and transient-document state, and protocol translation; it depends on `dsh-lsp` and Node APIs, not `dsh-fs`. `dsh-tool-lsp` runtime-injects only `tools`, `lsp`, and `systemPrompt`, obtains the workspace from `exec.agent?.session.header.cwd` through a package-local `sessionCwd(exec)` helper matching the filesystem tools' lookup, and imports no provider. +`dsh-lsp-local` owns host files, server configuration, JSON-RPC, process and transient-document state, and protocol translation; it depends on `dsh-lsp` and Node APIs, not `dsh-fs`. The server-table key is its provider id. The plugin resolves every server-local setting before registration, rolls back earlier registrations if a later mapping is invalid or conflicts, and retains an independent process pool per provider. `dsh-tool-lsp` runtime-injects only `tools`, `lsp`, and `systemPrompt`, obtains the workspace from `exec.agent?.session.header.cwd` through a package-local `sessionCwd(exec)` helper matching the filesystem tools' lookup, and imports no provider. ## Model-facing contract diff --git a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md index 9556ead6c2..b181987f70 100644 --- a/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md +++ b/docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.zh.md @@ -17,7 +17,7 @@ harness 已具备文本搜索与文件读取能力,但二者都无法识别程 将 LSP 建成由三个包(package)组成的能力服务边界,其中包含一个只读模型工具和一个通用本地提供方实现: 1. `packages/lsp/lsp` 下的 `@deepseek-ai/dsh-lsp` 负责 `ctx.lsp`、提供方注册与选择、标准化请求与结果、执行控制,以及结构化 LSP 错误。 -2. `packages/lsp/lsp-local` 下的 `@deepseek-ai/dsh-lsp-local` 将配置的 stdio 语言服务器适配到该服务边界。多个插件实例可注册不同的服务器命令和扩展名到语言 id 的映射。 +2. `packages/lsp/lsp-local` 下的 `@deepseek-ai/dsh-lsp-local` 将配置的 stdio 语言服务器适配到该服务边界。一个插件实例接收具名服务器表,并为每组命令及扩展名到语言 id 的映射注册一个隔离的提供方。 3. `packages/lsp/tool-lsp` 下的 `@deepseek-ai/dsh-tool-lsp` 负责面向模型的 `lsp` schema、提示词指导、参数校验、结果限制与格式化,以及 ACP(Agent Client Protocol)展示。 `dsh-lsp-local` 是通用 host,不是语言服务器目录或安装器。部署显式配置命令与映射;未来 preset 属于组合插件或 `cordis.yml` overlay。 @@ -79,7 +79,7 @@ interface LspService { 映射键规范化为带前导点的小写扩展名,并按 `filePath` 的最后一个扩展名选择;语言 id 仅用于文档同步。服务边界中的位置和范围从零开始按 UTF-16 计数。`references` 始终包含声明:提供方在内部执行该约束,本地映射设置 `context.includeDeclaration: true`,调用方不能配置。封闭结果联合将导航统一为位置,将 `hover` 统一为内容或 `null`;导航结果携带提供方解析后的工作区根目录,使消费方依据同一规范化根目录相对化文件 URI。服务边界不公开协议类型、进程或文档控制,也不提供通用请求逃生口。 -`dsh-lsp-local` 负责主机文件、服务器配置、JSON-RPC、进程与临时文档状态和协议转换;它依赖 `dsh-lsp` 与 Node API,不依赖 `dsh-fs`。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`,通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区,其取值方式与文件系统工具一致,也不导入提供方。 +`dsh-lsp-local` 负责主机文件、服务器配置、JSON-RPC、进程与临时文档状态和协议转换;它依赖 `dsh-lsp` 与 Node API,不依赖 `dsh-fs`。服务器表的键是提供方 id。插件在注册前解析每个服务器的本地设置;如果后续映射无效或发生冲突,插件会撤销此前的注册,并为每个提供方保留独立进程池。`dsh-tool-lsp` 在运行时只注入 `tools`、`lsp` 和 `systemPrompt`,通过包内的 `sessionCwd(exec)` 辅助函数从 `exec.agent?.session.header.cwd` 取得工作区,其取值方式与文件系统工具一致,也不导入提供方。 ## 面向模型的契约 diff --git a/packages/lsp/README.md b/packages/lsp/README.md index 57a1f6b8d9..f57eed8ae0 100644 --- a/packages/lsp/README.md +++ b/packages/lsp/README.md @@ -5,7 +5,7 @@ The language-server capability seam: an abstract LSP interface, a generic stdio | Package | Role | ctx key | |---|---|---| | `lsp/` | Abstract LSP seam (provider registry by branded id + extension mapping, per-query selection, vocabulary, `LspError`) | `ctx.lsp` | -| `lsp-local/` | Generic stdio language-server provider (spawn, JSON-RPC, transient-open queries) | (registers on `ctx.lsp`) | +| `lsp-local/` | Generic multi-server local backend (spawn, JSON-RPC, transient-open queries) | (registers providers on `ctx.lsp`) | | `tool-lsp/` | Model-facing `lsp` tool (four operations, one-based UTF-16 cursor coordinates) | (registers on `ctx.tools`) | The interface lives at `lsp/lsp/`. The seam exposes exactly four semantic operations — `definition`, `references`, `implementation`, `hover` — and no generic JSON-RPC escape hatch, so a provider swap does not change how the model asks for navigation and no protocol payload or unreviewed mutation reaches the model contract. Providers register **capabilities**, not tools; `tool-lsp` is the only owner of the model-facing name, schema, prompt guidance, and presentation. diff --git a/packages/lsp/lsp-local/README.md b/packages/lsp/lsp-local/README.md index 1424f27835..75b0595626 100644 --- a/packages/lsp/lsp-local/README.md +++ b/packages/lsp/lsp-local/README.md @@ -1,21 +1,23 @@ # @deepseek-ai/dsh-lsp-local -A **generic stdio language-server provider** for `ctx.lsp`. One plugin instance configures one server command and its extension-to-language-id map; load multiple instances for multiple servers. This is a generic host, not a language-server catalog or installer — deployments configure commands and mappings explicitly; presets belong in composition plugins or `cordis.yml` overlays. +A **generic local stdio language-server backend** for `ctx.lsp`. One plugin instance accepts a named server table and registers one isolated provider per entry. This is a generic host, not a language-server catalog or installer — deployments configure commands and mappings explicitly; presets belong in `cordis.yml` overlays. Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export). ## What it does -- Lazily single-flights one server process per `(provider id, canonical workspace realpath)`. A crash fails the active query without replay; a later query may replace the process. +- Resolves every server-local setting before registration; an invalid mapping or registration conflict rolls back earlier entries, so a failed load leaves no provider routes. +- Lazily single-flights one server process per `(server id, canonical workspace realpath)`. A crash fails the active query without replay; a later query may replace the process. - Uses a compatibility-first **transient-open** sequence per query: canonicalize and read the source with Node APIs, `textDocument/didOpen` (version 1, full text), the requested request, then `textDocument/didClose` in `finally`. Documents close after each call, so the first version needs no `didChange`, content cache, or document LRU. - Serializes queries through one abortable per-instance queue so a cancellation that fails to stop the server can terminate it without killing unrelated work; distinct instances run in parallel. - Reads sources through Node filesystem APIs in the subprocess's host namespace — NOT `ctx.fs`, and emits no `fs/observed`: only the LSP result is model-visible, so a query does not satisfy read-before-write policy. ## Configuration -| Key | Default | Meaning | +The `servers` record key is the stable provider id reserved on `ctx.lsp`; each value has this shape: + +| Server key | Default | Meaning | |---|---|---| -| `providerId` | (required) | Stable provider id reserved on `ctx.lsp` with the extensions. | | `command` | (required) | Executable to spawn — absolute, or resolved on the child PATH at load. Launch uses no shell. | | `args` | `[]` | Arguments passed to the executable. | | `env` | `{}` | Extra env merged on top of the credential-scrubbed ambient env (vars matching `KEY`/`SECRET`/`TOKEN` are not forwarded). | @@ -28,7 +30,7 @@ Namespace plugin (`name` / `inject` / `Config` / `apply`, no default export). | `shutdownTimeoutMs` | `5000` | Graceful `shutdown`/`exit` budget before escalation. | | `killGraceMs` | `2000` | SIGTERM→SIGKILL grace after graceful shutdown fails. | -The executable is resolved at load (after credential scrubbing); a missing command fails before registration. The process itself launches lazily on the first matching query. +`servers` must contain at least one entry, and every id must be non-empty. All executables resolve at load after credential scrubbing; a bad later entry prevents every provider from registering. Processes launch lazily on the first matching query. ## Protocol behavior @@ -46,4 +48,4 @@ Indirectly, through `dsh-tool-lsp`, which surfaces this provider's normalized re - **Trusted host-local only** — no sandbox confinement, no private cache/temp write contract; supporting untrusted binaries or restricted/remote/virtual workspaces requires a later process/filesystem contract and a different provider ([seam RFC](../../../docs/rfc/implemented/architecture/2026-07-15-lsp-capability-seam.md)). Containment resolves `realpath`, then opens the source through one handle with `O_NOFOLLOW` (final-component symlink guard) and a bounded read; a concurrent mutator that swaps an *ancestor* directory for a symlink between the resolve and the open is an accepted residual TOCTOU under this trusted-deployment model, not closed with non-portable `openat` segment walks. - **Transient-open compatibility floor** — servers whose synchronization omits open/close (or advertise `None`) are unsupported even if closed-document queries would work; the pinned TypeScript e2e establishes one compatibility floor, not a cross-language claim. -- **Per-instance serialization latency** — parallel agents sharing a workspace queue behind one process; long-lived workspace processes consume memory until disposal. +- **Per-server/workspace serialization latency** — parallel agents sharing one server and workspace queue behind one process; long-lived workspace processes consume memory until disposal. diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts index f1d5408f5c..07e1cbed5a 100644 --- a/packages/lsp/lsp-local/src/index.ts +++ b/packages/lsp/lsp-local/src/index.ts @@ -1,10 +1,10 @@ /** - * Generic stdio language-server provider for `ctx.lsp`. One plugin instance configures one server - * command and its extension→language-id map; load multiple instances for multiple servers. The - * provider lazily single-flights one server process per `(provider id, canonical workspace - * realpath)`, serves transient-open queries through it, and evicts a crashed process so a later - * query can replace it. It reads sources through Node APIs in the host namespace (not `ctx.fs`) and - * trusts its configured server — no sandbox confinement. + * Generic stdio language-server backend for `ctx.lsp`. One plugin instance configures a named table + * of server commands and registers one isolated provider for each entry. Every provider lazily + * single-flights one server process per canonical workspace realpath, serves transient-open queries + * through it, and evicts a crashed process so a later query can replace it. Providers read sources + * through Node APIs in the host namespace (not `ctx.fs`) and trust their configured servers — no + * sandbox confinement. * * Namespace plugin (named exports, no default export). Lifecycle is effect-scoped: disposal * unregisters from `ctx.lsp` and tears down every live server. @@ -55,10 +55,8 @@ const DEFAULT_MAX_DOCUMENT_BYTES = 4_000_000 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000 const DEFAULT_KILL_GRACE_MS = 2_000 -/** Plugin configuration: one server command plus its extension mapping and host bounds. */ -export interface Config { - /** Stable provider id, reserved on `ctx.lsp` with the extensions. */ - providerId: string +/** One configured local language server and its host bounds. */ +export interface LspLocalServerConfig { /** Executable to spawn (absolute, or resolved on PATH at load). */ command: string /** Lowercase leading-dot extension → LSP language id (e.g. `{ '.ts': 'typescript' }`). */ @@ -83,11 +81,16 @@ export interface Config { killGraceMs?: number } -/** The resolved config after schemastery fills every default; the provider reads this shape. */ -type ResolvedConfig = Required +/** Plugin configuration: provider id → local language-server configuration. */ +export interface Config { + /** Non-empty table of stable provider ids to independent local server configurations. */ + servers: Record +} -export const Config: z = z.object({ - providerId: z.string().required(), +/** One server config after schemastery fills every default. */ +type ResolvedServerConfig = Required + +const LspLocalServerConfig: z = z.object({ command: z.string().required(), args: z.array(String).default([]), env: z.dict(String).default({}), @@ -101,43 +104,66 @@ export const Config: z = z.object({ killGraceMs: z.number().default(DEFAULT_KILL_GRACE_MS), }) +export const Config: z = z.object({ + servers: z.dict(LspLocalServerConfig).required(), +}) + /** - * Register a generic stdio LSP provider. Resolves the executable at load (after credential - * scrubbing) and fails before registration when it is unavailable; the process itself launches - * lazily on the first matching query. + * Register the configured stdio LSP providers. Resolves every executable at load (after credential + * scrubbing) before publishing any provider; each process launches lazily on its first matching + * query. * @param ctx - the plugin context (must inject `lsp`). * @param config - the resolved plugin configuration (schemastery has filled every default). */ export function apply(ctx: Context, config: Config): void { - const resolved = config as ResolvedConfig + const entries = Object.entries(config.servers) + if (entries.length === 0) throw new Error('lsp-local: servers must contain at least one server') + + // Resolve every server-local setting before registration so a bad later command or bound cannot + // publish an earlier provider. Registry-level mapping conflicts are rolled back below. + const providers = entries.map(([providerId, rawConfig]) => { + if (providerId.trim() === '') throw new Error('lsp-local: server ids must be non-empty strings') + const resolved = rawConfig as ResolvedServerConfig + validateServerConfig(providerId, resolved) + const childEnv = buildChildEnv(resolved.env) + const executable = resolveExecutable(resolved.command, childEnv) + return new LocalLspProvider(providerId, resolved, childEnv, executable) + }) + + ctx.effect(() => { + const disposers: Array<() => void> = [] + try { + for (const provider of providers) disposers.push(ctx.lsp.registerProvider(provider)) + } catch (error) { + for (const dispose of disposers.reverse()) dispose() + throw error + } + return async () => { + // Remove every route before process teardown so no new query can enter a draining provider. + for (const dispose of disposers.reverse()) dispose() + await Promise.all(providers.map(provider => provider.disposeAll())) + } + }, 'lsp-local.registerProviders') +} + +/** Validate one resolved server entry before any provider in the table is registered. */ +function validateServerConfig(providerId: string, resolved: ResolvedServerConfig): void { // Teardown budgets feed `deadline()`, whose `<= 0` is the internal no-timeout sentinel; a // nonpositive value would let a server that ignores shutdown hang disposal forever. Fail at load. - assertPositiveInteger('shutdownTimeoutMs', resolved.shutdownTimeoutMs) - assertPositiveInteger('killGraceMs', resolved.killGraceMs) + assertPositiveInteger(providerId, 'shutdownTimeoutMs', resolved.shutdownTimeoutMs) + assertPositiveInteger(providerId, 'killGraceMs', resolved.killGraceMs) // Byte caps must be positive: a nonpositive stderr cap defeats the retained-tail bound // (`slice(-0)` keeps everything), `maxMessageBytes: 0` makes every response fatal, and a bad // document cap fails later in the read path instead of at load. - assertPositiveInteger('maxStderrBytes', resolved.maxStderrBytes) - assertPositiveInteger('maxMessageBytes', resolved.maxMessageBytes) - assertPositiveInteger('maxDocumentBytes', resolved.maxDocumentBytes) - const childEnv = buildChildEnv(resolved.env) - // Resolve the executable eagerly so a misconfigured command fails at load, not on first query. - const executable = resolveExecutable(resolved.command, childEnv) - - const provider = new LocalLspProvider(resolved, childEnv, executable) - ctx.effect(() => { - const dispose = ctx.lsp.registerProvider(provider) - return async () => { - dispose() - await provider.disposeAll() - } - }, 'lsp-local.registerProvider') + assertPositiveInteger(providerId, 'maxStderrBytes', resolved.maxStderrBytes) + assertPositiveInteger(providerId, 'maxMessageBytes', resolved.maxMessageBytes) + assertPositiveInteger(providerId, 'maxDocumentBytes', resolved.maxDocumentBytes) } /** Reject a nonpositive or non-integer config value at load, so misconfiguration fails loud. */ -function assertPositiveInteger(name: string, value: number): void { +function assertPositiveInteger(providerId: string, name: string, value: number): void { if (!Number.isInteger(value) || value < 1) { - throw new Error(`lsp-local: ${name} must be a positive integer`) + throw new Error(`lsp-local: servers.${providerId}.${name} must be a positive integer`) } } @@ -150,11 +176,12 @@ class LocalLspProvider implements LspProvider { private disposed = false constructor( - private readonly config: ResolvedConfig, + providerId: string, + private readonly config: ResolvedServerConfig, private readonly childEnv: Record, private readonly executable: string, ) { - this.id = LspProviderId(config.providerId) + this.id = LspProviderId(providerId) this.extensionToLanguage = config.extensionToLanguage } diff --git a/packages/lsp/lsp-local/tests/built-lib.e2e.ts b/packages/lsp/lsp-local/tests/built-lib.e2e.ts index cea1f0d189..799069c0fd 100644 --- a/packages/lsp/lsp-local/tests/built-lib.e2e.ts +++ b/packages/lsp/lsp-local/tests/built-lib.e2e.ts @@ -46,11 +46,14 @@ describe.skipIf(!built)('built lib real load path (plain node)', () => { const ctx = new Context() await ctx.plugin(Lsp) await ctx.plugin(LspLocal, { - providerId: 'fake', - command: ${JSON.stringify(process.execPath)}, - args: ['--import', ${JSON.stringify(tsxLoader)}, ${JSON.stringify(fixtureServer)}], - env: { TSX_TSCONFIG_PATH: ${JSON.stringify(repoTsconfig)}, LSP_FAKE_DEF: ${JSON.stringify(location)} }, - extensionToLanguage: { '.ts': 'typescript' }, + servers: { + fake: { + command: ${JSON.stringify(process.execPath)}, + args: ['--import', ${JSON.stringify(tsxLoader)}, ${JSON.stringify(fixtureServer)}], + env: { TSX_TSCONFIG_PATH: ${JSON.stringify(repoTsconfig)}, LSP_FAKE_DEF: ${JSON.stringify(location)} }, + extensionToLanguage: { '.ts': 'typescript' }, + }, + }, }) const result = await ctx.lsp.query({ operation: 'definition', filePath: 'a.ts', position: { line: 0, character: 6 }, workspaceRoot: ${JSON.stringify(ws)} }) console.log(JSON.stringify(result)) diff --git a/packages/lsp/lsp-local/tests/lifecycle.spec.ts b/packages/lsp/lsp-local/tests/lifecycle.spec.ts index 78f1a8e419..3d06b7576b 100644 --- a/packages/lsp/lsp-local/tests/lifecycle.spec.ts +++ b/packages/lsp/lsp-local/tests/lifecycle.spec.ts @@ -8,7 +8,7 @@ import { Context } from 'cordis' import Lsp, { type LspQueryRequest, type LspQueryResult } from '@deepseek-ai/dsh-lsp' import { deadline } from '@deepseek-ai/dsh-timeout' import * as LspLocal from '@deepseek-ai/dsh-lsp-local' -import type { Config } from '@deepseek-ai/dsh-lsp-local' +import type { LspLocalServerConfig } from '@deepseek-ai/dsh-lsp-local' const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) const fixtureServer = fileURLToPath(new URL('./fixture-server.ts', import.meta.url)) @@ -28,17 +28,23 @@ afterEach(async () => { await rm(root, { recursive: true, force: true }) }) -/** Mount the real seam + lsp-local plugin driving the fake server with the given env. */ -async function mount(fakeEnv: Record = {}, overrides: Partial = {}): Promise { - const ctx = new Context() - await ctx.plugin(Lsp) - await ctx.plugin(LspLocal, { - providerId: 'fake', +/** One fake stdio server entry with optional behavior and host-bound overrides. */ +function fakeServer(fakeEnv: Record = {}, overrides: Partial = {}): LspLocalServerConfig { + return { command: process.execPath, args: ['--import', tsxLoader, fixtureServer], env: { TSX_TSCONFIG_PATH: repoTsconfig, ...fakeEnv }, extensionToLanguage: { '.ts': 'typescript' }, ...overrides, + } +} + +/** Mount the real seam + lsp-local plugin driving one fake server. */ +async function mount(fakeEnv: Record = {}, overrides: Partial = {}): Promise { + const ctx = new Context() + await ctx.plugin(Lsp) + await ctx.plugin(LspLocal, { + servers: { fake: fakeServer(fakeEnv, overrides) }, }) return ctx } @@ -53,6 +59,24 @@ function locationJson(line: number): unknown { } describe('lsp-local end to end over a fake server', () => { + it('routes different extensions to independent configured servers', async () => { + await writeFile(join(ws, 'a.py'), 'x = 1\n') + const ctx = new Context() + await ctx.plugin(Lsp) + await ctx.plugin(LspLocal, { + servers: { + typescript: fakeServer({ LSP_FAKE_HOVER: JSON.stringify({ contents: 'ts' }) }), + python: fakeServer( + { LSP_FAKE_HOVER: JSON.stringify({ contents: 'py' }) }, + { extensionToLanguage: { '.py': 'python' } }, + ), + }, + }) + expect(await ctx.lsp.query(query('hover', 'a.ts'))).toEqual({ kind: 'hover', hover: { contents: 'ts' } }) + expect(await ctx.lsp.query(query('hover', 'a.py'))).toEqual({ kind: 'hover', hover: { contents: 'py' } }) + await ctx.fiber.dispose() + }) + it('resolves definition to normalized locations', async () => { const ctx = await mount({ LSP_FAKE_DEF: JSON.stringify(locationJson(0)) }) const result = await ctx.lsp.query(query('definition')) @@ -245,10 +269,13 @@ describe('lsp-local end to end over a fake server', () => { const ctx = new Context() await ctx.plugin(Lsp) await expect(ctx.plugin(LspLocal, { - providerId: 'missing', - command: 'definitely-not-a-real-lsp-binary-xyz', - args: [], - extensionToLanguage: { '.ts': 'typescript' }, + servers: { + missing: { + command: 'definitely-not-a-real-lsp-binary-xyz', + args: [], + extensionToLanguage: { '.ts': 'typescript' }, + }, + }, })).rejects.toThrow(/was not found on PATH/) await ctx.fiber.dispose() }) diff --git a/packages/lsp/lsp-local/tests/provider.spec.ts b/packages/lsp/lsp-local/tests/provider.spec.ts index 53f9a88369..65a22bfb5b 100644 --- a/packages/lsp/lsp-local/tests/provider.spec.ts +++ b/packages/lsp/lsp-local/tests/provider.spec.ts @@ -5,6 +5,7 @@ import { join } from 'node:path' import { Context } from 'cordis' import Lsp, { type LspQueryRequest } from '@deepseek-ai/dsh-lsp' import * as LspLocal from '@deepseek-ai/dsh-lsp-local' +import type { Config, LspLocalServerConfig } from '@deepseek-ai/dsh-lsp-local' let root: string let ws: string @@ -24,6 +25,11 @@ function query(): LspQueryRequest { return { operation: 'definition', filePath: 'a.ts', position: { line: 0, character: 0 }, workspaceRoot: ws } } +/** Wrap one server entry in the plugin's named server table. */ +function config(providerId: string, server: LspLocalServerConfig): Config { + return { servers: { [providerId]: server } } +} + describe('lsp-local provider resolution', () => { it('resolves a bare command on the child PATH and registers the provider', async () => { // A tiny executable script placed on a custom PATH dir: the load-time resolver must find it. @@ -35,26 +41,24 @@ describe('lsp-local provider resolution', () => { const ctx = new Context() await ctx.plugin(Lsp) - await expect(ctx.plugin(LspLocal, { - providerId: 'onpath', + await expect(ctx.plugin(LspLocal, config('onpath', { command: 'fake-lsp', args: [], env: { PATH: bin }, extensionToLanguage: { '.ts': 'typescript' }, - })).resolves.toBeDefined() + }))).resolves.toBeDefined() await ctx.fiber.dispose() }) it('skips empty PATH segments and fails when the command is absent', async () => { const ctx = new Context() await ctx.plugin(Lsp) - await expect(ctx.plugin(LspLocal, { - providerId: 'nope', + await expect(ctx.plugin(LspLocal, config('nope', { command: 'fake-lsp', args: [], env: { PATH: `::${join(root, 'empty')}` }, extensionToLanguage: { '.ts': 'typescript' }, - })).rejects.toThrow(/was not found on PATH/) + }))).rejects.toThrow(/was not found on PATH/) await ctx.fiber.dispose() }) @@ -64,12 +68,11 @@ describe('lsp-local provider resolution', () => { await ctx.plugin(Lsp) // Grab the provider instance by registering, then dispose the whole plugin fiber. const lsp = ctx.lsp - const fiber = await ctx.plugin(LspLocal, { - providerId: 'disp', + const fiber = await ctx.plugin(LspLocal, config('disp', { command: process.execPath, args: ['-e', 'setInterval(()=>{},1000)'], extensionToLanguage: { '.ts': 'typescript' }, - }) + })) await fiber.dispose() // After disposal the provider unregistered from the seam, so selection fails as unavailable. await expect(lsp.query(query())).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' })) @@ -79,13 +82,12 @@ describe('lsp-local provider resolution', () => { it('rejects a nonpositive teardown budget at load', async () => { const ctx = new Context() await ctx.plugin(Lsp) - await expect(ctx.plugin(LspLocal, { - providerId: 'bad-budget', + await expect(ctx.plugin(LspLocal, config('bad-budget', { command: process.execPath, args: ['-e', ''], extensionToLanguage: { '.ts': 'typescript' }, killGraceMs: 0, - })).rejects.toThrow(/killGraceMs must be a positive integer/) + }))).rejects.toThrow(/servers\.bad-budget\.killGraceMs must be a positive integer/) await ctx.fiber.dispose() }) @@ -94,24 +96,65 @@ describe('lsp-local provider resolution', () => { await writeFile(notExe, 'plain text, not executable') const ctx = new Context() await ctx.plugin(Lsp) - await expect(ctx.plugin(LspLocal, { - providerId: 'abs-bad', + await expect(ctx.plugin(LspLocal, config('abs-bad', { command: notExe, args: [], extensionToLanguage: { '.ts': 'typescript' }, - })).rejects.toThrow(/is not an executable file/) + }))).rejects.toThrow(/is not an executable file/) await ctx.fiber.dispose() }) it('rejects an executable directory as a command at load', async () => { const ctx = new Context() await ctx.plugin(Lsp) - await expect(ctx.plugin(LspLocal, { - providerId: 'abs-directory', + await expect(ctx.plugin(LspLocal, config('abs-directory', { command: ws, args: [], extensionToLanguage: { '.ts': 'typescript' }, - })).rejects.toThrow(/is not an executable file/) + }))).rejects.toThrow(/is not an executable file/) + await ctx.fiber.dispose() + }) + + it('rejects an empty server table at load', async () => { + const ctx = new Context() + await ctx.plugin(Lsp) + await expect(ctx.plugin(LspLocal, { servers: {} })).rejects.toThrow(/servers must contain at least one server/) + await ctx.fiber.dispose() + }) + + it('rejects an empty server id at load', async () => { + const ctx = new Context() + await ctx.plugin(Lsp) + await expect(ctx.plugin(LspLocal, config('', { + command: process.execPath, + extensionToLanguage: { '.ts': 'typescript' }, + }))).rejects.toThrow(/server ids must be non-empty strings/) + await ctx.fiber.dispose() + }) + + it('resolves every executable before publishing any provider', async () => { + const ctx = new Context() + await ctx.plugin(Lsp) + await expect(ctx.plugin(LspLocal, { + servers: { + valid: { command: process.execPath, extensionToLanguage: { '.ts': 'typescript' } }, + missing: { command: 'definitely-not-a-real-lsp-binary-xyz', extensionToLanguage: { '.py': 'python' } }, + }, + })).rejects.toThrow(/was not found on PATH/) + await expect(ctx.lsp.query(query())).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' })) + await ctx.fiber.dispose() + }) + + it('rolls back earlier registrations when a later server conflicts', async () => { + const ctx = new Context() + await ctx.plugin(Lsp) + await expect(ctx.plugin(LspLocal, { + servers: { + first: { command: process.execPath, extensionToLanguage: { '.ts': 'typescript' } }, + second: { command: process.execPath, extensionToLanguage: { '.ts': 'typescript' } }, + }, + })).rejects.toThrow(expect.objectContaining({ code: 'LSP_CONFLICT' })) + await expect(ctx.lsp.query(query())).rejects.toThrow(expect.objectContaining({ code: 'LSP_UNAVAILABLE' })) await ctx.fiber.dispose() }) }) diff --git a/packages/lsp/lsp-local/tests/typescript-server.e2e.ts b/packages/lsp/lsp-local/tests/typescript-server.e2e.ts index ca4df620d3..300ce7d318 100644 --- a/packages/lsp/lsp-local/tests/typescript-server.e2e.ts +++ b/packages/lsp/lsp-local/tests/typescript-server.e2e.ts @@ -53,10 +53,13 @@ beforeAll(async () => { ctx = new Context() await ctx.plugin(Lsp) await ctx.plugin(LspLocal, { - providerId: 'typescript', - command: serverBin, - args: ['--stdio'], - extensionToLanguage: { '.ts': 'typescript', '.tsx': 'typescriptreact' }, + servers: { + typescript: { + command: serverBin, + args: ['--stdio'], + extensionToLanguage: { '.ts': 'typescript', '.tsx': 'typescriptreact' }, + }, + }, }) }, 60_000) diff --git a/packages/lsp/lsp/README.md b/packages/lsp/lsp/README.md index 8e51d0653a..8923523e05 100644 --- a/packages/lsp/lsp/README.md +++ b/packages/lsp/lsp/README.md @@ -7,7 +7,7 @@ This package is the interface third of the LSP capability: | Package | Role | |---|---| | `@deepseek-ai/dsh-lsp` (this) | the interface: the service, provider registry keyed by branded id + extension mapping, per-query selection, request/result vocabulary, the `LspError` taxonomy | -| `@deepseek-ai/dsh-lsp-local` | a generic stdio language-server provider | +| `@deepseek-ai/dsh-lsp-local` | a generic local backend that registers configured stdio language-server providers | | `@deepseek-ai/dsh-tool-lsp` | the model-facing `lsp` tool over `ctx.lsp` | The seam exposes exactly four semantic operations — `definition`, `references`, `implementation`, `hover` — and no generic JSON-RPC escape hatch, so no protocol payload or unreviewed command/mutation reaches a provider through `ctx.lsp`. diff --git a/packages/lsp/tool-lsp/tests/integration.spec.ts b/packages/lsp/tool-lsp/tests/integration.spec.ts index f2e8d1c46a..74d9c6ae77 100644 --- a/packages/lsp/tool-lsp/tests/integration.spec.ts +++ b/packages/lsp/tool-lsp/tests/integration.spec.ts @@ -52,12 +52,15 @@ async function mount(hang: boolean, timeoutMs?: number): Promise { await ctx.plugin(ToolRegistry) await ctx.plugin(Lsp) await ctx.plugin(LspLocal, { - providerId: 'inline', - command: process.execPath, - args: ['-e', serverScript(hang)], - extensionToLanguage: { '.ts': 'typescript' }, - shutdownTimeoutMs: 200, - killGraceMs: 200, + servers: { + inline: { + command: process.execPath, + args: ['-e', serverScript(hang)], + extensionToLanguage: { '.ts': 'typescript' }, + shutdownTimeoutMs: 200, + killGraceMs: 200, + }, + }, }) await ctx.plugin(TimeoutPolicy) await ctx.plugin(ToolLsp, timeoutMs !== undefined ? { timeoutMs } : {}) From e92ec69f32058ff10bede65f43e6452575226ce3 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Thu, 16 Jul 2026 17:55:07 +0800 Subject: [PATCH 019/273] refactor(lsp): drop redundant side-effect type import The value import of LspProviderId already pulls in the cordis module augmentation for ctx.lsp, so the separate `import type {}` is dead. --- docs/config-catalog.md | 2 +- packages/lsp/lsp-local/src/index.ts | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 636713146c..ba2476b1a5 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -457,7 +457,7 @@ export interface LspLocalServerConfig { } ``` -Source: [`packages/lsp/lsp-local/src/index.ts:85`](../packages/lsp/lsp-local/src/index.ts) +Source: [`packages/lsp/lsp-local/src/index.ts:83`](../packages/lsp/lsp-local/src/index.ts) ## `@deepseek-ai/dsh-mcp-client` diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts index 07e1cbed5a..03ae5e9781 100644 --- a/packages/lsp/lsp-local/src/index.ts +++ b/packages/lsp/lsp-local/src/index.ts @@ -21,8 +21,6 @@ import type { LspProviderQuery, LspQueryResult, } from '@deepseek-ai/dsh-lsp' -// Side-effect type import: declaration-merges `ctx.lsp` onto Context. -import type {} from '@deepseek-ai/dsh-lsp' import { canonicalizeWorkspace, readHostSource } from './host.ts' import { abortError, LspInstance } from './instance.ts' import type { InstanceSpec } from './instance.ts' From c238992fbbba0b35f7bf2848712960a39e49ea0e Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 16 Jul 2026 18:12:34 +0800 Subject: [PATCH 020/273] feat(core): make turn cancellation explicit --- docs/architecture.md | 4 +- docs/config-catalog.md | 2 +- docs/cordis-catalog/events.md | 44 +-- docs/cordis-catalog/services.md | 2 +- docs/core-data-structures/core.md | 30 +- docs/core-data-structures/session.md | 5 +- docs/core-data-structures/system-prompt.md | 3 +- docs/event-producer-consumer.md | 30 +- docs/persistence-catalog.md | 30 +- docs/rfc/INDEX.md | 1 + ...-18-agent-lifecycle-and-ownership-seams.md | 4 +- ...07-16-explicit-turn-cancellation.i18n.yaml | 6 + .../2026-07-16-explicit-turn-cancellation.md | 55 ++++ ...026-07-16-explicit-turn-cancellation.zh.md | 55 ++++ .../2026-06-20-public-agent-stop-surface.md | 8 +- .../tests/snapshots/cancel/session.jsonl | 2 +- .../cordis/tool-cordis/src/api-catalog.ts | 20 +- packages/core/agent-loop/README.md | 6 +- packages/core/agent-loop/src/agent.ts | 61 ++-- packages/core/agent-loop/src/cancellation.ts | 31 ++ packages/core/agent-loop/src/inbox.ts | 2 +- packages/core/agent-loop/src/loop.ts | 236 ++++++++------- .../agent-loop/tests/agent-execution.spec.ts | 76 +++++ packages/core/agent-loop/tests/agent.spec.ts | 2 +- packages/core/agent-loop/tests/cancel.spec.ts | 268 +++++++++++++++--- .../tests/contract-regressions.spec.ts | 51 ++-- .../agent-loop/tests/coverage-edges.spec.ts | 4 +- .../agent-loop/tests/interception.spec.ts | 8 +- packages/core/agent-loop/tests/loop.spec.ts | 14 +- .../tests/request-reconstruction.spec.ts | 6 +- packages/core/agent-loop/tests/resume.spec.ts | 2 +- .../core/agent-loop/tests/turn-stop.spec.ts | 2 +- packages/core/agent/README.md | 4 +- packages/core/agent/src/dispatch.ts | 5 +- packages/core/agent/src/types.ts | 100 ++++++- packages/core/agent/tests/agent.spec.ts | 6 +- packages/core/session/README.md | 2 + packages/core/session/src/types.ts | 3 +- packages/core/session/tests/fork.spec.ts | 2 +- packages/core/session/tests/session.spec.ts | 10 + packages/core/system-prompt/README.md | 4 +- packages/core/system-prompt/src/index.ts | 4 + packages/guard/repeat-tool-guard/src/index.ts | 2 +- packages/hooks/hook-protocol/src/runner.ts | 2 +- packages/hooks/hooks-claude/src/index.ts | 8 +- packages/hooks/hooks-codex/src/index.ts | 8 +- .../subagent/subagent-inprocess/src/index.ts | 2 +- .../subagent-inprocess/src/structured.ts | 2 +- .../tests/structured.spec.ts | 4 +- .../tests/subagent-inprocess.spec.ts | 11 +- packages/ui/acp/src/index.ts | 10 +- packages/ui/acp/tests/codec.spec.ts | 2 +- packages/ui/acp/tests/turns.spec.ts | 4 + scripts/translation-pairing.manifest.json | 1 + scripts/type-equiv.manifest.json | 1 + 55 files changed, 884 insertions(+), 383 deletions(-) create mode 100644 docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml create mode 100644 docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.md create mode 100644 docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md create mode 100644 packages/core/agent-loop/src/cancellation.ts diff --git a/docs/architecture.md b/docs/architecture.md index d4faf07f4b..18675d6862 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -102,7 +102,7 @@ Post-tool context follows all results, preserving call/result adjacency. Steerin ### Failure Boundaries -The turn contains listener, adapter, and step failures: it records an error reason and emits `agent/error` without killing the driver. `cancel()` clears pending work, aborts active model/tool work when possible, and records the turn end. Disposal stops and drains the loop before unregistering the agent. +The turn contains listener, adapter, and step failures: it records an error reason and emits `agent/error` without killing the driver. One explicit `AbortSignal` spans prompt submission, prompt assembly, all steps, continuation, turn close, and flush; `cancel()` clears pending work and carries a typed `user` or `parent` runtime cause, while the durable turn records only `aborted` and disposal remains a distinct higher-priority terminal state. Cooperative work must settle before the loop reports quiescence. See the [explicit turn cancellation decision](rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.md). Every session event is turn-enclosed. Reload closes an interrupted tail with a synthetic `interrupted` end; failures after durable turn close only emit `agent/error`. A turn has one `TurnEndReason`; [TurnEndReasonMap](core-data-structures/session.md#why-a-turn-ended-turnendreasonmap) defines each variant. @@ -116,7 +116,7 @@ Every live agent owns a scoped `agent.ctx`; its registrations shadow globals, re ### Agent Execution Context -`AgentLoop` wraps each concrete driver in process-local `ctx.agentExecution`; child creation and setup stay outside its boundary, and explicit identities remain authoritative. See the [package contract](../packages/core/agent-execution/README.md) and [decision](rfc/implemented/architecture/2026-07-15-agent-execution-context.md). +`AgentLoop` wraps each concrete driver in process-local `ctx.agentExecution`; its ALS frame contains only `{ agent }`. Child creation and setup stay outside the boundary, and turn, step, signal, cwd, and authority remain explicit. See the [package contract](../packages/core/agent-execution/README.md) and [decision](rfc/implemented/architecture/2026-07-15-agent-execution-context.md). ## State diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 06547594ec..3981ea5dc6 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -863,7 +863,7 @@ export interface Config { } ``` -Source: [`packages/core/system-prompt/src/index.ts:143`](../packages/core/system-prompt/src/index.ts) +Source: [`packages/core/system-prompt/src/index.ts:147`](../packages/core/system-prompt/src/index.ts) ## `@deepseek-ai/dsh-time-context` diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index ede449cb1c..180537eec1 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -23,7 +23,7 @@ A fully configured agent and live session were published. Setup is composition-o Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:139`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:206`](../../packages/core/agent/src/types.ts) ### `agent/disposed` — emit @@ -35,7 +35,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence but bef Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:148`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:215`](../../packages/core/agent/src/types.ts) ### `agent/error` — emit @@ -47,7 +47,7 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:283`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:357`](../../packages/core/agent/src/types.ts) ### `agent/pre-step` — serial @@ -59,19 +59,19 @@ Awaited serial checkpoint for session-surface mutation after prompt assembly and Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:202`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:269`](../../packages/core/agent/src/types.ts) ### `agent/prompt-submit` — waterfall -Allow, rewrite, or block one drained prompt before it becomes a user message. Call `next()` for the unchanged default. +Allow, rewrite, or block one drained prompt before it becomes a user message. Call `next()` for the unchanged default. The signal controls only this turn; listeners may cooperate with it but must not retain it to control another turn. ```ts cordis-catalog -'agent/prompt-submit'(this: Scoped, agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise): Promise +'agent/prompt-submit'(this: Scoped, agent: Agent, content: ContentBlock[], source: MessageSource, signal: AbortSignal, next: () => Promise): Promise ``` Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:212`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:282`](../../packages/core/agent/src/types.ts) ### `agent/queued` — emit @@ -83,19 +83,19 @@ Detached, frozen content entered the agent's inbox. Source defaults have already Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:234`](../../packages/core/agent/src/types.ts) ### `agent/request` — waterfall Replace the frozen call configuration. Model-visible content must use logged channels; this seam cannot mutate messages. Injection here joins the next request because the current step boundary is already fixed. ```ts cordis-catalog -'agent/request'(this: Scoped, agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise): Promise +'agent/request'(this: Scoped, agent: Agent, turn: number, step: number, config: LlmCallConfig, signal: AbortSignal, next: () => Promise): Promise ``` Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:224`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:295`](../../packages/core/agent/src/types.ts) ### `agent/session-prefix` — waterfall @@ -107,7 +107,7 @@ Compose request-only messages placed before derived history. The frozen result i Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:239`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:310`](../../packages/core/agent/src/types.ts) ### `agent/session-start` — emit @@ -119,7 +119,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to Types: [Agent](../core-data-structures/core.md) · [SessionStartSource](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:180`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:247`](../../packages/core/agent/src/types.ts) ### `agent/status` — emit @@ -131,43 +131,43 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does no Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:157`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:224`](../../packages/core/agent/src/types.ts) ### `agent/step-result` — waterfall Waterfall: post-process the assembled assistant Message before tool dispatch (validation, content rewriting, …). ```ts cordis-catalog -'agent/step-result'(this: Scoped, agent: Agent, turn: number, step: number, message: Message, next: () => Promise): Promise +'agent/step-result'(this: Scoped, agent: Agent, turn: number, step: number, message: Message, signal: AbortSignal, next: () => Promise): Promise ``` Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:250`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:322`](../../packages/core/agent/src/types.ts) ### `agent/turn-continuation` — waterfall Override whether the turn continues. The default continues after tool calls or steering and stops otherwise; a continue reason becomes steering. ```ts cordis-catalog -'agent/turn-continuation'(this: Scoped, agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise): Promise +'agent/turn-continuation'(this: Scoped, agent: Agent, turn: number, defaultDecision: ContinuationDecision, signal: AbortSignal, next: () => Promise): Promise ``` Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:260`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:333`](../../packages/core/agent/src/types.ts) ### `agent/turn-stop` — serial Monotonic terminal-stop checkpoint after continuation and steering are folded; a stop remains authoritative through turn close and flush: steering queued in that window is discarded, while ordinary sends survive. ```ts cordis-catalog -'agent/turn-stop'(this: Scoped, agent: Agent, turn: number): ContinuationStop | undefined +'agent/turn-stop'(this: Scoped, agent: Agent, turn: number, signal: AbortSignal): Promise | ContinuationStop | undefined ``` Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:270`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:344`](../../packages/core/agent/src/types.ts) ## `approval/*` @@ -325,13 +325,13 @@ Source: [`packages/subagent/subagent/src/index.ts:99`](../../packages/subagent/s ### `system-prompt/assemble` — waterfall -Expert waterfall over the assembled sections, tools, and variables. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners receive only that scope's assemblies. The returned value is authoritative. +Expert waterfall over the assembled sections, tools, and variables. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners receive only that scope's assemblies. The returned value is authoritative. A supplied signal controls only this explicit assembly request and must not be retained to control later turns. ```ts cordis-catalog 'system-prompt/assemble'(this: Scoped, assembly: PromptAssembly, context: AssembleContext, next: () => Promise): Promise ``` -Source: [`packages/core/system-prompt/src/index.ts:27`](../../packages/core/system-prompt/src/index.ts) +Source: [`packages/core/system-prompt/src/index.ts:29`](../../packages/core/system-prompt/src/index.ts) ### `system-prompt/change` — emit @@ -341,7 +341,7 @@ Emitted when any prompt provider changes. This registry notification is unfilter 'system-prompt/change'(): void ``` -Source: [`packages/core/system-prompt/src/index.ts:33`](../../packages/core/system-prompt/src/index.ts) +Source: [`packages/core/system-prompt/src/index.ts:35`](../../packages/core/system-prompt/src/index.ts) ## `tools/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index ac002b3e4b..001fd1e75c 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -254,7 +254,7 @@ variable(name: string, provider: (context: AssembleContext) => string | undefine async assemble(context: AssembleContext = {}): Promise ``` -Source: [`packages/core/system-prompt/src/index.ts:209`](../../packages/core/system-prompt/src/index.ts) +Source: [`packages/core/system-prompt/src/index.ts:213`](../../packages/core/system-prompt/src/index.ts) ## `ctx.tasks` — `TaskService` diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index 133458f55b..5e98169659 100644 --- a/docs/core-data-structures/core.md +++ b/docs/core-data-structures/core.md @@ -246,6 +246,14 @@ The fifteen event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts) +`AgentCancelCause` identifies the runtime caller without widening the durable turn outcome. The concrete Agent validates, detaches, and freezes this value before placing it on the current turn signal; Session replay records only that the turn was aborted. + +```ts type-equiv +type AgentCancelCause = + | { readonly kind: 'user' } + | { readonly kind: 'parent' } +``` + ```ts type-equiv interface Agent { readonly id: AgentId @@ -300,22 +308,14 @@ interface Agent { inject(content: ContentBlock[], options?: SendOptions): void /** - * Cancel ALL pending work for the agent. `cancel()`: - * - * - clears the queued FIFO (un-started prompts never run) and the steering - * FIFO (steering for the cancelled turn is dropped, not re-enqueued); - * - aborts the in-flight step if one is running (the turn ends `aborted`); - * - drops a turn that is about to start (a `cancel()` landing in the - * pre-step window — after a `send()` queued but before the loop flips to - * `running`, or after `running` is emitted but before the first step) so - * that queued prompt does not run and cannot be batched into the cancelled - * turn. - * - * After `cancel()`, `whenIdle()` resolves on the post-cancel quiescent state. - * `cancel()` on an idle agent with nothing queued or running is a safe no-op - * — it does NOT arm anything that would drop a later legitimate prompt. + * Clear queued and steering work, including work waiting to start, and abort + * the active turn. The first cause wins for that turn, and `whenIdle()` resolves + * after cancellation reaches quiescence. Omission means `{ kind: 'user' }`; + * invalid causes throw synchronously even while idle. Idle cancellation is a + * no-op after validation and does not arm a later cancel. + * @param cause - the stable caller intent carried by the current turn signal. */ - cancel(reason?: string): void + cancel(cause?: AgentCancelCause): void /** * Resolve once the agent has reached quiescence after settling out of diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md index d8292c49b3..68421022ea 100644 --- a/docs/core-data-structures/session.md +++ b/docs/core-data-structures/session.md @@ -254,10 +254,13 @@ interface TurnTriggerMap { ## Why a turn ended: `TurnEndReasonMap` +`aborted` is intentionally a coarse durable outcome: it records that cancellation interrupted the live turn, not which runtime caller requested it. The runtime-only caller vocabulary belongs to [`AgentCancelCause`](core.md#the-agent-handle); a future audit requirement would use a separate control-request event rather than overloading the terminal result. + ```ts type-equiv interface TurnEndReasonMap { completed: { kind: 'completed' } - aborted: { kind: 'aborted'; reason?: string } + /** A cancellation request interrupted the live turn. */ + aborted: { kind: 'aborted' } /** * The turn failed: a step threw or the model reported a failure. `step` is the * step number the failure occurred on (the operational error's location — the diff --git a/docs/core-data-structures/system-prompt.md b/docs/core-data-structures/system-prompt.md index 4b6f1e6625..0ffc243279 100644 --- a/docs/core-data-structures/system-prompt.md +++ b/docs/core-data-structures/system-prompt.md @@ -6,11 +6,12 @@ Source: [`packages/core/system-prompt/src/index.ts`](../../packages/core/system- ## Assembly context -`AssembleContext` identifies the scope layer one assembly resolves. It is merge-extensible: `dsh-agent` adds the optional live `agent` field, and `assembleContextFor(agent)` sets that field and `scope` together. +`AssembleContext` identifies the scope layer one assembly resolves and may carry the explicit control signal for that request. It is merge-extensible: `dsh-agent` adds the optional live `agent` field, and `assembleContextFor(agent, signal)` sets the explicit fields together. A bare assembly has neither scope nor signal. ```ts type-equiv interface AssembleContext { scope?: ScopeKey + signal?: AbortSignal } ``` diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index d8c924b24d..9ca0c378d9 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -7,19 +7,19 @@ This matrix shows which packages dispatch each harness-owned event and which pac | Event | Mode | Declared in | Dispatchers | Listeners | | --- | --- | --- | --- | --- | -| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:139`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`jsonrpc`](../packages/ui/jsonrpc), [`stdio`](../packages/ui/stdio) | -| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:148`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`stdio`](../packages/ui/stdio) | -| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:283`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:202`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`user-approval`](../packages/ui/user-approval) | -| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:212`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | -| `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:167`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:224`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:239`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill) | -| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:180`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:157`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`invariants`](../packages/support/invariants), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`stdio`](../packages/ui/stdio) | -| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:250`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:260`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `agent/turn-stop` | `serial` | [`packages/core/agent/src/types.ts:270`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | +| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:206`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`jsonrpc`](../packages/ui/jsonrpc), [`stdio`](../packages/ui/stdio) | +| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:215`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`stdio`](../packages/ui/stdio) | +| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:357`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:269`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`user-approval`](../packages/ui/user-approval) | +| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:282`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | +| `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:234`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:295`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:310`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill) | +| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:247`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:224`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`invariants`](../packages/support/invariants), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`stdio`](../packages/ui/stdio) | +| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:322`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:333`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `agent/turn-stop` | `serial` | [`packages/core/agent/src/types.ts:344`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | | `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:31`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/ui/acp) | | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:59`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) | | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:68`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) | @@ -33,8 +33,8 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:82`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) | | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:88`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`tool-subagent`](../packages/subagent/tool-subagent) | | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:99`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) | -| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:27`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | - | -| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:33`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - | +| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | - | +| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - | | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:116`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - | | `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:89`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`timeout-policy`](../packages/timeout/timeout-policy) | | `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:98`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index a27b19b9a7..ca2f1e4094 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -57,7 +57,7 @@ Raw stream chunk — token-level replay fidelity. Types: [StreamChunk](core-data-structures/llm-streaming.md) -Source: [`packages/core/session/src/types.ts:242`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:243`](../packages/core/session/src/types.ts) #### `assistant/message` — surface @@ -69,7 +69,7 @@ Assembled assistant message for one step (derived history uses this). Carries th Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md) -Source: [`packages/core/session/src/types.ts:249`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:250`](../packages/core/session/src/types.ts) ### `bash/*` @@ -129,7 +129,7 @@ In-session context injection (file-change notices, subdir AGENTS.md, skill conte Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:240`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:241`](../packages/core/session/src/types.ts) ### `hook/*` @@ -177,7 +177,7 @@ Durable record of a prompt veto and its reason. It is log-only: the blocked prom Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:234`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:235`](../packages/core/session/src/types.ts) ### `request/*` @@ -189,7 +189,7 @@ Full EpochHeader for the next request, appended inside its step before dispatch. 'request/header': { header: EpochHeader; reason: RequestHeaderReason } ``` -Source: [`packages/core/session/src/types.ts:277`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:278`](../packages/core/session/src/types.ts) #### `request/header-delta` — log-only @@ -199,7 +199,7 @@ Log-only amendment to the folded EpochHeader. System and tools use their delta c 'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[] } ``` -Source: [`packages/core/session/src/types.ts:283`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:284`](../packages/core/session/src/types.ts) ### `steering/*` @@ -213,7 +213,7 @@ Steering content injected between steps of a running turn. Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:267`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:268`](../packages/core/session/src/types.ts) ### `step/*` @@ -225,7 +225,7 @@ Closes step `step` of turn `turn`. 'step/end': { turn: number; step: number } ``` -Source: [`packages/core/session/src/types.ts:227`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:228`](../packages/core/session/src/types.ts) #### `step/start` — log-only @@ -235,7 +235,7 @@ Opens step `step` of turn `turn` — one model call plus the tool executions it 'step/start': { turn: number; step: number } ``` -Source: [`packages/core/session/src/types.ts:225`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:226`](../packages/core/session/src/types.ts) ### `todo/*` @@ -249,7 +249,7 @@ Whole-list snapshot; the latest write wins on replay. It is log-only UI state an Types: [TodoItem](core-data-structures/session.md) -Source: [`packages/core/session/src/types.ts:272`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:273`](../packages/core/session/src/types.ts) ### `tool/*` @@ -263,7 +263,7 @@ The model requested one tool invocation: `name` with the raw `arguments` JSON st Types: [CallId](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:255`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:256`](../packages/core/session/src/types.ts) #### `tool/code-dispatch` — log-only @@ -287,7 +287,7 @@ A completed tool call's model-facing result, plus an optional tool-private `meta Types: [CallId](core-data-structures/core.md) · [ContentBlock](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:265`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:266`](../packages/core/session/src/types.ts) ### `turn/*` @@ -301,7 +301,7 @@ Closes turn `turn` with the TurnEndReason that ended it. The loop fires the awai Types: [TurnEndReason](core-data-structures/session.md) -Source: [`packages/core/session/src/types.ts:223`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:224`](../packages/core/session/src/types.ts) #### `turn/start` — log-only @@ -313,7 +313,7 @@ Opens turn `turn`. `trigger` records what started it — a drained message batch Types: [TurnTrigger](core-data-structures/session.md) -Source: [`packages/core/session/src/types.ts:217`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:218`](../packages/core/session/src/types.ts) ### `user/*` @@ -327,4 +327,4 @@ A user-visible prompt (queued message drained at turn start). Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:229`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:230`](../packages/core/session/src/types.ts) diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index bc355fa328..78a11d4619 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -150,6 +150,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [Single-file executable SDK runtime distribution (single-exe)](implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) | 2026-07-10 | | [Agent-scope runtime design and correctness](implemented/architecture/2026-07-12-agent-scope-runtime-design.md) | 2026-07-12 | | [Agent execution context over AsyncLocalStorage](implemented/architecture/2026-07-15-agent-execution-context.md) | 2026-07-15 | +| [Explicit turn cancellation capability](implemented/architecture/2026-07-16-explicit-turn-cancellation.md) | 2026-07-16 | ### Process diff --git a/docs/rfc/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md b/docs/rfc/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md index 665063399d..9305941629 100644 --- a/docs/rfc/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md +++ b/docs/rfc/implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md @@ -10,9 +10,9 @@ Several ACP and tool-bash limitations were symptoms of the same missing seam: pl Three seams: the queue-aware cancel, the `AgentHandle` disposer, and the bash owner token. -### 1. Queue-aware `Agent.cancel(reason?)` +### 1. Queue-aware `Agent.cancel(cause?)` -`cancel()` is the single public stop primitive. It clears queued and steering input, aborts an in-flight step, and arms a turn-scoped marker checked at each turn boundary. A queued prompt therefore cannot start after cancellation or absorb later input. `whenIdle()` waits for post-cancel quiescence, and ACP `session/cancel` maps to this method. An idle cancel does not arm the marker. +`cancel()` is the single public stop primitive. It clears queued and steering input and aborts the active turn through one private turn cancellation holder; a cause-less pre-run marker covers work not yet claimed by the driver without leaking into replacement input. The typed cause is `user` or `parent`, with omission and ACP `session/cancel` mapping to `user`. `whenIdle()` waits for actual post-cancel quiescence, and an idle cancel validates its cause without arming future work. See the [explicit turn cancellation contract](2026-07-16-explicit-turn-cancellation.md). ### 2. `AgentHandle` async disposer diff --git a/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml b/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml new file mode 100644 index 0000000000..c9de5dd06a --- /dev/null +++ b/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# 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 +2026-07-16-explicit-turn-cancellation.md: 3716895c145c24603a93dab99108489e19154490 +2026-07-16-explicit-turn-cancellation.zh.md: d2f8a4227d38a05d7ed1dd5135a20d3b4e94deed diff --git a/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.md b/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.md new file mode 100644 index 0000000000..3716895c14 --- /dev/null +++ b/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.md @@ -0,0 +1,55 @@ +# RFC: Explicit turn cancellation capability + +Status: implemented + +English | [中文](2026-07-16-explicit-turn-cancellation.zh.md) + +## Problem + +Cancellation is a control capability with a shorter lifetime than an Agent driver. A free-form string cannot distinguish callers exhaustively, and a step-local controller cannot interrupt prompt submission, prompt assembly, continuation, or terminal turn policy. Storing `Error`, `AbortSignal.reason`, or backend-private objects would also expose unstable runtime details to durable replay. + +The [Agent execution context decision](2026-07-15-agent-execution-context.md) intentionally keeps the AsyncLocalStorage frame at `{ agent }`. Adding turn, step, or signal state to that driver-lifetime frame would make stale asynchronous descendants appear to retain authority over later turns. Cancellation therefore needs one turn owner and explicit propagation without creating another ambient context or public turn wrapper. + +## Decision + +Agent owns the runtime-only `AgentCancelCause` union `{ kind: 'user' } | { kind: 'parent' }`; `agent.cancel()` defaults to `user`. The normalization boundary accepts only an exact ordinary or null-prototype object with one supported `kind`, then returns a detached frozen value for the current turn signal. Strings, extra or symbol fields, unknown kinds, arrays, class instances, `Error`, and `AbortSignal` are rejected synchronously even when the Agent is idle. + +An interrupted live turn ends with the coarse durable `{ kind: 'aborted' }` outcome. The terminal event records what happened to the turn, while the runtime signal identifies who requested cancellation; it does not duplicate `user` or `parent` into replay. A future audit requirement uses a separate control-request event so a request and its eventual outcome remain distinct. Durable events contain no stack, signal, error object, free-form cancellation text, or backend-private detail. + +AgentLoop privately owns one `TurnCancellation` per prospective turn. It installs the holder before notifying `agent/status = running`, retains its single `AbortController` through prompt processing, prompt assembly, every step, model and tool execution, continuation, `agent/turn-stop`, `turn/end`, and durability flush, then clears it. Every participating method, event, and request value receives that same explicit signal; the next turn receives a fresh signal. + +The driver keeps only a cause-less pre-run marker for queued work cancelled before a turn is claimed. It clears the queued and steering work that existed when `cancel()` ran without arming cancellation for future prompts. If a `running` listener synchronously cancels old work and sends a replacement, the driver discards the aborted holder and creates a fresh one for the replacement. Repeated cancellation is first-wins for the active holder, while later calls may still clear newly queued pending work. + +The explicit event signatures keep their positional form and place `signal` immediately before a waterfall's final `next`. Prompt submission, request configuration, step-result processing, continuation, and terminal stop join the pre-existing explicit signal seams for pre-step, session prefix, model generation, tool execution, approval, and subagent or workflow requests. `SystemPrompt.assemble()` carries `signal?: AbortSignal` in `AssembleContext` because that object is an explicit request value. Listeners may cooperate with the signal but must not retain it to control another turn. + +`ctx.agentExecution` remains identity-only. Ambient Agent presence does not imply liveness, a current turn, or cancellation authority, and `agentInterruptReasonOf(signal)` reads only its explicit argument. Concurrent Agents isolate both their ALS identities and their turn signals; a child Agent shadows the parent identity while its parent request signal still travels through the subagent seam. + +Agent disposal requests the runtime-only `{ kind: 'disposed' }` interruption on the active holder. If cancellation already won the controller reason, the reason cannot be rewritten, so terminal classification first checks lifecycle state: disposed wins, then a supported `user` or `parent` cause becomes the coarse aborted outcome, and unrelated exceptions retain the existing error path. ACP cancellation maps to `user`; in-process spawn and fork propagation map to `parent`. Remote ACP subagents retain their existing wire protocol. + +Cancellation remains cooperative. The loop checks interruption before and after awaited boundaries but does not use `Promise.race` to abandon an in-process listener, adapter, or tool Promise. Work that ignores the signal must settle before `whenIdle()`, handle disposal, and scope teardown report quiescence. + +## Verification + +Contract tests verify strict runtime cause validation, frozen detachment, default and first-wins behavior, the coarse Session JSON round trip, ACP `user`, in-process subagent `parent`, and disposal precedence. Loop tests make cooperative listeners wait on the signal at prompt submission, system-prompt assembly, session prefix, pre-step, request, model stream, step result, tool execution, continuation, and terminal stop; they assert one signal within a turn and a fresh signal across turns. + +Execution-context tests assert that every hook still observes exactly `{ agent }`, concurrent Agents retain independent identities and signals, and nested child creation shadows only identity. Race tests cover idle cancellation, pre-run cancellation, replacement submission from a `running` listener, repeated cancellation, and cancel-versus-dispose quiescence. + +## Alternatives considered + +**Store the signal in ALS.** ALS follows asynchronous descendants for the entire driver lifetime, while cancellation authority ends with one turn. A leaked callback could observe a stale signal or require mutable frame replacement, so the identity frame stays `{ agent }` and control remains explicit. + +**Persist a free-form string reason.** Strings admit spelling drift, prevent exhaustive switching, and encourage consumers to parse presentation text. The runtime uses a closed discriminated union, while the terminal record needs only the stable aborted outcome. + +**Persist the typed caller cause in `turn/end`.** No production replay, UI, ACP, telemetry, or workflow consumer distinguishes `user` from `parent`. Copying the request source into the terminal result would conflate two facts and add Session-specific validation without a consumer; a future audit surface can record a separate cancellation-request event. + +**Define speculative `superseded`, `timeout`, and `shutdown` variants now.** No current Agent cancellation producer implements those semantics. `shutdown` is already lifecycle disposal, and timeout or supersession should enter the union only with an owning policy and unique terminal meaning. + +**Expose public turn or step context wrappers.** Existing positional seams already identify Agent, turn, and step. A wrapper would widen every API, duplicate ownership, and tempt callers to treat a captured object as durable authority. + +**Abandon uncooperative work after a grace period.** Returning idle while same-process work still runs breaks teardown and resource-ownership guarantees. Hard termination requires a worker or process isolation boundary and is outside this control seam. + +## Consequences + +Cancellation has one runtime owner, one signal per turn, and one typed runtime caller vocabulary. Session retains the coarse `aborted` outcome that its consumers actually use, stays isolated from runtime objects, and no longer needs cancellation-specific canonicalization. Cooperative cancellation reaches every asynchronous turn seam, including work before the first step and after the last one. + +The explicit signal adds parameters to several public events and requires plugins to forward cancellation deliberately. This is intentional: authority is visible at the call boundary, lifetime matches the turn, and stale ambient descendants cannot acquire control. Uncooperative in-process work may delay cancellation, but the reported quiescent state remains truthful. diff --git a/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md b/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md new file mode 100644 index 0000000000..d2f8a4227d --- /dev/null +++ b/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md @@ -0,0 +1,55 @@ +# RFC:显式的 turn 取消能力 + +Status: implemented + +[English](2026-07-16-explicit-turn-cancellation.md) | 中文 + +## 问题 + +取消是一种生命周期短于 Agent 驱动的控制能力。自由文本字符串无法对调用方进行穷尽区分,步骤级 controller 也无法中断 prompt 提交、prompt 组装、continuation 或 turn 终止策略。持久化 `Error`、`AbortSignal.reason` 或后端私有对象还会把不稳定的运行时细节暴露给持久化 replay。 + +[Agent 执行上下文决策](2026-07-15-agent-execution-context.md)有意让 AsyncLocalStorage 帧保持为 `{ agent }`。若把 turn、步骤或 signal 状态加入这个与驱动同生命周期的帧,陈旧的异步后代就会看似仍对后续 turn 拥有权限。因此,取消需要一个 turn 归属方和显式传播,不能引入另一套环境上下文或公开 turn 包装类型。 + +## 决策 + +Agent 拥有仅用于运行时的 `AgentCancelCause` union:`{ kind: 'user' } | { kind: 'parent' }`;`agent.cancel()` 默认使用 `user`。规范化边界只接受恰好包含一个受支持 `kind` 的普通对象或 null-prototype 对象,并返回供当前 turn signal 使用的分离且冻结值。即使 Agent 处于 idle,字符串、额外字段或 symbol 字段、未知 kind、数组、class 实例、`Error` 和 `AbortSignal` 也会被同步拒绝。 + +被中断的 live turn 以粗粒度的持久化结果 `{ kind: 'aborted' }` 结束。终态事件记录 turn 发生了什么,运行时 signal 则标识谁请求了取消;回放不会重复保存 `user` 或 `parent`。未来若有审计需求,应使用独立的控制请求事件,让请求与最终结果保持为两项事实。持久化事件不包含 stack、signal、错误对象、自由文本取消原因或后端私有细节。 + +AgentLoop 为每个预期 turn 私有地拥有一个 `TurnCancellation`。它在通知 `agent/status = running` 前安装 holder,使其中唯一的 `AbortController` 持续覆盖 prompt 处理、prompt 组装、每个步骤、模型与工具执行、continuation、`agent/turn-stop`、`turn/end` 和持久化 flush,随后清除 holder。所有参与的方法、事件和请求值都会收到同一个显式 signal;下一 turn 会收到全新 signal。 + +对于 turn 被认领前取消的 queued work,驱动只保留一个不带 cause 的 pre-run marker。它会清除 `cancel()` 调用时已存在的 queued 和 steering work,但不会为未来 prompt 预设取消。若 `running` listener 同步取消旧工作并发送 replacement,驱动会丢弃已 aborted 的 holder,并为 replacement 创建全新 holder。同一 active holder 上的重复取消遵循 first-wins,后续调用仍可清除新进入队列的 pending work。 + +显式事件签名保留 positional 形态,并把 `signal` 放在 waterfall 最后一个参数 `next` 之前。Prompt 提交、请求配置、步骤结果处理、continuation 和终止停止加入已有的 pre-step、session prefix、模型生成、工具执行、审批以及 subagent 或 workflow 请求显式 signal seam。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`,因为该对象是显式请求值。Listener 可以配合该 signal 取消,但不得保留它来控制另一 turn。 + +`ctx.agentExecution` 仍只提供身份。环境中的 Agent 并不代表存活、当前 turn 或取消权限,`agentInterruptReasonOf(signal)` 也只读取其显式参数。并发 Agent 会同时隔离各自的 ALS 身份和 turn signal;子 Agent 会遮蔽父 Agent 身份,而父请求 signal 仍通过 subagent seam 传递。 + +Agent dispose 会在 active holder 上请求仅用于运行时的 `{ kind: 'disposed' }` 中断。若取消已经先成为 controller reason,该 reason 无法改写,因此终态分类会先检查生命周期状态:disposed 优先,之后受支持的 `user` 或 `parent` cause 形成粗粒度 aborted 结果,其他异常保留现有 error 路径。ACP 取消映射为 `user`;进程内 spawn 和 fork 的传播映射为 `parent`。远程 ACP subagent 保持现有 wire protocol。 + +取消仍然是协作式的。Loop 会在 await 边界前后检查中断,但不会用 `Promise.race` 放弃进程内 listener、adapter 或工具 Promise。忽略 signal 的工作必须真正结算,`whenIdle()`、handle dispose 和 scope teardown 才会报告静止状态。 + +## 验证 + +契约测试验证严格的运行时 cause 校验、冻结分离、默认与 first-wins 行为、粗粒度 Session JSON 往返、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。Loop 测试让协作式 listener 在 prompt 提交、system-prompt 组装、session prefix、pre-step、请求、模型 stream、步骤结果、工具执行、continuation 和终止停止处等待 signal;并断言同一 turn 使用一个 signal,不同 turn 使用全新 signal。 + +执行上下文测试断言所有 hook 仍只观察到 `{ agent }`,并发 Agent 保持独立的身份与 signal,嵌套子 Agent 创建只遮蔽身份。竞态测试覆盖 idle 取消、pre-run 取消、从 `running` listener 提交 replacement、重复取消以及 cancel 与 dispose 竞争下的静止状态。 + +## 考虑过的替代方案 + +**把 signal 存入 ALS。** ALS 会在整个驱动生命周期内跟随异步后代,而取消权限在一个 turn 结束时就已终止。泄漏的回调可能观察到陈旧 signal,或者迫使实现替换可变帧,因此身份帧保持 `{ agent }`,控制能力继续显式传递。 + +**持久化自由文本 reason。** 字符串允许拼写漂移、阻碍穷尽 switch,还会鼓励消费方解析展示文本。运行时使用封闭的 discriminated union,终态记录只需要稳定的 aborted 结果。 + +**在 `turn/end` 中持久化类型化调用方 cause。** 当前没有任何生产环境中的 replay、UI、ACP、telemetry 或 workflow 消费方区分 `user` 与 `parent`。把请求来源复制到终态结果会混淆两项事实,还会在没有消费方的情况下引入 Session 特有校验;未来的审计接口可以记录独立的取消请求事件。 + +**现在就定义推测性的 `superseded`、`timeout` 和 `shutdown` 变体。** 当前没有 Agent 取消生产方实现这些语义。`shutdown` 已经属于生命周期 dispose;timeout 或 supersession 只有在拥有明确归属策略和唯一终态含义时才应进入 union。 + +**公开 turn 或步骤 context 包装类型。** 现有 positional seam 已经标识 Agent、turn 和步骤。包装类型会加宽所有 API、重复归属,并诱导调用方把捕获的对象当成持久权限。 + +**在宽限期后放弃不协作的工作。** 同进程工作仍在运行时就返回 idle 会破坏 teardown 与资源归属保证。硬终止需要 worker 或进程隔离边界,不属于该控制 seam。 + +## 后果 + +取消拥有一个运行时归属方、每个 turn 一个 signal,以及一套类型化的运行时调用方词汇。Session 保留其消费方实际使用的粗粒度 `aborted` 结果,与运行时对象保持隔离,也不再需要取消专用的规范化逻辑。协作式取消覆盖每个异步 turn seam,包括第一个步骤之前和最后一个步骤之后的工作。 + +显式 signal 会给多个公开事件增加参数,并要求插件有意识地转发取消。这是有意设计:权限在调用边界可见,生命周期与 turn 匹配,陈旧的环境异步后代无法获得控制能力。不协作的进程内工作可能延迟取消,但所报告的静止状态仍然真实。 diff --git a/docs/rfc/implemented/simplification/2026-06-20-public-agent-stop-surface.md b/docs/rfc/implemented/simplification/2026-06-20-public-agent-stop-surface.md index 7ed7d10211..57550971d6 100644 --- a/docs/rfc/implemented/simplification/2026-06-20-public-agent-stop-surface.md +++ b/docs/rfc/implemented/simplification/2026-06-20-public-agent-stop-surface.md @@ -6,19 +6,19 @@ Status: implemented ## Problem -The public `Agent` handle exposed two overlapping ways to stop in-flight work: `abort(reason?)` and `cancel(reason?)`. `abort()` killed only the in-flight step and left queued work alone; `cancel()` clears queued and steering work, aborts the running step, and handles the pre-step race. In production, ACP uses `cancel()` for `session/cancel`, while lifecycle owners tear down agents through `AgentHandle.dispose()`. No production caller needed bare `abort()`. +The public `Agent` handle exposed two overlapping ways to stop in-flight work: step-only `abort()` and queue-aware `cancel()`. The former preserved queued input while the latter clears queued and steering work and aborts the active turn. In production, ACP uses `cancel()` for `session/cancel`, while lifecycle owners tear down agents through `AgentHandle.dispose()`. No production caller needs a bare step-only abort. -The `abort()`/`cancel()` distinction is real — `abort()` preserves queued prompts and steering while `cancel()` drops them — but no shipping code called the public `abort()` verb. The loop's own stop paths (`cancel()` and disposal) abort the current `AbortController` directly rather than routing through `Agent.abort()`. Most tests that called `abort()` interrupt an empty queue and switch to `cancel(reason)`; the steering re-delivery test that deliberately depends on queue preservation drives the in-flight `AbortController` directly, because `cancel()` would drop the queued steering it is trying to prove survives a step abort. The no-argument `abort()` default reason (`'aborted'`) is deleted with the verb rather than preserved by accident; `cancel()` keeps its own `'cancelled'` default. +The behavioral distinction is real, but no shipping code needs the narrower operation. AgentLoop instead owns one private cancellation holder for the whole turn. `cancel(cause?)` carries a typed `user` or `parent` cause, defaults to `user`, and drops pending input; disposal remains a separate lifecycle interruption. The complete ownership and propagation contract lives in the [explicit turn cancellation RFC](../architecture/2026-07-16-explicit-turn-cancellation.md). The extra surface area made the loop carry a public verb that is mostly a teardown internal: `abort()` had to be documented as distinct from queue-aware cancellation even though a UI cancellation almost always wants the broader operation. ## Decision -`cancel()` is the only public *stop* primitive on `Agent`. Lifecycle owners use `AgentHandle.dispose()` to stop and unregister an agent; non-owners use `cancel()` to abandon current and queued work. The implementation keeps a private abort controller, but it is not part of the plugin-facing `Agent` contract. +`cancel()` is the only public *stop* primitive on `Agent`. Lifecycle owners use `AgentHandle.dispose()` to stop and unregister an agent; non-owners use `cancel()` to abandon current and queued work. The implementation keeps a private turn cancellation holder, but it is not part of the plugin-facing `Agent` contract. `whenIdle()` is **retained** as the public quiescence-observation primitive (resolve once the agent settles out of `running`, resolve immediately when already idle, await the loop exit when disposed). It is not a stop verb; it is how a non-owner observes the stop *completing* without disposing the agent. Its live consumers are ACP and agent tests that await settlement through this public seam (`packages/ui/acp/tests`, `packages/core/agent-loop/tests`); the production ACP bridge owns its agents and tears them down through `AgentHandle.dispose()`, so `packages/ui/acp/src` itself has no `whenIdle()` call. -Public `abort()` is deleted, with the tests that exercised it as standalone API and the docs that described step-only abort as an embedding feature. Empty-queue abort tests migrated to `cancel(reason)` where they still prove cancellation behavior; tests whose subject is the loop's internal `AbortController` drive that controller directly via an in-package typed cast to the private field; tests that only pinned the removed no-arg `abort()` default went with the method. The disposer remains async and still waits for the loop to stop. +Public `abort()` is absent, and the disposer remains async and waits for the loop to stop. Tests exercise cancellation through the public typed cause and explicit signal seams rather than reaching into the holder. ## Alternatives considered diff --git a/examples/acp-agent/tests/snapshots/cancel/session.jsonl b/examples/acp-agent/tests/snapshots/cancel/session.jsonl index 7b2f5adff1..2d1d940b73 100644 --- a/examples/acp-agent/tests/snapshots/cancel/session.jsonl +++ b/examples/acp-agent/tests/snapshots/cancel/session.jsonl @@ -6,4 +6,4 @@ {"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} {"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"partial"}}} {"type":"step/end","seq":6,"time":0,"data":{"turn":1,"step":1}} -{"type":"turn/end","seq":7,"time":0,"data":{"turn":1,"reason":{"kind":"aborted","reason":"session/cancel"}}} +{"type":"turn/end","seq":7,"time":0,"data":{"turn":1,"reason":{"kind":"aborted"}}} diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index eb8a25d8b4..514ec43844 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -299,7 +299,7 @@ export const EVENT_API: readonly EventApiEntry[] = [ { name: 'agent/prompt-submit', mode: 'waterfall', - signature: '\'agent/prompt-submit\'(this: Scoped, agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise): Promise', + signature: '\'agent/prompt-submit\'(this: Scoped, agent: Agent, content: ContentBlock[], source: MessageSource, signal: AbortSignal, next: () => Promise): Promise', summary: 'Allow, rewrite, or block one drained prompt before it becomes a user message.', }, { @@ -311,7 +311,7 @@ export const EVENT_API: readonly EventApiEntry[] = [ { name: 'agent/request', mode: 'waterfall', - signature: '\'agent/request\'(this: Scoped, agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise): Promise', + signature: '\'agent/request\'(this: Scoped, agent: Agent, turn: number, step: number, config: LlmCallConfig, signal: AbortSignal, next: () => Promise): Promise', summary: 'Replace the frozen call configuration.', }, { @@ -335,19 +335,19 @@ export const EVENT_API: readonly EventApiEntry[] = [ { name: 'agent/step-result', mode: 'waterfall', - signature: '\'agent/step-result\'(this: Scoped, agent: Agent, turn: number, step: number, message: Message, next: () => Promise): Promise', + signature: '\'agent/step-result\'(this: Scoped, agent: Agent, turn: number, step: number, message: Message, signal: AbortSignal, next: () => Promise): Promise', summary: 'Waterfall: post-process the assembled assistant Message before tool dispatch (validation, content rewriting, …).', }, { name: 'agent/turn-continuation', mode: 'waterfall', - signature: '\'agent/turn-continuation\'(this: Scoped, agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise): Promise', + signature: '\'agent/turn-continuation\'(this: Scoped, agent: Agent, turn: number, defaultDecision: ContinuationDecision, signal: AbortSignal, next: () => Promise): Promise', summary: 'Override whether the turn continues.', }, { name: 'agent/turn-stop', mode: 'serial', - signature: '\'agent/turn-stop\'(this: Scoped, agent: Agent, turn: number): ContinuationStop | undefined', + signature: '\'agent/turn-stop\'(this: Scoped, agent: Agent, turn: number, signal: AbortSignal): Promise | ContinuationStop | undefined', summary: 'Monotonic terminal-stop checkpoint after continuation and steering are folded; a stop remains authoritative through turn close and flush: steering queued in that window is discarded, while ordinary sends survive.', }, { @@ -512,7 +512,11 @@ export const EVENT_API: readonly EventApiEntry[] = [ export const TYPE_API: readonly TypeApiEntry[] = [ { name: 'Agent', - declaration: 'export interface Agent {\n readonly id: AgentId;\n readonly options: AgentOptions;\n readonly session: Session;\n readonly status: AgentStatus;\n readonly ctx: Context;\n send(content: ContentBlock[], options?: SendOptions): void;\n steer(content: ContentBlock[], options?: SendOptions): void;\n inject(content: ContentBlock[], options?: SendOptions): void;\n cancel(reason?: string): void;\n whenIdle(): Promise;\n}', + declaration: 'export interface Agent {\n readonly id: AgentId;\n readonly options: AgentOptions;\n readonly session: Session;\n readonly status: AgentStatus;\n readonly ctx: Context;\n send(content: ContentBlock[], options?: SendOptions): void;\n steer(content: ContentBlock[], options?: SendOptions): void;\n inject(content: ContentBlock[], options?: SendOptions): void;\n cancel(cause?: AgentCancelCause): void;\n whenIdle(): Promise;\n}', + }, + { + name: 'AgentCancelCause', + declaration: 'export type AgentCancelCause = {\n readonly kind: \'user\';\n} | {\n readonly kind: \'parent\';\n};', }, { name: 'AgentExecution', @@ -572,7 +576,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'AssembleContext', - declaration: 'export interface AssembleContext {\n scope?: ScopeKey;\n}', + declaration: 'export interface AssembleContext {\n scope?: ScopeKey;\n signal?: AbortSignal;\n}', }, { name: 'AssembledSection', @@ -1064,7 +1068,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'TurnEndReasonMap', - declaration: 'export interface TurnEndReasonMap {\n completed: {\n kind: \'completed\';\n };\n aborted: {\n kind: \'aborted\';\n reason?: string;\n };\n error: {\n kind: \'error\';\n step: number;\n message: string;\n code?: string;\n };\n disposed: {\n kind: \'disposed\';\n };\n \'max-tokens\': {\n kind: \'max-tokens\';\n };\n rejected: {\n kind: \'rejected\';\n reason: string;\n };\n interrupted: {\n kind: \'interrupted\';\n };\n}', + declaration: 'export interface TurnEndReasonMap {\n completed: {\n kind: \'completed\';\n };\n aborted: {\n kind: \'aborted\';\n };\n error: {\n kind: \'error\';\n step: number;\n message: string;\n code?: string;\n };\n disposed: {\n kind: \'disposed\';\n };\n \'max-tokens\': {\n kind: \'max-tokens\';\n };\n rejected: {\n kind: \'rejected\';\n reason: string;\n };\n interrupted: {\n kind: \'interrupted\';\n };\n}', }, { name: 'TurnTrigger', diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md index c961969edc..73162d6995 100644 --- a/packages/core/agent-loop/README.md +++ b/packages/core/agent-loop/README.md @@ -48,11 +48,13 @@ Configured agents start automatically. `cwd` applies only to fresh sessions; `re ### Loop lifecycle (`loop.ts`) -The driver owns one agent for its lifetime and runs inside `ctx.agentExecution.run({ agent }, ...)`, so process-local asynchronous continuations can recover the initiating Agent. Creation, persistence load, and unpublished setup stay outside the child boundary; explicit Agent fields remain authoritative at service, worker, process, persistence, and wire boundaries. The [execution-context package](../agent-execution/README.md) owns propagation and detached-work rules. +The driver owns one agent for its lifetime and runs inside `ctx.agentExecution.run({ agent }, ...)`, so process-local asynchronous continuations can recover the initiating Agent. The ALS frame contains only `{ agent }`: creation, persistence load, and unpublished setup stay outside the child boundary, while turn, step, signal, and other control state remain explicit at every seam. The [execution-context package](../agent-execution/README.md) owns propagation and detached-work rules. The loop records turn, step, request, stream, and tool boundaries in the session log; live extension events coordinate policy around those durable facts. The [architecture turn flow](../../../docs/architecture.md#turn-flow) and generated [event catalog](../../../docs/cordis-catalog/events.md) are the authoritative sequence and signatures. -Plugin failure ends the current turn, not the loop. Cancellation clears pending work and aborts the current step without leaking to the next prompt. Terminal continuation stops remain authoritative through turn close and durability flush. +Plugin failure ends the current turn, not the loop. The loop creates one private turn cancellation holder before announcing `running`, passes its single signal through prompt handling, prompt assembly, every step, model and tool execution, continuation, terminal stop, turn end, and durability flush, then discards it. A replacement prompt accepted after cancellation receives a fresh holder, while all work in the cancelled turn observes the first typed runtime cause. The durable turn outcome is only `aborted`; disposal is a separate runtime interrupt and wins classification even if cancellation reached the signal first. + +Cancellation is cooperative: the loop checks for interruption between awaited boundaries but does not abandon an in-process listener, adapter, or tool Promise with `Promise.race`. `whenIdle()` and handle disposal therefore observe real quiescence. See the [explicit turn cancellation RFC](../../../docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.md). ### What belongs to plugins diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index 7194d6c7e8..b984e4bfa0 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -7,12 +7,13 @@ */ import type { Context } from 'cordis' -import { agentEvents } from '@deepseek-ai/dsh-agent' -import type { AgentId, AgentOptions, AgentStatus, SendOptions } from '@deepseek-ai/dsh-agent' +import { agentEvents, normalizeAgentCancelCause } from '@deepseek-ai/dsh-agent' +import type { AgentCancelCause, AgentId, AgentOptions, AgentStatus, SendOptions } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import { deepFreeze } from '@deepseek-ai/dsh-llm' import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm' import { snapshotJsonValue, type Session } from '@deepseek-ai/dsh-session' +import { DISPOSED_INTERRUPT_REASON, TurnCancellation } from './cancellation.ts' import { Inbox, type InboxMessage } from './inbox.ts' import { isTurnOpen, lastTurnNumber, runLoop } from './loop.ts' @@ -91,7 +92,7 @@ export function bindReactLoopAgentContext(agent: ReactLoopAgent, ctx: Context): /** * The concrete {@link Agent} implementation owned by the agent-loop plugin. * - * Owns the inbox (queued + steering FIFOs), the per-step AbortController, and + * Owns the inbox (queued + steering FIFOs), one turn cancellation holder, and * the loop driver. Everything observable happens through session events and * the agent/* event taxonomy — plugins never need this class. */ @@ -116,21 +117,18 @@ export class ReactLoopAgent implements Agent { } private _status: AgentStatus = 'idle' - private currentAbort: AbortController | undefined + /** Active turn owner, installed before the running notification and retained through flush. */ + private turnCancellation: TurnCancellation | undefined /** Whether runLoop has been installed into {@link done}. */ private driverStarted = false /** Whether registry publication began and status disposal is externally visible. */ private published = false /** - * Turn-scoped cancel marker, set by {@link cancel} and read/cleared by the - * driver loop (via the LoopHandle) at every point a turn could start or - * continue. Armed ONLY when there is something to cancel (a running turn, an - * in-flight step, or queued/steering work), so an idle no-op cancel cannot - * leave it set to wrongly drop a later prompt. + * Cause-less marker for queued work cancelled before the driver installs a + * turn owner. It never represents an active turn and cannot leak a cause into + * replacement work. */ - private cancelRequested = false - /** Pending cancellation reason, preserved even outside an active step signal. */ - private cancelReason = 'cancelled' + private preRunCancelled = false private disposed: Promise private resolveDisposed!: () => void /** Resolves when the driver loop has fully exited (tests/disposal). */ @@ -272,24 +270,18 @@ export class ReactLoopAgent implements Agent { } } - cancel(reason?: string): void { - // Arm only for current work; an idle marker would cancel the next prompt. - if (this._status === 'running' || this.currentAbort !== undefined || this.#inbox.hasQueued || this.#inbox.hasSteering) { - this.cancelRequested = true - // Capture the resolved reason for the marker-only windows (pre-step / - // continuation). The mid-step path reads it from abort.signal.reason - // below; the marker path reads it via the LoopHandle's cancelReason(). - this.cancelReason = reason ?? 'cancelled' - } + cancel(cause?: AgentCancelCause): void { + // Validate before the idle no-op so misuse fails consistently in every state. + const accepted = normalizeAgentCancelCause(cause ?? { kind: 'user' }) + const active = this.turnCancellation + if (active === undefined && !this.#inbox.hasQueued && !this.#inbox.hasSteering) return + if (active === undefined) this.preRunCancelled = true + else active.request(accepted) // Drop all pending queued + steering work (un-started prompts never run; the // cancelled turn's steering is not re-enqueued). Cleared directly even when // the loop is parked in waitForQueued — there is no turn to stop and nothing // left for the parked loop to run, so no wake is needed. this.#inbox.clear() - // Interrupt an in-flight step immediately (the running turn observes the - // abort and ends `aborted`). The marker covers the windows where no step is - // running (pre-step, continuation). - this.currentAbort?.abort(reason ?? 'cancelled') } /** @@ -330,13 +322,20 @@ export class ReactLoopAgent implements Agent { this.done = this.loopCtx.agentExecution.run({ agent: this }, () => runLoop(this.loopCtx, this, { inbox: this.#inbox, setStatus: (status) => { this.setStatus(status) }, - setAbort: controller => void (this.currentAbort = controller), + installTurnCancellation: () => { + const cancellation = new TurnCancellation() + this.turnCancellation = cancellation + return cancellation + }, + clearTurnCancellation: (cancellation) => { + /* v8 ignore else -- the internal driver clears only the exact holder returned by its latest install */ + if (this.turnCancellation === cancellation) this.turnCancellation = undefined + }, disposed: this.disposed, isDisposed: () => this._status === 'disposed', - isCancelled: () => this.cancelRequested, - cancelReason: () => this.cancelReason, - clearCancel: () => { this.cancelRequested = false }, - // Pre-step cancellation re-parks without emitting a status transition. + isPreRunCancelled: () => this.preRunCancelled, + clearPreRunCancel: () => { this.preRunCancelled = false }, + // Pre-run cancellation re-parks without emitting a status transition. settleIdle: () => { this.settleIdleWaiters() }, })) } @@ -354,7 +353,7 @@ export class ReactLoopAgent implements Agent { // internal state that must settle even if a listener throws below. Each // waiter chains `done`, so it resolves only once the loop actually exits. this.settleIdleWaiters() - this.currentAbort?.abort('disposed') + this.turnCancellation?.request(DISPOSED_INTERRUPT_REASON) // An unpublished rollback has no public status lifecycle to announce. // Once publication begins, disposed is part of the agent/status contract. if (this.published) { diff --git a/packages/core/agent-loop/src/cancellation.ts b/packages/core/agent-loop/src/cancellation.ts new file mode 100644 index 0000000000..e4054d8262 --- /dev/null +++ b/packages/core/agent-loop/src/cancellation.ts @@ -0,0 +1,31 @@ +/** Turn-scoped cancellation ownership for the concrete AgentLoop driver. @module dsh-agent-loop/cancellation */ + +import type { AgentCancelCause } from '@deepseek-ai/dsh-agent' + +/** Stable runtime-only reason used when lifecycle teardown interrupts a turn. */ +export const DISPOSED_INTERRUPT_REASON = Object.freeze({ kind: 'disposed' } as const) + +/** + * Owns the single controller shared by every asynchronous boundary of one turn. + * The first request wins because a later caller must not rewrite the cause + * observed by earlier listeners. + */ +export class TurnCancellation { + readonly #controller = new AbortController() + + /** The explicit signal passed through this turn's execution boundaries. */ + get signal(): AbortSignal { + return this.#controller.signal + } + + /** + * Abort the turn once. + * @param reason - a validated caller cause or lifecycle disposal marker. + * @returns whether this request established the signal reason. + */ + request(reason: AgentCancelCause | typeof DISPOSED_INTERRUPT_REASON): boolean { + if (this.signal.aborted) return false + this.#controller.abort(reason) + return true + } +} diff --git a/packages/core/agent-loop/src/inbox.ts b/packages/core/agent-loop/src/inbox.ts index abb588b919..29de25e723 100644 --- a/packages/core/agent-loop/src/inbox.ts +++ b/packages/core/agent-loop/src/inbox.ts @@ -29,7 +29,7 @@ export class Inbox { return this.queuedMessages.length > 0 } - /** True while steering messages are pending — read by `cancel()`'s arm gate and the loop's stop-override check. */ + /** True while steering messages are pending — read by cancellation and the loop's stop-override check. */ get hasSteering(): boolean { return this.steeringMessages.length > 0 } diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts index 15cc0aa410..9611a75823 100644 --- a/packages/core/agent-loop/src/loop.ts +++ b/packages/core/agent-loop/src/loop.ts @@ -6,9 +6,9 @@ */ import type { Context } from 'cordis' -import type { FinishReason, GenerateOptions, LlmCallConfig, Message } from '@deepseek-ai/dsh-llm' -import { BlockAssembler, HarnessError, deepFreeze } from '@deepseek-ai/dsh-llm' -import { agentEvents, assembleContextFor } from '@deepseek-ai/dsh-agent' +import type { FinishReason, GenerateOptions, LlmCallConfig, Message, TokenUsage } from '@deepseek-ai/dsh-llm' +import { assertNever, BlockAssembler, HarnessError, deepFreeze } from '@deepseek-ai/dsh-llm' +import { agentEvents, agentInterruptReasonOf, assembleContextFor } from '@deepseek-ai/dsh-agent' import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision } from '@deepseek-ai/dsh-agent' import { canonicalHeader } from '@deepseek-ai/dsh-session' import type { Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session' @@ -19,6 +19,7 @@ import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt' import type {} from '@deepseek-ai/dsh-tools' import type { ReactLoopAgent } from './agent.ts' import type { Inbox } from './inbox.ts' +import type { TurnCancellation } from './cancellation.ts' /** An Error with an optional machine-readable code (e.g., from LlmError or a throwing plugin). */ type CodedError = Error & { code?: string } @@ -68,21 +69,65 @@ function stepFinishReason(finish: FinishReason): TurnEndReason | undefined { } } +/** Internal control-flow sentinel; durable classification comes only from the turn signal. */ +const TURN_INTERRUPTED = new Error('turn interrupted') + +/** Stop at an explicit cooperative boundary without stringifying the runtime reason. */ +function interruptionCheckpoint(signal: AbortSignal): void { + if (signal.aborted) throw TURN_INTERRUPTED +} + +/** Classify a supported turn interruption, with lifecycle disposal taking precedence. */ +function interruptionTurnEndReason(handle: LoopHandle, signal: AbortSignal): TurnEndReason | undefined { + if (handle.isDisposed()) return { kind: 'disposed' } + const reason = agentInterruptReasonOf(signal) + if (reason === undefined) return undefined + switch (reason.kind) { + case 'user': + case 'parent': + return { kind: 'aborted' } + /* v8 ignore next 2 -- the private holder requests disposed only after lifecycle state flips, which returns above */ + case 'disposed': + return { kind: 'disposed' } + /* v8 ignore next 2 -- AgentInterruptReason is closed and the public helper filters unsupported reasons */ + default: + return assertNever(reason, 'AgentInterruptReason') + } +} + +/** Append the durable assembled assistant message when it carries content or usage. */ +function appendAssistantMessage( + session: Session, + turn: number, + step: number, + message: Message, + usage: TokenUsage | undefined, + chunkSeqs: number[], +): void { + if (message.content.length === 0 && usage === undefined) return + session.append( + 'assistant/message', + { turn, step, content: message.content, ...usage === undefined ? {} : { usage } }, + { surfaceOp: 'append', ...(chunkSeqs.length > 0 ? { sourceEventSeqs: chunkSeqs } : {}) }, + ) +} + /** Mutable agent controls supplied to the loop driver. */ export interface LoopHandle { /** Native-private agent inbox handed to the driver only at internal startup. */ readonly inbox: Inbox setStatus(status: 'idle' | 'running'): void - setAbort(controller: AbortController | undefined): void + /** Install a fresh active-turn owner before the running notification. */ + installTurnCancellation(): TurnCancellation + /** Clear only the exact owner whose turn and durability flush settled. */ + clearTurnCancellation(cancellation: TurnCancellation): void /** Resolves when the agent is disposed — unblocks the idle wait. */ disposed: Promise isDisposed(): boolean - /** Whether cancellation is pending for the current loop iteration. */ - isCancelled(): boolean - /** Resolved pending-cancellation reason; meaningful only while {@link isCancelled} is true. */ - cancelReason(): string - /** Clear the cancel marker (called once per iteration after the turn returns). */ - clearCancel(): void + /** Whether queued work was cancelled before an active turn owner existed. */ + isPreRunCancelled(): boolean + /** Clear the cause-less pre-run marker without affecting replacement work. */ + clearPreRunCancel(): void /** Settle idle waiters when pre-running cancellation skips a turn, without emitting `agent/status`. */ settleIdle(): void } @@ -92,7 +137,7 @@ export interface LoopHandle { * current turn without terminating the driver. * @param ctx - the plugin context the loop reaches events (agent/…, session/flush) and services (systemPrompt, llm, tools) through. * @param agent - the agent this invocation drives for its whole lifetime (its inbox, session, and options). - * @param handle - the bridge to the agent's mutable state: status/abort setters plus the disposal and cancel-marker reads. + * @param handle - the bridge to status, turn cancellation ownership, disposal, and pre-run cancellation state. */ export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopHandle): Promise { // Per-instance prefix and request-header state; conversation history remains in the session log. @@ -108,31 +153,38 @@ export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopH // Cancellation between wake and `running` skips only the cancelled work; // a replacement prompt still runs and owns the eventual idle transition. - if (handle.isCancelled()) { - handle.clearCancel() + if (handle.isPreRunCancelled()) { + handle.clearPreRunCancel() if (!handle.inbox.hasQueued) { handle.settleIdle() continue } } + let cancellation = handle.installTurnCancellation() handle.setStatus('running') - // A synchronous `running` listener can cancel before `runTurn`; balance the - // status only when no replacement prompt was queued by that listener. - if (handle.isCancelled()) { - handle.clearCancel() + if (handle.isDisposed()) { + handle.clearTurnCancellation(cancellation) + break + } + + // A synchronous running listener may cancel old work and enqueue a + // replacement. The replacement receives a fresh, non-aborted turn owner. + if (cancellation.signal.aborted) { + handle.clearTurnCancellation(cancellation) if (!handle.inbox.hasQueued) { handle.setStatus('idle') continue } + cancellation = handle.installTurnCancellation() } // Idle injection can add a turn, so derive the next number from the log. const turn = lastTurnNumber(session) + 1 let terminalStopped = false try { - terminalStopped = await runTurn(ctx, events, agent, handle, turn, transmission) + terminalStopped = await runTurn(ctx, events, agent, handle, turn, transmission, cancellation.signal) } catch (error: unknown) { // Pre-turn failure has no durable boundary to close; report it without appending outside a turn. const err = toError(error) @@ -140,11 +192,10 @@ export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopH try { events.emit('agent/error', turn, 0, err) } catch { /* contained: a throwing agent/error listener must not kill the driver */ } + } finally { + handle.clearTurnCancellation(cancellation) } - // Reset per iteration, including when a prompt arrives during the flush window. - handle.clearCancel() - // Late steering becomes queued input unless terminal policy stopped the turn. for (const message of handle.inbox.drainSteering()) { if (!terminalStopped) handle.inbox.enqueue(message) @@ -156,6 +207,7 @@ export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopH async function runTurn( ctx: Context, events: AgentEventDispatch, agent: ReactLoopAgent, handle: LoopHandle, turn: number, transmission: TransmissionLog, + signal: AbortSignal, ): Promise { const { session } = agent @@ -202,6 +254,7 @@ async function runTurn( // matter what throws below; the catch + closeTurn guarantee it. A pre-commit // veto leaves no turn/start in the log and therefore owes no turn/end. session.append('turn/start', { turn, trigger }) + interruptionCheckpoint(signal) // Each drained queued message runs the `agent/prompt-submit` waterfall before // it becomes a `user/message` — a hook can rewrite the prompt or block it. // Recorded INSIDE the turn (after turn/start) so every event is turn-enclosed; @@ -215,9 +268,10 @@ async function runTurn( let lastBlockReason = 'prompt blocked by hook' for (const message of queued) { const decision = await events.waterfall( - 'agent/prompt-submit', message.content, message.source, + 'agent/prompt-submit', message.content, message.source, signal, () => Promise.resolve({ kind: 'allow' }), ) + interruptionCheckpoint(signal) if (decision.kind === 'block') { lastBlockReason = decision.reason // Record the veto durably: `PromptDecision.reason` is the durable record @@ -253,53 +307,28 @@ async function runTurn( // the request. drainSteering(agent, handle.inbox, turn) - // The step's AbortController exists BEFORE any async pre-step work so a - // dispose() or cancel() — in a synchronous turn-start listener or an - // async listener whose effect fires before we block — always has an armed - // abort to cancel against. isDisposed below covers disposal, which does - // NOT set the cancel marker. Cleared on every exit path below. - const abort = new AbortController() - handle.setAbort(abort) - // Assemble once before pre-step so pressure checks and the request share the same prompt. - const assembly = await ctx.systemPrompt.assemble(assembleContextFor(agent)) + const assembly = await ctx.systemPrompt.assemble(assembleContextFor(agent, signal)) + interruptionCheckpoint(signal) const fullSystemPrompt = renderPrompt(assembly) - // Cancellation or disposal during assembly ends the turn before any step opens. - if (handle.isCancelled() || handle.isDisposed()) { - handle.setAbort(undefined) - reason = handle.isDisposed() ? { kind: 'disposed' } : { kind: 'aborted', reason: handle.cancelReason() } - break - } - // Compose the request-only prefix once per loop instance before pressure // checks. It precedes all derived history and is recorded only in the // request header, not as session history. if (transmission.sessionPrefix === undefined) { const emptyPrefix: Message[] = deepFreeze([]) const composed = await events.waterfall( - 'agent/session-prefix', emptyPrefix, abort.signal, + 'agent/session-prefix', emptyPrefix, signal, () => Promise.resolve(emptyPrefix), ) - // Never cache an interrupted composition; the next turn recomposes it. - if (handle.isCancelled() || handle.isDisposed()) { - handle.setAbort(undefined) - reason = handle.isDisposed() ? { kind: 'disposed' } : { kind: 'aborted', reason: handle.cancelReason() } - break - } + interruptionCheckpoint(signal) transmission.sessionPrefix = deepFreeze(structuredClone(composed)) } // Await surface mutations outside the step; pressure checks receive the pending prefix. - await events.serial('agent/pre-step', turn, step, fullSystemPrompt, transmission.sessionPrefix, abort.signal) - - // Interruption landing during the pre-step seam: do not open an empty step. - if (handle.isCancelled() || handle.isDisposed()) { - handle.setAbort(undefined) - reason = handle.isDisposed() ? { kind: 'disposed' } : { kind: 'aborted', reason: handle.cancelReason() } - break - } + await events.serial('agent/pre-step', turn, step, fullSystemPrompt, transmission.sessionPrefix, signal) + interruptionCheckpoint(signal) // Snapshot the exact log prefix before step/start: the reconstruction // boundary. Appends after this synchronous snapshot join the next request. @@ -310,26 +339,15 @@ async function runTurn( // pre-commit veto throws before this assignment; post-commit observers // are contained inside Session.append(). stepOpen = true - - // Cancel landing in the step-start window: a synchronous `session/event` - // step/start listener can cancel after the step is already open. Check - // AFTER the step/start append and before `runStep`: drop the step, end the - // turn accordingly. closeStep balances the already-appended step/start. - if (handle.isCancelled() || handle.isDisposed()) { - handle.setAbort(undefined) - reason = handle.isDisposed() ? { kind: 'disposed' } : { kind: 'aborted', reason: handle.cancelReason() } - closeStep() - break - } + // A synchronous step/start observer can cancel after the step opened. + interruptionCheckpoint(signal) let stepOutcome: { hadToolCalls: boolean; finish: FinishReason } | { error: Error } try { stepOutcome = await runStep( - ctx, events, agent, turn, step, assembly, fullSystemPrompt, boundaryMessages, transmission, abort.signal) + ctx, events, agent, turn, step, assembly, fullSystemPrompt, boundaryMessages, transmission, signal) } catch (error: unknown) { stepOutcome = { error: toError(error) } - } finally { - handle.setAbort(undefined) } if ('error' in stepOutcome) { @@ -338,14 +356,9 @@ async function runTurn( // starts a fresh turn instead of being silently consumed. closeStep() const { error } = stepOutcome - if (handle.isDisposed()) { - reason = { kind: 'disposed' } - } else if (abort.signal.aborted) { - /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */ - reason = { kind: 'aborted', reason: String(abort.signal.reason ?? 'aborted') } - } else { - failTurn(error) - } + const interruption = interruptionTurnEndReason(handle, signal) + if (interruption === undefined) failTurn(error) + else reason = interruption break } @@ -357,17 +370,20 @@ async function runTurn( const steered = drainSteering(agent, handle.inbox, turn) closeStep() + interruptionCheckpoint(signal) const defaultDecision: ContinuationDecision = { action: stepOutcome.hadToolCalls || steered ? 'continue' : 'stop' } let decision: ContinuationDecision try { decision = await events.waterfall( - 'agent/turn-continuation', turn, defaultDecision, + 'agent/turn-continuation', turn, defaultDecision, signal, () => Promise.resolve(defaultDecision), ) + interruptionCheckpoint(signal) } catch (error: unknown) { - // A broken continuation plugin ends the turn, not the loop. - failTurn(toError(error)) + const interruption = interruptionTurnEndReason(handle, signal) + if (interruption === undefined) failTurn(toError(error)) + else reason = interruption break } @@ -383,12 +399,13 @@ async function runTurn( // Terminal policy is monotonic and runs after ordinary continuation folding. let terminalStop = false try { - const stop = await events.serial('agent/turn-stop', turn) + const stop = await events.serial('agent/turn-stop', turn, signal) + interruptionCheckpoint(signal) terminalStop = stop !== undefined } catch (error: unknown) { - // A broken terminal policy is an ordinary continuation failure: fail - // this turn closed while leaving the driver alive for later turns. - failTurn(toError(error)) + const interruption = interruptionTurnEndReason(handle, signal) + if (interruption === undefined) failTurn(toError(error)) + else reason = interruption break } if (terminalStop) { @@ -398,12 +415,6 @@ async function runTurn( shouldContinue = false } - // The marker catches cancellation after the step controller was cleared. - if (handle.isCancelled()) { - reason = { kind: 'aborted', reason: handle.cancelReason() } - break - } - if (!shouldContinue || handle.isDisposed()) { /* v8 ignore next -- disposal during continuation-decision window is a narrow race; error-path disposal is covered elsewhere */ if (handle.isDisposed()) reason = { kind: 'disposed' } @@ -418,12 +429,9 @@ async function runTurn( const turnStartLogged = session.events.some(e => e.type === 'turn/start' && e.data.turn === turn) if (!turnStartLogged) throw error closeStep() - // Preserve an established disposal reason; otherwise report the failure. - if (handle.isDisposed() && !errorReported) { // eslint-disable-line @typescript-eslint/no-unnecessary-condition - reason = { kind: 'disposed' } - } else { - failTurn(toError(error)) - } + const interruption = interruptionTurnEndReason(handle, signal) + if (interruption === undefined) failTurn(toError(error)) + else reason = interruption closeTurn() } @@ -480,7 +488,8 @@ async function runStep( : { model: options.model ?? '' })) // Listener replacements are recorded in the request header before dispatch. - const config = await events.waterfall('agent/request', turn, step, seedConfig, () => Promise.resolve(seedConfig)) + const config = await events.waterfall('agent/request', turn, step, seedConfig, signal, () => Promise.resolve(seedConfig)) + interruptionCheckpoint(signal) if (!config.model) { throw new Error(`agent "${agent.id}" has no model: set AgentOptions.model or supply one via the agent/request waterfall`) } @@ -514,12 +523,12 @@ async function runStep( const assembler = new BlockAssembler() const chunkSeqs: number[] = [] for await (const chunk of ctx.llm.stream(request)) { - /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */ - if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted')) + interruptionCheckpoint(signal) const chunkEvent = session.append('assistant/chunk', { turn, step, chunk }) chunkSeqs.push(chunkEvent.seq) assembler.push(chunk) } + interruptionCheckpoint(signal) // Normalize failure finish chunks into the same path as thrown stream errors. const stepError = finishError(assembler.finish) @@ -527,39 +536,26 @@ async function runStep( if (assembler.finish.kind === 'max-tokens') { let message: Message = withoutToolCalls(assembler.message()) - message = withoutToolCalls(await events.waterfall('agent/step-result', turn, step, message, () => Promise.resolve(message))) + message = withoutToolCalls(await events.waterfall('agent/step-result', turn, step, message, signal, () => Promise.resolve(message))) + interruptionCheckpoint(signal) // Preserve usage even when max-token truncation produced no content. - if (message.content.length > 0 || assembler.usage) { - // The finish chunk guarantees non-empty provenance here. - session.append( - 'assistant/message', - { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) }, - { surfaceOp: 'append', sourceEventSeqs: chunkSeqs }, - ) - } + appendAssistantMessage(session, turn, step, message, assembler.usage, chunkSeqs) return { hadToolCalls: false, finish: assembler.finish } } // Record the post-waterfall message that tool dispatch uses. let message: Message = assembler.message() - message = await events.waterfall('agent/step-result', turn, step, message, () => Promise.resolve(message)) + message = await events.waterfall('agent/step-result', turn, step, message, signal, () => Promise.resolve(message)) + interruptionCheckpoint(signal) - // Empty messages exist only to carry usage; omit empty provenance. - if (message.content.length > 0 || assembler.usage) { - session.append( - 'assistant/message', - { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) }, - { surfaceOp: 'append', ...(chunkSeqs.length > 0 ? { sourceEventSeqs: chunkSeqs } : {}) }, - ) - } + appendAssistantMessage(session, turn, step, message, assembler.usage, chunkSeqs) // Tool execution stays sequential; recheck abort around each normalized result. const toolCalls = message.content.filter(block => block.type === 'tool-call') // Buffer context until all results are appended to preserve call/result adjacency. const pendingContext: HookContext[] = [] for (const call of toolCalls) { - /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */ - if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted')) + interruptionCheckpoint(signal) const callEvent = session.append('tool/call', { turn, step, callId: call.id, name: call.name, arguments: call.arguments }) let parsedArguments: unknown try { @@ -588,11 +584,7 @@ async function runStep( ...result.meta !== undefined ? { meta: result.meta } : {}, }, { surfaceOp: 'append', sourceEventSeqs: [callEvent.seq] }) if (result.additionalContext) pendingContext.push(result.additionalContext) - // The signal may flip while the tool is awaited. - /* v8 ignore start -- signal.reason default unreachable: cancel()/disposal always set it */ - // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition - if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted')) - /* v8 ignore stop */ + interruptionCheckpoint(signal) } // Append buffered context after the complete result batch. diff --git a/packages/core/agent-loop/tests/agent-execution.spec.ts b/packages/core/agent-loop/tests/agent-execution.spec.ts index 98cebcbc97..c33fec7432 100644 --- a/packages/core/agent-loop/tests/agent-execution.spec.ts +++ b/packages/core/agent-loop/tests/agent-execution.spec.ts @@ -146,6 +146,82 @@ describe('AgentLoop execution context', () => { await ctx.fiber.dispose() }) + it('keeps ALS identity minimal while one explicit signal spans each turn seam', async () => { + const adapter = new MockAdapter([ + toolCallResponse('observe-call', 'observe', {}), + textResponse('first done'), + textResponse('second done'), + ]) + const { ctx } = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('signal-owner'), { model: 'mock' }) + let signals: AbortSignal[] = [] + const capture = (signal: AbortSignal | undefined): void => { + if (signal === undefined) throw new Error('turn seam omitted its explicit signal') + const execution = ctx.agentExecution.require() + expect(Object.keys(execution)).toEqual(['agent']) + expect(execution.agent).toBe(agent) + signals.push(signal) + } + + ctx.on('system-prompt/assemble', async (_assembly, context, next) => { + if (context.agent === agent) capture(context.signal) + return next() + }) + ctx.on('agent/prompt-submit', async (subject, _content, _source, signal, next) => { + if (subject === agent) capture(signal) + return next() + }) + ctx.on('agent/session-prefix', async (subject, _prefix, signal, next) => { + if (subject === agent) capture(signal) + return next() + }) + ctx.on('agent/pre-step', (subject, _turn, _step, _system, _prefix, signal) => { + if (subject === agent) capture(signal) + }) + ctx.on('agent/request', async (subject, _turn, _step, _config, signal, next) => { + if (subject === agent) capture(signal) + return next() + }) + ctx.on('agent/step-result', async (subject, _turn, _step, _message, signal, next) => { + if (subject === agent) capture(signal) + return next() + }) + ctx.on('agent/turn-continuation', async (subject, _turn, _decision, signal, next) => { + if (subject === agent) capture(signal) + return next() + }) + ctx.on('agent/turn-stop', (subject, _turn, signal) => { + if (subject === agent) capture(signal) + }) + ctx.tools.register(defineTool({ + name: 'observe', + description: 'observe explicit turn state', + parameters: {}, + execute: async (_args, exec) => { + capture(exec.signal) + return [{ type: 'text', text: 'observed' }] + }, + })) + + const firstIdle = waitForIdle(ctx, agent) + send(agent, 'first') + await firstIdle + const firstSignal = signals[0] + expect(firstSignal).toBeDefined() + expect(new Set([...signals, ...adapter.requests.slice(0, 2).map(request => request.signal!)])).toEqual(new Set([firstSignal])) + + signals = [] + const secondIdle = waitForIdle(ctx, agent) + send(agent, 'second') + await secondIdle + const secondSignal = signals[0] + expect(secondSignal).toBeDefined() + expect(new Set([...signals, adapter.requests[2]!.signal!])).toEqual(new Set([secondSignal])) + expect(secondSignal).not.toBe(firstSignal) + expect(ctx.agentExecution.current()).toBeUndefined() + await ctx.fiber.dispose() + }) + it('keeps child setup under the parent boundary, switches for the child driver, then restores the parent', async () => { const adapter = new MockAdapter([ toolCallResponse('spawn', 'spawn-child', {}), diff --git a/packages/core/agent-loop/tests/agent.spec.ts b/packages/core/agent-loop/tests/agent.spec.ts index bcc31a6172..defb913d44 100644 --- a/packages/core/agent-loop/tests/agent.spec.ts +++ b/packages/core/agent-loop/tests/agent.spec.ts @@ -329,7 +329,7 @@ describe('ReactLoopAgent', () => { expect(settled).toBe(false) await waitForStatus(ctx, agent, 'running') - agent.cancel('done') + agent.cancel({ kind: 'user' }) await idle expect(settled).toBe(true) expect(agent.status).toBe('idle') diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts index 7568ba0765..0dbac6fce6 100644 --- a/packages/core/agent-loop/tests/cancel.spec.ts +++ b/packages/core/agent-loop/tests/cancel.spec.ts @@ -1,9 +1,8 @@ /** * Tests for the queue-aware `Agent.cancel()` primitive. `cancel()` is the broad verb — it - * clears queued + steering work, aborts an in-flight step, and drops a turn about to start — - * whereas a bare step abort (the loop's private `AbortController`) kills only the current step - * and leaves the queue intact. The suite covers every landing window plus marker - * reset and `whenIdle()` quiescence. + * clears queued + steering work, aborts the active turn, and drops work not yet claimed by the + * driver without leaking cancellation into a replacement prompt. The suite covers every landing + * window plus marker reset and `whenIdle()` quiescence. * @module dsh-agent-loop/tests/cancel */ @@ -12,11 +11,11 @@ import { Context } from 'cordis' import LlmService, { type Message } from '@deepseek-ai/dsh-llm' import SessionStore, { SessionId, TurnEndReason } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' -import ToolRegistry from '@deepseek-ai/dsh-tools' +import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools' import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent' import AgentExecutionProvider from '@deepseek-ai/dsh-agent-execution' import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' -import { MockAdapter, textResponse } from './mock-adapter.ts' +import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts' async function harness(adapter: MockAdapter) { const ctx = new Context() @@ -60,7 +59,7 @@ describe('Agent.cancel()', () => { // The loop is parked at the idle wait with nothing queued. A cancel here must // NOT arm the marker — otherwise the next legitimate prompt would be dropped. - agent.cancel('nothing to cancel') + agent.cancel({ kind: 'user' }) send(agent, 'real prompt') await waitForIdle(ctx, agent) @@ -78,7 +77,7 @@ describe('Agent.cancel()', () => { // send() queues synchronously (status still idle, loop microtask not yet // resumed). Cancel in that pre-step window: the queued turn must not run. send(agent, 'drop me') - agent.cancel('pre-step') + agent.cancel({ kind: 'user' }) // Give the loop a chance to wake and process the cancel. await new Promise(r => setTimeout(r, 30)) @@ -98,7 +97,7 @@ describe('Agent.cancel()', () => { // drops the turn before it runs; the skip path must settle it directly. send(agent, 'q') const idle = agent.whenIdle() - agent.cancel('pre-step') + agent.cancel({ kind: 'user' }) // Must resolve (not hang). A timeout makes the failure a clear test failure. await Promise.race([ @@ -119,13 +118,13 @@ describe('Agent.cancel()', () => { send(agent, 'go') await new Promise(r => setTimeout(r, 30)) expect(agent.status).toBe('running') - agent.cancel('mid-step') + agent.cancel({ kind: 'user' }) await waitForIdle(ctx, agent) - expect(reasons).toEqual([{ kind: 'aborted', reason: 'mid-step' }]) + expect(reasons).toEqual([{ kind: 'aborted' }]) }) - it('cancel() with no reason defaults to "cancelled" when aborting an in-flight step', async () => { + it('cancel() with no cause defaults to user when aborting an active turn', async () => { const adapter = new MockAdapter(['hang']) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) @@ -135,10 +134,10 @@ describe('Agent.cancel()', () => { send(agent, 'go') await new Promise(r => setTimeout(r, 30)) - agent.cancel() // no reason → default 'cancelled' + agent.cancel() await waitForIdle(ctx, agent) - expect(reasons).toEqual([{ kind: 'aborted', reason: 'cancelled' }]) + expect(reasons).toEqual([{ kind: 'aborted' }]) }) it('a prompt sent AFTER a cancelled turn settles runs normally (marker reset)', async () => { @@ -149,7 +148,7 @@ describe('Agent.cancel()', () => { // First turn hangs; cancel it mid-step. send(agent, 'first') await new Promise(r => setTimeout(r, 30)) - agent.cancel('cancel first') + agent.cancel({ kind: 'user' }) await waitForIdle(ctx, agent) // The marker must have been reset after the cancelled turn — a fresh prompt @@ -174,7 +173,7 @@ describe('Agent.cancel()', () => { let streamed = false ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true }) ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next) => { - agent.cancel('from prefix composition') + agent.cancel({ kind: 'user' }) return next() }) @@ -185,7 +184,7 @@ describe('Agent.cancel()', () => { await waitForIdle(ctx, agent) expect(streamed).toBe(false) - expect(reasons).toEqual([{ kind: 'aborted', reason: 'from prefix composition' }]) + expect(reasons).toEqual([{ kind: 'aborted' }]) }) it('disposal from inside the agent/session-prefix waterfall ends the turn disposed (prefix-composition window)', async () => { @@ -239,7 +238,7 @@ describe('Agent.cancel()', () => { ctx.on('agent/session-prefix', async (_agent, _prefix, _signal, next): Promise => { compositions += 1 if (compositions === 1) { - agent.cancel('mid-composition') + agent.cancel({ kind: 'user' }) return next() } return [opener, ...await next()] @@ -262,12 +261,11 @@ describe('Agent.cancel()', () => { const ctx = await harness(adapter) const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) - // A turn/start listener fires before a step controller exists, so the - // turn-scoped marker—not step abort—must drop the pending step. + // The turn holder is already installed when turn/start is appended. let streamed = false ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true }) const dispose = ctx.on('session/event', (session, event) => { - if (session === agent.session && event.type === 'turn/start') agent.cancel('from turn-start') + if (session === agent.session && event.type === 'turn/start') agent.cancel({ kind: 'user' }) }) const reasons: TurnEndReason[] = [] @@ -277,11 +275,9 @@ describe('Agent.cancel()', () => { await waitForIdle(ctx, agent) dispose() - // No step streamed (the model never ran), and the turn ended aborted with - // the CALLER's reason — the marker carries `cancel(reason)` through even - // though no AbortController observed it in this window. + // The turn closes as aborted after its single cancellation holder fires. expect(streamed).toBe(false) - expect(reasons).toEqual([{ kind: 'aborted', reason: 'from turn-start' }]) + expect(reasons).toEqual([{ kind: 'aborted' }]) }) it('cancel from a synchronous step/start session-event listener drops the step (post-step-start window)', async () => { @@ -296,7 +292,7 @@ describe('Agent.cancel()', () => { let streamed = false ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true }) const dispose = ctx.on('session/event', (session, event) => { - if (session === agent.session && event.type === 'step/start') agent.cancel('from step-start') + if (session === agent.session && event.type === 'step/start') agent.cancel({ kind: 'user' }) }) const reasons: TurnEndReason[] = [] @@ -309,7 +305,7 @@ describe('Agent.cancel()', () => { // No step streamed, the turn ended aborted with the caller's reason, and the // log is balanced (the open step was closed by the cancel branch). expect(streamed).toBe(false) - expect(reasons).toEqual([{ kind: 'aborted', reason: 'from step-start' }]) + expect(reasons).toEqual([{ kind: 'aborted' }]) const types = agent.session.events.map(e => e.type) expect(types.filter(t => t === 'step/start').length).toBe(types.filter(t => t === 'step/end').length) }) @@ -353,10 +349,8 @@ describe('Agent.cancel()', () => { }) it('cancel during the continuation window ends the turn aborted and runs no further step', async () => { - // A continuation-waterfall listener cancels DURING the continuation decision - // (the finished step's AbortController is already cleared), and votes to - // continue — but the turn-scoped marker checked right after must end the turn - // `aborted` and run NO second step. + // A continuation-waterfall listener cancels during the continuation decision + // and votes to continue, but the turn signal remains authoritative. const adapter = new MockAdapter([textResponse('one'), textResponse('two')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) @@ -369,11 +363,11 @@ describe('Agent.cancel()', () => { }) let continued = false - ctx.on('agent/turn-continuation', async (subject, _turn, _default, next) => { + ctx.on('agent/turn-continuation', async (subject, _turn, _default, _signal, next) => { if (subject === agent && !continued) { continued = true - agent.cancel('from continuation') - return { action: 'continue' as const } // vote to continue — the post-waterfall marker check must override + agent.cancel({ kind: 'user' }) + return { action: 'continue' as const } } return next() }) @@ -381,11 +375,9 @@ describe('Agent.cancel()', () => { send(agent, 'go') await waitForIdle(ctx, agent) - // Only ONE step ran (the second was cancelled in the continuation window), - // and the turn ended aborted with the CALLER's reason (carried by the - // marker, since the finished step's AbortController was already cleared). + // Only one step ran and the turn ended with the coarse aborted outcome. expect(steps).toBe(1) - expect(reasons).toEqual([{ kind: 'aborted', reason: 'from continuation' }]) + expect(reasons).toEqual([{ kind: 'aborted' }]) }) it('cancel from a synchronous agent/status(running) listener drops the turn (window 2)', async () => { @@ -398,7 +390,7 @@ describe('Agent.cancel()', () => { let streamed = false ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true }) const dispose = ctx.on('agent/status', (subject, status) => { - if (subject === agent && status === 'running') agent.cancel('from running listener') + if (subject === agent && status === 'running') agent.cancel({ kind: 'user' }) }) send(agent, 'go') @@ -411,6 +403,33 @@ describe('Agent.cancel()', () => { expect(agent.session.events.some(e => e.type === 'turn/start')).toBe(false) }) + it('disposal from a synchronous running listener stops before opening a turn', async () => { + const adapter = new MockAdapter([textResponse('should not stream')]) + const ctx = await harness(adapter) + const handle = await ctx.agents.create({ + agentId: AgentId('dispose-running-listener'), + sessionId: SessionId('dispose-running-listener-session'), + agentOptions: { model: 'mock' }, + }) + const { agent } = handle + let disposalDone: Promise | undefined + const disposalStarted = Promise.withResolvers() + ctx.on('agent/status', (subject, status) => { + if (subject === agent && status === 'running') { + disposalDone = handle.dispose() + disposalStarted.resolve(undefined) + } + }) + + agent.send([{ type: 'text', text: 'go' }]) + await disposalStarted.promise + await disposalDone + + expect(agent.status).toBe('disposed') + expect(agent.session.events.some(event => event.type === 'turn/start')).toBe(false) + expect(adapter.requests).toHaveLength(0) + }) + it('window 2: whenIdle() does NOT resolve early when a running listener cancels then queues replacement work', async () => { // Cancellation must not settle idle while replacement work remains queued. const adapter = new MockAdapter([textResponse('A reply'), textResponse('B reply')]) @@ -421,7 +440,7 @@ describe('Agent.cancel()', () => { const dispose = ctx.on('agent/status', (subject, status) => { if (subject !== agent || status !== 'running' || replaced) return replaced = true - agent.cancel('drop A') + agent.cancel({ kind: 'user' }) send(agent, 'B') }) @@ -446,7 +465,7 @@ describe('Agent.cancel()', () => { send(agent, 'A') // queues A (status still idle, loop microtask pending) const idle = agent.whenIdle() // registers a waiter (idle + hasQueued → no fast path) - agent.cancel('drop A') // arms marker, clears A + agent.cancel({ kind: 'user' }) // arms marker, clears A send(agent, 'B') // B races in before the loop resumes // whenIdle() must resolve only after B's turn fully ran — by which point B's user message @@ -469,7 +488,7 @@ describe('Agent.cancel()', () => { // Steer (joins the running turn's steering FIFO), then cancel: the steering // must be dropped, NOT re-enqueued as a new queued turn. agent.steer([{ type: 'text', text: 'steer text' }]) - agent.cancel('cancel with steering') + agent.cancel({ kind: 'user' }) await waitForIdle(ctx, agent) // After the cancelled turn settles, the agent is idle with NO follow-up turn @@ -485,4 +504,169 @@ describe('Agent.cancel()', () => { .flatMap(b => b.type === 'text' ? [b.text] : []) expect(flat).not.toContain('steer text') }) + + it('keeps the first typed cause for an active turn and detaches the runtime reason', async () => { + const adapter = new MockAdapter(['hang']) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('typed-first-wins'), { model: 'mock' }) + const supplied: { kind: 'parent' | 'user' } = { kind: 'parent' } + + send(agent, 'go') + await new Promise(resolve => setTimeout(resolve, 30)) + agent.cancel(supplied) + supplied.kind = 'user' + agent.cancel({ kind: 'user' }) + await waitForIdle(ctx, agent) + + const runtimeReason: unknown = adapter.requests[0]?.signal?.reason + expect(runtimeReason).toEqual({ kind: 'parent' }) + expect(runtimeReason).not.toBe(supplied) + expect(Object.isFrozen(runtimeReason)).toBe(true) + const turnEnd = agent.session.events.findLast(event => event.type === 'turn/end') + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' }) + }) + + it('rejects invalid causes synchronously while idle and running', async () => { + class Cause { + readonly kind = 'user' + } + const adapter = new MockAdapter(['hang']) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('invalid-cause'), { model: 'mock' }) + const controller = new AbortController() + const invalid: unknown[] = [ + 'user', + { kind: 'timeout' }, + { kind: 'user', detail: 'extra' }, + new Error('cancelled'), + controller.signal, + new Cause(), + ] + for (const value of invalid) expect(() => { agent.cancel(value as never) }).toThrow(TypeError) + + send(agent, 'go') + await new Promise(resolve => setTimeout(resolve, 30)) + for (const value of invalid) expect(() => { agent.cancel(value as never) }).toThrow(TypeError) + expect(agent.status).toBe('running') + agent.cancel() + await waitForIdle(ctx, agent) + }) + + it('records disposed when lifecycle teardown races an already-requested cancel', async () => { + const adapter = new MockAdapter(['hang']) + const ctx = await harness(adapter) + const handle = await ctx.agents.create({ + agentId: AgentId('cancel-dispose-race'), + sessionId: SessionId('cancel-dispose-race-session'), + agentOptions: { model: 'mock' }, + }) + const agent = handle.agent + + agent.send([{ type: 'text', text: 'go' }]) + await new Promise(resolve => setTimeout(resolve, 30)) + agent.cancel({ kind: 'user' }) + await handle.dispose() + + const turnEnd = agent.session.events.findLast(event => event.type === 'turn/end') + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'disposed' }) + }) + + it.each([ + 'prompt-submit', + 'system-prompt', + 'session-prefix', + 'pre-step', + 'request', + 'step-result', + 'turn-continuation', + 'turn-stop', + 'tool', + ] as const)('lets a cooperative %s boundary settle from the explicit turn signal', async (stage) => { + const adapter = new MockAdapter(stage === 'tool' + ? [toolCallResponse('blocked-tool', 'blocked', {})] + : [textResponse('done')]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId(`cooperative-${stage}`), { model: 'mock' }) + const started = Promise.withResolvers() + const blockUntilAbort = async (signal: AbortSignal): Promise => { + started.resolve(undefined) + if (signal.aborted) return + await new Promise((resolve) => { + signal.addEventListener('abort', () => { resolve() }, { once: true }) + }) + } + + switch (stage) { + case 'prompt-submit': + ctx.on('agent/prompt-submit', async (subject, _content, _source, signal, next) => { + if (subject === agent) await blockUntilAbort(signal) + return next() + }) + break + case 'system-prompt': + ctx.on('system-prompt/assemble', async (_assembly, context, next) => { + if (context.agent === agent) { + if (context.signal === undefined) throw new Error('turn assembly omitted its signal') + await blockUntilAbort(context.signal) + } + return next() + }) + break + case 'session-prefix': + ctx.on('agent/session-prefix', async (subject, _prefix, signal, next) => { + if (subject === agent) await blockUntilAbort(signal) + return next() + }) + break + case 'pre-step': + ctx.on('agent/pre-step', async (subject, _turn, _step, _system, _prefix, signal) => { + if (subject === agent) await blockUntilAbort(signal) + }) + break + case 'request': + ctx.on('agent/request', async (subject, _turn, _step, _config, signal, next) => { + if (subject === agent) await blockUntilAbort(signal) + return next() + }) + break + case 'step-result': + ctx.on('agent/step-result', async (subject, _turn, _step, _message, signal, next) => { + if (subject === agent) await blockUntilAbort(signal) + return next() + }) + break + case 'turn-continuation': + ctx.on('agent/turn-continuation', async (subject, _turn, _decision, signal, next) => { + if (subject === agent) await blockUntilAbort(signal) + return next() + }) + break + case 'turn-stop': + ctx.on('agent/turn-stop', async (subject, _turn, signal) => { + if (subject === agent) await blockUntilAbort(signal) + }) + break + case 'tool': + ctx.tools.register(defineTool({ + name: 'blocked', + description: 'wait for cancellation', + parameters: {}, + execute: async (_args, exec) => { + if (exec.signal === undefined) throw new Error('tool execution omitted its signal') + await blockUntilAbort(exec.signal) + return [{ type: 'text', text: 'cancelled' }] + }, + })) + break + } + + send(agent, 'go') + await started.promise + const idle = waitForIdle(ctx, agent) + agent.cancel({ kind: 'user' }) + await idle + const turnEnd = agent.session.events.findLast(event => event.type === 'turn/end') + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' }) + await ctx.fiber.dispose() + }) }) diff --git a/packages/core/agent-loop/tests/contract-regressions.spec.ts b/packages/core/agent-loop/tests/contract-regressions.spec.ts index 70528a7b0b..bd959e870d 100644 --- a/packages/core/agent-loop/tests/contract-regressions.spec.ts +++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts @@ -59,7 +59,7 @@ describe('session log records what agent/step-result actually produced', () => { // Plugin rewrites the message: replaces the text AND adds a tool call. let rewritten = false - ctx.on('agent/step-result', async (_agent, _turn, _step, _message, next) => { + ctx.on('agent/step-result', async (_agent, _turn, _step, _message, _signal, next) => { if (rewritten) return next() rewritten = true return { @@ -92,7 +92,7 @@ describe('session log records what agent/step-result actually produced', () => { }) describe('abort during tool execution ends the turn', () => { - it('aborting the in-flight step inside a tool prevents both remaining tools and the next model step', async () => { + it('cancelling the active turn inside a tool prevents both remaining tools and the next model step', async () => { const adapter = new MockAdapter([ // model asks for two tool calls in one step [ @@ -113,11 +113,7 @@ describe('abort during tool execution ends the turn', () => { parameters: {}, async execute() { executed.push('aborter') - // Fire the in-flight step's AbortController directly (the loop registers - // it on the agent). This is the bare step-abort path — distinct from - // cancel(), which would also clear the inbox; here the subject is the - // loop's response to its running step being aborted mid-tool. - ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('user interrupt') + agent.cancel({ kind: 'user' }) return [{ type: 'text', text: 'done' }] }, })) @@ -139,7 +135,7 @@ describe('abort during tool execution ends the turn', () => { expect(executed).toEqual(['aborter']) // second tool never ran expect(adapter.requests).toHaveLength(1) // no follow-up model call - expect(reasons).toEqual([{ kind: 'aborted', reason: 'user interrupt' }]) + expect(reasons).toEqual([{ kind: 'aborted' }]) }) }) @@ -153,7 +149,7 @@ describe('steering from late extension points is never stranded', () => { const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) let steeredOnce = false - ctx.on('agent/turn-continuation', async (_agent, _turn, _decision, next) => { + ctx.on('agent/turn-continuation', async (_agent, _turn, _decision, _signal, next) => { if (!steeredOnce) { steeredOnce = true agent.steer([{ type: 'text', text: 'one more thing' }]) @@ -227,25 +223,19 @@ describe('steering from late extension points is never stranded', () => { expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('too late for this turn') }) - it('steering queued during an aborted step is re-delivered, not silently consumed', async () => { - const adapter = new MockAdapter(['hang', textResponse('recovered')]) + it('steering queued before turn cancellation is discarded with the cancelled work', async () => { + const adapter = new MockAdapter(['hang']) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) send(agent, 'go') await new Promise(r => setTimeout(r, 30)) agent.steer([{ type: 'text', text: 'redirect' }]) - // Abort ONLY the in-flight step, via its AbortController directly — NOT - // cancel(), which clears the inbox and would drop the queued steering this - // test proves survives a step abort. There is no public step-only abort - // verb (cancel() is the only public stop primitive), so reach the private - // controller the loop registered. - ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('user interrupt') + agent.cancel({ kind: 'user' }) await waitForIdle(ctx, agent) - // a new turn ran with the steering content delivered as a message - expect(adapter.requests).toHaveLength(2) - expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('redirect') + expect(adapter.requests).toHaveLength(1) + expect(JSON.stringify(agent.session.events)).not.toContain('redirect') }) }) @@ -383,7 +373,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => { const ctx = await harness(adapter) const agent = ctx.agentLoop.create(AgentId('a1'), {}) // no model — router plugin decides - ctx.on('agent/request', async (_agent, _turn, _step, config, _next) => { + ctx.on('agent/request', async (_agent, _turn, _step, config, _signal, _next) => { return { ...config, model: 'mock' } }) @@ -843,7 +833,7 @@ describe('turn and step boundary recovery', () => { it('disposal during a running turn ends the turn with reason disposed (balanced)', async () => { // The 'hang' adapter blocks in stream() until the signal aborts; disposing - // the agent's fiber mid-turn aborts the in-flight step. The turn must close + // the agent's fiber mid-turn aborts the active turn. The turn must close // balanced with reason disposed (no error event for a disposal). const adapter = new MockAdapter(['hang']) const ctx = await balancedHarness(adapter) @@ -1085,7 +1075,7 @@ describe('surface: assistant/message omits sourceEventSeqs when no chunks stream await ctx.plugin(Invariants) const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) - ctx.on('agent/step-result', async (_agent, _turn, _step, _message, _next) => ({ + ctx.on('agent/step-result', async (_agent, _turn, _step, _message, _signal, _next) => ({ role: 'assistant' as const, content: [{ type: 'text' as const, text: 'injected' }], })) @@ -1190,7 +1180,7 @@ describe('disposal and cancellation during pre-step assembly', () => { send(agent, 'go') await new Promise(r => setTimeout(r, 50)) - agent.cancel('user cancelled during assembly') + agent.cancel({ kind: 'user' }) releaseAssemble() await waitForIdle(ctx, agent) @@ -1202,15 +1192,12 @@ describe('disposal and cancellation during pre-step assembly', () => { expect(e.filter(x => x.type === 'turn/start')).toHaveLength(1) expect(e.filter(x => x.type === 'turn/end')).toHaveLength(1) const turnEnd = e.findLast(x => x.type === 'turn/end') - expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ - kind: 'aborted', - reason: 'user cancelled during assembly', - }) + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' }) expect(e.some(x => x.type === 'step/start')).toBe(false) expect(e.some(x => x.type === 'assistant/chunk')).toBe(false) expect(e.some(x => x.type === 'assistant/message')).toBe(false) expect(adapter.requests).toHaveLength(0) - expect(reasons).toEqual([{ kind: 'aborted', reason: 'user cancelled during assembly' }]) + expect(reasons).toEqual([{ kind: 'aborted' }]) }) it('disposal during agent/pre-step seam ends the turn disposed', { timeout: 15000 }, async () => { @@ -1297,7 +1284,7 @@ describe('disposal and cancellation during pre-step assembly', () => { send(agent, 'go') await new Promise(r => setTimeout(r, 30)) - agent.cancel('user cancelled') + agent.cancel({ kind: 'user' }) releasePreStep() await waitForIdle(ctx, agent) @@ -1308,10 +1295,10 @@ describe('disposal and cancellation during pre-step assembly', () => { expect(e.filter(x => x.type === 'turn/start')).toHaveLength(1) expect(e.filter(x => x.type === 'turn/end')).toHaveLength(1) const turnEnd = e.findLast(x => x.type === 'turn/end') - expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted', reason: 'user cancelled' }) + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' }) expect(e.some(x => x.type === 'step/start')).toBe(false) expect(e.some(x => x.type === 'assistant/chunk')).toBe(false) - expect(reasons).toEqual([{ kind: 'aborted', reason: 'user cancelled' }]) + expect(reasons).toEqual([{ kind: 'aborted' }]) }) it('disposal during assembly does not leak an LLM call or append assistant/chunk', { timeout: 15000 }, async () => { diff --git a/packages/core/agent-loop/tests/coverage-edges.spec.ts b/packages/core/agent-loop/tests/coverage-edges.spec.ts index 8c0884d0fa..a118d3a24e 100644 --- a/packages/core/agent-loop/tests/coverage-edges.spec.ts +++ b/packages/core/agent-loop/tests/coverage-edges.spec.ts @@ -157,7 +157,7 @@ describe('toError normalization', () => { const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) let threwOnce = false - ctx.on('agent/request', async (_agent, _turn, _step, _options, _next) => { + ctx.on('agent/request', async (_agent, _turn, _step, _options, _signal, _next) => { if (!threwOnce) { threwOnce = true throw { code: 500 } // non-Error throw, goes through runStep catch @@ -185,7 +185,7 @@ describe('coded error data emission', () => { const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) let threwOnce = false - ctx.on('agent/request', async (_agent, _turn, _step, _options, next) => { + ctx.on('agent/request', async (_agent, _turn, _step, _options, _signal, next) => { if (!threwOnce) { threwOnce = true throw new LlmError('server overloaded', 'RATE_LIMIT') diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts index 0c8f52c6c4..9aa3e7dcbf 100644 --- a/packages/core/agent-loop/tests/interception.spec.ts +++ b/packages/core/agent-loop/tests/interception.spec.ts @@ -62,7 +62,7 @@ describe('agent/prompt-submit', () => { const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) const seen: string[] = [] - ctx.on('agent/prompt-submit', async (_agent, content, _source, next) => { + ctx.on('agent/prompt-submit', async (_agent, content, _source, _signal, next) => { seen.push(content.map(b => (b.type === 'text' ? b.text : '')).join('')) return next() }) @@ -191,7 +191,7 @@ describe('agent/prompt-submit', () => { const ctx = await harness(adapter) const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) - ctx.on('agent/prompt-submit', async (_agent, content, _source, next): Promise => { + ctx.on('agent/prompt-submit', async (_agent, content, _source, _signal, next): Promise => { const text = content.map(b => (b.type === 'text' ? b.text : '')).join('') return text === 'secret' ? { kind: 'block', reason: 'policy: no secrets' } : next() }) @@ -498,7 +498,7 @@ describe('agent/turn-continuation (ContinuationDecision)', () => { const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) let forced = false - ctx.on('agent/turn-continuation', async (_agent, _turn, _default, next): Promise => { + ctx.on('agent/turn-continuation', async (_agent, _turn, _default, _signal, next): Promise => { if (!forced) { forced = true return { action: 'continue', reason: { content: [{ type: 'text', text: 'keep going on the goal' }], source: { kind: 'plugin', plugin: 'goal' } } } @@ -626,7 +626,7 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se ) }) // 2. PromptSubmit: block a forbidden prompt, annotate the rest. - ctx.on('agent/prompt-submit', async (_agent, content, _source, next): Promise => { + ctx.on('agent/prompt-submit', async (_agent, content, _source, _signal, next): Promise => { const text = content.map(b => (b.type === 'text' ? b.text : '')).join('') if (text.includes('rm -rf')) return { kind: 'block', reason: 'destructive prompt blocked' } return next() diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts index 79f9755220..c3695f2611 100644 --- a/packages/core/agent-loop/tests/loop.spec.ts +++ b/packages/core/agent-loop/tests/loop.spec.ts @@ -228,7 +228,7 @@ describe('agent loop', () => { assembly.variables['model'] = 'mock' return next() }) - ctx.on('agent/request', async (_agent, _turn, _step, config, _next) => { + ctx.on('agent/request', async (_agent, _turn, _step, config, _signal, _next) => { return { ...config, model: 'mock' } }) const agent = ctx.agentLoop.create(AgentId('a-late-model'), {}) @@ -429,7 +429,7 @@ describe('agent loop', () => { let steps = 0 ctx.on('session/event', (_session, event) => { if (event.type === 'step/end') steps++ }) - ctx.on('agent/turn-continuation', async (_agent, _turn, _defaultDecision, next) => { + ctx.on('agent/turn-continuation', async (_agent, _turn, _defaultDecision, _signal, next) => { if (steps < 3) return { action: 'continue' as const } return next() }) @@ -469,7 +469,7 @@ describe('agent loop', () => { ctx.llm.registerAdapter(['other-model'], adapter) const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) - ctx.on('agent/request', async (_agent, _turn, _step, config, _next) => { + ctx.on('agent/request', async (_agent, _turn, _step, config, _signal, _next) => { // The seed is frozen — config is not a mutable per-call knob; a switch // is proposed by returning a replacement, and the loop logs it. expect(Object.isFrozen(config)).toBe(true) @@ -601,10 +601,10 @@ describe('agent loop', () => { // wait until the stream is hanging, then cancel await new Promise(r => setTimeout(r, 30)) expect(agent.status).toBe('running') - agent.cancel('user interrupt') + agent.cancel({ kind: 'user' }) await waitForIdle(ctx, agent) - expect(reasons).toEqual([{ kind: 'aborted', reason: 'user interrupt' }]) + expect(reasons).toEqual([{ kind: 'aborted' }]) }) it('surfaces max-tokens as the turn-end reason when the last step is cut off', async () => { @@ -641,7 +641,7 @@ describe('agent loop', () => { ctx.on('session/event', (_session, event) => { if (event.type === 'step/end') steps++ }) // Force exactly one continuation (step 1 → step 2), then defer to default // (step 2 is a plain stop with no tool calls → stops). - ctx.on('agent/turn-continuation', async (_agent, _turn, _defaultDecision, next) => { + ctx.on('agent/turn-continuation', async (_agent, _turn, _defaultDecision, _signal, next) => { if (steps < 2) return { action: 'continue' as const } return next() }) @@ -781,7 +781,7 @@ describe('agent loop', () => { ]]) const ctx = await harness(adapter) let stepResults = 0 - ctx.on('agent/step-result', async (_agent, _turn, _step, message, next) => { + ctx.on('agent/step-result', async (_agent, _turn, _step, message, _signal, next) => { stepResults += 1 expect(message.content).toEqual([{ type: 'text', text: 'partial text' }]) return next() diff --git a/packages/core/agent-loop/tests/request-reconstruction.spec.ts b/packages/core/agent-loop/tests/request-reconstruction.spec.ts index 58c1017e81..ca56216c97 100644 --- a/packages/core/agent-loop/tests/request-reconstruction.spec.ts +++ b/packages/core/agent-loop/tests/request-reconstruction.spec.ts @@ -168,7 +168,7 @@ describe('request stability across the loop', () => { const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) let injected = false - ctx.on('agent/request', async (_agent, _turn, _step, _config, next) => { + ctx.on('agent/request', async (_agent, _turn, _step, _config, _signal, next) => { if (!injected) { injected = true agent.inject([{ type: 'text', text: '[late context]' }], { source: { kind: 'plugin', plugin: 'test' } }) @@ -245,7 +245,7 @@ describe('request stability across the loop', () => { const ctx = await harness(adapter) const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' }) - ctx.on('agent/request', async (_agent, _turn, _step, _config, next) => { + ctx.on('agent/request', async (_agent, _turn, _step, _config, _signal, next) => { const config = await next() // next() resolves the SAME frozen seed — in-place shaping after // delegation is unrepresentable, so a "mutate what next() returned" @@ -282,7 +282,7 @@ describe('request stability across the loop', () => { send(agent, 'go') await waitForIdle(ctx, agent) ctx.systemPrompt.section({ name: 'extra', order: 2, text: 'now with guidance' }) - ctx.on('agent/request', async (_agent, _turn, _step, config, _next) => ({ ...config, temperature: 0.5, maxTokens: 99, stop: [''] })) + ctx.on('agent/request', async (_agent, _turn, _step, config, _signal, _next) => ({ ...config, temperature: 0.5, maxTokens: 99, stop: [''] })) send(agent, 'again') await waitForIdle(ctx, agent) diff --git a/packages/core/agent-loop/tests/resume.spec.ts b/packages/core/agent-loop/tests/resume.spec.ts index 4b90453909..5530e909b8 100644 --- a/packages/core/agent-loop/tests/resume.spec.ts +++ b/packages/core/agent-loop/tests/resume.spec.ts @@ -198,7 +198,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => { order.push('agent/created') }) ctx.on('agent/session-start', (agent) => { - expect(() => { agent.cancel('now live') }).not.toThrow() + expect(() => { agent.cancel({ kind: 'user' }) }).not.toThrow() order.push('agent/session-start') }) diff --git a/packages/core/agent-loop/tests/turn-stop.spec.ts b/packages/core/agent-loop/tests/turn-stop.spec.ts index 944c6fd265..6b1117ebe4 100644 --- a/packages/core/agent-loop/tests/turn-stop.spec.ts +++ b/packages/core/agent-loop/tests/turn-stop.spec.ts @@ -51,7 +51,7 @@ describe('agent/turn-stop', () => { agent.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' })) let steered = false - ctx.on('agent/turn-continuation', async (subject, _turn, _default, next) => { + ctx.on('agent/turn-continuation', async (subject, _turn, _default, _signal, next) => { const downstream = await next() if (subject === agent && !steered) { steered = true diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md index 5639f30daf..bdbd6c6a11 100644 --- a/packages/core/agent/README.md +++ b/packages/core/agent/README.md @@ -33,6 +33,8 @@ The loop plugin registers `AgentFactory`, keeping consumers independent of its c Most interception points are cooperative waterfalls returning seam-specific decisions. `agent/pre-step` is a serial surface-mutation checkpoint, while `agent/turn-stop` is the terminal serial fold: it runs after ordinary continuation and steering folding, and a returned stop remains in force through turn close and flush so later steering cannot create an extra step or turn. Ordinary queued prompts remain intact. The full rationale is in the [agent-scope runtime-design RFC](../../../docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#three-execution-boundaries-are-deliberately-one-way). +Every asynchronous turn seam receives the same explicit `AbortSignal` for that turn. Listeners may cooperate with cancellation but must not retain the signal to control another turn; ambient `ctx.agentExecution` identity carries no liveness or cancellation authority. The signal and typed cancellation contract are defined by the [explicit turn cancellation RFC](../../../docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.md). + Turn and step boundaries and the model token stream are durable `session/event` facts rather than mirrored `agent/*` notifications. Consumers read `turn/*`, `step/*`, and `assistant/chunk` from the session feed; tool policy and outcome observation belong to the complete pipeline documented by [`dsh-tools`](../tools/README.md). ### Agent interface (`types.ts`) @@ -42,7 +44,7 @@ The handle every plugin programs against: - `agent.send(content, options?)` — queue a message; starts a turn when idle. Content and resolved source become one detached, deeply frozen lossless-JSON record before `agent/queued` and enqueue; invalid data throws synchronously, and caller or notification-listener in-place mutation cannot change the log or model input (`agent/prompt-submit` still rewrites by returning replacement content). - `agent.steer(content, options?)` — steer a running turn (inject between steps); uses the same owned acceptance boundary and behaves like `send` when idle - `agent.inject(content, options?)` — inject in-session context (context/message event); the next request sees it. Does not run the model. While a turn is open it joins that turn; while idle it is wrapped in a one-shot `injection` turn so every event stays turn-enclosed ([the turn-enclosure invariant](../../../docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)) -- `agent.cancel(reason?)` — cancel ALL pending work: clears the queued + steering FIFOs, aborts the in-flight step, and drops a turn about to start (the pre-step window) so a queued-but-not-started prompt never runs. A UI/ACP `session/cancel` maps to this. The single public stop primitive. Idle with nothing pending → a safe no-op. +- `agent.cancel(cause?)` — cancel ALL pending work: clears the queued + steering FIFOs, aborts the active turn, and drops queued work not yet claimed by the driver. `AgentCancelCause` is the runtime-only `{ kind: 'user' } | { kind: 'parent' }`; omission means `user`, the first cause wins for an active turn, and ACP `session/cancel` maps to `user`. `normalizeAgentCancelCause()` provides the same strict detached-value boundary used by the concrete loop: validation is synchronous even while idle, accepts only an exact plain object, and returns a safe no-op when no work exists. - `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit). A non-owner's quiescence-observation hook: it observes the work settling WITHOUT tearing the agent down. Teardown is separate — a lifecycle owner stops and unregisters via `AgentHandle.dispose()`, which awaits the loop exit directly. - `agent.session`, `agent.status`, `agent.options`, `agent.id` diff --git a/packages/core/agent/src/dispatch.ts b/packages/core/agent/src/dispatch.ts index 9d024d36be..8ce018c16b 100644 --- a/packages/core/agent/src/dispatch.ts +++ b/packages/core/agent/src/dispatch.ts @@ -115,8 +115,9 @@ export function agentEvents(ctx: Context, agent: Agent): AgentEventDispatch { * Build the prompt assembly context with agent and scope set together, so * agent-scoped prompt and tool contributions cannot be silently omitted. * @param agent - the agent the assembly is for. + * @param signal - the current turn's explicit control signal, when assembly belongs to a turn. * @returns the context to pass to `assemble()`. */ -export function assembleContextFor(agent: Agent): AssembleContext { - return { agent, scope: agent } +export function assembleContextFor(agent: Agent, signal?: AbortSignal): AssembleContext { + return { agent, scope: agent, ...signal === undefined ? {} : { signal } } } diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index 3aad65a70e..f0c352a5b3 100644 --- a/packages/core/agent/src/types.ts +++ b/packages/core/agent/src/types.ts @@ -10,6 +10,7 @@ import type { Context } from 'cordis' import type { Scoped } from '@deepseek-ai/dsh-scope' import type { ContentBlock, LlmCallConfig, Message, MessageSource } from '@deepseek-ai/dsh-llm' import type {} from '@deepseek-ai/dsh-system-prompt' +import type { Session } from '@deepseek-ai/dsh-session' /** Identifies one live agent in the registry. */ export type AgentId = Branded<'AgentId'> @@ -22,8 +23,6 @@ export type AgentId = Branded<'AgentId'> export function AgentId(id: string): AgentId { return id as AgentId } -import type { Session } from '@deepseek-ai/dsh-session' - declare module '@deepseek-ai/dsh-system-prompt' { interface AssembleContext { /** Agent for this assembly; absent on diagnostics. When present, `scope` must identify the same agent. */ @@ -80,6 +79,72 @@ export type ContinuationStop = Extract /** Why a session lifecycle began; seeded creates are `startup`, while persisted loads are `resume`. */ export type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact' +/** Stable runtime cause accepted by {@link Agent.cancel}. */ +export type AgentCancelCause = + | { readonly kind: 'user' } + | { readonly kind: 'parent' } + +/** + * Validate and detach a caller-supplied Agent cancellation cause. + * @param value - the candidate cancellation cause. + * @returns a fresh frozen cause suitable for the current turn signal. + * @throws {TypeError} when the value is not an exact supported cause. + */ +export function normalizeAgentCancelCause(value: unknown): AgentCancelCause { + if (typeof value !== 'object' || value === null || Array.isArray(value)) { + throw new TypeError('agent cancel cause must be an exact plain object with kind "user" or "parent"') + } + const prototype = Object.getPrototypeOf(value) as unknown + if (prototype !== Object.prototype && prototype !== null) { + throw new TypeError('agent cancel cause must be an exact plain object with kind "user" or "parent"') + } + const keys = Reflect.ownKeys(value) + if (keys.length !== 1 || keys[0] !== 'kind') { + throw new TypeError('agent cancel cause must contain exactly one field: kind') + } + const kind = (value as { readonly kind?: unknown }).kind + switch (kind) { + case 'user': + return Object.freeze({ kind: 'user' }) + case 'parent': + return Object.freeze({ kind: 'parent' }) + default: + throw new TypeError(`unsupported agent cancel cause kind: ${String(kind)}`) + } +} + +/** Runtime reason carried by the signal that controls one live turn. */ +export type AgentInterruptReason = AgentCancelCause | { readonly kind: 'disposed' } + +/** + * Read a supported agent interruption from an explicitly supplied signal. + * Unknown reasons return `undefined`; this helper never consults ambient agent + * execution identity, which does not grant cancellation authority. + * + * @param signal - the current turn's explicit control signal. + * @returns its canonical supported reason, or `undefined` while live or when an + * unrelated controller supplied an unsupported reason. + */ +export function agentInterruptReasonOf(signal: AbortSignal): AgentInterruptReason | undefined { + if (!signal.aborted) return undefined + const reason: unknown = signal.reason + if (typeof reason === 'object' && reason !== null && !Array.isArray(reason)) { + const prototype = Object.getPrototypeOf(reason) as unknown + const keys = Reflect.ownKeys(reason) + if ((prototype === Object.prototype || prototype === null) + && keys.length === 1 && keys[0] === 'kind' + && (reason as { readonly kind?: unknown }).kind === 'disposed') { + return Object.freeze({ kind: 'disposed' }) + } + } + try { + return normalizeAgentCancelCause(reason) + } catch (error: unknown) { + if (error instanceof TypeError) return undefined + throw error + } +} + /** Public agent handle; the concrete driver belongs to `@deepseek-ai/dsh-agent-loop`. */ export interface Agent { readonly id: AgentId @@ -112,11 +177,13 @@ export interface Agent { /** * Clear queued and steering work, including work waiting to start, and abort - * the active step. The supplied reason is preserved across pre-step and active - * cancellation windows, and `whenIdle()` resolves after cancellation reaches - * quiescence. Idle cancellation is a no-op and does not arm a later cancel. + * the active turn. The first cause wins for that turn, and `whenIdle()` resolves + * after cancellation reaches quiescence. Omission means `{ kind: 'user' }`; + * invalid causes throw synchronously even while idle. Idle cancellation is a + * no-op after validation and does not arm a later cancel. + * @param cause - the stable caller intent carried by the current turn signal. */ - cancel(reason?: string): void + cancel(cause?: AgentCancelCause): void /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */ whenIdle(): Promise @@ -202,14 +269,17 @@ declare module 'cordis' { 'agent/pre-step'(this: Scoped, agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise | void /** * Allow, rewrite, or block one drained prompt before it becomes a user - * message. Call `next()` for the unchanged default. + * message. Call `next()` for the unchanged default. The signal controls only + * this turn; listeners may cooperate with it but must not retain it to + * control another turn. * @param agent - the agent draining its inbox. * @param content - the drained message's blocks, as queued. * @param source - the message's resolved source. + * @param signal - the current turn's explicit abort signal. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode waterfall */ - 'agent/prompt-submit'(this: Scoped, agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise): Promise + 'agent/prompt-submit'(this: Scoped, agent: Agent, content: ContentBlock[], source: MessageSource, signal: AbortSignal, next: () => Promise): Promise /** * Replace the frozen call configuration. Model-visible content must use * logged channels; this seam cannot mutate messages. Injection here joins @@ -218,10 +288,11 @@ declare module 'cordis' { * @param turn - the open turn number. * @param step - the step whose request this is. * @param config - the config the loop would use (frozen); return a replacement to switch. + * @param signal - the current turn's explicit abort signal; ambient agent identity does not imply liveness or cancellation authority. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode waterfall */ - 'agent/request'(this: Scoped, agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise): Promise + 'agent/request'(this: Scoped, agent: Agent, turn: number, step: number, config: LlmCallConfig, signal: AbortSignal, next: () => Promise): Promise /** * Compose request-only messages placed before derived history. The frozen * result is computed once per loop instance, logged on its anchoring request @@ -233,7 +304,7 @@ declare module 'cordis' { * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @param agent - the agent whose session prefix is being composed. * @param prefix - the frozen seed; return an extended replacement. - * @param signal - aborts composition when the step is torn down. + * @param signal - the current turn's explicit abort signal. * @mode waterfall */ 'agent/session-prefix'(this: Scoped, agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise): Promise @@ -244,30 +315,33 @@ declare module 'cordis' { * @param turn - the open turn number. * @param step - the step that produced the message. * @param message - the assistant message as assembled from the stream. + * @param signal - the current turn's explicit abort signal. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode waterfall */ - 'agent/step-result'(this: Scoped, agent: Agent, turn: number, step: number, message: Message, next: () => Promise): Promise + 'agent/step-result'(this: Scoped, agent: Agent, turn: number, step: number, message: Message, signal: AbortSignal, next: () => Promise): Promise /** * Override whether the turn continues. The default continues after tool * calls or steering and stops otherwise; a continue reason becomes steering. * @param agent - the agent deciding whether to run another step. * @param turn - the turn being continued or stopped. * @param defaultDecision - what the loop would do absent an override. + * @param signal - the current turn's explicit abort signal. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode waterfall */ - 'agent/turn-continuation'(this: Scoped, agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise): Promise + 'agent/turn-continuation'(this: Scoped, agent: Agent, turn: number, defaultDecision: ContinuationDecision, signal: AbortSignal, next: () => Promise): Promise /** * Monotonic terminal-stop checkpoint after continuation and steering are * folded; a stop remains authoritative through turn close and flush: * steering queued in that window is discarded, while ordinary sends survive. * @param agent - the agent whose composed continuation outcome may be stopped. * @param turn - the turn at its terminal-stop checkpoint. + * @param signal - the current turn's explicit abort signal. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. * @mode serial */ - 'agent/turn-stop'(this: Scoped, agent: Agent, turn: number): ContinuationStop | undefined + 'agent/turn-stop'(this: Scoped, agent: Agent, turn: number, signal: AbortSignal): Promise | ContinuationStop | undefined // ---- error notifications (emit) ---- /** diff --git a/packages/core/agent/tests/agent.spec.ts b/packages/core/agent/tests/agent.spec.ts index 5d541d56a8..1056100b41 100644 --- a/packages/core/agent/tests/agent.spec.ts +++ b/packages/core/agent/tests/agent.spec.ts @@ -22,12 +22,12 @@ function stubAgent(rawId: string): Agent { } describe('AgentRegistry', () => { - it('keeps terminal stop decisions synchronous', () => { + it('allows terminal stop policy to cooperate asynchronously with turn cancellation', () => { type TurnStopListener = Events['agent/turn-stop'] type AsyncTurnStopListener = () => Promise - expectTypeOf().not.toExtend() - expectTypeOf>().toEqualTypeOf() + expectTypeOf().toExtend() + expectTypeOf>>().toEqualTypeOf() }) it('registers exact entries, emits lifecycle events, and unregisters on owner disposal', async () => { diff --git a/packages/core/session/README.md b/packages/core/session/README.md index 7e201ab647..3739df158f 100644 --- a/packages/core/session/README.md +++ b/packages/core/session/README.md @@ -64,6 +64,8 @@ Merge-extensible via `SessionEventMap` — a plugin declaration-merges its own t Also defines `TurnTriggerMap` and `TurnEndReasonMap` (merge-extensible sum types for typed turn boundaries — `kind`-tagged instead of strings). +An interrupted live turn ends with the coarse `{ kind: 'aborted' }` outcome. Caller identity belongs to the Agent's runtime cancellation signal rather than the durable transcript; disposal remains the separate `{ kind: 'disposed' }` terminal state. + Every `SessionEvent` carries two optional top-level fields (structural metadata): - `sourceEventSeqs?: number[]` — seq numbers of provenance sources (e.g., the `assistant/chunk` seqs behind an `assistant/message`, or the shadowed nodes behind a compaction replace node). diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts index f4f42062fd..0585117f5f 100644 --- a/packages/core/session/src/types.ts +++ b/packages/core/session/src/types.ts @@ -93,7 +93,8 @@ export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap] */ export interface TurnEndReasonMap { completed: { kind: 'completed' } - aborted: { kind: 'aborted'; reason?: string } + /** A cancellation request interrupted the live turn. */ + aborted: { kind: 'aborted' } /** * The turn failed: a step threw or the model reported a failure. `step` is the * step number the failure occurred on (the operational error's location — the diff --git a/packages/core/session/tests/fork.spec.ts b/packages/core/session/tests/fork.spec.ts index af143ea5ee..9dc8f84fb5 100644 --- a/packages/core/session/tests/fork.spec.ts +++ b/packages/core/session/tests/fork.spec.ts @@ -102,7 +102,7 @@ describe('SessionStore.fork', () => { const { ctx, sessions } = await setup() const reasons: TurnEndReason[] = [ { kind: 'completed' }, - { kind: 'aborted', reason: 'cancelled by user' }, + { kind: 'aborted' }, { kind: 'error', step: 1, message: 'model failed', code: 'MODEL' }, { kind: 'disposed' }, { kind: 'max-tokens' }, diff --git a/packages/core/session/tests/session.spec.ts b/packages/core/session/tests/session.spec.ts index 2326e7b212..a47025a715 100644 --- a/packages/core/session/tests/session.spec.ts +++ b/packages/core/session/tests/session.spec.ts @@ -40,6 +40,16 @@ describe('Session', () => { expect(structuredClone(turnEnd.data.reason)).toEqual({ kind: 'max-tokens' }) }) + it('round-trips the coarse aborted turn outcome', () => { + const session = new Session(SessionId('aborted')) + session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('turn/end', { turn: 1, reason: { kind: 'aborted' } }) + const replayed = new Session(SessionId('aborted-replay'), structuredClone(session.events)) + expect(replayed.events).toEqual(session.events) + const turnEnd = replayed.events.findLast(event => event.type === 'turn/end') + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' }) + }) + it('renders context and steering messages as tagged synthetic user content', () => { const session = new Session(SessionId('s2')) session.append('context/message', { diff --git a/packages/core/system-prompt/README.md b/packages/core/system-prompt/README.md index e8975bf17e..79ee30bbb0 100644 --- a/packages/core/system-prompt/README.md +++ b/packages/core/system-prompt/README.md @@ -16,7 +16,7 @@ System prompt assembly registry. Plugins contribute ordered sections, tool schem - `ctx.systemPrompt.section(section: PromptSection): () => void` Contribute a section. The layer is the calling context's scope: `agent.ctx` contributes to that agent alone, shadowing a same-named global section there. Duplicate names within one layer and non-finite orders throw. Disposed with the calling fiber. - `ctx.systemPrompt.tools(provider: (context: AssembleContext) => ToolProviderResult): () => void` Contribute tool schemas, evaluated at each assembly with that assembly's context. `ToolProviderResult` = `{ schemas, knownNames? }`: `schemas` is the post-restriction visible set; `knownNames` is the pre-restriction universe used by `toolOrder`. A provider must not return a schema named `TOOL_ORDER_REST`. Scoped providers are consulted only for their scope's assemblies. Disposed with the calling fiber. - `ctx.systemPrompt.variable(name: string, provider: (context) => string | undefined): () => void` Contribute a prompt variable, referenced from section text as `{{name}}`. Scoped variables shadow a same-named global for that agent. Duplicate-in-layer or unreferenceable names throw; `undefined` means "no value for this assembly". Disposed with the calling fiber. -- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise` Assemble the prompt for one caller: the global layer merged with `context.scope`'s layer, with tool schemas detached before the transform seam. Runs through the scope-filtered `system-prompt/assemble` waterfall and returns its authoritative result. Rejects when a configured `toolOrder` names a tool outside the providers' `knownNames` universe, or when a provider returns the reserved rest-entry name. +- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise` Assemble the prompt for one caller: the global layer merged with `context.scope`'s layer, with tool schemas detached before the transform seam. Runs through the scope-filtered `system-prompt/assemble` waterfall and returns its authoritative result. An optional `context.signal` explicitly controls this assembly request; providers and listeners may cooperate with it but must not retain it for another turn. Rejects when a configured `toolOrder` names a tool outside the providers' `knownNames` universe, or when a provider returns the reserved rest-entry name. ### Live events @@ -24,7 +24,7 @@ System prompt assembly registry. Plugins contribute ordered sections, tool schem ### Key types -- `AssembleContext` — what one `assemble()` call is FOR. Merge-extensible; declares `scope?: ScopeKey` (the layer selector) here, and `dsh-agent` declares `agent?: Agent` (the typed DX field — never set without `scope`; use `assembleContextFor(agent)`). Providers must tolerate absent fields (a bare `assemble()` carries an empty, scope-less context). +- `AssembleContext` — what one `assemble()` call is FOR. Merge-extensible; declares `scope?: ScopeKey` (the layer selector) and `signal?: AbortSignal` (the explicit request control capability) here, while `dsh-agent` declares `agent?: Agent` (the typed DX field — never set without `scope`; use `assembleContextFor(agent, signal)`). Providers must tolerate absent fields because a bare `assemble()` carries an empty, scope-less, signal-less context. `signal` is a request value, not part of the ambient Agent execution frame. - `PromptSection` — `{ name, order, text }`. Sections are concatenated in ascending `order`. Order bands: `-100` is the harness identity, `0` the deployment persona, tool guidance uses `100–199`. - `PromptAssembly` — `{ sections: AssembledSection[], tools: ToolSchema[], variables: Record }`. Section texts arrive resolved but not yet interpolated; `variables` holds every registered variable resolved against the context. Tool schemas are part of the assembly by design: "what the model is told it can do" is one coherent thing, even though adapters transmit schemas as a separate wire field. - `renderPrompt(assembly)` — interpolates `{{variable}}` references in each section, drops empty sections, joins with blank lines. STRICT: an unknown reference (`Object.hasOwn` lookup — prototype names like `{{constructor}}` are unknown), a registered-but-valueless reference, a malformed complete `{{…}}` group, or a `{{` that opens no complete group while a `}}` still follows (`{{{model}}}`) throws — fail loud beats shipping a malformed prompt. A lone `{{` with no `}}` anywhere after it passes through verbatim; substituted values are never re-scanned. diff --git a/packages/core/system-prompt/src/index.ts b/packages/core/system-prompt/src/index.ts index 5eb66d95f8..12171f1b2e 100644 --- a/packages/core/system-prompt/src/index.ts +++ b/packages/core/system-prompt/src/index.ts @@ -20,6 +20,8 @@ declare module 'cordis' { * Expert waterfall over the assembled sections, tools, and variables. * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners * receive only that scope's assemblies. The returned value is authoritative. + * A supplied signal controls only this explicit assembly request and must not + * be retained to control later turns. * @param assembly - the mutable assembly built from registered providers. * @param context - the caller's per-assembly context. * @mode waterfall @@ -41,6 +43,8 @@ export interface AssembleContext { * only global providers and subject-less listeners participate. */ scope?: ScopeKey + /** Explicit control signal for the turn that requested this assembly, when any. */ + signal?: AbortSignal } /** One contributed section of the system prompt (registry input). */ diff --git a/packages/guard/repeat-tool-guard/src/index.ts b/packages/guard/repeat-tool-guard/src/index.ts index ca4e6b5c0e..e227785472 100644 --- a/packages/guard/repeat-tool-guard/src/index.ts +++ b/packages/guard/repeat-tool-guard/src/index.ts @@ -230,7 +230,7 @@ export function apply(ctx: Context, config: Config): void { // A user interjection changes the context; repetition across it is not a // loop. Pure reset hook: always delegates (attaching nothing, vetoing // nothing). - ctx.on('agent/prompt-submit', (agent, _content, _source, next): Promise => { + ctx.on('agent/prompt-submit', (agent, _content, _source, _signal, next): Promise => { chains.delete(agent.id) return next() }) diff --git a/packages/hooks/hook-protocol/src/runner.ts b/packages/hooks/hook-protocol/src/runner.ts index fefb6936c9..1e7de698d0 100644 --- a/packages/hooks/hook-protocol/src/runner.ts +++ b/packages/hooks/hook-protocol/src/runner.ts @@ -27,7 +27,7 @@ export interface RunHookOptions { env?: Record /** Working directory for the hook (defaults to the executor's own default when omitted). */ cwd?: string - /** Abort signal — cancels the hook run when fired (the parent step aborts). */ + /** Explicit owning-operation signal; firing it cancels the hook run. */ signal?: AbortSignal /** Whether to append a trailing newline to the stdin payload (CC yes, Codex no). */ trailingNewline: boolean diff --git a/packages/hooks/hooks-claude/src/index.ts b/packages/hooks/hooks-claude/src/index.ts index 08a2d26c9d..f2006daef8 100644 --- a/packages/hooks/hooks-claude/src/index.ts +++ b/packages/hooks/hooks-claude/src/index.ts @@ -210,9 +210,9 @@ export function apply(ctx: Context, config: Config): void { // --- UserPromptSubmit → PromptDecision. The prompt text is the payload; no // matcher subject (CC ignores matchers for this event). --- - ctx.on('agent/prompt-submit', async (agent, content, _source, next): Promise => { + ctx.on('agent/prompt-submit', async (agent, content, _source, signal, next): Promise => { const turn = lastTurn(agent) - const merged = await runPoint('UserPromptSubmit', '', promptPayload(agent, content), { agent, turn }) + const merged = await runPoint('UserPromptSubmit', '', promptPayload(agent, content), { agent, turn, signal }) if (merged.decision === 'deny') { return { kind: 'block', reason: merged.reason ?? 'blocked by UserPromptSubmit hook' } } @@ -261,8 +261,8 @@ export function apply(ctx: Context, config: Config): void { // A blocking Stop hook forces continuation with its reason. // TODO(stop-loop-guard): cap consecutive forced continuations; hooks must self-limit meanwhile. - ctx.on('agent/turn-continuation', async (agent, turn, _default, next): Promise => { - const merged = await runPoint('Stop', '', stopPayload(agent), { agent, turn }) + ctx.on('agent/turn-continuation', async (agent, turn, _default, signal, next): Promise => { + const merged = await runPoint('Stop', '', stopPayload(agent), { agent, turn, signal }) if (merged.decision === 'deny') { // A blocking Stop hook forces continuation. const text = merged.reason ?? 'continue: blocked by Stop hook' diff --git a/packages/hooks/hooks-codex/src/index.ts b/packages/hooks/hooks-codex/src/index.ts index 924b181151..d84c96a0fd 100644 --- a/packages/hooks/hooks-codex/src/index.ts +++ b/packages/hooks/hooks-codex/src/index.ts @@ -183,9 +183,9 @@ export function apply(ctx: Context, config: Config): void { }) // UserPromptSubmit → PromptDecision. Codex supports block, not allow or ask. - ctx.on('agent/prompt-submit', async (agent, content, _source, next): Promise => { + ctx.on('agent/prompt-submit', async (agent, content, _source, signal, next): Promise => { const turn = lastTurn(agent) - const merged = await runPoint('UserPromptSubmit', '', { ...turnBase(agent, 'UserPromptSubmit', model), prompt: blocksToText(content) }, { agent, turn, plainStdoutAsContext: true }) + const merged = await runPoint('UserPromptSubmit', '', { ...turnBase(agent, 'UserPromptSubmit', model), prompt: blocksToText(content) }, { agent, turn, plainStdoutAsContext: true, signal }) /* jscpd:ignore-start */ if (merged.decision === 'deny') return { kind: 'block', reason: merged.reason ?? 'blocked by UserPromptSubmit hook' } // Context alone is not a veto: DELEGATE so a later prompt-submit listener can @@ -236,8 +236,8 @@ export function apply(ctx: Context, config: Config): void { // TODO(stop-loop-guard): Codex supplies `stop_hook_active` so a Stop hook can // avoid continuing the same turn indefinitely. It is always false here, so an // unconditionally blocking hook force-continues every step until it self-limits. - ctx.on('agent/turn-continuation', async (agent, turn, _default, next): Promise => { - const merged = await runPoint('Stop', '', { ...turnBase(agent, 'Stop', model), stop_hook_active: false, last_assistant_message: null }, { agent, turn }) + ctx.on('agent/turn-continuation', async (agent, turn, _default, signal, next): Promise => { + const merged = await runPoint('Stop', '', { ...turnBase(agent, 'Stop', model), stop_hook_active: false, last_assistant_message: null }, { agent, turn, signal }) /* jscpd:ignore-end */ if (merged.decision === 'deny') { // A blocking Stop hook forces continuation; a block with no reason (exit 2, diff --git a/packages/subagent/subagent-inprocess/src/index.ts b/packages/subagent/subagent-inprocess/src/index.ts index f6de7200cf..a1a5e9e7f8 100644 --- a/packages/subagent/subagent-inprocess/src/index.ts +++ b/packages/subagent/subagent-inprocess/src/index.ts @@ -153,7 +153,7 @@ export async function startInProcessRun( const onAbort = (): void => { flags.cancelled = true - child.cancel('subagent request aborted') + child.cancel({ kind: 'parent' }) } request.signal.addEventListener('abort', onAbort, { once: true }) diff --git a/packages/subagent/subagent-inprocess/src/structured.ts b/packages/subagent/subagent-inprocess/src/structured.ts index 09aa2d24b7..811d754094 100644 --- a/packages/subagent/subagent-inprocess/src/structured.ts +++ b/packages/subagent/subagent-inprocess/src/structured.ts @@ -96,7 +96,7 @@ export function attachStructuredRuntime(childCtx: Context, schema: StructuredOut // Stop the child's turn once its output is captured. This monotonic serial // checkpoint runs after the ordinary continuation waterfall, its reason, // and late-steering folding, so no ordering trick can resume a finished run. - childCtx.on('agent/turn-stop', function (this: unknown): ContinuationStop | undefined { + childCtx.on('agent/turn-stop', function (this: unknown, _agent, _turn, _signal): ContinuationStop | undefined { return captured === undefined ? undefined : { action: 'stop' } }) diff --git a/packages/subagent/subagent-inprocess/tests/structured.spec.ts b/packages/subagent/subagent-inprocess/tests/structured.spec.ts index e8d19fe4c5..2971da0d61 100644 --- a/packages/subagent/subagent-inprocess/tests/structured.spec.ts +++ b/packages/subagent/subagent-inprocess/tests/structured.spec.ts @@ -221,7 +221,7 @@ describe('in-process structured output', () => { ctx.on('agent/session-start', (child) => { if (child === parent) return wrapperInstalled = true - child.ctx.on('agent/turn-continuation', async (_subject, _turn, _decision, next): Promise => { + child.ctx.on('agent/turn-continuation', async (_subject, _turn, _decision, _signal, next): Promise => { const downstream = await next() expect(downstream).toEqual({ action: 'stop' }) return { action: 'continue' } @@ -247,7 +247,7 @@ describe('in-process structured output', () => { const run = await ctx.subagents.start('spawn', structuredRequest(parent)) ctx.on('agent/session-start', (child) => { if (child.id !== run.id) return - child.ctx.on('agent/turn-continuation', async (subject, _turn, _decision, next): Promise => { + child.ctx.on('agent/turn-continuation', async (subject, _turn, _decision, _signal, next): Promise => { const downstream = await next() expect(downstream).toEqual({ action: 'stop' }) subject.steer([{ type: 'text', text: 'late steering after downstream stop' }]) diff --git a/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts b/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts index cecad34bfc..720c22af2a 100644 --- a/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts +++ b/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts @@ -25,9 +25,10 @@ async function setup(script: Script) { await ctx.plugin(AgentExecutionProvider) await ctx.plugin(AgentLoop, { agents: [] }) await ctx.plugin(SubagentService) - ctx.llm.registerAdapter(['mock'], new MockAdapter(script)) + const adapter = new MockAdapter(script) + ctx.llm.registerAdapter(['mock'], adapter) const parent = ctx.agentLoop.create(AgentId('parent'), { model: 'mock' }) - return { ctx, parent } + return { ctx, parent, adapter } } function request(parent: Agent, signal = new AbortController().signal) { @@ -102,12 +103,16 @@ describe('startInProcessRun', () => { }) it('uses the request signal after publication and dispose as cancellation paths', async () => { - const { parent } = await setup(['hang', 'hang']) + const { parent, adapter } = await setup(['hang', 'hang']) const controller = new AbortController() const signalled = await startInProcessRun(request(parent, controller.signal), {}) await new Promise(resolve => setTimeout(resolve, 30)) controller.abort('stop child') await expect(signalled.result).resolves.toMatchObject({ stopReason: 'aborted' }) + expect(adapter.requests[0]?.signal?.reason).toEqual({ kind: 'parent' }) + const child = parent.ctx.agents.get(signalled.id) + const turnEnd = child?.session.events.findLast(event => event.type === 'turn/end') + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' }) await signalled.dispose() const disposed = await startInProcessRun(request(parent), {}) diff --git a/packages/ui/acp/src/index.ts b/packages/ui/acp/src/index.ts index c464ffd22b..26d5bab371 100644 --- a/packages/ui/acp/src/index.ts +++ b/packages/ui/acp/src/index.ts @@ -495,7 +495,7 @@ export function apply(ctx: Context, config: AcpConfig): void { // invariants and persistence observe the events in log order; the first flush // clears pending state. Promptless injection turns leave the switch pending, // with no request or execution under stale settings. - ctx.on('agent/prompt-submit', (agent, _content, _source, next) => { + ctx.on('agent/prompt-submit', (agent, _content, _source, _signal, next) => { const sessionId = bySession.get(agent) const rec = sessionId === undefined ? undefined : sessions.get(sessionId) if (rec !== undefined) flushPendingSwitches(rec) @@ -706,7 +706,7 @@ export function apply(ctx: Context, config: AcpConfig): void { cancel(params: CancelNotification): Promise { const rec = sessions.get(SessionId(params.sessionId)) if (rec === undefined) return Promise.resolve() - // session/cancel maps to the queue-aware agent.cancel(reason): it aborts + // session/cancel maps to the queue-aware user cancel cause: it aborts // a RUNNING step, clears the queued + steering FIFOs, and drops a // turn that is about to start (the pre-step window) — so a queued-but- // not-yet-started prompt never runs, and a prompt accepted right after @@ -717,7 +717,7 @@ export function apply(ctx: Context, config: AcpConfig): void { // settle it, because cancel() may drop the turn before any turn/end is // emitted, and removing this direct settle would move the RPC's // resolution onto a later observer path, changing its timing. - rec.agent.cancel('session/cancel') + rec.agent.cancel({ kind: 'user' }) settlePrompt(rec, 'cancelled') return Promise.resolve() }, @@ -778,7 +778,7 @@ export function apply(ctx: Context, config: AcpConfig): void { * Tear ALL live sessions down to quiescence (docs/defensive-patterns.md "dispose must reach * quiescence"): for each session settle any pending prompt `cancelled`, then * run that session's {@link AgentHandle} `dispose()` — which stops the loop - * (sets `disposed`, aborts the in-flight step), AWAITS the loop's exit (the + * (sets `disposed`, aborts the active turn), AWAITS the loop's exit (the * final `turn/end` + `session/flush` are captured while the store-owned publication hooks are still * attached), unregisters the agent, and removes its session from the store. * The per-session disposes run in parallel. Idempotent — clears the `sessions` @@ -817,7 +817,7 @@ export function apply(ctx: Context, config: AcpConfig): void { await Promise.all(recs.map(async (rec) => { settlePrompt(rec, 'cancelled') // Per-agent dispose (the AgentHandle disposer): unregister this agent, - // stop its loop (sets disposed + aborts the in-flight step), await + // stop its loop (sets disposed + aborts the active turn), await // quiescence (the loop exit + final flush), and remove its session — so // a bare client disconnect leaves NO registered agent and NO // session-store entry, not just an idled-but-still-registered one. diff --git a/packages/ui/acp/tests/codec.spec.ts b/packages/ui/acp/tests/codec.spec.ts index b4f0c10792..31ffb9ed48 100644 --- a/packages/ui/acp/tests/codec.spec.ts +++ b/packages/ui/acp/tests/codec.spec.ts @@ -15,7 +15,7 @@ describe('turnEndToStopReason', () => { it('maps every known TurnEndReason kind to a legal StopReason', () => { expect(turnEndToStopReason({ kind: 'completed' })).toBe('end_turn') expect(turnEndToStopReason({ kind: 'max-tokens' })).toBe('max_tokens') - expect(turnEndToStopReason({ kind: 'aborted', reason: 'x' })).toBe('cancelled') + expect(turnEndToStopReason({ kind: 'aborted' })).toBe('cancelled') expect(turnEndToStopReason({ kind: 'disposed' })).toBe('cancelled') expect(turnEndToStopReason({ kind: 'rejected', reason: 'blocked by hook' })).toBe('cancelled') expect(turnEndToStopReason({ kind: 'error', step: 1, message: 'boom' })).toBe('end_turn') diff --git a/packages/ui/acp/tests/turns.spec.ts b/packages/ui/acp/tests/turns.spec.ts index 78591ffa76..fc911480cd 100644 --- a/packages/ui/acp/tests/turns.spec.ts +++ b/packages/ui/acp/tests/turns.spec.ts @@ -316,6 +316,10 @@ describe('acp bridge — turn outcomes', () => { await harness.client.cancel({ sessionId }) const res = await promptDone expect(res.stopReason).toBe('cancelled') + const agent = harness.ctx.agents.get(AgentId(sessionId))! + await agent.whenIdle() + const turnEnd = agent.session.events.findLast(event => event.type === 'turn/end') + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'aborted' }) }) it('cancel right after prompt settles cancelled and leaves the agent idle, no leaked turn', async () => { diff --git a/scripts/translation-pairing.manifest.json b/scripts/translation-pairing.manifest.json index 35a957e57d..7104376ed6 100644 --- a/scripts/translation-pairing.manifest.json +++ b/scripts/translation-pairing.manifest.json @@ -12,6 +12,7 @@ "docs/i18n/README.md", "docs/i18n/translation-rules.md", "docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md", + "docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.md", "docs/rfc/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md", "python/README.md", "python/sdk-runtime/README.md", diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 221372aa5c..3d6e758838 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -10,6 +10,7 @@ { "doc": "docs/core-data-structures/core.md", "symbol": "ToolSchema", "source": "packages/llm/llm/src/types.ts" }, { "doc": "docs/core-data-structures/core.md", "symbol": "LlmCallConfig", "source": "packages/llm/llm/src/call-config.ts" }, { "doc": "docs/core-data-structures/core.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }, + { "doc": "docs/core-data-structures/core.md", "symbol": "AgentCancelCause", "source": "packages/core/agent/src/types.ts" }, { "doc": "docs/core-data-structures/core.md", "symbol": "Agent", "source": "packages/core/agent/src/types.ts" }, { "doc": "docs/core-data-structures/core.md", "symbol": "AgentExecution", "source": "packages/core/agent-execution/src/types.ts" }, { "doc": "docs/core-data-structures/core.md", "symbol": "AgentExecutionService", "source": "packages/core/agent-execution/src/index.ts" }, From d7ead6fdec930362de7877d33a991f5ba0d31aeb Mon Sep 17 00:00:00 2001 From: NI0317 Date: Thu, 16 Jul 2026 18:47:46 +0800 Subject: [PATCH 021/273] docs(rfc): correct harness loop contracts --- .../2026-07-16-harness-level-loop.i18n.yaml | 4 +- .../feature/2026-07-16-harness-level-loop.md | 184 ++++++++++-------- .../2026-07-16-harness-level-loop.zh.md | 184 ++++++++++-------- 3 files changed, 208 insertions(+), 164 deletions(-) diff --git a/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.i18n.yaml b/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.i18n.yaml index fe26d5d8a4..b167a54cef 100644 --- a/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.i18n.yaml +++ b/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.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 -2026-07-16-harness-level-loop.md: 8bc4ecf3734a7e9d82d1f844b3d7186fa6ccafed -2026-07-16-harness-level-loop.zh.md: 4e1b677259b310171098cc78dd174b55c8d69970 +2026-07-16-harness-level-loop.md: d308442c53dacd4fdb0d298c21e843899aba8d5c +2026-07-16-harness-level-loop.zh.md: b4884f2082deb601a1a5308911cb9458fe72f8af diff --git a/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.md b/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.md index 8bc4ecf373..d308442c53 100644 --- a/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.md +++ b/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.md @@ -13,7 +13,7 @@ The existing code offers three "just enough to run" alternatives, none of them a | Alternative | Problem | |---|---| | A `packages/workflow` script expressing `while (!done)` | The README explicitly writes "No token-budget vocabulary" and "No journaling or resume"; the parent turn blocks until the script settles. Fine for orchestration lasting minutes, unusable for tasks lasting hours | -| An external shell `while :; do dsh …; done` | Ralph-style scheduling can be written this way today. It lacks a shared vocabulary for stop condition, budget, and evaluator, so every user reinvents them; the loop itself has no durable object for post-hoc diagnosis or recovery | +| An external shell `while :; do dsh-sdk …; done` | Ralph-style scheduling can be written this way today. It lacks a shared vocabulary for stop condition, budget, and evaluator, so every user reinvents them; the loop itself has no durable object for post-hoc diagnosis or recovery | | The `sendMessage`/`resume` capabilities on the `packages/subagent` seam | The README explicitly writes "Runtime steering and continuation are seam-only capabilities". There is no model-facing consumer, so the model can only start a fresh subagent | Three typical use cases. **Automated fix**: a failing test suite in front of you, and you want a process to keep modifying code, running tests, and modifying again against the failure messages, until everything is green or the budget cap is hit. **Rubric-driven iterative revision**: a document, code, or translation must meet a set of scoring criteria; the loop repeatedly adjusts, an independent evaluator scores, and the loop stops when the criteria are met or the round budget is exhausted. **Unattended long runs**: for example, porting a repository from one tech stack to another overnight, kicked off before leaving work and reviewed the next morning, with the budget as the only safety net. Common shape across all three: minutes to hours, evaluator decides success, budget is a hard constraint, and post-run review and recovery are required. @@ -33,16 +33,16 @@ This RFC only **adds a capability seam `packages/loop/`** for the goal-based sha Three packages: -- `@deepseek-ai/dsh-loop`: types, the `LoopDriver` service, the `StopCondition` discriminated union, four built-in service definitions (`Evaluator` / `BudgetPolicy` / `RoundHandoff` / `GoalReflector`), and the event schema +- `@deepseek-ai/dsh-loop`: types, the `LoopDriver` service, the `StopCondition` discriminated union, the Phase 1 service definitions (`Evaluator` / `BudgetPolicy` / `RoundHandoff`), and the event schema; `GoalReflector` joins in Phase 2 with its first caller - `@deepseek-ai/dsh-loop-driver`: the default driver implementation -- `@deepseek-ai/dsh-loop-tool`: the model-facing `loop` tool plus the CLI `dsh loop` +- `@deepseek-ai/dsh-loop-tool`: the model-facing `loop` tool plus the CLI `dsh-sdk loop` -The design is organized around four concrete problems, each addressed by an independent cordis service seam: +The design is organized around four concrete problems, addressed by service seams or explicit driver policies in the phase where each has a caller: 1. A long-running loop that goes wrong leaves no systematic diagnosis or recovery. **Loop as an independent session** addresses this. 2. Whether the PASS at loop end is trustworthy determines whether hours of work are wasted. An architecture where the same LLM both generates and self-evaluates is not trustworthy on its face. **Making Evaluator and Budget into service seams** addresses this. 3. Short and long tasks need opposite memory strategies; hardcoding one mode makes the other class of scenario unusable. **Making RoundHandoff into a service seam** addresses this. -4. The user's initial goal is not always correct. An agent stubbornly pursuing a wrong goal exhausts the budget doing wrong work. **Making GoalReflector into a service seam** addresses this. +4. The user's initial goal is not always correct. An agent stubbornly pursuing a wrong goal exhausts the budget doing wrong work. **Goal concern events and policies cover Phase 1; the GoalReflector service arrives with the Phase 2 `reflect` path**. Beyond the four seams, one principle threads through the whole document: **one loop handles one atomic goal**. Large goals should be split into several small loops chained in sequence, not stuffed into one loop with the evaluator judging multiple things. A rule of thumb for whether granularity is right: if you cannot say what a finished loop actually accomplished, granularity is too large and should be split. Phase 2 adds a `loop_split` model-facing tool so the agent can split an oversized goal itself. @@ -55,7 +55,7 @@ interface EvaluatorReport { criteria: readonly { name: string; pass: boolean; ev type StopCondition = | { kind: 'goal-met'; evidence: EvaluatorReport } - | { kind: 'budget-cap'; scope: 'usd' | 'tokens' | 'rounds' } + | { kind: 'budget-cap'; scope: 'usd' | 'tokens' | 'rounds'; observed: number; maximum: number } | { kind: 'stuck'; pattern: 'repeat-action' | 'no-progress' | 'error-loop' } | { kind: 'approval-required'; reason: string } | { kind: 'user-cancel' } @@ -67,21 +67,21 @@ export {} Once a long-running loop goes wrong, the user has no systematic diagnostic method. A failure hours in leaves only scattered log files to sift through. Discovering that some middle round went off track and wanting to roll back to re-run means starting over from scratch. An agent wanting to consult its own experience from past loops has no API to reach it. -The driver opens an independent loop-session (a new session id) for each loop. Every round's inputs, inner-loop results, evaluator reports, and stop decisions are persisted as session events, reusing the SQLite backend from `packages/session-persistence`. This yields three capabilities. +The driver opens an independent loop-session (a new session id) for each loop. Every round's inputs, inner-loop results, evaluator reports, and stop decisions are persisted as session events, reusing the SQLite backend from `packages/session-persistence`. This yields three diagnostic and replay capabilities. -- **Resume from any round**: discover round 78 went off, restart from round 77 with a different prompt or evaluator, no need to start over -- **Post-hoc diagnosis**: through [sqlite-session-query-provider](2026-07-10-sqlite-session-query-provider.md), query "which round did the evaluator start hanging on the same criterion" to locate the stuck point -- **Meta-loop learning**: before starting a new loop, the agent queries its own experience from past loops of the same kind—"have I fixed a similar bug before? Which round did it fail on?" +- **Replay conversation from a recorded round**: while the source session is live, discover round 78 went off and fork the round-77 event prefix with a different prompt or evaluator; persisted replay needs a separate trusted load-and-seed path. Both forms replay conversation state against the current workspace, not the files and external side effects that existed at round 77 +- **Post-hoc diagnosis**: through the existing `ctx.sessionQuery` exact-read service, inspect the round where the evaluator started hanging on the same criterion +- **Meta-loop learning**: the proposed [SQLite FTS5 search](2026-07-10-sqlite-session-query-provider.md) can later find related historical loops before a new run—"have I fixed a similar bug before? Which round did it fail on?" Claude Code's and Codex's `/goal` are one-off objects: discarded when the run ends, so the agent starts from zero when facing a similar problem again. -**Storage and dependency**. A few KB of events per round, roughly 100–500 KB per 100-round loop; thousands of loops reach GB scale. Mitigated by the `logDetail: 'summary' | 'full'` config, defaulting to `full` with long-run users able to switch to `summary`. Persisting all intermediate state also writes generated keys, passwords, and similar secrets to disk—the same class of risk as an ordinary session but amplified 10–100×, and the README calls this out clearly. **The most critical point**: this section's capabilities have a hard dependency on the not-yet-landed [sqlite-session-query-provider RFC](2026-07-10-sqlite-session-query-provider.md). If that RFC does not land, arbitrary-round resume and query capability degrade to "just grep the JSONL files". If Phase 1 ships before that RFC merges, Phase 1 only guarantees correct event shape and defers the query surface to Phase 2. +**Storage and recovery boundary**. A few KB of events per round, roughly 100–500 KB per 100-round loop; thousands of loops reach GB scale. Mitigated by the `logDetail: 'summary' | 'full'` config, defaulting to `full` with long-run users able to switch to `summary`. Persisting all intermediate state also writes generated keys, passwords, and similar secrets to disk—the same class of risk as an ordinary session but amplified 10–100×, and the README calls this out clearly. Exact live and persisted reads already exist through `ctx.sessionQuery`; FTS5 is an optional discovery improvement, not a Phase 1 dependency. Exact execution-world restore is not promised: `SessionStore.fork()` accepts a live session, and session events do not restore files, processes, environment, or external side effects. Restoring those requires a separate Git/worktree/checkpoint design. ### Pluggable Evaluator and Budget A loop's value ultimately depends on whether the final PASS is trustworthy. If the evaluator can be hacked or hallucinates PASS, hours of work are wasted. An architecture where the same LLM both generates and self-evaluates is not trustworthy on its face: the model has the means to talk itself into PASS. Even letting an independent subagent be the evaluator only mitigates the problem; as long as the evaluator is still an LLM, it retains a systematic bias for the same class of content—an independent subagent is a mitigation, not a cure. -Truly trustworthy evaluation must be a fully non-LLM hard check: shell exit code, static analysis, an external service. The LLM physically cannot touch the evaluation process. But only the user knows which hard check to run: `pytest` commands differ by project, companies have private compliance checkers, some teams also run internal lint. No number of built-in evaluators can cover them all. Evaluator therefore must be a seam the user can plug into. +Trustworthy evaluation needs both a deterministic judgment mechanism and an isolation boundary appropriate to the threat model: shell exit code, static analysis, or an external service avoids LLM self-judgment, while a separate worktree, read-only mount, container, or remote service prevents the worker from rewriting evaluator inputs. Only the user knows which checks and boundary to use: `pytest` commands differ by project, companies have private compliance checkers, and some teams also run internal lint. No number of built-in evaluators can cover them all. Evaluator therefore must be a seam the user can plug into. Budget is the same story: product-level spending guardrails are opaque, and cannot be adjusted for team policy (personal card, team splitting, per-PR settlement). @@ -91,47 +91,47 @@ Budget is the same story: product-level spending guardrails are opaque, and cann interface RubricItem { name: string; description: string } interface EvaluatorContract { readonly name: string } -type EvaluatorSpec = { - tier: - | { kind: 'single-metric'; check: string } // "pytest -q && ruff check"、"exit code == 0" - | { kind: 'rubric'; criteria: RubricItem[] } // 若干独立 criterion,各自 pass/fail + evidence - | { kind: 'contract'; interface: EvaluatorContract } // 结构化合约(如 API sig 校验) - | { kind: 'llm-judge'; rubric: string; model: string } // 兜底档,仅软目标 - /** - * 主 agent 不可写的路径(通常是 evaluator 会读的测试文件、评估配置)。 - * 违规写会被 packages/fs policy gate 拒绝,记 loop/hack-attempt session event。 - * 这是防 reward hacking 的核心机制——把「改测试让 evaluator 通过」这条路封死。 - */ - protectedPaths?: readonly string[] +type CriteriaSpec = + | { kind: 'single-metric'; name: string } + | { kind: 'rubric'; criteria: RubricItem[] } + | { kind: 'contract'; interface: EvaluatorContract } + +type ExecutorSpec = + | { kind: 'shell'; command: string } + | { kind: 'llm-judge'; rubric: string; model: string } + | { kind: 'provider'; name: string; config?: unknown } + +type IsolationSpec = 'same-workspace' | 'separate-worktree' | 'container' | 'remote' + +interface EvaluatorSpec { + criteria: CriteriaSpec + executor: ExecutorSpec + isolation: IsolationSpec } export {} ``` -**Why tiers instead of letting the user pass any function?** Tiers force the user, at start time, to declare "which strength of judgment I'm using". A free function looks flexible, but in practice it lets evaluator strength quietly regress—the user thinks they're doing strict judgment when they've actually written a fuzzy LLM-judge-style semantic match. In long-run scenarios the cost is hours wasted. +**Why explicit dimensions instead of letting the user pass any function?** The spec forces the user, at start time, to declare what is judged, what executes the judgment, and what isolation boundary protects it. A free function looks flexible, but in practice it lets evaluator strength quietly regress—the user thinks they're doing a deterministic isolated check when they've actually written a same-workspace LLM judgment. In long-run scenarios the cost is hours wasted. -The four tiers descend in trustworthiness from top to bottom. The top three are fully non-LLM hard checks. `llm-judge` is the weakest tier, only for soft goals where there truly is no hard signal (revision, translation quality). The documentation explicitly notes "this tier cannot defend against targeted adversarial input; long unattended runs require at least one hard-check tier alongside". +Criteria shape, executor, and isolation are orthogonal rather than a trust ladder: a rubric may be checked by shell, an LLM, or an external service, and a contract may run in the same workspace or in a container. `llm-judge` remains the weakest executor for soft goals where there truly is no hard signal (revision, translation quality). The documentation explicitly notes "this executor cannot defend against targeted adversarial input; long unattended runs require at least one deterministic evaluator with an isolation boundary appropriate to the threat model". -The driver enforces five hard constraints, not delegated to Evaluator implementations. They address three distinct attack surfaces: +The driver enforces four structural constraints, not delegated to Evaluator implementations. Isolation strength remains an explicit property of the configured provider rather than a claim the driver can manufacture. **Preventing "the same agent both generates and self-evaluates"**: -1. **fresh subagent**: the evaluator opens a fresh subagent (via `dsh-subagent`'s `spawn`) each round, not inheriting the main loop's context - -**Preventing the main agent from reward-hacking by modifying evaluator inputs**: - -2. **`protectedPaths` hard isolation**: paths declared in `EvaluatorSpec` (typically test files and evaluator config) are rejected for main-agent writes by the existing policy gate in `packages/fs`, and blocked writes are recorded as `loop/hack-attempt` session events. This is Phase 1's real defense against reward hacking—it seals off the "modify the tests so the evaluator passes" path directly +1. **fresh subagent for LLM evaluation**: an LLM evaluator opens a fresh subagent (via `dsh-subagent`'s `spawn`) each round, not inheriting the main loop's context **Preventing the evaluator subagent itself from being subverted**: -3. **read-only tool set**: the evaluator's tool set is stripped by the driver to reads only, with write tools disabled (reusing `SubagentProvider`'s `toolFilter`). It defends not against main-agent reward hacking, but against the evaluator being prompted-injected via code embedded in the code being evaluated—so it cannot be tricked into modifying state +2. **scoped tool set**: an LLM evaluator's model-facing tool set is stripped by the driver to reads only, with write tools disabled (reusing `SubagentProvider`'s `toolFilter`). This reduces accidental mutation but is not process isolation: shell, code runtimes, or another capability can still write unless the configured isolation boundary prevents it **Preventing the evaluator report itself from deceiving the driver**: -4. **PASS can only flip via an evaluator report**: the `goal-met` StopCondition can only come from the evaluator; the driver and the main agent cannot construct it directly -5. **Default-FAIL**: the driver maintains each criterion's pass state at `false` internally; only an evaluator report with non-empty evidence is allowed to flip it to `true`. The evaluator cannot get the driver to accept a `{pass: true}` return with no evidence +3. **PASS can only flip via an evaluator report**: the `goal-met` StopCondition can only come from the evaluator; the driver and the main agent cannot construct it directly +4. **Default-FAIL**: the driver maintains each criterion's pass state at `false` internally; only an evaluator report with non-empty evidence is allowed to flip it to `true`. The evaluator cannot get the driver to accept a `{pass: true}` return with no evidence -Together, the five decide that evaluator conclusions can only be driven by evidence—not by confidence, and not by the main agent quietly modifying tests. +Together, the four ensure that evaluator conclusions are structurally evidence-driven rather than confidence-driven. They do not stop the main agent from modifying evaluator inputs in a shared workspace. **Phase 1 ships three backends**: @@ -139,9 +139,9 @@ Together, the five decide that evaluator conclusions can only be driven by evide - `loop-evaluator-rubric-judge` implements `llm-judge`: a prewritten rubric plus LLM scoring, soft goals only - `loop-budget-preflight`: before each round starts, estimate `(promptTokens + overhead + estOutputTokens) / 1M × pricePerMTok`; refuse to start if the estimate exceeds `perRoundUsd`. The estimation model comes from MartinLoop `policy.ts:551-596` -A `PricingProvider` service injects the pricing table; a test seam can override it, and it is not hardcoded into the driver (AGENTS.md "No hardcoded tunables in plugins"). The `rubric` and `contract` tiers get built-in implementations in Phase 2; Phase 1 only exposes the types so third-party plugins can integrate first. +A `PricingProvider` service injects the pricing table; a test seam can override it, and it is not hardcoded into the driver (AGENTS.md "No hardcoded tunables in plugins"). A resolved budget carries `maxRounds`, optional `maxTokens` and `maxUsd`, and optional `perRoundUsd`. The driver checks per-round admission before starting work, then accumulates worker, evaluator, compaction, and reflector usage after every request. A token or USD cap may overrun by one in-flight request because usage arrives after completion; the `budget-cap` result reports `observed` and `maximum`. The `rubric` and `contract` criteria shapes get built-in executors in Phase 2; Phase 1 exposes the shapes so third-party plugins can integrate first. -**Limitation**: the "read-only tools" the evaluator subagent receives are still shell and fs reads within the same process, and could theoretically be bypassed by prompt injection. Defending against targeted adversarial input requires the two-container approach (the evaluator's definition files are entirely inaccessible to the main agent, the route Anthropic patch.py takes), which is a Phase 3 item. See Risks. +**Limitation**: `same-workspace` plus a read-only model-facing tool set is not hard isolation. The current `packages/fs` policy enforces read-before-edit and version guards, not path denial, and bash or code runtimes can bypass filesystem tools. Defending against targeted adversarial input requires a boundary across every mutation channel—such as a read-only mount, isolated worktree, container, or remote evaluator. The two-container approach (the evaluator's definition files are entirely inaccessible to the main agent, the route Anthropic patch.py takes) remains a Phase 3 item. See Risks. ### Pluggable RoundHandoff @@ -150,23 +150,40 @@ How context passes between rounds is a dilemma. Preserving the full prior conver Made a service seam: ```ts -interface RoundContext { loopId: string; round: number } -interface NextRoundSpec { mode: 'fresh' | 'continue' } +interface ContinuationRun { + readonly id: string + resume?(prompt: string): Promise +} + +interface PreviousRound { + result: unknown + evaluator: { criteria: readonly { name: string; pass: boolean; evidence: readonly string[] }[] } + tokenUsage: number + summary: string + sessionId: string + run?: ContinuationRun +} + +interface RoundContext { loopId: string; round: number; previous: PreviousRound } + +type NextRoundSpec = + | { mode: 'fresh'; prompt: string } + | { mode: 'continue'; run: ContinuationRun; prompt: string } interface RoundHandoff { - buildNextRound(prev: RoundContext): NextRoundSpec + buildNextRound(prev: RoundContext, signal: AbortSignal): Promise } export {} ``` -Phase 1 ships three backends: +Phase 1 ships the fresh backend; Phase 2 adds the two continuation backends after provider continuation exists: -| Backend | Scenario | Mechanism | -|---|---|---| -| `handoff-fresh-with-summary` (default) | Long runs, unattended | Open a fresh subagent each round, injecting only a progress summary as a system prompt append | -| `handoff-continue-with-compaction` (recommended middle) | Medium length, 5–20 rounds | Retain the full conversation up to a token threshold; over the threshold, reuse [`packages/compact`](../../../../packages/compact/README.md) to compress into a summary, using summary + last K rounds as the starting point | -| `handoff-continue-raw` (advanced) | ≤5 rounds, short tasks, testing | Plain continuation without truncation | +| Backend | Phase | Scenario | Mechanism | +|---|---|---|---| +| `handoff-fresh-with-summary` (default) | Phase 1 | Long runs, unattended | Open a fresh subagent each round, injecting only a progress summary as a system prompt append | +| `handoff-continue-with-compaction` (recommended middle) | Phase 2 | Medium length, 5–20 rounds | Retain the full conversation up to a token threshold; over the threshold, reuse [`packages/compact`](../../../../packages/compact/README.md) to compress into a summary, using summary + last K rounds as the starting point | +| `handoff-continue-raw` (advanced) | Phase 2 | ≤5 rounds, short tasks, testing | Plain continuation without truncation | **Why default to fresh?** Every long-run loop that actually succeeded (repomirror, Kimi ralph-loop, autoresearch) uses fresh. Placing important loop state outside the context window under driver management is the correct posture for long runs. `handoff-continue-raw` violates this experience, and the README explicitly notes it is not suitable for long runs. @@ -174,13 +191,13 @@ Phase 1 ships three backends: **Why a seam rather than a three-choice flag?** Users can write 20-line plugins expressing hybrid strategies like "continue for the first 5 rounds, then fresh", or "auto-compact once when context hits 50%", without waiting for main-library support. -**Limitation**: `continue-with-compaction` depends on the compression quality of `packages/compact`; compression itself may write hallucinated information into the summary and propagate it forward. The README recommends fresh for long runs. The three backends' boundaries may confuse new users about which to pick; the `dsh loop` CLI defaults to fresh, so users don't have to understand the differences before hitting a concrete problem. +**Limitation**: `continue-with-compaction` depends on the compression quality of `packages/compact`; compression itself may write hallucinated information into the summary and propagate it forward. The README recommends fresh for long runs. The three backends' boundaries may confuse new users about which to pick; the `dsh-sdk loop` CLI defaults to fresh, so users don't have to understand the differences before hitting a concrete problem. ### Pluggable GoalReflector The goal the user gives at loop start is not always accurate. It may be based on a wrong assumption (asking the agent to implement a feature with a since-deprecated API), it may not be clear enough (the agent discovers a clarification is needed only mid-work), or it may be invalidated by later information. Current loop-execution frameworks treat the goal as a contract frozen at start; the agent can only push down the original path, and the result is exhausting the budget on the wrong direction. -Made a service seam, with responsibility separated from `Evaluator`: the evaluator asks "did we reach the goal", the reflector asks "is the goal still the same goal". +Phase 2 makes this a service seam, with responsibility separated from `Evaluator`: the evaluator asks "did we reach the goal", the reflector asks "is the goal still the same goal". Phase 1 carries concern events plus the `stop` and `notify-continue` driver policies without registering an unused `GoalReflector` service. ```ts interface RoundContext { loopId: string; round: number } @@ -198,7 +215,7 @@ type GoalReflection = export {} ``` -**Concerns have three sources**, and Phase 1 ships the first two: +**Concerns have three sources**. Phase 1 ships the first two; the `GoalReflector` service and periodic source arrive together in Phase 2: - **Agent-initiated**: via the model-facing tool `loop_flag_concern({ concern, severity })`. An agent that realizes during investigation that "the library the user assumed has been deprecated" can raise directly - **Driver heuristic**: when budget passes 50% and zero criteria have passed, the driver auto-raises a `no-progress-toward-goal` concern @@ -207,58 +224,61 @@ export {} **Response strategy is controlled by the `onGoalConcern` config**. The four settings correspond to different philosophies about loop use; users choose by their team's collaboration style, and the driver takes no default stance: - `'stop'` (Phase 1 default): any concern triggers `StopCondition: approval-required`, and a human decides. A loop should never proceed on its own in the face of uncertainty—suitable for cautious teams and for high-impact loop scenarios -- `'notify-continue'` (Phase 1): record a high-priority `loop/goal-concern` session event plus an explicit ACP notification, then continue; a human reviews at the end. The loop internal is not interrupted—suitable for unattended long runs +- `'notify-continue'` (Phase 1): record an ordinary `loop/goal-concern` session event, then continue; a human reviews at the end. ACP has no general high-priority marker, so dedicated concern rendering is deferred with the ACP command infrastructure. The loop internal is not interrupted—suitable for unattended long runs - `'reflect'` (Phase 2): call `GoalReflector` to decide continue, revise, or stop. Delegates the initial judgment to an independent agent in place of a human—suitable for teams with moderate autonomy - Not registering a `GoalReflector` and leaving `onGoalConcern` unset = the most hands-off tier: the loop stops only on traditional stop conditions **Why default to `stop`?** In unattended scenarios, stopping one extra time is safer than running for hours in the wrong direction. Users who explicitly want unattended can switch to `notify-continue`. -A concern is itself just an ordinary session event, composing naturally with the persistence capability described earlier: on resume, one can pick up from the round where the concern surfaced, swap the goal, and re-run—the work of the previous N rounds is not lost. +A concern is itself just an ordinary session event, composing naturally with the persistence capability described earlier: a later replay can seed a new conversation from the round where the concern surfaced and swap the goal. This does not roll the workspace back to that round. -**Abuse and loss protection**. An agent could raise a concern every round; the mitigation is the `severity` field plus a minimal rate limit on the driver side (same-concern dedup within 30 seconds). The cost of that abuse is that the agent stalls itself and cannot make progress, so the incentive is weak. Once a goal has been revised, the original goal is lost; each revise persists a `loop/goal-revised` session event with rationale, and resume can select any historical goal version. +**Abuse and loss protection**. An agent could raise a concern every round; the mitigation is the `severity` field plus a minimal rate limit on the driver side (same-concern dedup within 30 seconds). The cost of that abuse is that the agent stalls itself and cannot make progress, so the incentive is weak. Once a goal has been revised, the original goal is lost; each revise persists a `loop/goal-revised` session event with rationale, and later replay can select any historical goal version without claiming workspace restoration. ### User surface Four trigger surfaces share one driver: -- **Agent-side tool**: `loop({ goal, evaluator, maxRounds, maxUsd, onGoalConcern })` starts a nested harness loop. Inside a running loop, the internal agent can call `loop_flag_concern({ concern, severity })` to raise a concern proactively. ACP rendering intent is `generic`. An agent-initiated call is proactive triggering with no extra machinery -- **CLI**: `dsh loop --stop --max-rounds N --max-usd X --handoff fresh` is human-initiated startup, the most typical Ralph-style usage +- **Agent-side tool**: `loop({ goal, evaluator, maxRounds, maxUsd, onGoalConcern })` registers `kind: 'loop'` through `ctx.tasks`, returns the task id immediately, and runs the harness loop in the background. `task_output`, `task_list`, and `task_kill` provide collection and cancellation. Inside a running loop, the internal agent can call `loop_flag_concern({ concern, severity })` to raise a concern proactively. ACP rendering intent is `generic`. An agent-initiated call is proactive triggering with no extra machinery +- **CLI**: `dsh-sdk loop --stop --max-rounds N --max-usd X --handoff fresh` is human-initiated startup, the most typical Ralph-style usage - **cordis leaf**: declare a resident loop as a leaf in `cordis.yml`, with future `dsh-schedule` RFC integration for periodic triggering -- **ACP slash command**: `/loop ` (and `/loop-flag-concern`) starts directly from within the editor or client's current session. Semantically equivalent to a human typing `dsh loop` in a shell, but happens within the ongoing ACP session context, letting the loop result inject back into the session +- **ACP slash command**: `/loop ` (and `/loop-flag-concern`) starts directly from within the editor or client's current session. Semantically equivalent to a human typing `dsh-sdk loop` in a shell, but happens within the ongoing ACP session context, letting the loop result inject back into the session The ACP slash command depends on: `packages/ui/acp`'s `available_commands_update` surface is currently unbuilt ([acp-feature-support.md](../../../../packages/ui/acp/acp-feature-support.md)). Once the harness's slash-command infrastructure lands, `/loop` and `/loop-flag-concern` only need to be registered against that infrastructure; the driver and tool interfaces do not change. This RFC reserves the names and specifies the argument shape, but does not commit the infrastructure itself—that belongs to a separate ACP catch-up RFC. -The default system prompt carries two hard constraints, distributed with every built-in `loop` tool: +The default system prompt carries two behavioral instructions, distributed with every built-in `loop` tool: 1. No writing of `TODO`, `FAKE`, or `PLACEHOLDER` placeholders to superficially pass the evaluator 2. No writing of empty `try/except` or `catch(_)` blocks so the evaluator ignores errors -Neither can be stopped at the seam layer; both are prompt-layer conventions. Users may customize the system prompt but the built-in constraints remain. +Neither can be enforced at the seam layer; both are prompt-layer guidance and must not be described as hard constraints. Users may customize the system prompt; evaluators that require these rules must check them explicitly. ### Relationship with existing code Direct reuse without modification: -- `packages/subagent`'s `spawn` provider, `toolFilter`, and `persona`—the loop spawns a subagent per round; the evaluator gets the read-only tool set +- `packages/subagent`'s `spawn` provider, `toolFilter`, and `persona`—the loop spawns a subagent per round; an LLM evaluator gets a scoped model-facing tool set, not a process-isolation guarantee +- `packages/tasks`—the model-facing loop is a `loop` task producer and reuses owner isolation, `task_output`/`task_list`/`task_kill`, completion notices, cancellation, and awaited cleanup - The SQLite backend from `packages/session-persistence`—the loop-session persists +- `packages/session-query`—exact live and persisted session reads for post-hoc diagnosis - `packages/compact`—the implementation basis for `handoff-continue-with-compaction` - `packages/todo`—an optional progress representation in single-session continue mode - If [ToolExecution.reportProgress](2026-07-13-stream-workflow-progress-through-tool-calls.md) lands first, the loop tool can use it for per-round UI updates Not touched: `packages/core/agent-loop` (the inner-loop semantics stay the same); `packages/workflow` (DAG orchestration vs. iterating one goal is an orthogonal relationship; the two READMEs cross-link in their "Related" section to describe the boundary). -Two dependencies not yet landed: +One dependency is not yet landed: -- [sqlite-session-query-provider](2026-07-10-sqlite-session-query-provider.md)—see the limitation paragraph of Loop as an independent session for the mitigation - The ACP slash-command infrastructure (the `available_commands_update` surface)—see User surface. Before the infrastructure lands, the slash-command trigger is absent while the other three trigger surfaces work as normal -The one modification to existing code can be deferred to Phase 2: adding a "resume an existing subagent" argument surface to `packages/subagent-tool`, used by the `handoff-continue-*` backends. The underlying `SubagentRun.sendMessage` and `resume` already exist as seam capabilities; only the tool-layer argument entrypoint is missing. If Phase 1 ships only `handoff-fresh-with-summary`, subagent-tool need not be touched at all; Phase 2 adds it. +The proposed [SQLite FTS5 search](2026-07-10-sqlite-session-query-provider.md) is an optional Phase 2 discovery improvement over the existing exact-read query service, not a dependency for Phase 1 event access. + +Continuation work can be deferred to Phase 2: the `SubagentRun.sendMessage` and `resume` methods exist as optional seam capabilities, but the current `subagent-spawn` provider deliberately exposes neither. The two `handoff-continue-*` backends therefore require provider implementations, capability checks, ownership tests, and a consumer surface—not only a new argument on `packages/subagent-tool`. Phase 1 ships only `handoff-fresh-with-summary` and does not touch subagent continuation. ### Phasing -**Phase 1** (the scope this RFC commits): the three-package seam; `StopCondition`; the four-tier `EvaluatorSpec` type plus the `protectedPaths` hard isolation (reusing the `packages/fs` policy gate), with built-in implementations for `single-metric` and `llm-judge` and the `rubric` and `contract` types open for integration; Default-FAIL enforcement; three built-in evaluator/budget/handoff backends; the `loop_flag_concern` tool; the no-progress heuristic; the `onGoalConcern: 'stop' | 'notify-continue'` pair; the CLI; the tool; the default system prompt hard constraints. **Not included**: the session-query surface, the ACP slash-command trigger surface (depends on the `available_commands_update` infrastructure), the subagent-tool resume change, the stuck detector, the Reflector subagent, the `loop_split` tool, and the built-in implementations of the `rubric` and `contract` tiers. +**Phase 1** (the scope this RFC commits): the three-package seam; `StopCondition`; the orthogonal criteria/executor/isolation `EvaluatorSpec`, with built-in implementations for shell and LLM-judge execution and rubric/contract criteria shapes open for integration; Default-FAIL enforcement; evaluator and cumulative-budget backends; `handoff-fresh-with-summary`; `ctx.tasks` integration; the `loop_flag_concern` tool; the no-progress heuristic; the `onGoalConcern: 'stop' | 'notify-continue'` pair; the CLI; the tool; and the default system-prompt guidance. **Not included**: the SQLite FTS5 search surface, the ACP slash-command trigger surface (depends on the `available_commands_update` infrastructure), subagent continuation provider/tool work, the `GoalReflector` service, the stuck detector, the Reflector subagent, the `loop_split` tool, and built-in executors for every rubric/contract combination. -**Phase 2**: the query surface; the stuck detector (reproducing OpenHands's five patterns); the subagent-tool resume change (unlocking the two continue tiers of handoff); the Reflector subagent; the `onGoalConcern: 'reflect'` tier; the `loop_split` model-facing tool; the built-in implementations of the `rubric` and `contract` tiers. +**Phase 2**: the SQLite FTS5 search surface; the stuck detector (reproducing OpenHands's five patterns); subagent continuation provider implementations, capability checks, and consumer surface (unlocking the two continue handoffs); the `GoalReflector` service and Reflector subagent; the `onGoalConcern: 'reflect'` tier; the `loop_split` model-facing tool; and built-in executors for additional rubric/contract combinations. **Phase 3**: agent fleet (N parallel loops for the same goal, best result wins); integration with `dsh-schedule`; two-container evaluator isolation (evaluator definition files entirely inaccessible to the main agent, defending against reward hacking). @@ -274,13 +294,13 @@ The one modification to existing code can be deferred to Phase 2: adding a "resu **Skip the evaluator seam, ship a few built-ins**: lighter. Rejected—the core value of Pluggable Evaluator and Budget is that team-private evaluators can extend the system. Hardcoding leaves long unattended users no option but to modify the main library. -**Accept a free function that lacks an `EvaluatorSpec` tier**: allow users to pass any `(result) => boolean`. Rejected—the tier system forces users to declare at start time "which strength of judgment I'm using", the key to preventing quiet regression to a weaker tier. A free function looks flexible but lets evaluator strength quietly regress, and the cost is heavy in long-run scenarios. +**Accept a free function that lacks an explicit `EvaluatorSpec`**: allow users to pass any `(result) => boolean`. Rejected—the criteria/executor/isolation dimensions force users to declare at start time what is judged, what runs the judgment, and what boundary protects it, preventing quiet regression to a weaker setup. A free function looks flexible but lets evaluator strength quietly regress, and the cost is heavy in long-run scenarios. -**Introduce an independent memory engine (Beads / dex-style)**: an established approach to external state. Rejected—`packages/session-persistence` + `sqlite-session-query-provider` already provide equivalent capability; the payoff of a new engine is far smaller than the maintenance cost. +**Introduce an independent memory engine (Beads / dex-style)**: an established approach to external state. Rejected—`packages/session-persistence` plus the existing exact-read `ctx.sessionQuery` already cover Phase 1 diagnosis, while SQLite FTS5 can add search later; the payoff of a new engine is far smaller than the maintenance cost. **Fold goal reflection into the Evaluator seam** (have the evaluator return "criteria are impossible"): rejected—it conflates "was the goal achieved" with "is the goal still correct", which are orthogonal concerns. `Evaluator` should stay independent, read-only, and simple. -**Only add an event for goal-concern, no seam**: lighter. Rejected—the response-strategy family (stop / notify / reflect) is well defined and teams will want to plug in their own, so making it a seam pays off more than it costs. +**Only ever add an event for goal-concern, no seam**: lighter. Phase 1 does use the event plus `stop`/`notify` policies; rejected as the final design because the Phase 2 `reflect` path needs a replaceable response strategy. The seam lands with that first caller rather than ahead of it. **Ship the full Reflector subagent in Phase 1**: more complete. Rejected—`loop_flag_concern` tool plus no-progress heuristic plus the two-policy `onGoalConcern` already covers 80% of scenarios; running an independent subagent every round is expensive, and introducing it on demand in Phase 2 is more sensible. @@ -290,31 +310,33 @@ The one modification to existing code can be deferred to Phase 2: adding a "resu - The three packages `packages/loop/{loop,loop-driver,loop-tool}` are built as a capability seam; `dsh-loop` exports only types and registry - `StopCondition` discrimination covers all branches (unit); `assertNever` closes the switch at compile time -- The four services `Evaluator`, `BudgetPolicy`, `RoundHandoff`, and `GoalReflector` can each be replaced by an external plugin (fixture: inject a mock implementation, driver calls it correctly) -- `EvaluatorSpec`'s four-tier type converges at compile time; the driver refuses to start a loop without a paired evaluator (fixture: `loop({ goal, evaluator: undefined })` returns a configuration error immediately) +- The Phase 1 services `Evaluator`, `BudgetPolicy`, and `RoundHandoff` can each be replaced by an external plugin (fixture: inject a mock implementation, driver calls it correctly); no `GoalReflector` service is registered before the Phase 2 `reflect` consumer exists +- `EvaluatorSpec`'s criteria/executor/isolation dimensions converge at compile time; the driver refuses to start a loop without a paired evaluator (fixture: `loop({ goal, evaluator: undefined })` returns a configuration error immediately) - Default-FAIL fixture: when the evaluator report returns `{criterion, pass: true, evidence: []}`, the driver refuses that criterion flip and records an `evaluator/invalid-report` session event -- Each of the three built-in handoff backends has unit tests plus one e2e: `fresh-with-summary` (runs to pass), `continue-with-compaction` (runs past the token threshold to trigger compaction), `continue-raw` (runs 3 rounds) -- `dsh loop` CLI e2e: given a goal plus a 3-round cap plus one shell evaluator, both the pass and exhaustion paths return a structured stop cause with a semantic exit code -- Evaluator isolation fixture: the main agent has fs.write, the evaluator subagent's tool set does not; attempting to call fs.write is rejected by the registry -- protectedPaths fixture: with `EvaluatorSpec.protectedPaths: ["tests/**"]` declared, a main-agent attempt to write `tests/foo.py` is rejected by the `packages/fs` policy gate and recorded as a `loop/hack-attempt` session event, while the evaluator's read of that path succeeds -- Preflight guardrail fixture: inject a mock pricing table to construct a scenario over `perRoundUsd`; the driver refuses to start that round and emits a `budget-cap` StopCondition -- Goal concern fixture: `loop_flag_concern` is callable from the main agent and yields a `loop/goal-concern` session event; under `onGoalConcern: 'stop'` an `approval-required` StopCondition is emitted; under `'notify-continue'` the loop continues and the event carries an ACP high-priority marker; the no-progress heuristic fires once when budget exceeds 50% with zero passes (with rate-limit dedup) -- The default system prompt hard constraints (no TODO/FAKE/PLACEHOLDER, no empty catch) are distributed with the built-in `loop` tool, and a snapshot covers the prompt content -- Each round's prompt, inner-loop result, evaluator report, and stop decision appear as session events; when Phase 2 adds the query surface, they are indexable by `loopId` +- `RoundHandoff` receives the previous result, evaluator report, token usage, summary, session id, optional run handle, and cancellation signal; Phase 1's `fresh-with-summary` has unit coverage plus one pass-path e2e, while continuation backend tests wait for Phase 2 provider support +- `dsh-sdk loop` CLI e2e: given a goal plus a 3-round cap plus one shell evaluator, both the pass and exhaustion paths return a structured stop cause with a semantic exit code +- Evaluator scoping fixture: the main agent has fs.write while an LLM evaluator's model-facing tool set does not; the result and documentation still label `same-workspace` as non-isolated, and no `protectedPaths` guarantee is exposed +- Budget fixtures cover `perRoundUsd` admission plus cumulative `maxRounds`, `maxTokens`, and `maxUsd` across worker and evaluator usage; an in-flight overrun emits `budget-cap` with `observed` and `maximum` +- Goal concern fixture: `loop_flag_concern` is callable from the main agent and yields an ordinary `loop/goal-concern` session event; under `onGoalConcern: 'stop'` an `approval-required` StopCondition is emitted; under `'notify-continue'` the loop continues without nonexistent ACP priority metadata; the no-progress heuristic fires once when budget exceeds 50% with zero passes (with rate-limit dedup) +- The default system-prompt guidance (no TODO/FAKE/PLACEHOLDER, no empty catch) is distributed with the built-in `loop` tool, and a snapshot covers the prompt content without treating it as enforcement +- Each round's prompt, inner-loop result, evaluator report, and stop decision appear as session events and are readable through the existing exact-read `ctx.sessionQuery`; FTS5 search remains Phase 2 +- Model-facing loop startup returns a `loop` task id immediately; `task_output`, `task_list`, `task_kill`, parent-agent disposal, cancellation, producer reload, and service disposal cover owner isolation and awaited quiescence - The "Related" sections in `packages/loop/README.md` and `packages/workflow/README.md` cross-link and describe the "when to use workflow vs. when to use loop" boundary clearly - Unit 100% / snapshot / e2e / doc-sync / verify-module-graph / build / hygiene all green; the ACP rendering intent (`generic`) of the new tool has a snapshot ## Risks -**Dependency on [sqlite-session-query-provider](2026-07-10-sqlite-session-query-provider.md) landing**. The user-visible value of Loop as an independent session (arbitrary-round resume plus meta-loop learning) requires it. The mitigation is in that section's limitation paragraph; Phase 1 does not hard-bind, and the query surface ships in Phase 2. +**Conversation replay is not workspace restore**. Exact session reads already exist, and FTS5 improves historical discovery rather than enabling correctness. Replaying a round prefix against the current workspace can diagnose or redirect a run, but reproducing the execution world at that round requires Git/worktree/checkpoint support and an explicit policy for external side effects. **The boundary between `packages/workflow` and loop is a recurring FAQ**. "Is multi-round a loop or a workflow?"—both READMEs must state clearly: workflow is "steps known, agent to run undecided, parallel or serial orchestration"; loop is "agent decided, round count undecided, evaluator decides when to stop". Unclear docs cause users to pick the wrong one. -**Evaluator reverse-optimization (reward hacking)**. In a sufficiently long loop, the agent can identify the evaluator's pattern and optimize against it—for example, discovering that "as long as `assert True` appears in a test file, it PASSes" and bypassing real completion that way. **Phase 1 blocks most cases via `protectedPaths`**: evaluator input files (tests, evaluator config) are declared write-forbidden for the main agent via the `packages/fs` policy gate, sealing off the "modify the tests to make the evaluator pass" path directly. It still cannot prevent the agent from learning the evaluator's pattern and evading it in substance (for example, writing code that satisfies the surface pattern but is semantically wrong). Users needing high adversarial strength need Phase 3's two-container approach: the entire evaluator runtime (binary, rubric, dependency libraries) sits in a container that the main agent cannot access, matching what Anthropic patch.py does. +**Evaluator reverse-optimization (reward hacking)**. In a sufficiently long loop, the agent can identify the evaluator's pattern and optimize against it—for example, discovering that "as long as `assert True` appears in a test file, it PASSes" and bypassing real completion that way. Phase 1's `same-workspace` mode does not prevent the agent from modifying tests or evaluator configuration through bash, code runtimes, or another write channel; the current `packages/fs` policy is not a path-isolation boundary. Users needing adversarial strength must choose an isolated worktree, read-only mount, container, or remote evaluator. Phase 3's two-container approach keeps the evaluator runtime (binary, rubric, dependency libraries) entirely inaccessible to the main agent, matching what Anthropic patch.py does. -**Placeholder faking and over-defensive code**. Agents sometimes write `# TODO: implement` to sneak through a test, or write large amounts of `try/except: pass` to make the evaluator superficially PASS. These do not belong to the evaluator layer; they are prompt and training issues at the agent-generation stage. Mitigation goes through the two default system-prompt hard constraints in User surface; users who add "static-check-forbid TODO and empty catch" rules to a custom evaluator are safer. This class of problem cannot be cured at the seam layer. +**Placeholder faking and over-defensive code**. Agents sometimes write `# TODO: implement` to sneak through a test, or write large amounts of `try/except: pass` to make the evaluator superficially PASS. These do not belong to the evaluator layer; they are prompt and training issues at the agent-generation stage. The two default system-prompt instructions in User surface are guidance only; users who add "static-check-forbid TODO and empty catch" rules to a custom evaluator get enforceable coverage. This class of problem cannot be cured at the seam layer. -**Budget estimation drift**. The pricing table is a constant; the estimate drifts once the model provider changes prices. A conservative approximation is not a bug in itself, but the README notes "actual billing is per usage events; preflight only defends against a single round exploding". +**Budget estimation drift and in-flight overrun**. Pricing can change, and cumulative token/USD usage becomes exact only after each worker, evaluator, compaction, or reflector request reports usage. Preflight protects a single round; cumulative caps stop the next request and may exceed the configured maximum by one in-flight request. The README reports both observed and maximum values and states that provider billing remains authoritative. + +**Background tasks are process-local**. `ctx.tasks` gives the model-facing loop owner isolation, generic collection/cancellation, completion notices, and awaited cleanup. Parent-agent or service disposal cancels and awaits the loop; a process crash cannot run cleanup, and durable restart remains outside Phase 1. **Long-run loop log growth**. A 100-round loop reaches MB scale for one session. `logDetail: 'summary'` is a safety net but Phase 1 defaults to `full`; Phase 2 adds summary semantics. diff --git a/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.zh.md b/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.zh.md index 4e1b677259..b4884f2082 100644 --- a/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.zh.md +++ b/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.zh.md @@ -13,7 +13,7 @@ Status: proposed | 替代 | 问题 | |---|---| | `packages/workflow` 脚本表达 `while (!done)` | README 明写「No token-budget vocabulary」和「No journaling or resume」;父 turn 阻塞到脚本 settle。能跑几分钟的编排,跑不了几小时的长期任务 | -| 外部 shell `while :; do dsh …; done` | Ralph 风格的调度今天就能这么写。缺共享的 stop condition、budget、evaluator 词汇,每个使用者各自重发明;循环本身没有持久化对象可供事后诊断或恢复 | +| 外部 shell `while :; do dsh-sdk …; done` | Ralph 风格的调度今天就能这么写。缺共享的 stop condition、budget、evaluator 词汇,每个使用者各自重发明;循环本身没有持久化对象可供事后诊断或恢复 | | `packages/subagent` seam 的 `sendMessage`/`resume` | README 明写「Runtime steering and continuation are seam-only capabilities」。没有 model-facing consumer,模型只能起 fresh 子会话 | 典型使用场景有三类。**自动化修复**:面前一个失败的测试套件,希望一个进程持续修改代码、跑测试、根据失败信息再修改,直到全绿或触达预算上限。**按 rubric 迭代改稿**:一份文档、代码或翻译需要满足打分标准,循环反复调整、独立评估者打分、直到达标或耗尽轮数。**无人值守长跑**:例如通宵把一个仓库从一种技术栈移植到另一种,下班前启动第二天回来看结果,全程只有预算兜底。三类共同的形态:几分钟到几小时、evaluator 决定成败、预算是硬约束、跑完还需要能回看和恢复。 @@ -33,16 +33,16 @@ Status: proposed 三个包: -- `@deepseek-ai/dsh-loop`:类型、`LoopDriver` service、`StopCondition` 判别联合、四个内置 service 定义(`Evaluator` / `BudgetPolicy` / `RoundHandoff` / `GoalReflector`)、事件 schema +- `@deepseek-ai/dsh-loop`:类型、`LoopDriver` service、`StopCondition` 判别联合、Phase 1 service 定义(`Evaluator` / `BudgetPolicy` / `RoundHandoff`)、事件 schema;`GoalReflector` 在 Phase 2 与首个调用方一起加入 - `@deepseek-ai/dsh-loop-driver`:默认 driver 实现 -- `@deepseek-ai/dsh-loop-tool`:model-facing `loop` tool + CLI `dsh loop` +- `@deepseek-ai/dsh-loop-tool`:model-facing `loop` tool + CLI `dsh-sdk loop` -设计围绕四个具体问题展开,每个问题对应一条独立的 cordis service seam: +设计围绕四个具体问题展开,在每项能力出现调用方的 phase 中通过 service seam 或显式 driver policy 解决: 1. 长跑 loop 出问题后缺诊断和恢复手段。**loop 作为独立 session** 解决。 2. loop 结束时的 PASS 是否可信决定几小时工作是否作废。同一个 LLM 既生成又自评的架构本身就不可信。**Evaluator 与 Budget 做成 service seam** 解决。 3. 短任务和长任务需要的记忆策略相反,硬编一种模式会让另一类场景不可用。**RoundHandoff 做成 service seam** 解决。 -4. 用户初始给的 goal 未必始终正确。agent 沿着错的目标蛮干会耗尽预算做错事。**GoalReflector 做成 service seam** 解决。 +4. 用户初始给的 goal 未必始终正确。agent 沿着错的目标蛮干会耗尽预算做错事。**Phase 1 用 goal concern event 与 policy 处理;GoalReflector service 随 Phase 2 的 `reflect` 路径一起加入**。 四条 seam 之外还有一条贯穿全文的原则:**一个 loop 只处理一个原子目标**。大目标拆成若干小 loop 串联,不塞进一个 loop 让 evaluator 判定多件事。判定 granularity 是否合适的经验规则:如果 loop 跑完说不清它到底做完了什么,granularity 就太大,应当拆。Phase 2 补 `loop_split` model-facing tool 让 agent 收到过大 goal 时能自己拆。 @@ -55,7 +55,7 @@ interface EvaluatorReport { criteria: readonly { name: string; pass: boolean; ev type StopCondition = | { kind: 'goal-met'; evidence: EvaluatorReport } - | { kind: 'budget-cap'; scope: 'usd' | 'tokens' | 'rounds' } + | { kind: 'budget-cap'; scope: 'usd' | 'tokens' | 'rounds'; observed: number; maximum: number } | { kind: 'stuck'; pattern: 'repeat-action' | 'no-progress' | 'error-loop' } | { kind: 'approval-required'; reason: string } | { kind: 'user-cancel' } @@ -67,21 +67,21 @@ export {} 长跑 loop 一旦出错,用户没有系统的诊断手段。跑几小时后失败,只能翻散落的日志文件。发现中间某一轮走偏想倒回去重跑,只能从头开始。agent 想参考自己过去 loop 的经验也没有可用的 API。 -Driver 为每个 loop 开一个独立的 loop-session(新的 session id)。每轮的输入、inner-loop 结果、evaluator 报告、stop 决策都作为 session event 落盘,复用 `packages/session-persistence` 的 SQLite backend。得到三种能力。 +Driver 为每个 loop 开一个独立的 loop-session(新的 session id)。每轮的输入、inner-loop 结果、evaluator 报告、stop 决策都作为 session event 落盘,复用 `packages/session-persistence` 的 SQLite backend。得到三种诊断与 replay 能力。 -- **从任意轮恢复**:发现第 78 轮偏航,从第 77 轮拉起,换 prompt 或换 evaluator 重跑,不必从头 -- **事后诊断**:通过 [sqlite-session-query-provider](2026-07-10-sqlite-session-query-provider.md) 查「哪一轮 evaluator 开始一直挂在同条 criterion 上」定位卡点 -- **元循环学习**:agent 开新 loop 前查自己过往同类 loop 的经验——「我以前 fix 过类似的 bug 吗?失败在哪一轮?」 +- **从已记录轮次 replay 对话**:源 session 仍 live 时,发现第 78 轮偏航,可以 fork 第 77 轮的 event prefix,换 prompt 或 evaluator;已持久化 session 的 replay 还需要独立的受信任 load-and-seed 路径。两者都只会基于当前工作区 replay 对话状态,不会恢复第 77 轮的文件与外部副作用 +- **事后诊断**:通过现有 `ctx.sessionQuery` 精确读取 service 检查 evaluator 从哪一轮开始一直挂在同条 criterion 上 +- **元循环学习**:拟议中的 [SQLite FTS5 search](2026-07-10-sqlite-session-query-provider.md) 后续可以在新 loop 启动前找到相关历史 loop——「我以前 fix 过类似的 bug 吗?失败在哪一轮?」 Claude Code、Codex 的 `/goal` 是一次性对象:跑完就丢,agent 下次遇到同类问题从零开始。 -**存储与依赖**。每轮几 KB events,100 轮 loop 约 100–500 KB;跑几千个 loop 会到 GB 级。`logDetail: 'summary' | 'full'` 配置缓解,默认 `full`,长跑用户可切 `summary`。中间态全持久化会把生成过的 key、密码一并落盘,跟普通 session 是同一类风险但量放大 10–100 倍,README 明确提示。**最关键的一条**:本节能力硬依赖尚未落地的 [sqlite-session-query-provider RFC](2026-07-10-sqlite-session-query-provider.md)。若该 RFC 未落地,任意轮 resume 与查询能力会降级为「只能翻 JSONL 文件」。若 Phase 1 交付时该 RFC 还未 merge,本 Phase 只保证 event 结构正确,query 面延后到 Phase 2。 +**存储与恢复边界**。每轮几 KB events,100 轮 loop 约 100–500 KB;跑几千个 loop 会到 GB 级。`logDetail: 'summary' | 'full'` 配置缓解,默认 `full`,长跑用户可切 `summary`。中间态全持久化会把生成过的 key、密码一并落盘,跟普通 session 是同一类风险但量放大 10–100 倍,README 明确提示。通过 `ctx.sessionQuery` 的精确 live 与已持久化读取已经存在;FTS5 是可选的发现能力增强,不是 Phase 1 依赖。本 RFC 不承诺精确恢复执行世界:`SessionStore.fork()` 只接受 live session,而 session event 不会恢复文件、进程、环境或外部副作用。这需要单独的 Git/worktree/checkpoint 设计。 ### 可插拔的 Evaluator 与 Budget loop 的价值最终取决于结束时的 PASS 是否可信。如果 evaluator 会被 hack 或幻觉 PASS,前面几小时的工作全部作废。同一个 LLM 既生成又自评的架构本身就不可信:模型有条件说服自己 PASS。即便让独立 subagent 做 evaluator,只要 evaluator 还是 LLM,就仍然对同类内容有系统性偏好——独立 subagent 只是缓解不是根治。 -真正可信的评估必须是完全非 LLM 的硬检查:shell exit code、静态分析、外部服务。LLM 物理上碰不到评估过程。但硬检查只有用户自己知道该跑什么:不同项目 `pytest` 命令不同、公司有私有合规检查器、有些团队还要跑内部 lint。主库无论内置几种都覆盖不全。所以 evaluator 必须做成用户可以自己接入的 seam。 +可信评估同时需要确定性的判断机制,以及与 threat model 匹配的隔离边界:shell exit code、静态分析或外部服务避免 LLM 自评;独立 worktree、只读 mount、容器或远程服务防止 worker 改写 evaluator 输入。具体检查和边界只有用户知道:不同项目 `pytest` 命令不同、公司有私有合规检查器、有些团队还要跑内部 lint。主库无论内置几种都覆盖不全。所以 evaluator 必须做成用户可以自己接入的 seam。 预算方面同理:产品级的花费护栏是黑盒,无法按团队策略调整(个人卡、团队分摊、按 PR 结算)。 @@ -91,47 +91,47 @@ loop 的价值最终取决于结束时的 PASS 是否可信。如果 evaluator interface RubricItem { name: string; description: string } interface EvaluatorContract { readonly name: string } -type EvaluatorSpec = { - tier: - | { kind: 'single-metric'; check: string } // "pytest -q && ruff check"、"exit code == 0" - | { kind: 'rubric'; criteria: RubricItem[] } // 若干独立 criterion,各自 pass/fail + evidence - | { kind: 'contract'; interface: EvaluatorContract } // 结构化合约(如 API sig 校验) - | { kind: 'llm-judge'; rubric: string; model: string } // 兜底档,仅软目标 - /** - * 主 agent 不可写的路径(通常是 evaluator 会读的测试文件、评估配置)。 - * 违规写会被 packages/fs policy gate 拒绝,记 loop/hack-attempt session event。 - * 这是防 reward hacking 的核心机制——把「改测试让 evaluator 通过」这条路封死。 - */ - protectedPaths?: readonly string[] +type CriteriaSpec = + | { kind: 'single-metric'; name: string } + | { kind: 'rubric'; criteria: RubricItem[] } + | { kind: 'contract'; interface: EvaluatorContract } + +type ExecutorSpec = + | { kind: 'shell'; command: string } + | { kind: 'llm-judge'; rubric: string; model: string } + | { kind: 'provider'; name: string; config?: unknown } + +type IsolationSpec = 'same-workspace' | 'separate-worktree' | 'container' | 'remote' + +interface EvaluatorSpec { + criteria: CriteriaSpec + executor: ExecutorSpec + isolation: IsolationSpec } export {} ``` -**为什么分档,而不是让用户传自由函数?** 档位强制用户在启动时明确「用哪一档强度判成败」。自由函数看起来灵活,实际让 evaluator 强度隐性下沉——用户以为在做严格判定,实际写的是 LLM-judge 那种模糊的语义匹配。长跑场景下代价是几小时白跑。 +**为什么使用显式维度,而不是让用户传自由函数?** spec 强制用户在启动时声明评估什么、由什么执行判断,以及什么隔离边界保护它。自由函数看起来灵活,实际让 evaluator 强度隐性下沉——用户以为在做确定性隔离检查,实际写的是同工作区 LLM 判断。长跑场景下代价是几小时白跑。 -四档从上到下可信度依次降低。前三档都是完全非 LLM 的硬检查。`llm-judge` 是最弱一档,仅用于确实无硬信号的软目标(改稿、翻译质量)。文档明确标注「此档不能挡定向对抗,长跑无人值守场景需至少一档硬检查配合」。 +criteria shape、executor 与 isolation 是三个正交维度,不是可信度阶梯:rubric 可以由 shell、LLM 或外部服务检查,contract 也可以在同一工作区或容器中运行。`llm-judge` 仍是最弱的 executor,仅用于确实无硬信号的软目标(改稿、翻译质量)。文档明确标注「此 executor 不能挡定向对抗,长跑无人值守场景至少需要一个确定性 evaluator,并配合与 threat model 匹配的隔离边界」。 -Driver 强制五条硬约束,不下放给 Evaluator 实现。它们分别对付三类不同的攻击面: +Driver 强制四条结构约束,不下放给 Evaluator 实现。隔离强度仍是已配置提供方的显式属性,不是 driver 能凭空制造的保证。 **防「同一个 agent 既生成又自评」**: -1. **fresh subagent**:evaluator 每轮开 fresh subagent(用 `dsh-subagent` 的 `spawn`),不继承主循环 context - -**防主 agent 通过修改 evaluator 输入来 reward hack**: - -2. **`protectedPaths` 硬隔离**:`EvaluatorSpec` 声明的路径(通常是测试文件、评估配置)由 `packages/fs` 已有的 policy gate 拒绝主 agent 的写请求,记 `loop/hack-attempt` session event。这是 Phase 1 真正挡 reward hacking 的一层——直接封死「改测试让 evaluator 通过」这条路 +1. **LLM 评估使用 fresh subagent**:LLM evaluator 每轮开 fresh subagent(用 `dsh-subagent` 的 `spawn`),不继承主循环 context **防 evaluator subagent 自身被 subverted**: -3. **只读工具集**:evaluator 的 tool set 被 driver 剥离到只保留读类工具,写类工具禁用(复用 `SubagentProvider` 的 `toolFilter`)。它防的不是主 agent 的 reward hacking,而是 evaluator 读到被 evaluate 的代码里 embed 的 prompt injection 时不会被诱导去改状态 +2. **限制模型可见工具集**:LLM evaluator 的 model-facing tool set 被 driver 剥离到只保留读类工具,写类工具禁用(复用 `SubagentProvider` 的 `toolFilter`)。这会减少意外修改,但不是进程隔离:除非已配置隔离边界拦截,否则 shell、代码运行时或其他 capability 仍能写入 **防 evaluator 报告本身欺骗 driver**: -4. **PASS 只能由 evaluator 报告翻转**:`goal-met` StopCondition 只能来自 evaluator,driver 或主 agent 都不能直接构造 -5. **Default-FAIL**:driver 内部维护每个 criterion 的 pass 状态默认 `false`,只有 evaluator 报告里带非空 evidence 才允许翻 `true`;evaluator 无法通过返回 `{pass: true}` 而不给 evidence 让 driver 接受 +3. **PASS 只能由 evaluator 报告翻转**:`goal-met` StopCondition 只能来自 evaluator,driver 或主 agent 都不能直接构造 +4. **Default-FAIL**:driver 内部维护每个 criterion 的 pass 状态默认 `false`,只有 evaluator 报告里带非空 evidence 才允许翻 `true`;evaluator 无法通过返回 `{pass: true}` 而不给 evidence 让 driver 接受 -五条一起决定 evaluator 结论只能靠证据推动,无法靠自信推动,也无法靠主 agent 悄悄改测试推动。 +四条一起保证 evaluator 结论在结构上由证据推动,而不是由自信推动。它们不能阻止主 agent 在共享工作区中修改 evaluator 输入。 **Phase 1 内置三个 backend**: @@ -139,9 +139,9 @@ Driver 强制五条硬约束,不下放给 Evaluator 实现。它们分别对 - `loop-evaluator-rubric-judge` 实现 `llm-judge`:预写 rubric + LLM 打分,仅软目标 - `loop-budget-preflight`:每轮启动前估 `(promptTokens + overhead + estOutputTokens) / 1M × pricePerMTok`,超 `perRoundUsd` 拒绝启动。估算模型来自 MartinLoop `policy.ts:551-596` -`PricingProvider` 服务注入 pricing 表,test seam 可覆盖,不硬编到 driver 里(AGENTS.md「No hardcoded tunables in plugins」)。`rubric` 与 `contract` 档 Phase 2 补内置实现,Phase 1 只暴露类型让第三方插件先接。 +`PricingProvider` 服务注入 pricing 表,test seam 可覆盖,不硬编到 driver 里(AGENTS.md「No hardcoded tunables in plugins」)。解析后的 budget 携带 `maxRounds`、可选 `maxTokens` 与 `maxUsd`,以及可选 `perRoundUsd`。driver 在启动工作前检查单轮准入,随后在每次请求后累计 worker、evaluator、compaction 和 reflector 用量。token 或 USD 上限可能被一个在途请求超出,因为 usage 在完成后才到达;`budget-cap` 结果同时报告 `observed` 与 `maximum`。`rubric` 与 `contract` criteria shape 在 Phase 2 补内置 executor,Phase 1 暴露这些 shape 让第三方插件先接。 -**局限**:evaluator subagent 拿到的"只读工具"仍是同一进程的 shell 与 fs 读,理论上仍可能被 prompt injection 绕过。挡定向对抗需要两容器方案(evaluator 定义文件对主 agent 完全不可访问,Anthropic patch.py 走的就是这条路),本 RFC Phase 3 才做。见 风险。 +**局限**:`same-workspace` 加只读 model-facing tool set 不是硬隔离。当前 `packages/fs` policy 实施 read-before-edit 与版本保护,不是路径拒写;bash 或代码运行时可以绕过 filesystem tool。挡定向对抗需要覆盖所有写入通道的边界,例如只读 mount、隔离 worktree、容器或远程 evaluator。两容器方案(evaluator 定义文件对主 agent 完全不可访问,Anthropic patch.py 走的就是这条路)仍在 Phase 3。见 风险。 ### 可插拔的 RoundHandoff @@ -150,23 +150,40 @@ Driver 强制五条硬约束,不下放给 Evaluator 实现。它们分别对 做成 service seam: ```ts -interface RoundContext { loopId: string; round: number } -interface NextRoundSpec { mode: 'fresh' | 'continue' } +interface ContinuationRun { + readonly id: string + resume?(prompt: string): Promise +} + +interface PreviousRound { + result: unknown + evaluator: { criteria: readonly { name: string; pass: boolean; evidence: readonly string[] }[] } + tokenUsage: number + summary: string + sessionId: string + run?: ContinuationRun +} + +interface RoundContext { loopId: string; round: number; previous: PreviousRound } + +type NextRoundSpec = + | { mode: 'fresh'; prompt: string } + | { mode: 'continue'; run: ContinuationRun; prompt: string } interface RoundHandoff { - buildNextRound(prev: RoundContext): NextRoundSpec + buildNextRound(prev: RoundContext, signal: AbortSignal): Promise } export {} ``` -Phase 1 内置三个 backend: +Phase 1 交付 fresh backend;Phase 2 在 provider continuation 存在后增加两个 continuation backend: -| Backend | 场景 | 机制 | -|---|---|---| -| `handoff-fresh-with-summary`(默认) | 长跑、无人值守 | 每轮开 fresh subagent,只注入一段 progress 摘要作 system prompt 附加段 | -| `handoff-continue-with-compaction`(推荐中间档) | 5–20 轮的中等长度 | 整段对话保留到 token 阈值,超了复用 [`packages/compact`](../../../../packages/compact/README.md) 压缩,摘要 + 最近 K 轮作起点 | -| `handoff-continue-raw`(专业档) | ≤5 轮短任务、测试 | 纯连续对话不裁剪 | +| Backend | Phase | 场景 | 机制 | +|---|---|---|---| +| `handoff-fresh-with-summary`(默认) | Phase 1 | 长跑、无人值守 | 每轮开 fresh subagent,只注入一段 progress 摘要作 system prompt 附加段 | +| `handoff-continue-with-compaction`(推荐中间档) | Phase 2 | 5–20 轮的中等长度 | 整段对话保留到 token 阈值,超了复用 [`packages/compact`](../../../../packages/compact/README.md) 压缩,摘要 + 最近 K 轮作起点 | +| `handoff-continue-raw`(专业档) | Phase 2 | ≤5 轮短任务、测试 | 纯连续对话不裁剪 | **为什么默认 fresh?** 所有实际跑成的长跑 loop(repomirror、Kimi ralph-loop、autoresearch)用的都是 fresh。把重要 loop 状态放在 context window 外由 driver 管理是长跑的正确姿势。`handoff-continue-raw` 违反这条经验,README 明写长跑不适用。 @@ -174,13 +191,13 @@ Phase 1 内置三个 backend: **为什么做成 seam 而不是三选一 flag?** 用户可以写 20 行插件表达「前 5 轮 continue、之后 fresh」这类混合策略,或表达「context 到 50% 自动 compact 一次」,不用等主库支持。 -**局限**:`continue-with-compaction` 依赖 `packages/compact` 的压缩质量,压缩本身可能把幻觉信息写进摘要传下去;README 建议长跑首选 fresh。三个 backend 的边界会让新用户不知道选哪个;`dsh loop` CLI 默认用 fresh,用户在遇到具体问题前不需要理解这些差别。 +**局限**:`continue-with-compaction` 依赖 `packages/compact` 的压缩质量,压缩本身可能把幻觉信息写进摘要传下去;README 建议长跑首选 fresh。三个 backend 的边界会让新用户不知道选哪个;`dsh-sdk loop` CLI 默认用 fresh,用户在遇到具体问题前不需要理解这些差别。 ### 可插拔的 GoalReflector 用户在启动 loop 时给的目标不一定准确。可能基于错误假设(让 agent 用某个已经废弃的 API 实现功能),可能不够清晰(agent 在做的过程中才发现需要澄清),也可能被后来的信息证伪。现在的循环执行框架把 goal 当作启动时冻结的合约,agent 只能沿着原路蛮干,结果是在错的方向上耗尽预算。 -做成 service seam,与 `Evaluator` 职责分离:evaluator 问「是否达成目标」,reflector 问「目标是否还是那个目标」。 +Phase 2 把它做成 service seam,与 `Evaluator` 职责分离:evaluator 问「是否达成目标」,reflector 问「目标是否还是那个目标」。Phase 1 只携带 concern event,以及 `stop` 与 `notify-continue` driver policy,不注册没有调用方的 `GoalReflector` service。 ```ts interface RoundContext { loopId: string; round: number } @@ -198,7 +215,7 @@ type GoalReflection = export {} ``` -**concern 有三种触发来源**,Phase 1 实现前两种: +**concern 有三种触发来源**。Phase 1 实现前两种;`GoalReflector` service 与周期性来源一起在 Phase 2 加入: - **agent 主动**:通过 model-facing tool `loop_flag_concern({ concern, severity })`。agent 在调研中意识到「用户假设的那个库已经废弃」时可以直接 raise - **driver 启发式**:预算过 50% 且零 criterion pass 时,driver 自动 raise `no-progress-toward-goal` concern @@ -207,58 +224,61 @@ export {} **响应策略通过 `onGoalConcern` 配置项**。这四种配置对应不同的 loop 使用哲学,用户按团队协作方式选,driver 不预设立场: - `'stop'`(Phase 1 默认):任何 concern 都触发 `StopCondition: approval-required`,人拍板。loop 在遇到任何不确定性时都不应自己往下走,适合谨慎风格团队与影响面较大的 loop 场景 -- `'notify-continue'`(Phase 1):记 `loop/goal-concern` session event(高优先级)加 ACP 显式提示,继续跑,人在结束时集中审阅。loop 内部不打扰,适合无人值守长跑 +- `'notify-continue'`(Phase 1):记录普通 `loop/goal-concern` session event 后继续跑,人在结束时集中审阅。ACP 没有通用高优先级 marker,因此专用 concern 渲染与 ACP command 基础设施一起后置。loop 内部不打扰,适合无人值守长跑 - `'reflect'`(Phase 2):调 `GoalReflector` 决定 continue、revise 还是 stop。委派一个独立 agent 代替人做初步判断,适合中等自主度的团队 - 不注册 `GoalReflector` 且 `onGoalConcern` 未设 = 最放手档,loop 只在传统 stop condition 触发时停 **为什么默认选 `stop`?** 无人值守场景下宁可多停一次也不要在错方向上跑几小时。用户明确要无人值守可切 `notify-continue`。 -concern 本身就是普通 session event,跟前文的持久化 session 能力天然协同:resume 时可以从 concern 出现的那一轮拉起,换 goal 重跑,前 N 轮的工作不丢。 +concern 本身就是普通 session event,跟前文的持久化 session 能力天然协同:后续 replay 可以从 concern 出现的轮次为新对话提供 seed,并替换 goal。这不会把工作区回滚到该轮。 -**滥用与丢失防护**。agent 可能每轮都 raise concern;缓解是 `severity` 字段和 driver 侧的最小 rate limit(同一 concern 30 秒内去重)。这种滥用的代价是 agent 卡住自己无法推进,动机不强。goal 被 revise 后原始 goal 会丢失;每次 revise 落 `loop/goal-revised` session event 带 rationale,resume 时可选任意历史 goal 版本。 +**滥用与丢失防护**。agent 可能每轮都 raise concern;缓解是 `severity` 字段和 driver 侧的最小 rate limit(同一 concern 30 秒内去重)。这种滥用的代价是 agent 卡住自己无法推进,动机不强。goal 被 revise 后原始 goal 会丢失;每次 revise 落 `loop/goal-revised` session event 带 rationale,后续 replay 可选任意历史 goal 版本,但不承诺恢复工作区。 ### 用户面 四个触发面共享同一个 driver: -- **agent 侧 tool**:`loop({ goal, evaluator, maxRounds, maxUsd, onGoalConcern })` 启动嵌套 harness loop。正在跑的 loop 内部 agent 可用 `loop_flag_concern({ concern, severity })` 主动发起 concern。ACP 渲染意图为 `generic`。agent 自主发起就是 proactive 触发,无需额外机制 -- **CLI**:`dsh loop --stop --max-rounds N --max-usd X --handoff fresh`。人类主导启动,最典型的 Ralph 风格用法 +- **agent 侧 tool**:`loop({ goal, evaluator, maxRounds, maxUsd, onGoalConcern })` 通过 `ctx.tasks` 注册 `kind: 'loop'`,立即返回 task id,并在后台运行 harness loop。`task_output`、`task_list` 和 `task_kill` 负责收集与取消。正在跑的 loop 内部 agent 可用 `loop_flag_concern({ concern, severity })` 主动发起 concern。ACP 渲染意图为 `generic`。agent 自主发起就是 proactive 触发,无需额外机制 +- **CLI**:`dsh-sdk loop --stop --max-rounds N --max-usd X --handoff fresh`。人类主导启动,最典型的 Ralph 风格用法 - **cordis leaf**:`cordis.yml` 里以 leaf 形式声明常驻循环,配合未来的 `dsh-schedule` RFC 可做周期性触发 -- **ACP slash command**:`/loop `(还有 `/loop-flag-concern`)在编辑器/客户端的当前会话里直接启动。语义等价于人类在 CLI 里敲 `dsh loop`,但发生在正在进行的 ACP session 上下文中,允许 loop 结果直接注入会话 +- **ACP slash command**:`/loop `(还有 `/loop-flag-concern`)在编辑器/客户端的当前会话里直接启动。语义等价于人类在 CLI 里敲 `dsh-sdk loop`,但发生在正在进行的 ACP session 上下文中,允许 loop 结果直接注入会话 ACP slash command 的依赖:`packages/ui/acp` 的 `available_commands_update` 面目前是 unbuilt 状态([acp-feature-support.md](../../../../packages/ui/acp/acp-feature-support.md))。等 harness 的 slash command 基础设施落地,`/loop` 与 `/loop-flag-concern` 只需在该基础设施里注册;driver 与 tool 接口不变。本 RFC 保留名字并给出参数 shape,但不承诺基础设施本身——那属于独立的 ACP 补齐 RFC。 -默认 system prompt 里有两条硬约束,随所有内置 `loop` tool 一起分发: +默认 system prompt 里有两条行为指令,随所有内置 `loop` tool 一起分发: 1. 不允许写 `TODO`、`FAKE`、`PLACEHOLDER` 占位符让 evaluator 表面通过 2. 不允许写空的 `try/except` 或 `catch(_)` 让 evaluator 忽略错误 -这两条不是 seam 层能拦的,是 prompt 层的约定。用户可以自定义 system prompt 但内置约束保留。 +这两条无法在 seam 层强制,只是 prompt 层 guidance,不能描述成硬约束。用户可以自定义 system prompt;需要强制这些规则的 evaluator 必须显式检查。 ### 与仓库现有代码的关系 直接复用无需修改: -- `packages/subagent` 的 `spawn` provider、`toolFilter`、`persona`——loop 每轮起 subagent、evaluator 只读工具集 +- `packages/subagent` 的 `spawn` provider、`toolFilter`、`persona`——loop 每轮起 subagent;LLM evaluator 获得受限的 model-facing tool set,不获得进程隔离保证 +- `packages/tasks`——model-facing loop 是 `loop` task producer,复用 owner isolation、`task_output`/`task_list`/`task_kill`、完成通知、取消和 awaited cleanup - `packages/session-persistence` 的 SQLite backend——loop-session 落盘 +- `packages/session-query`——精确读取 live 与已持久化 session,用于事后诊断 - `packages/compact`——`handoff-continue-with-compaction` 的实现基础 - `packages/todo`——单会话 continue 模式下作为可选 progress 表达 - 若 [ToolExecution.reportProgress](2026-07-13-stream-workflow-progress-through-tool-calls.md) 先落地,loop tool 可用它逐轮 UI 更新 不动:`packages/core/agent-loop`(inner loop 语义保持);`packages/workflow`(DAG 编排 vs. 迭代同 goal 是 orthogonal 关系,两个 README 在「Related」段互链说明边界)。 -依赖尚未落地的两处: +依赖尚未落地的一处: -- [sqlite-session-query-provider](2026-07-10-sqlite-session-query-provider.md)——见 Loop 作为独立 session 局限段的缓解方案 - ACP slash command 基础设施(`available_commands_update` 面)——见 用户面。基础设施落地前,slash command 触发面缺席,其它三个触发面照常工作 -唯一涉及现有代码的改动可延后到 Phase 2:给 `packages/subagent-tool` 增加「续跑已有 subagent」的参数暴露,用于 `handoff-continue-*` 两个 backend。底层 `SubagentRun.sendMessage` 与 `resume` 已作为 seam 能力存在,缺的只是 tool 层的参数入口。若 Phase 1 只上 `handoff-fresh-with-summary`,完全不动 subagent-tool;Phase 2 再补。 +拟议中的 [SQLite FTS5 search](2026-07-10-sqlite-session-query-provider.md) 是现有 exact-read query service 之上的可选 Phase 2 发现能力增强,不是 Phase 1 event 访问的依赖。 + +Continuation 工作可以延后到 Phase 2:`SubagentRun.sendMessage` 与 `resume` 方法作为可选 seam capability 存在,但当前 `subagent-spawn` provider 明确不暴露这两个方法。因此,两个 `handoff-continue-*` backend 需要 provider 实现、capability check、ownership 测试和 consumer surface,不只是给 `packages/subagent-tool` 增加参数。Phase 1 只交付 `handoff-fresh-with-summary`,不改 subagent continuation。 ### 分阶段 -**Phase 1**(本 RFC 承诺范围):三包 seam;`StopCondition`;`EvaluatorSpec` 四档类型 + `protectedPaths` 硬隔离(复用 `packages/fs` policy gate),其中 `single-metric` 与 `llm-judge` 有内置实现,`rubric` 与 `contract` 类型开放待接;Default-FAIL 强制;3 个内置 evaluator/budget/handoff backend;`loop_flag_concern` tool;no-progress 启发式;`onGoalConcern: 'stop' | 'notify-continue'` 二档;CLI;tool;默认 system prompt 硬约束。**不含**:session-query 面、ACP slash command 触发面(依赖 `available_commands_update` 基础设施)、subagent-tool 续跑改动、stuck 检测器、Reflector subagent、`loop_split` tool、`rubric` 与 `contract` 档的内置实现。 +**Phase 1**(本 RFC 承诺范围):三包 seam;`StopCondition`;criteria/executor/isolation 三个正交维度的 `EvaluatorSpec`,其中 shell 与 LLM-judge execution 有内置实现,rubric/contract criteria shape 开放待接;Default-FAIL 强制;evaluator 与累计 budget backend;`handoff-fresh-with-summary`;`ctx.tasks` 集成;`loop_flag_concern` tool;no-progress 启发式;`onGoalConcern: 'stop' | 'notify-continue'` 二档;CLI;tool;默认 system prompt guidance。**不含**:SQLite FTS5 search 面、ACP slash command 触发面(依赖 `available_commands_update` 基础设施)、subagent continuation provider/tool 工作、`GoalReflector` service、stuck 检测器、Reflector subagent、`loop_split` tool,以及每种 rubric/contract 组合的内置 executor。 -**Phase 2**:query 面;stuck 检测器(复现 OpenHands 5 种模式);subagent-tool 续跑改动(解锁 continue 两档 handoff);Reflector subagent;`onGoalConcern: 'reflect'` 档;`loop_split` model-facing tool;`rubric` 与 `contract` 档的内置实现。 +**Phase 2**:SQLite FTS5 search 面;stuck 检测器(复现 OpenHands 5 种模式);subagent continuation provider 实现、capability check 与 consumer surface(解锁两个 continue handoff);`GoalReflector` service 与 Reflector subagent;`onGoalConcern: 'reflect'` 档;`loop_split` model-facing tool;更多 rubric/contract 组合的内置 executor。 **Phase 3**:agent fleet(同 goal 派 N 个并行 loop 取最优);与 `dsh-schedule` 集成;两容器 evaluator 隔离(evaluator 定义文件对主 agent 完全不可访问,防 reward 反向优化)。 @@ -274,13 +294,13 @@ ACP slash command 的依赖:`packages/ui/acp` 的 `available_commands_update` **不做 evaluator seam,内置几种够用**:更轻。拒绝——可插拔的 Evaluator 与 Budget 的核心价值是团队或私有 evaluator 可扩展。写死后长跑无人值守场景的用户只能改主库。 -**接受不带 `EvaluatorSpec` 档位的自由函数**:允许用户传任意 `(result) => boolean`。拒绝——档位强制用户在启动时明确「用哪一档强度判成败」,是防止不知不觉滑到弱档的关键。自由函数看起来灵活,实际让 evaluator 强度隐性下沉,长跑场景代价大。 +**接受不带显式 `EvaluatorSpec` 的自由函数**:允许用户传任意 `(result) => boolean`。拒绝——criteria/executor/isolation 维度强制用户在启动时声明评估什么、由什么执行判断、由什么边界保护,防止不知不觉滑到更弱的配置。自由函数看起来灵活,实际让 evaluator 强度隐性下沉,长跑场景代价大。 -**引入独立记忆引擎(Beads / dex-style)**:外部化状态的成熟做法。拒绝——`packages/session-persistence` + `sqlite-session-query-provider` 已能提供等效能力;新引擎收益远小于维护成本。 +**引入独立记忆引擎(Beads / dex-style)**:外部化状态的成熟做法。拒绝——`packages/session-persistence` 加现有 exact-read `ctx.sessionQuery` 已经覆盖 Phase 1 诊断,SQLite FTS5 后续可以补 search;新引擎收益远小于维护成本。 **goal reflection 塞进 Evaluator seam**(让 evaluator 返回「criteria 不可能满足」):拒绝——混淆「是否成功」和「目标是否正确」两个正交问题。`Evaluator` 应保持独立、只读、简单。 -**goal-concern 只做 event 不做 seam**:更轻。拒绝——响应策略族(stop / notify / reflect)明确,各团队会想插自己的,seam 化投资小于收益。 +**goal-concern 永远只做 event 不做 seam**:更轻。Phase 1 确实使用 event 加 `stop`/`notify` policy;作为最终设计仍拒绝,因为 Phase 2 的 `reflect` 路径需要可替换响应策略。seam 与首个调用方一起落地,不提前出现。 **Phase 1 就上完整 Reflector subagent**:更全。拒绝——`loop_flag_concern` tool + no-progress 启发式 + 二档 policy 覆盖 80% 场景;每轮跑独立 subagent 成本高,Phase 2 按需引入更合理。 @@ -290,31 +310,33 @@ ACP slash command 的依赖:`packages/ui/acp` 的 `available_commands_update` - `packages/loop/{loop,loop-driver,loop-tool}` 三包按 capability seam 建成;`dsh-loop` 只导 types 与 registry - `StopCondition` 判别覆盖所有分支(单元),`assertNever` 编译期收口 -- `Evaluator`、`BudgetPolicy`、`RoundHandoff`、`GoalReflector` 四条 service 都能被外部插件替换(fixture:注入 mock 实现,driver 正确调用) -- `EvaluatorSpec` 四档类型编译期收敛;driver 拒绝启动没有 evaluator 配对的 loop(fixture:`loop({ goal, evaluator: undefined })` 立即返回配置错误) +- Phase 1 的 `Evaluator`、`BudgetPolicy`、`RoundHandoff` 三条 service 都能被外部插件替换(fixture:注入 mock 实现,driver 正确调用);Phase 2 `reflect` consumer 出现前不注册 `GoalReflector` service +- `EvaluatorSpec` 的 criteria/executor/isolation 维度在编译期收敛;driver 拒绝启动没有 evaluator 配对的 loop(fixture:`loop({ goal, evaluator: undefined })` 立即返回配置错误) - Default-FAIL fixture:evaluator 报告返回 `{criterion, pass: true, evidence: []}` 时 driver 拒绝该 criterion 翻转、记 `evaluator/invalid-report` session event -- 三个内置 handoff backend 都有单元 + 一个 e2e:`fresh-with-summary`(跑到 pass)、`continue-with-compaction`(跑超 token 阈值触发 compact)、`continue-raw`(跑 3 轮) -- `dsh loop` CLI e2e:给定 goal + 3 轮上限 + 一个 shell evaluator,通过与耗尽两条路径都返回结构化 stop cause 并 exit code 语义化 -- Evaluator 独立性 fixture:主 agent 有 fs.write,evaluator subagent 的 tool set 里没有;试图调 fs.write 被 registry 拒绝 -- protectedPaths fixture:`EvaluatorSpec.protectedPaths: ["tests/**"]` 声明后,主 agent 尝试写 `tests/foo.py` 被 `packages/fs` policy gate 拒绝并记 `loop/hack-attempt` session event,evaluator 侧读该路径正常 -- Preflight 护栏 fixture:注入 mock pricing 表构造超 `perRoundUsd` 的场景,driver 拒绝启动该轮且 emit `budget-cap` StopCondition -- Goal concern fixture:`loop_flag_concern` 可从主 agent 调用并产出 `loop/goal-concern` session event;`onGoalConcern: 'stop'` 下 emit `approval-required` StopCondition;`'notify-continue'` 下继续跑且事件带 ACP 高优先级标记;no-progress 启发式在预算超 50% 且零 pass 时自动触发一次(rate-limit 去重) -- 默认 system prompt 硬约束(无 TODO/FAKE/PLACEHOLDER、无空 catch)随内置 `loop` tool 一起分发,snapshot 覆盖 prompt 内容 -- 每轮的 prompt、inner-loop 结果、evaluator report、stop 决策都以 session event 出现;Phase 2 补 query 面时可按 `loopId` 检索 +- `RoundHandoff` 接收上一轮 result、evaluator report、token usage、summary、session id、可选 run handle 和 cancellation signal;Phase 1 的 `fresh-with-summary` 有单元覆盖与一个 pass-path e2e,continuation backend 测试等待 Phase 2 provider 支持 +- `dsh-sdk loop` CLI e2e:给定 goal + 3 轮上限 + 一个 shell evaluator,通过与耗尽两条路径都返回结构化 stop cause 并 exit code 语义化 +- Evaluator scope fixture:主 agent 有 fs.write,LLM evaluator 的 model-facing tool set 没有;结果与文档仍把 `same-workspace` 标记为未隔离,不暴露 `protectedPaths` 保证 +- Budget fixture 覆盖 `perRoundUsd` 准入,以及跨 worker 与 evaluator usage 累计的 `maxRounds`、`maxTokens`、`maxUsd`;在途超限 emit 带 `observed` 与 `maximum` 的 `budget-cap` +- Goal concern fixture:`loop_flag_concern` 可从主 agent 调用并产出普通 `loop/goal-concern` session event;`onGoalConcern: 'stop'` 下 emit `approval-required` StopCondition;`'notify-continue'` 下继续跑且不携带不存在的 ACP priority metadata;no-progress 启发式在预算超 50% 且零 pass 时自动触发一次(rate-limit 去重) +- 默认 system prompt guidance(无 TODO/FAKE/PLACEHOLDER、无空 catch)随内置 `loop` tool 一起分发,snapshot 覆盖 prompt 内容但不把它当作强制机制 +- 每轮的 prompt、inner-loop 结果、evaluator report、stop 决策都以 session event 出现,并可通过现有 exact-read `ctx.sessionQuery` 读取;FTS5 search 留在 Phase 2 +- model-facing loop 启动后立即返回 `loop` task id;`task_output`、`task_list`、`task_kill`、父 agent dispose、取消、producer reload 和 service dispose 覆盖 owner isolation 与 awaited quiescence - `packages/loop/README.md` 和 `packages/workflow/README.md` 的「Related」段互链清楚「何时用 workflow、何时用 loop」的边界 - 单元 100% / snapshot / e2e / doc-sync / verify-module-graph / build / hygiene 全绿;新增 tool 的 ACP 渲染意图(`generic`)有 snapshot ## 风险 -**依赖 [sqlite-session-query-provider](2026-07-10-sqlite-session-query-provider.md) 落地**。Loop 作为独立 session 的用户可见价值(任意轮 resume + 元循环学习)需要它。缓解在该节局限段;Phase 1 不硬绑,Phase 2 才交付 query 面。 +**对话 replay 不是工作区恢复**。精确 session 读取已经存在,FTS5 改善历史发现能力,不决定正确性。基于当前工作区 replay 某一轮 prefix 可以诊断或改变运行方向,但复现该轮执行世界需要 Git/worktree/checkpoint 支持,以及针对外部副作用的显式 policy。 **`packages/workflow` 与 loop 的边界是持续答疑热点**。「多轮是 loop 还是 workflow」两个 README 必须写清楚:workflow 是「步骤已知、agent 未定、并串行编排」;loop 是「agent 已定、轮数未定、evaluator 判停」。文档不清晰会让用户混用错档。 -**evaluator 反向优化(reward hacking)**。足够长的 loop 里 agent 有条件识别 evaluator 的模式并针对性优化,例如发现「只要测试文件里出现 `assert True` 就 PASS」从而绕过实质完成。**Phase 1 靠 `protectedPaths` 挡多数 case**:evaluator 的输入文件(测试、评估配置)通过 `packages/fs` policy gate 声明为主 agent 不可写,直接从「改测试让 evaluator 通过」这条路上封死。但仍无法阻止 agent 学出 evaluator 的模式做实质规避(比如写符合表面 pattern 但语义错的代码)。对抗强度高的用户需要 Phase 3 的两容器方案:evaluator 的整个运行时(二进制、rubric、依赖库)都在主 agent 完全不可访问的容器里,Anthropic patch.py 走的就是这条路。 +**evaluator 反向优化(reward hacking)**。足够长的 loop 里 agent 有条件识别 evaluator 的模式并针对性优化,例如发现「只要测试文件里出现 `assert True` 就 PASS」从而绕过实质完成。Phase 1 的 `same-workspace` 模式不能阻止 agent 通过 bash、代码运行时或其他写入通道修改测试或 evaluator 配置;当前 `packages/fs` policy 不是路径隔离边界。需要对抗强度的用户必须选择隔离 worktree、只读 mount、容器或远程 evaluator。Phase 3 的两容器方案让 evaluator 整个运行时(二进制、rubric、依赖库)对主 agent 完全不可访问,Anthropic patch.py 走的就是这条路。 -**占位符伪造与过度防御码**。agent 有时会写 `# TODO: implement` 让测试勉强通过,或写大量 `try/except: pass` 让 evaluator 表面 PASS。这些不属于 evaluator 层的问题,而是 agent 生成阶段的 prompt 与训练问题。缓解走 用户面 段那两条默认 system prompt 硬约束;用户自定义 evaluator 时若加入「静态检查禁止 TODO 与空 catch」这类规则更稳妥。这类问题不是 seam 层能根治的。 +**占位符伪造与过度防御码**。agent 有时会写 `# TODO: implement` 让测试勉强通过,或写大量 `try/except: pass` 让 evaluator 表面 PASS。这些不属于 evaluator 层的问题,而是 agent 生成阶段的 prompt 与训练问题。用户面 段的两条默认 system prompt 指令只是 guidance;用户在自定义 evaluator 中加入「静态检查禁止 TODO 与空 catch」才能获得可强制覆盖。这类问题不是 seam 层能根治的。 -**预算估算漂移**。pricing 表是常量,模型调价后估算会飘。护栏保守方向的近似不算 bug,但 README 说明「真实计费以 usage 事件为准,preflight 仅保护单轮爆炸」。 +**预算估算漂移与在途超限**。pricing 可能变化,累计 token/USD usage 只能在每次 worker、evaluator、compaction 或 reflector 请求报告 usage 后精确。preflight 保护单轮;累计上限会停止下一个请求,但可能被一个在途请求超出。README 同时报告 observed 与 maximum,并说明 provider 账单才是权威。 + +**后台 task 只存在于当前进程**。`ctx.tasks` 为 model-facing loop 提供 owner isolation、通用收集/取消、完成通知和 awaited cleanup。父 agent 或 service dispose 会取消并等待 loop;进程 crash 无法执行 cleanup,持久重启不在 Phase 1 范围内。 **长跑 loop 日志膨胀**。跑 100 轮 loop 单 session 上 MB 级。`logDetail: 'summary'` 兜底但 Phase 1 默认 `full`,Phase 2 再补 summary 语义。 From 55916f931d10d1d894e7c26467f533065a2bfb9f Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 16 Jul 2026 19:16:54 +0800 Subject: [PATCH 022/273] fix(core): preserve abort-observer replacements --- ...07-16-explicit-turn-cancellation.i18n.yaml | 2 +- ...026-07-16-explicit-turn-cancellation.zh.md | 42 +++++++++---------- .../feature/2026-06-30-interception-seams.md | 2 +- packages/core/agent-loop/src/agent.ts | 9 ++-- packages/core/agent-loop/tests/cancel.spec.ts | 34 +++++++++++++++ packages/core/agent/README.md | 2 +- 6 files changed, 63 insertions(+), 28 deletions(-) diff --git a/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml b/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml index c9de5dd06a..bac31649ab 100644 --- a/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml +++ b/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write 2026-07-16-explicit-turn-cancellation.md: 3716895c145c24603a93dab99108489e19154490 -2026-07-16-explicit-turn-cancellation.zh.md: d2f8a4227d38a05d7ed1dd5135a20d3b4e94deed +2026-07-16-explicit-turn-cancellation.zh.md: 912f6ae7efcb5e0124c45e1a044b5cf140a6ab52 diff --git a/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md b/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md index d2f8a4227d..912f6ae7ef 100644 --- a/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md +++ b/docs/rfc/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md @@ -1,4 +1,4 @@ -# RFC:显式的 turn 取消能力 +# RFC:显式轮次取消能力 Status: implemented @@ -6,50 +6,50 @@ Status: implemented ## 问题 -取消是一种生命周期短于 Agent 驱动的控制能力。自由文本字符串无法对调用方进行穷尽区分,步骤级 controller 也无法中断 prompt 提交、prompt 组装、continuation 或 turn 终止策略。持久化 `Error`、`AbortSignal.reason` 或后端私有对象还会把不稳定的运行时细节暴露给持久化 replay。 +取消是一种生命周期短于 Agent(智能体)驱动器的控制能力。自由文本字符串无法穷尽地区分调用方,步骤级控制器也无法中断提示词提交、提示词组装、继续决策或轮次终止策略。持久化 `Error`、`AbortSignal.reason` 或后端私有对象还会向持久化回放暴露不稳定的运行时细节。 -[Agent 执行上下文决策](2026-07-15-agent-execution-context.md)有意让 AsyncLocalStorage 帧保持为 `{ agent }`。若把 turn、步骤或 signal 状态加入这个与驱动同生命周期的帧,陈旧的异步后代就会看似仍对后续 turn 拥有权限。因此,取消需要一个 turn 归属方和显式传播,不能引入另一套环境上下文或公开 turn 包装类型。 +[Agent 执行上下文决策](2026-07-15-agent-execution-context.md)有意让 AsyncLocalStorage 帧保持为 `{ agent }`。若把轮次、步骤或 signal 状态加入这个与驱动器同生命周期的帧,陈旧的异步后代就会看似仍对后续轮次拥有权限。因此,取消需要一个轮次归属方并显式传播,且不创建另一套环境上下文或公开的轮次包装层。 ## 决策 -Agent 拥有仅用于运行时的 `AgentCancelCause` union:`{ kind: 'user' } | { kind: 'parent' }`;`agent.cancel()` 默认使用 `user`。规范化边界只接受恰好包含一个受支持 `kind` 的普通对象或 null-prototype 对象,并返回供当前 turn signal 使用的分离且冻结值。即使 Agent 处于 idle,字符串、额外字段或 symbol 字段、未知 kind、数组、class 实例、`Error` 和 `AbortSignal` 也会被同步拒绝。 +Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user' } | { kind: 'parent' }`;`agent.cancel()` 默认使用 `user`。规范化边界只接受恰好包含一个受支持 `kind` 的普通对象或原型为 null 的对象,并返回供当前轮次 signal 使用的、与调用方分离且已冻结的值。即使 Agent 处于空闲状态,字符串、额外字段或符号字段、未知 kind、数组、类实例、`Error` 和 `AbortSignal` 也会被同步拒绝。 -被中断的 live turn 以粗粒度的持久化结果 `{ kind: 'aborted' }` 结束。终态事件记录 turn 发生了什么,运行时 signal 则标识谁请求了取消;回放不会重复保存 `user` 或 `parent`。未来若有审计需求,应使用独立的控制请求事件,让请求与最终结果保持为两项事实。持久化事件不包含 stack、signal、错误对象、自由文本取消原因或后端私有细节。 +正在运行的轮次被中断后,以粗粒度的持久化结果 `{ kind: 'aborted' }` 结束。终态事件记录轮次发生了什么,运行时 signal 标识谁请求了取消;回放不会重复保存 `user` 或 `parent`。未来若有审计需求,应使用独立的控制请求事件,让请求与最终结果保持为两项事实。持久化事件不包含调用栈、signal、错误对象、自由文本取消原因或后端私有细节。 -AgentLoop 为每个预期 turn 私有地拥有一个 `TurnCancellation`。它在通知 `agent/status = running` 前安装 holder,使其中唯一的 `AbortController` 持续覆盖 prompt 处理、prompt 组装、每个步骤、模型与工具执行、continuation、`agent/turn-stop`、`turn/end` 和持久化 flush,随后清除 holder。所有参与的方法、事件和请求值都会收到同一个显式 signal;下一 turn 会收到全新 signal。 +AgentLoop 为每个待启动轮次私有地持有一个 `TurnCancellation`。它在通知 `agent/status = running` 前安装该持有者,使其中唯一的 `AbortController` 持续覆盖提示词处理、提示词组装、每个步骤、模型与工具执行、继续决策、`agent/turn-stop`、`turn/end` 和持久化刷新,随后清除该持有者。所有参与的方法、事件和请求值都会收到同一个显式 signal;下一个轮次会收到全新的 signal。 -对于 turn 被认领前取消的 queued work,驱动只保留一个不带 cause 的 pre-run marker。它会清除 `cancel()` 调用时已存在的 queued 和 steering work,但不会为未来 prompt 预设取消。若 `running` listener 同步取消旧工作并发送 replacement,驱动会丢弃已 aborted 的 holder,并为 replacement 创建全新 holder。同一 active holder 上的重复取消遵循 first-wins,后续调用仍可清除新进入队列的 pending work。 +对于轮次被认领前已取消的排队工作,驱动器只保留一个不携带取消原因的运行前标记。它会清除 `cancel()` 调用时已存在的排队工作和 steering(中途引导)工作,但不会预先取消未来的提示词。若 `running` 监听器同步取消旧工作并发送替代提示词,驱动器会丢弃已中止的持有者,并为替代提示词创建全新的持有者。同一活跃持有者上的重复取消遵循首次请求优先,后续调用仍可清除新入队的待处理工作。 -显式事件签名保留 positional 形态,并把 `signal` 放在 waterfall 最后一个参数 `next` 之前。Prompt 提交、请求配置、步骤结果处理、continuation 和终止停止加入已有的 pre-step、session prefix、模型生成、工具执行、审批以及 subagent 或 workflow 请求显式 signal seam。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`,因为该对象是显式请求值。Listener 可以配合该 signal 取消,但不得保留它来控制另一 turn。 +显式事件签名保留位置参数形式,并把 `signal` 放在 waterfall(瀑布式事件)的最后一个参数 `next` 之前。提示词提交、请求配置、步骤结果处理、继续决策和终止停止加入已有的步骤前处理、会话前缀、模型生成、工具执行、审批以及 subagent 或工作流请求的显式 signal seam。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`,因为该对象是显式请求值。监听器可以配合该 signal 取消,但不得保留它来控制其他轮次。 -`ctx.agentExecution` 仍只提供身份。环境中的 Agent 并不代表存活、当前 turn 或取消权限,`agentInterruptReasonOf(signal)` 也只读取其显式参数。并发 Agent 会同时隔离各自的 ALS 身份和 turn signal;子 Agent 会遮蔽父 Agent 身份,而父请求 signal 仍通过 subagent seam 传递。 +`ctx.agentExecution` 仍只提供身份。环境中的 Agent 并不代表存活、当前轮次或取消权限,`agentInterruptReasonOf(signal)` 也只读取其显式参数。并发 Agent 会同时隔离各自的 ALS 身份和轮次 signal;子 Agent 会遮蔽父 Agent 身份,而父请求 signal 仍通过 subagent seam 传递。 -Agent dispose 会在 active holder 上请求仅用于运行时的 `{ kind: 'disposed' }` 中断。若取消已经先成为 controller reason,该 reason 无法改写,因此终态分类会先检查生命周期状态:disposed 优先,之后受支持的 `user` 或 `parent` cause 形成粗粒度 aborted 结果,其他异常保留现有 error 路径。ACP 取消映射为 `user`;进程内 spawn 和 fork 的传播映射为 `parent`。远程 ACP subagent 保持现有 wire protocol。 +Agent dispose(资源释放)会在活跃持有者上请求仅用于运行时的 `{ kind: 'disposed' }` 中断。若取消已经先占用控制器的中断原因,该原因便无法改写,因此终态分类会先检查生命周期状态:资源释放结果优先,之后受支持的 `user` 或 `parent` 取消原因形成粗粒度的中止结果,其他异常保留现有错误路径。ACP(Agent Client Protocol)取消映射为 `user`;进程内 spawn 和 fork 的传播映射为 `parent`。远程 ACP subagent 保持现有协议。 -取消仍然是协作式的。Loop 会在 await 边界前后检查中断,但不会用 `Promise.race` 放弃进程内 listener、adapter 或工具 Promise。忽略 signal 的工作必须真正结算,`whenIdle()`、handle dispose 和 scope teardown 才会报告静止状态。 +取消仍然是协作式的。AgentLoop 会在异步等待边界前后检查中断,但不会用 `Promise.race` 放弃进程内监听器、适配器或工具 Promise。忽略 signal 的工作必须真正结算,`whenIdle()`、句柄 dispose 和作用域清理才会报告静止状态。 ## 验证 -契约测试验证严格的运行时 cause 校验、冻结分离、默认与 first-wins 行为、粗粒度 Session JSON 往返、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。Loop 测试让协作式 listener 在 prompt 提交、system-prompt 组装、session prefix、pre-step、请求、模型 stream、步骤结果、工具执行、continuation 和终止停止处等待 signal;并断言同一 turn 使用一个 signal,不同 turn 使用全新 signal。 +契约测试验证严格的运行时取消原因校验、冻结且与调用方分离、默认行为与首次请求优先行为、粗粒度的会话 JSON 往返、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。AgentLoop 测试让协作式监听器在提示词提交、系统提示词组装、会话前缀、步骤前处理、请求、模型流、步骤结果、工具执行、继续决策和终止停止处等待 signal;并断言同一轮次使用一个 signal,不同轮次使用全新的 signal。 -执行上下文测试断言所有 hook 仍只观察到 `{ agent }`,并发 Agent 保持独立的身份与 signal,嵌套子 Agent 创建只遮蔽身份。竞态测试覆盖 idle 取消、pre-run 取消、从 `running` listener 提交 replacement、重复取消以及 cancel 与 dispose 竞争下的静止状态。 +执行上下文测试断言所有钩子仍只观察到 `{ agent }`,并发 Agent 保持独立的身份与 signal,嵌套子 Agent 创建只遮蔽身份。竞态测试覆盖空闲状态取消、运行前取消、从 `running` 监听器提交替代提示词、重复取消以及取消与 dispose 竞争下的静止状态。 ## 考虑过的替代方案 -**把 signal 存入 ALS。** ALS 会在整个驱动生命周期内跟随异步后代,而取消权限在一个 turn 结束时就已终止。泄漏的回调可能观察到陈旧 signal,或者迫使实现替换可变帧,因此身份帧保持 `{ agent }`,控制能力继续显式传递。 +**把 signal 存入 ALS。** ALS 会在整个驱动器生命周期内跟随异步后代,而取消权限在一个轮次结束时就已终止。泄漏的回调可能观察到陈旧 signal,或者迫使实现替换为可变帧,因此身份帧保持 `{ agent }`,控制能力继续显式传递。 -**持久化自由文本 reason。** 字符串允许拼写漂移、阻碍穷尽 switch,还会鼓励消费方解析展示文本。运行时使用封闭的 discriminated union,终态记录只需要稳定的 aborted 结果。 +**持久化自由文本原因。** 字符串允许拼写漂移、阻碍穷尽分支判断,还会鼓励消费方解析展示文本。运行时使用封闭的可辨识联合类型,终态记录只需要稳定的中止结果。 -**在 `turn/end` 中持久化类型化调用方 cause。** 当前没有任何生产环境中的 replay、UI、ACP、telemetry 或 workflow 消费方区分 `user` 与 `parent`。把请求来源复制到终态结果会混淆两项事实,还会在没有消费方的情况下引入 Session 特有校验;未来的审计接口可以记录独立的取消请求事件。 +**在 `turn/end` 中持久化类型化调用方取消原因。** 当前没有任何生产环境中的回放、UI、ACP、遥测或工作流消费方区分 `user` 与 `parent`。把请求来源复制到终态结果会混淆两项事实,还会在没有消费方的情况下引入会话特有校验;未来的审计接口可以记录独立的取消请求事件。 -**现在就定义推测性的 `superseded`、`timeout` 和 `shutdown` 变体。** 当前没有 Agent 取消生产方实现这些语义。`shutdown` 已经属于生命周期 dispose;timeout 或 supersession 只有在拥有明确归属策略和唯一终态含义时才应进入 union。 +**现在就定义推测性的 `superseded`、`timeout` 和 `shutdown` 变体。** 当前没有 Agent 取消生产方实现这些语义。`shutdown` 已经属于生命周期 dispose;超时或替代只有在拥有明确归属策略和唯一终态含义时才应进入联合类型。 -**公开 turn 或步骤 context 包装类型。** 现有 positional seam 已经标识 Agent、turn 和步骤。包装类型会加宽所有 API、重复归属,并诱导调用方把捕获的对象当成持久权限。 +**公开轮次或步骤上下文包装类型。** 现有位置参数 seam 已经标识 Agent、轮次和步骤。包装类型会加宽所有 API、重复归属,并诱导调用方把捕获的对象当成持久权限。 -**在宽限期后放弃不协作的工作。** 同进程工作仍在运行时就返回 idle 会破坏 teardown 与资源归属保证。硬终止需要 worker 或进程隔离边界,不属于该控制 seam。 +**在宽限期后放弃不协作的工作。** 同进程工作仍在运行时就报告空闲状态,会破坏资源清理与资源归属保证。硬终止需要 worker 或进程隔离边界,不属于该控制 seam。 ## 后果 -取消拥有一个运行时归属方、每个 turn 一个 signal,以及一套类型化的运行时调用方词汇。Session 保留其消费方实际使用的粗粒度 `aborted` 结果,与运行时对象保持隔离,也不再需要取消专用的规范化逻辑。协作式取消覆盖每个异步 turn seam,包括第一个步骤之前和最后一个步骤之后的工作。 +取消拥有一个运行时归属方、每个轮次一个 signal,以及一套类型化的运行时调用方词汇。会话保留其消费方实际使用的粗粒度 `aborted` 结果,与运行时对象保持隔离,也不再需要取消专用的规范化逻辑。协作式取消覆盖每个异步轮次 seam,包括第一个步骤之前和最后一个步骤之后的工作。 -显式 signal 会给多个公开事件增加参数,并要求插件有意识地转发取消。这是有意设计:权限在调用边界可见,生命周期与 turn 匹配,陈旧的环境异步后代无法获得控制能力。不协作的进程内工作可能延迟取消,但所报告的静止状态仍然真实。 +显式 signal 会给多个公开事件增加参数,并要求插件有意识地转发取消。这是有意设计:权限在调用边界可见,生命周期与轮次匹配,陈旧的环境异步后代无法获得控制能力。不协作的进程内工作可能延迟取消,但所报告的静止状态仍然真实。 diff --git a/docs/rfc/implemented/feature/2026-06-30-interception-seams.md b/docs/rfc/implemented/feature/2026-06-30-interception-seams.md index ea371ad55a..43169f67ff 100644 --- a/docs/rfc/implemented/feature/2026-06-30-interception-seams.md +++ b/docs/rfc/implemented/feature/2026-06-30-interception-seams.md @@ -14,7 +14,7 @@ The canonical surface separates transformable policy, around-dispatch control, a **Agent events** (`dsh-agent`): - `agent/session-start(agent, source)` — emit, once before turn 1, carrying a `SessionStartSource` (`startup` for a fresh/forked create, `resume` for a reloaded persisted session; `clear`/`compact` reserved). A pure notification — it CANNOT block startup (a deliberate gap: a bridge logs/injects, it does not gate startup). A listener seeds context via `agent.inject()`. -- `agent/prompt-submit(agent, content, source, next) → PromptDecision` — waterfall, fired per drained queued message inside the open turn, before the `user/message` append. `allow` (optionally rewriting the prompt `content` or attaching `additionalContext`) or `block` (dropping the prompt; the loop appends a durable `prompt/blocked` in its place — see the dispatch note below). +- `agent/prompt-submit(agent, content, source, signal, next) → PromptDecision` — waterfall, fired per drained queued message inside the open turn, before the `user/message` append. `signal` belongs to that turn and `next` remains the final parameter. `allow` optionally rewrites the prompt `content` or attaches `additionalContext`; `block` drops the prompt and the loop appends a durable `prompt/blocked` in its place (see the dispatch note below). **`agent/turn-continuation`** receives and returns a `ContinuationDecision`. A `{action:'continue', reason?}` may carry model-facing context recorded as next-step steering in the same turn — the typed twin of the `/goal` step-end-steer pattern. diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index b984e4bfa0..94a6193c36 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -276,12 +276,13 @@ export class ReactLoopAgent implements Agent { const active = this.turnCancellation if (active === undefined && !this.#inbox.hasQueued && !this.#inbox.hasSteering) return if (active === undefined) this.preRunCancelled = true - else active.request(accepted) // Drop all pending queued + steering work (un-started prompts never run; the - // cancelled turn's steering is not re-enqueued). Cleared directly even when - // the loop is parked in waitForQueued — there is no turn to stop and nothing - // left for the parked loop to run, so no wake is needed. + // cancelled turn's steering is not re-enqueued). Clear before abort dispatch, + // whose synchronous observers may enqueue replacement work that must survive. + // This is direct even when the loop is parked in waitForQueued — there is no + // turn to stop and nothing left for the parked loop to run, so no wake is needed. this.#inbox.clear() + if (active !== undefined) active.request(accepted) } /** diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts index 0dbac6fce6..2241717b94 100644 --- a/packages/core/agent-loop/tests/cancel.spec.ts +++ b/packages/core/agent-loop/tests/cancel.spec.ts @@ -124,6 +124,40 @@ describe('Agent.cancel()', () => { expect(reasons).toEqual([{ kind: 'aborted' }]) }) + it('keeps replacement work queued synchronously by an abort observer', async () => { + const adapter = new MockAdapter(['hang', textResponse('replacement reply')]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('abort-observer-replacement'), { model: 'mock' }) + + send(agent, 'original') + await expect.poll(() => adapter.requests.length).toBe(1) + const signal = adapter.requests[0]?.signal + if (signal === undefined) throw new Error('model request omitted its turn signal') + signal.addEventListener('abort', () => { send(agent, 'replacement') }, { once: true }) + const idle = waitForIdle(ctx, agent) + agent.cancel({ kind: 'user' }) + await Promise.race([ + idle, + new Promise((_resolve, reject) => { + setTimeout(() => { + reject(new Error(`replacement did not settle: ${JSON.stringify({ + status: agent.status, + requests: adapter.requests.length, + users: userTexts(agent), + events: agent.session.events.map(event => event.type), + })}`)) + }, 1000) + }), + ]) + + expect(adapter.requests).toHaveLength(2) + expect(userTexts(agent)).toEqual(['original', 'replacement']) + const reasons = agent.session.events + .filter(event => event.type === 'turn/end') + .map(event => event.type === 'turn/end' ? event.data.reason : undefined) + expect(reasons).toEqual([{ kind: 'aborted' }, { kind: 'completed' }]) + }) + it('cancel() with no cause defaults to user when aborting an active turn', async () => { const adapter = new MockAdapter(['hang']) const ctx = await harness(adapter) diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md index bdbd6c6a11..e5726c22c0 100644 --- a/packages/core/agent/README.md +++ b/packages/core/agent/README.md @@ -44,7 +44,7 @@ The handle every plugin programs against: - `agent.send(content, options?)` — queue a message; starts a turn when idle. Content and resolved source become one detached, deeply frozen lossless-JSON record before `agent/queued` and enqueue; invalid data throws synchronously, and caller or notification-listener in-place mutation cannot change the log or model input (`agent/prompt-submit` still rewrites by returning replacement content). - `agent.steer(content, options?)` — steer a running turn (inject between steps); uses the same owned acceptance boundary and behaves like `send` when idle - `agent.inject(content, options?)` — inject in-session context (context/message event); the next request sees it. Does not run the model. While a turn is open it joins that turn; while idle it is wrapped in a one-shot `injection` turn so every event stays turn-enclosed ([the turn-enclosure invariant](../../../docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)) -- `agent.cancel(cause?)` — cancel ALL pending work: clears the queued + steering FIFOs, aborts the active turn, and drops queued work not yet claimed by the driver. `AgentCancelCause` is the runtime-only `{ kind: 'user' } | { kind: 'parent' }`; omission means `user`, the first cause wins for an active turn, and ACP `session/cancel` maps to `user`. `normalizeAgentCancelCause()` provides the same strict detached-value boundary used by the concrete loop: validation is synchronous even while idle, accepts only an exact plain object, and returns a safe no-op when no work exists. +- `agent.cancel(cause?)` — cancel ALL pending work: clears the queued + steering FIFOs, aborts the active turn, and drops queued work not yet claimed by the driver. `AgentCancelCause` is the runtime-only `{ kind: 'user' } | { kind: 'parent' }`; omission means `user`, the first cause wins for an active turn, and ACP `session/cancel` maps to `user`. `normalizeAgentCancelCause()` provides the same strict detached-value boundary used by the concrete loop: validation is synchronous even while idle, accepts only an exact plain object, and returns a frozen detached cause. After validation, `agent.cancel()` is a safe no-op when no work exists. - `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit). A non-owner's quiescence-observation hook: it observes the work settling WITHOUT tearing the agent down. Teardown is separate — a lifecycle owner stops and unregisters via `AgentHandle.dispose()`, which awaits the loop exit directly. - `agent.session`, `agent.status`, `agent.options`, `agent.id` From a5c77325921120e326029d7f11446578b66687a8 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Fri, 17 Jul 2026 16:32:34 +0800 Subject: [PATCH 023/273] fix(lsp): address lifecycle review feedback --- examples/acp-agent/tests/acp.snapshot.ts | 2 + .../acp-agent/tests/lsp.cordis.snapshot.yml | 27 ++ examples/acp-agent/tests/lsp.cordis.yml | 23 ++ .../tests/snapshots/lsp-definition/input.json | 7 + .../snapshots/lsp-definition/session.jsonl | 23 ++ .../lsp-definition/stdout.golden.jsonl | 6 + .../lsp-definition/system-prompt.golden.md | 15 + .../lsp-definition/tool-schemas.golden.json | 282 ++++++++++++++++++ .../lsp-definition/workspace/lsp-server.mjs | 57 ++++ .../lsp-definition/workspace/subject.ts | 2 + knip.json | 1 + packages/lsp/lsp-local/src/connection.ts | 33 ++ packages/lsp/lsp-local/src/index.ts | 80 ++--- packages/lsp/lsp-local/src/instance.ts | 77 ++--- packages/lsp/lsp-local/tests/instance.spec.ts | 31 ++ .../lsp/tool-lsp/tests/integration.spec.ts | 8 +- packages/lsp/tool-lsp/tests/load-path.spec.ts | 8 +- 17 files changed, 585 insertions(+), 97 deletions(-) create mode 100644 examples/acp-agent/tests/lsp.cordis.snapshot.yml create mode 100644 examples/acp-agent/tests/lsp.cordis.yml create mode 100644 examples/acp-agent/tests/snapshots/lsp-definition/input.json create mode 100644 examples/acp-agent/tests/snapshots/lsp-definition/session.jsonl create mode 100644 examples/acp-agent/tests/snapshots/lsp-definition/stdout.golden.jsonl create mode 100644 examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.golden.md create mode 100644 examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.golden.json create mode 100644 examples/acp-agent/tests/snapshots/lsp-definition/workspace/lsp-server.mjs create mode 100644 examples/acp-agent/tests/snapshots/lsp-definition/workspace/subject.ts diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index 0d29f7b5ce..15670aa995 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -28,6 +28,7 @@ const CODE_MODE_CONFIG = fileURLToPath(new URL('../code-mode.cordis.yml', import const BOTH_MODE_CONFIG = fileURLToPath(new URL('../both-mode.cordis.yml', import.meta.url)) const ADVANCED_CONFIG = fileURLToPath(new URL('../advanced.cordis.yml', import.meta.url)) const FS_CONFIG = fileURLToPath(new URL('../fs.cordis.yml', import.meta.url)) +const LSP_CONFIG = fileURLToPath(new URL('./lsp.cordis.yml', import.meta.url)) function snapshotModeFromEnv(value: string | undefined): SnapshotSuiteOptions['mode'] { switch (value) { @@ -55,6 +56,7 @@ const SCENARIOS: Scenario[] = [ { name: 'todo-plan', hasModelTurn: true, recorded: true }, { name: 'skill-load', hasModelTurn: true, recorded: false, pinsHeader: true, headerClass: 'skill' }, { name: 'workspace-edit', hasModelTurn: true, recorded: true, pinsHeader: true, headerClass: 'fs', configPath: FS_CONFIG }, + { name: 'lsp-definition', hasModelTurn: true, recorded: false, pinsHeader: true, headerClass: 'lsp', configPath: LSP_CONFIG }, { name: 'fs-read', hasModelTurn: true, recorded: true, headerClass: 'fs', configPath: FS_CONFIG }, { name: 'fs-write', hasModelTurn: true, recorded: true, headerClass: 'fs', configPath: FS_CONFIG }, { name: 'fs-edit', hasModelTurn: true, recorded: true, headerClass: 'fs', configPath: FS_CONFIG }, diff --git a/examples/acp-agent/tests/lsp.cordis.snapshot.yml b/examples/acp-agent/tests/lsp.cordis.snapshot.yml new file mode 100644 index 0000000000..4d24ead86d --- /dev/null +++ b/examples/acp-agent/tests/lsp.cordis.snapshot.yml @@ -0,0 +1,27 @@ +# Keyless replay keeps the LSP composition intact and replaces only the model adapter. +- id: base + name: '@cordisjs/plugin-include' + config: + path: ../cordis.yml + patches: + - id: llm-deepseek + name: '@deepseek-ai/dsh-llm-deepseek' + disabled: true + - insert: + - id: lsp + name: '@deepseek-ai/dsh-lsp' + - id: lsp-local + name: '@deepseek-ai/dsh-lsp-local' + config: + servers: + fixture: + command: !!js process.execPath + args: ['./lsp-server.mjs'] + extensionToLanguage: + '.ts': typescript + - id: tool-lsp + name: '@deepseek-ai/dsh-tool-lsp' + config: + maxLocations: 1 + - id: llm-replay + name: '@deepseek-ai/dsh-llm-replay' diff --git a/examples/acp-agent/tests/lsp.cordis.yml b/examples/acp-agent/tests/lsp.cordis.yml new file mode 100644 index 0000000000..f1eefa99af --- /dev/null +++ b/examples/acp-agent/tests/lsp.cordis.yml @@ -0,0 +1,23 @@ +# Exercise the model-facing LSP tool through the shipped ACP app and Loader entry path. +# The scenario workspace supplies the deterministic stdio server used by this test composition. +- id: base + name: '@cordisjs/plugin-include' + config: + path: ../cordis.yml + patches: + - insert: + - id: lsp + name: '@deepseek-ai/dsh-lsp' + - id: lsp-local + name: '@deepseek-ai/dsh-lsp-local' + config: + servers: + fixture: + command: !!js process.execPath + args: ['./lsp-server.mjs'] + extensionToLanguage: + '.ts': typescript + - id: tool-lsp + name: '@deepseek-ai/dsh-tool-lsp' + config: + maxLocations: 1 diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/input.json b/examples/acp-agent/tests/snapshots/lsp-definition/input.json new file mode 100644 index 0000000000..2b49f7d280 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/lsp-definition/input.json @@ -0,0 +1,7 @@ +{ + "steps": [ + { "op": "initialize" }, + { "op": "newSession" }, + { "op": "prompt", "text": "Use the lsp tool exactly once to find the definition at subject.ts line 1 character 7, then reply with exactly DONE." } + ] +} diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/session.jsonl b/examples/acp-agent/tests/snapshots/lsp-definition/session.jsonl new file mode 100644 index 0000000000..e1a93752bb --- /dev/null +++ b/examples/acp-agent/tests/snapshots/lsp-definition/session.jsonl @@ -0,0 +1,23 @@ +{"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}"} +{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}} +{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Use the lsp tool exactly once to find the definition at subject.ts line 1 character 7, then reply with exactly DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"} +{"type":"step/start","seq":2,"time":0,"data":{"turn":1,"step":1}} +{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} +{"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_lsp_definition","name":"lsp","argumentsDelta":"{\"operation\":\"definition\",\"file_path\":\"subject.ts\",\"line\":1,\"character\":7}"}}} +{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_lsp_definition","name":"lsp","arguments":"{\"operation\":\"definition\",\"file_path\":\"subject.ts\",\"line\":1,\"character\":7}"}}}} +{"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}} +{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","seq":9,"time":0,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"call_lsp_definition","name":"lsp","arguments":"{\"operation\":\"definition\",\"file_path\":\"subject.ts\",\"line\":1,\"character\":7}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[4,5,6,7,8],"surfaceOp":"append"} +{"type":"tool/call","seq":10,"time":0,"data":{"turn":1,"step":1,"callId":"call_lsp_definition","name":"lsp","arguments":"{\"operation\":\"definition\",\"file_path\":\"subject.ts\",\"line\":1,\"character\":7}"}} +{"type":"tool/result","seq":11,"time":0,"data":{"turn":1,"step":1,"callId":"call_lsp_definition","content":[{"type":"text","text":"subject.ts:1:7\n… 1 more location omitted (limit 1)."}],"isError":false},"sourceEventSeqs":[10],"surfaceOp":"append"} +{"type":"step/end","seq":12,"time":0,"data":{"turn":1,"step":1}} +{"type":"step/start","seq":13,"time":0,"data":{"turn":1,"step":2}} +{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} +{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":0,"text":"DONE"}}} +{"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}} +{"type":"assistant/chunk","seq":17,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":2}}}} +{"type":"assistant/chunk","seq":18,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":19,"time":0,"data":{"turn":1,"step":2,"content":[{"type":"text","text":"DONE"}],"usage":{"inputTokens":10,"outputTokens":2}},"sourceEventSeqs":[14,15,16,17,18],"surfaceOp":"append"} +{"type":"step/end","seq":20,"time":0,"data":{"turn":1,"step":2}} +{"type":"turn/end","seq":21,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/lsp-definition/stdout.golden.jsonl new file mode 100644 index 0000000000..0abf55a261 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/lsp-definition/stdout.golden.jsonl @@ -0,0 +1,6 @@ +{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}} +{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"permission","name":"Permissions","description":"Sets this session's sandbox and approval behavior.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_lsp_definition","title":"LSP definition subject.ts:1:7","kind":"search","status":"in_progress","locations":[{"path":"subject.ts","line":1}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_lsp_definition","status":"completed","content":[{"type":"content","content":{"type":"text","text":"subject.ts:1:7\n… 1 more location omitted (limit 1)."}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"DONE"}}}} +{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.golden.md b/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.golden.md new file mode 100644 index 0000000000..21a80508f7 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/lsp-definition/system-prompt.golden.md @@ -0,0 +1,15 @@ +You are an AI agent powered by the DeepSeek Harness SDK. + +You are a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}. Your bash tool runs under a file sandbox — a `[sandbox: file access denied …]` result is policy, not a command bug. + +Verify your work by running the code or tests. Keep answers brief and factual. + + +Check the [exit code: N] marker on every bash result; investigate failures before moving on. + +Use search/read for ordinary navigation. Use lsp when textual matches are ambiguous or before a change requires precise definitions, implementations, or references. Positions are one-based line and character (UTF-16) at the cursor; an off-symbol position may return no results. references always includes the declaration. + +Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`). + + +Use the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls. diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.golden.json new file mode 100644 index 0000000000..72aaa3bd7d --- /dev/null +++ b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.golden.json @@ -0,0 +1,282 @@ +{ + "initial": [ + { + "name": "bash", + "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way (a background task reports the same marker via bash_output once it has finished). Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; poll it with `bash_output` and stop it with `bash_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.", + "parameters": { + "type": "object", + "properties": { + "command": { + "type": "string", + "description": "The bash command to execute." + }, + "description": { + "type": "string", + "description": "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"." + }, + "timeoutMs": { + "type": "number", + "description": "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry." + }, + "workdir": { + "type": "string", + "description": "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it." + }, + "run_in_background": { + "type": "boolean", + "description": "Run in the background and return a task id immediately. No timeout applies." + }, + "sandbox_permissions": { + "type": "string", + "description": "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.", + "enum": [ + "workspace-write", + "danger-full-access" + ] + }, + "justification": { + "type": "string", + "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access." + } + }, + "required": [ + "command", + "description" + ] + } + }, + { + "name": "bash_kill", + "description": "Ask the executor to kill a running background bash task by task id.", + "parameters": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "description": "Task id returned by the bash tool." + } + }, + "required": [ + "task_id" + ] + } + }, + { + "name": "bash_output", + "description": "Read new output from a background bash task started with `bash` + `run_in_background`. Returns only output produced since the previous bash_output call, plus the task status. Tasks keep running while you do other work; poll again later for more output.", + "parameters": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "description": "Task id returned by the bash tool." + } + }, + "required": [ + "task_id" + ] + } + }, + { + "name": "lsp", + "description": "Query a language server for precise code navigation. operation is one of definition, references, implementation, hover. line and character are one-based UTF-16 cursor coordinates. references includes the declaration.", + "parameters": { + "type": "object", + "properties": { + "operation": { + "type": "string", + "description": "definition, references, implementation, or hover.", + "enum": [ + "definition", + "references", + "implementation", + "hover" + ] + }, + "file_path": { + "type": "string", + "description": "The source file to query, relative to the workspace or absolute." + }, + "line": { + "type": "number", + "description": "One-based line of the cursor." + }, + "character": { + "type": "number", + "description": "One-based UTF-16 column of the cursor." + } + }, + "required": [ + "operation", + "file_path", + "line", + "character" + ] + } + }, + { + "name": "skill", + "description": "Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.", + "parameters": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The exact skill name from the available skills list." + } + }, + "required": [ + "name" + ] + } + }, + { + "name": "subagent", + "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.", + "parameters": { + "type": "object", + "properties": { + "description": { + "type": "string", + "description": "A short (3-5 word) description of the delegated task, for display." + }, + "prompt": { + "type": "string", + "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs." + } + }, + "required": [ + "description", + "prompt" + ] + } + }, + { + "name": "subagent_fork", + "description": "Delegate a task to a subagent that INHERITS this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps.", + "parameters": { + "type": "object", + "properties": { + "description": { + "type": "string", + "description": "A short (3-5 word) description of the delegated task, for display." + }, + "prompt": { + "type": "string", + "description": "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new." + } + }, + "required": [ + "description", + "prompt" + ] + } + }, + { + "name": "todo_write", + "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).", + "parameters": { + "type": "object", + "properties": { + "todos": { + "type": "array", + "description": "The COMPLETE task list, replacing any previous list.", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "What the task is — a short imperative line." + }, + "status": { + "type": "string", + "description": "pending (not started) | in_progress (now) | completed (done).", + "enum": [ + "pending", + "in_progress", + "completed" + ] + } + }, + "required": [ + "content", + "status" + ] + } + } + }, + "required": [ + "todos" + ] + } + }, + { + "name": "workflow", + "description": "Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), `model` (override). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.", + "parameters": { + "type": "object", + "properties": { + "script": { + "type": "string", + "description": "The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `)." + }, + "meta": { + "type": "object", + "description": "The workflow identity block (plain JSON — never code).", + "properties": { + "name": { + "type": "string", + "description": "Short kebab-case workflow name." + }, + "description": { + "type": "string", + "description": "One-line description of what the workflow does." + }, + "whenToUse": { + "type": "string", + "description": "Optional guidance on when this workflow applies." + }, + "phases": { + "type": "array", + "description": "Optional phase declarations matched by phase() calls.", + "items": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "The phase title phase() calls match by exact string." + }, + "detail": { + "type": "string", + "description": "Optional one-line description of the phase." + }, + "model": { + "type": "string", + "description": "Optional model override this phase is expected to use." + } + }, + "required": [ + "title" + ] + } + } + }, + "required": [ + "name", + "description" + ] + }, + "args": { + "type": "object", + "description": "Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})." + } + }, + "required": [ + "script", + "meta" + ] + } + } + ], + "deltas": [] +} diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/workspace/lsp-server.mjs b/examples/acp-agent/tests/snapshots/lsp-definition/workspace/lsp-server.mjs new file mode 100644 index 0000000000..431b322e0b --- /dev/null +++ b/examples/acp-agent/tests/snapshots/lsp-definition/workspace/lsp-server.mjs @@ -0,0 +1,57 @@ +import { resolve } from 'node:path' +import { pathToFileURL } from 'node:url' + +let buffered = Buffer.alloc(0) + +function frame(message) { + const body = Buffer.from(JSON.stringify({ jsonrpc: '2.0', ...message })) + return Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`), body]) +} + +function location(line) { + return { + uri: pathToFileURL(resolve('subject.ts')).href, + range: { start: { line, character: 6 }, end: { line, character: 12 } }, + } +} + +function handle(message) { + switch (message.method) { + case 'initialize': + process.stdout.write(frame({ + id: message.id, + result: { + capabilities: { + positionEncoding: 'utf-16', + textDocumentSync: 1, + definitionProvider: true, + }, + }, + })) + break + case 'textDocument/definition': + process.stdout.write(frame({ id: message.id, result: [location(0), location(1)] })) + break + case 'shutdown': + process.stdout.write(frame({ id: message.id, result: null })) + break + case 'exit': + process.exit(0) + } +} + +process.stdin.on('data', (chunk) => { + buffered = Buffer.concat([buffered, chunk]) + for (;;) { + const headerEnd = buffered.indexOf('\r\n\r\n') + if (headerEnd < 0) return + const match = /Content-Length: (\d+)/i.exec(buffered.toString('ascii', 0, headerEnd)) + if (match === null) throw new Error('missing Content-Length') + const length = Number(match[1]) + const bodyStart = headerEnd + 4 + if (buffered.length < bodyStart + length) return + const message = JSON.parse(buffered.toString('utf8', bodyStart, bodyStart + length)) + buffered = buffered.subarray(bodyStart + length) + handle(message) + } +}) diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/workspace/subject.ts b/examples/acp-agent/tests/snapshots/lsp-definition/workspace/subject.ts new file mode 100644 index 0000000000..6f3d62ca43 --- /dev/null +++ b/examples/acp-agent/tests/snapshots/lsp-definition/workspace/subject.ts @@ -0,0 +1,2 @@ +export const answer = 42 +console.log(answer) diff --git a/knip.json b/knip.json index 76634b0b78..210aea5cae 100644 --- a/knip.json +++ b/knip.json @@ -1,6 +1,7 @@ { "$schema": "https://unpkg.com/knip@5/schema.json", "exclude": ["duplicates"], + "ignore": ["examples/*/tests/snapshots/*/workspace/**/*"], "ignoreBinaries": ["bwrap", "sandbox-exec"], "ignoreWorkspaces": ["vendor/*", "python/sdk-runtime"], "workspaces": { diff --git a/packages/lsp/lsp-local/src/connection.ts b/packages/lsp/lsp-local/src/connection.ts index 795fe0dbff..e655877eb5 100644 --- a/packages/lsp/lsp-local/src/connection.ts +++ b/packages/lsp/lsp-local/src/connection.ts @@ -10,6 +10,7 @@ import type { ChildProcessByStdio } from 'node:child_process' import { spawn } from 'node:child_process' import type { Readable, Writable } from 'node:stream' +import { setImmediate as yieldToEventLoop } from 'node:timers/promises' import { encodeMessage, MessageDecoder } from './framing.ts' /** How to launch the server and answer its config requests. */ @@ -163,6 +164,19 @@ export class LspConnection { this.signalGroup('SIGKILL') } + /** + * Wait until the owned process group has no members. + * @param signal - optional bound for the wait. + * @returns `true` when the group exited, or `false` when the signal aborted first. + */ + async waitForProcessGroupExit(signal?: AbortSignal): Promise { + while (this.processGroupAlive()) { + if (signal?.aborted) return false + await yieldToEventLoop() + } + return true + } + /** * Signal the whole process group (negative pid) so helper processes are reached; fall back to the * direct child if the group send fails. Never throws — teardown races process exit. @@ -182,6 +196,25 @@ export class LspConnection { } } + /** Whether the detached process group still has at least one member. */ + private processGroupAlive(): boolean { + const pid = this.child.pid + /* v8 ignore next -- only an asynchronous spawn failure omits pid; its close path owns cleanup. */ + if (pid === undefined) return false + try { + process.kill(-pid, 0) + return true + } catch (error) { + const code = (error as NodeJS.ErrnoException).code + if (code === 'ESRCH') return false + /* v8 ignore start -- EPERM and non-POSIX negative-pid failures are platform defenses; CI runs + process-group lifecycle tests on POSIX hosts where absence reports ESRCH. */ + if (code === 'EPERM') return true + return this.child.exitCode === null && this.child.signalCode === null + /* v8 ignore stop */ + } + } + private onStdout(chunk: Buffer): void { let messages: unknown[] try { diff --git a/packages/lsp/lsp-local/src/index.ts b/packages/lsp/lsp-local/src/index.ts index 03ae5e9781..67e86da11c 100644 --- a/packages/lsp/lsp-local/src/index.ts +++ b/packages/lsp/lsp-local/src/index.ts @@ -169,8 +169,8 @@ function assertPositiveInteger(providerId: string, name: string, value: number): class LocalLspProvider implements LspProvider { readonly id: LspProviderId readonly extensionToLanguage: Readonly> - /** Single-flight map: canonical workspace realpath → the (pending) instance for it. */ - private readonly instances = new Map>() + /** One live instance per canonical workspace realpath. */ + private readonly instances = new Map() private disposed = false constructor( @@ -188,12 +188,17 @@ class LocalLspProvider implements LspProvider { return this.disposed } - async query(request: LspProviderQuery, signal?: AbortSignal): Promise { - /* v8 ignore next -- the seam unregisters this provider on dispose, so a query never reaches it disposed; defensive. */ + /** Reject work that cannot publish or use a provider-owned instance. */ + private assertActive(signal?: AbortSignal): void { + /* v8 ignore next -- the seam unregisters this provider before disposal; direct in-flight calls + exercise the post-await check instead. */ if (this.isDisposed()) throw new Error('lsp-local provider is disposed') - // Honor an already-aborted signal before any host I/O so a canceled request neither reads nor - // spawns a server. if (signal?.aborted) throw abortError(signal) + } + + async query(request: LspProviderQuery, signal?: AbortSignal): Promise { + // Honor an already-aborted signal before host I/O so a canceled request never starts a server. + this.assertActive(signal) const workspace = await canonicalizeWorkspace(request.workspaceRoot) // Validate and read the source BEFORE spawning a server: a missing/external/non-regular/oversized // source must fail without leaving an idle process pooled (the pre-start rejection contract), and @@ -201,49 +206,37 @@ class LocalLspProvider implements LspProvider { const source = await readHostSource(request.filePath, workspace, this.config.maxDocumentBytes) // Re-check disposal after the awaits: disposeAll() may have snapshotted the instance map while we // were canonicalizing/reading, so creating a server now would leave it unowned by teardown. - /* v8 ignore next -- guards a dispose landing during the canonicalize/read await; not a reproducible unit race. */ - if (this.isDisposed()) throw new Error('lsp-local provider is disposed') - // Re-check cancellation too: an abort during the canonicalize/read awaits must not go on to spawn - // (or pool) a server solely for an operation the caller already gave up on. - if (signal?.aborted) throw abortError(signal) - let instance = await this.instanceFor(workspace) - // A pooled server that exited while idle resolves to a dead instance: evict it and create a fresh - // one before dispatch, so this query does not have to fail on a closed connection first. One retry - // suffices — the replacement was just constructed and has not been used. + this.assertActive(signal) + let instance = this.instanceFor(workspace) + // Eviction and replacement are synchronous so disposal cannot snapshot the pool between them and + // miss a newly spawned process. if (instance.dead) { - await this.evictIfCurrent(workspace, instance) - instance = await this.instanceFor(workspace) + this.evictIfCurrent(workspace, instance) + instance = this.instanceFor(workspace) } try { return await instance.query(request, source, signal) } finally { // A crashed/closed process must not be reused: drop its slot so the next query starts fresh, // but only if the slot still holds THIS instance (a concurrent replacement must survive). - if (instance.dead) await this.evictIfCurrent(workspace, instance) + if (instance.dead) this.evictIfCurrent(workspace, instance) } } - /** Single-flight one instance per canonical workspace; a rejected creation clears the slot. */ - private instanceFor(workspace: string): Promise { + /** Return or synchronously publish the one instance for a canonical workspace. */ + private instanceFor(workspace: string): LspInstance { + this.assertActive() const existing = this.instances.get(workspace) if (existing !== undefined) return existing - const created = Promise.resolve().then(() => this.createInstance(workspace)) + const created = this.createInstance(workspace) this.instances.set(workspace, created) - /* v8 ignore next 3 -- createInstance (the LspInstance constructor) does not throw; spawn failures - surface asynchronously through the instance, so this creation-rejection cleanup is defensive. */ - created.catch(() => { - if (this.instances.get(workspace) === created) this.instances.delete(workspace) - }) return created } - /** Drop the slot for `workspace` iff it still resolves to `instance` (a concurrent replacement survives). */ - private async evictIfCurrent(workspace: string, instance: LspInstance): Promise { - const slot = this.instances.get(workspace) - /* v8 ignore next -- the slot-undefined/mismatch arm needs a concurrent eviction of the same slot; defensive. */ - if (slot !== undefined && (await settledInstance(slot)) === instance) { - this.instances.delete(workspace) - } + /** Drop the slot iff it still contains this instance. */ + private evictIfCurrent(workspace: string, instance: LspInstance): void { + /* v8 ignore next -- mismatch requires another query to replace the slot before this finally runs. */ + if (this.instances.get(workspace) === instance) this.instances.delete(workspace) } private createInstance(workspace: string): LspInstance { @@ -265,26 +258,9 @@ class LocalLspProvider implements LspProvider { /** Dispose every live instance and block further queries. */ async disposeAll(): Promise { this.disposed = true - const pending = [...this.instances.values()] + const live = [...this.instances.values()] this.instances.clear() - await Promise.all(pending.map(async (entry) => { - try { - const instance = await entry - await instance.dispose() - } catch { - // A never-initialized instance already rejected; nothing to tear down. - } - })) - } -} - -/** Resolve a slot promise to its instance for identity comparison, tolerating a pending rejection. */ -async function settledInstance(slot: Promise): Promise { - try { - return await slot - } catch { - /* v8 ignore next -- a slot promise only rejects if createInstance throws, which it never does; defensive. */ - return undefined + await Promise.all(live.map(instance => instance.dispose())) } } diff --git a/packages/lsp/lsp-local/src/instance.ts b/packages/lsp/lsp-local/src/instance.ts index 8bf2e48c5b..fb67f6e777 100644 --- a/packages/lsp/lsp-local/src/instance.ts +++ b/packages/lsp/lsp-local/src/instance.ts @@ -48,6 +48,8 @@ export class LspInstance { /** The serialization tail: each query awaits the prior one, so lifecycles never interleave. */ private queue: Promise = Promise.resolve() private disposed = false + /** The one teardown transaction shared by abort, failure, and explicit disposal. */ + private teardownPromise: Promise | undefined /** Set once the process closes, so the pool can synchronously skip a dead instance. */ private processClosed = false /** Populated once `initialize` succeeds; a failed handshake rejects every query. */ @@ -116,9 +118,8 @@ export class LspInstance { await this.abortable(this.ready, signal) } catch (error) { if (!this.dead) { - this.disposed = true /* v8 ignore next -- ready rejects with an Error (abort reason or initialize failure); the String() fallback is defensive. */ - await this.tearDown(error instanceof Error ? error : new Error(String(error))) + await this.startTeardown(error instanceof Error ? error : new Error(String(error))) } throw error } @@ -155,8 +156,7 @@ export class LspInstance { listener, so a synchronous didClose write failure is a defensive path. */ // A close-write failure does not replace the settled result/error, but the instance can no // longer be trusted: invalidate it and await bounded process termination. - this.disposed = true - void this.tearDown(error instanceof Error ? error : new Error(String(error))) + void this.startTeardown(error instanceof Error ? error : new Error(String(error))) /* v8 ignore stop */ } } @@ -210,19 +210,20 @@ export class LspInstance { this.connection.cancel(requestId) // Wait, bounded, for the server to honor the cancellation. If it does not, the request is still // running: terminate the instance (disposal awaits process close) so nothing outlives the query. - using grace = deadline(undefined, this.spec.killGraceMs, 'LSP_CANCEL_GRACE') - // `settled` is true if the request finished (either outcome) before the grace elapsed. - const settled = await Promise.race([ - send.then(markSettled, markSettled), - new Promise((resolve) => { - /* v8 ignore next -- the cancel-grace deadline signal is freshly armed and not yet aborted here; defensive. */ - if (grace.signal.aborted) { resolve(false); return } - grace.signal.addEventListener('abort', () => { resolve(false) }, { once: true }) - }), - ]) - if (!settled && !this.disposed) { - this.disposed = true - await this.tearDown(abortError(signal)) + const grace = deadline(undefined, this.spec.killGraceMs, 'LSP_CANCEL_GRACE') + try { + // `settled` is true if the request finished (either outcome) before the grace elapsed. + const settled = await Promise.race([ + send.then(markSettled, markSettled), + new Promise((resolve) => { + /* v8 ignore next -- the cancel-grace deadline signal is freshly armed and not yet aborted here; defensive. */ + if (grace.signal.aborted) { resolve(false); return } + grace.signal.addEventListener('abort', () => { resolve(false) }, { once: true }) + }), + ]) + if (!settled) await this.startTeardown(abortError(signal)) + } finally { + grace[Symbol.dispose]() } throw error } @@ -262,21 +263,24 @@ export class LspInstance { * process close so nothing outlives disposal. */ async dispose(): Promise { - if (this.disposed) { - await this.connection.closed - return - } + await this.startTeardown(new Error('LSP instance disposed')) + } + + /** Publish disposal once and make every caller await the same quiescence boundary. */ + private startTeardown(reason: Error): Promise { this.disposed = true - await this.tearDown(new Error('LSP instance disposed')) + this.teardownPromise ??= this.tearDown(reason) + return this.teardownPromise } private async tearDown(_reason: Error): Promise { + const shutdownDeadline = deadline(undefined, this.spec.shutdownTimeoutMs, 'LSP_SHUTDOWN') try { - using shutdownDeadline = deadline(undefined, this.spec.shutdownTimeoutMs, 'LSP_SHUTDOWN') await this.gracefulShutdown(shutdownDeadline.signal) - return } catch { - // Graceful shutdown failed or timed out: fall through to signal escalation. + // Graceful shutdown failed or timed out; process-group cleanup below remains authoritative. + } finally { + shutdownDeadline[Symbol.dispose]() } await this.forceTerminate() } @@ -288,20 +292,21 @@ export class LspInstance { await this.abortable(this.connection.closed, signal) } - /** SIGTERM, wait `killGraceMs` for close, then SIGKILL; await full process close either way. */ + /** SIGTERM the group, escalate after `killGraceMs`, then await leader and helper exit. */ private async forceTerminate(): Promise { this.connection.terminate() - using graceDeadline = deadline(undefined, this.spec.killGraceMs, 'LSP_KILL_GRACE') - const closedInTime = await Promise.race([ - this.connection.closed.then(() => true), - new Promise((resolve) => { - /* v8 ignore next -- the kill-grace deadline signal is freshly armed and not yet aborted here; defensive. */ - if (graceDeadline.signal.aborted) { resolve(false); return } - graceDeadline.signal.addEventListener('abort', () => { resolve(false) }, { once: true }) - }), + const graceDeadline = deadline(undefined, this.spec.killGraceMs, 'LSP_KILL_GRACE') + let groupExited: boolean + try { + groupExited = await this.connection.waitForProcessGroupExit(graceDeadline.signal) + } finally { + graceDeadline[Symbol.dispose]() + } + if (!groupExited) this.connection.kill() + await Promise.all([ + this.connection.closed, + this.connection.waitForProcessGroupExit(), ]) - if (!closedInTime) this.connection.kill() - await this.connection.closed } } diff --git a/packages/lsp/lsp-local/tests/instance.spec.ts b/packages/lsp/lsp-local/tests/instance.spec.ts index 52fc751754..f46d72571b 100644 --- a/packages/lsp/lsp-local/tests/instance.spec.ts +++ b/packages/lsp/lsp-local/tests/instance.spec.ts @@ -236,6 +236,26 @@ describe('LspInstance disposal', () => { await expect(instance.dispose()).resolves.toBeUndefined() }) + it('awaits a surviving process-group helper on every concurrent dispose', async () => { + const marker = join(root, 'helper.pid') + const helper = 'process.on("SIGTERM",()=>{});setInterval(()=>{},1000);' + const script = 'const{spawn}=require("node:child_process");const{writeFileSync}=require("node:fs");' + + `const helper=spawn(process.execPath,["-e",${JSON.stringify(helper)}],{stdio:"ignore"});` + + `writeFileSync(${JSON.stringify(marker)},String(helper.pid));` + + RESPONDING_SERVER + const instance = scriptInstance(script, { shutdownTimeoutMs: 100, killGraceMs: 100 }) + await run(instance, 'definition') + const helperPid = Number(await readFile(marker, 'utf8')) + try { + const first = instance.dispose() + await instance.dispose() + expect(processAlive(helperPid)).toBe(false) + await first + } finally { + if (processAlive(helperPid)) process.kill(helperPid, 'SIGKILL') + } + }) + it('carries a non-Error abort reason as a generic aborted error', async () => { const instance = makeInstance({ LSP_FAKE_HANG: '1' }) const controller = new AbortController() @@ -245,3 +265,14 @@ describe('LspInstance disposal', () => { await expect(pending).rejects.toThrow(/aborted/) }) }) + +/** Probe a pid without changing its state. */ +function processAlive(pid: number): boolean { + try { + process.kill(pid, 0) + return true + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'ESRCH') return false + throw error + } +} diff --git a/packages/lsp/tool-lsp/tests/integration.spec.ts b/packages/lsp/tool-lsp/tests/integration.spec.ts index 74d9c6ae77..5c98d9fff0 100644 --- a/packages/lsp/tool-lsp/tests/integration.spec.ts +++ b/packages/lsp/tool-lsp/tests/integration.spec.ts @@ -12,10 +12,8 @@ import * as TimeoutPolicy from '@deepseek-ai/dsh-timeout-policy' import * as ToolLsp from '@deepseek-ai/dsh-tool-lsp' /** - * Real-composition integration: the model-facing `lsp` tool over the real seam, the real - * `dsh-lsp-local` provider (driving an inline stdio server), and the real `dsh-timeout-policy`, all - * driven only through `ctx.tools.execute()`. Pins that a query round-trips end to end and that the - * policy's `TOOL_TIMEOUT` budget wins when the server hangs. + * Focused in-process integration of the model-facing tool, seam, local provider, and timeout policy. + * The `lsp-definition` ACP snapshot owns the shipped Loader/app entry path. */ let root: string @@ -77,7 +75,7 @@ function call(ctx: Context, args: unknown) { }) } -describe('tool-lsp real composition', () => { +describe('tool-lsp integration', () => { it('round-trips a definition query through the real provider and renders a location', async () => { const ctx = await mount(false) const result = await call(ctx, { operation: 'definition', file_path: 'a.ts', line: 1, character: 7 }) diff --git a/packages/lsp/tool-lsp/tests/load-path.spec.ts b/packages/lsp/tool-lsp/tests/load-path.spec.ts index 13dbaa7b78..7b3ec0f241 100644 --- a/packages/lsp/tool-lsp/tests/load-path.spec.ts +++ b/packages/lsp/tool-lsp/tests/load-path.spec.ts @@ -1,15 +1,15 @@ /** - * Real-load-path guard for @deepseek-ai/dsh-tool-lsp. It is a NAMESPACE plugin with `inject`, so a + * Loader export-shape guard for @deepseek-ai/dsh-tool-lsp. It is a NAMESPACE plugin with `inject`, so a * stray `export default apply` would make the Loader's `unwrapExports` collapse the module to the - * bare `apply`, dropping `inject` (postmortem 0001). This unwraps through the REAL - * `Loader.prototype.unwrapExports` and verifies the namespace shape survives. + * bare `apply`, dropping `inject` (postmortem 0001). This verifies the namespace survives + * `Loader.prototype.unwrapExports`; the `lsp-definition` ACP snapshot owns full app composition. */ import { describe, expect, it } from 'vitest' import Loader from '@cordisjs/plugin-loader' import * as toolLsp from '@deepseek-ai/dsh-tool-lsp' -describe('dsh-tool-lsp real-load-path guard', () => { +describe('dsh-tool-lsp Loader export-shape guard', () => { it('has no default export and keeps name/inject/Config through unwrapExports', () => { expect('default' in toolLsp).toBe(false) From e15a6168d2c8d69ae004feff822c89b2adc78c36 Mon Sep 17 00:00:00 2001 From: Huanqi Cao Date: Sun, 5 Jul 2026 04:31:22 +0800 Subject: [PATCH 024/273] Support durable JSONL persistence on Windows --- docs/rfc/INDEX.md | 1 + ...026-07-05-windows-jsonl-durable-publish.md | 33 ++++ .../session-persistence-jsonl/README.md | 4 +- .../session-persistence-jsonl/package.json | 1 + .../session-persistence-jsonl/src/index.ts | 128 +++++++++---- .../session-persistence-jsonl/src/win32.ts | 150 ++++++++++++++++ .../tests/jsonl.spec.ts | 39 ++++ .../tests/win32.spec.ts | 168 ++++++++++++++++++ pnpm-lock.yaml | 144 +++++++++++++++ pnpm-workspace.yaml | 2 + 10 files changed, 636 insertions(+), 34 deletions(-) create mode 100644 docs/rfc/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md create mode 100644 packages/session-persistence/session-persistence-jsonl/src/win32.ts create mode 100644 packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index ab39d4f314..32f11b744a 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -150,6 +150,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [Prompt variables and tool-guidance ownership](implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md) | 2026-07-05 | | [Every LLM request is reconstructable from the session log](implemented/architecture/2026-07-05-reconstructable-requests.md) | 2026-07-05 | | [Subagent provider-lifecycle events — `subagent/provider-added` / `subagent/provider-removed`](implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md) | 2026-07-05 | +| [Windows-native durable JSONL publication](implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md) | 2026-07-05 | | [A shared timeout/deadline primitive, with hard-kill left to each capability](implemented/architecture/2026-07-06-timeout-deadline-library.md) | 2026-07-06 | | [Tool result retention library](implemented/architecture/2026-07-06-tool-result-retention-library.md) | 2026-07-06 | | [Tool-call timeout policy as a plugin](implemented/architecture/2026-07-07-tool-call-timeout-policy.md) | 2026-07-07 | diff --git a/docs/rfc/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md b/docs/rfc/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md new file mode 100644 index 0000000000..909f75132f --- /dev/null +++ b/docs/rfc/implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md @@ -0,0 +1,33 @@ +# RFC: Windows-native durable JSONL publication + +Status: implemented + +## Problem + +`dsh-session-persistence-jsonl` publishes a session log lazily on the first append. The POSIX protocol writes a temp file, fsyncs it, links it to the final name, fsyncs the parent directory, and then removes the temp link. The parent-directory fsync is part of the durability contract: a crash after the namespace change must not lose the committed final name while leaving callers believing the session log materialized. + +Windows has atomic namespace operations, but Node does not expose a POSIX-equivalent parent-directory fsync contract there. Treating Windows directory sync failures as success would silently weaken a durable backend. The Windows path therefore needs a different publication primitive rather than a conditional inside the POSIX `syncDir` helper. + +## Decision + +The JSONL backend forks inside `materialize()` before any namespace mutation. Shared code computes the session directory, final log path, and initial JSONL bytes; POSIX and Windows then run separate publication protocols. + +POSIX keeps the existing protocol: create the root and cwd bucket with parent directory fsyncs, write and fsync a temp file, publish with `link()` so an existing final log is never overwritten, fsync the bucket directory, then remove the redundant temp hard link. + +Windows creates missing directories through a durable staging publish: create a random sibling directory, then publish it to the final directory name with `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` without `MOVEFILE_REPLACE_EXISTING` or `MOVEFILE_COPY_ALLOWED`. File materialization writes and fsyncs the temp log, then publishes that temp file to the final path with the same write-through `MoveFileExW` call and no replacement. `koffi` is the minimal Win32 bridge for this API surface; its install script is allowed in `pnpm-workspace.yaml` because the package ships the native loader and prebuilt platform modules. + +## Alternatives considered + +**Ignore Windows directory-sync failures.** Rejected because it reports a first append as durable without forcing the published namespace entry to stable storage. + +**Use `CreateHardLinkW`.** Rejected because hard links are filesystem-dependent, do not publish directories, and expose no write-through option. + +**Use replacement or transactional APIs.** `ReplaceFileW` has replacement semantics that conflict with same-id collision rejection, and Transactional NTFS is not recommended for new application designs. + +## Consequences + +The backend keeps one external contract across platforms: first append either publishes a complete log at the final name or fails without overwriting an existing log. The platform split is an implementation detail; `SessionPersistence` APIs and on-disk JSONL format do not change. + +Windows tests exercise the real Win32 publish path on native Windows. Power-loss behavior remains an API-contract property rather than something unit tests can prove; the testable invariants are that directory fsync is not called on Windows materialization, final-path collisions fail, temp logs are fsync'd before publication, and the resulting log loads normally. + +Append and repair still use ordinary file-handle fsyncs on both platforms. A failed append closes its append-only handle, reopens the log read/write, truncates it to the pre-append size, and fsyncs the rollback because Windows rejects `ftruncate` on append-only handles. diff --git a/packages/session-persistence/session-persistence-jsonl/README.md b/packages/session-persistence/session-persistence-jsonl/README.md index 43f4443107..097ad04b67 100644 --- a/packages/session-persistence/session-persistence-jsonl/README.md +++ b/packages/session-persistence/session-persistence-jsonl/README.md @@ -23,7 +23,7 @@ The JSONL durable session-persistence backend — a concrete `SessionPersistence ## Durability and crash semantics -- **Lazy materialization.** `create(meta)` writes nothing; on the first `append`, the backend writes and `fsync`s a temporary file, publishes it without overwrite via a hard link, then `fsync`s the directory. A created-but-never-appended session leaves nothing on disk and is absent from `list`. +- **Lazy materialization.** `create(meta)` writes nothing; the `.jsonl` (header + first batch) is written atomically on the first `append`: POSIX uses temp-write + file `fsync` + `link` + parent-directory `fsync`; Windows uses temp-write + file `fsync` + `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` and creates missing directories through the same write-through publish pattern. A created-but-never-appended session leaves nothing on disk and is absent from `list`. - **Append-only.** Committed events (at or below a flushed `turn/end`) are never rewritten. Subsequent appends are line appends at EOF + `fsync`. - **Crash recovery — preserve valid tail work.** `load` keeps the contiguous valid prefix of an interrupted final turn. It truncates from the first unparsable or sequence-gapped uncommitted record, then appends the synthetic tool, step, and turn closers required by the shared [persistence contract](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md); the same defect at or before the last committed `turn/end` rejects. - **Contiguous-seq.** `append` rejects a batch whose first `seq` does not continue the stored log, and rejects non-JSON-serializable `event.data` naming the offending event type. @@ -45,4 +45,4 @@ The plugin buffers frozen session events and drains them on flush or disposal. A - **Only the current `SESSION_FORMAT_VERSION` (v0) loads** — the on-disk format is pre-release/unstable: a breaking format change is absorbed at v0 and non-current logs are rejected; there is no migration. - **Nothing deletes session files** — logs accumulate under `root` until removed externally (the seam has no deletion surface). - **Single-process assumption** — per-session serialization and the write cursor live in this process; two processes appending to the same `root` are not coordinated. -- **Initial materialization requires hard-link support** — first append uses `link()` so same-id races fail instead of overwriting a committed log; a filesystem that cannot create hard links cannot host this backend. +- **POSIX materialization requires hard-link support** — its first append uses `link()` so same-id races fail instead of overwriting a committed log; Windows uses write-through rename without replacement. diff --git a/packages/session-persistence/session-persistence-jsonl/package.json b/packages/session-persistence/session-persistence-jsonl/package.json index ddb9f2af4d..2644e14efc 100644 --- a/packages/session-persistence/session-persistence-jsonl/package.json +++ b/packages/session-persistence/session-persistence-jsonl/package.json @@ -27,6 +27,7 @@ "cordis": "^4.0.0-rc.7" }, "dependencies": { + "koffi": "^3.1.0", "schemastery": "^3.18.0" }, "devDependencies": { diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts index 0c8a2ee3ef..ac1c07860e 100644 --- a/packages/session-persistence/session-persistence-jsonl/src/index.ts +++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts @@ -19,6 +19,7 @@ import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-se import { encodeSegment, eventLine, logPath, parseHeaderMeta, scanLog, sessionDir, toHeaderLine, } from './format.ts' +import { ensureDurableDirectoryWin32, publishNewFileWin32 } from './win32.ts' /** Plugin config: where the JSONL backend keeps its session logs (`root` is required — no default). */ export interface Config { @@ -160,33 +161,35 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi // --- materialization / append / repair (file mechanics) --- - /** Atomically write the header line + first batch (temp-write, fsync, collision-safe hard-link publish). */ + /** Atomically write the header line + first batch (temp-write, fsync, publish). */ private async materialize(meta: SessionHeader, events: readonly SessionEvent[]): Promise { const dir = sessionDir(this.root, meta.cwd) - await mkdir(this.root, { recursive: true, mode: 0o700 }) - await this.syncDir(dirname(this.root)) - await mkdir(dir, { recursive: true, mode: 0o700 }) - await this.syncDir(this.root) const finalPath = logPath(this.root, meta.cwd, meta.id) - // Materialization is the first write; an existing log is an id collision. - /* v8 ignore next 3 -- createCore guards collisions before materialize; this is a TOCTOU backstop */ - if (await this.exists(finalPath)) { - throw new Error(`refusing to materialize "${meta.id}": a log already exists on disk (load/resume it instead)`) + const content = this.initialLogContent(meta, events) + /* v8 ignore next -- native Windows coverage exercises this platform dispatch; Linux covers the POSIX peer */ + if (process.platform === 'win32') { + await this.materializeWin32(dir, finalPath, meta.id, content) + } else { + await this.materializePosix(dir, finalPath, meta.id, content) } + } + + private initialLogContent(meta: SessionHeader, events: readonly SessionEvent[]): string { const header = JSON.stringify(toHeaderLine(meta)) const body = events.map(eventLine).join('\n') - const content = header + '\n' + body + '\n' + return header + '\n' + body + '\n' + } - const tmp = `${finalPath}.${randomBytes(6).toString('hex')}.tmp` - const handle = await open(tmp, 'wx', 0o600) - try { - await handle.writeFile(content) - await handle.sync() - } finally { - await handle.close() - } - // Publish with link()+unlink(): unlike rename(), link fails if another - // process materialized the same id first. + private async materializePosix(dir: string, finalPath: string, id: SessionId, content: string): Promise { + await mkdir(this.root, { recursive: true, mode: 0o700 }) + await this.syncDirPosix(dirname(this.root)) + await mkdir(dir, { recursive: true, mode: 0o700 }) + await this.syncDirPosix(this.root) + await this.rejectExistingLog(finalPath, id) + const tmp = await this.writeSyncedTempFile(finalPath, content) + // Publish via link()+unlink(), NOT rename(): link fails with EEXIST if the + // final path already exists, so two processes materializing the same id + // concurrently cannot clobber each other. rename() would silently overwrite. let linked = false try { await link(tmp, finalPath) @@ -197,10 +200,13 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi /* v8 ignore next -- link failure is the TOCTOU/IO race guarded above; not reachable in test */ if (!linked) await rm(tmp, { force: true }) } - // The published link becomes crash-durable only after its directory fsync. - await this.syncDir(dir) - // Best-effort temp cleanup: the log is already published and durable, so a failure to - // remove the (now-redundant) temp hard link must not reject the append. + // link() succeeded — the log is published. fsync the directory so the new + // entry survives a power loss: the new link is not crash-durable until the + // parent directory's metadata is synced. + await this.syncDirPosix(dir) + // Best-effort temp cleanup: the log is already published and durable, so a + // failure to remove the (now-redundant) temp hard link must NOT reject the + // append. Swallow only the rm failure; nothing else of consequence runs here. try { await rm(tmp, { force: true }) } catch { @@ -208,8 +214,47 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi } } - /** fsync a directory so a just-created or published entry inside it is crash-durable. */ - private async syncDir(dir: string): Promise { + /* v8 ignore start -- native Windows coverage exercises this integration path */ + private async materializeWin32(dir: string, finalPath: string, id: SessionId, content: string): Promise { + await ensureDurableDirectoryWin32(this.root) + await ensureDurableDirectoryWin32(dir) + await this.rejectExistingLog(finalPath, id) + const tmp = await this.writeSyncedTempFile(finalPath, content) + try { + await publishNewFileWin32(tmp, finalPath) + } catch (error) { + await rm(tmp, { force: true }) + throw error + } + } + /* v8 ignore stop */ + + private async rejectExistingLog(finalPath: string, id: SessionId): Promise { + // Never publish over an existing committed log: materialize is the FIRST + // write of a session the backend believes is new. A file here means a + // different session shares this id on disk — reject loudly. (createCore + // already guards the create path, so this is unreachable-in-practice TOCTOU + // defense.) + /* v8 ignore next 3 -- createCore guards collisions before materialize; this is a TOCTOU backstop */ + if (await this.exists(finalPath)) { + throw new Error(`refusing to materialize "${id}": a log already exists on disk (load/resume it instead)`) + } + } + + private async writeSyncedTempFile(finalPath: string, content: string): Promise { + const tmp = `${finalPath}.${randomBytes(6).toString('hex')}.tmp` + const handle = await open(tmp, 'wx', 0o600) + try { + await handle.writeFile(content) + await handle.sync() + } finally { + await handle.close() + } + return tmp + } + + /** fsync a POSIX directory so a just-created/renamed entry is crash-durable. */ + private async syncDirPosix(dir: string): Promise { const handle = await open(dir, 'r') try { await handle.sync() @@ -226,17 +271,37 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi private async appendLines(meta: SessionHeader, events: readonly SessionEvent[]): Promise { const path = logPath(this.root, meta.cwd, meta.id) const handle = await open(path, 'a') + let closed = false + const closeAppendHandle = async (): Promise => { + if (closed) return + closed = true + await handle.close() + } + try { const { size: before } = await handle.stat() try { await handle.writeFile(events.map(eventLine).join('\n') + '\n') await handle.sync() } catch (error) { - // Roll back whatever bytes landed so a retry starts from a clean EOF. - await handle.truncate(before) - await handle.sync() + try { + await closeAppendHandle() + await this.rollbackAppend(path, before) + } catch (rollbackError) { + throw new AggregateError([error, rollbackError], `failed to roll back append to "${path}"`) + } throw error } + } finally { + await closeAppendHandle() + } + } + + private async rollbackAppend(path: string, size: number): Promise { + const handle = await open(path, 'r+') + try { + await handle.truncate(size) + await handle.sync() } finally { await handle.close() } @@ -322,9 +387,8 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi await handle.close() return true } catch (error) { - // Only ENOENT means absent. A permission/I/O error must surface, not be - // collapsed to `false` — otherwise load() reports "not found" and collision - // checks proceed under a false absence assumption. + // Only ENOENT means absent. A permission/I/O error must surface rather + // than letting load or collision checks proceed under false absence. if (isENOENT(error)) return false throw error } diff --git a/packages/session-persistence/session-persistence-jsonl/src/win32.ts b/packages/session-persistence/session-persistence-jsonl/src/win32.ts new file mode 100644 index 0000000000..143f230ea3 --- /dev/null +++ b/packages/session-persistence/session-persistence-jsonl/src/win32.ts @@ -0,0 +1,150 @@ +/** + * Windows durable namespace helpers for the JSONL backend. + * + * POSIX publishes a newly-created log by creating a directory entry and then + * fsyncing the parent directory. Windows does not expose that parent-directory + * fsync contract through Node, so the Windows path uses the native durable + * namespace primitive instead: create a staging object in the target directory + * and publish it with `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` without + * replacement or cross-volume copy fallback. + * + * @module dsh-session-persistence-jsonl/win32 + */ + +import { mkdtemp, rm, stat } from 'node:fs/promises' +import { basename, join, parse, resolve, toNamespacedPath } from 'node:path' + +type MoveFileExW = (existing: string, replacement: string, flags: number) => boolean +type GetLastError = () => number + +interface Win32Bindings { + moveFileExW: MoveFileExW + getLastError: GetLastError +} + +interface Win32ErrnoException extends NodeJS.ErrnoException { + win32Code: number + dest: string +} + +const MOVEFILE_WRITE_THROUGH = 0x00000008 +const ERROR_FILE_NOT_FOUND = 2 +const ERROR_PATH_NOT_FOUND = 3 +const ERROR_ACCESS_DENIED = 5 +const ERROR_NOT_SAME_DEVICE = 17 +const ERROR_FILE_EXISTS = 80 +const ERROR_INVALID_NAME = 123 +const ERROR_ALREADY_EXISTS = 183 + +let bindings: Win32Bindings | undefined + +/** Load the small Win32 surface lazily so non-Windows processes never load Koffi. */ +async function win32(): Promise { + if (bindings !== undefined) return bindings + const koffi = (await import('koffi')).default + const kernel32 = koffi.load('kernel32.dll') + bindings = { + moveFileExW: kernel32.func('__stdcall', 'MoveFileExW', 'bool', ['str16', 'str16', 'uint']) as MoveFileExW, + getLastError: kernel32.func('__stdcall', 'GetLastError', 'uint', []) as GetLastError, + } + return bindings +} + +function errnoCode(win32Code: number): string { + switch (win32Code) { + case ERROR_FILE_NOT_FOUND: + case ERROR_PATH_NOT_FOUND: + return 'ENOENT' + case ERROR_ACCESS_DENIED: + return 'EACCES' + case ERROR_NOT_SAME_DEVICE: + return 'EXDEV' + case ERROR_FILE_EXISTS: + case ERROR_ALREADY_EXISTS: + return 'EEXIST' + case ERROR_INVALID_NAME: + return 'EINVAL' + default: + return 'EIO' + } +} + +function win32Error(syscall: string, win32Code: number, path: string, dest: string): Win32ErrnoException { + const code = errnoCode(win32Code) + const error = new Error(`${syscall} ${code} (Win32 ${win32Code}): ${path} -> ${dest}`) as Win32ErrnoException + error.code = code + error.errno = win32Code + error.syscall = syscall + error.path = path + error.dest = dest + error.win32Code = win32Code + return error +} + +function isENOENT(error: unknown): boolean { + return (error as NodeJS.ErrnoException | null)?.code === 'ENOENT' +} + +function isEEXIST(error: unknown): boolean { + return (error as NodeJS.ErrnoException | null)?.code === 'EEXIST' +} + +async function assertDirectory(path: string): Promise { + try { + const info = await stat(path) + if (info.isDirectory()) return true + const error = new Error(`path exists but is not a directory: ${path}`) as NodeJS.ErrnoException + error.code = 'ENOTDIR' + error.path = path + throw error + } catch (error) { + if (isENOENT(error)) return false + throw error + } +} + +/** + * Publish `existing` at `replacement` with Windows write-through rename + * semantics. The destination must not already exist; the move must stay within + * the volume (no copy fallback flag is set). + * @param existing - the synced staging path to move. + * @param replacement - the final path, which must not already exist. + */ +export async function publishNewFileWin32(existing: string, replacement: string): Promise { + const api = await win32() + const ok = api.moveFileExW(toNamespacedPath(existing), toNamespacedPath(replacement), MOVEFILE_WRITE_THROUGH) + if (!ok) throw win32Error('MoveFileExW', api.getLastError(), existing, replacement) +} + +/** + * Create `target` and its missing ancestors with durable Windows namespace + * publication. Each missing directory is first created as a random staging + * sibling, then moved to its final name with `MOVEFILE_WRITE_THROUGH`; races + * with another creator are accepted only after verifying the winner is a + * directory. + * @param target - the absolute directory path to create durably when absent. + */ +export async function ensureDurableDirectoryWin32(target: string): Promise { + const absolute = resolve(target) + const root = parse(absolute).root + await assertDirectory(root) + + const segments = absolute.slice(root.length).split(/[\\/]+/).filter(part => part.length > 0) + let current = root + for (const segment of segments) { + const next = join(current, segment) + if (!await assertDirectory(next)) await createLeafDirectoryWin32(current, next) + current = next + } +} + +async function createLeafDirectoryWin32(parent: string, target: string): Promise { + const staging = await mkdtemp(join(parent, `.dsh-mkdir-${basename(target)}-`)) + try { + await publishNewFileWin32(staging, target) + } catch (error) { + await rm(staging, { recursive: true, force: true }) + if (isEEXIST(error) && await assertDirectory(target)) return + throw error + } +} diff --git a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts index 4b279e3c6e..e7a65d3c8f 100644 --- a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts +++ b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts @@ -336,6 +336,45 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7]) }) + it('reports both the append failure and a failed rollback', async () => { + const m = meta('rollback-failure') + await ctx.sessionPersistence.create(m) + await ctx.sessionPersistence.append(m.id, oneTurnLog()) + + const path = logPath(root, undefined, m.id) + const handle = await (await import('node:fs/promises')).open(path, 'r') + const proto = Object.getPrototypeOf(handle) as { sync: () => Promise } + await handle.close() + const realSync = proto.sync + let failed = false + const syncSpy = vi.spyOn(proto, 'sync').mockImplementation(async function (this: unknown) { + if (!failed) { failed = true; throw new Error('simulated append fsync failure') } + return realSync.call(this) + }) + const backend = ctx.sessionPersistence as unknown as { + rollbackAppend: (path: string, size: number) => Promise + } + const realRollback = backend.rollbackAppend.bind(backend) + backend.rollbackAppend = () => Promise.reject(new Error('simulated rollback failure')) + + try { + await ctx.sessionPersistence.append(m.id, [ + { type: 'turn/start', seq: 6, time: 9, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } }, + ] as SessionEvent[]) + throw new Error('expected append to reject') + } catch (error) { + expect(error).toBeInstanceOf(AggregateError) + const aggregate = error as AggregateError + expect(aggregate.message).toContain(`failed to roll back append to "${path}"`) + expect(aggregate.errors).toHaveLength(2) + expect(aggregate.errors[0]).toMatchObject({ message: 'simulated append fsync failure' }) + expect(aggregate.errors[1]).toMatchObject({ message: 'simulated rollback failure' }) + } finally { + backend.rollbackAppend = realRollback + syncSpy.mockRestore() + } + }) + it('load returns a meta copy: mutating it does not corrupt backend pathing', async () => { const m = meta('meta-copy', '/proj') await ctx.sessionPersistence.create(m) diff --git a/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts new file mode 100644 index 0000000000..760eb3d455 --- /dev/null +++ b/packages/session-persistence/session-persistence-jsonl/tests/win32.spec.ts @@ -0,0 +1,168 @@ +/** + * Unit tests for the Windows durable namespace helper with a mocked kernel32 + * binding. The real JSONL suite exercises the helper on native Windows; these + * tests keep the Win32 error mapping and race handling covered on every host. + */ + +import { afterEach, describe, expect, it, vi } from 'vitest' +import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs' +import { mkdtemp, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' + +const MOVEFILE_WRITE_THROUGH = 0x00000008 +const ERROR_FILE_NOT_FOUND = 2 +const ERROR_PATH_NOT_FOUND = 3 +const ERROR_ACCESS_DENIED = 5 +const ERROR_NOT_SAME_DEVICE = 17 +const ERROR_FILE_EXISTS = 80 +const ERROR_INVALID_NAME = 123 +const ERROR_ALREADY_EXISTS = 183 + +type MoveFileExW = (existing: string, replacement: string, flags: number, setLastError: (code: number) => void) => boolean + +const roots: string[] = [] + +function stripNamespace(path: string): string { + if (path.startsWith('\\\\?\\UNC\\')) return `\\\\${path.slice('\\\\?\\UNC\\'.length)}` + if (path.startsWith('\\\\?\\')) return path.slice('\\\\?\\'.length) + return path +} + +async function tempRoot(): Promise { + const dir = await mkdtemp(join(tmpdir(), 'dsh-jsonl-win32-')) + roots.push(dir) + return dir +} + +async function importWithMove(moveFileExW: MoveFileExW): Promise { + vi.resetModules() + vi.doMock('koffi', () => { + let lastError = 0 + const setLastError = (code: number): void => { lastError = code } + const move: MoveFileExW = (existing, replacement, flags, setError) => { + const ok = moveFileExW(existing, replacement, flags, setError) + lastError = ok ? 0 : lastError + return ok + } + return { + default: { + load: () => ({ + func: (_convention: string, name: string) => { + if (name === 'MoveFileExW') return (existing: string, replacement: string, flags: number) => { + const ok = move(existing, replacement, flags, setLastError) + return ok + } + return () => lastError + }, + }), + }, + } + }) + return import('../src/win32.ts') +} + +async function importWithError(code: number): Promise { + vi.resetModules() + vi.doMock('koffi', () => ({ + default: { + load: () => ({ + func: (_convention: string, name: string) => { + if (name === 'MoveFileExW') return () => false + return () => code + }, + }), + }, + })) + return import('../src/win32.ts') +} + +async function importWithFilesystemMove(): Promise { + return importWithMove((existing, replacement, flags, setLastError) => { + expect(flags).toBe(MOVEFILE_WRITE_THROUGH) + const from = stripNamespace(existing) + const to = stripNamespace(replacement) + if (!existsSync(from)) { setLastError(ERROR_FILE_NOT_FOUND); return false } + if (existsSync(to)) { setLastError(ERROR_ALREADY_EXISTS); return false } + renameSync(from, to) + return true + }) +} + +afterEach(async () => { + vi.doUnmock('koffi') + vi.resetModules() + for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true }) +}) + +describe('Windows durable namespace helpers', () => { + it('publishes a new file with write-through MoveFileExW semantics', async () => { + const { publishNewFileWin32 } = await importWithFilesystemMove() + const root = await tempRoot() + const tmp = join(root, 'log.tmp') + const final = join(root, 'log.jsonl') + await writeFile(tmp, 'content') + + await publishNewFileWin32(tmp, final) + expect(existsSync(tmp)).toBe(false) + expect(readFileSync(final, 'utf8')).toBe('content') + }) + + it('maps Win32 publish failures to Node-style errno codes', async () => { + const cases = [ + [ERROR_FILE_NOT_FOUND, 'ENOENT'], + [ERROR_PATH_NOT_FOUND, 'ENOENT'], + [ERROR_ACCESS_DENIED, 'EACCES'], + [ERROR_NOT_SAME_DEVICE, 'EXDEV'], + [ERROR_FILE_EXISTS, 'EEXIST'], + [ERROR_ALREADY_EXISTS, 'EEXIST'], + [ERROR_INVALID_NAME, 'EINVAL'], + [9999, 'EIO'], + ] as const + for (const [win32Code, code] of cases) { + const { publishNewFileWin32 } = await importWithError(win32Code) + await expect(publishNewFileWin32('from', 'to')).rejects.toMatchObject({ code, win32Code, path: 'from', dest: 'to' }) + } + }) + + it('creates missing directories through staging siblings and tolerates an already-created race', async () => { + const root = await tempRoot() + const raced = join(root, 'raced') + const { ensureDurableDirectoryWin32 } = await importWithMove((existing, replacement, flags, setLastError) => { + expect(flags).toBe(MOVEFILE_WRITE_THROUGH) + const from = stripNamespace(existing) + const to = stripNamespace(replacement) + if (to === raced) { + mkdirSync(to) + setLastError(ERROR_ALREADY_EXISTS) + return false + } + if (!existsSync(from)) { setLastError(ERROR_FILE_NOT_FOUND); return false } + if (existsSync(to)) { setLastError(ERROR_ALREADY_EXISTS); return false } + renameSync(from, to) + return true + }) + + await ensureDurableDirectoryWin32(join(root, 'a', 'b')) + expect(existsSync(join(root, 'a', 'b'))).toBe(true) + await ensureDurableDirectoryWin32(join(root, 'a', 'b')) + await ensureDurableDirectoryWin32(raced) + expect(existsSync(raced)).toBe(true) + }) + + it('surfaces directory publication failures other than an existing-target race', async () => { + const { ensureDurableDirectoryWin32 } = await importWithError(ERROR_ACCESS_DENIED) + const root = await tempRoot() + + await expect(ensureDurableDirectoryWin32(join(root, 'denied'))).rejects.toMatchObject({ code: 'EACCES' }) + }) + + it('rejects a non-directory component instead of treating it as missing', async () => { + const { ensureDurableDirectoryWin32 } = await importWithFilesystemMove() + const root = await tempRoot() + const blocked = join(root, 'blocked') + writeFileSync(blocked, 'x') + + await expect(ensureDurableDirectoryWin32(join(blocked, 'child'))).rejects.toMatchObject({ code: 'ENOTDIR' }) + }) +}) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 9810a9a61e..9e6532f466 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1259,6 +1259,9 @@ importers: packages/session-persistence/session-persistence-jsonl: dependencies: + koffi: + specifier: ^3.1.0 + version: 3.1.1 schemastery: specifier: ^3.18.0 version: 3.18.0 @@ -3453,6 +3456,81 @@ packages: '@jridgewell/trace-mapping@0.3.31': resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==} + '@koromix/koffi-darwin-arm64@3.1.1': + resolution: {integrity: sha512-+Dl0zQDh1Wb55AWOn9hp7K30qgkODvrvN+ZNkFOh81Q0oFX/rpJQtocgjAuYk2zFAcajSeVDumkcHMPwnKSXzA==} + cpu: [arm64] + os: [darwin] + + '@koromix/koffi-darwin-x64@3.1.1': + resolution: {integrity: sha512-cDFAKn1qdZBFLrp7dAc9QUDw3l4xAhTJbOdPWWb0LxssVicUdHcRCLZGrDsmPW2tpH6LGNNeLgqRpAoD2Mo8iA==} + cpu: [x64] + os: [darwin] + + '@koromix/koffi-freebsd-arm64@3.1.1': + resolution: {integrity: sha512-zaP7FJISI/scQW9Wa5QicY3a09WmtKBWSbmC+5nfCqPzwWe7Hx2so74Er7mPsDfCiMMR0Ya+evKbJQDkfyXicg==} + cpu: [arm64] + os: [freebsd] + + '@koromix/koffi-freebsd-ia32@3.1.1': + resolution: {integrity: sha512-7GejVb688TLM8rbjfc0oezJrATxZc0dn801xWEDJekN2DgmRXu7HquGqWQ6z3NeSq7ZxEggz4T3xtlbCysQapA==} + cpu: [ia32] + os: [freebsd] + + '@koromix/koffi-freebsd-x64@3.1.1': + resolution: {integrity: sha512-XLiCFP9OFCyOoGTjAimtDKLhzhfo34WcP1ShVWxRzNCWDGjfz8BYjwd69cp/cDSUXZbxamqs4+/6vmkePq9wxA==} + cpu: [x64] + os: [freebsd] + + '@koromix/koffi-linux-arm64@3.1.1': + resolution: {integrity: sha512-HA9xINK7G4dRAkpfnBWD9VfuyIBgW1SuK+KPHjksUwRMOnhgqP8J/JqgrAzdzcDiefGBkqEacIP776OUwz7knQ==} + cpu: [arm64] + os: [linux] + + '@koromix/koffi-linux-ia32@3.1.1': + resolution: {integrity: sha512-jG7IFytmP8K5Qtbx0ro0ZeuX3JjSsLxmYhq+nmXDdrtOAlxIsWGynuiDLS6Jk3vOchVii2m6Y2f/L3GLG2fG5A==} + cpu: [ia32] + os: [linux] + + '@koromix/koffi-linux-loong64@3.1.1': + resolution: {integrity: sha512-CIsT1cNnih8FuU52Me/IVlJBpH28SQfoDeYPctJswgJzaARktusF7m4MUbtR1PBDjuquCVM4/vFyNdOzfPonvA==} + cpu: [loong64] + os: [linux] + + '@koromix/koffi-linux-riscv64@3.1.1': + resolution: {integrity: sha512-9D6RmqeKsSvs3U6jILJU9PcAjMwKKyn7yLxNBb5k6z9PCoUoGJ3/BrhXAX0qjrLLwEiIpP/hS/40RuXvH8Lc3Q==} + cpu: [riscv64] + os: [linux] + + '@koromix/koffi-linux-x64@3.1.1': + resolution: {integrity: sha512-pyTcX5fePeYbt7TZAwRby69wdlRx3PT+g15ra5IYdat/Pgh3qAKEYeZ+uu7WpPGOy43p/oSRqqZoa2kORzozlA==} + cpu: [x64] + os: [linux] + + '@koromix/koffi-openbsd-ia32@3.1.1': + resolution: {integrity: sha512-iPnPzvG2HOfdzaiG1drdkt86sAqmTPDv9mAf+5gL7mRzkeeQC88EVGboRy7eXwdXn7R+v0ntA3iQxdHrBn6yXw==} + cpu: [ia32] + os: [openbsd] + + '@koromix/koffi-openbsd-x64@3.1.1': + resolution: {integrity: sha512-/Xqc3R0SVoMCYjMPZnJ9bULtRo364+dKmnQhfDrI83tSpxUHRw7HRNf12vBeL+hPgKxSBjtMpWfQ/ZIyVyLFag==} + cpu: [x64] + os: [openbsd] + + '@koromix/koffi-win32-arm64@3.1.1': + resolution: {integrity: sha512-JhqHauEwQvdcWUERxrV5HH/DT9W7hY1A1eU6/o8tB+yck+D3kt5elpRDBt9KjpW6h+vHPy3V0sjDvO0CXyabTA==} + cpu: [arm64] + os: [win32] + + '@koromix/koffi-win32-ia32@3.1.1': + resolution: {integrity: sha512-ZRuyYmlGS/rCc966qqs0qREXDW4FRdul7rDF1VgSWHbVmdc196PUgUT+blq/GjZgTwqzeEXtMRgM+cU8krHjvA==} + cpu: [ia32] + os: [win32] + + '@koromix/koffi-win32-x64@3.1.1': + resolution: {integrity: sha512-KqHPmvj6QILhNyI/To8QSihHsijeVGIYYPBOUnXEpcnH2LuLbargY4Hd6dDeTN3Z90uUUxN+1FWz1UnhVzFOiA==} + cpu: [x64] + os: [win32] + '@mermaid-js/parser@1.2.0': resolution: {integrity: sha512-oYPyv8A4As1yH5Bx+04iQEQxXuIQDe0GKCNSRgao6z8AM9jixXIfP0vsppRLvGf+nKIOb9/LdpWA4YuJiVvESA==} @@ -5662,6 +5740,9 @@ packages: engines: {node: ^20.19.0 || >=22.12.0} hasBin: true + koffi@3.1.1: + resolution: {integrity: sha512-mRX6AMeeKCxSOeOopqAcLAl5jcNvge7NAG8l7rF/8gGJATI0tdHFYjteIdE0mGOtWdsrJOij+PjnP8Q9c1gwgA==} + layout-base@1.0.2: resolution: {integrity: sha512-8h2oVEZNktL4BH2JCOI90iD1yXwL6iNW7KcCKT2QZgQJR2vbqDsldCTPRU9NifTCqHZci57XvQQ15YTu+sTYPg==} @@ -7842,6 +7923,51 @@ snapshots: '@jridgewell/resolve-uri': 3.1.2 '@jridgewell/sourcemap-codec': 1.5.5 + '@koromix/koffi-darwin-arm64@3.1.1': + optional: true + + '@koromix/koffi-darwin-x64@3.1.1': + optional: true + + '@koromix/koffi-freebsd-arm64@3.1.1': + optional: true + + '@koromix/koffi-freebsd-ia32@3.1.1': + optional: true + + '@koromix/koffi-freebsd-x64@3.1.1': + optional: true + + '@koromix/koffi-linux-arm64@3.1.1': + optional: true + + '@koromix/koffi-linux-ia32@3.1.1': + optional: true + + '@koromix/koffi-linux-loong64@3.1.1': + optional: true + + '@koromix/koffi-linux-riscv64@3.1.1': + optional: true + + '@koromix/koffi-linux-x64@3.1.1': + optional: true + + '@koromix/koffi-openbsd-ia32@3.1.1': + optional: true + + '@koromix/koffi-openbsd-x64@3.1.1': + optional: true + + '@koromix/koffi-win32-arm64@3.1.1': + optional: true + + '@koromix/koffi-win32-ia32@3.1.1': + optional: true + + '@koromix/koffi-win32-x64@3.1.1': + optional: true + '@mermaid-js/parser@1.2.0': dependencies: '@chevrotain/types': 11.1.2 @@ -10072,6 +10198,24 @@ snapshots: yaml: 2.9.0 zod: 4.4.3 + koffi@3.1.1: + optionalDependencies: + '@koromix/koffi-darwin-arm64': 3.1.1 + '@koromix/koffi-darwin-x64': 3.1.1 + '@koromix/koffi-freebsd-arm64': 3.1.1 + '@koromix/koffi-freebsd-ia32': 3.1.1 + '@koromix/koffi-freebsd-x64': 3.1.1 + '@koromix/koffi-linux-arm64': 3.1.1 + '@koromix/koffi-linux-ia32': 3.1.1 + '@koromix/koffi-linux-loong64': 3.1.1 + '@koromix/koffi-linux-riscv64': 3.1.1 + '@koromix/koffi-linux-x64': 3.1.1 + '@koromix/koffi-openbsd-ia32': 3.1.1 + '@koromix/koffi-openbsd-x64': 3.1.1 + '@koromix/koffi-win32-arm64': 3.1.1 + '@koromix/koffi-win32-ia32': 3.1.1 + '@koromix/koffi-win32-x64': 3.1.1 + layout-base@1.0.2: {} layout-base@2.0.1: {} diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 8f93814899..2de5578f5d 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -31,6 +31,8 @@ allowBuilds: '@google/genai': false protobufjs: false node-addon-require-builtin: false + # JSONL durability calls MoveFileExW with write-through publication on Windows. + koffi: true # The Landlock launcher family is our own sibling-repo release, consumed # fresh (hours old at each coordinated bump) — the release-age quarantine From 5ed34b66ce0d688a2440b42a25db99a7c71330de Mon Sep 17 00:00:00 2001 From: Huanqi Cao Date: Wed, 8 Jul 2026 12:45:31 +0800 Subject: [PATCH 025/273] fix(acp-snapshot): make path-separator tests platform-neutral Three tests in the shared acp-snapshot package hardcoded POSIX path separators in their assertions, so they failed on Windows where node:path.join produces backslash paths: - childFixturePaths (suite.spec.ts): expected literal '/snap/s/session.1.jsonl' but join returns '\snap\s\...' on Windows; use join() for the expected value. - harness.spec.ts (env-forwarding test): substring-matched a JSON-encoded path against raw stdout text, where backslash escaping makes the compare byte-fragile; parse the env-probe chunk and compare the structured value. - harness.spec.ts (harvested-cwd test): substring-matched the raw cwd against JSONL text where the cwd is JSON-escaped; parse the session line and compare the cwd field. These were master's latent bugs (the package's tests never ran on Windows until the Windows CI lane observed them). Verified green on Windows via scripts/caohuanqi-private/run-ci.py --windows. --- .../support/acp-snapshot/tests/harness.spec.ts | 18 ++++++++++++++++-- .../support/acp-snapshot/tests/suite.spec.ts | 2 +- 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts index 1d953f5e95..d141fb1f09 100644 --- a/packages/support/acp-snapshot/tests/harness.spec.ts +++ b/packages/support/acp-snapshot/tests/harness.spec.ts @@ -72,7 +72,11 @@ describe('runScenario', () => { expect(result.sessionLogs[0]?.createdAt).toBe(42) expect(result.sessionLogs[0]?.content).toContain('turn/start') // The harvested log embeds the run's REAL temp cwd (template-substituted). - expect(result.sessionLogs[0]?.content).toContain(result.cwd) + // The cwd is JSON-encoded in the log line, so compare the parsed field + // rather than substring-matching a raw path (which breaks when the path + // separator is escaped inside JSON text on Windows). + const sessionLine = result.sessionLogs[0]?.content.split('\n').find(l => l.includes('"type":"session"')) ?? '{}' + expect((JSON.parse(sessionLine) as { cwd?: string }).cwd).toBe(result.cwd) }) it('forwards override/child fixture paths into the child env and captures stderr', { timeout: 20_000 }, async () => { @@ -93,7 +97,17 @@ describe('runScenario', () => { expect(result.stderr).toContain('fake bin booted') expect(result.rawStdout).toContain('replay.override.json') // Child paths ride one env var, joined with the platform delimiter. - expect(result.rawStdout).toContain(JSON.stringify(childFiles.join(delimiter)).slice(1, -1)) + // Parse the fake bin's env-probe chunk rather than substring-matching a + // JSON-encoded path (the escaping breaks raw-substring compares on Windows). + const envChunk = result.rawStdout.split('\n') + .map(l => l.trim()) + .filter(l => l.length > 0) + .map(l => JSON.parse(l) as { params?: { update?: { content?: { text?: string } } } }) + .find(f => f.params?.update?.content?.text?.startsWith('env:')) + const env = JSON.parse((envChunk?.params?.update?.content?.text ?? 'env:{}').slice('env:'.length)) as { + childFiles: string | null + } + expect(env.childFiles).toBe(childFiles.join(delimiter)) }) it('seeds the workspace dir into the temp cwd before the run', { timeout: 20_000 }, async () => { diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts index 4cedc1cdfb..c2007321de 100644 --- a/packages/support/acp-snapshot/tests/suite.spec.ts +++ b/packages/support/acp-snapshot/tests/suite.spec.ts @@ -181,7 +181,7 @@ describe('defineAcpSnapshotSuite: registration contract', () => { describe('childFixturePaths', () => { it('yields one sibling path per child, 1-based', () => { - expect(childFixturePaths('/snap/s', 2)).toEqual(['/snap/s/session.1.jsonl', '/snap/s/session.2.jsonl']) + expect(childFixturePaths('/snap/s', 2)).toEqual([join('/snap/s', 'session.1.jsonl'), join('/snap/s', 'session.2.jsonl')]) }) it('yields nothing for a single-session scenario', () => { From 1a4af034c0edd60e4bd54de1f2a1371afbdef056 Mon Sep 17 00:00:00 2001 From: Huanqi Cao Date: Sun, 5 Jul 2026 04:45:41 +0800 Subject: [PATCH 026/273] Accept native ACP path separators in tests --- packages/ui/acp/README.md | 4 +- packages/ui/acp/tests/stream-update.spec.ts | 53 ++++++++++++++------- 2 files changed, 37 insertions(+), 20 deletions(-) diff --git a/packages/ui/acp/README.md b/packages/ui/acp/README.md index 300cd69023..4f810ba0b4 100644 --- a/packages/ui/acp/README.md +++ b/packages/ui/acp/README.md @@ -53,11 +53,11 @@ The shared [`ctx.tasks` runtime](../../tasks/tasks/) fences access to predictabl ## Tool-call presentation -Tools return provider-neutral `generic`, `terminal`, or `diff` render intents from `presentCall()` and `presentResult()`. The bridge maps the discriminator to ACP without special-casing tool names and falls back to a generic card. Per-session call-id state supplies result events with their omitted name and arguments during live streaming and replay. See [`dsh-tools`](../../core/tools/README.md#tool-owned-ui-presentation). +Tools return provider-neutral `generic`, `terminal`, or `diff` render intents from `presentCall()` and `presentResult()`. The bridge maps the discriminator to ACP without special-casing tool names and falls back to a generic card. Per-session call-id state supplies result events with their omitted name and arguments during live streaming and replay. File-card titles are relative to the session cwd and use the host separator, while location and diff paths remain raw so the editor opens the real file. See [`dsh-tools`](../../core/tools/README.md#tool-owned-ui-presentation). ## Terminal card (capability-gated) -When the client advertises `_meta.terminal_output`, terminal intents map to Zed's terminal info, output, and exit metadata. The bridge resolves relative cwd against the session, places the description before the terminal block, and omits result content because ACP updates replace call content. Other clients receive a generic card and bridge-derived fenced console fallback. Session creation snapshots the capability so call and result agree. The command still executes through the harness, not ACP terminal creation. See the [terminal-rendering RFC](../../../docs/rfc/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md) and [render-intent RFC](../../../docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md). +When the client advertises `_meta.terminal_output`, terminal intents map to Zed's terminal info, output, and exit metadata. The bridge resolves relative cwd against the session and preserves the host filesystem separator, places the description before the terminal block, and omits result content because ACP updates replace call content. Other clients receive a generic card and bridge-derived fenced console fallback. Session creation snapshots the capability so call and result agree. The command still executes through the harness, not ACP terminal creation. See the [terminal-rendering RFC](../../../docs/rfc/implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md) and [render-intent RFC](../../../docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md). ## Settle-exactly-once diff --git a/packages/ui/acp/tests/stream-update.spec.ts b/packages/ui/acp/tests/stream-update.spec.ts index 415e9afb33..15a6d3c3fc 100644 --- a/packages/ui/acp/tests/stream-update.spec.ts +++ b/packages/ui/acp/tests/stream-update.spec.ts @@ -1,4 +1,5 @@ import { describe, expect, it } from 'vitest' +import { join as pathJoin, resolve as pathResolve } from 'node:path' import { Context } from 'cordis' import { CallId } from '@deepseek-ai/dsh-llm' import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session' @@ -49,6 +50,16 @@ function evt(type: T, data: Extract { it('maps assistant/chunk text-delta to agent_message_chunk', () => { expect(updatesFor(evt('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'hi' } }))) @@ -480,10 +491,10 @@ describe('terminal-card mapping (capability-gated)', () => { it('capability ON: an ABSOLUTE tool cwd wins; a RELATIVE one resolves against the session cwd', () => { const [absCall] = termUpdates(termTool({ card: 'terminal', cwd: '/explicit/abs' }, { output: 'x' }), true, '/work/proj', callEvent) expect((absCall as unknown as { _meta: { terminal_info: { cwd: string } } })._meta.terminal_info.cwd).toBe('/explicit/abs') - const [relCall] = termUpdates(termTool({ card: 'terminal', cwd: 'sub/dir' }, { output: 'x' }), true, '/work/proj', callEvent) + const [relCall] = termUpdates(termTool({ card: 'terminal', cwd: nativePath('sub', 'dir') }, { output: 'x' }), true, nativeAbsolute('/work/proj'), callEvent) // Relative workdir resolved against the session cwd — the card header matches // where execution actually ran (tool-bash resolves the same way). - expect((relCall as unknown as { _meta: { terminal_info: { cwd: string } } })._meta.terminal_info.cwd).toBe('/work/proj/sub/dir') + expect((relCall as unknown as { _meta: { terminal_info: { cwd: string } } })._meta.terminal_info.cwd).toBe(nativeAbsolute('/work/proj', 'sub', 'dir')) // No session cwd to resolve against → the relative tool cwd is passed through as-is. const [noSessionCwd] = termUpdates(termTool({ card: 'terminal', cwd: 'rel/only' }, { output: 'x' }), true, undefined, callEvent) expect((noSessionCwd as unknown as { _meta: { terminal_info: { cwd: string } } })._meta.terminal_info.cwd).toBe('rel/only') @@ -675,10 +686,12 @@ describe('result-time diff card (REAL fs edit tool → tool_call_update diff blo // paths remain absolute so the editor can open the real file. const ctx = await fsCtx() const presenter = new ToolPresenter(ctx.tools) - const args = JSON.stringify({ file_path: '/work/proj/src/b.ts', old_string: 'OLD', new_string: 'NEW' }) - const meta = { diffs: [{ path: '/work/proj/src/b.ts', oldText: 'a\nOLD\nb', newText: 'a\nNEW\nb' }] } + const workspace = nativeAbsolute('/work/proj') + const file = nativeAbsolute('/work/proj', 'src', 'b.ts') + const args = JSON.stringify({ file_path: file, old_string: 'OLD', new_string: 'NEW' }) + const meta = { diffs: [{ path: file, oldText: 'a\nOLD\nb', newText: 'a\nNEW\nb' }] } const out: SessionNotification['update'][] = [] - const rendering = { enabled: false, cwd: '/work/proj' } + const rendering = { enabled: false, cwd: workspace } for (const event of [ evt('tool/call', { turn: 1, step: 1, callId: CallId('e1'), name: 'edit', arguments: args }), evt('tool/result', { turn: 1, step: 1, callId: CallId('e1'), content: [{ type: 'text', text: 'ok' }], isError: false, meta }), @@ -687,8 +700,8 @@ describe('result-time diff card (REAL fs edit tool → tool_call_update diff blo sessionUpdate: 'tool_call_update', toolCallId: 'e1', status: 'completed', - title: 'Edit src/b.ts', - content: [{ type: 'diff', path: '/work/proj/src/b.ts', oldText: 'a\nOLD\nb', newText: 'a\nNEW\nb' }], + title: `Edit ${nativePath('src', 'b.ts')}`, + content: [{ type: 'diff', path: file, oldText: 'a\nOLD\nb', newText: 'a\nNEW\nb' }], }) await ctx.fiber.dispose() }) @@ -739,21 +752,25 @@ describe('relative-path display titles (bridge relativizes the title against the it('read: an absolute path inside the workspace relativizes the TITLE; the location path stays absolute', async () => { const ctx = await fsCtx() - const update = callUpdate(ctx, '/work/proj', 'read', { file_path: '/work/proj/src/a.ts', offset: 5 }) + const workspace = nativeAbsolute('/work/proj') + const file = nativeAbsolute('/work/proj', 'src', 'a.ts') + const update = callUpdate(ctx, workspace, 'read', { file_path: file, offset: 5 }) expect(update).toMatchObject({ - title: 'Read src/a.ts (from line 5)', - locations: [{ path: '/work/proj/src/a.ts', line: 5 }], + title: `Read ${nativePath('src', 'a.ts')} (from line 5)`, + locations: [{ path: file, line: 5 }], }) await ctx.fiber.dispose() }) it('edit: the diff TITLE relativizes; the diff/location paths stay absolute (the editor opens the real path)', async () => { const ctx = await fsCtx() - const update = callUpdate(ctx, '/work/proj', 'edit', { file_path: '/work/proj/src/b.ts', old_string: 'x', new_string: 'y' }) + const workspace = nativeAbsolute('/work/proj') + const file = nativeAbsolute('/work/proj', 'src', 'b.ts') + const update = callUpdate(ctx, workspace, 'edit', { file_path: file, old_string: 'x', new_string: 'y' }) expect(update).toMatchObject({ - title: 'Edit src/b.ts', - locations: [{ path: '/work/proj/src/b.ts' }], - content: [{ type: 'diff', path: '/work/proj/src/b.ts', oldText: 'x', newText: 'y' }], + title: `Edit ${nativePath('src', 'b.ts')}`, + locations: [{ path: file }], + content: [{ type: 'diff', path: file, oldText: 'x', newText: 'y' }], }) await ctx.fiber.dispose() }) @@ -770,8 +787,8 @@ describe('relative-path display titles (bridge relativizes the title against the // with the chars `..` but is not a parent segment. Segment-aware guarding must relativize it, // matching targets under `cwd + sep` in the reference adapter. const ctx = await fsCtx() - const update = callUpdate(ctx, '/work/proj', 'read', { file_path: '/work/proj/..cache/x.ts' }) - expect((update as { title: string }).title).toBe('Read ..cache/x.ts') + const update = callUpdate(ctx, nativeAbsolute('/work/proj'), 'read', { file_path: nativeAbsolute('/work/proj', '..cache', 'x.ts') }) + expect((update as { title: string }).title).toBe(`Read ${nativePath('..cache', 'x.ts')}`) await ctx.fiber.dispose() }) @@ -784,8 +801,8 @@ describe('relative-path display titles (bridge relativizes the title against the it('a relative path is passed through unchanged (already display-friendly)', async () => { const ctx = await fsCtx() - const update = callUpdate(ctx, '/work/proj', 'read', { file_path: 'src/a.ts' }) - expect((update as { title: string }).title).toBe('Read src/a.ts') + const update = callUpdate(ctx, nativeAbsolute('/work/proj'), 'read', { file_path: nativePath('src', 'a.ts') }) + expect((update as { title: string }).title).toBe(`Read ${nativePath('src', 'a.ts')}`) await ctx.fiber.dispose() }) }) From 130944caeb8118033f5de86f4a1df1c85e962595 Mon Sep 17 00:00:00 2001 From: Huanqi Cao Date: Sun, 5 Jul 2026 17:47:24 +0800 Subject: [PATCH 027/273] Close SQLite probe handle after journalMode assertion --- .../session-persistence-sqlite/tests/sqlite.spec.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts b/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts index a728cc0b71..cebfae09a4 100644 --- a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts +++ b/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts @@ -423,7 +423,9 @@ describe('SessionPersistenceSqlite: edge cases', () => { const walPath = await freshDbPath() const bWal = await backend(walPath) await bWal.ctx.sessionPersistence.create(meta('jm-wal')) - expect((openDatabase(walPath, 'wal').prepare('PRAGMA journal_mode').get() as { journal_mode: string }).journal_mode).toBe('wal') + const probe = openDatabase(walPath, 'wal') + expect((probe.prepare('PRAGMA journal_mode').get() as { journal_mode: string }).journal_mode).toBe('wal') + probe.close() await bWal.dispose() const deletePath = await freshDbPath() From 715aa7372a0ab51c5780a4d014009138da5f1444 Mon Sep 17 00:00:00 2001 From: Huanqi Cao Date: Sun, 5 Jul 2026 18:57:23 +0800 Subject: [PATCH 028/273] Restore ENOTDIR semantic distinction in resolveLocalTarget on Windows --- packages/fs/fs-local/src/fsio.ts | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts index 360145e8c8..e0745f1735 100644 --- a/packages/fs/fs-local/src/fsio.ts +++ b/packages/fs/fs-local/src/fsio.ts @@ -145,8 +145,22 @@ export async function resolveLocalTarget(cwd: string, path: string): Promise Date: Sun, 5 Jul 2026 21:15:46 +0800 Subject: [PATCH 029/273] fs-local: POSIX-only mode-bit assertions, document Windows DACL-inheritance semantics Windows drives only the read-only attribute through chmod and reports synthetic stat mode bits, so writeFileAtomic's mode arguments are inert there; write-in-progress privacy comes from the staging dir (created in the target's parent) inheriting the destination directory's DACL. Production is deliberately unchanged -- the chmod calls are benign no-ops and platform-guarding them out buys nothing. Tests guard the mode-bit expects to POSIX; there is no Windows ACL assertion because an ACL check would pin OS inheritance plus the machine's %TEMP% ACL, not this package. Decision and rejected alternatives (explicit DACLs, Get-Acl/icacls test verification) recorded in the new RFC. --- docs/rfc/INDEX.md | 1 + .../2026-07-05-windows-fs-permissions.md | 29 +++++++++++++++++++ packages/fs/fs-local/README.md | 2 +- packages/fs/fs-local/src/fsio.ts | 4 ++- packages/fs/fs-local/tests/fsio.spec.ts | 19 +++++++++--- 5 files changed, 49 insertions(+), 6 deletions(-) create mode 100644 docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index 32f11b744a..5ebf52f07a 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -150,6 +150,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [Prompt variables and tool-guidance ownership](implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md) | 2026-07-05 | | [Every LLM request is reconstructable from the session log](implemented/architecture/2026-07-05-reconstructable-requests.md) | 2026-07-05 | | [Subagent provider-lifecycle events — `subagent/provider-added` / `subagent/provider-removed`](implemented/architecture/2026-07-05-subagent-provider-lifecycle-events.md) | 2026-07-05 | +| [Windows write-permission semantics — inherited DACLs, not mode bits](implemented/architecture/2026-07-05-windows-fs-permissions.md) | 2026-07-05 | | [Windows-native durable JSONL publication](implemented/architecture/2026-07-05-windows-jsonl-durable-publish.md) | 2026-07-05 | | [A shared timeout/deadline primitive, with hard-kill left to each capability](implemented/architecture/2026-07-06-timeout-deadline-library.md) | 2026-07-06 | | [Tool result retention library](implemented/architecture/2026-07-06-tool-result-retention-library.md) | 2026-07-06 | diff --git a/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md b/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md new file mode 100644 index 0000000000..0001e8223c --- /dev/null +++ b/docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md @@ -0,0 +1,29 @@ +# RFC: Windows write-permission semantics — inherited DACLs, not mode bits + +Status: implemented + +## Problem + +`writeFileAtomic` in `@deepseek-ai/dsh-fs-local` protects write-in-progress content with POSIX mode bits: the staging directory is created `0o700`, the temp file is opened `0o600`, and new files default to `0o600`. On POSIX this keeps temporary content owner-only regardless of the parent directory's permissions. + +Windows has no working equivalent behind the same API. Node's `chmod` there drives only the read-only attribute (every mode this package passes carries owner-write, so the calls are benign no-ops), and `stat().mode` reports synthetic `0o666`/`0o444` bits. The real security state is the file's DACL, which this code never sets; a newly created file or directory inherits its DACL from its parent directory. + +## Decision + +Production code is unchanged: no platform fork, no DACL management. The Windows privacy invariant is structural rather than mode-driven — the staging directory is created inside the target's parent directory (`dirname(absolutePath)`), so it and the temp file inherit exactly the destination directory's DACL, and write-in-progress content is never exposed more widely than the destination itself. In the typical deployment (a coding agent writing the user's own project tree under `C:\Users\\`) the inherited DACL is owner + SYSTEM + Administrators, matching the POSIX intent. + +Tests assert mode bits on POSIX only. There is no Windows-side ACL assertion because there is no Windows-side code behavior to pin: an ACL check on a `mkdtemp(tmpdir())` fixture would verify Windows DACL inheritance plus the machine's `%TEMP%` ACL — the operating system, not this package — and no change to this package could turn it red. + +## Alternatives considered + +**Explicit protected DACLs.** Granting owner-only access would require per-write FFI or a subprocess, break inheritance, and surprise users whose project directories are deliberately shared. This becomes appropriate only if the threat model includes hostile local readers of broadly accessible target directories. + +**Test-side ACL verification.** A `Get-Acl` SID allowlist or `icacls` would verify Windows inheritance and the machine's `%TEMP%` ACL rather than package behavior; `icacls` also localizes well-known account names, making parsing locale-fragile. + +**Skip `chmod` on Windows.** Platform-guarding benign no-op calls adds branches without changing behavior. + +## Consequences + +POSIX keeps the stronger guarantee: owner-only temp content regardless of the parent directory. Windows guarantees only "no wider than the destination": a target inside a broadly accessible directory (a share, a permissive `D:\` root) gets equally accessible write-in-progress content. The gap is deliberate and documented, not an oversight. + +Mode preservation across a replace degenerates to a no-op on Windows: a writable file probes as `0o666`, and replaying that through `chmod` leaves the read-only attribute clear. A read-only target cannot be replaced at all there — `rename` over it fails before the preserved mode would matter. diff --git a/packages/fs/fs-local/README.md b/packages/fs/fs-local/README.md index 65ed76efce..7c3899e5cb 100644 --- a/packages/fs/fs-local/README.md +++ b/packages/fs/fs-local/README.md @@ -16,7 +16,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() }) - **`stat` / `lstat`** — return target metadata or `undefined` when absent. `stat` reports `FsInfo` for an already resolved target (`version` = an opaque token derived from bigint `dev:ino:size:mtimeNs:ctimeNs`, `type` of `file`/`directory`/`other`, byte `size`); path-shaped `lstat` reports `FsPathInfo` without following the final symlink and can therefore return `symlink`. Both check cancellation before and after their asynchronous metadata probe, so an abort that lands in flight reports `FS_ABORTED` rather than stale absence. - **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` streams it in chunks (cross-chunk decoding) so a huge file never has to be held whole in memory. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) decides which to call by size and owns the line windowing. - **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other listing or child metadata I/O failures report `FS_IO_ERROR`. Broken/disappeared children are returned as `other` without metadata, but permission/IO failures while resolving a child fail the whole listing with a structured `FsError`. -- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`. The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`). +- **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`; on Windows the mode bits drive only the read-only attribute, and write-in-progress privacy comes instead from the staging dir inheriting the destination directory's DACL ([Windows write-permission RFC](../../../docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md)). The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`). - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`). The package-root SDK surface is the default/named `LocalFileSystem` class plus `Config`. Raw I/O lives in `src/fsio.ts` (Cordis-free, independently unit-tested); `src/index.ts` is the thin service wiring. diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts index e0745f1735..4603611ce4 100644 --- a/packages/fs/fs-local/src/fsio.ts +++ b/packages/fs/fs-local/src/fsio.ts @@ -408,9 +408,11 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow /** * Atomically replace a file through a private, synced staging file in the same directory. + * POSIX protects the staging directory and file with `0o700` and `0o600`; Windows + * inherits the destination directory's DACL because Node mode bits are synthetic there. * @param absolutePath - destination; missing parent directories are created. * @param content - the full UTF-8 text to write. - * @param mode - final mode, or `0o600` when omitted. + * @param mode - final POSIX mode, or `0o600` when omitted; inert on Windows. * @param signal - cancellation checked before the final rename. * @param internals - test seam for pinning temp names and observing the staged file. */ diff --git a/packages/fs/fs-local/tests/fsio.spec.ts b/packages/fs/fs-local/tests/fsio.spec.ts index 199c01f411..559ef86563 100644 --- a/packages/fs/fs-local/tests/fsio.spec.ts +++ b/packages/fs/fs-local/tests/fsio.spec.ts @@ -367,6 +367,12 @@ describe('streamWholeText', () => { }) }) +// Windows drives only the read-only attribute through `chmod` and reports +// synthetic `stat` mode bits, so mode assertions are POSIX-only; on Windows +// write-in-progress privacy comes from the destination directory's inherited +// DACL (docs/rfc/implemented/architecture/2026-07-05-windows-fs-permissions.md). +const posixModes = process.platform !== 'win32' + describe('writeFileAtomic — temp-file safety', () => { it('writes through a private staging dir and owner-only temp file', async () => { const file = join(dir, 'a.txt') @@ -374,17 +380,22 @@ describe('writeFileAtomic — temp-file safety', () => { await writeFileAtomic(file, 'hello', 0o640, undefined, { inspectTemp: async ({ stagingDir, tempPath }) => { inspected = true - expect((await stat(stagingDir)).mode & 0o777).toBe(0o700) - expect((await stat(tempPath)).mode & 0o777).toBe(0o600) + const [staging, temp] = await Promise.all([stat(stagingDir), stat(tempPath)]) + expect(staging.isDirectory()).toBe(true) + expect(temp.isFile()).toBe(true) + if (posixModes) { + expect(staging.mode & 0o777).toBe(0o700) + expect(temp.mode & 0o777).toBe(0o600) + } }, }) expect(inspected).toBe(true) expect(await readFile(file, 'utf8')).toBe('hello') - expect((await stat(file)).mode & 0o777).toBe(0o640) + if (posixModes) expect((await stat(file)).mode & 0o777).toBe(0o640) expect((await readdir(dir)).filter(n => n.includes('.tmp'))).toEqual([]) }) - it('creates new files owner-only by default', async () => { + it.skipIf(!posixModes)('creates new files owner-only by default', async () => { const file = join(dir, 'a.txt') await writeFileAtomic(file, 'hello', undefined, undefined) expect((await stat(file)).mode & 0o777).toBe(0o600) From 5a2ca3ff3aaa6b3410572c9a443ca98625b557ad Mon Sep 17 00:00:00 2001 From: Huanqi Cao Date: Fri, 17 Jul 2026 15:43:44 +0800 Subject: [PATCH 030/273] Restore JSONL ENOTDIR distinction on Windows --- .../session-persistence-jsonl/src/index.ts | 24 +++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts index ac1c07860e..2f33664139 100644 --- a/packages/session-persistence/session-persistence-jsonl/src/index.ts +++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts @@ -8,7 +8,7 @@ import { Context } from 'cordis' import z from 'schemastery' -import { open, mkdir, readFile, readdir, link, rm, truncate } from 'node:fs/promises' +import { open, mkdir, readFile, readdir, link, rm, stat as fsStat, truncate } from 'node:fs/promises' import { dirname, resolve } from 'node:path' import { randomBytes } from 'node:crypto' import { @@ -389,7 +389,27 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi } catch (error) { // Only ENOENT means absent. A permission/I/O error must surface rather // than letting load or collision checks proceed under false absence. - if (isENOENT(error)) return false + // Windows reports ENOENT, not ENOTDIR, for `regular-file/child`; verify + // the immediate parent so a blocked cwd bucket remains a storage fault. + if (isENOENT(error)) { + await this.assertLogParentAllowsAbsence(path) + return false + } + throw error + } + } + + private async assertLogParentAllowsAbsence(path: string): Promise { + try { + const parent = dirname(path) + const info = await fsStat(parent) + if (info.isDirectory()) return + const error = new Error(`ENOTDIR: parent path exists but is not a directory: ${parent}`) as NodeJS.ErrnoException + error.code = 'ENOTDIR' + error.path = parent + throw error + } catch (error) { + if (isENOENT(error)) return throw error } } From 86c09f6ca9d4bcec8226bd7a62febb1580bb96f4 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Fri, 17 Jul 2026 15:50:37 +0800 Subject: [PATCH 031/273] test(jsonl): mark native Windows ENOTDIR coverage --- docs/config-catalog.md | 2 +- .../session-persistence/session-persistence-jsonl/src/index.ts | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 3e3d8141fa..ba273888d1 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -634,7 +634,7 @@ export interface Config { } ``` -Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:24`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) +Source: [`packages/session-persistence/session-persistence-jsonl/src/index.ts:25`](../packages/session-persistence/session-persistence-jsonl/src/index.ts) ## `@deepseek-ai/dsh-session-persistence-sqlite` diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts index 2f33664139..39aa493a0b 100644 --- a/packages/session-persistence/session-persistence-jsonl/src/index.ts +++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts @@ -399,6 +399,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi } } + /* v8 ignore start -- native Windows coverage exercises this repair; POSIX open reports ENOTDIR before this point. */ private async assertLogParentAllowsAbsence(path: string): Promise { try { const parent = dirname(path) @@ -413,6 +414,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi throw error } } + /* v8 ignore stop */ } export default SessionPersistenceJsonl From beb13c3808c643a93e3a4b0d6fc698d050638321 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Fri, 17 Jul 2026 13:53:13 +0800 Subject: [PATCH 032/273] test(acp): pin Windows-native snapshot paths --- examples/acp-agent/tests/acp.snapshot.ts | 10 +- .../stdout.golden.windows.jsonl | 132 ++++++++++++++++++ packages/support/acp-snapshot/README.md | 10 +- packages/support/acp-snapshot/src/harness.ts | 11 +- packages/support/acp-snapshot/src/index.ts | 2 + .../support/acp-snapshot/src/normalize.ts | 66 +++++++-- packages/support/acp-snapshot/src/suite.ts | 49 ++++++- .../acp-snapshot/tests/harness.spec.ts | 7 +- .../acp-snapshot/tests/normalize.spec.ts | 77 ++++++++++ .../support/acp-snapshot/tests/suite.spec.ts | 26 ++++ 10 files changed, 367 insertions(+), 23 deletions(-) create mode 100644 examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index 23eca9dbc0..e68724cbfe 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -57,7 +57,15 @@ const SCENARIOS: Scenario[] = [ { name: 'fs-terminal-card', hasModelTurn: true, recorded: true }, { name: 'todo-plan', hasModelTurn: true, recorded: true }, { name: 'skill-load', hasModelTurn: true, recorded: false, pinsHeader: true, headerClass: 'skill' }, - { name: 'workspace-edit', hasModelTurn: true, recorded: true, pinsHeader: true, headerClass: 'fs', configPath: FS_CONFIG }, + { + name: 'workspace-edit', + hasModelTurn: true, + recorded: true, + pinsHeader: true, + pinsNativeWindowsStdout: true, + headerClass: 'fs', + configPath: FS_CONFIG, + }, { name: 'fs-read', hasModelTurn: true, recorded: true, headerClass: 'fs', configPath: FS_CONFIG }, { name: 'fs-write', hasModelTurn: true, recorded: true, headerClass: 'fs', configPath: FS_CONFIG }, { name: 'fs-edit', hasModelTurn: true, recorded: true, headerClass: 'fs', configPath: FS_CONFIG }, diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl new file mode 100644 index 0000000000..5f8762adcd --- /dev/null +++ b/examples/acp-agent/tests/snapshots/workspace-edit/stdout.golden.windows.jsonl @@ -0,0 +1,132 @@ +{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}} +{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"Sets this session's sandbox and approval behavior.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" user"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" wants"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Read"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" greeting"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":".txt"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Append"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" word"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" WORLD"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" as"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" second"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" line"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"3"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Read"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" back"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" cat"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" confirm"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"4"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Reply"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" D"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" start"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" by"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reading"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" see"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" its"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" contents"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_OjRFB4zvxu6UALDjytZD0978","title":"Read greeting.txt","kind":"read","status":"in_progress","locations":[{"path":"greeting.txt","line":1}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_OjRFB4zvxu6UALDjytZD0978","status":"completed","content":[{"type":"content","content":{"type":"text","text":"{{cwd}}\\greeting.txt\nfile\n\n1: hello\n\n(End of file - total 1 lines)\n"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" contains"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"hello"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" on"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" one"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" line"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Now"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" I"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" need"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" append"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" a"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" second"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" line"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"WOR"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"LD"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\""}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" it"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" Then"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" cat"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" it"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" confirm"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_IUUvbNiPcnwhVL8ErEFS4806","title":"printf '\\nWORLD' >> greeting.txt","kind":"execute","status":"in_progress","rawInput":"printf '\\nWORLD' >> greeting.txt","content":[{"type":"content","content":{"type":"text","text":"Append newline and WORLD to greeting.txt"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_IUUvbNiPcnwhVL8ErEFS4806","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```console\n(no output)\n```"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"Good"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":","}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" now"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" let"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" me"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" read"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" back"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" cat"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_Wo4H7tFNheZJWKVDrAHK5851","title":"cat greeting.txt","kind":"execute","status":"in_progress","rawInput":"cat greeting.txt","content":[{"type":"content","content":{"type":"text","text":"Read greeting.txt to confirm"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_Wo4H7tFNheZJWKVDrAHK5851","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```console\nhello\n\nWORLD\n```"}}]}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" now"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" has"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" two"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" lines"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":":\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"1"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" hello"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"2"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" WORLD"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"\n\n"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"I"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" can"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" reply"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" D"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"D"}}}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"ONE"}}}} +{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md index 222d572043..9969eadb46 100644 --- a/packages/support/acp-snapshot/README.md +++ b/packages/support/acp-snapshot/README.md @@ -4,9 +4,9 @@ The ACP snapshot suite kit: the shared machinery behind the keyless snapshot tie Three layers, importable separately: -- **`runScenario` (harness)** — boots the real agent bin as a subprocess via tsx (unbuilt, Loader path), drives it over ACP JSON-RPC stdio from a deterministic `input.json` script, tees raw stdout for the golden + purity check, and harvests every persisted session JSONL (parent + subagent children, primary-first) after a graceful stdin-EOF shutdown. Parameterized by `AgentUnderTest` (`binScript`, `configPath`, `tsconfigPath` — absolute paths; the subprocess cwd is a temp dir outside the repo). Startup failures preserve captured agent stderr in the rejected diagnostic. -- **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), and `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header RFC](../../../docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)). -- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario golden + re-persisted-log compares, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, the per-header-class pin (`system-prompt.golden.md` plus `tool-schemas.golden.json`) with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL prompt/schema-scrubbed, non-pinning fixtures fully header-scrubbed). Must be called at vitest collection time. +- **`runScenario` (harness)** — boots the real agent bin in the selected example mode: source under tsx or built `lib` under plain Node. It drives ACP JSON-RPC stdio from a deterministic `input.json` script, tees raw stdout for the golden and purity check, and harvests every persisted session JSONL (parent and subagent children, primary-first) after graceful stdin EOF. `AgentUnderTest` supplies absolute `binScript`, `configPath`, and `tsconfigPath` paths because the subprocess cwd is a temp directory outside the repo. Startup failures preserve captured agent stderr in the rejected diagnostic. +- **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; cwd-rooted separators → `/` for shared goldens; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), and `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header RFC](../../../docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)). +- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario shared golden + re-persisted-log compares, optional Windows-native stdout sidecars, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, the per-header-class pin (`system-prompt.golden.md` plus `tool-schemas.golden.json`) with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL prompt/schema-scrubbed, non-pinning fixtures fully header-scrubbed). Must be called at vitest collection time. A consuming `*.snapshot.ts` is the scenario table plus one factory call: @@ -37,6 +37,8 @@ defineAcpSnapshotSuite({ A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode and filesystem scenarios are templates. Each pinning directory stores the normalized full prompt sequence in generated `system-prompt.golden.md` and the corresponding full tool-schema sequence in generated `tool-schemas.golden.json`; `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. A pin with legitimate mid-run header changes declares `expectedHeaderChanges`, which fixes the length of both sidecar sequences. +Every scenario compares `stdout.golden.jsonl` with cwd-rooted separators canonicalized to `/`. A scenario may set `pinsNativeWindowsStdout` to add a Windows-only comparison against the complete `stdout.golden.windows.jsonl`; the shared golden still runs first on Windows, and the fixture guard requires the sidecar exactly when declared. + Examples use a `cordis.snapshot.yml` overlay with [`dsh-llm-replay`](../llm-replay/README.md). Recording calls the live model and updates model fixtures; keyless refresh replays those fixtures and updates derived stdout, session-log, prompt, and tool-schema snapshots. See the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md). `suite.ts` imports Vitest, so use this package only inside a Vitest run. The ACP-specific script queues permission answers by stable option kind and maps them to current option ids; a missing answer cancels, while an unavailable kind fails the scenario after cancelling the agent request. It can also set session config options or assert that unknown ids and values are rejected in the transcript. @@ -48,4 +50,4 @@ None, as this test-only harness records, normalizes, and compares ACP transcript ## Known Limitations and Deferred Work - **Session harvest is JSONL-only** — `runScenario` collects persisted `.jsonl` logs, so an example composed over the SQLite persistence backend has no snapshot path. -- **The subprocess boots the unbuilt tsx/Loader path only** — the built-bin artifact is guarded by the separate `built-bin` e2e smokes, never by this tier. +- **Built mode requires current artifacts** — run `pnpm run build` before selecting `DSH_EXAMPLE_MODE=lib`; source mode remains the zero-build path. diff --git a/packages/support/acp-snapshot/src/harness.ts b/packages/support/acp-snapshot/src/harness.ts index e2072b6b17..cf8d7afc27 100644 --- a/packages/support/acp-snapshot/src/harness.ts +++ b/packages/support/acp-snapshot/src/harness.ts @@ -150,6 +150,15 @@ export interface RunOptions { configPath?: string } +/** + * Return a fixed-length spill root across POSIX and Windows after Windows adds its drive prefix. + * @param platform - the host platform, injectable for unit coverage. + * @returns the root-relative snapshot spill directory. + */ +export function snapshotSpillRoot(platform: NodeJS.Platform = process.platform): string { + return platform === 'win32' ? '/t/dsh-acp-snapshot-spill' : '/tmp/dsh-acp-snapshot-spill' +} + /** * Run a scenario end-to-end against a freshly-spawned subprocess. Owns the * child and its temp dirs; always tears them down. Returns the captured stdout @@ -164,7 +173,7 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise const sessionsRoot = await mkdtemp(join(tmpdir(), 'acp-snap-sessions-')) // Fixed path length: spill-policy budgets the preview against the REAL path // before stdout normalization, so tmpdir() length differences churn goldens. - const spillRoot = '/tmp/dsh-acp-snapshot-spill' + const spillRoot = snapshotSpillRoot() // Everything past the temp-dir creation runs under a try/finally that always // removes both dirs — so a failure in workspace seeding, spawn, or any step // never leaks them (the "e2e tests own their resources" rule). diff --git a/packages/support/acp-snapshot/src/index.ts b/packages/support/acp-snapshot/src/index.ts index bdf8cccaf7..46eac5568b 100644 --- a/packages/support/acp-snapshot/src/index.ts +++ b/packages/support/acp-snapshot/src/index.ts @@ -21,7 +21,9 @@ export { scrubRequestHeaders, scrubSystemPrompts, scrubToolSchemas, + type CwdPathMode, type NormalizeContext, + type NormalizeOptions, } from './normalize.ts' export { defineAcpSnapshotSuite, diff --git a/packages/support/acp-snapshot/src/normalize.ts b/packages/support/acp-snapshot/src/normalize.ts index 48761864f0..76bd40d610 100644 --- a/packages/support/acp-snapshot/src/normalize.ts +++ b/packages/support/acp-snapshot/src/normalize.ts @@ -12,19 +12,33 @@ const SYSTEM = '{{system}}' const TOOLS = '{{tools}}' const MESSAGE_PREFIX = '{{messagePrefix}}' +/** A cwd-rooted path after volatile cwd replacement, through its last separator-delimited segment. */ +const CWD_ROOTED_PATH_RE = /\{\{cwd\}\}(?:[\\/][^\s<>"'`]+)+/g +const PATH_TAG_RE = /()([^<]*)(<\/path>)/g +const ADDITIONAL_INSTRUCTIONS_PATH_RE = /(Additional instructions from: )([^\r\n]+)/g + /** A UUID v4 string, the shape `randomUUID()` produces for session ids. */ const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi const LOCAL_SPILL_PATH_RE = new RegExp( - String.raw`\{\{cwd\}\}/\.spill/session-[0-9a-f]{12}/[0-9a-f]{12}-([A-Za-z0-9._~-]+?)` + String.raw`\{\{cwd\}\}[\\/]\.spill[\\/]session-[0-9a-f]{12}[\\/][0-9a-f]{12}-([A-Za-z0-9._~-]+?)` + String.raw`(?=\. Use read with offset/limit|[\s)]|$)`, 'g', ) const SNAPSHOT_SPILL_PATH_RE = new RegExp( - String.raw`/tmp/dsh-acp-snapshot-spill/session-[0-9a-f]{12}/[0-9a-f]{12}-([A-Za-z0-9._~-]+?)` + String.raw`(?:[A-Za-z]:)?[\\/](?:tmp|t)[\\/]dsh-acp-snapshot-spill[\\/]session-[0-9a-f]{12}[\\/][0-9a-f]{12}-([A-Za-z0-9._~-]+?)` + String.raw`(?=\. Use read with offset/limit|[\s)]|$)`, 'g', ) +/** Convert separators only inside generated path-bearing text markers. */ +function canonicalizeEmbeddedPaths(value: string): string { + return value + .replace(PATH_TAG_RE, (_match, open: string, path: string, close: string) => + `${open}${path.replaceAll('\\', '/')}${close}`) + .replace(ADDITIONAL_INSTRUCTIONS_PATH_RE, (_match, prefix: string, path: string) => + `${prefix}${path.replaceAll('\\', '/')}`) +} + /** Inputs the normalizers need to recognize a run's volatile values. */ export interface NormalizeContext { /** The session id(s) the run issued — replaced with `{{sessionId}}`. */ @@ -33,13 +47,28 @@ export interface NormalizeContext { cwd: string } +/** How cwd-rooted path separators are represented after the cwd is tokenized. */ +export type CwdPathMode = 'canonical' | 'native' + +/** Optional controls shared by stdout and session-log normalization. */ +export interface NormalizeOptions { + /** Use `/` for shared goldens, or preserve captured separators for a platform-specific golden. */ + cwdPathMode?: CwdPathMode +} + /** Replace cwd, session ids, and any stray UUID with stable tokens in a string. */ -function scrubString(value: string, ctx: NormalizeContext): string { +function scrubString(value: string, ctx: NormalizeContext, cwdPathMode: CwdPathMode): string { let out = value // cwd first (longest, most specific), then explicit session ids, then any // residual UUID (covers ids that appear in places we didn't enumerate). out = out.split(ctx.cwd).join(CWD) out = out.split(`/private${CWD}`).join(CWD) + if (cwdPathMode === 'canonical') { + // Restrict separator conversion to paths rooted at the cwd token. A global + // backslash rewrite would corrupt regexes, commands, and model-authored text. + out = out.replace(CWD_ROOTED_PATH_RE, path => path.replaceAll('\\', '/')) + out = canonicalizeEmbeddedPaths(out) + } out = out.replace(LOCAL_SPILL_PATH_RE, (_match, name: string) => `{{spillLocator:${name}}}`) out = out.replace(SNAPSHOT_SPILL_PATH_RE, (_match, name: string) => `{{spillLocator:${name}}}`) for (const id of ctx.sessionIds) out = out.split(id).join(SESSION_ID) @@ -48,12 +77,15 @@ function scrubString(value: string, ctx: NormalizeContext): string { } /** Recursively scrub a parsed JSON value (strings replaced; structure kept). */ -function scrubValue(value: unknown, ctx: NormalizeContext): unknown { - if (typeof value === 'string') return scrubString(value, ctx) - if (Array.isArray(value)) return value.map(v => scrubValue(v, ctx)) +function scrubValue(value: unknown, ctx: NormalizeContext, cwdPathMode: CwdPathMode, key?: string): unknown { + if (typeof value === 'string') { + const scrubbed = scrubString(value, ctx, cwdPathMode) + return cwdPathMode === 'canonical' && key === 'path' ? scrubbed.replaceAll('\\', '/') : scrubbed + } + if (Array.isArray(value)) return value.map(v => scrubValue(v, ctx, cwdPathMode)) if (value !== null && typeof value === 'object') { const out: Record = {} - for (const [k, v] of Object.entries(value)) out[k] = scrubValue(v, ctx) + for (const [k, v] of Object.entries(value)) out[k] = scrubValue(v, ctx, cwdPathMode, k) return out } return value @@ -67,9 +99,15 @@ function scrubValue(value: unknown, ctx: NormalizeContext): unknown { * * @param rawStdout The captured stdout bytes, decoded utf8. * @param ctx The run's volatile values to scrub. + * @param options Separator output controls; shared canonical paths are the default. * @returns The normalized NDJSON transcript, one frame per line. */ -export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): string { +export function normalizeStdout( + rawStdout: string, + ctx: NormalizeContext, + options: NormalizeOptions = {}, +): string { + const cwdPathMode = options.cwdPathMode ?? 'canonical' const lines = rawStdout.split('\n').filter(line => line.trim().length > 0) // Map each distinct JSON-RPC id (request/response correlate by id) to a stable // sequence number, in first-seen order, so id churn doesn't perturb the golden. @@ -85,7 +123,7 @@ export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): strin if ('id' in frame && frame.id !== undefined && frame.id !== null) { frame.id = stableId(frame.id) } - return scrubValue(frame, ctx) as Record + return scrubValue(frame, ctx, cwdPathMode) as Record }) return frames.map(f => JSON.stringify(f)).join('\n') + '\n' } @@ -99,9 +137,15 @@ export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): strin * * @param rawLog The raw session `.jsonl` content. * @param ctx The run's volatile values to scrub. + * @param options Separator output controls; shared canonical paths are the default. * @returns The normalized JSONL log, one record per line. */ -export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): string { +export function normalizeSessionLog( + rawLog: string, + ctx: NormalizeContext, + options: NormalizeOptions = {}, +): string { + const cwdPathMode = options.cwdPathMode ?? 'canonical' const lines = rawLog.split('\n').filter(line => line.trim().length > 0) const records = lines.map((line) => { const record = JSON.parse(line) as Record @@ -119,7 +163,7 @@ export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): stri if ('durationMs' in data) data.durationMs = 0 } } - return scrubValue(record, ctx) as Record + return scrubValue(record, ctx, cwdPathMode) as Record }) return records.map(r => JSON.stringify(r)).join('\n') + '\n' } diff --git a/packages/support/acp-snapshot/src/suite.ts b/packages/support/acp-snapshot/src/suite.ts index 322439bb01..7fdc70dc67 100644 --- a/packages/support/acp-snapshot/src/suite.ts +++ b/packages/support/acp-snapshot/src/suite.ts @@ -21,6 +21,7 @@ import { join } from 'node:path' import { describe, expect, it } from 'vitest' import { type AgentUnderTest, type HarvestedLog, type InputScript, runScenario } from './harness.ts' import { + type CwdPathMode, type NormalizeContext, normalizeSessionLog, normalizeStdout, @@ -35,6 +36,9 @@ const SYSTEM_PROMPT_SNAPSHOT = 'system-prompt.golden.md' /** The structured tool-schema snapshot beside each header-pinning fixture. */ const TOOL_SCHEMAS_SNAPSHOT = 'tool-schemas.golden.json' +/** The optional full Windows-native stdout transcript. */ +const WINDOWS_STDOUT_SNAPSHOT = 'stdout.golden.windows.jsonl' + /** Stable session-log token standing in for the sidecar's initial schemas. */ const TOOLS_TOKEN = '{{tools}}' @@ -108,6 +112,35 @@ export interface Scenario { * {@link headerClass}. */ configPath?: string + /** + * Whether Windows additionally compares stdout with native separators against + * `stdout.golden.windows.jsonl`. The shared canonical stdout golden is still + * compared on every platform, and the fixture guard requires this sidecar + * exactly when the option is set. + */ + pinsNativeWindowsStdout?: boolean +} + +/** One stdout golden selected for a platform run. */ +interface StdoutGoldenVariant { + file: string + cwdPathMode: CwdPathMode +} + +/** + * Select the shared stdout golden plus any platform-native assertion declared by a scenario. + * + * @param scenario The scenario whose stdout contract is being selected. + * @param platform The running Node platform, injectable for unit coverage. + * @returns The ordered golden variants: shared canonical first, then optional Windows native. + */ +export function stdoutGoldenVariants( + scenario: Scenario, + platform: NodeJS.Platform = process.platform, +): StdoutGoldenVariant[] { + const canonical: StdoutGoldenVariant = { file: 'stdout.golden.jsonl', cwdPathMode: 'canonical' } + if (platform !== 'win32' || scenario.pinsNativeWindowsStdout !== true) return [canonical] + return [canonical, { file: WINDOWS_STDOUT_SNAPSHOT, cwdPathMode: 'native' }] } /** One suite's inputs: the agent to boot, where its fixtures live, and its scenario table. */ @@ -530,11 +563,13 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void { } } - const stdout = normalizeStdout(result.rawStdout, ctx) - if (REFRESHING) { - await writeFile(join(dir, 'stdout.golden.jsonl'), stdout) + for (const golden of stdoutGoldenVariants(scenario)) { + const stdout = normalizeStdout(result.rawStdout, ctx, { cwdPathMode: golden.cwdPathMode }) + if (REFRESHING) { + await writeFile(join(dir, golden.file), stdout) + } + await expect(stdout, `${golden.file} mismatch`).toMatchFileSnapshot(join(dir, golden.file)) } - await expect(stdout).toMatchFileSnapshot(join(dir, 'stdout.golden.jsonl')) // A model turn always produces a log worth comparing; a hook scenario can // produce one without a model turn (a `rejected` turn carrying `hook/*`). @@ -621,10 +656,14 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void { it('every registered scenario has its required fixture files', () => { // Every scenario has an input script and an stdout golden. - for (const { name, overridden, childSessions, pinsHeader } of scenarios) { + for (const { name, overridden, childSessions, pinsHeader, pinsNativeWindowsStdout } of scenarios) { const dir = join(snapshotsDir, name) expect(existsSync(join(dir, 'input.json')), `${name}/input.json`).toBe(true) expect(existsSync(join(dir, 'stdout.golden.jsonl')), `${name}/stdout.golden.jsonl`).toBe(true) + expect( + existsSync(join(dir, WINDOWS_STDOUT_SNAPSHOT)), + `${name}/${WINDOWS_STDOUT_SNAPSHOT} presence must match \`pinsNativeWindowsStdout\``, + ).toBe(pinsNativeWindowsStdout === true) expect(existsSync(join(dir, 'session.jsonl')), `${name}/session.jsonl`).toBe(true) expect(existsSync(join(dir, 'replay.override.json')), `${name}/replay.override.json presence must match \`overridden\``) .toBe(overridden === true) diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts index d141fb1f09..35fcb21d09 100644 --- a/packages/support/acp-snapshot/tests/harness.spec.ts +++ b/packages/support/acp-snapshot/tests/harness.spec.ts @@ -3,7 +3,7 @@ import { tmpdir } from 'node:os' import { delimiter, join } from 'node:path' import { fileURLToPath } from 'node:url' import { afterAll, describe, expect, it } from 'vitest' -import { runScenario, type AgentUnderTest, type InputStep } from '../src/harness.ts' +import { runScenario, snapshotSpillRoot, type AgentUnderTest, type InputStep } from '../src/harness.ts' /** * Unit tests for the subprocess harness, driven through the REAL spawn path @@ -39,6 +39,11 @@ async function scenario(behavior: object): Promise<{ dir: string; fixtureFile: s const boot: InputStep[] = [{ op: 'initialize' }, { op: 'newSession' }] +it('keeps the resolved snapshot spill root length stable across platforms', () => { + expect(snapshotSpillRoot('linux')).toBe('/tmp/dsh-acp-snapshot-spill') + expect(snapshotSpillRoot('win32')).toBe('/t/dsh-acp-snapshot-spill') +}) + describe('runScenario', () => { it('includes agent stderr when the ACP connection closes during startup', { timeout: 20_000 }, async () => { const { fixtureFile } = await scenario({ failOnBoot: true, stderrNote: 'fake agent requested startup failure' }) diff --git a/packages/support/acp-snapshot/tests/normalize.spec.ts b/packages/support/acp-snapshot/tests/normalize.spec.ts index 2beaba5114..fed086fec7 100644 --- a/packages/support/acp-snapshot/tests/normalize.spec.ts +++ b/packages/support/acp-snapshot/tests/normalize.spec.ts @@ -44,6 +44,56 @@ describe('normalizeStdout', () => { expect(out).not.toContain(ctx.sessionIds[0] as string) }) + it('canonicalizes only cwd-rooted path separators', () => { + const windowsCtx: NormalizeContext = { + sessionIds: [], + cwd: String.raw`C:\Users\runner\AppData\Local\Temp\acp-snapshot`, + } + const raw = JSON.stringify({ + jsonrpc: '2.0', + method: 'session/update', + params: { + path: `${windowsCtx.cwd}\\nested\\proof.txt`, + regex: String.raw`\d+\w+`, + command: String.raw`printf "\\n"`, + }, + }) + const frame = JSON.parse(normalizeStdout(raw, windowsCtx)) as { + params: { path: string; regex: string; command: string } + } + expect(frame.params).toEqual({ + path: '{{cwd}}/nested/proof.txt', + regex: String.raw`\d+\w+`, + command: String.raw`printf "\\n"`, + }) + }) + + it('canonicalizes generated relative path fields and text markers without rewriting other text', () => { + const raw = JSON.stringify({ + path: String.raw`nested\AGENTS.md`, + content: String.raw`.\nested\task.txt +Additional instructions from: nested\AGENTS.md`, + regex: String.raw`\d+\w+`, + }) + const frame = JSON.parse(normalizeStdout(raw, { sessionIds: [], cwd: '/unused' })) as { + path: string + content: string + regex: string + } + expect(frame).toEqual({ + path: 'nested/AGENTS.md', + content: './nested/task.txt\nAdditional instructions from: nested/AGENTS.md', + regex: String.raw`\d+\w+`, + }) + }) + + it('can preserve native cwd-rooted separators for a platform golden', () => { + const windowsCtx: NormalizeContext = { sessionIds: [], cwd: String.raw`C:\work\snapshot` } + const raw = JSON.stringify({ path: `${windowsCtx.cwd}\\nested\\proof.txt` }) + const frame = JSON.parse(normalizeStdout(raw, windowsCtx, { cwdPathMode: 'native' })) as { path: string } + expect(frame.path).toBe(String.raw`{{cwd}}\nested\proof.txt`) + }) + it('scrubs a stray UUID not in the known list', () => { const raw = JSON.stringify({ jsonrpc: '2.0', method: 'x', params: { id: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' } }) expect(normalizeStdout(raw, ctx)).toContain('{{sessionId}}') @@ -139,6 +189,33 @@ describe('normalizeSessionLog', () => { expect(out).not.toContain('/tmp/dsh-acp-snapshot-spill') }) + it('scrubs fixed snapshot spill paths with Windows drive and separators', () => { + const ev = JSON.stringify({ + type: 'tool/result', seq: 2, time: 5, + data: { + content: [{ + type: 'text', + text: String.raw`Full formatted result stored at: C:\t\dsh-acp-snapshot-spill\session-c22bc3f1d2af\8a7b6c5d4e3f-bash.txt. Use read with offset/limit, or grep this path to search within it.`, + }], + }, + }) + const out = normalizeSessionLog(`${header({ cwd: ctx.cwd })}\n${ev}\n`, ctx) + expect(out).toContain('{{spillLocator:bash.txt}}') + expect(out).not.toContain('C:\\t\\dsh-acp-snapshot-spill') + }) + + it('shares cwd-rooted path handling with stdout normalization', () => { + const windowsCtx: NormalizeContext = { sessionIds: [], cwd: String.raw`C:\work\snapshot` } + const ev = JSON.stringify({ + type: 'tool/result', seq: 2, time: 5, + data: { path: `${windowsCtx.cwd}\\nested\\proof.txt` }, + }) + expect(normalizeSessionLog(`${header({ cwd: windowsCtx.cwd })}\n${ev}\n`, windowsCtx)) + .toContain('{{cwd}}/nested/proof.txt') + expect(normalizeSessionLog(`${header({ cwd: windowsCtx.cwd })}\n${ev}\n`, windowsCtx, { cwdPathMode: 'native' })) + .toContain(String.raw`{{cwd}}\\nested\\proof.txt`) + }) + it('scrubs the session id in the header', () => { const out = normalizeSessionLog(`${header({ id: ctx.sessionIds[0] })}\n`, ctx) expect(out).toContain('{{sessionId}}') diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts index c2007321de..24812029dc 100644 --- a/packages/support/acp-snapshot/tests/suite.spec.ts +++ b/packages/support/acp-snapshot/tests/suite.spec.ts @@ -18,6 +18,7 @@ import { refreshFixtureReplacements, restorePinnedToolSchemas, stabilizeRefreshLog, + stdoutGoldenVariants, unknownToolCallIds, } from '../src/suite.ts' @@ -189,6 +190,31 @@ describe('childFixturePaths', () => { }) }) +describe('stdoutGoldenVariants', () => { + const scenario: Scenario = { + name: 'windows-native', + hasModelTurn: true, + recorded: true, + pinsNativeWindowsStdout: true, + } + + it('adds the native sidecar after the shared golden on Windows', () => { + expect(stdoutGoldenVariants(scenario, 'win32')).toEqual([ + { file: 'stdout.golden.jsonl', cwdPathMode: 'canonical' }, + { file: 'stdout.golden.windows.jsonl', cwdPathMode: 'native' }, + ]) + }) + + it('keeps only the shared golden on other platforms or without the declaration', () => { + expect(stdoutGoldenVariants(scenario, 'linux')).toEqual([ + { file: 'stdout.golden.jsonl', cwdPathMode: 'canonical' }, + ]) + expect(stdoutGoldenVariants({ ...scenario, pinsNativeWindowsStdout: false }, 'win32')).toEqual([ + { file: 'stdout.golden.jsonl', cwdPathMode: 'canonical' }, + ]) + }) +}) + describe('fixtureContext', () => { it('reads the fixture header id and cwd', () => { const ctx = fixtureContext('{"type":"session","id":"abc","cwd":"/rec"}\n{"type":"turn/start"}\n') From b5fa2cb2b8c3a320f773e21695daa7a8b222cc87 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Fri, 17 Jul 2026 12:30:16 +0800 Subject: [PATCH 033/273] test(windows): skip unsupported SDK test surfaces --- .../sdk/create-sdk/tests/create.snapshot.ts | 2 +- vitest.config.ts | 18 +++++++++++++++++- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/packages/sdk/create-sdk/tests/create.snapshot.ts b/packages/sdk/create-sdk/tests/create.snapshot.ts index a5ea46db53..4733653a0d 100644 --- a/packages/sdk/create-sdk/tests/create.snapshot.ts +++ b/packages/sdk/create-sdk/tests/create.snapshot.ts @@ -71,7 +71,7 @@ class RecordingPort implements PromptPort { } } -describe('create-sdk terminal contract', () => { +describe.skipIf(process.platform === 'win32')('create-sdk terminal contract', () => { it('renders package-manager-specific setup commands', () => { const model = packageManagerTemplateModel(createPackageManager('yarn', '4.0.0')) expect(CREATE_TEMPLATES.installQuestion.render(model)).toBe('Run yarn install and then build the project?\n') diff --git a/vitest.config.ts b/vitest.config.ts index c0946e2e10..1001b7daa3 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -1,6 +1,16 @@ import tsconfigPaths from 'vite-tsconfig-paths' import { defineConfig } from 'vitest/config' +const windowsUnsupportedPackages = process.platform === 'win32' + ? [ + 'packages/bash/*', + 'packages/hooks/*', + 'packages/sandbox/sandbox-local', + 'packages/sdk/create-sdk', + 'packages/sdk/helper', + ] + : [] + export default defineConfig({ // Native path resolution reads each package's nearest tsconfig, but only the root defines // workspace paths. Keep this plugin pinned to the root map so unbuilt bare package imports resolve @@ -8,6 +18,7 @@ export default defineConfig({ plugins: [tsconfigPaths({ projects: ['./tsconfig.json'] })], test: { include: ['packages/*/*/tests/**/*.spec.ts', 'examples/*/tests/**/*.spec.ts', 'scripts/**/*.spec.ts'], + exclude: windowsUnsupportedPackages.map(path => `${path}/tests/**/*.spec.ts`), coverage: { provider: 'v8', // Coverage measures OUR runtime source. Types-only files carry no @@ -16,7 +27,12 @@ export default defineConfig({ include: ['packages/*/*/src/**/*.ts'], // Types-only files have no runtime coverage. Importing self-executing bins/workers would boot // them inside the unit process, so real subprocess/Worker tests cover their thin entry glue. - exclude: ['packages/*/*/src/types.ts', 'packages/*/*/src/bin.ts', 'packages/*/*/src/worker.ts'], + exclude: [ + 'packages/*/*/src/types.ts', + 'packages/*/*/src/bin.ts', + 'packages/*/*/src/worker.ts', + ...windowsUnsupportedPackages.map(path => `${path}/src/**/*.ts`), + ], // 100% or it doesn't merge (docs/testing.md: excessive tests are welcome). // Per-file so a well-covered big file can't subsidize a bare one. // Every v8 ignore comment must carry a reason — see the quality-gates RFC From 228f6e3867ce4cdbbd2d4edb85ef132c91e5634c Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Fri, 17 Jul 2026 15:44:19 +0800 Subject: [PATCH 034/273] test(windows): skip POSIX-only assertions --- .../workspace-context/tests/workspace-context.spec.ts | 2 +- packages/spill/spill-local/tests/spill-local.spec.ts | 2 +- packages/subagent/subagent-acp/tests/subagent-acp.spec.ts | 2 +- .../subagent-subprocess/tests/subagent-subprocess.spec.ts | 5 +++-- 4 files changed, 6 insertions(+), 5 deletions(-) diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts index b3a9947221..5f04b3a485 100644 --- a/packages/context/workspace-context/tests/workspace-context.spec.ts +++ b/packages/context/workspace-context/tests/workspace-context.spec.ts @@ -2403,7 +2403,7 @@ describe('dynamic nested workspace context injection', () => { } }) - it('skips unreadable nested instruction files without attaching empty context', async () => { + it.skipIf(process.platform === 'win32')('skips unreadable nested instruction files without attaching empty context', async () => { const root = await tempRepo() const home = await tempRepo() try { diff --git a/packages/spill/spill-local/tests/spill-local.spec.ts b/packages/spill/spill-local/tests/spill-local.spec.ts index d73fca9fe3..b4abc6e3d6 100644 --- a/packages/spill/spill-local/tests/spill-local.spec.ts +++ b/packages/spill/spill-local/tests/spill-local.spec.ts @@ -84,7 +84,7 @@ describe('saveTextFile', () => { expect(saved.path.includes('/..')).toBe(false) }) - it('creates the session dir with owner-only permissions', async () => { + it.skipIf(process.platform === 'win32')('creates the session dir with owner-only permissions', async () => { const saved = await saveTextFile({ root, sessionId: 'sess-1', suggestedName: 'r.txt', content: 'x' }) // 0o700 dir, 0o600 file (masked by umask, but the owner bits must hold). expect(statSync(dirname(saved.path)).mode & 0o700).toBe(0o700) diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts index bfc8476bae..e3fd3eda48 100644 --- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts +++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts @@ -263,7 +263,7 @@ describe('dsh-subagent-acp', () => { } }) - it('escalates to SIGTERM for a child that ignores EOF but is not SIGTERM-trapping', async () => { + it.skipIf(process.platform === 'win32')('escalates to SIGTERM for a child that ignores EOF but is not SIGTERM-trapping', async () => { // A child that keeps its loop alive past stdin EOF (so the graceful window // times out) but exits cooperatively on SIGTERM must die on the SIGTERM tier // — dispose returns there, never reaching the SIGKILL tier. The child touches diff --git a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts index bdc0260c73..8ed3891578 100644 --- a/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts +++ b/packages/subagent/subagent-subprocess/tests/subagent-subprocess.spec.ts @@ -258,8 +258,9 @@ describe('createIsolatedConfigDir', () => { expect(dir.path.startsWith(join(tmpdir(), 'dsh-subagent-subprocess-test-'))).toBe(true) const st = await stat(dir.path) expect(st.isDirectory()).toBe(true) - // Private (0700) per the defensive-patterns temp-dir rule. - expect(st.mode & 0o777).toBe(0o700) + // Windows reports synthetic POSIX mode bits; privacy comes from the + // inherited directory ACL rather than chmod-compatible mode bits. + if (process.platform !== 'win32') expect(st.mode & 0o777).toBe(0o700) } finally { await dir.remove() } From 7e620db8ba470cc48b44c8a1887208b03206bd3a Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Fri, 17 Jul 2026 21:08:59 +0800 Subject: [PATCH 035/273] test(windows): use host path semantics --- .../tests/workspace-context.spec.ts | 46 +++++++++---------- .../fs/tool-fs-search/tests/tools.spec.ts | 7 +-- .../spill-local/tests/spill-local.spec.ts | 7 +-- packages/util/paths/tests/paths.spec.ts | 4 +- 4 files changed, 33 insertions(+), 31 deletions(-) diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts index 5f04b3a485..9de003ae8d 100644 --- a/packages/context/workspace-context/tests/workspace-context.spec.ts +++ b/packages/context/workspace-context/tests/workspace-context.spec.ts @@ -1,5 +1,5 @@ import { chmod, mkdtemp, mkdir, rm, stat, symlink, utimes, writeFile } from 'node:fs/promises' -import { dirname, join } from 'node:path' +import { dirname, join, resolve } from 'node:path' import { tmpdir } from 'node:os' import { describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' @@ -61,7 +61,7 @@ class RecordingFileSystem extends FileSystem { override async resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise { if (opts?.signal !== undefined) this.signals.push(opts.signal) opts?.signal?.throwIfAborted() - const absolute = join(opts?.cwd ?? '/', path) + const absolute = resolve(opts?.cwd ?? '/', path) return { targetKey: FsTargetKey(absolute), displayPath: absolute } } @@ -277,8 +277,8 @@ describe('workspace context instruction discovery', () => { expect(files.map(file => file.displayPath)).toEqual([ '$DSH_HOME/AGENTS.md', 'AGENTS.md', - 'packages/CLAUDE.md', - 'packages/app/AGENTS.md', + join('packages', 'CLAUDE.md'), + join('packages', 'app', 'AGENTS.md'), ]) expect(files.map(file => file.absolutePath)).not.toContain(join(root, 'CLAUDE.md')) } finally { @@ -336,7 +336,7 @@ describe('workspace context instruction discovery', () => { } }) - it('skips a file that becomes unreadable after discovery without failing the request', async () => { + it.skipIf(process.platform === 'win32')('skips a file that becomes unreadable after discovery without failing the request', async () => { const root = await tempRepo() const home = await tempRepo() try { @@ -932,7 +932,7 @@ describe('workspace context request injection', () => { await composeBaselinePrefix(ctx, agent) expect(derivedText(agent)).toContain('omitted AGENTS.md') - expect(derivedText(agent)).toContain('Instructions from: pkg/AGENTS.md\n\npackage rule') + expect(derivedText(agent)).toContain(`Instructions from: ${join('pkg', 'AGENTS.md')}\n\npackage rule`) } finally { await rm(root, { recursive: true, force: true }) await rm(home, { recursive: true, force: true }) @@ -1398,7 +1398,7 @@ describe('workspace context request injection', () => { await composeBaselinePrefix(ctx, agent) expect(derivedText(agent)).toContain('Instructions from: AGENTS.md\n\nroot schema default rule') - expect(derivedText(agent)).toContain('Instructions from: child/AGENTS.md\n\nchild schema default rule') + expect(derivedText(agent)).toContain(`Instructions from: ${join('child', 'AGENTS.md')}\n\nchild schema default rule`) await ctx.fiber.dispose() } finally { await rm(root, { recursive: true, force: true }) @@ -1700,7 +1700,7 @@ describe('dynamic nested workspace context injection', () => { changes: [{ action: 'set', scope: 'pkg', - path: 'pkg/AGENTS.md', + path: join('pkg', 'AGENTS.md'), }], }) const meta = workspaceContextOf(result)?.meta @@ -1714,7 +1714,7 @@ describe('dynamic nested workspace context injection', () => { const text = blocksText(workspaceContextOf(result)?.content) expect(text).toBe([ '', - 'Additional instructions from: pkg/AGENTS.md', + `Additional instructions from: ${join('pkg', 'AGENTS.md')}`, '', 'These instructions apply to work under `pkg`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.', '', @@ -1752,7 +1752,7 @@ describe('dynamic nested workspace context injection', () => { }) const text = blocksText(workspaceContextOf(result)?.content) - expect(text).toContain('Additional instructions from: pkg/CLAUDE.local.md') + expect(text).toContain(`Additional instructions from: ${join('pkg', 'CLAUDE.local.md')}`) expect(text).toContain('local package rule') expect(text).not.toContain('native package rule') } finally { @@ -1922,11 +1922,11 @@ describe('dynamic nested workspace context injection', () => { expect(workspaceContextOf(changed)?.meta).toMatchObject({ kind: 'workspace-instructions', - changes: [{ action: 'replace', scope: 'pkg', path: 'pkg/AGENTS.md' }], + changes: [{ action: 'replace', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], }) expect(blocksText(workspaceContextOf(changed)?.content)).toBe([ '', - 'Updated instructions from: pkg/AGENTS.md', + `Updated instructions from: ${join('pkg', 'AGENTS.md')}`, '', 'This file changed after it was loaded. Use the following content instead of the previously loaded instructions from this file.', '', @@ -1966,11 +1966,11 @@ describe('dynamic nested workspace context injection', () => { expect(workspaceContextOf(changed)?.meta).toMatchObject({ changes: [{ - action: 'replace', scope: 'pkg', path: 'pkg/CLAUDE.md', previousPath: 'pkg/AGENTS.md', + action: 'replace', scope: 'pkg', path: join('pkg', 'CLAUDE.md'), previousPath: join('pkg', 'AGENTS.md'), }], }) - expect(blocksText(workspaceContextOf(changed)?.content)).toContain('Updated instructions from: pkg/CLAUDE.md') - expect(blocksText(workspaceContextOf(changed)?.content)).toContain('The instructions previously loaded from `pkg/AGENTS.md` no longer apply. Use the following content for `pkg` instead.') + expect(blocksText(workspaceContextOf(changed)?.content)).toContain(`Updated instructions from: ${join('pkg', 'CLAUDE.md')}`) + expect(blocksText(workspaceContextOf(changed)?.content)).toContain(`The instructions previously loaded from \`${join('pkg', 'AGENTS.md')}\` no longer apply. Use the following content for \`pkg\` instead.`) expect(blocksText(workspaceContextOf(changed)?.content)).toContain('fallback package rule') expect(unchanged.additionalContexts).toBeUndefined() } finally { @@ -2002,11 +2002,11 @@ describe('dynamic nested workspace context injection', () => { expect(workspaceContextOf(removed)?.meta).toEqual({ kind: 'workspace-instructions', version: 1, - changes: [{ action: 'remove', scope: 'pkg', path: 'pkg/AGENTS.md' }], + changes: [{ action: 'remove', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], }) expect(blocksText(workspaceContextOf(removed)?.content)).toBe([ '', - 'Instructions removed: pkg/AGENTS.md', + `Instructions removed: ${join('pkg', 'AGENTS.md')}`, '', 'The previously loaded instructions from this file no longer apply.', '', @@ -2044,9 +2044,9 @@ describe('dynamic nested workspace context injection', () => { }) expect(workspaceContextOf(restored)?.meta).toMatchObject({ - changes: [{ action: 'set', scope: 'pkg', path: 'pkg/AGENTS.md' }], + changes: [{ action: 'set', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], }) - expect(blocksText(workspaceContextOf(restored)?.content)).toContain('Additional instructions from: pkg/AGENTS.md') + expect(blocksText(workspaceContextOf(restored)?.content)).toContain(`Additional instructions from: ${join('pkg', 'AGENTS.md')}`) expect(blocksText(workspaceContextOf(restored)?.content)).toContain('restored package rule') } finally { await rm(root, { recursive: true, force: true }) @@ -2146,7 +2146,7 @@ describe('dynamic nested workspace context injection', () => { const update = resumed.session.events.findLast(event => event.type === 'context/message') expect(update?.type === 'context/message' && update.data.meta).toMatchObject({ - changes: [{ action: 'replace', scope: 'pkg', path: 'pkg/AGENTS.md' }], + changes: [{ action: 'replace', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], }) expect(update?.type === 'context/message' && blocksText(update.data.content)).toContain('new nested rule after resume') } finally { @@ -2267,8 +2267,8 @@ describe('dynamic nested workspace context injection', () => { }) const firstText = blocksText(workspaceContextOf(first)?.content) - expect(firstText).toContain('omitted pkg/AGENTS.md') - expect(firstText).not.toContain('## pkg/AGENTS.md') + expect(firstText).toContain(`omitted ${join('pkg', 'AGENTS.md')}`) + expect(firstText).not.toContain(`## ${join('pkg', 'AGENTS.md')}`) expect(firstText).toContain('subtree rule') expect(blocksText(workspaceContextOf(second)?.content)).toContain('parent rule') } finally { @@ -2462,7 +2462,7 @@ describe('dynamic nested workspace context injection', () => { expect(workspaceContextOf(result)?.envelope).toBe('raw') expect(workspaceContextOf(result)?.meta).toMatchObject({ kind: 'workspace-instructions', - changes: [{ action: 'set', scope: 'pkg', path: 'pkg/AGENTS.md' }], + changes: [{ action: 'set', scope: 'pkg', path: join('pkg', 'AGENTS.md') }], }) expect(blocksText(workspaceContextOf(result)?.content)).toContain('nested package rule') expect(blocksText(workspaceContextOf(result)?.content)).not.toContain('downstream context') diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts index 5363344f07..add5b932f9 100644 --- a/packages/fs/tool-fs-search/tests/tools.spec.ts +++ b/packages/fs/tool-fs-search/tests/tools.spec.ts @@ -12,6 +12,7 @@ import { describe, expect, it } from 'vitest' import { Context } from 'cordis' +import { join } from 'node:path' import { CallId } from '@deepseek-ai/dsh-llm' import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt' import ToolRegistry from '@deepseek-ai/dsh-tools' @@ -416,7 +417,7 @@ describe('glob results', () => { const { ctx, bash } = await setup() bash.handler = () => runResult('/sessions/s1/src/a.ts\n/elsewhere/b.ts\nrel/c.ts\n') const result = await call(ctx, 'glob', { pattern: '*' }, { agent: agent('/sessions/s1') }) - expect(text(result)).toBe('src/a.ts\n/elsewhere/b.ts\nrel/c.ts') + expect(text(result)).toBe(`${join('src', 'a.ts')}\n/elsewhere/b.ts\nrel/c.ts`) }) it('validates arguments (blank pattern, blank path)', async () => { @@ -498,7 +499,7 @@ describe('grep results', () => { const { ctx, bash } = await setup() bash.handler = () => runResult(`${matchLine('/sessions/s1/deep/a.ts', 2, 'hit')}\n`) const result = await call(ctx, 'grep', { pattern: 'hit', path: '/sessions/s1' }, { agent: agent('/sessions/s1') }) - expect(text(result)).toContain('deep/a.ts\nLine 2: hit') + expect(text(result)).toContain(`${join('deep', 'a.ts')}\nLine 2: hit`) }) it('previews a long matched line at grepMaxLineBytes preserving UTF-8', async () => { @@ -608,7 +609,7 @@ describe('presentation', () => { describe('helpers', () => { it('toWorkdirRelative maps inside-workdir absolutes and passes everything else through', () => { - expect(toWorkdirRelative('/w/a/b.ts', '/w')).toBe('a/b.ts') + expect(toWorkdirRelative('/w/a/b.ts', '/w')).toBe(join('a', 'b.ts')) expect(toWorkdirRelative('/w', '/w')).toBe('.') expect(toWorkdirRelative('/other/b.ts', '/w')).toBe('/other/b.ts') expect(toWorkdirRelative('/w-sibling/b.ts', '/w')).toBe('/w-sibling/b.ts') diff --git a/packages/spill/spill-local/tests/spill-local.spec.ts b/packages/spill/spill-local/tests/spill-local.spec.ts index b4abc6e3d6..46fa0b66b2 100644 --- a/packages/spill/spill-local/tests/spill-local.spec.ts +++ b/packages/spill/spill-local/tests/spill-local.spec.ts @@ -10,7 +10,7 @@ import { describe, expect, it, beforeEach, afterEach } from 'vitest' import { Context } from 'cordis' import { mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs' import { tmpdir } from 'node:os' -import { dirname, isAbsolute, join } from 'node:path' +import { basename, dirname, isAbsolute, join, normalize } from 'node:path' import { CallId } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' import type { SaveTextSpill } from '@deepseek-ai/dsh-spill' @@ -63,7 +63,8 @@ describe('sessionDir', () => { it('is a stable per-session hash under the root', () => { const dir = sessionDir('/spill', 'sess-1') expect(dir).toBe(sessionDir('/spill', 'sess-1')) - expect(dir).toMatch(/\/spill\/session-[0-9a-f]{12}$/) + expect(dirname(dir)).toBe(normalize('/spill')) + expect(basename(dir)).toMatch(/^session-[0-9a-f]{12}$/) expect(sessionDir('/spill', 'sess-2')).not.toBe(dir) }) }) @@ -74,7 +75,7 @@ describe('saveTextFile', () => { expect(readFileSync(saved.path, 'utf8')).toBe('héllo') expect(saved.bytes).toBe(Buffer.byteLength('héllo', 'utf8')) expect(dirname(saved.path)).toBe(sessionDir(root, 'sess-1')) - expect(saved.path).toMatch(/\/[0-9a-f]{12}-r\.txt$/) + expect(basename(saved.path)).toMatch(/^[0-9a-f]{12}-r\.txt$/) }) it('sanitizes a traversal-shaped suggested name into one segment', async () => { diff --git a/packages/util/paths/tests/paths.spec.ts b/packages/util/paths/tests/paths.spec.ts index 97e91a556e..4ba4fab155 100644 --- a/packages/util/paths/tests/paths.spec.ts +++ b/packages/util/paths/tests/paths.spec.ts @@ -1,5 +1,5 @@ import { homedir } from 'node:os' -import { join } from 'node:path' +import { join, resolve } from 'node:path' import { describe, expect, it } from 'vitest' import { DEFAULT_DSH_HOME_DISPLAY, @@ -28,7 +28,7 @@ describe('dsh path helpers', () => { const envHome = join(homedir(), 'env-dsh') expect(resolveDshHome(undefined, { DSH_HOME: '~/env-dsh' })).toBe(envHome) - expect(resolveDshHome('/tmp/explicit-dsh', { DSH_HOME: '~/env-dsh' })).toBe('/tmp/explicit-dsh') + expect(resolveDshHome('/tmp/explicit-dsh', { DSH_HOME: '~/env-dsh' })).toBe(resolve('/tmp/explicit-dsh')) expect(resolveDshHome(undefined, {})).toBe(defaultDshHome()) }) }) From 3a82b3edd7d52107578c1add212ade384bebfe55 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 15 Jul 2026 20:28:46 +0800 Subject: [PATCH 036/273] ci(windows): observe runtime coverage and snapshots docs: record cross-platform gate boundaries --- .github/AGENTS.md | 3 +++ .github/workflows/ci.yml | 24 +++++++++++++++++++----- scripts/AGENTS.md | 3 +++ 3 files changed, 25 insertions(+), 5 deletions(-) create mode 100644 .github/AGENTS.md create mode 100644 scripts/AGENTS.md diff --git a/.github/AGENTS.md b/.github/AGENTS.md new file mode 100644 index 0000000000..00e3ed8f87 --- /dev/null +++ b/.github/AGENTS.md @@ -0,0 +1,3 @@ +# AGENTS.md — CI gates + +Run Windows gates from native `pwsh`, invoke pnpm shell-free, and normalize repo-relative glob paths to `/` at ingestion. Keep platform fixes at each gate boundary; do not add a shared platform layer. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bac25b07cb..de9a03288b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -182,11 +182,9 @@ jobs: - name: Build (tsc -b + tsdown) run: pnpm run build - # Observational, non-blocking Windows static, lint, and artifact lanes. Coverage - # and snapshot stay Linux-only until their platform-specific runtime failures - # have dedicated support. Run the gates from native PowerShell: an MSYS parent - # would change the environment being measured. This job intentionally stays - # out of all-checks-passed.needs. + # Observational, non-blocking Windows mirror of the Linux gate lanes. Run the + # gates from native PowerShell: an MSYS parent would change the environment + # being measured. This job intentionally stays out of all-checks-passed.needs. windows-gates: continue-on-error: true runs-on: windows-2025 @@ -194,6 +192,7 @@ jobs: env: DSH_GATE_CONCURRENCY: ${{ matrix.gate_concurrency }} DSH_PUBLINT_CONCURRENCY: ${{ matrix.publint_concurrency }} + DSH_COVERAGE_MAX_WORKERS: ${{ matrix.coverage_max_workers }} DSH_ESLINT_CACHE: ${{ matrix.eslint_cache }} strategy: fail-fast: false @@ -203,16 +202,31 @@ jobs: command: pnpm run check:ci:static gate_concurrency: '4' publint_concurrency: '8' + coverage_max_workers: '' eslint_cache: '' - lane: lint command: pnpm run check:ci:lint gate_concurrency: '1' publint_concurrency: '8' + coverage_max_workers: '' eslint_cache: '1' + - lane: coverage + command: pnpm run check:ci:coverage + gate_concurrency: '1' + publint_concurrency: '8' + coverage_max_workers: '4' + eslint_cache: '' + - lane: snapshot + command: pnpm run check:ci:snapshot + gate_concurrency: '1' + publint_concurrency: '8' + coverage_max_workers: '' + eslint_cache: '' - lane: artifacts command: pnpm run check:ci:artifacts gate_concurrency: '3' publint_concurrency: '8' + coverage_max_workers: '' eslint_cache: '' steps: - uses: actions/checkout@v6 diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md new file mode 100644 index 0000000000..2d1ebafc27 --- /dev/null +++ b/scripts/AGENTS.md @@ -0,0 +1,3 @@ +# AGENTS.md — Repository scripts + +Gate-related scripts follow the [CI gate rules](../.github/AGENTS.md). From 1d6acc331538aa7d5144257fcfd6690acd69eb1f Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 18 Jul 2026 03:23:52 +0800 Subject: [PATCH 037/273] test(loader-smoke): use native home paths --- packages/support/loader-smoke/tests/loader-smoke.spec.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/support/loader-smoke/tests/loader-smoke.spec.ts b/packages/support/loader-smoke/tests/loader-smoke.spec.ts index b99d810188..755197b134 100644 --- a/packages/support/loader-smoke/tests/loader-smoke.spec.ts +++ b/packages/support/loader-smoke/tests/loader-smoke.spec.ts @@ -1,4 +1,5 @@ import { existsSync } from 'node:fs' +import { join } from 'node:path' import { fileURLToPath } from 'node:url' import { describe, expect, it } from 'vitest' import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke' @@ -33,8 +34,8 @@ describe('runLoaderSmoke', () => { marker: 'present', input: 'one\ntwo\n', }) - expect(canonicalTempPath(output.dshHome)).toBe(`${canonicalTempPath(output.cwd)}/.dsh`) - expect(canonicalTempPath(output.agentsHome)).toBe(`${canonicalTempPath(output.cwd)}/.agents`) + expect(canonicalTempPath(output.dshHome)).toBe(canonicalTempPath(join(output.cwd, '.dsh'))) + expect(canonicalTempPath(output.agentsHome)).toBe(canonicalTempPath(join(output.cwd, '.agents'))) expect(result.stderr).toContain('fixture stderr') expect(existsSync(output.cwd)).toBe(false) }, LOADER_SMOKE_TEST_TIMEOUT_MS) From 588f4d948d8ac1c023366dbdc337546cb3ca65d3 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 18 Jul 2026 12:10:18 +0800 Subject: [PATCH 038/273] test(windows): mark platform-only coverage branches --- packages/context/workspace-context/src/files.ts | 1 + packages/context/workspace-context/src/state.ts | 1 + packages/fs/fs-local/src/fsio.ts | 1 + packages/sandbox/sandbox/src/index.ts | 1 + .../session-persistence-jsonl/src/index.ts | 5 +++++ packages/skill/skill-local/src/index.ts | 1 + 6 files changed, 10 insertions(+) diff --git a/packages/context/workspace-context/src/files.ts b/packages/context/workspace-context/src/files.ts index feb6304b4c..770024c569 100644 --- a/packages/context/workspace-context/src/files.ts +++ b/packages/context/workspace-context/src/files.ts @@ -459,6 +459,7 @@ export async function readScopeInstruction( signal?: AbortSignal, ): Promise { const content = await readBounded(file, maxSourceBytes, fileSystem, signal) + /* v8 ignore next -- Windows cannot reproduce a post-probe unreadable file with POSIX mode bits. */ if (content === undefined) return undefined return { absolutePath: file.absolutePath, diff --git a/packages/context/workspace-context/src/state.ts b/packages/context/workspace-context/src/state.ts index 98b8fcc066..ab18f442f4 100644 --- a/packages/context/workspace-context/src/state.ts +++ b/packages/context/workspace-context/src/state.ts @@ -437,6 +437,7 @@ export async function reconcileInstructionContext( ) continue const file = await readScopeInstruction(probedFile, resolved.maxSourceBytes, fileSystem, options.signal) + /* v8 ignore next -- Windows cannot make the probed file unreadable through POSIX mode bits. */ if (file === undefined) continue const currentDigest = instructionContentSha1(file.content) const nextVersion: InstructionVersionState = { diff --git a/packages/fs/fs-local/src/fsio.ts b/packages/fs/fs-local/src/fsio.ts index 4603611ce4..9592ba0349 100644 --- a/packages/fs/fs-local/src/fsio.ts +++ b/packages/fs/fs-local/src/fsio.ts @@ -175,6 +175,7 @@ export async function resolveLocalTarget(cwd: string, path: string): Promise { await mkdir(this.root, { recursive: true, mode: 0o700 }) await this.syncDirPosix(dirname(this.root)) @@ -213,6 +214,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi /* v8 ignore next -- redundant temp link; publish already durable, rm failure is an unreachable IO edge */ } } + /* v8 ignore stop */ /* v8 ignore start -- native Windows coverage exercises this integration path */ private async materializeWin32(dir: string, finalPath: string, id: SessionId, content: string): Promise { @@ -254,6 +256,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi } /** fsync a POSIX directory so a just-created/renamed entry is crash-durable. */ + /* v8 ignore start -- Windows uses write-through namespace operations; POSIX coverage exercises directory fsync. */ private async syncDirPosix(dir: string): Promise { const handle = await open(dir, 'r') try { @@ -262,6 +265,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi await handle.close() } } + /* v8 ignore stop */ /** * Append and fsync event lines. On a partial write or sync failure, restore the @@ -395,6 +399,7 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi await this.assertLogParentAllowsAbsence(path) return false } + /* v8 ignore next -- Windows repairs ENOTDIR from ENOENT above; POSIX covers direct ENOTDIR. */ throw error } } diff --git a/packages/skill/skill-local/src/index.ts b/packages/skill/skill-local/src/index.ts index ee109fbb16..29f5c622b9 100644 --- a/packages/skill/skill-local/src/index.ts +++ b/packages/skill/skill-local/src/index.ts @@ -317,6 +317,7 @@ async function nodeEntryKind(fullPath: string, entry: { isDirectory(): boolean; const info = await stat(fullPath) if (info.isDirectory()) return 'directory' if (info.isFile()) return 'file' + /* v8 ignore next -- The special-file symlink fixture relies on POSIX /dev/null. */ return undefined } catch (error) { ctx.logger.warn(`skill entry ${fullPath} ignored: failed to follow symbolic link: ${errorMessage(error)}`) From b426c2f19c06a6132e2d21992af8f2e2f5679506 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 18 Jul 2026 12:13:53 +0800 Subject: [PATCH 039/273] docs(api): refresh sandbox source link --- website/zh-CN/api/harness/sandbox.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/zh-CN/api/harness/sandbox.md b/website/zh-CN/api/harness/sandbox.md index bc5b1d38a5..51980d36d7 100644 --- a/website/zh-CN/api/harness/sandbox.md +++ b/website/zh-CN/api/harness/sandbox.md @@ -21,4 +21,4 @@ Wrap `argv` so it executes confined under `policy` on this host; the caller spaw **Returns** the argv to spawn instead, plus the enforcement completeness the selected backend achieves for it. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts#L127) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts#L128) From f62cc439e9bbc7e26e674e3a82b53e4dbb05469c Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 18 Jul 2026 13:03:44 +0800 Subject: [PATCH 040/273] docs(windows): clarify portability rules --- .github/AGENTS.md | 4 ++-- packages/support/acp-snapshot/README.md | 2 +- scripts/AGENTS.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/AGENTS.md b/.github/AGENTS.md index 00e3ed8f87..5f03c8617d 100644 --- a/.github/AGENTS.md +++ b/.github/AGENTS.md @@ -1,3 +1,3 @@ -# AGENTS.md — CI gates +# AGENTS.md — GitHub Actions -Run Windows gates from native `pwsh`, invoke pnpm shell-free, and normalize repo-relative glob paths to `/` at ingestion. Keep platform fixes at each gate boundary; do not add a shared platform layer. +Run Windows jobs under native `pwsh`. diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md index 9969eadb46..57f7245d7c 100644 --- a/packages/support/acp-snapshot/README.md +++ b/packages/support/acp-snapshot/README.md @@ -37,7 +37,7 @@ defineAcpSnapshotSuite({ A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode and filesystem scenarios are templates. Each pinning directory stores the normalized full prompt sequence in generated `system-prompt.golden.md` and the corresponding full tool-schema sequence in generated `tool-schemas.golden.json`; `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. A pin with legitimate mid-run header changes declares `expectedHeaderChanges`, which fixes the length of both sidecar sequences. -Every scenario compares `stdout.golden.jsonl` with cwd-rooted separators canonicalized to `/`. A scenario may set `pinsNativeWindowsStdout` to add a Windows-only comparison against the complete `stdout.golden.windows.jsonl`; the shared golden still runs first on Windows, and the fixture guard requires the sidecar exactly when declared. +Every scenario compares `stdout.golden.jsonl` with cwd-rooted separators canonicalized to `/`. On Windows, `pinsNativeWindowsStdout` additionally compares the complete `stdout.golden.windows.jsonl` after the shared golden and requires that sidecar exactly when enabled. Examples use a `cordis.snapshot.yml` overlay with [`dsh-llm-replay`](../llm-replay/README.md). Recording calls the live model and updates model fixtures; keyless refresh replays those fixtures and updates derived stdout, session-log, prompt, and tool-schema snapshots. See the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md). diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md index 2d1ebafc27..68ea79ea7b 100644 --- a/scripts/AGENTS.md +++ b/scripts/AGENTS.md @@ -1,3 +1,3 @@ # AGENTS.md — Repository scripts -Gate-related scripts follow the [CI gate rules](../.github/AGENTS.md). +Gate scripts invoke pnpm shell-free, normalize repository-relative glob paths to `/` at ingestion, and keep platform adaptation at the owning gate boundary instead of a shared platform layer. From b965285f282a5c7aadde6e4de76a42d0da756b28 Mon Sep 17 00:00:00 2001 From: NI0317 Date: Sat, 18 Jul 2026 14:04:43 +0800 Subject: [PATCH 041/273] feat(research): add trace-workbench local session-replay UI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A localhost viewer over persisted session JSONL for agent developers and researchers. Three first-class views — Chat (markdown-rendered surface conversation with a second-level inspector), Trajectory (turn/step tree with scroll-spy over a step-grouped event table, inline annotations), and Waterfall (timing summary + aligned time track that deep-links into Trajectory). Subagent sessions group under their parentSession with spawn links and breadcrumbs; failed tool calls are marked in every view; ?session=&view=&sel= makes any selection a shareable deep link. Motion follows an audited restraint baseline (plans/ documents the audit): one strong ease-out token, enter-only animations, press feedback on pushbuttons, prefers-reduced-motion support. AGENTS.md gains the research/ layout entry; the AGENTS.md word ceiling rises 1370 -> 1375 to fit it (one line, relocation not applicable for a top-level layout entry). --- AGENTS.md | 1 + research/trace-workbench/.gitignore | 1 + research/trace-workbench/README.md | 39 + research/trace-workbench/app.js | 1663 +++++++++++ research/trace-workbench/index.html | 173 ++ .../plans/001-motion-foundation.md | 60 + .../plans/002-inspector-enter.md | 61 + .../plans/003-details-enter.md | 61 + .../plans/004-press-feedback.md | 56 + .../plans/005-reduced-motion.md | 70 + research/trace-workbench/plans/README.md | 15 + research/trace-workbench/server.js | 456 +++ research/trace-workbench/styles.css | 2646 +++++++++++++++++ scripts/doc-budgets.manifest.json | 2 +- 14 files changed, 5303 insertions(+), 1 deletion(-) create mode 100644 research/trace-workbench/.gitignore create mode 100644 research/trace-workbench/README.md create mode 100644 research/trace-workbench/app.js create mode 100644 research/trace-workbench/index.html create mode 100644 research/trace-workbench/plans/001-motion-foundation.md create mode 100644 research/trace-workbench/plans/002-inspector-enter.md create mode 100644 research/trace-workbench/plans/003-details-enter.md create mode 100644 research/trace-workbench/plans/004-press-feedback.md create mode 100644 research/trace-workbench/plans/005-reduced-motion.md create mode 100644 research/trace-workbench/plans/README.md create mode 100644 research/trace-workbench/server.js create mode 100644 research/trace-workbench/styles.css diff --git a/AGENTS.md b/AGENTS.md index 23d7c0263b..b7eee0a2bf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,6 +33,7 @@ packages/ Harness packages at packages///, all named @deepseek-ai python/ Python SDK and bundled runtime (see python/README.md) examples/ Runnable cordis.yml leaves over packages/examples bundles (see examples/AGENTS.md) docs/ architecture, generated catalogs, RFCs, postmortems, cookbook (see docs/AGENTS.md) +research/ research prototypes (see research/trace-workbench/README.md) scripts/ repo gates and generators ``` diff --git a/research/trace-workbench/.gitignore b/research/trace-workbench/.gitignore new file mode 100644 index 0000000000..a4bb5320d9 --- /dev/null +++ b/research/trace-workbench/.gitignore @@ -0,0 +1 @@ +.feedback/ diff --git a/research/trace-workbench/README.md b/research/trace-workbench/README.md new file mode 100644 index 0000000000..71dea925b9 --- /dev/null +++ b/research/trace-workbench/README.md @@ -0,0 +1,39 @@ +# DeepSeek Harness Trace Workbench + +Localhost UI backed by real DeepSeek Harness persisted session JSONL files. + +```sh +node server.js +``` + +Then open . + +Defaults: + +- Reads sessions from `./.sessions` under the current working directory (set `HARNESS_SESSIONS_ROOT` to point elsewhere) +- Serves static UI and API from the same localhost origin +- Annotations are appended to `.feedback/*.jsonl` next to the server (local data, not committed) + +Useful overrides: + +```sh +HARNESS_SESSIONS_ROOT=/path/to/.sessions PORT=5174 node server.js +``` + +API: + +- `GET /api/health` +- `GET /api/sessions` +- `GET /api/sessions/:id` + +Current UI capabilities: + +- Reads real session JSONL, not mock data; replay-only (the composer is disabled until live runtime wiring lands). +- Three first-class views; the inspector is second-level and belongs to Chat only: + - **Chat** — markdown-rendered surface conversation; clicking a message opens the inspector as an inner column (paired Input/Output, metadata, feedback, Plain/JSON/JSONL/YAML formatting) that squeezes the conversation, never overlays it. + - **Trajectory** — self-contained: a structure tree (turn → step, with durations, tool summaries and error dots) navigates a step-grouped event table; lifecycle events are absorbed into the tree and sticky group headers instead of appearing as rows. Expanded rows carry Copy JSON, inline annotations (标注) and the raw event. + - **Waterfall** — hotspot finder: a summary strip (total / LLM time / tool time / errors / slowest step / tokens) plus an aligned time track; clicking any bar, label or stat jumps to the matching Trajectory row. +- Session list groups subagent sessions under their `parentSession`; a spawning tool call links to the sessions it spawned, and a child session shows a breadcrumb back to its parent. +- Failed tool calls are marked in every view (red rail + `← error` chip in Trajectory, red bar in Waterfall, `Tool failed` in Chat). +- Panes resize by dragging the dividers (clamped; widths persist), and all panes squeeze each other in one layer. +- URL carries `?session=&view=&sel=` so any selection is a shareable deep link. diff --git a/research/trace-workbench/app.js b/research/trace-workbench/app.js new file mode 100644 index 0000000000..070d1c601c --- /dev/null +++ b/research/trace-workbench/app.js @@ -0,0 +1,1663 @@ +const state = { + sessions: [], + session: null, + selected: null, // chat-side selection (drives the inspector) + activeDetailTab: 'input', + inspectorOpen: false, // chat-only second-level panel + expandedTrajectorySeqs: new Set(), + annotateOpenIds: new Set(), + trajGroups: [], // step-grouped trajectory rows (lifecycle events become group metadata) + trajectoryRows: [], // flat row list across all groups + turnMeta: new Map(), // turn -> {trigger, reason, startTime, endTime} + sessionQuery: '', + // Per-session indexes, rebuilt on every loadSession: + seqMap: new Map(), // seq -> event (tree nodes reference events by seq) + callPairs: new Map(), // callId -> { call, result } + firstChunkByStep: new Map(), // "turn:step" -> first assistant/chunk time +} + +const $ = (selector) => document.querySelector(selector) +const $$ = (selector) => [...document.querySelectorAll(selector)] + +async function api(path) { + const response = await fetch(path) + if (!response.ok) throw new Error(`${response.status} ${response.statusText}`) + return response.json() +} + +async function postJson(path, body) { + const response = await fetch(path, { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify(body), + }) + return response.json() +} + +function escapeHtml(value) { + return String(value) + .replaceAll('&', '&') + .replaceAll('<', '<') + .replaceAll('>', '>') + .replaceAll('"', '"') +} + +function ms(seconds) { + if (!Number.isFinite(seconds)) return '0ms' + return seconds >= 1 ? `${seconds.toFixed(2)}s` : `${Math.round(seconds * 1000)}ms` +} + +function fmtOffset(seconds) { + return `+${ms(Math.max(0, seconds))}` +} + +function dateTime(msValue) { + if (!Number.isFinite(msValue)) return 'unknown' + return new Date(msValue).toLocaleString() +} + +function truncate(value, limit = 180) { + const text = String(value ?? '').replace(/\s+/g, ' ').trim() + return text.length > limit ? `${text.slice(0, limit - 1)}...` : text +} + +function nodeGlyph(kind) { + return { + session: 'S', + turn: 'T', + step: 'ST', + tool: 'TL', + llm: 'AI', + event: 'EV', + }[kind] ?? 'N' +} + +function flatten(node, depth = 0, out = []) { + if (!node) return out + out.push({ ...node, depth }) + for (const child of node.children ?? []) flatten(child, depth + 1, out) + return out +} + +function currentNodes() { + return flatten(state.session?.tree) +} + +function findNode(id) { + return currentNodes().find(node => node.id === id) ?? state.session?.tree +} + +// Tree nodes carry eventSeqs (not embedded events); resolve through the seq index. +function eventsOf(node) { + if (node?.rawEvents) return node.rawEvents + return (node?.eventSeqs ?? []).map(seq => state.seqMap.get(seq)).filter(Boolean) +} + +function resolvePrompt(node) { + const seq = node?.detail?.promptSeq + if (seq !== undefined) return state.seqMap.get(seq)?.data?.header + return node?.detail?.prompt +} + +function contentToText(content) { + if (!Array.isArray(content)) return '' + return content.map((block) => { + if (block.type === 'text' || block.type === 'reasoning') return block.text ?? '' + if (block.type === 'tool-call') return `[tool-call ${block.name}] ${block.arguments ?? ''}` + if (block.type === 'tool-result') return `[tool-result] ${JSON.stringify(block.content ?? block)}` + return JSON.stringify(block) + }).filter(Boolean).join('\n') +} + +function contentBlocks(content) { + return Array.isArray(content) ? content : [] +} + +function renderValue(value, format) { + if (value === undefined || value === null || value === '') return '' + if (format === 'json') return JSON.stringify(value, null, 2) + if (format === 'jsonl') { + const rows = Array.isArray(value) ? value : [value] + return rows.map(row => typeof row === 'string' ? row : JSON.stringify(row)).join('\n') + } + if (format === 'yaml') return toYaml(value) + if (typeof value === 'string') return value + if (Array.isArray(value) && value.every(item => item?.type)) return contentToText(value) + return JSON.stringify(value, null, 2) +} + +function toYaml(value, indent = 0) { + const pad = ' '.repeat(indent) + if (value === null) return 'null' + if (typeof value !== 'object') return JSON.stringify(value) + if (Array.isArray(value)) { + return value.map(item => { + if (item && typeof item === 'object') return `${pad}-\n${toYaml(item, indent + 2)}` + return `${pad}- ${toYaml(item)}` + }).join('\n') + } + return Object.entries(value).map(([key, item]) => { + if (item && typeof item === 'object') return `${pad}${key}:\n${toYaml(item, indent + 2)}` + return `${pad}${key}: ${toYaml(item)}` + }).join('\n') +} + +// Minimal safe markdown for the Chat surface: input is escaped FIRST, then a +// line-based pass adds structure. Headings, lists, hr, fenced code, inline +// bold/code/links (http(s) only). Everything unrecognized stays a paragraph. +function mdInline(escaped) { + return escaped + .replace(/`([^`]+)`/g, '$1') + .replace(/\*\*([^*]+)\*\*/g, '$1') + .replace(/\*(\S(?:[^*\n]*\S)?)\*/g, '$1') + .replace(/\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g, '$1') +} + +function mdSplitRow(line) { + return line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map(cell => cell.trim()) +} + +const MD_TABLE_ROW = /^\s*\|.*\|\s*$/ +// A |---|:---:| separator row (text is already HTML-escaped, pipes unaffected). +const MD_TABLE_SEP = /^\s*\|?[\s:|-]+\|[\s:|-]*$/ + +function renderMarkdown(text) { + const lines = escapeHtml(text).split('\n') + const out = [] + let inCode = false + let listType = null + const closeList = () => { + if (listType) { + out.push(``) + listType = null + } + } + for (let i = 0; i < lines.length; i++) { + const line = lines[i] + if (line.trim().startsWith('```')) { + closeList() + out.push(inCode ? '' : '
')
+      inCode = !inCode
+      continue
+    }
+    if (inCode) {
+      out.push(line)
+      continue
+    }
+    // Table: a |...| row whose next line is the |---|---| separator.
+    if (MD_TABLE_ROW.test(line) && i + 1 < lines.length && MD_TABLE_SEP.test(lines[i + 1]) && lines[i + 1].includes('-')) {
+      closeList()
+      const header = mdSplitRow(line)
+      const aligns = mdSplitRow(lines[i + 1]).map(cell => {
+        if (cell.startsWith(':') && cell.endsWith(':')) return 'center'
+        if (cell.endsWith(':')) return 'right'
+        return ''
+      })
+      i += 1
+      const rows = []
+      while (i + 1 < lines.length && MD_TABLE_ROW.test(lines[i + 1])) {
+        i += 1
+        rows.push(mdSplitRow(lines[i]))
+      }
+      const cellHtml = (tag, cells) => cells.map((cell, k) =>
+        `<${tag}${aligns[k] ? ` style="text-align:${aligns[k]}"` : ''}>${mdInline(cell)}`).join('')
+      out.push('
') + out.push(`${cellHtml('th', header)}`) + out.push(`${rows.map(row => `${cellHtml('td', row)}`).join('')}`) + out.push('
') + continue + } + // Blockquote ('>' is already escaped to >). + if (/^\s*>\s?/.test(line)) { + closeList() + const quote = [] + while (i < lines.length && /^\s*>\s?/.test(lines[i])) { + quote.push(lines[i].replace(/^\s*>\s?/, '')) + i += 1 + } + i -= 1 + out.push(`
${quote.map(q => mdInline(q)).join('
')}
`) + continue + } + const heading = line.match(/^(#{1,4})\s+(.*)$/) + if (heading) { + closeList() + const level = Math.min(heading[1].length + 2, 5) + out.push(`${mdInline(heading[2])}`) + continue + } + if (/^\s*(---+|\*\*\*+)\s*$/.test(line)) { + closeList() + out.push('
') + continue + } + if (/^\s*[-*]\s+/.test(line)) { + if (listType !== 'ul') { + closeList() + out.push('