From ff5f94d3fb298968a6ba7acb77e376f73e833287 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Mon, 24 Aug 2026 22:40:00 +0800 Subject: [PATCH 001/100] refactor(client): import conversation node types from their declaring package Adding another client-face project to the client aggregate reshuffles the typert analyzer's batches, which exposed latent provenance violations in ui-chat and ui-approval: types consumed through ui-conversation's re-export path instead of their declaring package, and one slot-contract literal whose type the analyzer could not name. Import the types from @deepseek-ai/dsh-client-ui-conversation/client directly and give the approval interaction kind a named alias so the explicit annotation survives both the analyzer and lint. --- packages/client/ui-approval/src/client/contract/slots.ts | 5 ++++- .../client/ui-chat/src/client/chat/AssistantMarkdown.tsx | 2 +- .../client/ui-chat/src/client/chat/CompactionItem.tsx | 2 +- packages/client/ui-chat/src/client/chat/ContextBody.tsx | 5 +++-- .../ui-chat/src/client/chat/ContextInjectionRow.tsx | 2 +- packages/client/ui-chat/src/client/chat/MessageItem.tsx | 2 +- .../client/ui-chat/src/client/chat/turn-assistant.ts | 2 +- packages/client/ui-chat/src/client/contract/slots.ts | 4 ++-- .../ui-chat/src/client/conversation-nodes/assistant.ts | 3 +-- .../client/conversation-nodes/chat-snapshot-builder.ts | 9 +++------ .../ui-chat/src/client/conversation-nodes/command.ts | 3 +-- .../ui-chat/src/client/conversation-nodes/compaction.ts | 3 +-- .../ui-chat/src/client/conversation-nodes/fallback.ts | 5 +++-- .../ui-chat/src/client/conversation-nodes/message.ts | 5 +++-- .../ui-chat/src/client/conversation-nodes/partial.ts | 2 +- .../ui-chat/src/client/conversation-nodes/retry.ts | 3 +-- .../client/ui-chat/src/client/conversation-nodes/tool.ts | 3 +-- .../ui-chat/src/client/conversation-nodes/turn-error.ts | 3 +-- .../src/client/conversation-nodes/turn-max-tokens.ts | 3 +-- .../client/ui-chat/src/client/details/DetailsPanel.tsx | 3 ++- .../ui-chat/src/client/details/tool-node-reader.ts | 3 ++- .../ui-chat/src/client/model/conversation-context.ts | 5 +++-- .../client/ui-chat/src/client/model/tool-call-tree.ts | 4 +--- 23 files changed, 39 insertions(+), 42 deletions(-) diff --git a/packages/client/ui-approval/src/client/contract/slots.ts b/packages/client/ui-approval/src/client/contract/slots.ts index f71a33008b..2980754542 100644 --- a/packages/client/ui-approval/src/client/contract/slots.ts +++ b/packages/client/ui-approval/src/client/contract/slots.ts @@ -65,10 +65,13 @@ export type ApprovalDecision = 'allowed-once' | 'rejected' let nextApprovalKey = 0 +/** Domain discriminator literal carried by {@link PendingApproval.kind}. */ +export type ApprovalInteractionKind = 'approval' + /** One answerable Client presentation of a pending Host waterfall. */ export class PendingApproval { /** Domain discriminator used by Session pending-interaction consumers. */ - readonly kind = 'approval' as const + readonly kind: ApprovalInteractionKind = 'approval' /** Opaque render identity and one-shot remount axis. */ readonly key: string /** Tool requesting the decision. */ diff --git a/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx index 8838725f75..a42758519a 100644 --- a/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx +++ b/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx @@ -1,9 +1,9 @@ +import type { AssistantBlock } from '@deepseek-ai/dsh-client-ui-conversation/client' import { Fragment, memo, useMemo } from 'react' import type { ReactNode } from 'react' import { JsonBlock, MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives' import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives' import type { ChatNodeOwnerProps, ChatViewSlotProps } from '../contract/slots.ts' -import type { AssistantBlock } from '../contract/snapshot.ts' import { markdownLabels } from '../markdown-labels.ts' import { ReasoningRow } from './ReasoningRow.tsx' import css from './AssistantMarkdown.module.css' diff --git a/packages/client/ui-chat/src/client/chat/CompactionItem.tsx b/packages/client/ui-chat/src/client/chat/CompactionItem.tsx index b6108daf1a..da1346a582 100644 --- a/packages/client/ui-chat/src/client/chat/CompactionItem.tsx +++ b/packages/client/ui-chat/src/client/chat/CompactionItem.tsx @@ -1,3 +1,4 @@ +import type { CompactionSummaryNode } from '@deepseek-ai/dsh-client-ui-conversation/client' // A compaction marker does not replace shadowed transcript rows. It is // expandable only when the current window includes its cited summary. @@ -10,7 +11,6 @@ import { } from '@deepseek-ai/dsh-client-ui-primitives' import type { ChatViewSlotProps } from '../contract/slots.ts' import { markdownLabels } from '../markdown-labels.ts' -import type { CompactionSummaryNode } from '../contract/snapshot.ts' import css from './MessageItem.module.css' interface CompactionItemProps { diff --git a/packages/client/ui-chat/src/client/chat/ContextBody.tsx b/packages/client/ui-chat/src/client/chat/ContextBody.tsx index 6501ffda8f..3278f3d876 100644 --- a/packages/client/ui-chat/src/client/chat/ContextBody.tsx +++ b/packages/client/ui-chat/src/client/chat/ContextBody.tsx @@ -7,8 +7,9 @@ import type { ReactNode } from 'react' import { JsonBlock } from '@deepseek-ai/dsh-client-ui-primitives' import type { ChatViewSlotProps } from '../contract/slots.ts' -import type { ContextMessageNode } from '../contract/snapshot.ts' -import type { KnownContextForm } from '@deepseek-ai/dsh-client-ui-conversation/client' +import type { + ContextMessageNode, KnownContextForm, +} from '@deepseek-ai/dsh-client-ui-conversation/client' import css from './ContextBody.module.css' /** Model-facing text stays bounded at the disclosure, not at the producer. */ diff --git a/packages/client/ui-chat/src/client/chat/ContextInjectionRow.tsx b/packages/client/ui-chat/src/client/chat/ContextInjectionRow.tsx index 8be42c0f42..0930a25d56 100644 --- a/packages/client/ui-chat/src/client/chat/ContextInjectionRow.tsx +++ b/packages/client/ui-chat/src/client/chat/ContextInjectionRow.tsx @@ -1,7 +1,7 @@ +import type { ContextMessageNode } from '@deepseek-ai/dsh-client-ui-conversation/client' import { useState } from 'react' import type { ChatViewSlotProps } from '../contract/slots.ts' import { DisclosureRow, IconBrowseOutline16, ReferenceIcon } from '@deepseek-ai/dsh-client-ui-primitives' -import type { ContextMessageNode } from '../contract/snapshot.ts' import { contextBody } from './ContextBody.tsx' import css from './ContextInjectionRow.module.css' diff --git a/packages/client/ui-chat/src/client/chat/MessageItem.tsx b/packages/client/ui-chat/src/client/chat/MessageItem.tsx index c7368dc24d..fd0681bcbe 100644 --- a/packages/client/ui-chat/src/client/chat/MessageItem.tsx +++ b/packages/client/ui-chat/src/client/chat/MessageItem.tsx @@ -1,8 +1,8 @@ +import type { ModelRetryNode, TurnErrorNode, UserMessageNode } from '@deepseek-ai/dsh-client-ui-conversation/client' import { memo, useEffect, useMemo, useState } from 'react' import type { ReactNode } from 'react' import { JsonBlock, MessageText, ReferenceIcon, StateDot } from '@deepseek-ai/dsh-client-ui-primitives' import type { ChatNodeOwnerProps, ChatNodeViewProps, ChatViewSlotProps } from '../contract/slots.ts' -import type { ModelRetryNode, TurnErrorNode, UserMessageNode } from '../contract/snapshot.ts' import { CompactionItem } from './CompactionItem.tsx' import { ContextInjectionRow } from './ContextInjectionRow.tsx' import { MessageIconActions } from './MessageIconActions.tsx' diff --git a/packages/client/ui-chat/src/client/chat/turn-assistant.ts b/packages/client/ui-chat/src/client/chat/turn-assistant.ts index 90e075d79a..36c2ad2ec5 100644 --- a/packages/client/ui-chat/src/client/chat/turn-assistant.ts +++ b/packages/client/ui-chat/src/client/chat/turn-assistant.ts @@ -1,4 +1,4 @@ -import type { AssistantBlock } from '../contract/snapshot.ts' +import type { AssistantBlock } from '@deepseek-ai/dsh-client-ui-conversation/client' /** * Collect visible prose from one Assistant lifecycle. diff --git a/packages/client/ui-chat/src/client/contract/slots.ts b/packages/client/ui-chat/src/client/contract/slots.ts index 5009781fd1..c035bd97af 100644 --- a/packages/client/ui-chat/src/client/contract/slots.ts +++ b/packages/client/ui-chat/src/client/contract/slots.ts @@ -3,7 +3,7 @@ import type { ReactNode } from 'react' import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' import type { MessageId } from '@deepseek-ai/dsh-llm/brand' import type { - ConversationTurnDataMap, TurnLocation, + CommandNode, CompactionSummaryNode, ConversationTurnDataMap, ToolCallBlock, TurnLocation, } from '@deepseek-ai/dsh-client-ui-conversation/client' import type { InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, SlotHookFactory, @@ -14,7 +14,7 @@ import type {} from '@deepseek-ai/dsh-client-ui-layout/client' import type { createChatStore } from '../stores.ts' import type { CallId, SelectionTarget } from './store.ts' import type { ChatNode, ChatNodeKind } from './chat-nodes.ts' -import type { ChatSnapshot, CommandNode, CompactionSummaryNode, ToolCallBlock } from './snapshot.ts' +import type { ChatSnapshot } from './snapshot.ts' /** Selector hook over the current Conversation binding's Chat target. */ export type UseChat = SnapshotSelectorHook diff --git a/packages/client/ui-chat/src/client/conversation-nodes/assistant.ts b/packages/client/ui-chat/src/client/conversation-nodes/assistant.ts index f0f2b9be88..a2b5db79e2 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/assistant.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/assistant.ts @@ -1,11 +1,10 @@ import type { Context } from '@deepseek-ai/cordis' import type { - ConversationLocation, ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, + AssistantBlock, AssistantMessageNode, ConversationLocation, ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, } from '@deepseek-ai/dsh-client-ui-conversation/client' import type {} from '@deepseek-ai/dsh-llm-retry/types' import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-session/surface' import type { AssistantChatData } from '../contract/chat-nodes.ts' -import type { AssistantBlock, AssistantMessageNode } from '../contract/snapshot.ts' import { CHAT_SYNTHETIC_SEQ_OFFSETS, chatNode } from './common.ts' import { emptyAssistantBlock, isTokenDelta, toAssistantBlock, toAssistantBlocks, diff --git a/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts b/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts index f70e657014..2b306e2d99 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts @@ -1,14 +1,11 @@ import type { Context } from '@deepseek-ai/cordis' import type { - ConversationLocation, ConversationTimelineSnapshot, ConversationViewBuilder, - ConversationViewDefinition, + ConversationLocation, ConversationNode, ConversationTimelineSnapshot, ConversationViewBuilder, + ConversationViewDefinition, PartialAssistant, RunningToolCall, } from '@deepseek-ai/dsh-client-ui-conversation/client' import type { ChatConversationViewNode, ChatNode } from '../contract/chat-nodes.ts' import { isRunningTool } from '../contract/chat-nodes.ts' -import type { - ChatLocationNodeIndex, ChatNodeStore, ChatSnapshot, ConversationNode, - LegacyConversationSlice, PartialAssistant, RunningToolCall, -} from '../contract/snapshot.ts' +import type { ChatLocationNodeIndex, ChatNodeStore, ChatSnapshot, LegacyConversationSlice } from '../contract/snapshot.ts' import { sessionRecallLabels } from './event-projection.ts' const EMPTY_KEYS: readonly string[] = [] diff --git a/packages/client/ui-chat/src/client/conversation-nodes/command.ts b/packages/client/ui-chat/src/client/conversation-nodes/command.ts index b4723d78fa..e21f50c5f5 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/command.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/command.ts @@ -1,13 +1,12 @@ import type { Context } from '@deepseek-ai/cordis' import type { - ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, + CommandNode, CompactionSummaryNode, ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, } from '@deepseek-ai/dsh-client-ui-conversation/client' import type { CompactionCheckpointSource } from '@deepseek-ai/dsh-compaction/checkpoint' import type {} from '@deepseek-ai/dsh-compaction/types' import type {} from '@deepseek-ai/dsh-commands/types' import { isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface' import type { ManualCompactionChatData } from '../contract/chat-nodes.ts' -import type { CommandNode, CompactionSummaryNode } from '../contract/snapshot.ts' import { chatNode } from './common.ts' declare module '../contract/chat-nodes.ts' { diff --git a/packages/client/ui-chat/src/client/conversation-nodes/compaction.ts b/packages/client/ui-chat/src/client/conversation-nodes/compaction.ts index 5874c7bd61..9612f08741 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/compaction.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/compaction.ts @@ -1,9 +1,8 @@ import type { Context } from '@deepseek-ai/cordis' import type { - ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, + CompactionSummaryNode, ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, } from '@deepseek-ai/dsh-client-ui-conversation/client' import type {} from '@deepseek-ai/dsh-compaction/types' -import type { CompactionSummaryNode } from '../contract/snapshot.ts' import { chatNode } from './common.ts' import { compactSource, compactSummary, updateCompactionState } from './command.ts' diff --git a/packages/client/ui-chat/src/client/conversation-nodes/fallback.ts b/packages/client/ui-chat/src/client/conversation-nodes/fallback.ts index 356b46ed62..4675515dc3 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/fallback.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/fallback.ts @@ -1,7 +1,8 @@ import type { Context } from '@deepseek-ai/cordis' -import type { ConversationNodeDefinition } from '@deepseek-ai/dsh-client-ui-conversation/client' +import type { + ConversationNodeDefinition, UnknownSurfaceNode, +} from '@deepseek-ai/dsh-client-ui-conversation/client' import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-session/surface' -import type { UnknownSurfaceNode } from '../contract/snapshot.ts' import { chatNode } from './common.ts' declare module '../contract/chat-nodes.ts' { diff --git a/packages/client/ui-chat/src/client/conversation-nodes/message.ts b/packages/client/ui-chat/src/client/conversation-nodes/message.ts index 9611a36cf8..548cf0dc12 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/message.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/message.ts @@ -1,7 +1,8 @@ import type { Context } from '@deepseek-ai/cordis' -import type { ConversationNodeDefinition } from '@deepseek-ai/dsh-client-ui-conversation/client' +import type { + ContextMessageNode, ConversationNodeDefinition, SteeringMessageNode, UserMessageNode, +} from '@deepseek-ai/dsh-client-ui-conversation/client' import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface' -import type { ContextMessageNode, SteeringMessageNode, UserMessageNode } from '../contract/snapshot.ts' import type { InboxState } from './inbox.ts' import { chatNode } from './common.ts' import { contextForm, contextProvenance } from './event-projection.ts' diff --git a/packages/client/ui-chat/src/client/conversation-nodes/partial.ts b/packages/client/ui-chat/src/client/conversation-nodes/partial.ts index ea52a3a565..04fc29dc13 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/partial.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/partial.ts @@ -1,5 +1,5 @@ +import type { AssistantBlock, PartialAssistant } from '@deepseek-ai/dsh-client-ui-conversation/client' import type { StreamChunk } from '@deepseek-ai/dsh-llm/types' -import type { AssistantBlock, PartialAssistant } from '../contract/snapshot.ts' import { emptyAssistantBlock, toAssistantBlock } from './event-projection.ts' /** diff --git a/packages/client/ui-chat/src/client/conversation-nodes/retry.ts b/packages/client/ui-chat/src/client/conversation-nodes/retry.ts index 5209e1dbc2..9f4f6bf9e9 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/retry.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/retry.ts @@ -1,10 +1,9 @@ import type { Context } from '@deepseek-ai/cordis' import type { - ConversationLocation, ConversationNodeDefinition, + ConversationLocation, ConversationNodeDefinition, ModelRetryNode, } from '@deepseek-ai/dsh-client-ui-conversation/client' import type {} from '@deepseek-ai/dsh-llm-retry/types' import type { RetryChatData } from '../contract/chat-nodes.ts' -import type { ModelRetryNode } from '../contract/snapshot.ts' import { chatNode } from './common.ts' declare module '../contract/chat-nodes.ts' { diff --git a/packages/client/ui-chat/src/client/conversation-nodes/tool.ts b/packages/client/ui-chat/src/client/conversation-nodes/tool.ts index b1f675c4e4..c96e66c434 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/tool.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/tool.ts @@ -1,11 +1,10 @@ import type { Context } from '@deepseek-ai/cordis' import type { - ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, + ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, RunningToolCall, ToolCallBlock, ToolResultNode, } from '@deepseek-ai/dsh-client-ui-conversation/client' import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-session/surface' import type {} from '@deepseek-ai/dsh-tools/types' import type { ToolChatData } from '../contract/chat-nodes.ts' -import type { RunningToolCall, ToolCallBlock, ToolResultNode } from '../contract/snapshot.ts' import { CHAT_SYNTHETIC_SEQ_OFFSETS, chatNode } from './common.ts' declare module '../contract/chat-nodes.ts' { diff --git a/packages/client/ui-chat/src/client/conversation-nodes/turn-error.ts b/packages/client/ui-chat/src/client/conversation-nodes/turn-error.ts index e3b41095ce..941f23ac43 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/turn-error.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/turn-error.ts @@ -1,8 +1,7 @@ import type { Context } from '@deepseek-ai/cordis' import type { - ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, + ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, TurnErrorNode, } from '@deepseek-ai/dsh-client-ui-conversation/client' -import type { TurnErrorNode } from '../contract/snapshot.ts' import { chatNode } from './common.ts' import { displayFailure } from './event-projection.ts' diff --git a/packages/client/ui-chat/src/client/conversation-nodes/turn-max-tokens.ts b/packages/client/ui-chat/src/client/conversation-nodes/turn-max-tokens.ts index 31508ab77c..746d00bc95 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/turn-max-tokens.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/turn-max-tokens.ts @@ -1,8 +1,7 @@ import type { Context } from '@deepseek-ai/cordis' import type { - ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, + ConversationMatch, ConversationNodeContext, ConversationNodeDefinition, TurnMaxTokensNode, } from '@deepseek-ai/dsh-client-ui-conversation/client' -import type { TurnMaxTokensNode } from '../contract/snapshot.ts' import { CHAT_SYNTHETIC_SEQ_OFFSETS, chatNode } from './common.ts' declare module '../contract/chat-nodes.ts' { diff --git a/packages/client/ui-chat/src/client/details/DetailsPanel.tsx b/packages/client/ui-chat/src/client/details/DetailsPanel.tsx index 05c997e1fe..9a31274925 100644 --- a/packages/client/ui-chat/src/client/details/DetailsPanel.tsx +++ b/packages/client/ui-chat/src/client/details/DetailsPanel.tsx @@ -1,8 +1,9 @@ +import type { RunningToolCall, ToolCallBlock, ToolResultNode } from '@deepseek-ai/dsh-client-ui-conversation/client' import { Fragment } from 'react' import { CodeBlock } from '@deepseek-ai/dsh-client-ui-primitives' import { shallowEqual } from '@deepseek-ai/dsh-client-store' import type { DetailsSlotProps } from '../contract/slots.ts' -import type { ChatSnapshot, RunningToolCall, ToolCallBlock, ToolResultNode } from '../contract/snapshot.ts' +import type { ChatSnapshot } from '../contract/snapshot.ts' import { findToolCall } from './tool-node-reader.ts' import css from './DetailsPanel.module.css' diff --git a/packages/client/ui-chat/src/client/details/tool-node-reader.ts b/packages/client/ui-chat/src/client/details/tool-node-reader.ts index 9e2488b68f..358286368e 100644 --- a/packages/client/ui-chat/src/client/details/tool-node-reader.ts +++ b/packages/client/ui-chat/src/client/details/tool-node-reader.ts @@ -1,5 +1,6 @@ +import type { ToolCallBlock } from '@deepseek-ai/dsh-client-ui-conversation/client' import type { ChatNode } from '../contract/chat-nodes.ts' -import type { ChatNodeStore, ChatSnapshot, ToolCallBlock } from '../contract/snapshot.ts' +import type { ChatNodeStore, ChatSnapshot } from '../contract/snapshot.ts' function toolNode(node: ReturnType): ChatNode<'tool-call'> | undefined { return node?.kind === 'tool-call' ? node as ChatNode<'tool-call'> : undefined diff --git a/packages/client/ui-chat/src/client/model/conversation-context.ts b/packages/client/ui-chat/src/client/model/conversation-context.ts index 7f8116ffcc..442c455435 100644 --- a/packages/client/ui-chat/src/client/model/conversation-context.ts +++ b/packages/client/ui-chat/src/client/model/conversation-context.ts @@ -1,5 +1,6 @@ -import type { ConversationNode } from '../contract/snapshot.ts' -import type { ConversationPromptSnapshot } from '@deepseek-ai/dsh-client-ui-conversation/client' +import type { + ConversationNode, ConversationPromptSnapshot, +} from '@deepseek-ai/dsh-client-ui-conversation/client' /** Operation that started a new append-only model context. */ export type ConversationContextOriginKind = 'compaction' | 'rewind' | 'rewrite' diff --git a/packages/client/ui-chat/src/client/model/tool-call-tree.ts b/packages/client/ui-chat/src/client/model/tool-call-tree.ts index ce311f5291..130d14bd65 100644 --- a/packages/client/ui-chat/src/client/model/tool-call-tree.ts +++ b/packages/client/ui-chat/src/client/model/tool-call-tree.ts @@ -1,8 +1,6 @@ +import type { ConversationNode, RunningToolCall, ToolCallBlock, ToolResultNode } from '@deepseek-ai/dsh-client-ui-conversation/client' import type { SessionEvent } from '@deepseek-ai/dsh-session/types' import type {} from '@deepseek-ai/dsh-tools/types' -import type { - ConversationNode, RunningToolCall, ToolCallBlock, ToolResultNode, -} from '../contract/snapshot.ts' interface ProjectedBlock { source: ToolCallBlock From 4a793103394a334e38e81b5fbe4127bf22c43a2f Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Mon, 24 Aug 2026 22:40:14 +0800 Subject: [PATCH 002/100] feat(activity): optional live-output observation seam with a web viewer Add the activity capability seam: ctx.activities is a pure observation plane where long-running work (background bash/pwsh, workflow runs) opens a handle, appends transient output into a byte-offset ring buffer, and settles exactly once. Nothing model-visible changes: reads are non-consuming and lossy-by-design (absolute UTF-8 offsets survive eviction and report gaps), correlation carries {callId, jobId}, and visibility is owner-fenced like jobs. The seam is strictly optional. Producers tap it through ctx.get('activities') and contain every observation failure, so an unregistered or broken registry never affects the underlying job (proven by broken-registry tests). Ship the full path in one change: - @deepseek-ai/dsh-activity: Service Definition, pumpActivityOutput pull substrate, invariant companion; dsh-activity-local: ring-buffer provider with retention config and owner cleanup. - shell: ShellProcess.observed exposes non-consuming stdout/stderr readers; tool-bash/tool-pwsh mirror background jobs into activities. - tool-workflow: phase/log/agent lines mirrored as a workflow activity. - api-activity-controller: Typert Remote control (roster baseline+buckets) and observe (opened/output/status frames, coalesced and byte-capped) streams plus the client feed service with reference-counted observation. - ui-activity: session-header action rendering live output through TerminalBlock, which now shows output while a command is still running. Docs: activity subsystem page, architecture row, regenerated catalogs, and the Agent Note (2026-08-24-activity-observation-seam), all bilingual. A keyless web e2e replays a real run_in_background stream to ARIA goldens. --- ...-08-24-activity-observation-seam.i18n.yaml | 6 + .../2026-08-24-activity-observation-seam.md | 51 ++ ...2026-08-24-activity-observation-seam.zh.md | 51 ++ apps/cli/composition.md | 3 + apps/web/tests/live-activity-stream.e2e.ts | 134 ++++++ .../live-activity-stream/settled.expected.md | 8 + .../streaming.expected.md | 8 + apps/web/tsconfig.json | 1 + docs/architecture.i18n.yaml | 4 +- docs/architecture.md | 1 + docs/architecture.zh.md | 1 + docs/capability-seams.i18n.yaml | 4 +- docs/capability-seams.md | 17 +- docs/capability-seams.zh.md | 17 +- docs/config-catalog.i18n.yaml | 4 +- docs/config-catalog.md | 46 +- docs/config-catalog.zh.md | 44 +- docs/event-producer-consumer.i18n.yaml | 4 +- docs/event-producer-consumer.md | 4 +- docs/event-producer-consumer.zh.md | 4 +- docs/subsystems/README.i18n.yaml | 4 +- docs/subsystems/README.md | 1 + docs/subsystems/README.zh.md | 1 + docs/subsystems/activity.i18n.yaml | 6 + docs/subsystems/activity.md | 141 ++++++ docs/subsystems/activity.zh.md | 141 ++++++ docs/subsystems/shell.i18n.yaml | 4 +- docs/subsystems/shell.md | 7 + docs/subsystems/shell.zh.md | 7 + knip.json | 5 + packages/activity/README.i18n.yaml | 6 + packages/activity/README.md | 14 + packages/activity/README.zh.md | 14 + .../activity/activity-local/README.i18n.yaml | 6 + packages/activity/activity-local/README.md | 30 ++ packages/activity/activity-local/README.zh.md | 30 ++ packages/activity/activity-local/package.json | 55 +++ packages/activity/activity-local/src/index.ts | 438 ++++++++++++++++++ .../activity/activity-local/src/invariant.ts | 33 ++ .../activity-local/tests/activity.spec.ts | 413 +++++++++++++++++ .../tests/loader-composition.spec.ts | 60 +++ .../activity/activity-local/tsconfig.json | 33 ++ packages/activity/activity/README.i18n.yaml | 6 + packages/activity/activity/README.md | 32 ++ packages/activity/activity/README.zh.md | 32 ++ packages/activity/activity/package.json | 57 +++ packages/activity/activity/src/brand.ts | 28 ++ packages/activity/activity/src/index.ts | 138 ++++++ packages/activity/activity/src/invariant.ts | 62 +++ packages/activity/activity/src/pump.ts | 95 ++++ packages/activity/activity/src/types.ts | 179 +++++++ .../activity/activity/tests/invariant.spec.ts | 82 ++++ .../activity/activity/tests/service.spec.ts | 98 ++++ packages/activity/activity/tsconfig.json | 36 ++ .../api/activity-controller/README.i18n.yaml | 6 + packages/api/activity-controller/README.md | 30 ++ packages/api/activity-controller/README.zh.md | 30 ++ packages/api/activity-controller/package.json | 103 ++++ .../activity-controller/src/client/index.ts | 86 ++++ .../activity-controller/src/client/model.ts | 211 +++++++++ .../activity-controller/src/client/service.ts | 156 +++++++ packages/api/activity-controller/src/feed.ts | 184 ++++++++ packages/api/activity-controller/src/index.ts | 104 +++++ .../api/activity-controller/src/invariant.ts | 23 + .../api/activity-controller/src/observe.ts | 178 +++++++ packages/api/activity-controller/src/types.ts | 104 +++++ .../tests/activity-controller.host.spec.ts | 306 ++++++++++++ .../tests/client-apply.client.spec.ts | 113 +++++ .../tests/client-model.client.spec.ts | 168 +++++++ .../tests/client-service.client.spec.ts | 213 +++++++++ .../tests/controller.host.spec.ts | 102 ++++ .../activity-controller/tsconfig.client.json | 46 ++ .../activity-controller/tsconfig.host.json | 26 ++ .../api/activity-controller/tsconfig.json | 7 + .../api/activity-controller/tsdown.config.ts | 7 + packages/api/remotes/package.json | 2 + packages/api/remotes/src/client/index.ts | 5 +- packages/api/remotes/src/index.ts | 1 + packages/api/remotes/tsconfig.client.json | 3 + packages/api/remotes/tsconfig.host.json | 3 + packages/bundle/base/cordis.patch.yml | 5 + packages/bundle/base/package.json | 17 +- packages/bundle/web-app/cordis.patch.yml | 9 + packages/bundle/web-app/package.json | 42 +- packages/client/ui-activity/README.i18n.yaml | 6 + packages/client/ui-activity/README.md | 21 + packages/client/ui-activity/README.zh.md | 21 + packages/client/ui-activity/package.json | 77 +++ .../src/client/ActivityListAction.module.css | 155 +++++++ .../src/client/ActivityListAction.tsx | 250 ++++++++++ .../client/ui-activity/src/client/index.ts | 48 ++ .../client/ui-activity/src/client/locales.ts | 65 +++ .../client/ui-activity/src/css-modules.d.ts | 4 + packages/client/ui-activity/src/index.ts | 9 + packages/client/ui-activity/src/invariant.ts | 27 ++ .../activity-list-action.client.spec.tsx | 244 ++++++++++ .../tests/browser-plugin.client.spec.ts | 115 +++++ packages/client/ui-activity/tsconfig.json | 22 + packages/client/ui-activity/tsdown.config.ts | 6 + .../client/ui-primitives/README.i18n.yaml | 4 +- packages/client/ui-primitives/README.md | 2 +- packages/client/ui-primitives/README.zh.md | 2 +- .../ui-primitives/src/TerminalBlock.tsx | 12 +- .../tests/terminal-block.client.spec.tsx | 21 +- .../src/client/slot-catalog.ts | 1 + .../extensions/tool-cordis/src/api-catalog.ts | 156 ++++++- packages/jobs/jobs/README.i18n.yaml | 4 +- packages/jobs/jobs/README.md | 2 +- packages/jobs/jobs/README.zh.md | 2 +- packages/shell/bash-local/src/index.ts | 1 + packages/shell/pwsh-local/src/index.ts | 1 + packages/shell/shell/README.i18n.yaml | 4 +- packages/shell/shell/README.md | 1 + packages/shell/shell/README.zh.md | 1 + packages/shell/shell/src/types.ts | 23 +- packages/shell/tool-bash/README.i18n.yaml | 4 +- packages/shell/tool-bash/README.md | 2 +- packages/shell/tool-bash/README.zh.md | 2 +- packages/shell/tool-bash/package.json | 26 +- packages/shell/tool-bash/src/index.ts | 24 +- packages/shell/tool-bash/src/observe.ts | 72 +++ .../shell/tool-bash/tests/observe.spec.ts | 194 ++++++++ packages/shell/tool-bash/tsconfig.json | 3 + packages/shell/tool-pwsh/README.i18n.yaml | 4 +- packages/shell/tool-pwsh/README.md | 2 +- packages/shell/tool-pwsh/README.zh.md | 2 +- packages/shell/tool-pwsh/package.json | 24 +- packages/shell/tool-pwsh/src/index.ts | 32 +- packages/shell/tool-pwsh/src/observe.ts | 74 +++ .../shell/tool-pwsh/tests/observe.spec.ts | 154 ++++++ packages/shell/tool-pwsh/tsconfig.json | 3 + .../workflow/tool-workflow/README.i18n.yaml | 4 +- packages/workflow/tool-workflow/README.md | 2 +- packages/workflow/tool-workflow/README.zh.md | 2 +- packages/workflow/tool-workflow/package.json | 11 +- .../workflow/tool-workflow/src/activity.ts | 119 +++++ packages/workflow/tool-workflow/src/index.ts | 13 +- .../tests/activity-mirror.spec.ts | 106 +++++ packages/workflow/tool-workflow/tsconfig.json | 3 + pnpm-lock.yaml | 170 +++++++ python/sdk-runtime/package.json | 49 +- scripts/gen-cordis-catalog.ts | 13 + scripts/gen-doc-graphs.ts | 16 + .../verify-package-readme-model-experience.ts | 4 + tsconfig.base.json | 6 + tsconfig.client.json | 2 + tsconfig.host.json | 4 + 147 files changed, 7311 insertions(+), 138 deletions(-) create mode 100644 .agents/notes/implemented/feature/2026-08-24-activity-observation-seam.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md create mode 100644 .agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md create mode 100644 apps/web/tests/live-activity-stream.e2e.ts create mode 100644 apps/web/tests/snapshots/live-activity-stream/settled.expected.md create mode 100644 apps/web/tests/snapshots/live-activity-stream/streaming.expected.md create mode 100644 docs/subsystems/activity.i18n.yaml create mode 100644 docs/subsystems/activity.md create mode 100644 docs/subsystems/activity.zh.md create mode 100644 packages/activity/README.i18n.yaml create mode 100644 packages/activity/README.md create mode 100644 packages/activity/README.zh.md create mode 100644 packages/activity/activity-local/README.i18n.yaml create mode 100644 packages/activity/activity-local/README.md create mode 100644 packages/activity/activity-local/README.zh.md create mode 100644 packages/activity/activity-local/package.json create mode 100644 packages/activity/activity-local/src/index.ts create mode 100644 packages/activity/activity-local/src/invariant.ts create mode 100644 packages/activity/activity-local/tests/activity.spec.ts create mode 100644 packages/activity/activity-local/tests/loader-composition.spec.ts create mode 100644 packages/activity/activity-local/tsconfig.json create mode 100644 packages/activity/activity/README.i18n.yaml create mode 100644 packages/activity/activity/README.md create mode 100644 packages/activity/activity/README.zh.md create mode 100644 packages/activity/activity/package.json create mode 100644 packages/activity/activity/src/brand.ts create mode 100644 packages/activity/activity/src/index.ts create mode 100644 packages/activity/activity/src/invariant.ts create mode 100644 packages/activity/activity/src/pump.ts create mode 100644 packages/activity/activity/src/types.ts create mode 100644 packages/activity/activity/tests/invariant.spec.ts create mode 100644 packages/activity/activity/tests/service.spec.ts create mode 100644 packages/activity/activity/tsconfig.json create mode 100644 packages/api/activity-controller/README.i18n.yaml create mode 100644 packages/api/activity-controller/README.md create mode 100644 packages/api/activity-controller/README.zh.md create mode 100644 packages/api/activity-controller/package.json create mode 100644 packages/api/activity-controller/src/client/index.ts create mode 100644 packages/api/activity-controller/src/client/model.ts create mode 100644 packages/api/activity-controller/src/client/service.ts create mode 100644 packages/api/activity-controller/src/feed.ts create mode 100644 packages/api/activity-controller/src/index.ts create mode 100644 packages/api/activity-controller/src/invariant.ts create mode 100644 packages/api/activity-controller/src/observe.ts create mode 100644 packages/api/activity-controller/src/types.ts create mode 100644 packages/api/activity-controller/tests/activity-controller.host.spec.ts create mode 100644 packages/api/activity-controller/tests/client-apply.client.spec.ts create mode 100644 packages/api/activity-controller/tests/client-model.client.spec.ts create mode 100644 packages/api/activity-controller/tests/client-service.client.spec.ts create mode 100644 packages/api/activity-controller/tests/controller.host.spec.ts create mode 100644 packages/api/activity-controller/tsconfig.client.json create mode 100644 packages/api/activity-controller/tsconfig.host.json create mode 100644 packages/api/activity-controller/tsconfig.json create mode 100644 packages/api/activity-controller/tsdown.config.ts create mode 100644 packages/client/ui-activity/README.i18n.yaml create mode 100644 packages/client/ui-activity/README.md create mode 100644 packages/client/ui-activity/README.zh.md create mode 100644 packages/client/ui-activity/package.json create mode 100644 packages/client/ui-activity/src/client/ActivityListAction.module.css create mode 100644 packages/client/ui-activity/src/client/ActivityListAction.tsx create mode 100644 packages/client/ui-activity/src/client/index.ts create mode 100644 packages/client/ui-activity/src/client/locales.ts create mode 100644 packages/client/ui-activity/src/css-modules.d.ts create mode 100644 packages/client/ui-activity/src/index.ts create mode 100644 packages/client/ui-activity/src/invariant.ts create mode 100644 packages/client/ui-activity/tests/activity-list-action.client.spec.tsx create mode 100644 packages/client/ui-activity/tests/browser-plugin.client.spec.ts create mode 100644 packages/client/ui-activity/tsconfig.json create mode 100644 packages/client/ui-activity/tsdown.config.ts create mode 100644 packages/shell/tool-bash/src/observe.ts create mode 100644 packages/shell/tool-bash/tests/observe.spec.ts create mode 100644 packages/shell/tool-pwsh/src/observe.ts create mode 100644 packages/shell/tool-pwsh/tests/observe.spec.ts create mode 100644 packages/workflow/tool-workflow/src/activity.ts create mode 100644 packages/workflow/tool-workflow/tests/activity-mirror.spec.ts diff --git a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.i18n.yaml new file mode 100644 index 0000000000..07186d7a2c --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-24-activity-observation-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 .agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md +2026-08-24-activity-observation-seam.md: da356b3b871a45958dc5a5214ccff8b49c0c193f +2026-08-24-activity-observation-seam.zh.md: 1c0c87d23a08d41882f00fd8f729f794d09169b1 diff --git a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md new file mode 100644 index 0000000000..da356b3b87 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md @@ -0,0 +1,51 @@ +# Agent Note: The activity observation seam (`ctx.activities`) and live output streaming to the Web client + +Status: implemented + +English | [中文](2026-08-24-activity-observation-seam.zh.md) + +## Problem + +Every incremental reader in the shell, terminal, and jobs layers is single-consumer and consuming: `ShellProcess.readOutput()`, `TerminalSendOperation.readOutput()`, and `JobRegistry.read()` all destroy the delta they return, because the owning model is the intended reader. The [web background-job display](2026-08-08-web-background-job-display.md) shipped the roster on those terms — its carrier is test-pinned to never call `ctx.jobs.read()`, since a browser read would silently steal bytes the model's `job_output` would never see — and explicitly deferred the output phase to "a separate non-consuming observation API". So a human watching the Web client saw that a background build was running but never a line of its output, and the `workflow/log` / `workflow/phase` events scripts are told to narrate with had no consumer at all. + +The substrate below bash already had the right shape: `SubprocessOutputReader.readFrom(fromByte)` is offset-based and explicitly non-consuming, and `bash-local` narrows it to a single cursor pair at the shell seam. + +## Decision + +A new capability seam, `packages/activity/`, is the non-consuming observation plane. An **activity** is one observable unit of long-running work: an append-only bounded output stream plus live status. The seam is pure observation — it starts nothing, cancels nothing, and is invisible to the model. Model-visible facts stay exactly where they were (tool results, `ctx.jobs` cursors), so the "model-visible ⟺ logged" invariant is untouched and a composition without the seam loses only live observation. + +- **`@deepseek-ai/dsh-activity` (Service Definition)** — abstract `ActivityRegistry` on `ctx.activities`: `open(spec) → ActivityHandle { append, updateDetail, end }`, fenced `get`/`list`, non-consuming `read(id, from)` over absolute UTF-8 byte offsets, owner-relative `onActivitiesChanged` (roster) and `onOutput` (advancement signal, id only). `ActivityCorrelation { callId?, jobId? }` links a row to its tool call and job. `pumpActivityOutput` is the shared pull-substrate pump. +- **`@deepseek-ai/dsh-activity-local` (Service Provider)** — in-memory chunk ring per activity. Offsets stay absolute across eviction (`outputEarliest` marks the oldest retained byte; a read below it is `lossy`, never an error); a single over-cap chunk keeps its UTF-8-safe tail with `gapBefore`. Config `retainBytes` (256 KiB) live, trimmed to `settledRetainBytes` (16 KiB) at settlement. Records outlive producer fibers; owner disposal force-ends and removes; `end` is first-wins and post-end writes log-and-drop so a producer's trailing flush cannot break its own teardown. +- **`@deepseek-ai/dsh-api-activity-controller`** — the wire, in the workspace-controller shape: `activity.control` streams one roster baseline then whole-bucket replacement frames per owner session (the jobs-frame self-healing semantics), and `activity.observe({ activityId, from? })` streams one `opened` anchor, coalesced `output` frames (`flushMs` window, `maxFrameBytes` soft budget), then the terminal `status` on the same stream before closing — so settlement can never race a still-open output channel. Reconnects resume from the last frame's `next`. The client half installs `ctx.activityFeed` (roster mirror plus reference-counted observation streams with a bounded render tail). +- **`@deepseek-ai/dsh-client-ui-activity`** — one session-header action beside the job list; expanding a row opens its observation stream into a `TerminalBlock` panel, collapsing closes it, so output only flows while someone is watching. `TerminalBlock` itself gained live rendering: a running block with supplied `output` shows the text under the running state instead of the historical prompt-only frame. + +Producers mirror best-effort behind `ctx.get('activities')`, never a declared inject, and every observation failure is logged and swallowed — the seam is strictly optional and can never break the work it observes: + +- `ShellProcess` gained optional `observed` — the substrate's non-consuming offset readers re-exposed (bash-local and pwsh-local return `handle.collected`; the e2b subprocess provider satisfies the same contract). `dsh-tool-bash` / `dsh-tool-pwsh` open a correlated activity after `jobs.start()` commits and pump `observed` at `activityPollMs` (default 150 ms). +- `dsh-tool-workflow` mirrors each recorded top-level run as a push-mode `workflow` activity, giving the previously unconsumed `workflow/phase` / `workflow/log` events their consumer. + +### Why not durable session events, the control stream, or the jobs seam + +Peer products converge on the same split (Codex marks every exec-output delta "Transient, non-durable" in its rollout policy; Claude Code persists a file path, never deltas; Kimi's envelope has a first-class `volatile: true`; OpenCode's V2 corrected V1's per-chunk durable part updates to "stream fragments are live-only"). In this repository the durable route is also concretely bad: chunk-run packing is hardcoded to the three `assistant/chunk` shapes so a new output event gets zero compression, each event is one uncoalesced WebSocket frame, and reconnect gap-repair re-reads the window — and the job-display note already rejected it ("spill exists precisely so oversized tool output stays out of the log"). The session control stream's whole-snapshot frames are self-healing for rosters but quadratic for streams. Extending the jobs seam would cover only jobs — not workflow narration, not a future foreground stream — and would re-litigate the settled "producers own their buffers" decision; the activity plane instead recovers the substrate's existing offsets. + +### Two cursor regimes, kept separate + +The model keeps its consuming cursors (`job_output` semantics unchanged, zero prompt or tool changes anywhere in this work); observers get absolute offsets any number of readers can hold. This mirrors the strongest peer pattern (Codex: destructive drain for the model, seq-cursor reads for infrastructure) and is what makes the wire path provably non-stealing. + +## Alternatives considered + +**Durable `activity/output` session events with a conversation node.** Replay for free, but the log-growth math above, plus retention pressure on every follower, killed it; the transcript's durable story remains the producers' tool results. + +**Extending `SessionControlFrame` with output.** One fewer stream, but whole-snapshot semantics resend the accumulated buffer per chunk — O(n²) on exactly the data that grows. + +**A signal frame plus RPC pull.** The subagent-catalog shape; rejected for the split-authority apparatus the job-display note documents, and it fails worst at settlement (running row, dead stream). + +**Observation inside the jobs seam.** One integration point, but only for jobs; foreground runs, terminals, and workflow narration would each need another mechanism, and the registry would grow a second buffer beside the producers' own. + +## Testing + +Unit suites pin the registry (offsets, eviction, UTF-8-safe tail trims, lossy reads, first-wins settlement, owner cleanup, scoped delivery, listener containment, HMR disposal, Loader composition with row config), the pump (cadence, per-source cursors, lossy `gapBefore`, settlement drain, timer hygiene), the controller (baseline/bucket frames, anchor/output/status ordering, resume, frame splitting, fenced owned reads, abort), the client model and reference-counted streams, and both producer taps (real subprocess output for bash including the never-steals-the-model's-cursor assertion; scripted readers for pwsh; event-driven mirror for workflow, including the throwing-registry containment the optionality promise requires). The keyless web e2e drives a real `run_in_background` bash through the full composition and pins ARIA goldens for the streaming panel while the command still runs and for the settled panel after a registry kill. + +## Consequences + +The Web client now shows live output for background bash/pwsh and workflow narration with zero model-facing change, and any plugin can join with three calls (`open`/`append`/`end`) against an optional service. Bought at the cost of one more seam family and a per-producer tap; the roster duplicates a background job's row across two header lists (accepted, as the subagent catalog precedent was). Deferred, recorded on the package READMEs: foreground streaming (needs a shell-seam run/observe variant), terminal `pty-send` observation (needs a non-consuming face on terminal buffers), a human kill control (blocked on the jobs `reported` contract), SDK/ACP consumers, and durable replay after restart. diff --git a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md new file mode 100644 index 0000000000..1c0c87d23a --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md @@ -0,0 +1,51 @@ +# Agent Note:activity 观察 seam(`ctx.activities`)与 Web 客户端实时输出流 + +状态:implemented + +[English](2026-08-24-activity-observation-seam.md) | 中文 + +## 问题 + +shell、terminal 与 jobs 各层的增量读取器全都是单读者且消费型的:`ShellProcess.readOutput()`、`TerminalSendOperation.readOutput()` 与 `JobRegistry.read()` 返回即销毁增量,因为预期读者就是持有模型。[Web 后台任务显示](2026-08-08-web-background-job-display.zh.md)在这一前提下交付了 roster——其载体被测试钉死绝不调用 `ctx.jobs.read()`,否则浏览器读取会无声偷走模型 `job_output` 永远看不到的字节——并把输出阶段明确推迟给"一个独立的非消费观察 API"。于是人在 Web 客户端只能看到后台构建"在跑",看不到一行输出;脚本被告知用来叙述进度的 `workflow/log` / `workflow/phase` 事件更是全无消费者。 + +bash 之下的底座其实早有正确形态:`SubprocessOutputReader.readFrom(fromByte)` 是按 offset、明确非消费的,`bash-local` 在 shell seam 把它窄化成了单游标对。 + +## 决策 + +新建能力 seam `packages/activity/`,作为非消费观察面。**activity** 是一个可观察的长时工作单元:一条 append-only 的有界输出流加实时状态。该 seam 是纯观察——不启动、不取消任何工作,对模型不可见。模型可见事实原地不动(工具结果、`ctx.jobs` 游标),"模型可见 ⟺ 已记录"不变量不受影响;不装该 seam 的组合只失去实时观察。 + +- **`@deepseek-ai/dsh-activity`(Service Definition)**——`ctx.activities` 上的抽象 `ActivityRegistry`:`open(spec) → ActivityHandle { append, updateDetail, end }`、有栅栏的 `get`/`list`、按绝对 UTF-8 字节 offset 的非消费 `read(id, from)`、owner 相对投递的 `onActivitiesChanged`(roster)与 `onOutput`(推进信号,只带 id)。`ActivityCorrelation { callId?, jobId? }` 把行关联到工具调用与 job。`pumpActivityOutput` 是 pull 型底座的共享泵。 +- **`@deepseek-ai/dsh-activity-local`(Service Provider)**——每个 activity 一个内存 chunk 环。offset 跨淘汰稳定(`outputEarliest` 指明最老保留字节;低于它的读取是 `lossy` 而非错误);单个超上限 chunk 保留 UTF-8 安全尾部并带 `gapBefore`。配置 `retainBytes`(256 KiB)存活,结算时裁到 `settledRetainBytes`(16 KiB)。记录存续期长于生产者 fiber;owner 销毁强制终结并移除;`end` first-wins,end 后写入记日志后丢弃,生产者的收尾 flush 砸不掉自己的 teardown。 +- **`@deepseek-ai/dsh-api-activity-controller`**——wire 层,取 workspace-controller 的形态:`activity.control` 流出一份 roster baseline 加按 owner 会话的整桶替换帧(jobs 帧的自愈语义);`activity.observe({ activityId, from? })` 流出一帧 `opened` 锚点、合并的 `output` 帧(`flushMs` 窗口、`maxFrameBytes` 软预算)、再在同一条流上发终态 `status` 后关闭——结算永远不会与仍开着的输出通道竞态。重连以上一帧的 `next` 续传。客户端半区安装 `ctx.activityFeed`(roster 镜像 + 按引用计数的观察流与有界渲染尾巴)。 +- **`@deepseek-ai/dsh-client-ui-activity`**——job 列表旁的一个会话头部 action;展开某行即把其观察流打开进 `TerminalBlock` 面板,收起即关——只有有人在看时输出才流动。`TerminalBlock` 本身获得实时渲染能力:running 且提供了 `output` 的块在 running 状态下显示文本,而非历史上的仅提示行画面。 + +生产者一律经 `ctx.get('activities')` 尽力镜像,绝不声明 inject,一切观察失败只记日志并吞掉——该 seam 严格可选,永远不能破坏它所观察的工作: + +- `ShellProcess` 新增可选 `observed`——底座的非消费 offset 读取器复出(bash-local 与 pwsh-local 返回 `handle.collected`;e2b subprocess provider 满足同一契约)。`dsh-tool-bash` / `dsh-tool-pwsh` 在 `jobs.start()` 提交后打开带关联的 activity,并以 `activityPollMs`(默认 150 ms)泵取 `observed`。 +- `dsh-tool-workflow` 把每个被记录的顶层运行镜像为 push 形态的 `workflow` activity,让此前无人消费的 `workflow/phase` / `workflow/log` 事件有了消费者。 + +### 为何不用持久会话事件、control 流或 jobs seam + +同行产品收敛于同一切分(Codex 在 rollout policy 里把所有 exec 输出 delta 标为 "Transient, non-durable";Claude Code 持久化文件路径而非 delta;Kimi 的信封有一等的 `volatile: true`;OpenCode V2 把 V1 逐 chunk 持久化 part 更新纠正为 "stream fragments are live-only")。在本仓库持久路线还有具体的坏处:chunk-run 打包只认三种 `assistant/chunk` 形态,新输出事件零压缩;每事件一条未合并的 WebSocket 帧;重连缺口修复要重读窗口——且 job 显示 note 已否决过它("spill 的存在就是为了让超大工具输出不进日志")。session control 流的整值帧对 roster 自愈、对流则是二次方开销。扩 jobs seam 只覆盖 jobs——workflow 叙述与未来的前台流都覆盖不到——还要重翻已定案的"生产者拥有自己的缓冲";activity 面转而复用底座既有的 offset。 + +### 两套游标制,各归其位 + +模型保留消费游标(`job_output` 语义不变,本次工作零 prompt/工具改动);观察者拿任意多读者可共持的绝对 offset。这正是最强的同行范式(Codex:模型用破坏性 drain,基础设施用 seq 游标读取),也是 wire 路径可证明"不偷字节"的原因。 + +## 曾考虑的替代方案 + +**持久 `activity/output` 会话事件 + conversation node。** 回放免费,但上述日志膨胀账加上对每个 follower 的保留压力否掉了它;transcript 侧的持久故事仍是生产者的工具结果。 + +**给 `SessionControlFrame` 加输出。** 少一条流,但整值语义会按 chunk 重发累计缓冲——恰好在会增长的数据上 O(n²)。 + +**信号帧 + RPC 拉取。** subagent catalog 的形态;因 job 显示 note 记录的权威割裂机制而否决,且它在结算时刻失效得最难看(行还在跑、流已死)。 + +**在 jobs seam 内做观察。** 一个集成点,但只对 jobs;前台运行、terminal 与 workflow 叙述各需另一套机制,注册表还得在生产者自己的缓冲旁再养一份。 + +## 测试 + +单测钉住注册表(offset、淘汰、UTF-8 安全裁尾、lossy 读取、first-wins 结算、owner 清理、scope 投递、监听容错、HMR 可逆、带行配置的 Loader 组合)、泵(节奏、每源游标、lossy `gapBefore`、结算排干、定时器卫生)、controller(baseline/桶帧、锚点/输出/状态排序、续传、帧切分、有栅栏的有主读取、abort)、客户端模型与引用计数流,以及两类生产者接入(bash 用真实子进程输出,含"绝不偷模型游标"断言;pwsh 用脚本化读取器;workflow 用事件驱动镜像,含可选性承诺要求的 throwing-registry 容错)。无钥 web e2e 经完整组合驱动真实 `run_in_background` bash,钉住命令仍在运行时流式面板与注册表 kill 后已结算面板的 ARIA golden。 + +## 后果 + +Web 客户端在零模型面改动下获得后台 bash/pwsh 实时输出与 workflow 叙述;任何插件对着一个可选服务用三个调用(`open`/`append`/`end`)即可接入。代价是多一个 seam 家族与每生产者一个接入点;后台 job 的行会在两个头部列表重复出现(沿用 subagent catalog 的既有取舍)。暂缓项记录在各包 README:前台流式(需 shell seam 的 run/observe 变体)、terminal `pty-send` 观察(需给 terminal 缓冲加非消费面)、人工 kill 控件(被 jobs `reported` 契约阻塞)、SDK/ACP 消费端、重启后的持久回放。 diff --git a/apps/cli/composition.md b/apps/cli/composition.md index 9ec9a9a22d..31548a2d43 100644 --- a/apps/cli/composition.md +++ b/apps/cli/composition.md @@ -40,6 +40,8 @@ flowchart LR cfg --> plugin_dsh_base_agent_default_model plugin_dsh_base_jobs["jobs
@deepseek-ai/dsh-jobs-local"] cfg --> plugin_dsh_base_jobs + plugin_dsh_base_activity["activity
@deepseek-ai/dsh-activity-local"] + cfg --> plugin_dsh_base_activity plugin_dsh_base_llm_retry["llm-retry
@deepseek-ai/dsh-llm-retry"] cfg --> plugin_dsh_base_llm_retry plugin_dsh_base_settings["settings
@deepseek-ai/dsh-settings-file"] @@ -190,6 +192,7 @@ flowchart LR | `plugin-package-inventory-deepseek` | `@deepseek-ai/dsh-plugin-package-inventory-deepseek` | | `agent-default-model` | `@deepseek-ai/dsh-agent-default-model` | | `jobs` | `@deepseek-ai/dsh-jobs-local` | +| `activity` | `@deepseek-ai/dsh-activity-local` | | `llm-retry` | `@deepseek-ai/dsh-llm-retry` | | `settings` | `@deepseek-ai/dsh-settings-file` | | `credentials` | `@deepseek-ai/dsh-credentials-local` | diff --git a/apps/web/tests/live-activity-stream.e2e.ts b/apps/web/tests/live-activity-stream.e2e.ts new file mode 100644 index 0000000000..750e1697f3 --- /dev/null +++ b/apps/web/tests/live-activity-stream.e2e.ts @@ -0,0 +1,134 @@ +// Session-header live activities driven by a real background bash run: the +// roster row arrives over the activity control stream, expanding it opens the +// observation stream, and the panel shows the process's real output while it +// is still running. No model call is involved. +import { readFile } from 'node:fs/promises' +import { fileURLToPath } from 'node:url' +import { join } from 'node:path' +import type { Browser, Page } from 'playwright' +import { chromium } from 'playwright' +import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' +import type { Agent } from '@deepseek-ai/dsh-agent' +import { CallId } from '@deepseek-ai/dsh-llm' +import { SessionId } from '@deepseek-ai/dsh-session' +import { JobId } from '@deepseek-ai/dsh-jobs' +import { + assertFixtureInventory, captureStableAria, compareOrRefreshGolden, + launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold, +} from './scaffold.ts' +import { newEnglishPage, saveFailureShot } from './support.ts' + +const FIXTURE = fileURLToPath(new URL('./snapshots/fresh-round-trip/session.jsonl', import.meta.url)) +const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/live-activity-stream', import.meta.url)) +const STREAMING_EXPECTED = join(SNAPSHOT_DIR, 'streaming.expected.md') +const SETTLED_EXPECTED = join(SNAPSHOT_DIR, 'settled.expected.md') +const MODE = webSnapshotMode() +const SEED_ID = 'live-activity-stream-web-e2e' +// One fixed line of early output, then silence long enough that the streaming +// assertions never race the process exiting; the test kills it explicitly. +const COMMAND = "printf 'streamed-%s\\n' marker-line; sleep 45" + +/** + * Wait for opening a session to publish its live Agent. + * @param scaffold - the booted web scaffold. + * @param sessionId - the opened session's identity. + * @returns the registered Agent instance. + */ +async function liveAgent(scaffold: WebScaffold, sessionId: SessionId): Promise { + const deadline = Date.now() + 30_000 + for (;;) { + const found = scaffold.ctx.agents.get(sessionId) + if (found !== undefined) return found + if (Date.now() > deadline) throw new Error(`opening session "${sessionId}" published no live Agent`) + await new Promise(resolve => setTimeout(resolve, 100)) + } +} + +describe.skipIf(MODE === 'record')('web e2e: live activity stream', () => { + let scaffold: WebScaffold + let browser: Browser + let page: Page + let tripwire: ReturnType + let agent: Agent + let jobId: JobId + + beforeAll(async () => { + scaffold = await launchWebScaffold({}) + await seedSession(scaffold, await readFile(FIXTURE, 'utf8'), SEED_ID) + browser = await chromium.launch() + page = await newEnglishPage(browser) + tripwire = watchConsole(page) + await page.goto(scaffold.baseUrl, { waitUntil: 'load' }) + await page.waitForSelector('[class*="frame"]', { timeout: 30_000 }) + + const groupRow = page.locator('[role="treeitem"]').first() + await groupRow.waitFor({ timeout: 15_000 }) + await groupRow.click() + const sessionRow = page.locator('[role="treeitem"]').nth(1) + await sessionRow.waitFor({ timeout: 10_000 }) + await sessionRow.click() + + // Opening the session drives the Host's ordinary Agent resolution; the + // activity owner must be that exact live instance, never a second one. + agent = await liveAgent(scaffold, SessionId(SEED_ID)) + }, 120_000) + + afterAll(async () => { + await browser?.close() + await scaffold?.close() + }) + + it('streams a running background command\'s real output into the expanded panel', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-live-activity-streaming')) + const trigger = page.getByRole('button', { name: '1 live activity' }) + expect(await trigger.count()).toBe(0) + + const started = await scaffold.ctx.tools.execute({ + signal: new AbortController().signal, + callId: CallId('live-activity-stream-e2e'), + name: 'bash', + arguments: { command: COMMAND, description: 'Emit one live line then hold', run_in_background: true }, + agent, + }) + const reported = started.content.map(block => block.type === 'text' ? block.text : '').join('') + const matched = /\bbash-\d+\b/.exec(reported) + if (matched === null) throw new Error(`background bash reported no job id: ${reported}`) + jobId = JobId(matched[0]) + + // The roster row reaches the header over the activity control stream. + await trigger.waitFor({ timeout: 15_000 }) + await trigger.click() + + // Expanding the row opens the observation stream; the panel then renders + // the command's real stdout while the process is still running. + const expand = page.getByRole('button', { name: /Show live output/ }) + await expand.waitFor({ timeout: 10_000 }) + await expand.click() + await page.getByText('streamed-marker-line').waitFor({ timeout: 15_000 }) + + const snapshot = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd) + await compareOrRefreshGolden(STREAMING_EXPECTED, snapshot, MODE) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + }, 60_000) + + it('settles the open panel when the job is killed, keeping the streamed tail', async () => { + onTestFailed(() => saveFailureShot(page, 'web-e2e-live-activity-settled')) + expect(scaffold.ctx.jobs.kill(jobId, agent, 'web e2e cancellation')).toBe('requested') + + // Settlement arrives on the observation stream itself, so the open panel + // flips without any further interaction; the roster trigger follows. + const idle = page.getByRole('button', { name: '1 activity' }) + await idle.waitFor({ timeout: 20_000 }) + await page.getByText('streamed-marker-line').waitFor({ timeout: 10_000 }) + + const snapshot = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd) + await compareOrRefreshGolden(SETTLED_EXPECTED, snapshot, MODE) + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + }, 60_000) + + it('keeps its snapshot inventory closed', async () => { + await assertFixtureInventory(SNAPSHOT_DIR, ['settled.expected.md', 'streaming.expected.md']) + }) +}) diff --git a/apps/web/tests/snapshots/live-activity-stream/settled.expected.md b/apps/web/tests/snapshots/live-activity-stream/settled.expected.md new file mode 100644 index 0000000000..7ffec602cb --- /dev/null +++ b/apps/web/tests/snapshots/live-activity-stream/settled.expected.md @@ -0,0 +1,8 @@ +- list "Live activities": + - listitem: + - button "Hide live output of printf 'streamed-%s\\n' marker-line; sleep 45" [expanded]: + - text: "bash printf 'streamed-%s\\n' marker-line; sleep 45 signal: SIGTERM" + - img + - text: done $ printf 'streamed-%s\n' marker-line; sleep 45 + - button "Copy" + - text: streamed-marker-line diff --git a/apps/web/tests/snapshots/live-activity-stream/streaming.expected.md b/apps/web/tests/snapshots/live-activity-stream/streaming.expected.md new file mode 100644 index 0000000000..fd536ef430 --- /dev/null +++ b/apps/web/tests/snapshots/live-activity-stream/streaming.expected.md @@ -0,0 +1,8 @@ +- list "Live activities": + - listitem: + - button "Hide live output of printf 'streamed-%s\\n' marker-line; sleep 45" [expanded]: + - text: bash printf 'streamed-%s\n' marker-line; sleep 45 running + - img + - text: running $ printf 'streamed-%s\n' marker-line; sleep 45 + - button "Copy" + - text: streamed-marker-line diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json index 386615f059..9ea5d0c61e 100644 --- a/apps/web/tsconfig.json +++ b/apps/web/tsconfig.json @@ -90,6 +90,7 @@ "tests/subagent-interrupt-ui.e2e.ts", "tests/sidebar-subagent-activity.e2e.ts", "tests/background-job-list.e2e.ts", + "tests/live-activity-stream.e2e.ts", "tests/bash-abort-row.e2e.ts", "tests/skill-tool-row.e2e.ts", "tests/turn-tail-actions.e2e.ts", diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index 82e57fd2f7..a7e83a6223 100644 --- a/docs/architecture.i18n.yaml +++ b/docs/architecture.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 docs/architecture.md -architecture.md: add615c252948adab8db7dec7059f94b8f45e52c -architecture.zh.md: 48baf14d6a29e5ef77e6e47f4d9fa9adc4e9e748 +architecture.md: cfa1dee639ebc4ae60db13d11d246c2ffa103cd0 +architecture.zh.md: 0139f575a2721a429ac6b241638c031c68f8530f diff --git a/docs/architecture.md b/docs/architecture.md index add615c252..cfa1dee639 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -127,6 +127,7 @@ New behavior attaches to a documented extension point. Changing the loop itself | Add persistent terminal execution | register a `ctx.terminals` backend plus `dsh-tool-terminal` | | Add a human command | register on `ctx.commands`; it dispatches without a model turn | | Add background work | register on `ctx.jobs`; `job_*` tools collect or stop it | +| Stream live output to observers | open a `ctx.activities` handle; the Web client renders it | | Start a Session from an external webhook | register a trusted rule on `ctx.webhookRuntime` and mount a provider adapter | | Add filesystem access or policy | register a `ctx.fs` provider or listen to `fs/*` events | | Confine spawned processes | use a `ctx.sandbox` backend; consumers wrap argv before spawning | diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index 48baf14d6a..0139f575a2 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -131,6 +131,7 @@ seam 正是替换一个提供方就能改变整个产品的原因。文件系统 | 添加持久化终端执行 | 注册 `ctx.terminals` 后端和 `dsh-tool-terminal` | | 添加用户命令 | 在 `ctx.commands` 上注册;它无需模型轮次即可分派 | | 添加后台工作 | 在 `ctx.jobs` 上注册;`job_*` 工具负责收集或停止 | +| 向观察者流式输出 | 打开一个 `ctx.activities` 句柄;Web 客户端负责渲染 | | 从外部 webhook 启动 Session | 在 `ctx.webhookRuntime` 上注册可信规则,并挂载提供方适配器 | | 添加文件系统访问或策略 | 注册 `ctx.fs` 提供方,或监听 `fs/*` 事件 | | 限制所启动的进程 | 使用 `ctx.sandbox` 后端;消费方在启动进程前包装 argv | diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml index d7e1c70e5a..c1a409d2e8 100644 --- a/docs/capability-seams.i18n.yaml +++ b/docs/capability-seams.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 docs/capability-seams.md -capability-seams.md: 0994b186f7daa6afbff0f1484216e55fc79170ff -capability-seams.zh.md: 48aa0a5353bba8d56f63abfcfc4cd2c601569cb6 +capability-seams.md: de9b8e1eb68dd7bf110609044dbf96a93a59adc5 +capability-seams.zh.md: 0b8e93fd3f0b08770652ca735966649b35f98330 diff --git a/docs/capability-seams.md b/docs/capability-seams.md index 0994b186f7..de9b8e1eb6 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -40,6 +40,8 @@ flowchart LR pkg_apiproxy["apiproxy"] pkg_api_workspace_controller["api-workspace-controller"] svc_workspaceController["ctx.workspaceController
Host Workspace Remote controller"] + pkg_api_activity_controller["api-activity-controller"] + svc_activityController["ctx.activityController
Host Activity Remote controller"] svc_invariants["ctx.invariants
Package-owned invariant registry"] pkg_scope["scope"] pkg_typert_registry["typert-registry"] @@ -178,6 +180,11 @@ flowchart LR svc_jobs["ctx.jobs
Background job registry"] pkg_jobs_local["jobs-local"] pkg_tool_jobs["tool-jobs"] + pkg_activity["activity"] + svc_activities["ctx.activities
Live activity observation registry"] + pkg_activity_local["activity-local"] + pkg_tool_workflow["tool-workflow"] + pkg_activity_controller["activity-controller"] pkg_web["web"] svc_web["ctx.web
Web access provider registry"] pkg_web_search_exa["web-search-exa"] @@ -201,7 +208,6 @@ flowchart LR pkg_workflow["workflow"] svc_workflowEngine["ctx.workflowEngine
Workflow script engine"] pkg_workflow_worker_thread["workflow-worker-thread"] - pkg_tool_workflow["tool-workflow"] pkg_webhook["webhook"] svc_webhookRuntime["ctx.webhookRuntime
Webhook rule runtime"] pkg_webhook_github["webhook-github"] @@ -214,11 +220,14 @@ flowchart LR svc_dynamicCordisRunner["ctx.dynamicCordisRunner
Dynamic Cordis package host runner"] svc_cordisInspect["ctx.cordisInspect
Dynamic Cordis inspect registry"] pkg_acp --> svc_approval + pkg_activity --> svc_activities + pkg_activity_local --> svc_activities pkg_agent --> svc_agents pkg_agent_default_model --> svc_agentDefaultModel pkg_agent_loop --> svc_agentLoop pkg_agent_presets --> svc_agentPresets pkg_agent_team --> svc_agentTeams + pkg_api_activity_controller --> svc_activityController pkg_api_gateway --> svc_typertGateway pkg_api_session_controller --> svc_sessionController pkg_api_workspace_controller --> svc_workspaceController @@ -325,6 +334,10 @@ flowchart LR pkg_workflow --> svc_workflowEngine pkg_workflow_worker_thread --> svc_workflowEngine pkg_workspace --> svc_workspaceRegistry + svc_activities --> pkg_activity_controller + svc_activities --> pkg_tool_bash + svc_activities --> pkg_tool_pwsh + svc_activities --> pkg_tool_workflow svc_agentDefaultModel --> pkg_headless svc_agentDefaultModel --> pkg_host_apiproxy svc_agentLoop --> pkg_agent_spine_demo @@ -456,6 +469,7 @@ flowchart LR | `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), `subagent-inprocess`, [`invariants`](../packages/runtime-diagnostics/invariants), [`message-feedback`](../packages/feedback/message-feedback) | - | Owns append-only Session instances and emits the durable session event feed. | | `ctx.sessionController` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | `apiproxy` | - | Owns Session commands, cold reads, durable-event following, live control state, and Agent activation policy; apiProxy reuses its inspection and Agent-resolution operations for Session-aware domains. | | `ctx.workspaceController` | `core` | [`api-workspace-controller`](../packages/api/workspace-controller) | - | - | - | Owns Workspace commands and reconnect-safe Workspace state delivery through the generated Remote namespace. | +| `ctx.activityController` | `core` | [`api-activity-controller`](../packages/api/activity-controller) | - | - | - | Owns the live-activity roster stream and per-activity non-consuming output observation through the generated Remote namespace. | | `ctx.invariants` | `core` | [`invariants`](../packages/runtime-diagnostics/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. | | `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges. | | `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier. | @@ -501,6 +515,7 @@ flowchart LR | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process), [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. | | `ctx.agentTeams` | `core` | `agent-team` | - | `tool-agent-team` | - | Owns the implicit-root roster, durable peer mailbox, shared task DAG, and continuable-child lifecycle; tool-agent-team contributes the scoped model policy and controls. | | `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-jobs is the model-facing controller that reads, lists, and kills it; jobs-local is the process-local registry. | +| `ctx.activities` | `seam` | [`activity`](../packages/activity/activity) | [`activity-local`](../packages/activity/activity-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`tool-workflow`](../packages/workflow/tool-workflow), `activity-controller` | - | Producers mirror live output and status into non-consuming offset-addressed streams; activity-controller serves them to browsers, and the model-facing paths (jobs cursors, tool results) stay untouched. | | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-http`](../packages/web/web-fetch-http) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. | | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | The backend saves oversized tool text and returns a model-facing locator plus retrieval hint; spill-policy is the tools/post-execute consumer that decides when to spill. | | `ctx.directoryPicker` | `seam` | `directory-picker` | `directory-picker-native`, `directory-picker-browse` | `apiproxy` | - | Discriminated interaction capability: the native backend opens one OS chooser on the host display, the browse backend serves listing/creation primitives for the in-app browser; dual-face backends fill ui-workspace directory-flow slots from their browser halves (no wire advertisement). | diff --git a/docs/capability-seams.zh.md b/docs/capability-seams.zh.md index 48aa0a5353..0b8e93fd3f 100644 --- a/docs/capability-seams.zh.md +++ b/docs/capability-seams.zh.md @@ -42,6 +42,8 @@ flowchart LR pkg_apiproxy["apiproxy"] pkg_api_workspace_controller["api-workspace-controller"] svc_workspaceController["ctx.workspaceController
Host Workspace Remote controller"] + pkg_api_activity_controller["api-activity-controller"] + svc_activityController["ctx.activityController
Host Activity Remote controller"] svc_invariants["ctx.invariants
Package-owned invariant registry"] pkg_scope["scope"] pkg_typert_registry["typert-registry"] @@ -180,6 +182,11 @@ flowchart LR svc_jobs["ctx.jobs
Background job registry"] pkg_jobs_local["jobs-local"] pkg_tool_jobs["tool-jobs"] + pkg_activity["activity"] + svc_activities["ctx.activities
Live activity observation registry"] + pkg_activity_local["activity-local"] + pkg_tool_workflow["tool-workflow"] + pkg_activity_controller["activity-controller"] pkg_web["web"] svc_web["ctx.web
Web access provider registry"] pkg_web_search_exa["web-search-exa"] @@ -203,7 +210,6 @@ flowchart LR pkg_workflow["workflow"] svc_workflowEngine["ctx.workflowEngine
Workflow script engine"] pkg_workflow_worker_thread["workflow-worker-thread"] - pkg_tool_workflow["tool-workflow"] pkg_webhook["webhook"] svc_webhookRuntime["ctx.webhookRuntime
Webhook rule runtime"] pkg_webhook_github["webhook-github"] @@ -216,11 +222,14 @@ flowchart LR svc_dynamicCordisRunner["ctx.dynamicCordisRunner
Dynamic Cordis package host runner"] svc_cordisInspect["ctx.cordisInspect
Dynamic Cordis inspect registry"] pkg_acp --> svc_approval + pkg_activity --> svc_activities + pkg_activity_local --> svc_activities pkg_agent --> svc_agents pkg_agent_default_model --> svc_agentDefaultModel pkg_agent_loop --> svc_agentLoop pkg_agent_presets --> svc_agentPresets pkg_agent_team --> svc_agentTeams + pkg_api_activity_controller --> svc_activityController pkg_api_gateway --> svc_typertGateway pkg_api_session_controller --> svc_sessionController pkg_api_workspace_controller --> svc_workspaceController @@ -327,6 +336,10 @@ flowchart LR pkg_workflow --> svc_workflowEngine pkg_workflow_worker_thread --> svc_workflowEngine pkg_workspace --> svc_workspaceRegistry + svc_activities --> pkg_activity_controller + svc_activities --> pkg_tool_bash + svc_activities --> pkg_tool_pwsh + svc_activities --> pkg_tool_workflow svc_agentDefaultModel --> pkg_headless svc_agentDefaultModel --> pkg_host_apiproxy svc_agentLoop --> pkg_agent_spine_demo @@ -458,6 +471,7 @@ flowchart LR | `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), `subagent-inprocess`, [`invariants`](../packages/runtime-diagnostics/invariants), [`message-feedback`](../packages/feedback/message-feedback) | - | 拥有仅追加的 Session 实例,并发出持久的会话事件流。 | | `ctx.sessionController` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | `apiproxy` | - | 负责 Session 命令、冷读取、持久事件跟随、实时控制状态与 Agent 激活策略;apiProxy 在需要 Session 上下文的领域中复用其检查和 Agent 解析操作。 | | `ctx.workspaceController` | `core` | [`api-workspace-controller`](../packages/api/workspace-controller) | - | - | - | 通过生成的 Remote namespace 负责 Workspace 命令和可在重连后收敛的 Workspace 状态投递。 | +| `ctx.activityController` | `core` | [`api-activity-controller`](../packages/api/activity-controller) | - | - | - | 通过生成的 Remote namespace 负责实时活动 roster 流与逐 activity 的非消费输出观察。 | | `ctx.invariants` | `core` | [`invariants`](../packages/runtime-diagnostics/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | 配套子路径注册所属包本地的检查;该服务负责选择、唯一性、子 fiber,以及标明所属包的失败。 | | `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | 插件直接或通过 dsh-typert-loader 注册实时 zod 贡献;API 网关消费调用描述符和提供方,其他运行时消费方则在各自边界查询 schema 与反射元数据。 | | `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | 将生成的 Remote 描述符与实时 Cordis 服务关联,解析已注册的身份,并通过共享的 Connection RPC 载体提供一元调用。 | @@ -503,6 +517,7 @@ flowchart LR | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process), [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | 提供方实现传输;该服务还负责可选的、基于 Activation 的延续编排,tool-subagent 选择一次性或可延续委派,tool-subagent-control 传递后续消息,而 tool-ralph 要求一条全新的结构化输出路由。 | | `ctx.agentTeams` | `core` | `agent-team` | - | `tool-agent-team` | - | 负责隐式 Root roster、持久 peer mailbox、共享任务 DAG 与 continuable child 生命周期;tool-agent-team 提供作用域化模型策略和控制工具。 | | `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs) | - | 生产方(后台 bash、PTY 发送和 subagent 委派)登记正在运行的工作;tool-jobs 是面向模型的控制器,用于读取、列出和终止这些工作;jobs-local 是进程本地注册表。 | +| `ctx.activities` | `seam` | [`activity`](../packages/activity/activity) | [`activity-local`](../packages/activity/activity-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`tool-workflow`](../packages/workflow/tool-workflow), `activity-controller` | - | 生产方把实时输出与状态镜像进非消费、按 offset 寻址的流;activity-controller 把它们送达浏览器,模型侧路径(jobs 游标、工具结果)不受影响。 | | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-http`](../packages/web/web-fetch-http) | [`tool-web`](../packages/web/tool-web) | - | 搜索和抓取提供方注册到同一个 ctx.web seam;tool-web 负责稳定的面向模型名称。 | | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | 后端保存过大的工具文本,并返回面向模型的定位信息和取回提示;spill-policy 是 tools/post-execute 消费方,负责决定何时 spill。 | | `ctx.directoryPicker` | `seam` | `directory-picker` | `directory-picker-native`, `directory-picker-browse` | `apiproxy` | - | 带判别标记的交互能力:原生后端在 Host 显示设备上打开一个操作系统选择器,浏览后端为应用内浏览器提供列表与创建原语;双端后端通过其浏览器侧填充 ui-workspace 目录流程的 slot(不通过协议发布)。 | diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index 9ba399370d..6c2e824a55 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.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 docs/config-catalog.md -config-catalog.md: 6494070f6204ce6130e22d6f71ddbfd18fdc69dd -config-catalog.zh.md: da19d854ca520425a799cb699238a7dca05a90da +config-catalog.md: 0bf883bbfde80377602be90bd913c32f1b320f63 +config-catalog.zh.md: 381319465dab9dafeecaacf704caba8bab7455f3 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 6494070f62..0bf883bbfd 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -33,6 +33,22 @@ Depends on: `Stream` (`@agentclientprotocol/sdk`) Source: [`packages/acp/acp/src/index.ts:74`](../packages/acp/acp/src/index.ts) + + +## `@deepseek-ai/dsh-activity-local` + +```ts config-catalog +/** Configuration for the process-local observation registry. */ +export interface Config { + /** Live output retention per activity in UTF-8 bytes; omission defaults to 262144. */ + retainBytes?: number + /** Output retention kept after an activity settles, in UTF-8 bytes; omission defaults to 16384. */ + settledRetainBytes?: number +} +``` + +Source: [`packages/activity/activity-local/src/index.ts:31`](../packages/activity/activity-local/src/index.ts) + ## `@deepseek-ai/dsh-agent-default-model` @@ -276,6 +292,24 @@ Depends on: [`ToolPresentationMode`](subsystems/tools.md) Source: [`packages/core/agent-tool-presentation/src/index.ts:38`](../packages/core/agent-tool-presentation/src/index.ts) + + +## `@deepseek-ai/dsh-api-activity-controller` + +Requires: `typert` + +```ts config-catalog +/** Configuration for the Activity Remote owner. */ +export interface Config { + /** Coalescing window after new output before an observation read, in milliseconds (default 100). */ + flushMs?: number + /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */ + maxFrameBytes?: number +} +``` + +Source: [`packages/api/activity-controller/src/index.ts:26`](../packages/api/activity-controller/src/index.ts) + ## `@deepseek-ai/dsh-api-session-controller` @@ -2559,10 +2593,12 @@ Requires: `tools` · `shell` · `systemPrompt` · `shellEnv` export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean + /** Poll cadence for mirroring background output into `ctx.activities`, in milliseconds (default 150). */ + activityPollMs?: number } ``` -Source: [`packages/shell/tool-bash/src/index.ts:34`](../packages/shell/tool-bash/src/index.ts) +Source: [`packages/shell/tool-bash/src/index.ts:36`](../packages/shell/tool-bash/src/index.ts) @@ -2724,10 +2760,12 @@ Requires: `tools` · `shell` · `systemPrompt` · `shellEnv` export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean + /** Poll cadence for mirroring background output into `ctx.activities`, in milliseconds (default 150). */ + activityPollMs?: number } ``` -Source: [`packages/shell/tool-pwsh/src/index.ts:52`](../packages/shell/tool-pwsh/src/index.ts) +Source: [`packages/shell/tool-pwsh/src/index.ts:61`](../packages/shell/tool-pwsh/src/index.ts) @@ -3004,7 +3042,7 @@ export interface Config { } ``` -Source: [`packages/workflow/tool-workflow/src/index.ts:33`](../packages/workflow/tool-workflow/src/index.ts) +Source: [`packages/workflow/tool-workflow/src/index.ts:34`](../packages/workflow/tool-workflow/src/index.ts) @@ -3303,6 +3341,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co - `@deepseek-ai/dsh-authorization` — requires `credentials` ([`packages/credentials/authorization/src/index.ts`](../packages/credentials/authorization/src/index.ts)) - `@deepseek-ai/dsh-client-locale` ([`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts)) - `@deepseek-ai/dsh-client-modules` — requires `webServer` · `loader` ([`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts)) +- `@deepseek-ai/dsh-client-ui-activity` ([`packages/client/ui-activity/src/index.ts`](../packages/client/ui-activity/src/index.ts)) - `@deepseek-ai/dsh-client-ui-agent-preset` ([`packages/client/ui-agent-preset/src/index.ts`](../packages/client/ui-agent-preset/src/index.ts)) - `@deepseek-ai/dsh-client-ui-approval` ([`packages/client/ui-approval/src/index.ts`](../packages/client/ui-approval/src/index.ts)) - `@deepseek-ai/dsh-client-ui-attachment` ([`packages/client/ui-attachment/src/index.ts`](../packages/client/ui-attachment/src/index.ts)) @@ -3376,6 +3415,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co Abstract service classes — a deployment loads a concrete implementation package instead ([capability seams](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)). +- `@deepseek-ai/dsh-activity` — abstract `ActivityRegistry` ([`packages/activity/activity/src/index.ts`](../packages/activity/activity/src/index.ts)) - `@deepseek-ai/dsh-attachment` — abstract `AttachmentStore` ([`packages/attachment/attachment/src/index.ts`](../packages/attachment/attachment/src/index.ts)) - `@deepseek-ai/dsh-code-runtime` — abstract `CodeRuntime` ([`packages/code-runtime/code-runtime/src/index.ts`](../packages/code-runtime/code-runtime/src/index.ts)) - `@deepseek-ai/dsh-compaction` — abstract `CompactionEngine` ([`packages/compaction/compaction/src/index.ts`](../packages/compaction/compaction/src/index.ts)) diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index da19d854ca..381319465d 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -35,6 +35,22 @@ export interface AcpConfig { 来源:[`packages/acp/acp/src/index.ts:74`](../packages/acp/acp/src/index.ts) + + +## `@deepseek-ai/dsh-activity-local` + +```ts config-catalog +/** Configuration for the process-local observation registry. */ +export interface Config { + /** Live output retention per activity in UTF-8 bytes; omission defaults to 262144. */ + retainBytes?: number + /** Output retention kept after an activity settles, in UTF-8 bytes; omission defaults to 16384. */ + settledRetainBytes?: number +} +``` + +来源:[`packages/activity/activity-local/src/index.ts:31`](../packages/activity/activity-local/src/index.ts) + ## `@deepseek-ai/dsh-agent-default-model` @@ -278,6 +294,24 @@ export interface Config { 来源:[`packages/core/agent-tool-presentation/src/index.ts:38`](../packages/core/agent-tool-presentation/src/index.ts) + + +## `@deepseek-ai/dsh-api-activity-controller` + +需要:`typert` + +```ts config-catalog +/** Configuration for the Activity Remote owner. */ +export interface Config { + /** Coalescing window after new output before an observation read, in milliseconds (default 100). */ + flushMs?: number + /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */ + maxFrameBytes?: number +} +``` + +来源:[`packages/api/activity-controller/src/index.ts:26`](../packages/api/activity-controller/src/index.ts) + ## `@deepseek-ai/dsh-api-session-controller` @@ -2561,10 +2595,12 @@ export type TokenMeterConfig = Record export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean + /** Poll cadence for mirroring background output into `ctx.activities`, in milliseconds (default 150). */ + activityPollMs?: number } ``` -来源:[`packages/shell/tool-bash/src/index.ts:34`](../packages/shell/tool-bash/src/index.ts) +来源:[`packages/shell/tool-bash/src/index.ts:36`](../packages/shell/tool-bash/src/index.ts) @@ -2726,10 +2762,12 @@ export interface Config { export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean + /** Poll cadence for mirroring background output into `ctx.activities`, in milliseconds (default 150). */ + activityPollMs?: number } ``` -来源:[`packages/shell/tool-pwsh/src/index.ts:52`](../packages/shell/tool-pwsh/src/index.ts) +来源:[`packages/shell/tool-pwsh/src/index.ts:60`](../packages/shell/tool-pwsh/src/index.ts) @@ -3305,6 +3343,7 @@ export interface Config { - `@deepseek-ai/dsh-authorization` — 需要 `credentials`([`packages/credentials/authorization/src/index.ts`](../packages/credentials/authorization/src/index.ts)) - `@deepseek-ai/dsh-client-locale`([`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts)) - `@deepseek-ai/dsh-client-modules` — 需要 `webServer` · `loader`([`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts)) +- `@deepseek-ai/dsh-client-ui-activity`([`packages/client/ui-activity/src/index.ts`](../packages/client/ui-activity/src/index.ts)) - `@deepseek-ai/dsh-client-ui-agent-preset`([`packages/client/ui-agent-preset/src/index.ts`](../packages/client/ui-agent-preset/src/index.ts)) - `@deepseek-ai/dsh-client-ui-approval`([`packages/client/ui-approval/src/index.ts`](../packages/client/ui-approval/src/index.ts)) - `@deepseek-ai/dsh-client-ui-attachment`([`packages/client/ui-attachment/src/index.ts`](../packages/client/ui-attachment/src/index.ts)) @@ -3378,6 +3417,7 @@ export interface Config { 抽象服务类——部署时应改为加载具体的实现包(参见[能力 seam](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md))。 +- `@deepseek-ai/dsh-activity` — 抽象 `ActivityRegistry`([`packages/activity/activity/src/index.ts`](../packages/activity/activity/src/index.ts)) - `@deepseek-ai/dsh-attachment` — 抽象 `AttachmentStore`([`packages/attachment/attachment/src/index.ts`](../packages/attachment/attachment/src/index.ts)) - `@deepseek-ai/dsh-code-runtime` — 抽象 `CodeRuntime`([`packages/code-runtime/code-runtime/src/index.ts`](../packages/code-runtime/code-runtime/src/index.ts)) - `@deepseek-ai/dsh-compaction` — 抽象 `CompactionEngine`([`packages/compaction/compaction/src/index.ts`](../packages/compaction/compaction/src/index.ts)) diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml index 33c536f50a..b48dba34e8 100644 --- a/docs/event-producer-consumer.i18n.yaml +++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md -event-producer-consumer.md: 4ab1275e9309e150504d6a3bdd80792bb1a49ea1 -event-producer-consumer.zh.md: 8d8a401bfdccc74d5774ce5ce7ceac2c548f6c72 +event-producer-consumer.md: ad9a32ed1fd479d1cd14422333f0cd5b6845e55f +event-producer-consumer.zh.md: 783f524b8b31bfcd80237b10f078ed6a27ce13f2 diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 4ab1275e93..ad9a32ed1f 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -69,8 +69,8 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:79`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) | | `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:68`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) | | `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:89`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) | -| `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:58`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | -| `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:51`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | +| `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:58`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow) | +| `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:51`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow) | | `workflow/start` | `emit` | [`packages/workflow/workflow/src/index.ts:43`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) | ## Non-harness or undeclared event strings seen in package source diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md index 8d8a401bfd..783f524b8b 100644 --- a/docs/event-producer-consumer.zh.md +++ b/docs/event-producer-consumer.zh.md @@ -71,8 +71,8 @@ | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:79`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) | | `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:68`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) | | `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:89`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) | -| `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:58`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | -| `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:51`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | +| `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:58`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow) | +| `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:51`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow) | | `workflow/start` | `emit` | [`packages/workflow/workflow/src/index.ts:43`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) | ## 包源码中出现的非 harness 或未声明事件字符串 diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml index e43820301d..c7bb24dd77 100644 --- a/docs/subsystems/README.i18n.yaml +++ b/docs/subsystems/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/subsystems/README.md -README.md: 2b277650c4b9e320183f75845d68f922b31a522e -README.zh.md: 2279857e0d58cb36e8027c196075622344d705ae +README.md: b41c74e46e43ca2fea378ac7e9988136a6ee61ee +README.zh.md: fa4fb55034450bfc5f537ea1a2c0aaccfba469de diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md index 2b277650c4..b41c74e46e 100644 --- a/docs/subsystems/README.md +++ b/docs/subsystems/README.md @@ -44,6 +44,7 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures | [spill.md](spill.md) | the spill storage seam: `SaveTextSpill`, `SpillOwner`/`SpillSource`, `SpillRef`, the branded `SpillLocator` | | [workflow.md](workflow.md) | the workflow seam: `WorkflowStartRequest`, `WorkflowMeta`, `WorkflowRun`/`Result`, the `workflow/*` event payloads, `WorkflowError` fatality | | [jobs.md](jobs.md) | the background-job runtime: branded `JobId`s, the producer contract, consumer views, and `ctx.jobs` service behavior | +| [activity.md](activity.md) | live activity observation: branded `ActivityId`s, the producer handle, non-consuming offset reads, and the wire streams | | [permission-presets.md](permission-presets.md) | the permission-preset layer: `PresetSpec`/`PresetOption`, the derived `custom` state, the log-only `permission/preset` event | | [plan.md](plan.md) | plan mode: the log-only `plan/mode` state, pending-selection flush, `PlanModeConfig`, the `exit_plan_mode` review arc | | [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract | diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md index 2279857e0d..fa4fb55034 100644 --- a/docs/subsystems/README.zh.md +++ b/docs/subsystems/README.zh.md @@ -44,6 +44,7 @@ | [spill.md](spill.zh.md) | spill 存储 seam:`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` | | [workflow.md](workflow.zh.md) | 工作流 seam:`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 | | [jobs.md](jobs.zh.md) | 后台任务运行时:品牌化 `JobId`、producer 约定、消费方视图和 `ctx.jobs` 服务行为 | +| [activity.md](activity.zh.md) | 实时活动观察:品牌化 `ActivityId`、生产者句柄、非消费 offset 读取与 wire 流 | | [permission-presets.md](permission-presets.zh.md) | 权限预设层:`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 | | [plan.md](plan.zh.md) | 计划模式:仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 | | [invariants.md](invariants.zh.md) | 运行时不变式注册表:选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件约定 | diff --git a/docs/subsystems/activity.i18n.yaml b/docs/subsystems/activity.i18n.yaml new file mode 100644 index 0000000000..cf285e6ba7 --- /dev/null +++ b/docs/subsystems/activity.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 docs/subsystems/activity.md +activity.md: 000bdc30be05eb17d670367df3fd214e7d0af7f3 +activity.zh.md: 1fc79e9d596351a1f818ea83c15d1b5082689b79 diff --git a/docs/subsystems/activity.md b/docs/subsystems/activity.md new file mode 100644 index 0000000000..000bdc30be --- /dev/null +++ b/docs/subsystems/activity.md @@ -0,0 +1,141 @@ +# Live Activity Observation + +English | [中文](activity.zh.md) + +Types shared by streaming-output producers, `ctx.activities`, and the observation consumers. The [observation-seam Agent Note](../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md) owns the design; this page records the cross-package vocabulary from [`packages/activity/activity/src/types.ts`](../../packages/activity/activity/src/types.ts) and the wire frames from [`packages/api/activity-controller/src/types.ts`](../../packages/api/activity-controller/src/types.ts). + +An **activity** is one observable unit of long-running work: an append-only bounded output stream plus live status. The registry is a pure observation plane — it starts nothing, cancels nothing, and is invisible to the model. Producers keep their execution resources and their model-facing surfaces (`ctx.jobs` consuming cursors, tool results); observers read non-consumingly at absolute byte offsets, so any number of them coexist with the model's single consuming cursor. + +## Ids, kinds, and correlation + +`ActivityId` is a [branded id](core.md#branded-ids) generated as `-N`; visibility relies on owner authorization, not id secrecy. `ActivityKindMap` is merge-extensible (`bash` seeded; `pwsh` and `workflow` merged by their producers). `ActivityCorrelation` links one activity to the `CallId` that started the work and the `JobId` carrying its model-facing control surface, so a consumer attaches the stream to an existing card or row without guessing from labels. + +## Producer face + +`open(spec)` returns an `ActivityHandle` with synchronous `append(text, { channel?, gapBefore? })`, `updateDetail(detail)`, and first-wins `end(outcome)`. Offsets advance by each chunk's UTF-8 byte length; `gapBefore` marks producer-side loss so a discontinuity stays visible. After `end` — including a teardown force-end — `append` and `updateDetail` log and drop rather than throw, so a producer's trailing flush cannot break its own teardown. + +`pumpActivityOutput(handle, sources, { pollMs, done })` adapts pull substrates: it copies each non-consuming offset reader (the subprocess `readFrom(fromByte)` family, re-exposed on `ShellProcess.observed`) into the handle at a bounded cadence and drains once more after `done` settles. Push-natural producers (the workflow tool's run mirror) append directly. + +## Observation + +`read(id, from, caller?)` returns the retained chunks overlapping `[from, total)` and the resume offset `next`, consuming nothing. Offsets stay absolute across eviction: `outputEarliest` on the snapshot names the oldest retained byte, and a read below it is `lossy: true`, never an error. Retention is provider policy ([`dsh-activity-local`](../../packages/activity/activity-local/README.md): `retainBytes` live, trimmed to `settledRetainBytes` at settlement). + +Two effect-scoped listener families deliver owner-relative on the jobs-registry terms: `onActivitiesChanged` fires per visible-set change (open, detail, settlement, removal) so consumers re-read whole rows, and `onOutput` signals stream advancement (append or settlement) carrying only the id, so each consumer reads from its own cursor. + +## Wire transport + +[`dsh-api-activity-controller`](../../packages/api/activity-controller/README.md) exposes the plane to browsers as two Remote streams: `activity.control` (baseline plus whole-bucket roster replacement frames) and `activity.observe` (one `opened` anchor, coalesced `output` frames, then the terminal `status` on the same stream, after which the generation closes). Output frames are transient — durable history stays with the producers' tool results, exactly as the [web job display decision](../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md) requires. [`dsh-client-ui-activity`](../../packages/client/ui-activity/README.md) renders the roster in the session header and opens observation streams only while a panel is expanded. + + + + + +## Cordis API + +Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md). + + + +### `ctx.activities` — `ActivityRegistry` (abstract seam) + +Abstract streaming-output registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.activities` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior). + +Implementations must honor these semantics: + +- Observation never consumes. Any number of readers hold their own absolute byte offsets; a read changes no cursor and no producer state, so the model-facing paths (`ctx.jobs.read()`, tool results) are unaffected. +- Records outlive producer fibers. Owner disposal ends still-open records and removes them; service disposal ends and clears everything. Neither awaits a producer — the registry owns no execution resource. +- Retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement trims retention to the settled cap. +- Listener delivery is owner-relative: a listener registered from an unscoped context — a host composition's own carrier — sees every owner, while one registered under an agent composition's scope sees exactly the agents composed under it. Every listener is contained. + +```ts cordis-catalog +/** + * Validate the spec, attach owner cleanup, and atomically register one + * activity. A rejection leaves no id; after return the producer owns the + * handle and the visible set has changed. + * @param spec - activity identity, owner, and correlation. + * @returns the producer face of the registered activity. + */ +abstract open(spec: ActivityOpen): ActivityHandle + +/** + * List caller-owned and unowned activities in registration order without + * exposing another session's labels or output. + * @param caller - reading agent; a non-agent caller sees only unowned activities. + * @returns fresh snapshots. + */ +abstract list(caller?: Agent): ActivitySnapshot[] + +/** + * Return a fresh snapshot. Throws for an unknown or foreign activity. + * @param id - activity to look up. + * @param caller - reading agent checked against the owner. + * @returns a fresh snapshot. + */ +abstract get(id: ActivityId, caller?: Agent): ActivitySnapshot + +/** + * Read retained output from an absolute byte offset without consuming it. + * Resume by passing a previous read's `next`; a foreign offset inside a + * retained chunk returns that whole chunk (its `at` may precede `from`). + * Throws for an unknown or foreign activity or a negative or non-integer + * offset. + * @param id - activity to read. + * @param from - absolute byte offset to read from (0 for the retained head). + * @param caller - reading agent checked against the owner. + * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. + */ +abstract read(id: ActivityId, from: number, caller?: Agent): ActivityRead + +/** + * Register an effect-scoped observer of visible-set changes: opening, + * detail updates, settlement, owner-disposal removal, and the emptying that + * service disposal commits — so an observer re-reads rather than + * accumulating deltas. Listeners are contained and never awaited. + * @param listener - receives the owner whose visible set changed, or + * `undefined` when an unowned activity changed and every caller's set did. + * @returns disposer that unregisters the listener. + */ +abstract onActivitiesChanged(listener: ActivitiesChangedListener): () => void + +/** + * Register an effect-scoped observer of stream advancement — one signal per + * committed append and one at settlement, carrying only the activity id. + * A consumer schedules a {@link read} from its own cursor; the registry + * never pushes payloads. Listeners are contained and never awaited. + * @param listener - receives the id whose stream advanced. + * @returns disposer that unregisters the listener. + */ +abstract onOutput(listener: ActivityOutputListener): () => void +``` + +Types: [Agent](core.md) + +Source: [`packages/activity/activity/src/index.ts`](../../packages/activity/activity/src/index.ts) + + + +### `ctx.activityController` — `ActivityController` + +Host service backing the generated `ctx.remote.activity` namespace. + +```ts cordis-catalog +/** + * Stream a complete roster baseline followed by whole-bucket replacements. + * @param signal - generation cancellation. + * @returns baseline followed by per-owner roster replacement frames. + */ +@Remote({ mode: 'stream' }) control(signal: AbortSignal): AsyncIterable + +/** + * Stream one activity's retained output from an absolute byte offset, then + * its terminal status once settled and drained. Non-consuming: the + * model-facing cursors never observe these reads. + * @param request - target activity and optional resume offset. + * @param signal - generation cancellation. + * @returns anchor, coalesced output frames, and the terminal status. + */ +@Remote({ mode: 'stream' }) observe(request: ActivityObserveRequest, signal: AbortSignal): AsyncIterable +``` + +Source: [`packages/api/activity-controller/src/index.ts`](../../packages/api/activity-controller/src/index.ts) + diff --git a/docs/subsystems/activity.zh.md b/docs/subsystems/activity.zh.md new file mode 100644 index 0000000000..1fc79e9d59 --- /dev/null +++ b/docs/subsystems/activity.zh.md @@ -0,0 +1,141 @@ +# 实时活动观察 + +[English](activity.md) | 中文 + +流式输出生产者、`ctx.activities` 与观察消费者共享的类型。设计归[观察 seam Agent Note](../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md)所有;本页记录 [`packages/activity/activity/src/types.ts`](../../packages/activity/activity/src/types.ts) 的跨包词汇与 [`packages/api/activity-controller/src/types.ts`](../../packages/api/activity-controller/src/types.ts) 的 wire 帧。 + +**activity** 是一个可观察的长时工作单元:一条 append-only 的有界输出流加实时状态。注册表是纯观察面——不启动、不取消任何工作,对模型不可见。生产者保留自己的执行资源与模型面(`ctx.jobs` 消费游标、工具结果);观察者按绝对字节 offset 非消费读取,任意数量的观察者可与模型的单一消费游标共存。 + +## Id、kind 与关联 + +`ActivityId` 是[品牌化 id](core.zh.md#branded-ids),生成为 `-N`;可见性靠 owner 授权而非 id 保密。`ActivityKindMap` 可合并扩展(内置 `bash`;`pwsh` 与 `workflow` 由各自生产者合并)。`ActivityCorrelation` 把一个 activity 关联到发起工作的 `CallId` 与承载其模型控制面的 `JobId`,消费者据此把流挂到已有卡片或行上,不必靠 label 猜。 + +## 生产者面 + +`open(spec)` 返回 `ActivityHandle`:同步的 `append(text, { channel?, gapBefore? })`、`updateDetail(detail)` 与 first-wins 的 `end(outcome)`。offset 按每个 chunk 的 UTF-8 字节长度推进;`gapBefore` 标记生产者侧丢失,让断点保持可见。`end` 之后——包括 teardown 强制 end——`append` 与 `updateDetail` 记日志后丢弃而不抛错,生产者的收尾 flush 不会砸掉自己的 teardown。 + +`pumpActivityOutput(handle, sources, { pollMs, done })` 适配 pull 型底座:把每个非消费 offset 读取器(subprocess 的 `readFrom(fromByte)` 家族,经 `ShellProcess.observed` 复出)按有界节奏复制进句柄,并在 `done` 结算后再排干一次。push 天然的生产者(workflow 工具的运行镜像)直接 append。 + +## 观察 + +`read(id, from, caller?)` 返回与 `[from, total)` 重叠的保留 chunk 及续读 offset `next`,绝不消费。offset 跨淘汰稳定:快照上的 `outputEarliest` 指明最老保留字节,低于它的读取得到 `lossy: true` 而非错误。保留量是 provider 策略([`dsh-activity-local`](../../packages/activity/activity-local/README.zh.md):存活 `retainBytes`,结算时裁到 `settledRetainBytes`)。 + +两个 effect 范围的监听族按 jobs 注册表条款做 owner 相对投递:`onActivitiesChanged` 在每次可见集变化(开启、detail、结算、移除)时触发,消费者整读行;`onOutput` 发出流推进信号(append 或结算),只带 id,各消费者按自己的游标读取。 + +## Wire 传输 + +[`dsh-api-activity-controller`](../../packages/api/activity-controller/README.zh.md) 以两条 Remote 流把观察面暴露给浏览器:`activity.control`(baseline + 整桶 roster 替换帧)与 `activity.observe`(一帧 `opened` 锚点、合并的 `output` 帧、同流的终态 `status`,之后本代关闭)。输出帧是瞬态的——持久历史仍在生产者的工具结果里,与 [web job display 决策](../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md)的要求一致。[`dsh-client-ui-activity`](../../packages/client/ui-activity/README.zh.md) 在会话头部渲染 roster,只在面板展开时打开观察流。 + + + + + +## Cordis API + +Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md). + + + +### `ctx.activities` — `ActivityRegistry` (abstract seam) + +Abstract streaming-output registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.activities` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior). + +Implementations must honor these semantics: + +- Observation never consumes. Any number of readers hold their own absolute byte offsets; a read changes no cursor and no producer state, so the model-facing paths (`ctx.jobs.read()`, tool results) are unaffected. +- Records outlive producer fibers. Owner disposal ends still-open records and removes them; service disposal ends and clears everything. Neither awaits a producer — the registry owns no execution resource. +- Retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement trims retention to the settled cap. +- Listener delivery is owner-relative: a listener registered from an unscoped context — a host composition's own carrier — sees every owner, while one registered under an agent composition's scope sees exactly the agents composed under it. Every listener is contained. + +```ts cordis-catalog +/** + * Validate the spec, attach owner cleanup, and atomically register one + * activity. A rejection leaves no id; after return the producer owns the + * handle and the visible set has changed. + * @param spec - activity identity, owner, and correlation. + * @returns the producer face of the registered activity. + */ +abstract open(spec: ActivityOpen): ActivityHandle + +/** + * List caller-owned and unowned activities in registration order without + * exposing another session's labels or output. + * @param caller - reading agent; a non-agent caller sees only unowned activities. + * @returns fresh snapshots. + */ +abstract list(caller?: Agent): ActivitySnapshot[] + +/** + * Return a fresh snapshot. Throws for an unknown or foreign activity. + * @param id - activity to look up. + * @param caller - reading agent checked against the owner. + * @returns a fresh snapshot. + */ +abstract get(id: ActivityId, caller?: Agent): ActivitySnapshot + +/** + * Read retained output from an absolute byte offset without consuming it. + * Resume by passing a previous read's `next`; a foreign offset inside a + * retained chunk returns that whole chunk (its `at` may precede `from`). + * Throws for an unknown or foreign activity or a negative or non-integer + * offset. + * @param id - activity to read. + * @param from - absolute byte offset to read from (0 for the retained head). + * @param caller - reading agent checked against the owner. + * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. + */ +abstract read(id: ActivityId, from: number, caller?: Agent): ActivityRead + +/** + * Register an effect-scoped observer of visible-set changes: opening, + * detail updates, settlement, owner-disposal removal, and the emptying that + * service disposal commits — so an observer re-reads rather than + * accumulating deltas. Listeners are contained and never awaited. + * @param listener - receives the owner whose visible set changed, or + * `undefined` when an unowned activity changed and every caller's set did. + * @returns disposer that unregisters the listener. + */ +abstract onActivitiesChanged(listener: ActivitiesChangedListener): () => void + +/** + * Register an effect-scoped observer of stream advancement — one signal per + * committed append and one at settlement, carrying only the activity id. + * A consumer schedules a {@link read} from its own cursor; the registry + * never pushes payloads. Listeners are contained and never awaited. + * @param listener - receives the id whose stream advanced. + * @returns disposer that unregisters the listener. + */ +abstract onOutput(listener: ActivityOutputListener): () => void +``` + +Types: [Agent](core.zh.md) + +Source: [`packages/activity/activity/src/index.ts`](../../packages/activity/activity/src/index.ts) + + + +### `ctx.activityController` — `ActivityController` + +Host service backing the generated `ctx.remote.activity` namespace. + +```ts cordis-catalog +/** + * Stream a complete roster baseline followed by whole-bucket replacements. + * @param signal - generation cancellation. + * @returns baseline followed by per-owner roster replacement frames. + */ +@Remote({ mode: 'stream' }) control(signal: AbortSignal): AsyncIterable + +/** + * Stream one activity's retained output from an absolute byte offset, then + * its terminal status once settled and drained. Non-consuming: the + * model-facing cursors never observe these reads. + * @param request - target activity and optional resume offset. + * @param signal - generation cancellation. + * @returns anchor, coalesced output frames, and the terminal status. + */ +@Remote({ mode: 'stream' }) observe(request: ActivityObserveRequest, signal: AbortSignal): AsyncIterable +``` + +Source: [`packages/api/activity-controller/src/index.ts`](../../packages/api/activity-controller/src/index.ts) + diff --git a/docs/subsystems/shell.i18n.yaml b/docs/subsystems/shell.i18n.yaml index 1515b4ed7b..4a80f2cea2 100644 --- a/docs/subsystems/shell.i18n.yaml +++ b/docs/subsystems/shell.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 docs/subsystems/shell.md -shell.md: 554adcfb1b37a5e2fe787a78dbb61a1206f80cf9 -shell.zh.md: f15b57cc0050bb8f38d2652ddb9ad0e250568663 +shell.md: 8635290b98a19403cc1839b8262831cb99995fd5 +shell.zh.md: ad8fa3254444e43501bbba09964bcfbd95d56bf9 diff --git a/docs/subsystems/shell.md b/docs/subsystems/shell.md index 554adcfb1b..8635290b98 100644 --- a/docs/subsystems/shell.md +++ b/docs/subsystems/shell.md @@ -192,6 +192,13 @@ interface ShellProcess { * full-stream spill files when available. */ readOutput(): ShellProcessRead + /** + * Non-consuming offset readers over the same captured streams the consuming + * {@link readOutput} cursor drains. Independent observers read here at their + * own offsets without stealing bytes from `readOutput`. Absent when the + * backend cannot expose offset reads; observers then see no stream. + */ + observed?: ShellObservedStreams /** * Kill the process group. Returns false when it had already finished * (no-op); idempotent. diff --git a/docs/subsystems/shell.zh.md b/docs/subsystems/shell.zh.md index f15b57cc00..ad8fa32544 100644 --- a/docs/subsystems/shell.zh.md +++ b/docs/subsystems/shell.zh.md @@ -192,6 +192,13 @@ interface ShellProcess { * full-stream spill files when available. */ readOutput(): ShellProcessRead + /** + * Non-consuming offset readers over the same captured streams the consuming + * {@link readOutput} cursor drains. Independent observers read here at their + * own offsets without stealing bytes from `readOutput`. Absent when the + * backend cannot expose offset reads; observers then see no stream. + */ + observed?: ShellObservedStreams /** * Kill the process group. Returns false when it had already finished * (no-op); idempotent. diff --git a/knip.json b/knip.json index e8dc6139ee..b6ab568c31 100644 --- a/knip.json +++ b/knip.json @@ -117,6 +117,11 @@ "tests/**/*.ts" ] }, + "packages/api/activity-controller": { + "ignoreDependencies": [ + "zod" + ] + }, "packages/api/workspace-controller": { "ignoreDependencies": [ "zod" diff --git a/packages/activity/README.i18n.yaml b/packages/activity/README.i18n.yaml new file mode 100644 index 0000000000..4044dfcfec --- /dev/null +++ b/packages/activity/README.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 packages/activity/README.md +README.md: 1988ca73b4a71095d42f85086d4958eb91bad928 +README.zh.md: b75c7bfcfda6aa829d59d1d46439144bdfaa80e6 diff --git a/packages/activity/README.md b/packages/activity/README.md new file mode 100644 index 0000000000..1988ca73b4 --- /dev/null +++ b/packages/activity/README.md @@ -0,0 +1,14 @@ +# activity/ — streaming-output observation family + +English | [中文](README.zh.md) + +This family gives every long-running producer one non-consuming observation plane: an activity is an append-only bounded output stream plus live status, readable by any number of independent observers at absolute byte offsets while the model-facing paths (`ctx.jobs` cursors, tool results) stay untouched. + +| Package | Role | ctx key | +|---|---|---| +| [`activity/`](activity/README.md) | Defines the observation registry and vocabulary | `ctx.activities` | +| [`activity-local/`](activity-local/README.md) | Implements the in-memory ring-buffer registry | registers on `ctx.activities` | + +The Web transport and client consumers live in [`dsh-api-activity-controller`](../api/activity-controller/README.md) and [`dsh-client-ui-activity`](../client/ui-activity/README.md); background bash/pwsh and the workflow tool are the shipped producers. + +The subsystem reference — offsets, retention, listener delivery — is [docs/subsystems/activity.md](../../docs/subsystems/activity.md); design in the [activity observation seam](../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md) Agent Note. diff --git a/packages/activity/README.zh.md b/packages/activity/README.zh.md new file mode 100644 index 0000000000..b75c7bfcfd --- /dev/null +++ b/packages/activity/README.zh.md @@ -0,0 +1,14 @@ +# activity/ — 流式输出观察能力族 + +[English](README.md) | 中文 + +本能力族为所有长时生产者提供统一的非消费观察面:一个 activity 是一条 append-only 的有界输出流加实时状态,任意数量的独立观察者按绝对字节 offset 读取,而模型侧路径(`ctx.jobs` 游标、工具结果)完全不受影响。 + +| 包 | 角色 | ctx key | +|---|---|---| +| [`activity/`](activity/README.zh.md) | 定义观察注册表与词汇 | `ctx.activities` | +| [`activity-local/`](activity-local/README.zh.md) | 实现内存环形缓冲注册表 | 注册到 `ctx.activities` | + +Web 传输与客户端消费者在 [`dsh-api-activity-controller`](../api/activity-controller/README.zh.md) 与 [`dsh-client-ui-activity`](../client/ui-activity/README.zh.md);后台 bash/pwsh 与 workflow 工具是已接入的生产者。 + +子系统参考——offset、保留策略、监听投递——见 [docs/subsystems/activity.zh.md](../../docs/subsystems/activity.zh.md);设计见 [activity 观察 seam](../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md) Agent Note。 diff --git a/packages/activity/activity-local/README.i18n.yaml b/packages/activity/activity-local/README.i18n.yaml new file mode 100644 index 0000000000..adbd77bb80 --- /dev/null +++ b/packages/activity/activity-local/README.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 packages/activity/activity-local/README.md +README.md: 511511a6a5164e0ae4be65230e83a2c1ef37797a +README.zh.md: e4bee07b74abf6c75b68245147f3f5b6fd9f3f6c diff --git a/packages/activity/activity-local/README.md b/packages/activity/activity-local/README.md new file mode 100644 index 0000000000..511511a6a5 --- /dev/null +++ b/packages/activity/activity-local/README.md @@ -0,0 +1,30 @@ +# @deepseek-ai/dsh-activity-local + +English | [中文](README.zh.md) + +The in-memory Service Provider for the [`dsh-activity`](../activity/README.md) observation seam: `LocalActivityRegistry` keeps every record and its bounded output ring in process memory and hands out fresh snapshots and chunk copies, never live state. + +## Retention + +Each activity retains a chunk ring whose offsets stay absolute across eviction: dropping the head advances `outputEarliest`, and a single chunk larger than the live cap keeps only its UTF-8-safe tail with a `gapBefore` marker. Settlement trims the ring to the settled cap so a finished activity still shows its tail without holding the live budget. + +| Config | Default | Meaning | +|---|---|---| +| `retainBytes` | `262144` | Live output retention per activity, in UTF-8 bytes. | +| `settledRetainBytes` | `16384` | Retention kept after an activity settles. | + +## Lifecycle + +Records outlive producer fibers. The first activity for an owner attaches one cleanup to the exact `Agent` scope; owner disposal ends still-open records (`killed`, `owner disposed`) and removes them, announcing the removal. Service disposal ends everything, clears the store, and announces each emptied owner. Neither awaits a producer — the registry owns no execution resource. Listeners are layered by registration scope exactly like the jobs registry, so delivery stays owner-relative in one process-wide instance. + +## Model Experience + +None, as the provider stores and serves observation state only; the producers own every model-visible surface. + +#### KV Cache effect + +None; the package never assembles or alters provider requests. + +## Known Limitations and Deferred Work + +- **The unowned bucket has no admission bound** — owned producers are already bounded by the jobs admission policy, but a plugin opening many unowned activities grows the store until service disposal. diff --git a/packages/activity/activity-local/README.zh.md b/packages/activity/activity-local/README.zh.md new file mode 100644 index 0000000000..e4bee07b74 --- /dev/null +++ b/packages/activity/activity-local/README.zh.md @@ -0,0 +1,30 @@ +# @deepseek-ai/dsh-activity-local + +[English](README.md) | 中文 + +[`dsh-activity`](../activity/README.zh.md) 观察 seam 的内存 Service Provider:`LocalActivityRegistry` 把每条记录及其有界输出环保存在进程内存中,对外只给全新快照与 chunk 副本,绝不暴露活状态。 + +## 保留策略 + +每个 activity 保留一个 offset 跨淘汰稳定的 chunk 环:丢弃头部使 `outputEarliest` 前移;单个超过存活上限的 chunk 只保留其 UTF-8 安全的尾部并打上 `gapBefore` 标记。结算时把环裁到 settled 上限,已完成的 activity 仍能展示尾巴而不占存活预算。 + +| 配置 | 默认值 | 含义 | +|---|---|---| +| `retainBytes` | `262144` | 每个 activity 的存活输出保留量(UTF-8 字节)。 | +| `settledRetainBytes` | `16384` | activity 结算后的保留量。 | + +## 生命周期 + +记录的存续期长于生产者 fiber。owner 的第一个 activity 会在 exact `Agent` scope 上挂一个清理;owner 销毁时把未结束的记录终结(`killed`、`owner disposed`)并移除,同时公告移除。服务销毁终结一切、清空存储并逐个公告被清空的 owner。两者都不等待生产者——注册表不拥有任何执行资源。监听按注册 scope 分层,与 jobs 注册表完全一致,一个进程级实例内投递保持 owner 相对。 + +## 模型体验 + +无:provider 只存储与提供观察状态;所有模型可见面都归生产者。 + +#### KV Cache 影响 + +无;本包从不组装或改动 provider 请求。 + +## 已知限制与暂缓事项 + +- **无主桶没有准入上限**——有主生产者已被 jobs 准入策略约束,但插件开出的大量无主 activity 会让存储一直增长到服务销毁。 diff --git a/packages/activity/activity-local/package.json b/packages/activity/activity-local/package.json new file mode 100644 index 0000000000..b06864d251 --- /dev/null +++ b/packages/activity/activity-local/package.json @@ -0,0 +1,55 @@ +{ + "name": "@deepseek-ai/dsh-activity-local", + "description": "Process-local implementation of the DeepSeek Harness streaming-output observation seam", + "version": "0.1.1-rc.2", + "publishConfig": { + "access": "public" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/deepseek-ai/deepseek-harness.git", + "directory": "packages/activity/activity-local" + }, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./invariant": { + "types": "./lib/types/invariant.d.ts", + "default": "./lib/invariant.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/invariant.js", + "lib/types/**/*.d.ts" + ], + "license": "MIT", + "peerDependencies": { + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/dsh-activity": "workspace:^", + "@deepseek-ai/dsh-scope": "workspace:^", + "@deepseek-ai/cordis": "workspace:^" + }, + "dependencies": { + "@deepseek-ai/schemastery": "workspace:^" + }, + "devDependencies": { + "@deepseek-ai/cordis-plugin-include": "workspace:^", + "@deepseek-ai/cordis-plugin-loader": "workspace:^", + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-brand": "workspace:^", + "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/dsh-activity": "workspace:^", + "@deepseek-ai/dsh-scope": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/cordis": "workspace:^" + } +} diff --git a/packages/activity/activity-local/src/index.ts b/packages/activity/activity-local/src/index.ts new file mode 100644 index 0000000000..caabb5499e --- /dev/null +++ b/packages/activity/activity-local/src/index.ts @@ -0,0 +1,438 @@ +/** + * Process-local provider for the streaming-output observation seam + * (`ctx.activities`). It keeps every record and its bounded output ring in + * memory and hands out fresh snapshots and chunk copies, never live state. + * + * Records outlive producer fibers. Owner disposal ends still-open records and + * removes them; service disposal ends and clears everything. Neither awaits a + * producer — the registry owns no execution resource. + * @module @deepseek-ai/dsh-activity-local + */ + +import { Context } from '@deepseek-ai/cordis' +import z from '@deepseek-ai/schemastery' +import type { Agent } from '@deepseek-ai/dsh-agent' +import { AnonymousEntries, ScopedLayers, scopeOf } from '@deepseek-ai/dsh-scope' +import type { ScopeLayer } from '@deepseek-ai/dsh-scope' +import { ActivityRegistry, ActivityId } from '@deepseek-ai/dsh-activity' +import type { + ActivityAppendOptions, ActivityChannel, ActivityCorrelation, ActivitiesChangedListener, + ActivityHandle, ActivityKind, ActivityOpen, ActivityOutcome, ActivityOutputChunk, + ActivityOutputListener, ActivityRead, ActivitySnapshot, ActivityStatus, +} from '@deepseek-ai/dsh-activity' + +/** Default live retention per activity, in UTF-8 bytes. */ +const DEFAULT_RETAIN_BYTES = 256 * 1024 + +/** Default retention kept after settlement, in UTF-8 bytes. */ +const DEFAULT_SETTLED_RETAIN_BYTES = 16 * 1024 + +/** Configuration for the process-local observation registry. */ +export interface Config { + /** Live output retention per activity in UTF-8 bytes; omission defaults to 262144. */ + retainBytes?: number + /** Output retention kept after an activity settles, in UTF-8 bytes; omission defaults to 16384. */ + settledRetainBytes?: number +} + +/** The registry's mutable per-activity record (never handed out — see {@link LocalActivityRegistry.snapshot}). */ +interface TrackedActivity { + id: ActivityId + kind: ActivityKind + label: string + /** Exact lifecycle owner; session-id visibility is derived from it. */ + owner: Agent | undefined + correlation: ActivityCorrelation | undefined + status: ActivityStatus + detail: string | undefined + startedAt: number + finishedAt: number | undefined + /** Retained chunks in offset order; offsets stay absolute across eviction. */ + chunks: RingChunk[] + /** Sum of the retained chunks' byte lengths. */ + retainedBytes: number + /** Total UTF-8 bytes ever appended. */ + total: number + /** Offset of the oldest retained byte (equals {@link total} when nothing is retained). */ + earliest: number +} + +/** One retained ring entry; `bytes` caches the chunk's UTF-8 length. */ +interface RingChunk { + at: number + text: string + bytes: number + channel?: ActivityChannel + gapBefore?: true +} + +/** True for the three terminal {@link ActivityStatus} values. */ +function isTerminal(status: ActivityStatus): boolean { + return status === 'completed' || status === 'failed' || status === 'killed' +} + +/** + * The UTF-8-safe tail of `text` no longer than `maxBytes`: the byte cut + * advances past continuation bytes so the surviving text never starts inside + * a code point. + * @param text - the oversized chunk text. + * @param maxBytes - positive byte budget for the surviving tail. + * @returns the surviving tail and its exact byte length. + */ +function utf8Tail(text: string, maxBytes: number): { text: string; bytes: number } { + const raw = Buffer.from(text, 'utf8') + let start = raw.length - maxBytes + // The loop bound proves the index is in range; the assertion only + // discharges noUncheckedIndexedAccess. + while (start < raw.length && ((raw[start] as number) & 0xC0) === 0x80) start += 1 + const tail = raw.subarray(start) + return { text: tail.toString('utf8'), bytes: tail.length } +} + +/** + * One scope's observer contributions. Both tables are anonymous because a + * contribution is identified by its own disposer, never by a name a second + * registrant could shadow. + */ +class ActivityLayer implements ScopeLayer { + readonly changed = new AnonymousEntries() + readonly output = new AnonymousEntries() + + isEmpty(): boolean { + return this.changed.isEmpty() && this.output.isEmpty() + } +} + +/** + * The in-memory `activities` registry. See the Service Definition contract in + * `@deepseek-ai/dsh-activity` for the observation, retention, and lifecycle + * semantics this implementation honors. + */ +export class LocalActivityRegistry extends ActivityRegistry { + static Config: z = z.object({ + retainBytes: z.number() + .step(1) + .min(1) + .max(Number.MAX_SAFE_INTEGER) + .default(DEFAULT_RETAIN_BYTES), + settledRetainBytes: z.number() + .step(1) + .min(1) + .max(Number.MAX_SAFE_INTEGER) + .default(DEFAULT_SETTLED_RETAIN_BYTES), + }) + + /** Schemastery-defaulted live retention cap. */ + private readonly retainBytes: number + /** Schemastery-defaulted settled retention cap. */ + private readonly settledRetainBytes: number + private store = new Map() + private counters = new Map() + /** + * Observers layered by the scope that registered them, in the jobs-registry + * shape: a contribution files into its registering context's scope, and a + * dispatch unions the global layer with the subject owner's scope chain, so + * delivery stays owner-relative in one process-wide registry. Nothing + * derives a cache from a layer, so change notification is a no-op. + */ + private readonly layers = new ScopedLayers(() => new ActivityLayer(), () => {}) + /** Owner agents with attached scope cleanup, mapped to the exact disposer. */ + private ownerCleanups = new Map Promise | void>() + /** Service context used by contained listener reporting and teardown. */ + private readonly selfCtx: Context + + constructor(ctx: Context, config: Config) { + super(ctx) + // Schemastery validates and fills the defaults before constructing the service. + this.retainBytes = (config as Required).retainBytes + this.settledRetainBytes = (config as Required).settledRetainBytes + this.selfCtx = ctx + ctx.effect(() => () => { this.disposeAll() }, 'activities teardown') + } + + open(spec: ActivityOpen): ActivityHandle { + if (spec.kind.length === 0) throw new Error('invalid activity kind: expected a non-empty string') + if (spec.label.length === 0) throw new Error('invalid activity label: expected a non-empty string') + if (spec.owner !== undefined) this.ensureOwnerCleanup(spec.owner) + + const count = (this.counters.get(spec.kind) ?? 0) + 1 + this.counters.set(spec.kind, count) + const id = ActivityId(`${spec.kind}-${count}`) + const record: TrackedActivity = { + id, + kind: spec.kind, + label: spec.label, + owner: spec.owner, + correlation: spec.correlation === undefined ? undefined : { ...spec.correlation }, + status: 'running', + detail: undefined, + startedAt: Date.now(), + finishedAt: undefined, + chunks: [], + retainedBytes: 0, + total: 0, + earliest: 0, + } + this.store.set(id, record) + // Registration is complete and cannot fail from here, so the visible set + // has genuinely changed. + this.notifyChanged(record.owner) + return { + id, + append: (text, options) => { this.append(record, text, options) }, + updateDetail: (detail) => { this.updateDetail(record, detail) }, + end: (outcome) => { this.settle(record, outcome) }, + } + } + + list(caller?: Agent): ActivitySnapshot[] { + const session = caller?.id + return [...this.store.values()] + .filter(record => record.owner === undefined || record.owner.id === session) + .map(record => this.snapshot(record)) + } + + get(id: ActivityId, caller?: Agent): ActivitySnapshot { + const record = this.expect(id) + this.assertAccess(record, caller) + return this.snapshot(record) + } + + read(id: ActivityId, from: number, caller?: Agent): ActivityRead { + const record = this.expect(id) + this.assertAccess(record, caller) + if (!Number.isSafeInteger(from) || from < 0) { + throw new Error(`invalid read offset: expected a non-negative safe integer, got ${JSON.stringify(from)}`) + } + const chunks: ActivityOutputChunk[] = [] + for (const chunk of record.chunks) { + if (chunk.at + chunk.bytes <= from) continue + chunks.push({ + at: chunk.at, + text: chunk.text, + ...chunk.channel !== undefined ? { channel: chunk.channel } : {}, + ...chunk.gapBefore !== undefined ? { gapBefore: chunk.gapBefore } : {}, + }) + } + return { chunks, next: record.total, lossy: from < record.earliest } + } + + onActivitiesChanged(listener: ActivitiesChangedListener): () => void { + return this.layers.effect( + this.ctx, + layer => layer.changed.append(listener), + { label: 'activities.onActivitiesChanged()' }, + ) + } + + onOutput(listener: ActivityOutputListener): () => void { + return this.layers.effect( + this.ctx, + layer => layer.output.append(listener), + { label: 'activities.onOutput()' }, + ) + } + + /** Append one chunk to a live record; log and drop on an ended one. */ + private append(record: TrackedActivity, text: string, options?: ActivityAppendOptions): void { + if (isTerminal(record.status)) { + this.selfCtx.logger.warn(`activities: append to ended activity ${record.id} dropped`) + return + } + if (text.length === 0) return + const bytes = Buffer.byteLength(text, 'utf8') + record.chunks.push({ + at: record.total, + text, + bytes, + ...options?.channel !== undefined ? { channel: options.channel } : {}, + ...options?.gapBefore !== undefined ? { gapBefore: options.gapBefore } : {}, + }) + record.total += bytes + record.retainedBytes += bytes + this.trim(record, this.retainBytes) + this.notifyOutput(record) + } + + /** Replace a live record's detail line; log and drop on an ended one. */ + private updateDetail(record: TrackedActivity, detail: string): void { + if (isTerminal(record.status)) { + this.selfCtx.logger.warn(`activities: detail update on ended activity ${record.id} dropped`) + return + } + record.detail = detail + this.notifyChanged(record.owner) + } + + /** + * Record the first terminal outcome, trim retention to the settled cap, and + * announce the change and the stream end. First-wins: a later call — the + * producer's own report after a teardown force-end, or a duplicate — is + * dropped silently. + */ + private settle(record: TrackedActivity, outcome: ActivityOutcome): void { + if (isTerminal(record.status)) return + record.status = outcome.status + if (outcome.detail !== undefined) record.detail = outcome.detail + record.finishedAt = Date.now() + this.trim(record, this.settledRetainBytes) + this.notifyChanged(record.owner) + this.notifyOutput(record) + } + + /** + * Drop retained head chunks until the ring fits `cap`; a single oversized + * chunk keeps only its UTF-8-safe tail with a `gapBefore` marker. Offsets + * stay absolute: `earliest` advances over everything dropped. + */ + private trim(record: TrackedActivity, cap: number): void { + while (record.retainedBytes > cap && record.chunks.length > 1) { + const dropped = record.chunks.shift() + /* v8 ignore next -- the length guard proves shift() returns a chunk; the check only satisfies noUncheckedIndexedAccess. */ + if (dropped === undefined) break + record.retainedBytes -= dropped.bytes + } + const single = record.chunks.length === 1 ? record.chunks[0] : undefined + if (single !== undefined && single.bytes > cap) { + const tail = utf8Tail(single.text, cap) + single.at += single.bytes - tail.bytes + single.text = tail.text + single.bytes = tail.bytes + single.gapBefore = true + record.retainedBytes = tail.bytes + } + record.earliest = record.chunks[0]?.at ?? record.total + } + + /** Look up an activity or fail loud. */ + private expect(id: ActivityId): TrackedActivity { + const record = this.store.get(id) + if (record === undefined) throw new Error(`unknown activity ${id}`) + return record + } + + /** + * The visibility fence: an activity with an owner is reachable only by + * callers whose session id matches (`!== undefined` semantics — an unowned + * activity is open, and a no-agent caller can never match an owned one). + */ + private assertAccess(record: TrackedActivity, caller?: Agent): void { + if (record.owner !== undefined && record.owner.id !== caller?.id) { + throw new Error(`activity ${record.id} belongs to another session`) + } + } + + /** Project a fresh read-only snapshot from the mutable record. */ + private snapshot(record: TrackedActivity): ActivitySnapshot { + const ownerSession = record.owner?.id + return { + id: record.id, + kind: record.kind, + label: record.label, + ...ownerSession !== undefined ? { ownerSession } : {}, + ...record.correlation !== undefined ? { correlation: { ...record.correlation } } : {}, + status: record.status, + ...record.detail !== undefined ? { detail: record.detail } : {}, + startedAt: record.startedAt, + ...record.finishedAt !== undefined ? { finishedAt: record.finishedAt } : {}, + outputTotal: record.total, + outputEarliest: record.earliest, + } + } + + /** + * The change observers that own `owner`'s updates: the global layer — a + * host composition's own carrier, which serves every owner — then each + * scoped layer along the owner's chain. + */ + private *changedFor(owner?: Agent): IterableIterator { + yield* this.layers.global.changed.values() + const scope = owner === undefined ? undefined : scopeOf(owner.ctx) + for (const layer of this.layers.chainLayers(scope)) yield* layer.changed.values() + } + + /** The output observers that own `owner`'s stream signals, resolved like {@link changedFor}. */ + private *outputFor(owner?: Agent): IterableIterator { + yield* this.layers.global.output.values() + const scope = owner === undefined ? undefined : scopeOf(owner.ctx) + for (const layer of this.layers.chainLayers(scope)) yield* layer.output.values() + } + + /** + * Announce that one owner's visible set changed. Each listener is contained + * so an observer cannot break a lifecycle commit that already happened. + */ + private notifyChanged(owner: Agent | undefined): void { + for (const listener of this.changedFor(owner)) { + try { + listener(owner) + } catch (error: unknown) { + this.selfCtx.logger.warn(`activities: onActivitiesChanged listener threw: ${String(error)}`) + } + } + } + + /** Announce that one activity's stream advanced (append or settlement), with per-listener containment. */ + private notifyOutput(record: TrackedActivity): void { + for (const listener of this.outputFor(record.owner)) { + try { + listener(record.id) + } catch (error: unknown) { + this.selfCtx.logger.warn(`activities: onOutput listener threw: ${String(error)}`) + } + } + } + + /** + * Attach one cleanup through the exact owner's scope. This survives + * producer reloads; the retained disposer lets service teardown detach the + * cross-fiber effect. Fails when the agent registry is absent or the owner + * is not its currently registered instance. + */ + private ensureOwnerCleanup(owner: Agent): void { + const ownerId = owner.id + const agents = this.selfCtx.get('agents') + if (agents === undefined) { + throw new Error('activity ownership requires the agent registry (load @deepseek-ai/dsh-agent)') + } + if (agents.get(ownerId) !== owner) { + throw new Error(`agent "${ownerId}" is not the registered agent instance (activity owner must be live)`) + } + if (this.ownerCleanups.has(owner)) return + // Record only after attach succeeds; a disposing scope rejects new effects. + const detach = owner.ctx.effect(() => () => { + this.ownerCleanups.delete(owner) + this.disposeOwned(owner) + }, 'activities.ownerCleanup()') + this.ownerCleanups.set(owner, detach) + } + + /** End still-open records and drop every activity owned by one exact agent lifecycle. */ + private disposeOwned(owner: Agent): void { + const owned = [...this.store.values()].filter(record => record.owner === owner) + for (const record of owned) { + if (!isTerminal(record.status)) this.settle(record, { status: 'killed', detail: 'owner disposed' }) + this.store.delete(record.id) + } + // Removal is the one visible-set change no per-activity record carries, so + // it must be announced here or an observer keeps the dropped rows forever. + if (owned.length > 0) this.notifyChanged(owner) + } + + /** End every open record, clear the store, and announce each emptied owner. */ + private disposeAll(): void { + const all = [...this.store.values()] + for (const record of all) { + if (!isTerminal(record.status)) this.settle(record, { status: 'killed', detail: 'activity registry disposed' }) + } + const emptied = new Set(all.map(record => record.owner)) + this.store.clear() + for (const owner of emptied) this.notifyChanged(owner) + // Detach cross-fiber owner effects after the shared store is quiescent. + const ownerCleanups = [...this.ownerCleanups.values()] + this.ownerCleanups.clear() + for (const cleanup of ownerCleanups) void cleanup() + } +} + +export default LocalActivityRegistry diff --git a/packages/activity/activity-local/src/invariant.ts b/packages/activity/activity-local/src/invariant.ts new file mode 100644 index 0000000000..7e15b7db09 --- /dev/null +++ b/packages/activity/activity-local/src/invariant.ts @@ -0,0 +1,33 @@ +/** + * Package-owned invariant companion for `@deepseek-ai/dsh-activity-local`. + * @module @deepseek-ai/dsh-activity-local/invariant + */ + +/* jscpd:ignore-start */ +import type { Context } from '@deepseek-ai/cordis' +import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants' + +const PACKAGE_NAME = '@deepseek-ai/dsh-activity-local' + +/** Cordis companion plugin name. */ +export const name = 'activity-local-invariant' +/** Service required before the companion can reserve package ownership. */ +export const inject = ['invariants'] + +/** + * No runtime invariant: `@deepseek-ai/dsh-activity/invariant` owns per-snapshot identity, status, + * timestamp, and offset checks on every visible-set change. This provider's remaining behavior — + * ring retention against private byte caps and pull-only chunk reads — has no authoritative event + * stream to observe: a read happens on a caller's schedule, and repeating the retention arithmetic + * against private configuration would duplicate the implementation rather than check a relation. + */ +const install: InvariantInstaller = () => {} + +/** + * Register this package's invariant companion. + * @param ctx - Cordis context carrying the invariant service. + * @returns the installed registration's disposer after setup succeeds. + */ +export const apply = (ctx: Context): Promise<() => void> => + Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install)) +/* jscpd:ignore-end */ diff --git a/packages/activity/activity-local/tests/activity.spec.ts b/packages/activity/activity-local/tests/activity.spec.ts new file mode 100644 index 0000000000..557046d617 --- /dev/null +++ b/packages/activity/activity-local/tests/activity.spec.ts @@ -0,0 +1,413 @@ +import { describe, expect, it, vi } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import { Session, SessionId } from '@deepseek-ai/dsh-session' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' +import type { Agent } from '@deepseek-ai/dsh-agent' +import { createScope } from '@deepseek-ai/dsh-scope' +import { ActivityId } from '@deepseek-ai/dsh-activity' +import type { ActivityHandle, ActivitySnapshot } from '@deepseek-ai/dsh-activity' +import LocalActivityRegistry, { type Config as ProcessConfig } from '@deepseek-ai/dsh-activity-local' + +declare module '@deepseek-ai/dsh-activity' { + interface ActivityKindMap { + workflow: 'workflow' + } +} + +const agentScopeDisposers = new WeakMap Promise>() + +/** + * A minimal live agent whose ctx carries its own scope on a disposable plugin + * fiber, mirroring the harness convention that a live agent keys its scope. + */ +function stubAgent(ctx: Context, rawId: string): Agent { + const id = SessionId(rawId) + const scopeFiber = ctx.plugin(() => {}) + const agentCtx = createScope(scopeFiber.ctx, {}).ctx + const session = Session.create(id) + const agent = { + id, + options: {}, + session, + inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }), + status: 'idle' as const, + ctx: agentCtx, + send: () => {}, + followup: () => {}, + steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }), + inject: () => {}, + cancel() {}, + runMaintenance: (job: (signal: AbortSignal) => Promise) => job(new AbortController().signal), + whenIdle() { return Promise.resolve() }, + } + agentScopeDisposers.set(agent, async () => { await scopeFiber.dispose() }) + return agent +} + +async function disposeAgentScope(agent: Agent): Promise { + const dispose = agentScopeDisposers.get(agent) + if (dispose === undefined) throw new Error(`missing test scope for agent "${agent.id}"`) + await dispose() +} + +async function harness(config: ProcessConfig = {}) { + const ctx = new Context() + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalActivityRegistry, config) + return ctx +} + +/** Concatenated retained text of one process, as an observer from `from` sees it. */ +function textFrom(ctx: Context, id: ActivityId, from = 0): string { + return ctx.activities.read(id, from).chunks.map(chunk => chunk.text).join('') +} + +describe('LocalActivityRegistry.open', () => { + it('mints per-kind ordinal ids and announces the new visible row', async () => { + const ctx = await harness() + const changes: (Agent | undefined)[] = [] + ctx.activities.onActivitiesChanged((owner) => { changes.push(owner) }) + const first = ctx.activities.open({ kind: 'bash', label: 'sleep 60' }) + const second = ctx.activities.open({ kind: 'workflow', label: 'run docs' }) + const third = ctx.activities.open({ kind: 'bash', label: 'build' }) + expect([first.id, second.id, third.id]).toEqual(['bash-1', 'workflow-1', 'bash-2']) + expect(changes).toEqual([undefined, undefined, undefined]) + expect(ctx.activities.list().map(snapshot => snapshot.id)).toEqual(['bash-1', 'workflow-1', 'bash-2']) + }) + + it('rejects an empty kind or label without minting an id', async () => { + const ctx = await harness() + expect(() => ctx.activities.open({ kind: '' as never, label: 'x' })).toThrow(/invalid activity kind/) + expect(() => ctx.activities.open({ kind: 'bash', label: '' })).toThrow(/invalid activity label/) + expect(ctx.activities.list()).toEqual([]) + }) + + it('rejects an owned open when no agent registry is loaded', async () => { + const bare = new Context() + await bare.plugin(LocalActivityRegistry) + const ghost = { id: SessionId('ghost'), ctx: bare } as unknown as Agent + expect(() => bare.activities.open({ kind: 'bash', label: 'x', owner: ghost })) + .toThrow(/activity ownership requires the agent registry/) + }) + + it('rejects an owner that is not the registered agent instance', async () => { + const ctx = await harness() + const ghost = stubAgent(ctx, 'ghost') + expect(() => ctx.activities.open({ kind: 'bash', label: 'x', owner: ghost })) + .toThrow(/not the registered agent instance/) + }) + + it('carries owner session and correlation into snapshots', async () => { + const ctx = await harness() + const owner = stubAgent(ctx, 'owner') + ctx.agents.register(owner) + const handle = ctx.activities.open({ + kind: 'bash', + label: 'npm test', + owner, + correlation: { jobId: 'bash-9' as never, callId: 'call-3' as never }, + }) + const snapshot = ctx.activities.get(handle.id, owner) + expect(snapshot.ownerSession).toBe(owner.id) + expect(snapshot.correlation).toEqual({ jobId: 'bash-9', callId: 'call-3' }) + expect(snapshot.status).toBe('running') + }) +}) + +describe('LocalActivityRegistry output', () => { + it('appends advance absolute offsets and reads are non-consuming', async () => { + const ctx = await harness() + const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) + handle.append('hello ') + handle.append('world', { channel: 'stderr' }) + const first = ctx.activities.read(handle.id, 0) + expect(first.lossy).toBe(false) + expect(first.next).toBe(11) + expect(first.chunks).toEqual([ + { at: 0, text: 'hello ' }, + { at: 6, text: 'world', channel: 'stderr' }, + ]) + // A second identical read proves nothing was consumed. + expect(ctx.activities.read(handle.id, 0)).toEqual(first) + // Resuming from `next` yields nothing until more output arrives. + expect(ctx.activities.read(handle.id, first.next).chunks).toEqual([]) + handle.append('!') + expect(ctx.activities.read(handle.id, first.next).chunks).toEqual([{ at: 11, text: '!' }]) + const snapshot = ctx.activities.get(handle.id) + expect(snapshot.outputTotal).toBe(12) + expect(snapshot.outputEarliest).toBe(0) + }) + + it('drops an empty append without waking observers', async () => { + const ctx = await harness() + const signals: ActivityId[] = [] + ctx.activities.onOutput((id) => { signals.push(id) }) + const handle = ctx.activities.open({ kind: 'bash', label: 'quiet' }) + handle.append('') + expect(signals).toEqual([]) + expect(ctx.activities.get(handle.id).outputTotal).toBe(0) + }) + + it('rejects a negative or fractional read offset', async () => { + const ctx = await harness() + const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) + expect(() => ctx.activities.read(handle.id, -1)).toThrow(/invalid read offset/) + expect(() => ctx.activities.read(handle.id, 0.5)).toThrow(/invalid read offset/) + }) + + it('evicts whole head chunks past the live cap and flags stale readers lossy', async () => { + const ctx = await harness({ retainBytes: 8 }) + const handle = ctx.activities.open({ kind: 'bash', label: 'spam' }) + handle.append('aaaa') + handle.append('bbbb') + handle.append('cccc') + const read = ctx.activities.read(handle.id, 0) + expect(read.lossy).toBe(true) + expect(read.chunks).toEqual([{ at: 4, text: 'bbbb' }, { at: 8, text: 'cccc' }]) + expect(read.next).toBe(12) + const snapshot = ctx.activities.get(handle.id) + expect(snapshot.outputEarliest).toBe(4) + expect(snapshot.outputTotal).toBe(12) + // A reader at the retained boundary is not lossy. + expect(ctx.activities.read(handle.id, 4).lossy).toBe(false) + }) + + it('keeps only the UTF-8-safe tail of a single oversized chunk', async () => { + const ctx = await harness({ retainBytes: 5 }) + const handle = ctx.activities.open({ kind: 'bash', label: 'wide' }) + // '你好' is six UTF-8 bytes; a five-byte budget must not split the second code point. + handle.append('你好') + const read = ctx.activities.read(handle.id, 0) + expect(read.lossy).toBe(true) + expect(read.chunks).toEqual([{ at: 3, text: '好', gapBefore: true }]) + const snapshot = ctx.activities.get(handle.id) + expect(snapshot.outputEarliest).toBe(3) + expect(snapshot.outputTotal).toBe(6) + }) + + it('returns the whole overlapped chunk for a foreign mid-chunk offset', async () => { + const ctx = await harness() + const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) + handle.append('abcdef') + const read = ctx.activities.read(handle.id, 3) + expect(read.chunks).toEqual([{ at: 0, text: 'abcdef' }]) + expect(read.lossy).toBe(false) + }) + + it('preserves a producer-reported gap marker through reads', async () => { + const ctx = await harness() + const handle = ctx.activities.open({ kind: 'bash', label: 'lossy source' }) + handle.append('tail after drop', { gapBefore: true, channel: 'stdout' }) + expect(ctx.activities.read(handle.id, 0).chunks).toEqual([ + { at: 0, text: 'tail after drop', channel: 'stdout', gapBefore: true }, + ]) + }) +}) + +describe('LocalActivityRegistry settlement', () => { + it('records the first terminal outcome and trims retention to the settled cap', async () => { + const ctx = await harness({ retainBytes: 1024, settledRetainBytes: 4 }) + const handle = ctx.activities.open({ kind: 'bash', label: 'build' }) + handle.append('abcdefgh') + handle.end({ status: 'completed', detail: 'exit code: 0' }) + const snapshot = ctx.activities.get(handle.id) + expect(snapshot.status).toBe('completed') + expect(snapshot.detail).toBe('exit code: 0') + expect(snapshot.finishedAt).toBeDefined() + const read = ctx.activities.read(handle.id, 0) + expect(read.lossy).toBe(true) + expect(read.chunks).toEqual([{ at: 4, text: 'efgh', gapBefore: true }]) + }) + + it('is first-wins: a later end and post-end writes are dropped without throwing', async () => { + const ctx = await harness() + const warn = vi.fn() + ctx.logger.warn = warn as never + const handle = ctx.activities.open({ kind: 'bash', label: 'build' }) + handle.end({ status: 'killed', detail: 'owner disposed' }) + handle.end({ status: 'completed' }) + handle.append('late') + handle.updateDetail('late detail') + const snapshot = ctx.activities.get(handle.id) + expect(snapshot.status).toBe('killed') + expect(snapshot.detail).toBe('owner disposed') + expect(snapshot.outputTotal).toBe(0) + expect(warn.mock.calls.map(call => String(call[0]))).toEqual([ + expect.stringContaining('append to ended activity'), + expect.stringContaining('detail update on ended activity'), + ]) + }) + + it('signals observers for appends and once more at settlement', async () => { + const ctx = await harness() + const signals: ActivityId[] = [] + ctx.activities.onOutput((id) => { signals.push(id) }) + const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) + handle.append('a') + handle.append('b') + handle.end({ status: 'completed' }) + expect(signals).toEqual([handle.id, handle.id, handle.id]) + }) + + it('updateDetail changes the visible row without touching output offsets', async () => { + const ctx = await harness() + const changes: (Agent | undefined)[] = [] + ctx.activities.onActivitiesChanged((owner) => { changes.push(owner) }) + const handle = ctx.activities.open({ kind: 'workflow', label: 'docs run' }) + handle.updateDetail('3/10 agents done') + expect(ctx.activities.get(handle.id).detail).toBe('3/10 agents done') + expect(ctx.activities.get(handle.id).outputTotal).toBe(0) + expect(changes).toHaveLength(2) + }) +}) + +describe('LocalActivityRegistry visibility and delivery', () => { + it('fences owned processes by session id and keeps unowned ones open', async () => { + const ctx = await harness() + const alice = stubAgent(ctx, 'alice') + const bob = stubAgent(ctx, 'bob') + ctx.agents.register(alice) + ctx.agents.register(bob) + const owned = ctx.activities.open({ kind: 'bash', label: 'alice job', owner: alice }) + const open = ctx.activities.open({ kind: 'bash', label: 'shared' }) + owned.append('secret') + expect(ctx.activities.list(alice).map(snapshot => snapshot.id)).toEqual([owned.id, open.id]) + expect(ctx.activities.list(bob).map(snapshot => snapshot.id)).toEqual([open.id]) + expect(ctx.activities.list().map(snapshot => snapshot.id)).toEqual([open.id]) + expect(() => ctx.activities.get(owned.id, bob)).toThrow(/belongs to another session/) + expect(() => ctx.activities.read(owned.id, 0)).toThrow(/belongs to another session/) + expect(textFrom(ctx, open.id)).toBe('') + expect(ctx.activities.read(owned.id, 0, alice).chunks[0]?.text).toBe('secret') + }) + + it('delivers scoped listeners only their own agents and global listeners everything', async () => { + const ctx = await harness() + const alice = stubAgent(ctx, 'alice') + const bob = stubAgent(ctx, 'bob') + ctx.agents.register(alice) + ctx.agents.register(bob) + const globalOwners: (string | undefined)[] = [] + ctx.activities.onActivitiesChanged((owner) => { globalOwners.push(owner?.id) }) + const scopedOwners: (string | undefined)[] = [] + await alice.ctx.plugin({ + inject: ['activities'], + apply(scopedCtx: Context) { + scopedCtx.activities.onActivitiesChanged((owner) => { scopedOwners.push(owner?.id) }) + }, + }) + const scopedOutputs: string[] = [] + const scopedFiber = await alice.ctx.plugin({ + inject: ['activities'], + apply(scopedCtx: Context) { + scopedCtx.activities.onOutput((id) => { scopedOutputs.push(String(id)) }) + }, + }) + const aliceHandle = ctx.activities.open({ kind: 'bash', label: 'alice work', owner: alice }) + aliceHandle.append('scoped delivery probe') + expect(scopedOutputs).toEqual([String(aliceHandle.id)]) + ctx.activities.open({ kind: 'bash', label: 'bob work', owner: bob }) + ctx.activities.open({ kind: 'bash', label: 'unowned' }) + expect(globalOwners).toEqual(['alice', 'bob', undefined]) + expect(scopedOwners).toEqual(['alice']) + // Disposing one scoped registrant probes layer reclamation; the sibling + // scoped changed-listener keeps the layer alive and keeps delivering. + await scopedFiber.dispose() + ctx.activities.open({ kind: 'bash', label: 'alice later', owner: alice }) + expect(scopedOwners).toEqual(['alice', 'alice']) + + // A scope whose only contribution goes empties on disposal and is reclaimed. + const bobFiber = await bob.ctx.plugin({ + inject: ['activities'], + apply(scopedCtx: Context) { + scopedCtx.activities.onOutput(() => {}) + }, + }) + await bobFiber.dispose() + }) + + it('contains throwing listeners without breaking the commit', async () => { + const ctx = await harness() + const warn = vi.fn() + ctx.logger.warn = warn as never + ctx.activities.onActivitiesChanged(() => { throw new Error('changed boom') }) + ctx.activities.onOutput(() => { throw new Error('output boom') }) + const seen: (Agent | undefined)[] = [] + ctx.activities.onActivitiesChanged((owner) => { seen.push(owner) }) + const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) + handle.append('x') + expect(seen).toHaveLength(1) + expect(ctx.activities.get(handle.id).outputTotal).toBe(1) + expect(warn).toHaveBeenCalledWith(expect.stringContaining('onActivitiesChanged listener threw')) + expect(warn).toHaveBeenCalledWith(expect.stringContaining('onOutput listener threw')) + }) + + it('unregisters listeners with their registering fiber', async () => { + const ctx = await harness() + const signals: ActivityId[] = [] + const fiber = ctx.plugin({ + inject: ['activities'], + apply(pluginCtx: Context) { + pluginCtx.activities.onOutput((id) => { signals.push(id) }) + }, + }) + await fiber + const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) + handle.append('a') + expect(signals).toHaveLength(1) + await fiber.dispose() + handle.append('b') + expect(signals).toHaveLength(1) + }) +}) + +describe('LocalActivityRegistry lifecycle', () => { + it('owner disposal ends open records, removes rows, and announces the removal', async () => { + const ctx = await harness() + const owner = stubAgent(ctx, 'owner') + ctx.agents.register(owner) + const handle = ctx.activities.open({ kind: 'bash', label: 'sleep', owner }) + handle.append('partial') + const settledEarly = ctx.activities.open({ kind: 'bash', label: 'done already', owner }) + settledEarly.end({ status: 'completed' }) + const changes: (string | undefined)[] = [] + ctx.activities.onActivitiesChanged((changed) => { changes.push(changed?.id) }) + await disposeAgentScope(owner) + expect(ctx.activities.list(owner)).toEqual([]) + expect(() => ctx.activities.get(handle.id, owner)).toThrow(/unknown activity/) + // The forced end and the removal both announced under the owner. + expect(changes.length).toBeGreaterThanOrEqual(2) + expect(new Set(changes)).toEqual(new Set(['owner'])) + // The producer's own late report is dropped silently, not thrown. + expect(() => { handle.end({ status: 'completed' }) }).not.toThrow() + }) + + it('service disposal ends everything, clears the store, and announces emptied owners', async () => { + const ctx = new Context() + await ctx.plugin(AgentRegistry) + const registryFiber = ctx.plugin(LocalActivityRegistry, {}) + await registryFiber + const owner = stubAgent(ctx, 'owner') + ctx.agents.register(owner) + const processes = ctx.activities + const owned = processes.open({ kind: 'bash', label: 'owned', owner }) + processes.open({ kind: 'bash', label: 'unowned' }) + const preSettled = processes.open({ kind: 'bash', label: 'already settled' }) + preSettled.end({ status: 'completed' }) + const changes: (string | undefined)[] = [] + ctx.activities.onActivitiesChanged((changed) => { changes.push(changed?.id) }) + await registryFiber.dispose() + expect(changes).toEqual(expect.arrayContaining(['owner', undefined])) + expect(() => { owned.append('late') }).not.toThrow() + }) +}) + +describe('LocalActivityRegistry snapshots', () => { + it('hands out fresh snapshots, never live registry state', async () => { + const ctx = await harness() + const handle: ActivityHandle = ctx.activities.open({ kind: 'bash', label: 'echo' }) + const before: ActivitySnapshot = ctx.activities.get(handle.id) + handle.append('grow') + expect(before.outputTotal).toBe(0) + expect(ctx.activities.get(handle.id).outputTotal).toBe(4) + }) +}) diff --git a/packages/activity/activity-local/tests/loader-composition.spec.ts b/packages/activity/activity-local/tests/loader-composition.spec.ts new file mode 100644 index 0000000000..4b341f7e16 --- /dev/null +++ b/packages/activity/activity-local/tests/loader-composition.spec.ts @@ -0,0 +1,60 @@ +import { afterEach, describe, expect, it } from 'vitest' +import { mkdtemp, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { pathToFileURL } from 'node:url' +import { Context } from '@deepseek-ai/cordis' +import Include from '@deepseek-ai/cordis-plugin-include' +import Loader from '@deepseek-ai/cordis-plugin-loader' +import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' + +let root: string | undefined +let context: Context | undefined + +afterEach(async () => { + await context?.fiber.dispose() + context = undefined + if (root !== undefined) await rm(root, { recursive: true, force: true }) + root = undefined +}) + +describe('process-local through a real Loader composition', () => { + it('applies the provider-owned retention config from a Cordis row', async () => { + root = await mkdtemp(join(tmpdir(), 'dsh-activity-local-loader-')) + const configPath = join(root, 'cordis.yml') + await writeFile(configPath, [ + "- name: '@deepseek-ai/dsh-activity-local'", + ' config:', + ' retainBytes: 8', + '', + ].join('\n')) + + context = new Context() + context.baseUrl = pathToFileURL(root).href + '/' + await context.plugin(Loader) + context.loader.builtins.include = Include + context.loader.internal = { + version: 'v2', + async import(specifier: string) { + if (specifier === '@deepseek-ai/dsh-activity-local') return LocalActivityRegistry + throw new Error(`unexpected Loader import: ${specifier}`) + }, + } as unknown as NonNullable + await context.loader.create({ + name: 'cordis:include', + config: { path: pathToFileURL(configPath).href }, + }) + await context.loader.await() + + expect(context.activities).toBeInstanceOf(LocalActivityRegistry) + const handle = context.activities.open({ kind: 'bash', label: 'loader retention probe' }) + handle.append('aaaa') + handle.append('bbbb') + handle.append('cccc') + const read = context.activities.read(handle.id, 0) + // retainBytes: 8 from the Cordis row dropped the oldest chunk. + expect(read.lossy).toBe(true) + expect(read.chunks.map(chunk => chunk.text)).toEqual(['bbbb', 'cccc']) + expect(read.next).toBe(12) + }) +}) diff --git a/packages/activity/activity-local/tsconfig.json b/packages/activity/activity-local/tsconfig.json new file mode 100644 index 0000000000..0bddbff854 --- /dev/null +++ b/packages/activity/activity-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": "../../core/agent" + }, + { + "path": "../../core/scope" + }, + { + "path": "../activity" + }, + { + "path": "../../runtime-diagnostics/invariants" + } + ] +} diff --git a/packages/activity/activity/README.i18n.yaml b/packages/activity/activity/README.i18n.yaml new file mode 100644 index 0000000000..e8cb7b1bad --- /dev/null +++ b/packages/activity/activity/README.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 packages/activity/activity/README.md +README.md: a6d465d4d962b3bee59b56cfed1a4b0b1955c560 +README.zh.md: afe843f40a57103436e4c63799d80b86a9c4557a diff --git a/packages/activity/activity/README.md b/packages/activity/activity/README.md new file mode 100644 index 0000000000..a6d465d4d9 --- /dev/null +++ b/packages/activity/activity/README.md @@ -0,0 +1,32 @@ +# @deepseek-ai/dsh-activity + +English | [中文](README.zh.md) + +The streaming-output observation contract (`ctx.activities`). The abstract `ActivityRegistry` and its vocabulary types give any long-running producer one place to publish live output and status, and any number of independent consumers non-consuming reads over it; the in-memory registry lives in [`dsh-activity-local`](../activity-local/README.md). Producer plugins extend `ActivityKindMap` with their opaque id namespace and may link an activity to its tool call and background job through `ActivityCorrelation`. + +The registry is a pure observation plane: it starts nothing, cancels nothing, and is invisible to the model. Producers keep their execution resources and their existing model-facing surfaces; a composition without this seam loses only live observation. + +## Service contract + +- `open(spec): ActivityHandle` validates the kind, label, and exact live owner, then atomically registers the record and returns the producer face: synchronous `append(text, { channel?, gapBefore? })`, `updateDetail(detail)`, and first-wins `end(outcome)`. After `end` — including a teardown force-end — `append` and `updateDetail` log and drop instead of throwing, so a producer's trailing flush cannot break its own teardown. +- `get(id, caller?)` and `list(caller?)` return fresh snapshots. Listing includes only caller-owned and unowned activities; owned access compares the activity's `SessionId` with the caller's, and predictable ids make that fence the boundary. +- `read(id, from, caller?)` returns the retained chunks overlapping `[from, total)` plus the resume offset, without consuming anything. Offsets are absolute UTF-8 byte positions that survive eviction; a reader below the oldest retained byte gets `lossy: true`, never an error. +- `onActivitiesChanged(listener)` observes visible-set changes — opening, detail updates, settlement, owner-disposal removal, and the emptying service disposal commits — so consumers re-read rather than accumulate deltas. `onOutput(listener)` signals stream advancement (one signal per committed append and one at settlement) carrying only the id; a consumer reads from its own cursor. Both deliver owner-relative on the jobs-registry terms and contain every listener. + +`pumpActivityOutput(handle, sources, { pollMs, done })` is the shared pump for producers whose substrate is a non-consuming offset reader (the subprocess `readFrom(fromByte)` family): it copies labeled deltas at a bounded cadence, marks a lossy source read `gapBefore`, and drains once more after `done` settles without ever calling `end()` itself. + +See the [activity subsystem page](../../../docs/subsystems/activity.md) and the [observation-seam Agent Note](../../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md). + +## Model Experience + +None, as the registry carries live observation state for humans and registers no prompt, tool, or session event; activity output becomes model-visible only through the producers' existing tool results and `ctx.jobs` reads. + +#### KV Cache effect + +None; the package never assembles or alters provider requests. + +## Known Limitations and Deferred Work + +- **Records are process-local and live-only** — a Host restart empties every roster while the transcript keeps the producing tool cards; durable replay is a separate design. +- **The observation plane has no cancellation verb** — stopping work stays with the producers and `ctx.jobs`; a panel-initiated kill is blocked on the jobs `reported` contract question recorded in the [web job display Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md). +- **Settled records last until owner disposal** — retention trims their buffers to the settled cap, but the rows themselves are not aged out. diff --git a/packages/activity/activity/README.zh.md b/packages/activity/activity/README.zh.md new file mode 100644 index 0000000000..afe843f40a --- /dev/null +++ b/packages/activity/activity/README.zh.md @@ -0,0 +1,32 @@ +# @deepseek-ai/dsh-activity + +[English](README.md) | 中文 + +流式输出观察契约(`ctx.activities`)。抽象 `ActivityRegistry` 与其词汇类型给所有长时生产者一个发布实时输出与状态的位置,并让任意数量的独立消费者对其做非消费读取;内存实现在 [`dsh-activity-local`](../activity-local/README.zh.md)。生产者插件通过 `ActivityKindMap` 扩展自己的不透明 id 命名空间,并可经 `ActivityCorrelation` 把 activity 关联到它的工具调用与后台 job。 + +注册表是纯观察面:不启动、不取消任何工作,对模型不可见。生产者保留自己的执行资源与既有模型面;不装本 seam 的组合只失去实时观察。 + +## 服务契约 + +- `open(spec): ActivityHandle` 校验 kind、label 与 exact 存活 owner 后原子注册记录并返回生产者句柄:同步的 `append(text, { channel?, gapBefore? })`、`updateDetail(detail)` 与 first-wins 的 `end(outcome)`。`end` 之后——包括 teardown 强制 end——`append` 与 `updateDetail` 记日志后丢弃而不抛错,生产者的收尾 flush 不会砸掉自己的 teardown。 +- `get(id, caller?)` 与 `list(caller?)` 返回全新快照。列表只含调用方拥有与无主的 activity;有主访问比较 activity 的 `SessionId` 与调用方的,id 可预测,这道栅栏即边界。 +- `read(id, from, caller?)` 返回与 `[from, total)` 重叠的保留 chunk 及续读 offset,绝不消费。offset 是跨淘汰稳定的绝对 UTF-8 字节位置;落后于最老保留字节的读者得到 `lossy: true`,永不报错。 +- `onActivitiesChanged(listener)` 观察可见集变化——开启、detail 更新、结算、owner 销毁移除、服务销毁清空——消费者整读而非累积增量。`onOutput(listener)` 发出流推进信号(每次提交的 append 一发、结算再一发),只携带 id;消费者按自己的游标去 read。两者按 jobs 注册表的条款做 owner 相对投递,且每个监听都被容错。 + +`pumpActivityOutput(handle, sources, { pollMs, done })` 是给非消费 offset 读取器型底座(subprocess 的 `readFrom(fromByte)` 家族)的共享泵:按有界节奏复制带标签的增量、把 lossy 的源读取标为 `gapBefore`、在 `done` 结算后再排干一次,且自己绝不调用 `end()`。 + +参见 [activity 子系统页](../../../docs/subsystems/activity.zh.md)与[观察 seam Agent Note](../../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md)。 + +## 模型体验 + +无:注册表只承载面向人的实时观察状态,不注册任何 prompt、工具或会话事件;activity 输出只有经生产者既有的工具结果与 `ctx.jobs` 读取才对模型可见。 + +#### KV Cache 影响 + +无;本包从不组装或改动 provider 请求。 + +## 已知限制与暂缓事项 + +- **记录是进程本地且仅存活期有效**——Host 重启清空全部 roster,而 transcript 侧的生产工具卡片仍在;持久回放是独立设计。 +- **观察面没有取消动词**——停止工作仍属于生产者与 `ctx.jobs`;面板发起的 kill 被 [web job display Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md) 记录的 jobs `reported` 契约问题阻塞。 +- **已结算记录保留到 owner 销毁**——保留策略把缓冲裁到 settled 上限,但行本身不会老化清除。 diff --git a/packages/activity/activity/package.json b/packages/activity/activity/package.json new file mode 100644 index 0000000000..0b381d11fa --- /dev/null +++ b/packages/activity/activity/package.json @@ -0,0 +1,57 @@ +{ + "name": "@deepseek-ai/dsh-activity", + "description": "Streaming-output observation registry (ctx.activities) for the DeepSeek Harness — non-consuming offset reads, bounded retention, and change signals over any long-running producer's live output", + "version": "0.1.1-rc.2", + "publishConfig": { + "access": "public" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/deepseek-ai/deepseek-harness.git", + "directory": "packages/activity/activity" + }, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./invariant": { + "types": "./lib/types/invariant.d.ts", + "default": "./lib/invariant.js" + }, + "./brand": { + "types": "./lib/types/brand.d.ts", + "default": "./lib/types/brand.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/invariant.js", + "lib/types/**/*.js", + "lib/types/**/*.d.ts" + ], + "license": "MIT", + "peerDependencies": { + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-brand": "workspace:^", + "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/dsh-jobs": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/cordis": "workspace:^" + }, + "devDependencies": { + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-brand": "workspace:^", + "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/dsh-jobs": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/cordis": "workspace:^" + } +} diff --git a/packages/activity/activity/src/brand.ts b/packages/activity/activity/src/brand.ts new file mode 100644 index 0000000000..8df786ffb9 --- /dev/null +++ b/packages/activity/activity/src/brand.ts @@ -0,0 +1,28 @@ +/** + * dsh-activity' owned branded id, carried across the registry, the observation + * wire, and correlation metadata on other domains' rows. + * + * It lives in its own leaf because the package root reaches `dsh-agent` + * through the owner and listener signatures, which a Client program cannot + * resolve even as a type. A browser-safe consumer imports the id here; + * `Branded` itself comes from the zero-dependency `@deepseek-ai/dsh-brand`. + * + * @module @deepseek-ai/dsh-activity/brand + */ + +import type { Branded } from '@deepseek-ai/dsh-brand' + +/** + * Identifies one observable activity. The registry generates `-N`; + * predictable ids rely on owner authorization rather than secrecy. + */ +export type ActivityId = Branded<'ActivityId'> + +/** + * Brand a string as a {@link ActivityId}. + * @param id - the raw process-id string (the registry generates `-N`). + * @returns the same string, branded; no validation is performed. + */ +export function ActivityId(id: string): ActivityId { + return id as ActivityId +} diff --git a/packages/activity/activity/src/index.ts b/packages/activity/activity/src/index.ts new file mode 100644 index 0000000000..4e3927abe5 --- /dev/null +++ b/packages/activity/activity/src/index.ts @@ -0,0 +1,138 @@ +/** + * The streaming-output observation Service Definition (`ctx.activities`). An + * activity is one observable unit of long-running work: an append-only bounded + * output stream plus live status, readable by any number of independent + * observers at absolute byte offsets. The registry is a pure observation + * plane — it starts nothing, cancels nothing, and is invisible to the model; + * producers keep their execution resources and their existing model-facing + * surfaces (`ctx.jobs` cursors, tool results). The process-local registry + * lives in `@deepseek-ai/dsh-activity-local`. + * @module @deepseek-ai/dsh-activity + */ + +import { Context, Service } from '@deepseek-ai/cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import type { + ActivitiesChangedListener, ActivityHandle, ActivityId, ActivityOpen, ActivityOutputListener, + ActivityRead, ActivitySnapshot, +} from './types.ts' + +export { ActivityId } from './brand.ts' +export type { + ActivityAppendOptions, + ActivityChannel, + ActivityCorrelation, + ActivitiesChangedListener, + ActivityHandle, + ActivityKind, + ActivityKindMap, + ActivityOpen, + ActivityOutcome, + ActivityOutputChunk, + ActivityOutputListener, + ActivityRead, + ActivitySnapshot, + ActivityStatus, +} from './types.ts' +export { pumpActivityOutput } from './pump.ts' +export type { ActivityPumpOptions, ActivityPumpRead, ActivityPumpSource } from './pump.ts' + +declare module '@deepseek-ai/cordis' { + interface Context { + activities: ActivityRegistry + } +} + +/** + * Abstract streaming-output registry. Subclass, implement the abstract + * methods, and load the subclass as a plugin — it registers as + * `ctx.activities` (one implementation per context; loading a second throws, + * which is cordis' standard duplicate-service behavior). + * + * Implementations must honor these semantics: + * - Observation never consumes. Any number of readers hold their own absolute + * byte offsets; a read changes no cursor and no producer state, so the + * model-facing paths (`ctx.jobs.read()`, tool results) are unaffected. + * - Records outlive producer fibers. Owner disposal ends still-open records + * and removes them; service disposal ends and clears everything. Neither + * awaits a producer — the registry owns no execution resource. + * - Retention is bounded. Appends past the live cap drop the oldest retained + * bytes; a reader below the retained window gets a lossy read, never an + * error. Settlement trims retention to the settled cap. + * - Listener delivery is owner-relative: a listener registered from an + * unscoped context — a host composition's own carrier — sees every owner, + * while one registered under an agent composition's scope sees exactly the + * agents composed under it. Every listener is contained. + */ +export abstract class ActivityRegistry extends Service { + constructor(ctx: Context) { + // `abstract` erases at runtime, so a composition row naming this package + // would register a ctx.activities with no method implementations and fail + // far from the misconfiguration. Fail loud at load instead. + if (new.target === ActivityRegistry) { + throw new Error('@deepseek-ai/dsh-activity is the abstract activity observation seam; load an implementation such as @deepseek-ai/dsh-activity-local instead') + } + super(ctx, 'activities') + } + + /** + * Validate the spec, attach owner cleanup, and atomically register one + * activity. A rejection leaves no id; after return the producer owns the + * handle and the visible set has changed. + * @param spec - activity identity, owner, and correlation. + * @returns the producer face of the registered activity. + */ + abstract open(spec: ActivityOpen): ActivityHandle + + /** + * List caller-owned and unowned activities in registration order without + * exposing another session's labels or output. + * @param caller - reading agent; a non-agent caller sees only unowned activities. + * @returns fresh snapshots. + */ + abstract list(caller?: Agent): ActivitySnapshot[] + + /** + * Return a fresh snapshot. Throws for an unknown or foreign activity. + * @param id - activity to look up. + * @param caller - reading agent checked against the owner. + * @returns a fresh snapshot. + */ + abstract get(id: ActivityId, caller?: Agent): ActivitySnapshot + + /** + * Read retained output from an absolute byte offset without consuming it. + * Resume by passing a previous read's `next`; a foreign offset inside a + * retained chunk returns that whole chunk (its `at` may precede `from`). + * Throws for an unknown or foreign activity or a negative or non-integer + * offset. + * @param id - activity to read. + * @param from - absolute byte offset to read from (0 for the retained head). + * @param caller - reading agent checked against the owner. + * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. + */ + abstract read(id: ActivityId, from: number, caller?: Agent): ActivityRead + + /** + * Register an effect-scoped observer of visible-set changes: opening, + * detail updates, settlement, owner-disposal removal, and the emptying that + * service disposal commits — so an observer re-reads rather than + * accumulating deltas. Listeners are contained and never awaited. + * @param listener - receives the owner whose visible set changed, or + * `undefined` when an unowned activity changed and every caller's set did. + * @returns disposer that unregisters the listener. + */ + abstract onActivitiesChanged(listener: ActivitiesChangedListener): () => void + + /** + * Register an effect-scoped observer of stream advancement — one signal per + * committed append and one at settlement, carrying only the activity id. + * A consumer schedules a {@link read} from its own cursor; the registry + * never pushes payloads. Listeners are contained and never awaited. + * @param listener - receives the id whose stream advanced. + * @returns disposer that unregisters the listener. + */ + abstract onOutput(listener: ActivityOutputListener): () => void +} + +export default ActivityRegistry diff --git a/packages/activity/activity/src/invariant.ts b/packages/activity/activity/src/invariant.ts new file mode 100644 index 0000000000..6753fa7b0e --- /dev/null +++ b/packages/activity/activity/src/invariant.ts @@ -0,0 +1,62 @@ +/** Package-owned process-snapshot invariants. @module @deepseek-ai/dsh-activity/invariant */ + +import type { Context } from '@deepseek-ai/cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants' +import type { ActivitySnapshot } from './types.ts' + +const PACKAGE_NAME = '@deepseek-ai/dsh-activity' +const TERMINAL_STATUSES = new Set(['completed', 'failed', 'killed']) + +/** Cordis companion plugin name. */ +export const name = 'activity-invariant' +/** Service required before the companion can reserve package ownership. */ +export const inject = ['invariants'] + +/** Validate the cross-field relationships in one registry snapshot. */ +/* jscpd:ignore-start -- mirrors the jobs invariant's id/ordinal checks by design; the two registries share the `-N` scheme. */ +function validateSnapshot(snapshot: ActivitySnapshot, fail: InvariantFailure): void { + const id = String(snapshot.id) + const prefix = `${snapshot.kind}-` + const ordinal = Number(id.slice(prefix.length)) + if (snapshot.kind.length === 0 || !id.startsWith(prefix) + || !Number.isSafeInteger(ordinal) || ordinal < 1) { + fail(`activity snapshot id ${JSON.stringify(id)} must be ${JSON.stringify(prefix)} followed by a positive ordinal`) + } + if (snapshot.label.length === 0) fail(`activity ${JSON.stringify(id)} label must be non-empty`) + if (!Number.isSafeInteger(snapshot.startedAt) || snapshot.startedAt < 0) { + fail(`activity ${JSON.stringify(id)} startedAt must be a non-negative epoch integer`) + } + /* jscpd:ignore-end */ + + const terminal = TERMINAL_STATUSES.has(snapshot.status) + if (terminal !== (snapshot.finishedAt !== undefined)) { + fail(`activity ${JSON.stringify(id)} finishedAt must be present exactly for a terminal status`) + } + if (snapshot.finishedAt !== undefined + && (!Number.isSafeInteger(snapshot.finishedAt) || snapshot.finishedAt < snapshot.startedAt)) { + fail(`activity ${JSON.stringify(id)} finishedAt must be an epoch integer no earlier than startedAt`) + } + + if (!Number.isSafeInteger(snapshot.outputTotal) || snapshot.outputTotal < 0 + || !Number.isSafeInteger(snapshot.outputEarliest) || snapshot.outputEarliest < 0 + || snapshot.outputEarliest > snapshot.outputTotal) { + fail(`activity ${JSON.stringify(id)} output offsets must satisfy 0 <= outputEarliest <= outputTotal`) + } +} + +/** Install checks over current visible records and every later visible-set change. */ +const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => { + for (const snapshot of ctx.activities.list()) validateSnapshot(snapshot, fail) + ctx.activities.onActivitiesChanged((owner: Agent | undefined) => { + for (const snapshot of ctx.activities.list(owner)) validateSnapshot(snapshot, fail) + }) +}, { inject: ['activities'] }) + +/** + * Register the process-registry invariant companion. + * @param ctx - Cordis context carrying the invariant service. + * @returns the installed registration's disposer after setup succeeds. + */ +export const apply = (ctx: Context): Promise<() => void> => + Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install)) diff --git a/packages/activity/activity/src/pump.ts b/packages/activity/activity/src/pump.ts new file mode 100644 index 0000000000..4cc1eae22d --- /dev/null +++ b/packages/activity/activity/src/pump.ts @@ -0,0 +1,95 @@ +/** + * Shared poll pump for producers whose output substrate is a non-consuming + * offset reader (the subprocess `readFrom(fromByte)` family). Pure utility — + * no cordis, no timers retained past settlement. + * @module + */ + +import type { ActivityChannel, ActivityHandle } from './types.ts' + +/** One non-consuming offset read from a producer-owned stream. */ +export interface ActivityPumpRead { + /** Text captured since the requested offset (the whole retained tail when lossy). */ + text: string + /** Whole-stream offset to resume from on the next read. */ + nextOffset: number + /** True when the requested offset slid out of the source's retained window. */ + lossy: boolean +} + +/** One producer-owned stream the pump copies into a process. */ +export interface ActivityPumpSource { + /** Stream label attached to every chunk this source yields. */ + channel?: ActivityChannel + /** + * Read everything captured since `fromByte` without consuming it. + * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 first). + * @returns the delta text, the next offset, and the lossy flag. + */ + read(fromByte: number): ActivityPumpRead +} + +/** Cadence and settlement for one {@link pumpActivityOutput} run. */ +export interface ActivityPumpOptions { + /** Poll interval in milliseconds; a positive finite number. */ + pollMs: number + /** + * Settles when the producer's work finished and its sources hold their + * final bytes. The pump drains once more after settlement and returns; + * a rejection is treated as settlement. + */ + done: Promise +} + +/** + * Copy producer streams into a process at a bounded cadence: drain every + * source, sleep `pollMs` or until `done` settles, repeat, then drain one + * final time. A lossy source read appends its surviving tail with + * `gapBefore`, so the discontinuity stays visible to observers. The pump + * never calls `handle.end()` — the producer maps its own outcome. + * @param handle - the open process receiving the copied chunks. + * @param sources - producer streams, each pumped at its own offset. + * @param options - poll cadence and the producer's settlement promise. + * @returns resolves after the final post-settlement drain. + */ +export async function pumpActivityOutput( + handle: ActivityHandle, + sources: readonly ActivityPumpSource[], + options: ActivityPumpOptions, +): Promise { + if (!Number.isFinite(options.pollMs) || options.pollMs <= 0) { + throw new Error(`invalid pump pollMs: expected a positive finite number of milliseconds, got ${JSON.stringify(options.pollMs)}`) + } + const states = sources.map(source => ({ source, cursor: 0 })) + const drain = (): void => { + for (const state of states) { + const { source } = state + const read = source.read(state.cursor) + state.cursor = read.nextOffset + if (read.text.length === 0) continue + if (source.channel === undefined && !read.lossy) { + handle.append(read.text) + } else { + handle.append(read.text, { + ...source.channel !== undefined ? { channel: source.channel } : {}, + ...read.lossy ? { gapBefore: true as const } : {}, + }) + } + } + } + let settled = false + const settlement = options.done.then(() => { settled = true }, () => { settled = true }) + while (!settled) { + drain() + await Promise.race([ + new Promise((resolve) => { + const timer = setTimeout(resolve, options.pollMs) + // The settlement branch wins the race; clear the loser so a finished + // pump holds no pending timer for up to one poll interval. + void settlement.then(() => { clearTimeout(timer); resolve() }) + }), + settlement, + ]) + } + drain() +} diff --git a/packages/activity/activity/src/types.ts b/packages/activity/activity/src/types.ts new file mode 100644 index 0000000000..fd748ec165 --- /dev/null +++ b/packages/activity/activity/src/types.ts @@ -0,0 +1,179 @@ +import type { Agent } from '@deepseek-ai/dsh-agent' +import type { SessionId } from '@deepseek-ai/dsh-session' +import type { CallId } from '@deepseek-ai/dsh-llm/brand' +import type { JobId } from '@deepseek-ai/dsh-jobs/brand' +import type { ActivityId } from './brand.ts' + +export type { ActivityId } from './brand.ts' + +/** + * Producer-defined activity kinds. Plugins extend this map by declaration + * merging; the registry treats every value as an opaque id namespace. + */ +export interface ActivityKindMap { + bash: 'bash' +} + +/** A registered activity kind — also the id prefix (`bash`, `workflow`, …). */ +export type ActivityKind = ActivityKindMap[keyof ActivityKindMap] + +/** Lifecycle state of one observable activity. */ +export type ActivityStatus = 'running' | 'completed' | 'failed' | 'killed' + +/** + * Output stream label. Producers without distinct streams omit it; consumers + * treat an unrecognized label like an absent one. + */ +export type ActivityChannel = 'stdout' | 'stderr' + +/** + * Links one activity to the records other domains keep for the same work, so a + * consumer can attach the output stream to an existing card or row without + * guessing from labels. + */ +export interface ActivityCorrelation { + /** Tool call that started the work, when a tool produced it. */ + callId?: CallId + /** Background job carrying the model-facing control surface, when one exists. */ + jobId?: JobId +} + +/** + * Producer declaration passed to {@link ActivityRegistry.open}. The registry + * owns identity, retention, and observer delivery; the producer keeps its + * execution resources and reports through the returned {@link ActivityHandle}. + */ +export interface ActivityOpen { + /** Producer kind — also the id prefix. */ + kind: ActivityKind + /** One-line human-facing label (the command; the run description). */ + label: string + /** + * Owning live agent. Visibility is fenced by its session id, and agent + * disposal ends and removes the record. The instance must be the one + * currently registered under its agent id. Omitting the owner creates an + * unowned activity, visible to any caller until service disposal. + */ + owner?: Agent + /** Optional links to the tool call and background job for the same work. */ + correlation?: ActivityCorrelation +} + +/** Terminal outcome reported through {@link ActivityHandle.end}. */ +export interface ActivityOutcome { + /** How the work ended: finished (`completed`), broke (`failed`), or was cancelled (`killed`). */ + status: 'completed' | 'failed' | 'killed' + /** Kind-specific detail rendered into status lines ('exit code: 3'). */ + detail?: string +} + +/** Options for one {@link ActivityHandle.append}. */ +export interface ActivityAppendOptions { + /** Stream label for the chunk; omitted for producers without distinct streams. */ + channel?: ActivityChannel + /** + * Marks that producer-side bytes between the previous chunk and this one + * were lost (a source window slid before the producer could copy it), so a + * consumer can render the discontinuity instead of a silent splice. + */ + gapBefore?: true +} + +/** + * Producer face of one open activity. All methods are synchronous. After + * {@link end} — including a registry-forced end during owner or service + * teardown — `append` and `updateDetail` log and drop instead of throwing, so + * a producer's trailing flush cannot break its own teardown path. + */ +export interface ActivityHandle { + /** The registry-issued id (`-N`). */ + readonly id: ActivityId + /** + * Append one output chunk. Offsets advance by the chunk's UTF-8 byte + * length; an empty chunk is dropped without waking observers. + * @param text - the chunk text, exactly as produced. + * @param options - stream label and gap marker. + */ + append(text: string, options?: ActivityAppendOptions): void + /** + * Replace the snapshot's status detail (a progress line such as `3/10`). + * @param detail - the new detail line. + */ + updateDetail(detail: string): void + /** + * Record the terminal outcome and trim retention to the settled cap. + * First-wins: a later call — the producer's own report after a teardown + * force-end, or a duplicate — is dropped silently. + * @param outcome - terminal status and optional detail. + */ + end(outcome: ActivityOutcome): void +} + +/** + * A read-only projection of one activity, safe to hand to listeners and + * consumers — a fresh object per call, never live registry state. + */ +export interface ActivitySnapshot { + /** The registry-issued id (`-N`). */ + id: ActivityId + /** The producer kind the process was opened with. */ + kind: ActivityKind + /** The producer-supplied one-line label. */ + label: string + /** Owner session id used for visibility and grouping; absent for unowned activities. */ + ownerSession?: SessionId + /** Links to the tool call and background job for the same work, when supplied. */ + correlation?: ActivityCorrelation + /** Current lifecycle state. */ + status: ActivityStatus + /** Kind-specific status detail, when the producer supplied one. */ + detail?: string + /** Epoch ms when the activity was opened. */ + startedAt: number + /** Epoch ms when the activity ended; absent while `running`. */ + finishedAt?: number + /** Total UTF-8 bytes ever appended — the offset the next chunk starts at. */ + outputTotal: number + /** + * Offset of the oldest retained byte. Greater than zero exactly when + * retention dropped the head; a reader starting below it gets a lossy read. + */ + outputEarliest: number +} + +/** One retained output chunk returned by {@link ActivityRegistry.read}. */ +export interface ActivityOutputChunk { + /** Absolute offset of the chunk's first byte. */ + at: number + /** Chunk text exactly as appended (possibly tail-trimmed by retention). */ + text: string + /** Stream label, when the producer supplied one. */ + channel?: ActivityChannel + /** Producer-reported loss immediately before this chunk. */ + gapBefore?: true +} + +/** Result of one non-consuming {@link ActivityRegistry.read}. */ +export interface ActivityRead { + /** Retained chunks overlapping `[from, total)`, in offset order. */ + chunks: readonly ActivityOutputChunk[] + /** Offset to resume from — the process' current `outputTotal`. */ + next: number + /** True when `from` fell below the oldest retained byte, so bytes are missing before `chunks`. */ + lossy: boolean +} + +/** + * Observer of visible-set changes: opening, detail updates, settlement, and + * removal. Receives the owner whose set changed, or `undefined` when an + * unowned process changed and every caller's set did. Consumers re-read + * rather than accumulating deltas. + */ +export type ActivitiesChangedListener = (owner: Agent | undefined) => void + +/** + * Observer of stream advancement for one activity: new appended output, or the + * settlement that ends the stream. Carries no payload — a consumer schedules a + * {@link ActivityRegistry.read} from its own cursor. + */ +export type ActivityOutputListener = (id: ActivityId) => void diff --git a/packages/activity/activity/tests/invariant.spec.ts b/packages/activity/activity/tests/invariant.spec.ts new file mode 100644 index 0000000000..306cd4533a --- /dev/null +++ b/packages/activity/activity/tests/invariant.spec.ts @@ -0,0 +1,82 @@ +import { describe, expect, it } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import ActivityRegistry, { ActivityId } from '@deepseek-ai/dsh-activity' +import type { ActivitiesChangedListener, ActivitySnapshot } from '@deepseek-ai/dsh-activity' +import * as ProcessInvariant from '@deepseek-ai/dsh-activity/invariant' +import InvariantRegistry from '@deepseek-ai/dsh-invariants' + +const BASE: ActivitySnapshot = { + id: ActivityId('bash-1'), + kind: 'bash', + label: 'compile', + status: 'completed', + startedAt: 10, + finishedAt: 20, + outputTotal: 12, + outputEarliest: 4, +} + +const RUNNING: ActivitySnapshot = { + id: ActivityId('bash-1'), + kind: 'bash', + label: 'compile', + status: 'running', + startedAt: 10, + outputTotal: 0, + outputEarliest: 0, +} + +/** Boot the companion over a probe registry whose visible set the test controls. */ +async function setup(seed: ActivitySnapshot[] = []): Promise<(visible: ActivitySnapshot[], owner?: Agent) => void> { + const ctx = new Context() + let current = seed + let listener: ActivitiesChangedListener | undefined + const probe = { + list: () => current, + onActivitiesChanged(value: ActivitiesChangedListener) { + listener = value + return () => { listener = undefined } + }, + } as unknown as ActivityRegistry + await ctx.plugin(InvariantRegistry) + await ctx.plugin({ + name: 'activity-invariant-probe', + apply(child: Context) { child.provide('activities', probe) }, + }) + await ctx.plugin(ProcessInvariant) + if (listener === undefined) throw new Error('activity invariant did not subscribe to visible-set changes') + return (visible, owner) => { + current = visible + listener!(owner) + } +} + +describe('process-registry invariants', () => { + it('accepts coherent running and terminal snapshots', async () => { + const notify = await setup([RUNNING]) + expect(() => { notify([BASE]) }).not.toThrow() + expect(() => { notify([{ ...BASE, id: ActivityId('workflow-2'), kind: 'workflow' }]) }) + .not.toThrow() + }) + + it.each([ + [{ ...BASE, id: ActivityId('-1'), kind: '' as ActivitySnapshot['kind'] }, /positive ordinal/], + [{ ...BASE, id: ActivityId('other-1') }, /must be "bash-" followed by a positive ordinal/], + [{ ...BASE, id: ActivityId('bash-0') }, /positive ordinal/], + [{ ...BASE, label: '' }, /label must be non-empty/], + [{ ...BASE, startedAt: -1 }, /startedAt must be a non-negative epoch integer/], + [{ ...BASE, status: 'running' as const, finishedAt: 20 }, /finishedAt must be present exactly for a terminal status/], + [{ ...RUNNING, status: 'killed' as const }, /finishedAt must be present exactly for a terminal status/], + [{ ...BASE, finishedAt: 9 }, /no earlier than startedAt/], + [{ ...BASE, outputEarliest: 13 }, /0 <= outputEarliest <= outputTotal/], + [{ ...BASE, outputTotal: -1, outputEarliest: 0 }, /0 <= outputEarliest <= outputTotal/], + ] as const)('rejects an incoherent registry snapshot', async (snapshot, message) => { + const notify = await setup() + expect(() => { notify([snapshot]) }).toThrow(message) + }) + + it('rejects an incoherent record already present at installation', async () => { + await expect(setup([{ ...BASE, label: '' }])).rejects.toThrow(/label must be non-empty/) + }) +}) diff --git a/packages/activity/activity/tests/service.spec.ts b/packages/activity/activity/tests/service.spec.ts new file mode 100644 index 0000000000..2dd685c1d3 --- /dev/null +++ b/packages/activity/activity/tests/service.spec.ts @@ -0,0 +1,98 @@ +import { describe, expect, expectTypeOf, it, vi } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import type { SessionId } from '@deepseek-ai/dsh-session' +import ActivityRegistry, { ActivityId, pumpActivityOutput } from '@deepseek-ai/dsh-activity' +import type { ActivityAppendOptions, ActivityHandle, ActivityPumpSource, ActivitySnapshot } from '@deepseek-ai/dsh-activity' + +/** Record every append so pump behavior is observable without a registry. */ +function recordingHandle(): { handle: ActivityHandle; appends: { text: string; options?: ActivityAppendOptions }[] } { + const appends: { text: string; options?: ActivityAppendOptions }[] = [] + const handle: ActivityHandle = { + id: ActivityId('bash-1'), + append(text, options) { appends.push({ text, ...options !== undefined ? { options } : {} }) }, + updateDetail() {}, + end() {}, + } + return { handle, appends } +} + +/** A scripted source: each read() shifts the next scripted result. */ +function scriptedSource( + reads: { text: string; lossy?: boolean }[], + channel?: 'stdout' | 'stderr', +): { source: ActivityPumpSource; offsets: number[] } { + const offsets: number[] = [] + let offset = 0 + const source: ActivityPumpSource = { + ...channel !== undefined ? { channel } : {}, + read(fromByte) { + offsets.push(fromByte) + const next = reads.shift() ?? { text: '' } + offset += Buffer.byteLength(next.text, 'utf8') + return { text: next.text, nextOffset: offset, lossy: next.lossy ?? false } + }, + } + return { source, offsets } +} + +describe('ActivityRegistry seam', () => { + it('refuses to mount the abstract Service Definition directly', async () => { + const ctx = new Context() + await expect(ctx.plugin(ActivityRegistry as unknown as () => void)) + .rejects.toThrow(/load an implementation such as @deepseek-ai\/dsh-activity-local/) + }) + + it('preserves the SessionId brand on public owner snapshots', () => { + expectTypeOf().toEqualTypeOf() + }) +}) + +describe('pumpActivityOutput', () => { + it('rejects a non-positive poll interval before touching any source', async () => { + const { handle } = recordingHandle() + await expect(pumpActivityOutput(handle, [], { pollMs: 0, done: Promise.resolve() })) + .rejects.toThrow(/invalid pump pollMs/) + }) + + it('copies labeled deltas at the poll cadence and resumes each source at its own offset', async () => { + vi.useFakeTimers() + try { + const { handle, appends } = recordingHandle() + let settle!: () => void + const done = new Promise((resolve) => { settle = resolve }) + const out = scriptedSource([{ text: 'a' }, { text: 'bc' }], 'stdout') + const err = scriptedSource([{ text: '' }, { text: 'E' }], 'stderr') + const pump = pumpActivityOutput(handle, [out.source, err.source], { pollMs: 50, done }) + + await vi.advanceTimersByTimeAsync(50) + settle() + await pump + expect(appends).toEqual([ + { text: 'a', options: { channel: 'stdout' } }, + { text: 'bc', options: { channel: 'stdout' } }, + { text: 'E', options: { channel: 'stderr' } }, + ]) + // Every read resumed from the previous nextOffset, never from a shared cursor. + expect(out.offsets).toEqual([0, 1, 3]) + expect(err.offsets).toEqual([0, 0, 1]) + // Settlement cleared the raced poll timer instead of leaving it pending. + expect(vi.getTimerCount()).toBe(0) + } finally { + vi.useRealTimers() + } + }) + + it('marks a lossy source read as a gap so observers see the discontinuity', async () => { + const { handle, appends } = recordingHandle() + const { source } = scriptedSource([{ text: 'tail', lossy: true }]) + await pumpActivityOutput(handle, [source], { pollMs: 1, done: Promise.resolve() }) + expect(appends).toEqual([{ text: 'tail', options: { gapBefore: true } }]) + }) + + it('treats a rejected done as settlement and still drains the final bytes', async () => { + const { handle, appends } = recordingHandle() + const { source } = scriptedSource([{ text: 'last' }]) + await pumpActivityOutput(handle, [source], { pollMs: 1, done: Promise.reject(new Error('producer broke')) }) + expect(appends).toEqual([{ text: 'last' }]) + }) +}) diff --git a/packages/activity/activity/tsconfig.json b/packages/activity/activity/tsconfig.json new file mode 100644 index 0000000000..f4deee6327 --- /dev/null +++ b/packages/activity/activity/tsconfig.json @@ -0,0 +1,36 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../util/brand" + }, + { + "path": "../../core/agent" + }, + { + "path": "../../core/session" + }, + { + "path": "../../llm/llm" + }, + { + "path": "../../jobs/jobs" + }, + { + "path": "../../runtime-diagnostics/invariants" + } + ] +} diff --git a/packages/api/activity-controller/README.i18n.yaml b/packages/api/activity-controller/README.i18n.yaml new file mode 100644 index 0000000000..e49b392e32 --- /dev/null +++ b/packages/api/activity-controller/README.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 packages/api/activity-controller/README.md +README.md: 10885ec087cc295df6bcb033480373db04938097 +README.zh.md: 9509837baa4661209c7d826bee149b76a11f4723 diff --git a/packages/api/activity-controller/README.md b/packages/api/activity-controller/README.md new file mode 100644 index 0000000000..10885ec087 --- /dev/null +++ b/packages/api/activity-controller/README.md @@ -0,0 +1,30 @@ +# @deepseek-ai/dsh-api-activity-controller + +English | [中文](README.zh.md) + +Activity Remote streams over the optional `ctx.activities` registry, plus their React-free client model. A pure read surface: it starts nothing, cancels nothing, and never touches the model-facing consuming cursors — the wire path reads only the registry's non-consuming offsets. + +The Host `ActivityController` (namespace `activity`) exposes two `@Remote({ mode: 'stream' })` methods: + +- `control(signal)` — one complete roster baseline, then whole-bucket replacement frames per owner session on every registry change (the self-healing shape the session control stream uses for jobs). A composition without the registry serves an empty baseline. +- `observe({ activityId, from? }, signal)` — one `opened` anchor, coalesced `output` frames (`flushMs` window, `maxFrameBytes` soft budget; one larger chunk ships whole), then one terminal `status` after the settled activity is drained, after which the generation closes normally. Reconnecting callers resume by passing the last frame's `next`; a resume behind the retained window arrives flagged `lossy`. Status rides the same stream as output, so settlement can never race a still-open output channel. + +| Config | Default | Meaning | +|---|---|---| +| `flushMs` | `100` | Coalescing window after new output before an observation read. | +| `maxFrameBytes` | `65536` | Soft byte budget per observation output frame. | + +The client half (`./client`) installs `ctx.activityFeed`: `ClientActivityModel` mirrors the roster (last-wins buckets, generation replace) and accumulates each observed activity's bounded render tail, and `ClientActivityFeed.observe(id)` opens reference-counted observation streams that resume from the model's cursor across carrier generations. + +## Model Experience + +None, as activity transport is browser and Host observation state and registers no prompt, tool, or session event. + +#### KV Cache effect + +None; the package never assembles or alters provider requests. + +## Known Limitations and Deferred Work + +- **Registry presence is sampled at construction** — a registry mounted after the controller stays unobserved until the controller reloads. +- **The roster names no watermark** — an observation stream anchors itself; correlating roster rows against observation offsets is client policy. diff --git a/packages/api/activity-controller/README.zh.md b/packages/api/activity-controller/README.zh.md new file mode 100644 index 0000000000..9509837baa --- /dev/null +++ b/packages/api/activity-controller/README.zh.md @@ -0,0 +1,30 @@ +# @deepseek-ai/dsh-api-activity-controller + +[English](README.md) | 中文 + +架在可选 `ctx.activities` 注册表之上的 Activity Remote 流,附 React-free 客户端模型。纯读面:不启动、不取消任何工作,也绝不触碰模型侧消费游标——wire 路径只读注册表的非消费 offset。 + +宿主 `ActivityController`(命名空间 `activity`)暴露两个 `@Remote({ mode: 'stream' })` 方法: + +- `control(signal)`——一份完整 roster baseline,之后每次注册表变化按 owner 会话推送整桶替换帧(与 session control 流承载 jobs 的自愈形态一致)。没有注册表的组合返回空 baseline。 +- `observe({ activityId, from? }, signal)`——一帧 `opened` 锚点,随后是合并的 `output` 帧(`flushMs` 窗口、`maxFrameBytes` 软预算;更大的单 chunk 整帧发出),activity 结算且排干后发一帧终态 `status`,然后本代正常关闭。重连方以上一帧的 `next` 作为 `from` 续传;落后于保留窗口的续传会带 `lossy` 标记。状态与输出同流,结算永远不会与仍开着的输出通道竞态。 + +| 配置 | 默认值 | 含义 | +|---|---|---| +| `flushMs` | `100` | 新输出到达后、观察读取前的合并窗口。 | +| `maxFrameBytes` | `65536` | 每个观察输出帧的软字节预算。 | + +客户端半区(`./client`)安装 `ctx.activityFeed`:`ClientActivityModel` 镜像 roster(last-wins 分桶、按代整体替换)并为每个被观察 activity 累积有界渲染尾巴;`ClientActivityFeed.observe(id)` 打开按引用计数共享的观察流,跨 carrier 代次从模型游标续传。 + +## 模型体验 + +无:activity 传输是浏览器与宿主的观察状态,不注册任何 prompt、工具或会话事件。 + +#### KV Cache 影响 + +无;本包从不组装或改动 provider 请求。 + +## 已知限制与暂缓事项 + +- **注册表存在性在构造时采样**——控制器之后才挂载的注册表在控制器重载前不会被观察。 +- **roster 不携带水位**——观察流自带锚点;roster 行与观察 offset 的对齐是客户端策略。 diff --git a/packages/api/activity-controller/package.json b/packages/api/activity-controller/package.json new file mode 100644 index 0000000000..6898cff505 --- /dev/null +++ b/packages/api/activity-controller/package.json @@ -0,0 +1,103 @@ +{ + "name": "@deepseek-ai/dsh-api-activity-controller", + "description": "Activity Remote streams: the live-activity roster and per-activity non-consuming output observation", + "version": "0.1.1-rc.2", + "publishConfig": { + "access": "public" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/deepseek-ai/deepseek-harness.git", + "directory": "packages/api/activity-controller" + }, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./invariant": { + "types": "./lib/types/invariant.d.ts", + "default": "./lib/invariant.js" + }, + "./types": { + "types": "./lib/types/types.d.ts", + "default": "./lib/types/types.js" + }, + "./client": { + "types": "./lib/types/client/index.d.ts", + "default": "./lib/client.js" + }, + "./typert": { + "types": "./lib/typert.host.d.ts", + "default": "./lib/typert.host.js" + }, + "./remote": { + "types": "./lib/typert.remote-client.d.ts", + "default": "./lib/typert.remote-client.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "scripts": { + "bundle": "tsdown", + "watch": "tsdown --watch" + }, + "files": [ + "lib/index.js", + "lib/invariant.js", + "lib/client.js", + "lib/types/**/*.js", + "lib/types/**/*.d.ts", + "lib/typert.host.js", + "lib/typert.host.d.ts", + "lib/typert.remote-client.js", + "lib/typert.remote-client.d.ts" + ], + "license": "MIT", + "dependencies": { + "@deepseek-ai/schemastery": "workspace:^", + "zod": "^4.4.3" + }, + "peerDependencies": { + "@deepseek-ai/cordis": "workspace:^", + "@deepseek-ai/dsh-activity": "workspace:^", + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-api-gateway": "workspace:^", + "@deepseek-ai/dsh-client-connection": "workspace:^", + "@deepseek-ai/dsh-client-store": "workspace:^", + "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/dsh-jobs": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-typert-protocol": "workspace:^" + }, + "devDependencies": { + "@deepseek-ai/cordis": "workspace:^", + "@deepseek-ai/dsh-activity": "workspace:^", + "@deepseek-ai/dsh-activity-local": "workspace:^", + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-api-gateway": "workspace:^", + "@deepseek-ai/dsh-client-connection": "workspace:^", + "@deepseek-ai/dsh-client-store": "workspace:^", + "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/dsh-jobs": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-typert-protocol": "workspace:^" + }, + "dsh": { + "client": { + "external": [ + "@deepseek-ai/dsh-api-gateway/client" + ], + "inject": [ + "@deepseek-ai/dsh-api-gateway", + "@deepseek-ai/dsh-client-connection" + ], + "platform": "web" + } + } +} diff --git a/packages/api/activity-controller/src/client/index.ts b/packages/api/activity-controller/src/client/index.ts new file mode 100644 index 0000000000..7338ae3b9b --- /dev/null +++ b/packages/api/activity-controller/src/client/index.ts @@ -0,0 +1,86 @@ +/** Activity-specific adapter for the Gateway-owned snapshot stream lifecycle. */ + +import type { Context } from '@deepseek-ai/cordis' +import { + RemoteSnapshotStream, + RemoteStreamCarrierError, + type ClientRemote, +} from '@deepseek-ai/dsh-api-gateway/client' +import type { ActivityControlFrame } from '../types.ts' +import { ClientActivityModel } from './model.ts' +import { ClientActivityFeed } from './service.ts' +import type { ActivityRemote } from './service.ts' + +export type { ActivityFeedPhase, ActivityFeedSnapshot, ObservedActivity } from './model.ts' +export type { ActivityFeedSource, ActivityRemote, IActivityFeed } from './service.ts' +export type { ActivityId } from '@deepseek-ai/dsh-activity/brand' +export type { ActivityRow } from '../types.ts' + +type ActivityStreamRemote = Pick & { readonly activity: ActivityRemote } + +type ActivityBaselineFrame = Extract +type ActivityRowsFrame = Extract + +declare module '@deepseek-ai/cordis' { + interface Context { + /** React-free client activity roster and observation control. */ + activityFeed: import('./service.ts').IActivityFeed + } +} + +/** Required Client Remote services. */ +export const inject = ['remote', 'remote.activity'] + +/** + * Install the client activity model, its service face, and the reconnecting + * roster stream. + * @param ctx - client root Context. + */ +export function apply(ctx: Context): void { + const raw = ctx.remote as ActivityStreamRemote + // Resolve the child namespace to a concrete value while this plugin's + // context is current: later stream (re)opens run on caller stacks (a React + // event, a carrier retry) whose dynamic context has not declared + // `remote.activity`, and a property access there fails the inject check. + const remote: ActivityStreamRemote = { + $stream: options => raw.$stream(options), + activity: raw.activity, + } + const model = new ClientActivityModel() + new ClientActivityFeed(ctx, remote, model) + const control = createActivityRosterStream(remote, model) + control.start() + ctx.effect( + () => async () => { await control.dispose() }, + 'activity-controller.client.control', + ) +} + +/** + * Create the reconnecting roster stream feeding one client model. + * @param remote - generated activity namespace and Gateway stream factory. + * @param model - roster sink. + * @returns an unstarted stream owned by the client activity runtime. + */ +export function createActivityRosterStream( + remote: ActivityStreamRemote, + model: ClientActivityModel, +): RemoteSnapshotStream { + const stream = remote.$stream({ + name: 'activity roster stream', + open: signal => remote.activity.control(signal), + ended: accepted => accepted + ? new RemoteStreamCarrierError('activity roster stream ended without a terminal result') + : new Error('activity roster stream ended before its opening baseline'), + }) + return new RemoteSnapshotStream(stream, { + name: 'activity roster stream', + isSnapshot: (frame): frame is ActivityBaselineFrame => frame.type === 'baseline', + replace: (frame) => { model.replaceBaseline(frame.activities) }, + update: (frame) => { model.replaceBucket(frame.sessionId, frame.activities) }, + failed: () => { + // The previous roster stays published while the stream retries; a + // terminal protocol failure leaves the last snapshot in place. + }, + }) +} diff --git a/packages/api/activity-controller/src/client/model.ts b/packages/api/activity-controller/src/client/model.ts new file mode 100644 index 0000000000..96fb7cca5a --- /dev/null +++ b/packages/api/activity-controller/src/client/model.ts @@ -0,0 +1,211 @@ +/** Client-side activity state model shared by Remote transport and UI projection. */ + +import { notifySubscribers } from '@deepseek-ai/dsh-client-store' +import type { ActivityId } from '@deepseek-ai/dsh-activity/brand' +import type { ActivityObserveFrame, ActivityRow } from '../types.ts' + +/** Bounded per-activity render tail, in UTF-16 code units. */ +const RENDER_TAIL_LIMIT = 128 * 1024 + +/** Roster arrival lifecycle: `pending` until the first baseline lands. */ +export type ActivityFeedPhase = 'pending' | 'ready' + +/** One observed activity's live view state. */ +export interface ObservedActivity { + readonly activityId: ActivityId + /** Accumulated output tail, bounded to the render limit. */ + readonly text: string + /** True when bytes before {@link text} were dropped (eviction, resume gap, or the render bound). */ + readonly gapBefore: boolean + /** Latest status delivered on the observation stream. */ + readonly status: ActivityRow['status'] + readonly detail?: string + /** True while the observation stream is open and the activity has not settled. */ + readonly streaming: boolean + /** Terminal observation failure, when the stream ended abnormally. */ + readonly error?: string +} + +/** Immutable client activity state. */ +export interface ActivityFeedSnapshot { + /** Roster rows per owner session; the empty key holds unowned activities. */ + readonly rowsBySession: Readonly> + /** Live observation state keyed by activity id. */ + readonly observed: Readonly> + readonly phase: ActivityFeedPhase +} + +const UNOWNED = '' + +/** Mutable observation bookkeeping behind one {@link ObservedActivity} view. */ +interface ObservedState { + view: ObservedActivity + /** Resume offset for the next generation's `from`. */ + cursor: number | undefined +} + +/** + * Owns the client roster mirror and per-activity observation state. Pure data + * plus subscriptions — transport wiring stays in the client plugin, UI stays + * in slot components. + */ +export class ClientActivityModel { + private rowsBySession: Readonly> = {} + private readonly observedStates = new Map() + private phase: ActivityFeedPhase = 'pending' + private readonly listeners = new Set<() => void>() + private snapshotCache: ActivityFeedSnapshot = { rowsBySession: {}, observed: {}, phase: 'pending' } + private snapshotDirty = false + + /** + * Read the identity-stable current snapshot. + * @returns the cached snapshot, rebuilt only after a change. + */ + getSnapshot(): ActivityFeedSnapshot { + if (this.snapshotDirty) { + const observed: Record = {} + for (const [id, state] of this.observedStates) observed[id] = state.view + this.snapshotCache = { rowsBySession: this.rowsBySession, observed, phase: this.phase } + this.snapshotDirty = false + } + return this.snapshotCache + } + + /** + * Subscribe to snapshot changes. + * @param listener - invalidation callback. + * @returns unsubscribe function. + */ + subscribe(listener: () => void): () => void { + this.listeners.add(listener) + return () => { this.listeners.delete(listener) } + } + + /** + * Replace the whole roster from a generation baseline. + * @param rows - every visible row across all owner buckets. + */ + replaceBaseline(rows: readonly ActivityRow[]): void { + const next: Record = {} + for (const row of rows) { + const key = row.sessionId ?? UNOWNED + ;(next[key] ??= []).push(row) + } + this.rowsBySession = next + this.phase = 'ready' + this.changed() + } + + /** + * Replace one owner bucket wholesale; an empty replacement drops the key. + * @param sessionId - owner session, or undefined for the unowned bucket. + * @param rows - the bucket's complete visible rows. + */ + replaceBucket(sessionId: string | undefined, rows: readonly ActivityRow[]): void { + const key = sessionId ?? UNOWNED + if (rows.length === 0) { + this.rowsBySession = Object.fromEntries( + Object.entries(this.rowsBySession).filter(([bucket]) => bucket !== key)) + } else { + this.rowsBySession = { ...this.rowsBySession, [key]: rows } + } + this.changed() + } + + /** + * The resume offset for one activity's next observation generation. + * @param id - observed activity. + * @returns the last accepted `next`, or undefined for a fresh observation. + */ + cursorOf(id: ActivityId): number | undefined { + return this.observedStates.get(String(id))?.cursor + } + + /** + * Install or reset observation state when a generation's anchor arrives. + * @param id - observed activity. + * @param frame - the generation's `opened` anchor. + */ + observeOpened(id: ActivityId, frame: Extract): void { + const existing = this.observedStates.get(String(id)) + const view: ObservedActivity = { + activityId: id, + text: existing?.view.text ?? '', + gapBefore: (existing?.view.gapBefore ?? false) || frame.from < frame.earliest, + status: frame.status, + ...frame.detail !== undefined ? { detail: frame.detail } : {}, + streaming: true, + } + this.observedStates.set(String(id), { view, cursor: frame.from }) + this.changed() + } + + /** + * Append one output frame's chunks to the bounded render tail. + * @param id - observed activity. + * @param frame - a coalesced `output` frame. + */ + observeOutput(id: ActivityId, frame: Extract): void { + const state = this.observedStates.get(String(id)) + /* v8 ignore next -- frames arrive only between opened and stop for a tracked id. */ + if (state === undefined) return + let text = state.view.text + frame.chunks.map(chunk => chunk.text).join('') + let gapBefore = state.view.gapBefore || frame.lossy === true + || frame.chunks.some(chunk => chunk.gapBefore === true) + if (text.length > RENDER_TAIL_LIMIT) { + let cut = text.length - RENDER_TAIL_LIMIT + // Never split a surrogate pair at the render bound. + const unit = text.charCodeAt(cut) + if (unit >= 0xDC00 && unit <= 0xDFFF) cut += 1 + text = text.slice(cut) + gapBefore = true + } + state.view = { ...state.view, text, gapBefore } + state.cursor = frame.next + this.changed() + } + + /** + * Record the terminal status delivered at the end of the observation stream. + * @param id - observed activity. + * @param frame - the terminal `status` frame. + */ + observeStatus(id: ActivityId, frame: Extract): void { + const state = this.observedStates.get(String(id)) + /* v8 ignore next -- frames arrive only between opened and stop for a tracked id. */ + if (state === undefined) return + state.view = { + ...state.view, + status: frame.status, + ...frame.detail !== undefined ? { detail: frame.detail } : {}, + streaming: false, + } + this.changed() + } + + /** + * Record a terminal observation failure. + * @param id - observed activity. + * @param error - the stream's terminal failure. + */ + observeFailed(id: ActivityId, error: unknown): void { + const state = this.observedStates.get(String(id)) + if (state === undefined) return + state.view = { ...state.view, streaming: false, error: String(error) } + this.changed() + } + + /** + * Drop observation state after the last observer stops. + * @param id - the no-longer-observed activity. + */ + observeStopped(id: ActivityId): void { + if (!this.observedStates.delete(String(id))) return + this.changed() + } + + private changed(): void { + this.snapshotDirty = true + notifySubscribers(this.listeners, 'activity feed') + } +} diff --git a/packages/api/activity-controller/src/client/service.ts b/packages/api/activity-controller/src/client/service.ts new file mode 100644 index 0000000000..a640bc8ba2 --- /dev/null +++ b/packages/api/activity-controller/src/client/service.ts @@ -0,0 +1,156 @@ +/** React-free client activity service: roster snapshot plus observation control. */ + +import { Service, type Context } from '@deepseek-ai/cordis' +import { RemoteStreamCarrierError, type ClientRemote } from '@deepseek-ai/dsh-api-gateway/client' +import type {} from '@deepseek-ai/dsh-api-activity-controller/remote' +import type { TypertClientRemote } from '@deepseek-ai/dsh-typert-protocol' +import type { ActivityId } from '@deepseek-ai/dsh-activity/brand' +import type { ActivityObserveFrame } from '../types.ts' +import type { ActivityFeedSnapshot, ClientActivityModel } from './model.ts' + +/** Complete generated `ctx.remote.activity` namespace. */ +export type ActivityRemote = TypertClientRemote['activity'] + +/** Bare observable source for the client activity snapshot. */ +export interface ActivityFeedSource { + /** Read the identity-stable current snapshot. */ + getSnapshot(): ActivityFeedSnapshot + /** + * Subscribe to snapshot changes. + * @param listener - invalidation callback. + * @returns unsubscribe function. + */ + subscribe(listener: () => void): () => void +} + +/** The activity feed's client service face. */ +export interface IActivityFeed { + /** Roster rows, observation state, and arrival phase. */ + readonly state: ActivityFeedSource + /** + * Start observing one activity's live output; reference-counted, so two + * viewers of the same activity share one stream. + * @param id - activity to observe. + * @returns stop function releasing this observer's reference. + */ + observe(id: ActivityId): () => void +} + +/** One reference-counted observation stream. */ +interface ObservationEntry { + refs: number + stopped: boolean + dispose: () => Promise +} + +/** Remote face the observation runner drives. */ +type ActivityStreamRemote = Pick & { readonly activity: ActivityRemote } + +/** Owns the bare activity snapshot and per-activity observation streams. */ +export class ClientActivityFeed extends Service implements IActivityFeed { + readonly state: ActivityFeedSource + private readonly entries = new Map() + + /** + * @param ctx - client root Context. + * @param remote - generated activity namespace plus the Gateway stream factory. + * @param model - shared client activity model. + */ + constructor( + ctx: Context, + private readonly remote: ActivityStreamRemote, + private readonly model: ClientActivityModel, + ) { + super(ctx, 'activityFeed') + this.state = model + ctx.effect(() => () => { + const open = [...this.entries.values()] + this.entries.clear() + for (const entry of open) { + entry.stopped = true + void entry.dispose() + } + }, 'activity-controller.client.observations') + } + + observe(id: ActivityId): () => void { + const key = String(id) + const existing = this.entries.get(key) + if (existing !== undefined && !existing.stopped) { + existing.refs += 1 + return this.releaser(key) + } + const entry = this.startObservation(id) + this.entries.set(key, entry) + return this.releaser(key) + } + + private releaser(key: string): () => void { + let released = false + return () => { + if (released) return + released = true + const entry = this.entries.get(key) + if (entry === undefined) return + entry.refs -= 1 + if (entry.refs > 0) return + this.entries.delete(key) + entry.stopped = true + void entry.dispose().then(() => { + // The key is the stringified branded id this releaser was minted for. + this.model.observeStopped(key as ActivityId) + }) + } + } + + private startObservation(id: ActivityId): ObservationEntry { + const name = `activity observation ${String(id)}` + const stream = this.remote.$stream({ + name, + open: (signal) => { + const from = this.model.cursorOf(id) + return this.remote.activity.observe( + { activityId: id, ...from !== undefined ? { from } : {} }, + signal, + ) + }, + // A premature end after the anchor is retryable (a Host reload closes the + // generation); resuming from the cursor loses nothing. An end before the + // anchor is terminal. + ended: accepted => accepted + ? new RemoteStreamCarrierError(`${name} ended before settlement`) + : new Error(`${name} ended before its anchor`), + }) + const entry: ObservationEntry = { + refs: 1, + stopped: false, + dispose: () => stream.dispose(), + } + void (async () => { + try { + for await (const item of stream) { + const frame = item.value + if (frame.type === 'opened') { + this.model.observeOpened(id, frame) + item.accept() + continue + } + if (frame.type === 'output') { + this.model.observeOutput(id, frame) + continue + } + // Terminal status: leave the loop before the generation end is + // classified, then close the stream for good. + this.model.observeStatus(id, frame) + break + } + } catch (error) { + if (!entry.stopped) this.model.observeFailed(id, error) + } finally { + entry.stopped = true + void entry.dispose() + } + })() + return entry + } +} diff --git a/packages/api/activity-controller/src/feed.ts b/packages/api/activity-controller/src/feed.ts new file mode 100644 index 0000000000..34091dad8d --- /dev/null +++ b/packages/api/activity-controller/src/feed.ts @@ -0,0 +1,184 @@ +/** Reconnect-safe activity roster producer over the optional `ctx.activities` registry. */ + +import type { Context } from '@deepseek-ai/cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import type { ActivityRegistry, ActivitySnapshot } from '@deepseek-ai/dsh-activity' +import type { ActivityControlFrame, ActivityRow } from './types.ts' + +/** + * Project one registry snapshot into its browser-safe roster row. + * @param snapshot - fresh registry snapshot. + * @returns detached wire row for Remote consumers. + */ +export function activityRow(snapshot: ActivitySnapshot): ActivityRow { + return { + id: snapshot.id, + kind: snapshot.kind, + label: snapshot.label, + ...snapshot.ownerSession !== undefined ? { sessionId: snapshot.ownerSession } : {}, + ...snapshot.correlation !== undefined + ? { + correlation: { + ...snapshot.correlation.callId !== undefined ? { callId: snapshot.correlation.callId } : {}, + ...snapshot.correlation.jobId !== undefined ? { jobId: snapshot.correlation.jobId } : {}, + }, + } + : {}, + status: snapshot.status, + ...snapshot.detail !== undefined ? { detail: snapshot.detail } : {}, + startedAt: snapshot.startedAt, + ...snapshot.finishedAt !== undefined ? { finishedAt: snapshot.finishedAt } : {}, + outputTotal: snapshot.outputTotal, + } +} + +/** One owner bucket: the exact live owner used for fenced reads plus its rows. */ +interface OwnerBucket { + /** Exact registered Agent; undefined for the unowned bucket. */ + readonly owner: Agent | undefined + rows: readonly ActivityRow[] +} + +const UNOWNED = '' + +/** + * Owns registry observation, the owner-bucketed roster mirror, and all active + * control-stream generations. The mirror also answers `ownerOf`, which + * observation streams use to read owned activities through the visibility + * fence with the exact owner the registry announced. + */ +export class ActivityFeed { + private readonly followers = new Set() + private readonly buckets = new Map() + private readonly registry: ActivityRegistry | undefined + + /** @param ctx - Host context; the activity registry stays optional. */ + constructor(ctx: Context) { + this.registry = ctx.get('activities') + if (this.registry === undefined) return + const registry = this.registry + this.refresh(undefined) + for (const agent of ctx.get('agents')?.list() ?? []) this.refresh(agent) + registry.onActivitiesChanged((owner) => { + this.refresh(owner) + const bucket = this.buckets.get(owner?.id ?? UNOWNED) + this.publish({ + type: 'rows', + ...owner !== undefined ? { sessionId: owner.id } : {}, + activities: bucket?.rows ?? [], + }) + }) + ctx.effect(() => () => { + for (const follower of this.followers) follower.close() + this.followers.clear() + }, 'activity-controller.feed') + } + + /** + * Read the complete current roster synchronously. + * @returns every visible row across all owner buckets. + */ + baseline(): readonly ActivityRow[] { + return [...this.buckets.values()].flatMap(bucket => bucket.rows) + } + + /** + * Resolve the exact owner the registry announced for one activity, for + * fenced reads. `undefined` covers both unowned activities and ids this + * mirror has never seen — the registry itself settles unknown ids. + * @param id - activity id to resolve. + * @returns the exact live owner, or undefined. + */ + ownerOf(id: string): Agent | undefined { + for (const bucket of this.buckets.values()) { + if (bucket.rows.some(row => String(row.id) === id)) return bucket.owner + } + return undefined + } + + /** + * Open one generation beginning with a complete baseline. + * @param signal - generation cancellation. + * @returns baseline followed by whole-bucket replacement frames. + */ + async *follow(signal: AbortSignal): AsyncIterable { + signal.throwIfAborted() + const follower = new ActivityFollower() + this.followers.add(follower) + try { + yield { type: 'baseline', activities: this.baseline() } + yield* follower.read(signal) + } finally { + this.followers.delete(follower) + follower.close() + } + } + + /** Re-read one owner's visible rows into its bucket; an emptied bucket is dropped. */ + private refresh(owner: Agent | undefined): void { + /* v8 ignore next -- refresh is only reachable through a live registry's change feed. */ + if (this.registry === undefined) return + const rows = this.registry.list(owner) + .filter(snapshot => owner === undefined + ? snapshot.ownerSession === undefined + : snapshot.ownerSession === owner.id) + .map(activityRow) + const key = owner?.id ?? UNOWNED + if (rows.length === 0) { + this.buckets.delete(key) + return + } + this.buckets.set(key, { owner, rows }) + } + + private publish(frame: Exclude): void { + for (const follower of this.followers) follower.push(frame) + } +} + +/* jscpd:ignore-start -- mirrors WorkspaceFeed's follower fan-out by design; both serve baseline-plus-increment Remote streams. */ +class ActivityFollower { + private readonly frames: ActivityControlFrame[] = [] + private waiting: (() => void) | undefined + private closed = false + + push(frame: ActivityControlFrame): void { + /* v8 ignore next -- closed followers are removed before later publication can reach them. */ + if (this.closed) return + this.frames.push(frame) + this.waiting?.() + } + + close(): void { + if (this.closed) return + this.closed = true + this.waiting?.() + } + + async *read(signal: AbortSignal): AsyncIterable { + while (!this.closed && !signal.aborted) { + const frame = this.frames.shift() + if (frame !== undefined) { + yield frame + continue + } + await this.wait(signal) + } + } + + private wait(signal: AbortSignal): Promise { + return new Promise((resolve) => { + const finish = (): void => { + signal.removeEventListener('abort', finish) + /* v8 ignore next -- one read owns the sole installed wait callback. */ + if (this.waiting === finish) this.waiting = undefined + resolve() + } + this.waiting = finish + signal.addEventListener('abort', finish, { once: true }) + /* v8 ignore next -- native signals and the private queue cannot change during this synchronous setup. */ + if (signal.aborted || this.closed || this.frames.length > 0) finish() + }) + } +} +/* jscpd:ignore-end */ diff --git a/packages/api/activity-controller/src/index.ts b/packages/api/activity-controller/src/index.ts new file mode 100644 index 0000000000..a2d62c4a33 --- /dev/null +++ b/packages/api/activity-controller/src/index.ts @@ -0,0 +1,104 @@ +/** + * Host Activity Remote owner: the live-activity roster stream and per-activity + * output observation. A pure read surface over the optional `ctx.activities` + * registry — it starts nothing, cancels nothing, and never touches the + * model-facing consuming cursors. Compositions without the registry serve an + * empty roster and refuse observation with a stable error. + */ + +import { Context } from '@deepseek-ai/cordis' +import z from '@deepseek-ai/schemastery' +import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol' +import type {} from '@deepseek-ai/dsh-activity' +import { ActivityFeed } from './feed.ts' +import { observeActivity } from './observe.ts' +import type { ActivityControlFrame, ActivityObserveFrame, ActivityObserveRequest } from './types.ts' + +export type * from './types.ts' + +/** Default coalescing window between observation reads, in milliseconds. */ +const DEFAULT_FLUSH_MS = 100 + +/** Default soft byte budget per observation output frame. */ +const DEFAULT_MAX_FRAME_BYTES = 64 * 1024 + +/** Configuration for the Activity Remote owner. */ +export interface Config { + /** Coalescing window after new output before an observation read, in milliseconds (default 100). */ + flushMs?: number + /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */ + maxFrameBytes?: number +} + +declare module '@deepseek-ai/cordis' { + interface Context { + /** Host Activity read API and Remote namespace owner. */ + activityController: ActivityController + } +} + +/** Host service backing the generated `ctx.remote.activity` namespace. */ +export class ActivityController extends TypertRemoteService { + static inject = ['typert'] + + static Config: z = z.object({ + flushMs: z.number() + .step(1) + .min(1) + .max(Number.MAX_SAFE_INTEGER) + .default(DEFAULT_FLUSH_MS), + maxFrameBytes: z.number() + .step(1) + .min(1) + .max(Number.MAX_SAFE_INTEGER) + .default(DEFAULT_MAX_FRAME_BYTES), + }) + + private readonly feed: ActivityFeed + private readonly flushMs: number + private readonly maxFrameBytes: number + + /** + * @param ctx - Host context; the activity registry stays optional. + * @param config - validated coalescing and framing bounds. + */ + constructor(ctx: Context, config: Config) { + super(ctx, 'activityController', { namespace: 'activity' }) + this.flushMs = (config as Required).flushMs + this.maxFrameBytes = (config as Required).maxFrameBytes + this.feed = new ActivityFeed(ctx) + } + + /** + * Stream a complete roster baseline followed by whole-bucket replacements. + * @param signal - generation cancellation. + * @returns baseline followed by per-owner roster replacement frames. + */ + @Remote({ mode: 'stream' }) + control(signal: AbortSignal): AsyncIterable { + return this.feed.follow(signal) + } + + /** + * Stream one activity's retained output from an absolute byte offset, then + * its terminal status once settled and drained. Non-consuming: the + * model-facing cursors never observe these reads. + * @param request - target activity and optional resume offset. + * @param signal - generation cancellation. + * @returns anchor, coalesced output frames, and the terminal status. + */ + @Remote({ mode: 'stream' }) + observe(request: ActivityObserveRequest, signal: AbortSignal): AsyncIterable { + const registry = this.ctx.get('activities') + if (registry === undefined) { + throw new Error('activity observation unavailable: no activity registry is loaded (load @deepseek-ai/dsh-activity-local)') + } + return observeActivity(registry, request, { + flushMs: this.flushMs, + maxFrameBytes: this.maxFrameBytes, + ownerOf: id => this.feed.ownerOf(id), + }, signal) + } +} + +export default ActivityController diff --git a/packages/api/activity-controller/src/invariant.ts b/packages/api/activity-controller/src/invariant.ts new file mode 100644 index 0000000000..f85e7460b8 --- /dev/null +++ b/packages/api/activity-controller/src/invariant.ts @@ -0,0 +1,23 @@ +/** Package-owned invariant companion. @module @deepseek-ai/dsh-api-activity-controller/invariant */ + +/* jscpd:ignore-start */ +import type { Context } from '@deepseek-ai/cordis' +import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants' + +const PACKAGE_NAME = '@deepseek-ai/dsh-api-activity-controller' + +/** Cordis companion plugin name. */ +export const name = 'api-activity-controller-invariant' +/** Service required before the companion can reserve package ownership. */ +export const inject = ['invariants'] + +/** + * No runtime invariant: `@deepseek-ai/dsh-activity/invariant` owns snapshot relations; every roster + * generation is a full projection and observation reads are validated by the registry itself. + */ +const install: InvariantInstaller = () => {} + +/** Register this package's invariant companion. */ +export const apply = (ctx: Context): Promise<() => void> => + Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install)) +/* jscpd:ignore-end */ diff --git a/packages/api/activity-controller/src/observe.ts b/packages/api/activity-controller/src/observe.ts new file mode 100644 index 0000000000..f793b11496 --- /dev/null +++ b/packages/api/activity-controller/src/observe.ts @@ -0,0 +1,178 @@ +/** Per-activity observation generations: anchor, coalesced output, terminal status. */ + +import type { ActivityRegistry, ActivitySnapshot } from '@deepseek-ai/dsh-activity' +import { ActivityId } from '@deepseek-ai/dsh-activity/brand' +import type { Agent } from '@deepseek-ai/dsh-agent' +import type { ActivityObserveFrame, ActivityObserveRequest, ActivityWireChunk } from './types.ts' + +/** Cadence and framing bounds for one observation generation. */ +export interface ObserveOptions { + /** Coalescing window after a wake before reading, in milliseconds. */ + readonly flushMs: number + /** + * Soft byte budget per `output` frame. Accumulated chunks flush once the + * budget is met; one chunk larger than the budget ships whole (the + * registry's retention cap is the hard bound on any single chunk). + */ + readonly maxFrameBytes: number + /** Resolve the exact owner for fenced reads (the roster mirror's `ownerOf`). */ + readonly ownerOf: (id: string) => Agent | undefined +} + +function isTerminal(status: ActivitySnapshot['status']): boolean { + return status !== 'running' +} + +/** Wake-flag waiter: a wake between waits is never lost. */ +class OutputWaiter { + private dirty = false + private resolve: (() => void) | undefined + + wake(): void { + this.dirty = true + this.resolve?.() + } + + /** + * Resolve on the next wake, immediately when one already arrived, or on abort. + * @param signal - generation cancellation. + */ + wait(signal: AbortSignal): Promise { + if (this.dirty || signal.aborted) { + this.dirty = false + return Promise.resolve() + } + return new Promise((resolve) => { + const finish = (): void => { + signal.removeEventListener('abort', finish) + /* v8 ignore next -- one wait owns the sole installed resolver. */ + if (this.resolve === finish) this.resolve = undefined + this.dirty = false + resolve() + } + this.resolve = finish + signal.addEventListener('abort', finish, { once: true }) + }) + } +} + +function sleep(ms: number, signal: AbortSignal): Promise { + if (signal.aborted) return Promise.resolve() + return new Promise((resolve) => { + const timer = setTimeout(done, ms) + function done(): void { + clearTimeout(timer) + signal.removeEventListener('abort', done) + resolve() + } + signal.addEventListener('abort', done, { once: true }) + }) +} + +/** + * Stream one activity's retained output from an absolute offset: one `opened` + * anchor, coalesced `output` frames as the stream advances, then one terminal + * `status` after the settled activity is drained, after which the generation + * closes normally. Reads are non-consuming; reconnecting callers resume by + * passing the last frame's `next` as `from`. + * @param registry - the live activity registry. + * @param request - target activity and optional resume offset. + * @param options - cadence, framing bounds, and owner resolution. + * @param signal - generation cancellation owned by the Remote stream carrier. + * @returns the observation frame sequence for one generation. + */ +export async function* observeActivity( + registry: ActivityRegistry, + request: ActivityObserveRequest, + options: ObserveOptions, + signal: AbortSignal, +): AsyncIterable { + if (request.from !== undefined && (!Number.isSafeInteger(request.from) || request.from < 0)) { + throw new Error(`invalid observe offset: expected a non-negative safe integer, got ${JSON.stringify(request.from)}`) + } + signal.throwIfAborted() + const id = ActivityId(String(request.activityId)) + const waiter = new OutputWaiter() + // Subscribe before the first read so an append between the anchor read and + // the wait cannot be missed. + const unsubscribe = registry.onOutput((changed) => { + if (changed === id) waiter.wake() + }) + try { + const caller = options.ownerOf(String(id)) + let snapshot = registry.get(id, caller) + let cursor = request.from ?? snapshot.outputEarliest + yield { + type: 'opened', + activityId: id, + from: cursor, + earliest: snapshot.outputEarliest, + total: snapshot.outputTotal, + status: snapshot.status, + ...snapshot.detail !== undefined ? { detail: snapshot.detail } : {}, + } + while (!signal.aborted) { + const read = registry.read(id, cursor, caller) + if (read.chunks.length > 0) { + yield* outputFrames(read.chunks, read.next, read.lossy, options.maxFrameBytes) + } + cursor = read.next + snapshot = registry.get(id, caller) + if (isTerminal(snapshot.status) && cursor >= snapshot.outputTotal) { + yield { + type: 'status', + status: snapshot.status, + ...snapshot.detail !== undefined ? { detail: snapshot.detail } : {}, + // Settlement always stamps finishedAt; the guard only discharges the optional field type. + /* v8 ignore next */ + ...snapshot.finishedAt !== undefined ? { finishedAt: snapshot.finishedAt } : {}, + } + return + } + await waiter.wait(signal) + // Let a burst accumulate so producer chatter becomes bounded frames. + await sleep(options.flushMs, signal) + } + } finally { + unsubscribe() + } +} + +/** Split one read into frames along the soft per-frame byte budget. */ +function* outputFrames( + chunks: readonly ActivityWireChunk[], + next: number, + lossy: boolean, + maxFrameBytes: number, +): Iterable { + let batch: ActivityWireChunk[] = [] + let batchBytes = 0 + let flaggedLossy = lossy + for (const chunk of chunks) { + batch.push(chunk) + batchBytes += Buffer.byteLength(chunk.text, 'utf8') + if (batchBytes >= maxFrameBytes) { + const last = batch[batch.length - 1] + /* v8 ignore start -- a non-empty batch always has a last chunk; the arm only discharges noUncheckedIndexedAccess. */ + const end = last === undefined ? next : last.at + Buffer.byteLength(last.text, 'utf8') + /* v8 ignore stop */ + yield { + type: 'output', + chunks: batch, + next: end, + ...flaggedLossy ? { lossy: true as const } : {}, + } + flaggedLossy = false + batch = [] + batchBytes = 0 + } + } + if (batch.length > 0 || flaggedLossy) { + yield { + type: 'output', + chunks: batch, + next, + ...flaggedLossy ? { lossy: true as const } : {}, + } + } +} diff --git a/packages/api/activity-controller/src/types.ts b/packages/api/activity-controller/src/types.ts new file mode 100644 index 0000000000..2116d4477b --- /dev/null +++ b/packages/api/activity-controller/src/types.ts @@ -0,0 +1,104 @@ +/** Browser-safe roster and observation vocabulary for the Activity Remote. */ + +import type { SessionId } from '@deepseek-ai/dsh-session/types' +import type { ActivityId } from '@deepseek-ai/dsh-activity/brand' +import type { JobId } from '@deepseek-ai/dsh-jobs/brand' +import type { CallId } from '@deepseek-ai/dsh-llm/brand' + +export type { ActivityId } from '@deepseek-ai/dsh-activity/brand' + +/** Lifecycle state carried on the wire; mirrors the registry's status union. */ +export type ActivityRowStatus = 'running' | 'completed' | 'failed' | 'killed' + +/** Links one roster row to the tool call and background job for the same work. */ +export interface ActivityRowCorrelation { + /** Tool call that started the work, when a tool produced it. */ + readonly callId?: CallId + /** Background job carrying the model-facing control surface, when one exists. */ + readonly jobId?: JobId +} + +/** + * Browser-safe activity row. `kind` is `string` on the wire because the kind + * map is merge-extensible by producer plugins; presentation falls through a + * documented default for an unrecognized kind. + */ +export interface ActivityRow { + readonly id: ActivityId + readonly kind: string + readonly label: string + /** Owning session for grouping; absent for an unowned activity, visible to every session. */ + readonly sessionId?: SessionId + readonly correlation?: ActivityRowCorrelation + readonly status: ActivityRowStatus + readonly detail?: string + readonly startedAt: number + readonly finishedAt?: number + /** Total UTF-8 bytes the activity has produced so far. */ + readonly outputTotal: number +} + +/** + * Roster stream frames. Each generation starts with exactly one complete + * baseline; later frames replace one owner bucket wholesale (absent + * `sessionId` = the unowned bucket), so start, settlement, removal, and a + * second browser tab all converge through one authoritative value. + */ +export type ActivityControlFrame = + | { readonly type: 'baseline'; readonly activities: readonly ActivityRow[] } + | { readonly type: 'rows'; readonly sessionId?: SessionId; readonly activities: readonly ActivityRow[] } + +/** Opens one observation stream over a single activity's retained output. */ +export interface ActivityObserveRequest { + readonly activityId: ActivityId + /** + * Absolute byte offset to resume from — a previous frame's `next`. Omitted + * starts at the oldest retained byte. + */ + readonly from?: number +} + +/** One retained output chunk on the wire. `channel` widens to string like `kind`. */ +export interface ActivityWireChunk { + /** Absolute offset of the chunk's first byte. */ + readonly at: number + readonly text: string + readonly channel?: string + /** Bytes immediately before this chunk were lost at the producer or to retention. */ + readonly gapBefore?: true +} + +/** + * Observation stream frames: one `opened` anchor, then coalesced `output` + * batches, then — once the activity has settled and its retained output is + * drained — one terminal `status`, after which the stream closes normally. + * Status rides the same stream as output so settlement can never race a + * still-open output channel. + */ +export type ActivityObserveFrame = + | { + readonly type: 'opened' + readonly activityId: ActivityId + /** Offset the first `output` frame continues from. */ + readonly from: number + /** Oldest retained byte at open time; `from < earliest` means the head is gone. */ + readonly earliest: number + /** Total bytes produced at open time. */ + readonly total: number + readonly status: ActivityRowStatus + readonly detail?: string + } + | { + readonly type: 'output' + readonly chunks: readonly ActivityWireChunk[] + /** Offset to resume from after this frame. */ + readonly next: number + /** Bytes between the requested offset and `chunks` were already evicted. */ + readonly lossy?: true + } + | { + readonly type: 'status' + readonly status: ActivityRowStatus + readonly detail?: string + readonly finishedAt?: number + } diff --git a/packages/api/activity-controller/tests/activity-controller.host.spec.ts b/packages/api/activity-controller/tests/activity-controller.host.spec.ts new file mode 100644 index 0000000000..757a0af115 --- /dev/null +++ b/packages/api/activity-controller/tests/activity-controller.host.spec.ts @@ -0,0 +1,306 @@ +import { describe, expect, it } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' +import type { Agent } from '@deepseek-ai/dsh-agent' +import { Session, SessionId } from '@deepseek-ai/dsh-session' +import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' +import { ActivityId } from '@deepseek-ai/dsh-activity' +import { ActivityFeed } from '../src/feed.ts' +import { observeActivity } from '../src/observe.ts' +import type { ObserveOptions } from '../src/observe.ts' +import type { ActivityControlFrame, ActivityObserveFrame } from '../src/types.ts' + +async function harness(withRegistry = true) { + const ctx = new Context() + await ctx.plugin(AgentRegistry) + if (withRegistry) await ctx.plugin(LocalActivityRegistry, { retainBytes: 64, settledRetainBytes: 64 }) + return ctx +} + +function registerAgent(ctx: Context, rawId: string): Agent { + const scopeFiber = ctx.plugin(() => {}) + const id = SessionId(rawId) + const session = Session.create(id) + const agent = { + id, + session, + inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }), + status: 'idle', + ctx: scopeFiber.ctx, + } as unknown as Agent + ctx.agents.register(agent) + return agent +} + +/** Read frames until `count` arrive or the generator finishes, then abort. */ +async function collect( + iterable: AsyncIterable, + count: number, + abort: AbortController, +): Promise { + const frames: Frame[] = [] + const iterator = iterable[Symbol.asyncIterator]() + try { + while (frames.length < count) { + const step = await iterator.next() + if (step.done) return frames + frames.push(step.value) + } + } finally { + abort.abort() + await iterator.next().catch(() => undefined) + } + return frames +} + +const OBSERVE: Omit = { flushMs: 5, maxFrameBytes: 1024 } + +describe('ActivityFeed roster', () => { + it('serves an empty baseline without the registry', async () => { + const ctx = await harness(false) + const feed = new ActivityFeed(ctx) + expect(feed.baseline()).toEqual([]) + }) + + it('projects owned and unowned rows into the baseline with correlation and no live objects', async () => { + const ctx = await harness() + const owner = registerAgent(ctx, 'alice') + ctx.activities.open({ kind: 'bash', label: 'unowned build' }) + ctx.activities.open({ + kind: 'bash', + label: 'owned build', + owner, + correlation: { jobId: 'bash-7' as never }, + }) + const feed = new ActivityFeed(ctx) + const rows = feed.baseline() + expect(rows).toHaveLength(2) + const owned = rows.find(row => row.sessionId !== undefined) + expect(owned?.sessionId).toBe('alice') + expect(owned?.correlation).toEqual({ jobId: 'bash-7' }) + expect(owned?.status).toBe('running') + for (const row of rows) { + expect(Object.keys(row)).not.toContain('owner') + expect(row.outputTotal).toBe(0) + } + }) + + it('pushes whole-bucket frames for open, detail, settlement, and removal', async () => { + const ctx = await harness() + const owner = registerAgent(ctx, 'alice') + const feed = new ActivityFeed(ctx) + const abort = new AbortController() + const frames = collect(feed.follow(abort.signal), 4, abort) + await new Promise(resolve => setTimeout(resolve, 0)) + const handle = ctx.activities.open({ kind: 'bash', label: 'work', owner }) + handle.updateDetail('halfway') + handle.end({ status: 'completed', detail: 'exit code: 0' }) + const seen = await frames + expect(seen[0]).toEqual({ type: 'baseline', activities: [] }) + const rows = seen.slice(1) as Extract[] + expect(rows.every(frame => frame.sessionId === 'alice')).toBe(true) + expect(rows[0]?.activities[0]?.status).toBe('running') + expect(rows[1]?.activities[0]?.detail).toBe('halfway') + expect(rows[2]?.activities[0]?.status).toBe('completed') + expect(feed.ownerOf(String(rows[0]!.activities[0]!.id))).toBe(owner) + }) + + it('projects callId-only correlation and serves rosters without an agent registry', async () => { + const bare = new Context() + await bare.plugin(LocalActivityRegistry) + bare.activities.open({ kind: 'bash', label: 'lone', correlation: { callId: 'call-1' as never } }) + const feed = new ActivityFeed(bare) + expect(feed.baseline()[0]?.correlation).toEqual({ callId: 'call-1' }) + }) + + it('pushes an empty bucket frame when owner disposal removes the last row', async () => { + const ctx = await harness() + const owner = registerAgent(ctx, 'alice') + const feed = new ActivityFeed(ctx) + ctx.activities.open({ kind: 'bash', label: 'doomed', owner }) + const abort = new AbortController() + const frames = collect(feed.follow(abort.signal), 3, abort) + await new Promise(resolve => setTimeout(resolve, 0)) + await (owner.ctx as unknown as { fiber: { dispose(): Promise } }).fiber?.dispose?.() + // Owner-disposal removal reaches the feed as an emptied bucket. + await new Promise(resolve => setTimeout(resolve, 10)) + abort.abort() + const seen = await frames + const last = seen.at(-1) as Extract | undefined + if (last !== undefined && last.type === 'rows') expect(Array.isArray(last.activities)).toBe(true) + }) + + it('resolves undefined for unowned and unknown activities', async () => { + const ctx = await harness() + const feed = new ActivityFeed(ctx) + const handle = ctx.activities.open({ kind: 'bash', label: 'shared' }) + expect(feed.ownerOf(String(handle.id))).toBeUndefined() + expect(feed.ownerOf('bash-999')).toBeUndefined() + }) +}) + +describe('observeActivity', () => { + async function observed(ctx: Context, feed: ActivityFeed, request: { activityId: ActivityId; from?: number }) { + const abort = new AbortController() + const frames: ActivityObserveFrame[] = [] + const stream = observeActivity( + ctx.activities, + request, + { ...OBSERVE, ownerOf: id => feed.ownerOf(id) }, + abort.signal, + ) + const done = (async () => { + for await (const frame of stream) frames.push(frame) + })() + return { abort, frames, done } + } + + it('anchors, streams coalesced output, and closes with the terminal status', async () => { + const ctx = await harness() + const feed = new ActivityFeed(ctx) + const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) + handle.append('early ') + const { frames, done } = await observed(ctx, feed, { activityId: handle.id }) + await new Promise(resolve => setTimeout(resolve, 20)) + handle.append('live', { channel: 'stderr' }) + await new Promise(resolve => setTimeout(resolve, 20)) + handle.end({ status: 'completed', detail: 'exit code: 0' }) + await done + + expect(frames[0]).toMatchObject({ type: 'opened', from: 0, earliest: 0, total: 6, status: 'running' }) + const outputs = frames.filter(frame => frame.type === 'output') + const text = outputs.flatMap(frame => frame.chunks.map(chunk => chunk.text)).join('') + expect(text).toBe('early live') + expect(outputs.at(-1)?.next).toBe(10) + expect(outputs.flatMap(frame => frame.chunks).find(chunk => chunk.text === 'live')?.channel).toBe('stderr') + expect(frames.at(-1)).toMatchObject({ type: 'status', status: 'completed', detail: 'exit code: 0' }) + }) + + it('resumes from an explicit offset and flags an evicted resume lossy', async () => { + const ctx = await harness() + const feed = new ActivityFeed(ctx) + const handle = ctx.activities.open({ kind: 'bash', label: 'spam' }) + handle.append('a'.repeat(60)) + handle.append('b'.repeat(60)) + handle.end({ status: 'completed' }) + + const fresh = await observed(ctx, feed, { activityId: handle.id, from: 0 }) + await fresh.done + const output = fresh.frames.find(frame => frame.type === 'output') + expect(output?.lossy).toBe(true) + expect(output?.chunks.map(chunk => chunk.text).join('')).toBe('b'.repeat(60)) + + const resumed = await observed(ctx, feed, { activityId: handle.id, from: 120 }) + await resumed.done + expect(resumed.frames.some(frame => frame.type === 'output')).toBe(false) + expect(resumed.frames.at(-1)?.type).toBe('status') + }) + + it('splits oversized reads along the frame budget', async () => { + const ctx = await harness() + const feed = new ActivityFeed(ctx) + const registry = ctx.activities + const handle = registry.open({ kind: 'bash', label: 'wide' }) + const abort = new AbortController() + handle.append('x'.repeat(30)) + handle.append('y'.repeat(30)) + handle.end({ status: 'completed' }) + const frames = await collect( + observeActivity(registry, { activityId: handle.id }, { + flushMs: 5, + maxFrameBytes: 30, + ownerOf: id => feed.ownerOf(id), + }, abort.signal), + 5, + abort, + ) + const outputs = frames.filter(frame => frame.type === 'output') + expect(outputs).toHaveLength(2) + expect(outputs[0]?.next).toBe(30) + expect(outputs[1]?.next).toBe(60) + }) + + it('carries the lossy flag on the first frame of a split evicted read', async () => { + const ctx = await harness() + const feed = new ActivityFeed(ctx) + const registry = ctx.activities + const handle = registry.open({ kind: 'bash', label: 'evicted split' }) + handle.append('a'.repeat(40)) + handle.append('b'.repeat(40)) + handle.append('c'.repeat(40)) + handle.end({ status: 'completed' }) + const abort = new AbortController() + const frames = await collect( + observeActivity(registry, { activityId: handle.id, from: 0 }, { + flushMs: 5, + maxFrameBytes: 40, + ownerOf: id => feed.ownerOf(id), + }, abort.signal), + 5, + abort, + ) + const outputs = frames.filter(frame => frame.type === 'output') + expect(outputs[0]?.lossy).toBe(true) + expect(outputs[1]?.lossy).toBeUndefined() + }) + + it('reads owned activities through the roster owner and rejects bad offsets and unknown ids', async () => { + const ctx = await harness() + const owner = registerAgent(ctx, 'alice') + const feed = new ActivityFeed(ctx) + const handle = ctx.activities.open({ kind: 'bash', label: 'secret', owner }) + handle.append('classified') + handle.end({ status: 'completed' }) + const { frames, done } = await observed(ctx, feed, { activityId: handle.id }) + await done + expect(frames.some(frame => frame.type === 'output' + && frame.chunks.some(chunk => chunk.text === 'classified'))).toBe(true) + + const abort = new AbortController() + await expect(collect( + observeActivity(ctx.activities, { activityId: handle.id, from: -1 }, { + ...OBSERVE, + ownerOf: id => feed.ownerOf(id), + }, abort.signal), + 1, + abort, + )).rejects.toThrow(/invalid observe offset/) + + const abortUnknown = new AbortController() + await expect(collect( + observeActivity(ctx.activities, { activityId: ActivityId('bash-999') }, { + ...OBSERVE, + ownerOf: id => feed.ownerOf(id), + }, abortUnknown.signal), + 1, + abortUnknown, + )).rejects.toThrow(/unknown activity/) + }) + + it('ignores output signals for other activities while waiting', async () => { + const ctx = await harness() + const feed = new ActivityFeed(ctx) + const watched = ctx.activities.open({ kind: 'bash', label: 'watched' }) + const noisy = ctx.activities.open({ kind: 'bash', label: 'noisy' }) + const { abort, frames, done } = await observed(ctx, feed, { activityId: watched.id }) + await new Promise(resolve => setTimeout(resolve, 15)) + noisy.append('unrelated') + await new Promise(resolve => setTimeout(resolve, 15)) + watched.end({ status: 'completed' }) + await done + abort.abort() + expect(frames.filter(frame => frame.type === 'output')).toEqual([]) + }) + + it('stops cleanly on abort while waiting for output', async () => { + const ctx = await harness() + const feed = new ActivityFeed(ctx) + const handle = ctx.activities.open({ kind: 'bash', label: 'idle' }) + const { abort, frames, done } = await observed(ctx, feed, { activityId: handle.id }) + await new Promise(resolve => setTimeout(resolve, 20)) + abort.abort() + await done + expect(frames[0]?.type).toBe('opened') + expect(frames.at(-1)?.type).not.toBe('status') + }) +}) diff --git a/packages/api/activity-controller/tests/client-apply.client.spec.ts b/packages/api/activity-controller/tests/client-apply.client.spec.ts new file mode 100644 index 0000000000..231703ba13 --- /dev/null +++ b/packages/api/activity-controller/tests/client-apply.client.spec.ts @@ -0,0 +1,113 @@ +import { describe, expect, it } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import { RemoteStreamCarrierError } from '@deepseek-ai/dsh-api-gateway/client' +import { apply, createActivityRosterStream } from '../src/client/index.ts' +import { ClientActivityModel } from '../src/client/model.ts' +import type { ActivityControlFrame, ActivityId, ActivityRow } from '../src/types.ts' + +function row(): ActivityRow { + return { + id: 'bash-1' as ActivityId, + kind: 'bash', + label: 'build', + status: 'running', + startedAt: 1, + outputTotal: 0, + } +} + +/** One scripted roster stream: frames pushed by the test, never reopened. */ +class FakeStream { + disposed = false + private readonly frames: ActivityControlFrame[] = [] + private waiter: (() => void) | undefined + private failure: Error | undefined + + push(frame: ActivityControlFrame): void { + this.frames.push(frame) + this.waiter?.() + } + + poison(error: Error): void { + this.failure = error + this.waiter?.() + } + + dispose(): Promise { + this.disposed = true + this.waiter?.() + return Promise.resolve() + } + + async *[Symbol.asyncIterator]() { + while (!this.disposed) { + if (this.failure !== undefined) throw this.failure + const frame = this.frames.shift() + if (frame === undefined) { + await new Promise((resolve) => { this.waiter = resolve }) + continue + } + yield { generation: 1, value: frame, signal: new AbortController().signal, accept: () => {} } + } + } +} + +const tick = () => new Promise(resolve => setTimeout(resolve, 0)) + +describe('activity-controller client plugin', () => { + it('installs ctx.activityFeed and folds roster frames from the control stream', async () => { + const ctx = new Context() + const streams: { options: { open: (signal: AbortSignal) => unknown; ended: (accepted: boolean) => Error }; stream: FakeStream }[] = [] + const controlCalls: AbortSignal[] = [] + ctx.provide('remote', { + $stream: (options: never) => { + const stream = new FakeStream() + streams.push({ options, stream }) + return stream + }, + activity: { + control: (signal: AbortSignal) => { + controlCalls.push(signal) + return { [Symbol.asyncIterator]: async function* () { /* never yields */ } } + }, + observe: () => { throw new Error('not exercised') }, + }, + } as never) + const fiber = ctx.plugin({ inject: ['remote'], apply }) + await fiber + + streams[0]!.stream.push({ type: 'baseline', activities: [row()] }) + streams[0]!.stream.push({ type: 'rows', activities: [] }) + await tick() + const snapshot = ctx.activityFeed.state.getSnapshot() + expect(snapshot.phase).toBe('ready') + expect(snapshot.rowsBySession['']).toBeUndefined() + + // The generation opener and end classification belong to the domain. + streams[0]!.options.open(new AbortController().signal) + expect(controlCalls).toHaveLength(1) + expect(streams[0]!.options.ended(true)).toBeInstanceOf(RemoteStreamCarrierError) + expect(streams[0]!.options.ended(false)).toBeInstanceOf(Error) + + // A terminal roster failure keeps the last snapshot in place. + streams[0]!.stream.poison(new Error('roster stream broke')) + await tick() + expect(ctx.activityFeed.state.getSnapshot().phase).toBe('ready') + + await fiber.dispose() + expect(streams[0]!.stream.disposed).toBe(true) + }) + + it('keeps the last roster on a terminal stream failure', async () => { + const model = new ClientActivityModel() + const remote = { + $stream: () => new FakeStream(), + activity: { control: () => { throw new Error('unused') }, observe: () => { throw new Error('unused') } }, + } + const stream = createActivityRosterStream(remote as never, model) + model.replaceBaseline([row()]) + stream.start() + await stream.dispose() + expect(model.getSnapshot().rowsBySession['']?.[0]?.label).toBe('build') + }) +}) diff --git a/packages/api/activity-controller/tests/client-model.client.spec.ts b/packages/api/activity-controller/tests/client-model.client.spec.ts new file mode 100644 index 0000000000..59ec9067c5 --- /dev/null +++ b/packages/api/activity-controller/tests/client-model.client.spec.ts @@ -0,0 +1,168 @@ +import { describe, expect, it } from 'vitest' +import { ClientActivityModel } from '../src/client/model.ts' +import type { ActivityId, ActivityRow } from '../src/types.ts' + +function row(over: Partial = {}): ActivityRow { + return { + id: 'bash-1' as ActivityId, + kind: 'bash', + label: 'build', + sessionId: 'alice' as ActivityRow['sessionId'], + status: 'running', + startedAt: 1, + outputTotal: 0, + ...over, + } as ActivityRow +} + +/** A row with no owner session, as the unowned bucket carries them. */ +function unownedRow(over: Partial = {}): ActivityRow { + const { sessionId: _drop, ...rest } = row(over) + return rest +} + +const ID = 'bash-1' as ActivityId + +function opened(model: ClientActivityModel, over: Partial<{ from: number; earliest: number; total: number }> = {}): void { + model.observeOpened(ID, { + type: 'opened', + activityId: ID, + from: 0, + earliest: 0, + total: 0, + status: 'running', + ...over, + }) +} + +describe('ClientActivityModel roster', () => { + it('folds baselines into per-session buckets and reports readiness', () => { + const model = new ClientActivityModel() + expect(model.getSnapshot().phase).toBe('pending') + model.replaceBaseline([row(), unownedRow({ id: 'workflow-1' as ActivityId })]) + const snapshot = model.getSnapshot() + expect(snapshot.phase).toBe('ready') + expect(snapshot.rowsBySession['alice']).toHaveLength(1) + expect(snapshot.rowsBySession['']).toHaveLength(1) + }) + + it('replaces buckets wholesale and drops emptied keys', () => { + const model = new ClientActivityModel() + model.replaceBaseline([row()]) + model.replaceBucket('alice', [row({ status: 'completed', finishedAt: 2 })]) + expect(model.getSnapshot().rowsBySession['alice']?.[0]?.status).toBe('completed') + model.replaceBucket('alice', []) + expect('alice' in model.getSnapshot().rowsBySession).toBe(false) + model.replaceBucket(undefined, [unownedRow()]) + expect(model.getSnapshot().rowsBySession['']).toHaveLength(1) + }) + + it('keeps snapshot identity stable between changes and notifies subscribers', () => { + const model = new ClientActivityModel() + let notified = 0 + const unsubscribe = model.subscribe(() => { notified += 1 }) + const before = model.getSnapshot() + expect(model.getSnapshot()).toBe(before) + model.replaceBaseline([row()]) + expect(notified).toBe(1) + expect(model.getSnapshot()).not.toBe(before) + unsubscribe() + model.replaceBucket('alice', []) + expect(notified).toBe(1) + }) +}) + +describe('ClientActivityModel observation', () => { + it('accumulates output, advances the resume cursor, and settles on status', () => { + const model = new ClientActivityModel() + opened(model) + expect(model.cursorOf(ID)).toBe(0) + model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'a' }, { at: 1, text: 'b' }], next: 2 }) + model.observeOutput(ID, { type: 'output', chunks: [{ at: 2, text: 'c' }], next: 3 }) + expect(model.cursorOf(ID)).toBe(3) + const view = model.getSnapshot().observed[String(ID)] + expect(view?.text).toBe('abc') + expect(view?.streaming).toBe(true) + model.observeStatus(ID, { type: 'status', status: 'completed', detail: 'exit code: 0' }) + const settled = model.getSnapshot().observed[String(ID)] + expect(settled?.streaming).toBe(false) + expect(settled?.status).toBe('completed') + expect(settled?.detail).toBe('exit code: 0') + }) + + it('marks gaps from lossy frames, gap chunks, and a resume behind the retained head', () => { + const model = new ClientActivityModel() + opened(model, { from: 4, earliest: 8, total: 10 }) + expect(model.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) + + const clean = new ClientActivityModel() + opened(clean) + clean.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'x', gapBefore: true }], next: 1 }) + expect(clean.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) + + const lossy = new ClientActivityModel() + opened(lossy) + lossy.observeOutput(ID, { type: 'output', chunks: [], next: 5, lossy: true }) + expect(lossy.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) + }) + + it('bounds the render tail without splitting a surrogate pair', () => { + const model = new ClientActivityModel() + opened(model) + const emoji = '😀'.repeat((64 * 1024) + 8) + model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: emoji }], next: emoji.length * 2 }) + const view = model.getSnapshot().observed[String(ID)] + expect(view?.gapBefore).toBe(true) + expect(view!.text.length).toBeLessThanOrEqual(128 * 1024) + // The bound landed between pairs: the surviving text still round-trips. + expect(/^(?:😀)+$/u.test(view!.text)).toBe(true) + }) + + it('carries the anchor detail and trims a plain-ASCII tail without a boundary shift', () => { + const model = new ClientActivityModel() + model.observeOpened(ID, { + type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running', detail: 'exit soon', + }) + expect(model.getSnapshot().observed[String(ID)]?.detail).toBe('exit soon') + const long = 'x'.repeat((128 * 1024) + 5) + model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: long }], next: long.length }) + const view = model.getSnapshot().observed[String(ID)] + expect(view?.text.length).toBe(128 * 1024) + expect(view?.gapBefore).toBe(true) + }) + + it('advances the cut past a low surrogate landing exactly on the bound', () => { + const model = new ClientActivityModel() + opened(model) + // 'z' + one emoji + odd ASCII tail puts a low surrogate exactly at the cut index. + const text = 'z😀' + 'a'.repeat((128 * 1024) - 1) + model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text }], next: text.length }) + const view = model.getSnapshot().observed[String(ID)] + expect(view?.text.length).toBe((128 * 1024) - 1) + expect(view?.text.startsWith('a')).toBe(true) + }) + + it('preserves accumulated text across a reconnect anchor and clears on stop', () => { + const model = new ClientActivityModel() + opened(model) + model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'kept' }], next: 4 }) + opened(model, { from: 4, earliest: 0, total: 4 }) + expect(model.getSnapshot().observed[String(ID)]?.text).toBe('kept') + model.observeStopped(ID) + expect(model.getSnapshot().observed[String(ID)]).toBeUndefined() + expect(model.cursorOf(ID)).toBeUndefined() + // A second stop is inert. + model.observeStopped(ID) + }) + + it('records a terminal stream failure on the live view', () => { + const model = new ClientActivityModel() + opened(model) + model.observeFailed(ID, new Error('carrier gone')) + const view = model.getSnapshot().observed[String(ID)] + expect(view?.streaming).toBe(false) + expect(view?.error).toContain('carrier gone') + // A failure for an untracked id is inert. + model.observeFailed('bash-9' as ActivityId, new Error('ignored')) + }) +}) diff --git a/packages/api/activity-controller/tests/client-service.client.spec.ts b/packages/api/activity-controller/tests/client-service.client.spec.ts new file mode 100644 index 0000000000..c27e66cdd0 --- /dev/null +++ b/packages/api/activity-controller/tests/client-service.client.spec.ts @@ -0,0 +1,213 @@ +import { describe, expect, it, vi } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import { ClientActivityModel } from '../src/client/model.ts' +import { ClientActivityFeed } from '../src/client/service.ts' +import type { ActivityId, ActivityObserveFrame } from '../src/types.ts' + +const ID = 'bash-1' as ActivityId + +/** One scripted logical stream: frames are pushed by the test, never reopened. */ +class FakeStream { + disposed = false + /** Model a carrier whose disposal surfaces as an iterator throw. */ + throwOnDispose = false + private readonly frames: ActivityObserveFrame[] = [] + private waiter: (() => void) | undefined + private failure: Error | undefined + readonly accepts: number[] = [] + + push(frame: ActivityObserveFrame): void { + this.frames.push(frame) + this.waiter?.() + } + + poison(error: Error): void { + this.failure = error + this.waiter?.() + } + + dispose(): Promise { + if (this.throwOnDispose && this.failure === undefined) { + this.failure = new Error('carrier tore down') + } else { + this.disposed = true + } + this.waiter?.() + return Promise.resolve() + } + + async *[Symbol.asyncIterator]() { + let generation = 1 + while (!this.disposed) { + if (this.failure !== undefined) throw this.failure + const frame = this.frames.shift() + if (frame === undefined) { + await new Promise((resolve) => { this.waiter = resolve }) + continue + } + yield { + generation, + value: frame, + signal: new AbortController().signal, + accept: () => { this.accepts.push(generation) }, + } + generation = 1 + } + } +} + +function bench() { + const ctx = new Context() + const model = new ClientActivityModel() + const streams: { options: { open: (signal: AbortSignal) => unknown }; stream: FakeStream }[] = [] + const observeCalls: unknown[] = [] + const remote = { + $stream: (options: { open: (signal: AbortSignal) => unknown }) => { + const stream = new FakeStream() + streams.push({ options, stream }) + return stream + }, + activity: { + observe: (request: unknown) => { + observeCalls.push(request) + return { [Symbol.asyncIterator]: async function* () { /* never yields */ } } + }, + control: () => { throw new Error('not exercised') }, + }, + } + const feed = new ClientActivityFeed(ctx, remote as never, model) + return { ctx, model, feed, streams, observeCalls } +} + +const tick = () => new Promise(resolve => setTimeout(resolve, 0)) + +describe('ClientActivityFeed observation streams', () => { + it('feeds anchor, output, and terminal frames into the model, then closes', async () => { + const { model, feed, streams } = bench() + feed.observe(ID) + const { stream } = streams[0]! + stream.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + stream.push({ type: 'output', chunks: [{ at: 0, text: 'hi' }], next: 2 }) + await tick() + expect(model.getSnapshot().observed[String(ID)]?.text).toBe('hi') + expect(stream.accepts).toHaveLength(1) + + stream.push({ type: 'status', status: 'completed' }) + await tick() + expect(model.getSnapshot().observed[String(ID)]?.streaming).toBe(false) + expect(stream.disposed).toBe(true) + }) + + it('shares one stream across observers and stops after the last release', async () => { + const { model, feed, streams } = bench() + const first = feed.observe(ID) + const second = feed.observe(ID) + expect(streams).toHaveLength(1) + streams[0]!.stream.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + await tick() + + first() + first() + expect(streams[0]!.stream.disposed).toBe(false) + second() + await tick() + expect(streams[0]!.stream.disposed).toBe(true) + expect(model.getSnapshot().observed[String(ID)]).toBeUndefined() + }) + + it('opens a fresh stream for a re-observed activity and resumes from the model cursor', async () => { + const { feed, streams, observeCalls, model } = bench() + const stop = feed.observe(ID) + streams[0]!.stream.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + streams[0]!.stream.push({ type: 'output', chunks: [{ at: 0, text: 'abc' }], next: 3 }) + await tick() + // The generation opener reads the live cursor at open time. + streams[0]!.options.open(new AbortController().signal) + expect(observeCalls.at(-1)).toEqual({ activityId: ID, from: 3 }) + + stop() + await tick() + feed.observe(ID) + expect(streams).toHaveLength(2) + streams[1]!.options.open(new AbortController().signal) + // Stopped observation dropped the cursor: the fresh stream starts unanchored. + expect(observeCalls.at(-1)).toEqual({ activityId: ID }) + expect(model.cursorOf(ID)).toBeUndefined() + }) + + it('classifies a premature end as retryable only after the anchor', () => { + const { feed, streams } = bench() + feed.observe(ID) + const options = streams[0]!.options as unknown as { ended: (accepted: boolean) => Error } + expect(options.ended(true).name).toBe('RemoteStreamCarrierError') + expect(options.ended(false).name).toBe('Error') + }) + + it('records a consumer failure on the live view', async () => { + const { model, feed, streams } = bench() + feed.observe(ID) + const { stream } = streams[0]! + stream.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + await tick() + stream.poison(new Error('frame decode broke')) + await tick() + const view = model.getSnapshot().observed[String(ID)] + expect(view?.error).toContain('frame decode broke') + expect(view?.streaming).toBe(false) + }) + + it('treats a release after service disposal as inert and stays silent for post-stop failures', async () => { + const { ctx, model, feed, streams } = bench() + const stop = feed.observe(ID) + const { stream } = streams[0]! + stream.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + await tick() + // Poison wakes the consumer, but the synchronous stop lands first, so the + // failure arrives on an already-stopped entry and stays silent. + stream.poison(new Error('after stop')) + stop() + await tick() + expect(model.getSnapshot().observed[String(ID)]).toBeUndefined() + + const second = feed.observe(ID) + await ctx.fiber.dispose() + // The disposal path already removed every entry; a live releaser whose + // entry is gone is inert. + second() + }) + + it('stays silent when the carrier teardown itself throws after a stop', async () => { + const { model, feed, streams } = bench() + const stop = feed.observe(ID) + const { stream } = streams[0]! + stream.throwOnDispose = true + stream.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + await tick() + // The releaser marks the entry stopped, then its dispose surfaces as an + // iterator throw — which the consumer swallows for a stopped entry. + stop() + await tick() + expect(model.getSnapshot().observed[String(ID)]?.error).toBeUndefined() + }) + + it('records a terminal stream failure and service disposal closes live streams', async () => { + const { ctx, model, feed, streams } = bench() + feed.observe(ID) + const failing = streams[0]!.stream + failing.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + await tick() + const iterator = failing[Symbol.asyncIterator]() + void iterator + // Simulate a terminal consumer failure by disposing the underlying stream: + // the consumer loop ends without a status frame and cleans up. + const spy = vi.spyOn(model, 'observeFailed') + await failing.dispose() + await tick() + + const other = 'bash-2' as ActivityId + feed.observe(other) + await ctx.fiber.dispose() + expect(streams.every(entry => entry.stream.disposed)).toBe(true) + expect(spy).not.toHaveBeenCalled() + }) +}) diff --git a/packages/api/activity-controller/tests/controller.host.spec.ts b/packages/api/activity-controller/tests/controller.host.spec.ts new file mode 100644 index 0000000000..4c3262f093 --- /dev/null +++ b/packages/api/activity-controller/tests/controller.host.spec.ts @@ -0,0 +1,102 @@ +import { describe, expect, it } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import AgentRegistry from '@deepseek-ai/dsh-agent' +import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' +import { ActivityController } from '../src/index.ts' +import type { ActivityControlFrame, ActivityObserveFrame } from '../src/types.ts' + +async function collect( + iterable: AsyncIterable, + count: number, + abort: AbortController, +): Promise { + const frames: Frame[] = [] + const iterator = iterable[Symbol.asyncIterator]() + try { + while (frames.length < count) { + const step = await iterator.next() + if (step.done) return frames + frames.push(step.value) + } + } finally { + abort.abort() + await iterator.next().catch(() => undefined) + } + return frames +} + +describe('ActivityController', () => { + it('closes live roster followers when the owning fiber unwinds', async () => { + const ctx = new Context() + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalActivityRegistry) + const controller = new ActivityController(ctx, { flushMs: 5, maxFrameBytes: 1024 }) + const abort = new AbortController() + const iterator = controller.control(abort.signal)[Symbol.asyncIterator]() + expect((await iterator.next()).value).toMatchObject({ type: 'baseline' }) + const pending = iterator.next() + await ctx.fiber.dispose() + // The feed effect closed the follower, ending the generation cleanly. + expect((await pending).done).toBe(true) + }) + + it('coalesces bursts that land inside the flush window and carries the anchor detail', async () => { + const ctx = new Context() + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalActivityRegistry) + const controller = new ActivityController(ctx, { flushMs: 30, maxFrameBytes: 1024 }) + const handle = ctx.activities.open({ kind: 'bash', label: 'burst' }) + handle.updateDetail('warming up') + const abort = new AbortController() + const frames: ActivityObserveFrame[] = [] + const done = (async () => { + for await (const frame of controller.observe({ activityId: handle.id }, abort.signal)) frames.push(frame) + })() + await new Promise(resolve => setTimeout(resolve, 10)) + handle.append('a') + await new Promise(resolve => setTimeout(resolve, 5)) + // Lands inside the flush sleep, so the waiter is already dirty at the next wait. + handle.append('b') + await new Promise(resolve => setTimeout(resolve, 80)) + handle.end({ status: 'completed' }) + await done + expect(frames[0]).toMatchObject({ type: 'opened', detail: 'warming up' }) + const text = frames.filter(frame => frame.type === 'output') + .flatMap(frame => frame.chunks.map(chunk => chunk.text)).join('') + expect(text).toBe('ab') + }) + + it('serves an empty baseline and refuses observation without the registry', async () => { + const ctx = new Context() + const controller = new ActivityController(ctx, { flushMs: 5, maxFrameBytes: 1024 }) + const abort = new AbortController() + const frames = await collect(controller.control(abort.signal), 1, abort) + expect(frames).toEqual([{ type: 'baseline', activities: [] }]) + expect(() => controller.observe({ activityId: 'bash-1' as never }, new AbortController().signal)) + .toThrow(/activity observation unavailable/) + }) + + it('streams the roster and one activity end to end over a live registry', async () => { + const ctx = new Context() + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalActivityRegistry) + const controller = new ActivityController(ctx, { flushMs: 5, maxFrameBytes: 1024 }) + + const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) + handle.append('hi') + handle.end({ status: 'completed', detail: 'exit code: 0' }) + + const rosterAbort = new AbortController() + const roster = await collect(controller.control(rosterAbort.signal), 1, rosterAbort) + expect(roster[0]).toMatchObject({ type: 'baseline' }) + expect((roster[0] as Extract).activities[0]?.label).toBe('echo') + + const observeAbort = new AbortController() + const observed = await collect( + controller.observe({ activityId: handle.id }, observeAbort.signal), + 3, + observeAbort, + ) + expect(observed.map(frame => frame.type)).toEqual(['opened', 'output', 'status']) + }) +}) diff --git a/packages/api/activity-controller/tsconfig.client.json b/packages/api/activity-controller/tsconfig.client.json new file mode 100644 index 0000000000..d2934629b4 --- /dev/null +++ b/packages/api/activity-controller/tsconfig.client.json @@ -0,0 +1,46 @@ +{ + "extends": "../../../tsconfig.base.client.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types", + "tsBuildInfoFile": "lib/tsconfig.client.tsbuildinfo" + }, + "files": [ + "src/client/index.ts", + "src/client/model.ts", + "src/client/service.ts", + "src/types.ts" + ], + "references": [ + { + "path": "../../../vendor/cordis" + }, + { + "path": "../gateway/tsconfig.client.json" + }, + { + "path": "../../client/connection/tsconfig.client.json" + }, + { + "path": "../../client/store" + }, + { + "path": "../../activity/activity" + }, + { + "path": "../../core/session" + }, + { + "path": "../../jobs/jobs" + }, + { + "path": "../../llm/llm" + }, + { + "path": "../../util/brand" + }, + { + "path": "../../typert/protocol" + } + ] +} diff --git a/packages/api/activity-controller/tsconfig.host.json b/packages/api/activity-controller/tsconfig.host.json new file mode 100644 index 0000000000..4193d47109 --- /dev/null +++ b/packages/api/activity-controller/tsconfig.host.json @@ -0,0 +1,26 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types", + "tsBuildInfoFile": "lib/tsconfig.host.tsbuildinfo" + }, + "files": [ + "src/index.ts", + "src/invariant.ts", + "src/types.ts", + "src/feed.ts", + "src/observe.ts" + ], + "references": [ + { "path": "../../../vendor/cordis" }, + { "path": "../../../vendor/schemastery" }, + { "path": "../../activity/activity" }, + { "path": "../../core/agent" }, + { "path": "../../core/session" }, + { "path": "../../jobs/jobs" }, + { "path": "../../llm/llm" }, + { "path": "../../runtime-diagnostics/invariants" }, + { "path": "../../typert/protocol" } + ] +} diff --git a/packages/api/activity-controller/tsconfig.json b/packages/api/activity-controller/tsconfig.json new file mode 100644 index 0000000000..2a0b0e33f7 --- /dev/null +++ b/packages/api/activity-controller/tsconfig.json @@ -0,0 +1,7 @@ +{ + "files": [], + "references": [ + { "path": "./tsconfig.host.json" }, + { "path": "./tsconfig.client.json" } + ] +} diff --git a/packages/api/activity-controller/tsdown.config.ts b/packages/api/activity-controller/tsdown.config.ts new file mode 100644 index 0000000000..0552d1b1cf --- /dev/null +++ b/packages/api/activity-controller/tsdown.config.ts @@ -0,0 +1,7 @@ +import { clientBundle } from '../../client/tsdown.client.ts' + +export default clientBundle( + '@deepseek-ai/dsh-api-activity-controller', + ['lib/types/index.js', 'lib/types/invariant.js'], + { hostPhase: true }, +) diff --git a/packages/api/remotes/package.json b/packages/api/remotes/package.json index 0724012e77..05c8dbe032 100644 --- a/packages/api/remotes/package.json +++ b/packages/api/remotes/package.json @@ -61,6 +61,7 @@ "peerDependencies": { "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-agent-presets": "workspace:^", + "@deepseek-ai/dsh-api-activity-controller": "workspace:^", "@deepseek-ai/dsh-api-gateway": "workspace:^", "@deepseek-ai/dsh-api-session-controller": "workspace:^", "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", @@ -82,6 +83,7 @@ "devDependencies": { "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-agent-presets": "workspace:^", + "@deepseek-ai/dsh-api-activity-controller": "workspace:^", "@deepseek-ai/dsh-api-gateway": "workspace:^", "@deepseek-ai/dsh-api-session-controller": "workspace:^", "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", diff --git a/packages/api/remotes/src/client/index.ts b/packages/api/remotes/src/client/index.ts index 528d78dc89..388d7e1fb6 100644 --- a/packages/api/remotes/src/client/index.ts +++ b/packages/api/remotes/src/client/index.ts @@ -10,6 +10,7 @@ import messageFeedbackRemote from '@deepseek-ai/dsh-message-feedback/remote' import sessionReferencesRemote from '@deepseek-ai/dsh-session-reference/remote' import sessionRemote from '@deepseek-ai/dsh-api-session-controller/remote' import workspaceRemote from '@deepseek-ai/dsh-api-workspace-controller/remote' +import activityRemote from '@deepseek-ai/dsh-api-activity-controller/remote' import type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client' export type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client' @@ -24,6 +25,8 @@ export type {} from '@deepseek-ai/dsh-api-session-controller/remote' export type * from '@deepseek-ai/dsh-api-session-controller/types' export type {} from '@deepseek-ai/dsh-api-workspace-controller/remote' export type * from '@deepseek-ai/dsh-api-workspace-controller/types' +export type {} from '@deepseek-ai/dsh-api-activity-controller/remote' +export type * from '@deepseek-ai/dsh-api-activity-controller/types' export type { SessionJob as JobView } from '@deepseek-ai/dsh-api-session-controller/types' // The forwarded-event allowlist's selection seat: without it in the consumer's // compilation face `TypertRemoteEvent` is `never` and every `$on` call fails. @@ -135,7 +138,7 @@ export async function apply(ctx: Context): Promise<() => Promise> { for (const contribution of [ commandsRemote, goalsRemote, dynamicRemote, fileReferencesRemote, pluginInventoryRemote, messageFeedbackRemote, sessionReferencesRemote, - sessionRemote, workspaceRemote, + sessionRemote, workspaceRemote, activityRemote, ]) { disposers.push(await ctx.remote.$mount(contribution)) } diff --git a/packages/api/remotes/src/index.ts b/packages/api/remotes/src/index.ts index 4d0256e162..7cd03cfd21 100644 --- a/packages/api/remotes/src/index.ts +++ b/packages/api/remotes/src/index.ts @@ -25,6 +25,7 @@ import type {} from '@deepseek-ai/dsh-settings/types' import type {} from '@deepseek-ai/dsh-user-approval' import type {} from '@deepseek-ai/dsh-user-questions' export type {} from '@deepseek-ai/dsh-api-session-controller/types' +export type {} from '@deepseek-ai/dsh-api-activity-controller/types' export { API_REMOTE_FORWARDED_EVENTS } from './remote-events.ts' export type { ApiRemoteForwardedEvent } from './types.ts' diff --git a/packages/api/remotes/tsconfig.client.json b/packages/api/remotes/tsconfig.client.json index eb98174378..c24ed4bca5 100644 --- a/packages/api/remotes/tsconfig.client.json +++ b/packages/api/remotes/tsconfig.client.json @@ -63,6 +63,9 @@ { "path": "../session-controller/tsconfig.client.json" }, + { + "path": "../activity-controller/tsconfig.client.json" + }, { "path": "../workspace-controller/tsconfig.client.json" }, diff --git a/packages/api/remotes/tsconfig.host.json b/packages/api/remotes/tsconfig.host.json index 4dd513bdeb..0b0841c2b4 100644 --- a/packages/api/remotes/tsconfig.host.json +++ b/packages/api/remotes/tsconfig.host.json @@ -54,6 +54,9 @@ { "path": "../session-controller/tsconfig.host.json" }, + { + "path": "../activity-controller/tsconfig.host.json" + }, { "path": "../workspace-controller/tsconfig.host.json" }, diff --git a/packages/bundle/base/cordis.patch.yml b/packages/bundle/base/cordis.patch.yml index 981e791fb4..3e2f48264a 100644 --- a/packages/bundle/base/cordis.patch.yml +++ b/packages/bundle/base/cordis.patch.yml @@ -81,6 +81,11 @@ - id: jobs name: '@deepseek-ai/dsh-jobs-local' + # Live-activity observation registry: non-consuming output streams for the + # optional activity plane (background bash/pwsh mirror into it when loaded). + - id: activity + name: '@deepseek-ai/dsh-activity-local' + - id: llm-retry name: '@deepseek-ai/dsh-llm-retry' diff --git a/packages/bundle/base/package.json b/packages/bundle/base/package.json index 80f33257db..e6ad006201 100644 --- a/packages/bundle/base/package.json +++ b/packages/bundle/base/package.json @@ -41,11 +41,13 @@ "dependencies": { "@deepseek-ai/cordis-plugin-hmr": "workspace:^", "@deepseek-ai/cordis-plugin-timer": "workspace:^", + "@deepseek-ai/dsh-activity-local": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-agent-default-model": "workspace:^", + "@deepseek-ai/dsh-agent-instructions": "workspace:^", "@deepseek-ai/dsh-agent-loop": "workspace:^", + "@deepseek-ai/dsh-api-gateway": "workspace:^", "@deepseek-ai/dsh-attachment-local": "workspace:^", - "@deepseek-ai/dsh-shell-env": "workspace:^", "@deepseek-ai/dsh-bash-sandbox": "workspace:^", "@deepseek-ai/dsh-command-compact": "workspace:^", "@deepseek-ai/dsh-command-feedback": "workspace:^", @@ -55,19 +57,19 @@ "@deepseek-ai/dsh-compaction-tool-result-pruner": "workspace:^", "@deepseek-ai/dsh-credentials-local": "workspace:^", "@deepseek-ai/dsh-deepseek-llm-api-extensions": "workspace:^", - "@deepseek-ai/dsh-plugin-package-inventory-deepseek": "workspace:^", "@deepseek-ai/dsh-fs-local": "workspace:^", "@deepseek-ai/dsh-fs-observation-policy": "workspace:^", "@deepseek-ai/dsh-fs-sandbox": "workspace:^", "@deepseek-ai/dsh-goal": "workspace:^", "@deepseek-ai/dsh-goal-round-driver": "workspace:^", - "@deepseek-ai/dsh-api-gateway": "workspace:^", + "@deepseek-ai/dsh-jobs-local": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-llm-deepseek": "workspace:^", "@deepseek-ai/dsh-llm-pi-ai": "workspace:^", "@deepseek-ai/dsh-llm-retry": "workspace:^", "@deepseek-ai/dsh-permission-presets": "workspace:^", "@deepseek-ai/dsh-plan-mode": "workspace:^", + "@deepseek-ai/dsh-plugin-package-inventory-deepseek": "workspace:^", "@deepseek-ai/dsh-pwsh-sandbox": "workspace:^", "@deepseek-ai/dsh-repeat-tool-reminder": "workspace:^", "@deepseek-ai/dsh-sandbox-local": "workspace:^", @@ -82,6 +84,7 @@ "@deepseek-ai/dsh-session-title": "workspace:^", "@deepseek-ai/dsh-session-title-first-prompt-llm": "workspace:^", "@deepseek-ai/dsh-settings-file": "workspace:^", + "@deepseek-ai/dsh-shell-env": "workspace:^", "@deepseek-ai/dsh-skill": "workspace:^", "@deepseek-ai/dsh-skill-badge": "workspace:^", "@deepseek-ai/dsh-skill-filesystem": "workspace:^", @@ -92,13 +95,13 @@ "@deepseek-ai/dsh-subagent-spawn-in-process": "workspace:^", "@deepseek-ai/dsh-subprocess-local": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", - "@deepseek-ai/dsh-jobs-local": "workspace:^", - "@deepseek-ai/dsh-tool-call-timeout-policy": "workspace:^", "@deepseek-ai/dsh-token-meter": "workspace:^", "@deepseek-ai/dsh-tool-bash": "workspace:^", + "@deepseek-ai/dsh-tool-call-timeout-policy": "workspace:^", "@deepseek-ai/dsh-tool-fs": "workspace:^", "@deepseek-ai/dsh-tool-fs-search": "workspace:^", "@deepseek-ai/dsh-tool-goal": "workspace:^", + "@deepseek-ai/dsh-tool-jobs": "workspace:^", "@deepseek-ai/dsh-tool-pwsh": "workspace:^", "@deepseek-ai/dsh-tool-ralph": "workspace:^", "@deepseek-ai/dsh-tool-skill": "workspace:^", @@ -106,7 +109,6 @@ "@deepseek-ai/dsh-tool-subagent": "workspace:^", "@deepseek-ai/dsh-tool-subagent-control": "workspace:^", "@deepseek-ai/dsh-tool-subagent-report": "workspace:^", - "@deepseek-ai/dsh-tool-jobs": "workspace:^", "@deepseek-ai/dsh-tool-todo": "workspace:^", "@deepseek-ai/dsh-tool-web": "workspace:^", "@deepseek-ai/dsh-tool-workflow": "workspace:^", @@ -117,8 +119,7 @@ "@deepseek-ai/dsh-user-questions": "workspace:^", "@deepseek-ai/dsh-web": "workspace:^", "@deepseek-ai/dsh-web-search-deepseek": "workspace:^", - "@deepseek-ai/dsh-workflow-worker-thread": "workspace:^", - "@deepseek-ai/dsh-agent-instructions": "workspace:^" + "@deepseek-ai/dsh-workflow-worker-thread": "workspace:^" }, "peerDependencies": { "@deepseek-ai/dsh-invariants": "workspace:^", diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml index 18a0d3911a..9fa12bc33f 100644 --- a/packages/bundle/web-app/cordis.patch.yml +++ b/packages/bundle/web-app/cordis.patch.yml @@ -109,6 +109,10 @@ - id: workspace-controller name: '@deepseek-ai/dsh-api-workspace-controller' + # Live-activity roster and per-activity output observation over Typert Remote. + - id: activity-controller + name: '@deepseek-ai/dsh-api-activity-controller' + # The API gateway: the transport-agnostic dispatch face every client shape # shares. The base layer's agent-default-model service owns the default model. - id: api-gateway @@ -273,6 +277,11 @@ - id: ui-jobs name: '@deepseek-ai/dsh-client-ui-jobs' + # Live activities: the session-header roster with on-demand streaming + # output panels over the activity feed. + - id: ui-activity + name: '@deepseek-ai/dsh-client-ui-activity' + # Goal surface: GoalBar in the input dock over the goal session projection. - id: ui-goal name: '@deepseek-ai/dsh-client-ui-goal' diff --git a/packages/bundle/web-app/package.json b/packages/bundle/web-app/package.json index 68c43da265..0837c9f6b1 100644 --- a/packages/bundle/web-app/package.json +++ b/packages/bundle/web-app/package.json @@ -45,75 +45,77 @@ }, "dependencies": { "@deepseek-ai/dsh-agent-presets": "workspace:^", - "@deepseek-ai/dsh-tool-subagent": "workspace:^", + "@deepseek-ai/dsh-api-activity-controller": "workspace:^", "@deepseek-ai/dsh-api-remotes": "workspace:^", + "@deepseek-ai/dsh-api-session-controller": "workspace:^", + "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", "@deepseek-ai/dsh-app-boot": "workspace:^", "@deepseek-ai/dsh-client-connection": "workspace:^", "@deepseek-ai/dsh-client-hmr": "workspace:^", "@deepseek-ai/dsh-client-locale": "workspace:^", "@deepseek-ai/dsh-client-modules": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", + "@deepseek-ai/dsh-client-ui-activity": "workspace:^", "@deepseek-ai/dsh-client-ui-agent-preset": "workspace:^", - "@deepseek-ai/dsh-client-ui-attachment": "workspace:^", "@deepseek-ai/dsh-client-ui-approval": "workspace:^", + "@deepseek-ai/dsh-client-ui-attachment": "workspace:^", "@deepseek-ai/dsh-client-ui-brand-official": "workspace:^", - "@deepseek-ai/dsh-client-ui-commands": "workspace:^", "@deepseek-ai/dsh-client-ui-chat": "workspace:^", + "@deepseek-ai/dsh-client-ui-commands": "workspace:^", "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", "@deepseek-ai/dsh-client-ui-cordis": "workspace:^", "@deepseek-ai/dsh-client-ui-deliverables": "workspace:^", "@deepseek-ai/dsh-client-ui-directory-picker-browse": "workspace:^", "@deepseek-ai/dsh-client-ui-directory-picker-native": "workspace:^", - "@deepseek-ai/dsh-client-ui-message-feedback": "workspace:^", "@deepseek-ai/dsh-client-ui-goal": "workspace:^", + "@deepseek-ai/dsh-client-ui-input-trigger": "workspace:^", + "@deepseek-ai/dsh-client-ui-jobs": "workspace:^", "@deepseek-ai/dsh-client-ui-layout": "workspace:^", + "@deepseek-ai/dsh-client-ui-message-feedback": "workspace:^", "@deepseek-ai/dsh-client-ui-model-selection": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings-models": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings-plugin-inventory": "workspace:^", "@deepseek-ai/dsh-client-ui-permission-presets": "workspace:^", "@deepseek-ai/dsh-client-ui-plan": "workspace:^", + "@deepseek-ai/dsh-client-ui-reference": "workspace:^", + "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings-plugins": "workspace:^", - "@deepseek-ai/dsh-client-ui-user-questions": "workspace:^", "@deepseek-ai/dsh-client-ui-settings": "workspace:^", "@deepseek-ai/dsh-client-ui-settings-general": "workspace:^", + "@deepseek-ai/dsh-client-ui-settings-models": "workspace:^", + "@deepseek-ai/dsh-client-ui-settings-plugin-inventory": "workspace:^", + "@deepseek-ai/dsh-client-ui-settings-plugins": "workspace:^", "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^", "@deepseek-ai/dsh-client-ui-skill": "workspace:^", - "@deepseek-ai/dsh-client-ui-input-trigger": "workspace:^", - "@deepseek-ai/dsh-client-ui-reference": "workspace:^", "@deepseek-ai/dsh-client-ui-subagent": "workspace:^", - "@deepseek-ai/dsh-client-ui-jobs": "workspace:^", "@deepseek-ai/dsh-client-ui-theme": "workspace:^", "@deepseek-ai/dsh-client-ui-tool": "workspace:^", - "@deepseek-ai/dsh-client-ui-workflow-run": "workspace:^", "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^", + "@deepseek-ai/dsh-client-ui-user-questions": "workspace:^", + "@deepseek-ai/dsh-client-ui-workflow-run": "workspace:^", "@deepseek-ai/dsh-client-ui-workspace": "workspace:^", "@deepseek-ai/dsh-cmdline": "workspace:^", "@deepseek-ai/dsh-code-runtime-worker-thread": "workspace:^", "@deepseek-ai/dsh-cordis-client-runner": "workspace:^", "@deepseek-ai/dsh-cordis-host-runner": "workspace:^", - "@deepseek-ai/dsh-web-frontend": "workspace:^", - "@deepseek-ai/dsh-host-frontend-static": "workspace:^", + "@deepseek-ai/dsh-file-reference": "workspace:^", + "@deepseek-ai/dsh-file-reference-local": "workspace:^", "@deepseek-ai/dsh-host-apiproxy": "workspace:^", "@deepseek-ai/dsh-host-directory-picker-auto": "workspace:^", "@deepseek-ai/dsh-host-directory-picker-browse": "workspace:^", "@deepseek-ai/dsh-host-directory-picker-native": "workspace:^", + "@deepseek-ai/dsh-host-frontend-static": "workspace:^", "@deepseek-ai/dsh-host-plugin-inventory": "workspace:^", "@deepseek-ai/dsh-host-webserver": "workspace:^", - "@deepseek-ai/dsh-file-reference": "workspace:^", - "@deepseek-ai/dsh-file-reference-local": "workspace:^", "@deepseek-ai/dsh-launch-environment": "workspace:^", "@deepseek-ai/dsh-message-feedback": "workspace:^", + "@deepseek-ai/dsh-session-log-export": "workspace:^", "@deepseek-ai/dsh-session-projection-cache": "workspace:^", "@deepseek-ai/dsh-session-reference": "workspace:^", - "@deepseek-ai/dsh-session-log-export": "workspace:^", "@deepseek-ai/dsh-session-stats": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", "@deepseek-ai/dsh-storage": "workspace:^", "@deepseek-ai/dsh-storage-domain": "workspace:^", "@deepseek-ai/dsh-storage-json": "workspace:^", "@deepseek-ai/dsh-subprocess": "workspace:^", + "@deepseek-ai/dsh-tool-subagent": "workspace:^", + "@deepseek-ai/dsh-web-frontend": "workspace:^", "@deepseek-ai/dsh-workspace": "workspace:^", "@deepseek-ai/schemastery": "workspace:^", "commander": "^15.0.0", diff --git a/packages/client/ui-activity/README.i18n.yaml b/packages/client/ui-activity/README.i18n.yaml new file mode 100644 index 0000000000..532ea19b10 --- /dev/null +++ b/packages/client/ui-activity/README.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 packages/client/ui-activity/README.md +README.md: 157e98e6b14bc1b556cb2aac8f6f90c43fbcb3f2 +README.zh.md: 392cc91c105caa2f79546f818700da0e6643b8a1 diff --git a/packages/client/ui-activity/README.md b/packages/client/ui-activity/README.md new file mode 100644 index 0000000000..157e98e6b1 --- /dev/null +++ b/packages/client/ui-activity/README.md @@ -0,0 +1,21 @@ +# @deepseek-ai/dsh-client-ui-activity + +English | [中文](README.zh.md) + +Session-header live-activity list over `ctx.activityFeed`: one header action beside the background-job list renders the roster rows this session can see (owned plus unowned), and expanding a row opens that activity's observation stream into an embedded terminal panel. Observation follows visibility — the stream opens on expand and closes on collapse, unmount, or popover dismissal, so output only flows while someone is watching. Retention gaps and stream failures render as notices above the panel. + +The control renders nothing until the session can see at least one activity, so an ordinary conversation never grows a control for a capability it is not using; without the activity registry the roster stays empty and the entry point never appears. + +## Model Experience + +None, as this package renders host-observed live output for a human and touches no prompt, message, schema, stream, or tool result. The model's own view of the same work stays with [`dsh-tool-jobs`](../../jobs/tool-jobs/README.md). + +#### KV Cache effect + +None; the package never assembles or sends provider requests. + +## Known Limitations and Deferred Work + +- **No kill control** — cancellation stays with the model's `job_kill`; a human kill is blocked on the jobs `reported` contract question recorded in the [web job display Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md). +- **Channel labels are not rendered** — stdout and stderr chunks concatenate into one stream; per-channel tinting is a presentation follow-up. +- **A background job appears in both header lists** — the job list carries control-facing status, this list carries output; the duplication mirrors the deliberate subagent-catalog precedent. diff --git a/packages/client/ui-activity/README.zh.md b/packages/client/ui-activity/README.zh.md new file mode 100644 index 0000000000..392cc91c10 --- /dev/null +++ b/packages/client/ui-activity/README.zh.md @@ -0,0 +1,21 @@ +# @deepseek-ai/dsh-client-ui-activity + +[English](README.md) | 中文 + +架在 `ctx.activityFeed` 上的会话头部实时活动列表:在后台任务列表旁提供一个头部 action,渲染本会话可见的 roster 行(有主 + 无主),展开某行即把该 activity 的观察流打开进内嵌终端面板。观察跟随可见性——展开开流,收起、卸载或关闭弹层即停流,只有有人在看时输出才流动。保留缺口与流失败以面板上方的提示呈现。 + +会话一个 activity 都看不到时该控件完全不渲染,普通会话不会为未使用的能力多出控件;没有 activity 注册表时 roster 恒空,入口永不出现。 + +## 模型体验 + +无:本包只为人渲染宿主观察到的实时输出,不触碰任何 prompt、消息、schema、流或工具结果。模型对同一工作的视图仍在 [`dsh-tool-jobs`](../../jobs/tool-jobs/README.zh.md)。 + +#### KV Cache 影响 + +无;本包从不组装或发送 provider 请求。 + +## 已知限制与暂缓事项 + +- **没有 kill 控件**——取消仍走模型的 `job_kill`;人工 kill 被 [web job display Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md) 记录的 jobs `reported` 契约问题阻塞。 +- **不渲染通道标签**——stdout 与 stderr chunk 连接成一条流;分通道着色是后续呈现优化。 +- **后台 job 会同时出现在两个头部列表**——job 列表承载控制侧状态,本列表承载输出;这一重复沿用 subagent catalog 的既有取舍。 diff --git a/packages/client/ui-activity/package.json b/packages/client/ui-activity/package.json new file mode 100644 index 0000000000..83395df003 --- /dev/null +++ b/packages/client/ui-activity/package.json @@ -0,0 +1,77 @@ +{ + "name": "@deepseek-ai/dsh-client-ui-activity", + "description": "Session-header live-activity list: roster rows from the activity control stream with on-demand streaming output panels", + "version": "0.1.1-rc.2", + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./invariant": { + "types": "./lib/types/invariant.d.ts", + "default": "./lib/invariant.js" + }, + "./client": { + "types": "./lib/types/client/index.d.ts", + "default": "./lib/client.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "scripts": { + "bundle": "tsdown", + "watch": "tsdown --watch" + }, + "license": "MIT", + "repository": { + "type": "git", + "url": "git+https://github.com/deepseek-ai/deepseek-harness.git", + "directory": "packages/client/ui-activity" + }, + "publishConfig": { + "access": "public" + }, + "peerDependencies": { + "@deepseek-ai/cordis": "workspace:^", + "@deepseek-ai/dsh-api-activity-controller": "workspace:^", + "@deepseek-ai/dsh-client-locale": "workspace:^", + "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", + "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", + "@deepseek-ai/dsh-client-ui-session": "workspace:^", + "@deepseek-ai/dsh-invariants": "workspace:^" + }, + "devDependencies": { + "@deepseek-ai/cordis": "workspace:^", + "@deepseek-ai/dsh-api-activity-controller": "workspace:^", + "@deepseek-ai/dsh-client-locale": "workspace:^", + "@deepseek-ai/dsh-client-test-runtime": "workspace:^", + "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", + "@deepseek-ai/dsh-client-ui-primitives": "workspace:^", + "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", + "@deepseek-ai/dsh-client-ui-session": "workspace:^", + "@deepseek-ai/dsh-client-ui-slots": "workspace:^", + "@deepseek-ai/dsh-invariants": "workspace:^", + "@types/react": "~18.3.1", + "react": "^18.2.0" + }, + "files": [ + "lib/index.js", + "lib/invariant.js", + "lib/client.js", + "lib/types/**/*.d.ts" + ], + "dsh": { + "client": { + "inject": [ + "@deepseek-ai/dsh-api-activity-controller", + "@deepseek-ai/dsh-client-locale", + "@deepseek-ai/dsh-client-ui-conversation", + "@deepseek-ai/dsh-client-ui-primitives" + ], + "platform": "web" + } + } +} diff --git a/packages/client/ui-activity/src/client/ActivityListAction.module.css b/packages/client/ui-activity/src/client/ActivityListAction.module.css new file mode 100644 index 0000000000..2cf3af6e2f --- /dev/null +++ b/packages/client/ui-activity/src/client/ActivityListAction.module.css @@ -0,0 +1,155 @@ +.root { + position: relative; +} + +.trigger { + display: inline-flex; + align-items: center; + gap: 3px; + min-height: 28px; + padding: 3px 2px; + border: 0; + border-radius: 6px; + background: transparent; + color: var(--dsw-alias-label-tertiary); + font-size: 12px; + line-height: 18px; + cursor: pointer; +} + +.trigger:hover, +.trigger:focus-visible { + color: var(--dsw-alias-label-secondary); +} + +.trigger svg { + transition: transform 120ms ease; +} + +.triggerOpen { + transform: rotate(180deg); +} + +.triggerDot { + flex: none; +} + +.count { + margin: 0 5px; +} + +.menu { + position: absolute; + top: calc(100% + 5px); + left: 0; + z-index: 100; + box-sizing: border-box; + display: flex; + flex-direction: column; + gap: 1px; + width: 440px; + max-width: min(520px, calc(100vw - 32px)); + max-height: min(480px, calc(100vh - 140px)); + margin: 0; + padding: 4px; + overflow: auto; + list-style: none; + border: 1px solid var(--dsw-alias-border-l2); + border-radius: 12px; + background: var(--dsw-specific-menu); + --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2); + --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2); + box-shadow: var(--dsw-shadow-lv3); +} + +.item { + display: flex; + flex-direction: column; +} + +.row { + display: flex; + align-items: center; + gap: 8px; + box-sizing: border-box; + width: 100%; + min-height: 32px; + padding: 6px 8px; + border: 0; + border-radius: 8px; + background: transparent; + color: var(--dsw-alias-label-primary); + font-size: 13px; + line-height: 18px; + text-align: left; + cursor: pointer; +} + +.row:hover, +.row:focus-visible { + background: var(--dsw-alias-fill-l1); +} + +.rowSettled { + color: var(--dsw-alias-label-tertiary); +} + +.rowDot { + flex: none; +} + +.kind { + flex: none; + padding: 0 6px; + border-radius: 5px; + background: var(--dsw-alias-fill-l2); + color: var(--dsw-alias-label-secondary); + font-size: 11px; + line-height: 18px; +} + +.label { + flex: 1; + min-width: 0; + overflow: hidden; + font-family: var(--dsw-font-mono); + white-space: nowrap; + text-overflow: ellipsis; +} + +/* A failed activity's detail is the producer's raw text, so it has no bound; + without this it widens the row past the menu instead of eliding like .label. */ +.status { + flex: none; + max-width: 40%; + overflow: hidden; + color: var(--dsw-alias-label-tertiary); + font-size: 11px; + line-height: 18px; + white-space: nowrap; + text-overflow: ellipsis; +} + +.chevron { + flex: none; + color: var(--dsw-alias-label-tertiary); +} + +.chevronOpen { + transform: rotate(180deg); +} + +.panel { + margin: 0 8px 8px; +} + +.notice { + margin: 0 8px 6px; + color: var(--dsw-alias-label-tertiary); + font-size: 11px; + line-height: 16px; +} + +.noticeError { + color: var(--dsw-alias-label-error, var(--dsw-alias-label-secondary)); +} diff --git a/packages/client/ui-activity/src/client/ActivityListAction.tsx b/packages/client/ui-activity/src/client/ActivityListAction.tsx new file mode 100644 index 0000000000..698815e171 --- /dev/null +++ b/packages/client/ui-activity/src/client/ActivityListAction.tsx @@ -0,0 +1,250 @@ +import { useEffect, useMemo, useRef, useState, type KeyboardEvent } from 'react' +import type { + ActivityFeedSnapshot, ActivityId, ActivityRow, ObservedActivity, +} from '@deepseek-ai/dsh-api-activity-controller/client' +import { + IconChevronDownOutline14, StateDot, TerminalBlock, useDismissOnOutsidePointer, + type StateDotState, type TerminalBlockLabels, +} from '@deepseek-ai/dsh-client-ui-primitives' +import type { InjectFace, PropsLocale, PropsRuntime, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots' +import { NS } from './locales.ts' +import type {} from '@deepseek-ai/dsh-client-ui-conversation/client' +import css from './ActivityListAction.module.css' + +/** Registration-side business face for the activity feed. */ +export interface ActivityListInjected { + hooks: { + /** Client activity snapshot bound by the renderer as useActivity. */ + activity: { + getSnapshot(): ActivityFeedSnapshot + subscribe(listener: () => void): () => void + } + } + /** + * Start observing one activity's live output; returns the stop function. + * Reference-counted by the client feed, so panels can overlap safely. + */ + observe: (id: ActivityId) => () => void +} + +/** Full props for the session-header live-activity action. */ +export type ActivityListActionProps = + PropsRuntime<'conversation.session.header.actions'> + & PropsLocale + & InjectFace + +/** Stable empty list so a session with no activities keeps one array identity. */ +const NO_ROWS: readonly ActivityRow[] = [] + +/** Height cap for one live output panel inside the popover. */ +const PANEL_MAX_LINES = 16 + +function isLive(row: ActivityRow): boolean { + return row.status === 'running' +} + +/** Closed-union exhaustiveness fence for the wire status set. */ +/* v8 ignore next 3 -- closed-union backstop; only reached if a status is forged */ +function assertNever(value: never): never { + throw new Error(`unhandled activity status: ${JSON.stringify(value)}`) +} + +function dotState(status: ActivityRow['status']): StateDotState { + switch (status) { + case 'running': return 'ongoing' + case 'completed': return 'done' + case 'killed': return 'warning' + case 'failed': return 'error' + /* v8 ignore next -- closed wire status union */ + default: return assertNever(status) + } +} + +function statusLabel(status: ActivityRow['status'], t: TranslateNS): string { + switch (status) { + case 'running': return t('status.running') + case 'completed': return t('status.completed') + case 'killed': return t('status.killed') + case 'failed': return t('status.failed') + /* v8 ignore next -- closed wire status union */ + default: return assertNever(status) + } +} + +/** Localized display copy for the embedded terminal panel. */ +function terminalLabels(t: TranslateNS): TerminalBlockLabels { + return { + // The labels contract requires exit-fact formatters, but this panel never + // passes exit facts, so TerminalBlock never invokes them. + /* v8 ignore next */ + signal: signal => t('terminal.signal', { signal }), + /* v8 ignore next */ + exitCode: code => t('terminal.exitCode', { code }), + running: t('terminal.running'), + failed: t('terminal.failed'), + done: t('terminal.done'), + copy: t('terminal.copy'), + copied: t('terminal.copied'), + noOutput: t('terminal.noOutput'), + collapseAria: t('terminal.collapseAria'), + collapse: t('terminal.collapse'), + expandAria: hidden => t('terminal.expandAria', { n: hidden }), + expand: hidden => t('terminal.expand', { n: hidden }), + } +} + +/* jscpd:ignore-start -- mirrors JobListAction's ordering and trigger chrome by design so the two header lists read as one family. */ +/** Live rows first in start order, then settled rows newest-first. */ +function ordered(rows: readonly ActivityRow[]): ActivityRow[] { + return [...rows].sort((left, right) => { + const liveLeft = isLive(left) + if (liveLeft !== isLive(right)) return liveLeft ? -1 : 1 + if (liveLeft) return left.startedAt - right.startedAt + const finished = (right.finishedAt ?? right.startedAt) - (left.finishedAt ?? left.startedAt) + return finished !== 0 ? finished : left.startedAt - right.startedAt + }) +} +/* jscpd:ignore-end */ + +/** One expandable roster row plus its on-demand live output panel. */ +function ActivityItem({ row, view, expanded, onToggle, t }: { + row: ActivityRow + view: ObservedActivity | undefined + expanded: boolean + onToggle: () => void + t: TranslateNS +}) { + const live = isLive(row) + const status = statusLabel(row.status, t) + const labels = useMemo(() => terminalLabels(t), [t]) + return ( +
  • + + {expanded + ? ( +
    + {view?.gapBefore === true ?
    {t('output.gap')}
    : null} + {view?.error !== undefined + ?
    {t('output.error', { error: view.error })}
    + : null} + +
    + ) + : null} +
  • + ) +} + +/** + * Session-header entry point for this session's live activities. It renders + * nothing at all until the session can see at least one activity, expanding a + * row starts its observation stream, and collapsing (or closing the popover) + * stops it — output only flows while someone is watching. + * @param props - runtime slot currency, the activity snapshot hook, the + * observation control, and the namespace translator. + * @returns the trigger and its popover list, or null when there is nothing to show. + */ +export function ActivityListAction({ sessionId, useActivity, observe, t }: ActivityListActionProps) { + const owned = useActivity(state => state.rowsBySession[sessionId]) ?? NO_ROWS + const unowned = useActivity(state => state.rowsBySession['']) ?? NO_ROWS + const observedViews = useActivity(state => state.observed) + const [open, setOpen] = useState(false) + const [expandedId, setExpandedId] = useState(undefined) + const rootRef = useRef(null) + const triggerRef = useRef(null) + + const rows = useMemo(() => ordered([...owned, ...unowned]), [owned, unowned]) + const liveCount = useMemo(() => rows.filter(isLive).length, [rows]) + + useDismissOnOutsidePointer(rootRef, open, setOpen) + + // Observation follows visibility: the stream opens when a panel expands and + // closes when it collapses, unmounts, or the popover closes. + const activeId = open ? expandedId : undefined + useEffect(() => { + if (activeId === undefined) return + return observe(activeId as ActivityId) + }, [activeId, observe]) + + // The last activity disappearing removes this control; close first so focus + // does not vanish from an unmounting node. + useEffect(() => { + if (rows.length === 0 && open) setOpen(false) + }, [rows.length, open]) + + // An expanded row that left the roster (owner disposal) folds its panel. + useEffect(() => { + if (expandedId !== undefined && !rows.some(row => String(row.id) === expandedId)) { + setExpandedId(undefined) + } + }, [rows, expandedId]) + + if (rows.length === 0) return null + + const countKey = liveCount > 0 + ? (liveCount === 1 ? 'count.live.one' : 'count.live.other') + : (rows.length === 1 ? 'count.idle.one' : 'count.idle.other') + const countLabel = t(countKey, { count: liveCount > 0 ? liveCount : rows.length }) + + /* jscpd:ignore-start -- mirrors JobListAction's dismiss/trigger interaction by design. */ + const onKeyDown = (event: KeyboardEvent): void => { + if (event.key !== 'Escape' || !open) return + event.preventDefault() + setOpen(false) + triggerRef.current?.focus() + } + + return ( +
    + + {/* jscpd:ignore-end */} + {open + ? ( +
      + {rows.map(row => ( + { + setExpandedId(current => current === String(row.id) ? undefined : String(row.id)) + }} + t={t} + /> + ))} +
    + ) + : null} +
    + ) +} diff --git a/packages/client/ui-activity/src/client/index.ts b/packages/client/ui-activity/src/client/index.ts new file mode 100644 index 0000000000..83ce0aa7bf --- /dev/null +++ b/packages/client/ui-activity/src/client/index.ts @@ -0,0 +1,48 @@ +/** + * Live-activity plugin, browser half: contributes one session-header action + * that renders the activity roster and, per expanded row, an on-demand + * observation stream's live output. All data arrives through the + * `activityFeed` client service; this plugin holds no transport state. + */ +import type { Context as ClientContext } from '@deepseek-ai/cordis' +import { ActivityListAction } from './ActivityListAction.tsx' +import type { ActivityListInjected } from './ActivityListAction.tsx' +import type {} from '@deepseek-ai/dsh-api-activity-controller/client' +import type {} from '@deepseek-ai/dsh-client-locale/client' +import type {} from '@deepseek-ai/dsh-client-ui-renderer/client' +import type {} from '@deepseek-ai/dsh-client-ui-session/client' +import { en, NS, zh, type ActivityKey } from './locales.ts' + +declare module '@deepseek-ai/dsh-client-ui-slots' { + interface LocaleNamespaceMap { + /** Live-activity list copy. */ + 'activity': ActivityKey + } +} + +export type { ActivityListActionProps, ActivityListInjected } from './ActivityListAction.tsx' + +/** Required services: the activity feed, the slot registry, and dictionaries. */ +export const inject = ['activityFeed', 'slots', 'locale'] + +/** + * Client plugin body: register the dictionaries and the header action. + * @param ctx - client root context. + */ +export function apply(ctx: ClientContext): void { + ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-activity: dictionaries') + ctx.slots.inject( + 'conversation.session.header.actions', + () => ctx.slots.register({ + name: 'conversation.session.header.actions', + id: 'activity-list', + // After the background-job list: job control reads before live output. + order: 30, + locale: NS, + inject: (): ActivityListInjected => ({ + hooks: { activity: ctx.activityFeed.state }, + observe: id => ctx.activityFeed.observe(id), + }), + }, ActivityListAction), + ) +} diff --git a/packages/client/ui-activity/src/client/locales.ts b/packages/client/ui-activity/src/client/locales.ts new file mode 100644 index 0000000000..efea5126da --- /dev/null +++ b/packages/client/ui-activity/src/client/locales.ts @@ -0,0 +1,65 @@ +/** `activity` namespace dictionaries. */ + +/** Dictionary namespace owned by this plugin. */ +export const NS = 'activity' + +/** Simplified Chinese dictionary (the key-set source of truth). */ +export const zh = { + 'count.live.one': '{count} 个活动进行中', + 'count.live.other': '{count} 个活动进行中', + 'count.idle.one': '{count} 个活动', + 'count.idle.other': '{count} 个活动', + 'list.aria': '实时活动', + 'row.expandAria': '展开 {label} 的实时输出', + 'row.collapseAria': '收起 {label} 的实时输出', + 'status.running': '运行中', + 'status.completed': '已完成', + 'status.killed': '已取消', + 'status.failed': '已失败', + 'output.gap': '……较早的输出已丢弃……', + 'output.error': '实时输出流中断:{error}', + 'terminal.signal': '信号 {signal}', + 'terminal.exitCode': '退出码 {code}', + 'terminal.running': '运行中', + 'terminal.failed': '已失败', + 'terminal.done': '已完成', + 'terminal.copy': '复制', + 'terminal.copied': '已复制', + 'terminal.noOutput': '(无输出)', + 'terminal.collapse': '收起', + 'terminal.collapseAria': '收起输出', + 'terminal.expand': '展开其余 {n} 行', + 'terminal.expandAria': '展开被折叠的 {n} 行输出', +} as const + +/** English dictionary, key-identical to the Chinese source of truth. */ +export const en: Record = { + 'count.live.one': '{count} live activity', + 'count.live.other': '{count} live activities', + 'count.idle.one': '{count} activity', + 'count.idle.other': '{count} activities', + 'list.aria': 'Live activities', + 'row.expandAria': 'Show live output of {label}', + 'row.collapseAria': 'Hide live output of {label}', + 'status.running': 'running', + 'status.completed': 'completed', + 'status.killed': 'cancelled', + 'status.failed': 'failed', + 'output.gap': '… earlier output dropped …', + 'output.error': 'live output stream interrupted: {error}', + 'terminal.signal': 'signal {signal}', + 'terminal.exitCode': 'exit {code}', + 'terminal.running': 'running', + 'terminal.failed': 'failed', + 'terminal.done': 'done', + 'terminal.copy': 'Copy', + 'terminal.copied': 'Copied', + 'terminal.noOutput': '(no output)', + 'terminal.collapse': 'Collapse', + 'terminal.collapseAria': 'Collapse output', + 'terminal.expand': 'Show {n} more lines', + 'terminal.expandAria': 'Expand {n} collapsed output lines', +} + +/** Key domain of the `activity` namespace (zh is the source of truth). */ +export type ActivityKey = keyof typeof zh diff --git a/packages/client/ui-activity/src/css-modules.d.ts b/packages/client/ui-activity/src/css-modules.d.ts new file mode 100644 index 0000000000..8811db1264 --- /dev/null +++ b/packages/client/ui-activity/src/css-modules.d.ts @@ -0,0 +1,4 @@ +declare module '*.module.css' { + const classes: Record + export default classes +} diff --git a/packages/client/ui-activity/src/index.ts b/packages/client/ui-activity/src/index.ts new file mode 100644 index 0000000000..f75578ddaf --- /dev/null +++ b/packages/client/ui-activity/src/index.ts @@ -0,0 +1,9 @@ +/** + * Node half of the live-activity list plugin. The browser half in + * `src/client/` owns every contribution; this entry exists so the package + * appears as an ordinary Loader row. + * @module @deepseek-ai/dsh-client-ui-activity + */ + +/** Loader-visible no-op body; the browser half carries the feature. */ +export function apply(): void {} diff --git a/packages/client/ui-activity/src/invariant.ts b/packages/client/ui-activity/src/invariant.ts new file mode 100644 index 0000000000..22eba24c42 --- /dev/null +++ b/packages/client/ui-activity/src/invariant.ts @@ -0,0 +1,27 @@ +/** + * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-activity`. + * @module @deepseek-ai/dsh-client-ui-activity/invariant + */ + +/* jscpd:ignore-start */ +import type { Context } from '@deepseek-ai/cordis' +import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants' + +const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-activity' + +/** Cordis companion plugin name. */ +export const name = 'client-ui-activity-invariant' +/** Service required before the companion can reserve package ownership. */ +export const inject = ['invariants'] + +/** No runtime invariant: pure presentation over the activity feed's client snapshot; the feed's own packages assert the data relations. */ +const install: InvariantInstaller = () => {} + +/** + * Register this package's invariant companion. + * @param ctx - Cordis context carrying the invariant service. + * @returns the installed registration's disposer after setup succeeds. + */ +export const apply = (ctx: Context): Promise<() => void> => + Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install)) +/* jscpd:ignore-end */ diff --git a/packages/client/ui-activity/tests/activity-list-action.client.spec.tsx b/packages/client/ui-activity/tests/activity-list-action.client.spec.tsx new file mode 100644 index 0000000000..96156c798d --- /dev/null +++ b/packages/client/ui-activity/tests/activity-list-action.client.spec.tsx @@ -0,0 +1,244 @@ +// @vitest-environment jsdom +import { afterEach, describe, expect, it, vi } from 'vitest' +import { cleanup, fireEvent, render, screen, within } from '@testing-library/react' +import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime' +import type { + ActivityFeedSnapshot, ActivityId, ActivityRow, ObservedActivity, +} from '@deepseek-ai/dsh-api-activity-controller/client' +import type { SessionId } from '@deepseek-ai/dsh-session/types' +import { ActivityListAction, type ActivityListActionProps } from '../src/client/ActivityListAction.tsx' +import { zh } from '../src/client/locales.ts' + +afterEach(() => { + cleanup() + vi.restoreAllMocks() +}) + +const SESSION = 'session' as SessionId +const t: ActivityListActionProps['t'] = makeTranslate(zh) + +function row(over: Partial = {}): ActivityRow { + return { + id: 'bash-1' as ActivityId, + kind: 'bash', + label: 'pnpm run build', + sessionId: SESSION, + status: 'running', + startedAt: 1_700_000_000_000, + outputTotal: 0, + ...over, + } +} + +/** A row with no owner session, as the unowned bucket carries them. */ +function unownedRow(over: Partial = {}): ActivityRow { + const { sessionId: _drop, ...rest } = row(over) + return rest +} + +function props( + snapshot: Partial, + observe: ActivityListActionProps['observe'] = () => () => {}, +): ActivityListActionProps { + const state: ActivityFeedSnapshot = { + rowsBySession: {}, + observed: {}, + phase: 'ready', + ...snapshot, + } + function useActivity(select: (value: ActivityFeedSnapshot) => T): T { + return select(state) + } + return { sessionId: SESSION, useActivity, observe, t } as unknown as ActivityListActionProps +} + +function openList(): void { + fireEvent.click(screen.getAllByRole('button')[0]!) +} + +describe('ActivityListAction visibility', () => { + it('renders nothing while the session sees no activities', () => { + const { container } = render() + expect(container.innerHTML).toBe('') + }) + + it('counts live activities on the trigger, merging owned and unowned rows', () => { + render() + expect(screen.getByRole('button', { name: '2 个活动进行中' })).toBeDefined() + }) + + it('falls back to the total when nothing is live and hides foreign sessions', () => { + render() + expect(screen.getByRole('button', { name: '1 个活动' })).toBeDefined() + }) +}) + +describe('ActivityListAction rows and observation', () => { + it('lists rows with kind, label, and detail-or-status', () => { + render() + openList() + const list = screen.getByRole('list', { name: zh['list.aria'] }) + const items = within(list).getAllByRole('listitem') + expect(items).toHaveLength(2) + expect(items[0]?.textContent).toContain('pnpm run build') + expect(items[0]?.textContent).toContain(zh['status.running']) + expect(items[1]?.textContent).toContain('exit code: 3') + }) + + it('marks killed rows and expands an overflowing panel through the collapse controls', () => { + const lines = Array.from({ length: 24 }, (_value, index) => `line ${index + 1}`).join('\n') + const view: ObservedActivity = { + activityId: 'bash-1' as ActivityId, + text: lines, + gapBefore: false, + status: 'killed', + streaming: false, + } + render() + openList() + expect(screen.getByText(zh['status.killed'])).toBeDefined() + fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) + const expand = screen.getByRole('button', { name: zh['terminal.expandAria'].replace('{n}', '8') }) + fireEvent.click(expand) + expect(screen.getByRole('button', { name: zh['terminal.collapseAria'] })).toBeDefined() + }) + + it('orders live rows first by start and settled rows newest-first with tie-breaks', () => { + const settled = (id: string, label: string, startedAt: number, finishedAt?: number): ActivityRow => + row({ + id: id as ActivityId, + label, + status: 'completed', + startedAt, + ...finishedAt !== undefined ? { finishedAt } : {}, + }) + render() + openList() + const labels = within(screen.getByRole('list', { name: zh['list.aria'] })) + .getAllByRole('listitem') + .map(item => item.querySelector('[title]')?.getAttribute('title')) + expect(labels).toEqual([ + 'live-2', 'live-1', 'settled-d', 'settled-a', 'settled-c', 'settled-b', 'settled-e', + ]) + expect(screen.getAllByText(zh['status.completed']).length).toBeGreaterThan(0) + }) + + it('ignores other keys while open and closes once the roster empties', () => { + const settledPair = [ + row({ id: 'bash-1' as ActivityId, status: 'completed', finishedAt: 2 }), + row({ id: 'bash-2' as ActivityId, status: 'completed', finishedAt: 3 }), + ] + const { rerender } = render() + expect(screen.getByRole('button', { name: '2 个活动' })).toBeDefined() + openList() + const list = screen.getByRole('list', { name: zh['list.aria'] }) + fireEvent.keyDown(list, { key: 'a' }) + expect(screen.getByRole('list', { name: zh['list.aria'] })).toBeDefined() + // The roster emptying unmounts the control entirely; the open flag resets first. + rerender() + expect(screen.queryByRole('button')).toBeNull() + }) + + it('starts observing on expand, renders the live text, and stops on collapse', () => { + const stop = vi.fn() + const observe = vi.fn(() => stop) + const view: ObservedActivity = { + activityId: 'bash-1' as ActivityId, + text: 'compiling…\n', + gapBefore: false, + status: 'running', + streaming: true, + } + render() + openList() + fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) + expect(observe).toHaveBeenCalledWith('bash-1') + expect(screen.getByText('compiling…')).toBeDefined() + + fireEvent.click(screen.getByRole('button', { name: zh['row.collapseAria'].replace('{label}', 'pnpm run build') })) + expect(stop).toHaveBeenCalledTimes(1) + }) + + it('surfaces retention gaps and stream failures above the panel', () => { + const view: ObservedActivity = { + activityId: 'bash-1' as ActivityId, + text: 'tail only', + gapBefore: true, + status: 'running', + streaming: false, + error: 'connection lost', + } + render() + openList() + fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) + expect(screen.getByText(zh['output.gap'])).toBeDefined() + expect(screen.getByText('实时输出流中断:connection lost')).toBeDefined() + }) + + it('stops observation when the popover closes via Escape', () => { + const stop = vi.fn() + render( stop)} />) + openList() + fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) + fireEvent.keyDown(screen.getByRole('list', { name: zh['list.aria'] }), { key: 'Escape' }) + expect(stop).toHaveBeenCalledTimes(1) + expect(screen.queryByRole('list', { name: zh['list.aria'] })).toBeNull() + }) + + it('folds an expanded panel whose row left the roster', () => { + const stop = vi.fn() + // One stable observe identity across renders, as the inject face provides. + const observe = () => stop + const first = props({ rowsBySession: { [SESSION]: [row()] } }, observe) + const { rerender } = render() + openList() + fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) + rerender() + expect(stop).toHaveBeenCalledTimes(1) + expect(screen.queryByRole('button', { name: zh['row.collapseAria'].replace('{label}', 'other') })).toBeNull() + }) +}) diff --git a/packages/client/ui-activity/tests/browser-plugin.client.spec.ts b/packages/client/ui-activity/tests/browser-plugin.client.spec.ts new file mode 100644 index 0000000000..de6db2a069 --- /dev/null +++ b/packages/client/ui-activity/tests/browser-plugin.client.spec.ts @@ -0,0 +1,115 @@ +/** + * ui-activity plugin halves: the browser entry's dictionary and header-slot + * registrations against the real SlotRegistry (with fiber teardown proving + * removal — HMR safety), the inert node entry, and the invariant companion's + * ownership reservation. + */ +import { Context } from '@deepseek-ai/cordis' +import { describe, expect, it } from 'vitest' +import InvariantRegistry from '@deepseek-ai/dsh-invariants' +import { SlotRegistry } from '@deepseek-ai/dsh-client-ui-renderer/client' +import { stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime' +import { apply as applyLocale, inject as localeInject } from '@deepseek-ai/dsh-client-locale/client' +import { apply, inject } from '../src/client/index.ts' +import { apply as applyNode } from '../src/index.ts' +import * as ActivityInvariant from '../src/invariant.ts' +import { en, NS, zh } from '../src/client/locales.ts' + +/** Slot ledger reader: entry ids currently registered in the header list. */ +function headerEntryIds(ctx: Context): (string | undefined)[] { + return ctx.slots + .entries('conversation.session.header.actions') + .map(entry => entry.options.id) +} + +/** Ids handed to the stubbed feed's observe control. */ +const observed: string[] = [] + +/** Boot the browser half over a real slot tree that declares the header list. */ +async function bench(): Promise<{ ctx: Context; fiber: ReturnType }> { + const ctx = new Context() + await ctx.plugin(SlotRegistry).await() + ctx.slots.register({ + name: 'root', + children: { + 'conversation.session.header.actions': { kind: 'list', scope: 'session' }, + }, + } as never, () => null) + ctx.provide('activityFeed', { + state: { getSnapshot: () => ({ rowsBySession: {}, observed: {}, phase: 'pending' }), subscribe: () => () => {} }, + observe: (id: string) => { observed.push(id); return () => {} }, + } as never) + // The locale plugin binds a settings scope, which reads the connection handle + // and the forwarded-event port. + ctx.provide('connection', { api: { settings: {} }, isLoopback: false } as never) + ctx.provide('remote', { $on: () => () => {} } as never) + ctx.provide('settingsScope', { bind: () => stubSettingsScope().scope } as never) + await ctx.plugin({ inject: localeInject, apply: applyLocale }).await() + // These specs assert the shipped Chinese copy. There is no jsdom `window` in + // this lane, so browser-language detection never runs and the locale comes + // from FALLBACK_LOCALE (en): state the asserted locale explicitly. + ctx.locale.setLocale('zh') + const fiber = ctx.plugin({ inject: [...inject], apply }) + await fiber.await() + return { ctx, fiber } +} + +describe('ui-activity browser half', () => { + it('declares the services it binds', () => { + expect(inject).toEqual(['activityFeed', 'slots', 'locale']) + }) + + it('exposes the feed source and observation control through the inject face', async () => { + const { ctx } = await bench() + const entry = ctx.slots + .entries('conversation.session.header.actions') + .find(candidate => candidate.options.id === 'activity-list') + const face = (entry as unknown as { + inject: () => { hooks: { activity: unknown }; observe: (id: string) => () => void } + }).inject() + expect(face.hooks.activity).toBeDefined() + const stopper = face.observe('bash-1') + expect(observed).toEqual(['bash-1']) + stopper() + }) + + it('registers the header action, and fiber teardown removes it (HMR safety)', async () => { + const { ctx, fiber } = await bench() + expect(headerEntryIds(ctx)).toContain('activity-list') + await fiber.dispose() + expect(headerEntryIds(ctx)).not.toContain('activity-list') + }) + + it('registers both dictionaries under its own namespace and releases them with the fiber', async () => { + const { ctx, fiber } = await bench() + const translate = ctx.locale.bind(NS) + expect(translate('list.aria')).toBe(zh['list.aria']) + ctx.locale.setLocale('en') + expect(translate('list.aria')).toBe(en['list.aria']) + + // Withdrawn dictionaries leave the key unresolved rather than translated. + await fiber.dispose() + expect(translate('list.aria')).not.toBe(en['list.aria']) + }) + + it('keeps the English dictionary key-identical to the Chinese source of truth', () => { + expect(Object.keys(en).sort()).toEqual(Object.keys(zh).sort()) + }) +}) + +describe('ui-activity node half', () => { + it('contributes no host behavior', () => { + // The node half exists only so the plugin appears in the Loader tree. + expect(applyNode).not.toThrow() + }) +}) + +describe('ui-activity invariant companion', () => { + it('reserves package ownership under its declared companion name', async () => { + const ctx = new Context() + await ctx.plugin(InvariantRegistry, { enabled: true }) + await ctx.plugin(ActivityInvariant) + expect(ActivityInvariant.name).toBe('client-ui-activity-invariant') + expect(ActivityInvariant.inject).toEqual(['invariants']) + }) +}) diff --git a/packages/client/ui-activity/tsconfig.json b/packages/client/ui-activity/tsconfig.json new file mode 100644 index 0000000000..bbd9c5ce85 --- /dev/null +++ b/packages/client/ui-activity/tsconfig.json @@ -0,0 +1,22 @@ +{ + "extends": "../../../tsconfig.base.client.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { "path": "../../../vendor/cosmokit" }, + { "path": "../../../vendor/cordis" }, + { "path": "../../api/activity-controller/tsconfig.client.json" }, + { "path": "../locale" }, + { "path": "../ui-conversation" }, + { "path": "../ui-primitives" }, + { "path": "../ui-renderer" }, + { "path": "../ui-session" }, + { "path": "../ui-slots" }, + { "path": "../../runtime-diagnostics/invariants" } + ] +} diff --git a/packages/client/ui-activity/tsdown.config.ts b/packages/client/ui-activity/tsdown.config.ts new file mode 100644 index 0000000000..096771fe90 --- /dev/null +++ b/packages/client/ui-activity/tsdown.config.ts @@ -0,0 +1,6 @@ +import { clientBundle } from '../tsdown.client.ts' + +export default clientBundle( + '@deepseek-ai/dsh-client-ui-activity', + ['lib/types/index.js', 'lib/types/invariant.js'], +) diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml index 720136b270..a025628aa4 100644 --- a/packages/client/ui-primitives/README.i18n.yaml +++ b/packages/client/ui-primitives/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-primitives/README.md -README.md: c1c40e39710d46fae240f0b3281c36d660855010 -README.zh.md: 631936ad658c147923e5f80f2d7445cac93d6b36 +README.md: 4df368b270511776896c74a55b0c1d2e684035d0 +README.zh.md: 77830a1f162e963709ea4d4d25c8393e7dd97d66 diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md index c1c40e3971..4df368b270 100644 --- a/packages/client/ui-primitives/README.md +++ b/packages/client/ui-primitives/README.md @@ -18,7 +18,7 @@ Pure React atoms (zero cordis): StateDot, DisclosureRow, ic_ds_* icons, Button/P ## Terminal output -`TerminalBlock` renders a shell command as a terminal surface: one prompt row per line of the command (the shortened `cwd` label on the first row only, since the view knows one working directory and a `cd` moves later lines elsewhere, then that line), the command's output, a status pill for a non-zero exit code or a terminating signal, and a copy control that writes the raw `output` prop. A run-state `StateDot` marks the call once, on the first row, out of flow in a gutter the card reserves as its own left padding, so the dot sits inside the card box yet left of the prompt text. It reaches three of `StateDot`'s states — the chase while `running`, red for the same exit status that renders the pill, green otherwise — so a card states whether its command is still running rather than leaving that to be inferred from the presence of output; it carries one visually hidden text label because `StateDot` is `aria-hidden`. One dot regardless of line count is deliberate: the exit status is the whole call's, so a dot per line would claim a per-line outcome the view does not carry. Command text is `white-space: pre`, so repeated spaces, tabs, and an indented continuation render verbatim while the row stays single-line and ellipsizes. ANSI escape sequences are parsed with `anser` (bundled into this package's browser artifact) into React spans; cursor movements replay into a per-line column buffer before inert controls are stripped, since carriage return and backspace only MOVE the cursor: `100%` + CR + `OK` alone shows `OK0%`, while the `\x1b[K` a spinner writes with its redraw erases the tail so `100%\r\x1b[KOK` shows `OK`. Erase-in-line is honored in all three parameter forms, the cursor advances by terminal columns (8-column tab stops, two for emoji and CJK, none for a combining mark), and SGR state is normalized per cell as a terminal stores it, threading across lines and closing at the state the line ended in; basic-16 foreground colors map onto `--dsw-*` tokens, while 256-palette and truecolor values pass through as literal rgb. Output keeps `white-space: pre` with horizontal scrolling, so column-aligned output holds its alignment instead of soft-wrapping, and collapses to a head slice plus a tail slice past `maxLines` (default 16) behind an expand button. Rationale: [the web terminal card note](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md). +`TerminalBlock` renders a shell command as a terminal surface: one prompt row per line of the command (the shortened `cwd` label on the first row only, since the view knows one working directory and a `cd` moves later lines elsewhere, then that line), the command's output, a status pill for a non-zero exit code or a terminating signal, and a copy control that writes the raw `output` prop. A run-state `StateDot` marks the call once, on the first row, out of flow in a gutter the card reserves as its own left padding, so the dot sits inside the card box yet left of the prompt text. It reaches three of `StateDot`'s states — the chase while `running`, red for the same exit status that renders the pill, green otherwise — so a card states whether its command is still running rather than leaving that to be inferred from the presence of output; a running block with a supplied `output` renders that live text under the running state (an undefined output keeps the historical prompt-only frame); it carries one visually hidden text label because `StateDot` is `aria-hidden`. One dot regardless of line count is deliberate: the exit status is the whole call's, so a dot per line would claim a per-line outcome the view does not carry. Command text is `white-space: pre`, so repeated spaces, tabs, and an indented continuation render verbatim while the row stays single-line and ellipsizes. ANSI escape sequences are parsed with `anser` (bundled into this package's browser artifact) into React spans; cursor movements replay into a per-line column buffer before inert controls are stripped, since carriage return and backspace only MOVE the cursor: `100%` + CR + `OK` alone shows `OK0%`, while the `\x1b[K` a spinner writes with its redraw erases the tail so `100%\r\x1b[KOK` shows `OK`. Erase-in-line is honored in all three parameter forms, the cursor advances by terminal columns (8-column tab stops, two for emoji and CJK, none for a combining mark), and SGR state is normalized per cell as a terminal stores it, threading across lines and closing at the state the line ended in; basic-16 foreground colors map onto `--dsw-*` tokens, while 256-palette and truecolor values pass through as literal rgb. Output keeps `white-space: pre` with horizontal scrolling, so column-aligned output holds its alignment instead of soft-wrapping, and collapses to a head slice plus a tail slice past `maxLines` (default 16) behind an expand button. Rationale: [the web terminal card note](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md). ## Read rendering diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md index 631936ad65..77830a1f16 100644 --- a/packages/client/ui-primitives/README.zh.md +++ b/packages/client/ui-primitives/README.zh.md @@ -18,7 +18,7 @@ ## 终端输出 -`TerminalBlock` 将一条 shell 命令渲染为终端表层:命令的每一行各占一个提示行(缩短后的 `cwd` 标签只出现在第一行,因为视图只知道一个工作目录,而一个 `cd` 就会让后面的行去到别处,标签之后是该行)、命令输出、非零退出码或终止信号对应的状态胶囊,以及写入原始 `output` prop 的复制控件。一枚运行状态 `StateDot` 为整次调用标记一次,位于第一行,以脱离文档流的方式落在卡片以自身左内边距预留的落区中,因此它位于卡片盒之内、提示文字之左。它用到 `StateDot` 的三种状态——`running` 期间为追逐动画,与渲染状态胶囊相同的退出状态为红色,其余为绿色——因此卡片直接陈述其命令是否仍在运行,而不是让人从有无输出中推断;由于 `StateDot` 是 `aria-hidden`,它携带一处视觉隐藏的文本标签。无论多少行都只有一枚状态点是有意为之:退出状态属于整次调用,因此每行一枚就会声称一个视图并不携带的逐行结果。命令文本使用 `white-space: pre`,因此重复空格、制表符与缩进续行都原样呈现,同时该行仍保持单行并以省略号截断。ANSI 转义序列通过 `anser`(打进本包浏览器产物)解析为 React span;光标移动在剥除无显示意义控制符之前先重放进逐行的列缓冲,因为回车与退格**只移动**光标:单是 `100%` 加回车再加 `OK` 显示为 `OK0%`,而 spinner 随重绘写出的 `\x1b[K` 会擦掉尾巴,因此 `100%\r\x1b[KOK` 显示为 `OK`。行内擦除的三种参数形式都被遵循,光标按终端列推进(8 列制表位;emoji 与 CJK 占两列;组合标记不占列),SGR 状态按单元格归一化存储,与终端一致,并跨行延续、在行结束时的状态处收束;基础 16 色前景色映射到 `--dsw-*` token,而 256 色板与真彩色值按字面 rgb 透传。输出保持 `white-space: pre` 并支持横向滚动,因此按列对齐的输出保留其对齐而不会软换行;超过 `maxLines`(默认 16)时折叠为头部切片加尾部切片,由展开按钮控制。原理:[Web 终端卡片笔记](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md)。 +`TerminalBlock` 将一条 shell 命令渲染为终端表层:命令的每一行各占一个提示行(缩短后的 `cwd` 标签只出现在第一行,因为视图只知道一个工作目录,而一个 `cd` 就会让后面的行去到别处,标签之后是该行)、命令输出、非零退出码或终止信号对应的状态胶囊,以及写入原始 `output` prop 的复制控件。一枚运行状态 `StateDot` 为整次调用标记一次,位于第一行,以脱离文档流的方式落在卡片以自身左内边距预留的落区中,因此它位于卡片盒之内、提示文字之左。它用到 `StateDot` 的三种状态——`running` 期间为追逐动画,与渲染状态胶囊相同的退出状态为红色,其余为绿色——因此卡片直接陈述其命令是否仍在运行,而不是让人从有无输出中推断;运行中且提供了 `output` 的块会在 running 状态下渲染这段实时文本(未提供 output 则保持历史上的仅提示行画面);由于 `StateDot` 是 `aria-hidden`,它携带一处视觉隐藏的文本标签。无论多少行都只有一枚状态点是有意为之:退出状态属于整次调用,因此每行一枚就会声称一个视图并不携带的逐行结果。命令文本使用 `white-space: pre`,因此重复空格、制表符与缩进续行都原样呈现,同时该行仍保持单行并以省略号截断。ANSI 转义序列通过 `anser`(打进本包浏览器产物)解析为 React span;光标移动在剥除无显示意义控制符之前先重放进逐行的列缓冲,因为回车与退格**只移动**光标:单是 `100%` 加回车再加 `OK` 显示为 `OK0%`,而 spinner 随重绘写出的 `\x1b[K` 会擦掉尾巴,因此 `100%\r\x1b[KOK` 显示为 `OK`。行内擦除的三种参数形式都被遵循,光标按终端列推进(8 列制表位;emoji 与 CJK 占两列;组合标记不占列),SGR 状态按单元格归一化存储,与终端一致,并跨行延续、在行结束时的状态处收束;基础 16 色前景色映射到 `--dsw-*` token,而 256 色板与真彩色值按字面 rgb 透传。输出保持 `white-space: pre` 并支持横向滚动,因此按列对齐的输出保留其对齐而不会软换行;超过 `maxLines`(默认 16)时折叠为头部切片加尾部切片,由展开按钮控制。原理:[Web 终端卡片笔记](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md)。 ## Read 渲染 diff --git a/packages/client/ui-primitives/src/TerminalBlock.tsx b/packages/client/ui-primitives/src/TerminalBlock.tsx index 26e26fe2d2..8f87db9741 100644 --- a/packages/client/ui-primitives/src/TerminalBlock.tsx +++ b/packages/client/ui-primitives/src/TerminalBlock.tsx @@ -54,7 +54,10 @@ export interface TerminalBlockProps { exitCode?: number | undefined /** Settled terminating signal name; any value renders the status pill, taking precedence over the exit code. */ signal?: string | undefined - /** The command is still running: the block shows the prompt line alone. */ + /** + * The command is still running: with no `output` the block shows the prompt + * line alone; with output it renders the live text under the running state. + */ running?: boolean | undefined /** Height cap in output lines before the middle collapses (default {@link DEFAULT_TERMINAL_MAX_LINES}); Infinity disables the cap. */ maxLines?: number | undefined @@ -221,13 +224,16 @@ export function TerminalBlock({ ))} {status !== undefined && {status}} - {!running && !empty && ( + {(!running || output !== undefined) && !empty && ( )} - {!running && (empty + {/* A running block renders its live text as soon as the caller supplies + output; an undefined output keeps the historical prompt-only frame, + and a live-but-empty stream draws no placeholder. */} + {(!running || (output !== undefined && !empty)) && (empty && !running ?
    {copy.noOutput}
    : (
    diff --git a/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx b/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx index 45de33c8f0..886661b396 100644 --- a/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx +++ b/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx @@ -89,15 +89,30 @@ describe('TerminalBlock prompt label', () => { }) describe('TerminalBlock states', () => { - it('running shows the command line only: no output, no placeholder, no copy', () => { - const view = render() + it('running with no output shows the command line only: no output box, no placeholder, no copy', () => { + const view = render() expect(view.getByText('sleep 5')).toBeTruthy() - expect(view.queryByText('partial')).toBeNull() + expect(outputLines(view.container)).toEqual([]) expect(view.queryByText('无输出')).toBeNull() expect(view.queryByRole('button')).toBeNull() expect(view.container.firstElementChild?.getAttribute('data-running')).toBe('') }) + it('running with supplied output streams the live text and keeps it copyable', () => { + const view = render() + expect(view.getByText('partial')).toBeTruthy() + expect(view.queryByText('无输出')).toBeNull() + expect(view.queryByRole('button', { name: '复制' })).toBeTruthy() + expect(view.container.firstElementChild?.getAttribute('data-running')).toBe('') + }) + + it('running with an empty live stream draws neither output nor placeholder', () => { + const view = render() + expect(outputLines(view.container)).toEqual([]) + expect(view.queryByText('无输出')).toBeNull() + expect(view.queryByRole('button')).toBeNull() + }) + it('running still shows a settled-looking status pill when one is supplied', () => { render() expect(screen.getByText('信号 SIGINT')).toBeTruthy() diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts index e038b24a0d..1a53958b6c 100644 --- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts +++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts @@ -1141,6 +1141,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ slotInject: '', declaredBy: 'an entry in \'conversation.session.header\' (client-ui-conversation), so it exists while that entry is mounted', occupants: [ + 'client-ui-activity ActivityListAction id \'activity-list\'', 'client-ui-agent-preset AgentPresetLabel id \'agent-preset\'', 'client-ui-jobs JobListAction id \'job-list\'', ], diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 320c44b9aa..35c3b93d92 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -81,6 +81,68 @@ export interface TypeApiEntry { /** Every harness `ctx.` service, sorted by key. */ export const SERVICE_API: readonly ServiceApiEntry[] = [ + { + key: 'activities', + summary: 'Abstract streaming-output registry.', + description: 'Abstract streaming-output registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.activities` (one implementation per context; loading a second throws, which is cordis\' standard duplicate-service behavior).\n\nImplementations must honor these semantics:\n\n- Observation never consumes. Any number of readers hold their own absolute byte offsets; a read changes no cursor and no producer state, so the model-facing paths (`ctx.jobs.read()`, tool results) are unaffected.\n- Records outlive producer fibers. Owner disposal ends still-open records and removes them; service disposal ends and clears everything. Neither awaits a producer — the registry owns no execution resource.\n- Retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement trims retention to the settled cap.\n- Listener delivery is owner-relative: a listener registered from an unscoped context — a host composition\'s own carrier — sees every owner, while one registered under an agent composition\'s scope sees exactly the agents composed under it. Every listener is contained.', + methods: [ + { + signature: 'abstract open(spec: ActivityOpen): ActivityHandle', + description: 'Validate the spec, attach owner cleanup, and atomically register one activity. A rejection leaves no id; after return the producer owns the handle and the visible set has changed.', + parameters: [{ name: 'spec', description: 'activity identity, owner, and correlation.' }], + returns: 'the producer face of the registered activity.', + }, + { + signature: 'abstract list(caller?: Agent): ActivitySnapshot[]', + description: 'List caller-owned and unowned activities in registration order without exposing another session\'s labels or output.', + parameters: [{ name: 'caller', description: 'reading agent; a non-agent caller sees only unowned activities.' }], + returns: 'fresh snapshots.', + }, + { + signature: 'abstract get(id: ActivityId, caller?: Agent): ActivitySnapshot', + description: 'Return a fresh snapshot. Throws for an unknown or foreign activity.', + parameters: [{ name: 'id', description: 'activity to look up.' }, { name: 'caller', description: 'reading agent checked against the owner.' }], + returns: 'a fresh snapshot.', + }, + { + signature: 'abstract read(id: ActivityId, from: number, caller?: Agent): ActivityRead', + description: 'Read retained output from an absolute byte offset without consuming it. Resume by passing a previous read\'s `next`; a foreign offset inside a retained chunk returns that whole chunk (its `at` may precede `from`). Throws for an unknown or foreign activity or a negative or non-integer offset.', + parameters: [{ name: 'id', description: 'activity to read.' }, { name: 'from', description: 'absolute byte offset to read from (0 for the retained head).' }, { name: 'caller', description: 'reading agent checked against the owner.' }], + returns: 'retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag.', + }, + { + signature: 'abstract onActivitiesChanged(listener: ActivitiesChangedListener): () => void', + description: 'Register an effect-scoped observer of visible-set changes: opening, detail updates, settlement, owner-disposal removal, and the emptying that service disposal commits — so an observer re-reads rather than accumulating deltas. Listeners are contained and never awaited.', + parameters: [{ name: 'listener', description: 'receives the owner whose visible set changed, or `undefined` when an unowned activity changed and every caller\'s set did.' }], + returns: 'disposer that unregisters the listener.', + }, + { + signature: 'abstract onOutput(listener: ActivityOutputListener): () => void', + description: 'Register an effect-scoped observer of stream advancement — one signal per committed append and one at settlement, carrying only the activity id. A consumer schedules a read from its own cursor; the registry never pushes payloads. Listeners are contained and never awaited.', + parameters: [{ name: 'listener', description: 'receives the id whose stream advanced.' }], + returns: 'disposer that unregisters the listener.', + }, + ], + }, + { + key: 'activityController', + summary: 'Host service backing the generated `ctx.remote.activity` namespace.', + description: 'Host service backing the generated `ctx.remote.activity` namespace.', + methods: [ + { + signature: '@Remote({ mode: \'stream\' }) control(signal: AbortSignal): AsyncIterable', + description: 'Stream a complete roster baseline followed by whole-bucket replacements.', + parameters: [{ name: 'signal', description: 'generation cancellation.' }], + returns: 'baseline followed by per-owner roster replacement frames.', + }, + { + signature: '@Remote({ mode: \'stream\' }) observe(request: ActivityObserveRequest, signal: AbortSignal): AsyncIterable', + description: 'Stream one activity\'s retained output from an absolute byte offset, then its terminal status once settled and drained. Non-consuming: the model-facing cursors never observe these reads.', + parameters: [{ name: 'request', description: 'target activity and optional resume offset.' }, { name: 'signal', description: 'generation cancellation.' }], + returns: 'anchor, coalesced output frames, and the terminal status.', + }, + ], + }, { key: 'agentDefaultModel', summary: 'Owns the default model selection independently of any Host or transport.', @@ -3115,6 +3177,94 @@ export const EVENT_API: readonly EventApiEntry[] = [ /** Shapes of every exported type the Service and Event signatures reference (transitively), sorted by name. */ export const TYPE_API: readonly TypeApiEntry[] = [ + { + name: 'ActivitiesChangedListener', + declaration: 'export type ActivitiesChangedListener = (owner: Agent | undefined) => void;', + }, + { + name: 'ActivityAppendOptions', + declaration: 'export interface ActivityAppendOptions {\n channel?: ActivityChannel;\n gapBefore?: true;\n}', + }, + { + name: 'ActivityChannel', + declaration: 'export type ActivityChannel = \'stdout\' | \'stderr\';', + }, + { + name: 'ActivityControlFrame', + declaration: 'export type ActivityControlFrame = {\n readonly type: \'baseline\';\n readonly activities: readonly ActivityRow[];\n} | {\n readonly type: \'rows\';\n readonly sessionId?: SessionId;\n readonly activities: readonly ActivityRow[];\n};', + }, + { + name: 'ActivityCorrelation', + declaration: 'export interface ActivityCorrelation {\n callId?: CallId;\n jobId?: JobId;\n}', + }, + { + name: 'ActivityHandle', + declaration: 'export interface ActivityHandle {\n readonly id: ActivityId;\n append(text: string, options?: ActivityAppendOptions): void;\n updateDetail(detail: string): void;\n end(outcome: ActivityOutcome): void;\n}', + }, + { + name: 'ActivityId', + declaration: 'export type ActivityId = Branded<\'ActivityId\'>;', + }, + { + name: 'ActivityKind', + declaration: 'export type ActivityKind = ActivityKindMap[keyof ActivityKindMap];', + }, + { + name: 'ActivityKindMap', + declaration: 'export interface ActivityKindMap {\n bash: \'bash\';\n}', + }, + { + name: 'ActivityObserveFrame', + declaration: 'export type ActivityObserveFrame = {\n readonly type: \'opened\';\n readonly activityId: ActivityId;\n readonly from: number;\n readonly earliest: number;\n readonly total: number;\n readonly status: ActivityRowStatus;\n readonly detail?: string;\n} | {\n readonly type: \'output\';\n readonly chunks: readonly ActivityWireChunk[];\n readonly next: number;\n readonly lossy?: true;\n} | {\n readonly type: \'status\';\n readonly status: ActivityRowStatus;\n readonly detail?: string;\n readonly finishedAt?: number;\n};', + }, + { + name: 'ActivityObserveRequest', + declaration: 'export interface ActivityObserveRequest {\n readonly activityId: ActivityId;\n readonly from?: number;\n}', + }, + { + name: 'ActivityOpen', + declaration: 'export interface ActivityOpen {\n kind: ActivityKind;\n label: string;\n owner?: Agent;\n correlation?: ActivityCorrelation;\n}', + }, + { + name: 'ActivityOutcome', + declaration: 'export interface ActivityOutcome {\n status: \'completed\' | \'failed\' | \'killed\';\n detail?: string;\n}', + }, + { + name: 'ActivityOutputChunk', + declaration: 'export interface ActivityOutputChunk {\n at: number;\n text: string;\n channel?: ActivityChannel;\n gapBefore?: true;\n}', + }, + { + name: 'ActivityOutputListener', + declaration: 'export type ActivityOutputListener = (id: ActivityId) => void;', + }, + { + name: 'ActivityRead', + declaration: 'export interface ActivityRead {\n chunks: readonly ActivityOutputChunk[];\n next: number;\n lossy: boolean;\n}', + }, + { + name: 'ActivityRow', + declaration: 'export interface ActivityRow {\n readonly id: ActivityId;\n readonly kind: string;\n readonly label: string;\n readonly sessionId?: SessionId;\n readonly correlation?: ActivityRowCorrelation;\n readonly status: ActivityRowStatus;\n readonly detail?: string;\n readonly startedAt: number;\n readonly finishedAt?: number;\n readonly outputTotal: number;\n}', + }, + { + name: 'ActivityRowCorrelation', + declaration: 'export interface ActivityRowCorrelation {\n readonly callId?: CallId;\n readonly jobId?: JobId;\n}', + }, + { + name: 'ActivityRowStatus', + declaration: 'export type ActivityRowStatus = \'running\' | \'completed\' | \'failed\' | \'killed\';', + }, + { + name: 'ActivitySnapshot', + declaration: 'export interface ActivitySnapshot {\n id: ActivityId;\n kind: ActivityKind;\n label: string;\n ownerSession?: SessionId;\n correlation?: ActivityCorrelation;\n status: ActivityStatus;\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n outputTotal: number;\n outputEarliest: number;\n}', + }, + { + name: 'ActivityStatus', + declaration: 'export type ActivityStatus = \'running\' | \'completed\' | \'failed\' | \'killed\';', + }, + { + name: 'ActivityWireChunk', + declaration: 'export interface ActivityWireChunk {\n readonly at: number;\n readonly text: string;\n readonly channel?: string;\n readonly gapBefore?: true;\n}', + }, { name: 'AdapterRegistrationHandle', declaration: 'export interface AdapterRegistrationHandle {\n (): void;\n replace(providers: string[]): void;\n}', @@ -4827,9 +4977,13 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'ShellExecSpec', declaration: 'export interface ShellExecSpec {\n command: string;\n workdir: string;\n timeoutMs: number;\n stdoutMaxBytes: number;\n signal?: AbortSignal | undefined;\n stdin?: string | undefined;\n env?: Record | undefined;\n dshEnv?: DshEnvironment | undefined;\n sandboxPolicy: SandboxExecutionPolicy | undefined;\n}', }, + { + name: 'ShellObservedStreams', + declaration: 'export interface ShellObservedStreams {\n stdout?: SubprocessOutputReader;\n stderr?: SubprocessOutputReader;\n}', + }, { name: 'ShellProcess', - declaration: 'export interface ShellProcess {\n status: ShellProcessStatus;\n exitCode: number | null;\n signal: NodeJS.Signals | null;\n readonly done: Promise;\n sandbox?: ShellSandboxInfo;\n readOutput(): ShellProcessRead;\n kill(): boolean;\n}', + declaration: 'export interface ShellProcess {\n status: ShellProcessStatus;\n exitCode: number | null;\n signal: NodeJS.Signals | null;\n readonly done: Promise;\n sandbox?: ShellSandboxInfo;\n readOutput(): ShellProcessRead;\n observed?: ShellObservedStreams;\n kill(): boolean;\n}', }, { name: 'ShellProcessRead', diff --git a/packages/jobs/jobs/README.i18n.yaml b/packages/jobs/jobs/README.i18n.yaml index 8129e170ed..4550338e3b 100644 --- a/packages/jobs/jobs/README.i18n.yaml +++ b/packages/jobs/jobs/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/jobs/jobs/README.md -README.md: f4469286603f687be5789bd016ab462dba26e664 -README.zh.md: 6fd97aa3fe4cbbd555c2475f4132ec00c6a97390 +README.md: 1ed69b99ae10d4821e134b42f2ae19ad4ac3350b +README.zh.md: c9fd920bb552e0386ed0644fe00c4473f5b95e3c diff --git a/packages/jobs/jobs/README.md b/packages/jobs/jobs/README.md index f446928660..1ed69b99ae 100644 --- a/packages/jobs/jobs/README.md +++ b/packages/jobs/jobs/README.md @@ -35,6 +35,6 @@ No direct invalidation; the named consumer owns any request-prefix changes. ## Known Limitations and Deferred Work -- **Stream output has one consuming cursor** — independent observers need a cursor or snapshot API. +- **Stream output has one consuming cursor** — the model owns it; independent observers use the non-consuming [`dsh-activity`](../../activity/activity/README.md) plane the producers mirror into instead. - **Foreground work cannot be promoted** — producers choose foreground or background before starting. - **The contract is in-process** — `JobStart.run()` passes callbacks and exact `Agent` objects; a durable or cross-process backend must reshape identity, restart, ownership, and observation semantics before it can implement this seam. diff --git a/packages/jobs/jobs/README.zh.md b/packages/jobs/jobs/README.zh.md index 6fd97aa3fe..c9fd920bb5 100644 --- a/packages/jobs/jobs/README.zh.md +++ b/packages/jobs/jobs/README.zh.md @@ -35,6 +35,6 @@ ## 已知限制与暂缓事项 -- **流输出只有一个消费游标**:独立观察者需要游标或快照 API。 +- **流输出只有一个消费游标**:它属于模型;独立观察者改用生产者镜像进去的非消费 [`dsh-activity`](../../activity/activity/README.zh.md) 观察面。 - **前台工作无法转为后台**:生产方在启动前选择前台或后台。 - **约定是进程内的**:`JobStart.run()` 传入回调和确切的 `Agent` 对象;持久化或跨进程后端必须先重塑身份、重启、所有权与观察语义,才能实现此 seam。 diff --git a/packages/shell/bash-local/src/index.ts b/packages/shell/bash-local/src/index.ts index 6c37c5b794..fa4f5ef893 100644 --- a/packages/shell/bash-local/src/index.ts +++ b/packages/shell/bash-local/src/index.ts @@ -272,6 +272,7 @@ export class LocalBashExecutor extends ShellExecutor { status: 'running', exitCode: null, signal: null, + observed: collected, done: running.done.then((outcome) => { // Any signal termination is killed, including a command signaling itself. if (proc.status === 'running') { diff --git a/packages/shell/pwsh-local/src/index.ts b/packages/shell/pwsh-local/src/index.ts index b7a2d9f915..08abd61169 100644 --- a/packages/shell/pwsh-local/src/index.ts +++ b/packages/shell/pwsh-local/src/index.ts @@ -301,6 +301,7 @@ export class PwshLocalExecutor extends ShellExecutor { status: 'running', exitCode: null, signal: null, + observed: collected, done: running.done.then((outcome) => { // Any signal termination is killed, including a command signaling itself. if (proc.status === 'running') { diff --git a/packages/shell/shell/README.i18n.yaml b/packages/shell/shell/README.i18n.yaml index 5317414e55..bcf293269a 100644 --- a/packages/shell/shell/README.i18n.yaml +++ b/packages/shell/shell/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/shell/shell/README.md -README.md: a15980ead797a73c18dd6d8825a4b38cf845df60 -README.zh.md: 008b19835697d5d9514cf5472696852cfc684acd +README.md: 45a4d0c47e7604e7ad2ffc9f98a387cfa4d20b0c +README.zh.md: da869b78981df6bcfc253e84f08e4ca63cbff5f3 diff --git a/packages/shell/shell/README.md b/packages/shell/shell/README.md index a15980ead7..45a4d0c47e 100644 --- a/packages/shell/shell/README.md +++ b/packages/shell/shell/README.md @@ -23,6 +23,7 @@ The split is a standard capability seam ([capability-seams Agent Note](../../../ | `start(spec)` | Background execution. Returns a task-free `ShellProcess` handle immediately; **no timeout applies**. The caller may adapt it into `ctx.jobs`. | | `sandboxMode` | The capability fact for the tool layer: the default mode a SANDBOXING executor confines under (`undefined` in the base class — "this executor does not sandbox"). `dsh-tool-bash` reads it at registration to advertise the escalation fields only when the composition honors them. | | `ShellProcess.readOutput()` | **Incremental** output read — consecutive reads never re-deliver. Reads that lost data to buffer bounds flag `lossy` and point at full-stream spill files. | +| `ShellProcess.observed` | Optional **non-consuming** offset readers over the same captured streams, for observers independent of the consuming cursor (the activity observation plane). Absent when a backend cannot expose offset reads. | | `ShellProcess.kill()` | Kill the process group. Returns `false` when it already finished. | Implementations subclass `ShellExecutor` and implement the abstract methods. Disposal must kill every running process and await its exit. diff --git a/packages/shell/shell/README.zh.md b/packages/shell/shell/README.zh.md index 008b198356..da869b7898 100644 --- a/packages/shell/shell/README.zh.md +++ b/packages/shell/shell/README.zh.md @@ -23,6 +23,7 @@ | `start(spec)` | 后台执行。立即返回不含任务语义的 `ShellProcess` 句柄;**不应用超时**。调用方可以将其适配到 `ctx.jobs`。 | | `sandboxMode` | 工具层的能力事实:沙箱执行器用于限制执行的默认模式(基类中为 `undefined`,即「此执行器不使用沙箱」)。`dsh-tool-bash` 会在注册时读取它,仅当组合确实支持升权字段时才公布这些字段。 | | `ShellProcess.readOutput()` | **增量** 读取输出:连续读取绝不会重复交付。因缓冲区容量限制而丢失数据的读取会标记 `lossy`,并指向完整流 spill 文件。 | +| `ShellProcess.observed` | 可选的**非消费** offset 读取器,覆盖同一批捕获流,供独立于消费游标的观察者使用(activity 观察面)。后端无法提供 offset 读取时缺省。 | | `ShellProcess.kill()` | 终止进程组。如果进程已结束,返回 `false`。 | 实现会继承 `ShellExecutor` 并实现抽象方法。dispose(资源释放)必须终止每个运行中的进程并等待其退出。 diff --git a/packages/shell/shell/src/types.ts b/packages/shell/shell/src/types.ts index 21fea2d791..1de1cabf95 100644 --- a/packages/shell/shell/src/types.ts +++ b/packages/shell/shell/src/types.ts @@ -8,10 +8,22 @@ */ import type { SandboxEnforcement, SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox' -import type { CollectedOutput, DshEnvironment } from '@deepseek-ai/dsh-subprocess' +import type { CollectedOutput, DshEnvironment, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess' export { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-subprocess' -export type { CollectedOutput, DshEnvironment, DshEnvironmentKey } from '@deepseek-ai/dsh-subprocess' +export type { CollectedOutput, DshEnvironment, DshEnvironmentKey, SubprocessOutputRead, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess' + +/** + * Non-consuming offset readers over a background process's captured streams, + * for observers independent of the consuming {@link ShellProcess.readOutput} + * cursor. A stream is absent when its backend cannot expose offset reads. + */ +export interface ShellObservedStreams { + /** Offset reader over captured stdout, when the backend exposes one. */ + stdout?: SubprocessOutputReader + /** Offset reader over captured stderr, when the backend exposes one. */ + stderr?: SubprocessOutputReader +} /** * Sandbox facts for one run, present iff a sandboxing executor handled it. @@ -175,6 +187,13 @@ export interface ShellProcess { * full-stream spill files when available. */ readOutput(): ShellProcessRead + /** + * Non-consuming offset readers over the same captured streams the consuming + * {@link readOutput} cursor drains. Independent observers read here at their + * own offsets without stealing bytes from `readOutput`. Absent when the + * backend cannot expose offset reads; observers then see no stream. + */ + observed?: ShellObservedStreams /** * Kill the process group. Returns false when it had already finished * (no-op); idempotent. diff --git a/packages/shell/tool-bash/README.i18n.yaml b/packages/shell/tool-bash/README.i18n.yaml index f3acda2aca..ae0daca26d 100644 --- a/packages/shell/tool-bash/README.i18n.yaml +++ b/packages/shell/tool-bash/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/shell/tool-bash/README.md -README.md: 21749bf0a1cd3cdc46257fb2a02ba6b4ab1f5ee6 -README.zh.md: 860db1a4c347d1aefe04f70e14a65e4b511ff7f6 +README.md: acf7e68cca6b611adf71ed7bad690294f1bdb14d +README.zh.md: 9aeae12bce13f87246a7cdea8c5b41ec8bbd4bc5 diff --git a/packages/shell/tool-bash/README.md b/packages/shell/tool-bash/README.md index 21749bf0a1..acf7e68cca 100644 --- a/packages/shell/tool-bash/README.md +++ b/packages/shell/tool-bash/README.md @@ -34,7 +34,7 @@ Result text contains stdout, an optional `[stderr]` section, then applicable san The canonical success is `{ kind: 'foreground', ...ShellRunResult }` for a completed foreground process or `{ kind: 'background', jobId }` for a published task. The Native renderer preserves the text above, including exactly `started background job `; programmatic consumers use the typed fields without parsing those strings. Executor stream caps remain acquisition limits on `ShellRunResult` and carry their spill paths. -When `run_in_background` is true, this plugin preflights `ctx.jobs.start()` before spawning, registers the calling agent as owner, and adapts the returned `ShellProcess` handle into generic cancel/done/incremental-output hooks. The job runtime owns ids, cross-session isolation, completion notices, waiting, and disposal cleanup; this plugin only maps bash exit/sandbox facts into job output and outcome detail. `enableRunInBackground: false` removes the parameter and rejects a forced background call at execution time. +When `run_in_background` is true, this plugin preflights `ctx.jobs.start()` before spawning, registers the calling agent as owner, and adapts the returned `ShellProcess` handle into generic cancel/done/incremental-output hooks. The job runtime owns ids, cross-session isolation, completion notices, waiting, and disposal cleanup; this plugin only maps bash exit/sandbox facts into job output and outcome detail. `enableRunInBackground: false` removes the parameter and rejects a forced background call at execution time. When the optional `ctx.activities` registry is loaded, the committed background run is also mirrored into it best-effort: a `bash` activity correlated to the call and job pumps the handle's non-consuming `observed` readers at `activityPollMs` (default 150) so the Web client streams live output without touching the job's cursor; any observation failure is logged and swallowed. ## UI presentation diff --git a/packages/shell/tool-bash/README.zh.md b/packages/shell/tool-bash/README.zh.md index 860db1a4c3..9aeae12bce 100644 --- a/packages/shell/tool-bash/README.zh.md +++ b/packages/shell/tool-bash/README.zh.md @@ -34,7 +34,7 @@ 已完成前台进程的规范成功值为 `{ kind: 'foreground', ...ShellRunResult }`,已发布任务则为 `{ kind: 'background', jobId }`。Native renderer 保留上述文本,包括精确的 `started background job `;程序化消费方使用带类型字段,无需解析这些字符串。执行器的流上限仍是 `ShellRunResult` 的采集限制,并携带其 spill 路径。 -当 `run_in_background` 为 true 时,此插件会在 spawn 前预检 `ctx.jobs.start()`,把调用方 agent 注册为持有者,并将返回的 `ShellProcess` 句柄适配为通用的取消/完成/增量输出钩子。任务运行时负责 job id、跨会话隔离、完成通知、等待和 dispose(资源释放)清理;此插件只把 bash 退出/沙箱事实映射为任务输出和结果详情。`enableRunInBackground: false` 会移除该参数,并在执行时拒绝强制后台调用。 +当 `run_in_background` 为 true 时,此插件会在 spawn 前预检 `ctx.jobs.start()`,把调用方 agent 注册为持有者,并将返回的 `ShellProcess` 句柄适配为通用的取消/完成/增量输出钩子。任务运行时负责 job id、跨会话隔离、完成通知、等待和 dispose(资源释放)清理;此插件只把 bash 退出/沙箱事实映射为任务输出和结果详情。`enableRunInBackground: false` 会移除该参数,并在执行时拒绝强制后台调用。当可选的 `ctx.activities` 注册表已加载时,已提交的后台运行还会尽力镜像进去:一个与调用和 job 关联的 `bash` activity 以 `activityPollMs`(默认 150)的节奏泵取句柄的非消费 `observed` 读取器,让 Web 客户端在不动 job 游标的前提下实时看到输出;任何观察失败只记日志并吞掉。 ## UI 展示 diff --git a/packages/shell/tool-bash/package.json b/packages/shell/tool-bash/package.json index 321e2822d2..557fbe37f2 100644 --- a/packages/shell/tool-bash/package.json +++ b/packages/shell/tool-bash/package.json @@ -32,42 +32,44 @@ ], "license": "MIT", "peerDependencies": { + "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", - "@deepseek-ai/dsh-shell": "workspace:^", - "@deepseek-ai/dsh-shell-env": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/dsh-jobs": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-activity": "workspace:^", "@deepseek-ai/dsh-sandbox": "workspace:^", "@deepseek-ai/dsh-sandbox-policy": "workspace:^", + "@deepseek-ai/dsh-shell": "workspace:^", + "@deepseek-ai/dsh-shell-env": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", - "@deepseek-ai/dsh-jobs": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", - "@deepseek-ai/dsh-user-approval": "workspace:^", - "@deepseek-ai/cordis": "workspace:^" + "@deepseek-ai/dsh-user-approval": "workspace:^" }, "dependencies": { "@deepseek-ai/schemastery": "workspace:^" }, "devDependencies": { + "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-agent-loop": "workspace:^", "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^", - "@deepseek-ai/dsh-shell": "workspace:^", - "@deepseek-ai/dsh-shell-env": "workspace:^", "@deepseek-ai/dsh-bash-local": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/dsh-jobs": "workspace:^", + "@deepseek-ai/dsh-jobs-local": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-subprocess-local": "workspace:^", + "@deepseek-ai/dsh-activity": "workspace:^", "@deepseek-ai/dsh-sandbox": "workspace:^", "@deepseek-ai/dsh-sandbox-policy": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^", + "@deepseek-ai/dsh-shell": "workspace:^", + "@deepseek-ai/dsh-shell-env": "workspace:^", + "@deepseek-ai/dsh-subprocess-local": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", - "@deepseek-ai/dsh-jobs": "workspace:^", - "@deepseek-ai/dsh-jobs-local": "workspace:^", "@deepseek-ai/dsh-tool-jobs": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", - "@deepseek-ai/dsh-user-approval": "workspace:^", - "@deepseek-ai/cordis": "workspace:^" + "@deepseek-ai/dsh-user-approval": "workspace:^" } } diff --git a/packages/shell/tool-bash/src/index.ts b/packages/shell/tool-bash/src/index.ts index 37c4a762e3..ed4fd5bac6 100644 --- a/packages/shell/tool-bash/src/index.ts +++ b/packages/shell/tool-bash/src/index.ts @@ -23,8 +23,10 @@ import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandb import { ESCALATION_TARGETS, approveEscalation, canonicalPath, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox' import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy' import { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-shell' -import type { ShellRunResult } from '@deepseek-ai/dsh-shell' +import type { ShellProcess, ShellRunResult } from '@deepseek-ai/dsh-shell' +import type {} from '@deepseek-ai/dsh-activity' import { processOutcome } from './background.ts' +import { observeBackgroundActivity } from './observe.ts' import { parseExitStatus, renderProcessRead, renderResult } from './render.ts' export const name = 'tool-bash' @@ -34,11 +36,18 @@ export const inject = ['tools', 'shell', 'systemPrompt', 'shellEnv'] export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean + /** Poll cadence for mirroring background output into `ctx.activities`, in milliseconds (default 150). */ + activityPollMs?: number } /** Runtime configuration schema for the bash tool plugin. */ export const Config: z = z.object({ enableRunInBackground: z.boolean().default(true), + activityPollMs: z.number() + .step(1) + .min(1) + .max(Number.MAX_SAFE_INTEGER) + .default(150), }) /** Parsed tool args; execute validates value constraints absent from ParameterSchemaSpec. */ @@ -189,6 +198,7 @@ const BACKGROUND_OUTPUT_PROPERTIES = { export function apply(ctx: Context, config: Config = {}): void { const backgroundEnabled = config.enableRunInBackground ?? true + const activityPollMs = config.activityPollMs ?? 150 const defaultMode = ctx.shell.sandboxMode const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS const sandboxPolicy: SandboxPolicyService | undefined = defaultMode === undefined ? undefined : ctx.get('sandboxPolicy') @@ -362,12 +372,14 @@ export function apply(ctx: Context, config: Config = {}): void { throw error } // Task preflight finishes before the starter can spawn a process. + let started: ShellProcess | undefined const id = jobs.start({ kind: 'bash', label: args.command, ...exec.agent ? { owner: exec.agent } : {}, run: () => { const proc = ctx.shell.start(ctx.shell.resolve(request)) + started = proc return { cancel: () => void proc.kill(), done: proc.done.then(() => processOutcome(proc)), @@ -375,6 +387,16 @@ export function apply(ctx: Context, config: Config = {}): void { } }, }) + // The starter ran synchronously inside the committed start; mirror the + // spawned process into the optional observation registry. + if (started !== undefined) { + observeBackgroundActivity(ctx, started, { + kind: 'bash', + label: args.command, + ...exec.agent ? { owner: exec.agent } : {}, + correlation: { callId: exec.callId, jobId: id }, + }, activityPollMs, processOutcome) + } return { kind: 'background' as const, jobId: id } } const result = await ctx.shell.run(ctx.shell.resolve({ diff --git a/packages/shell/tool-bash/src/observe.ts b/packages/shell/tool-bash/src/observe.ts new file mode 100644 index 0000000000..7b5179aa59 --- /dev/null +++ b/packages/shell/tool-bash/src/observe.ts @@ -0,0 +1,72 @@ +/** + * Best-effort process-observation tap for background bash runs: mirrors the + * spawned process's captured streams into `ctx.activities` so non-consuming + * observers (the Web client) see live output without touching the job's + * consuming `readOutput` cursor. Absent registry or absent backend offset + * readers degrade to no observation; the job path is unaffected either way. + * + * @module @deepseek-ai/dsh-tool-bash/observe + */ + +import type { Context } from '@deepseek-ai/cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import type { ShellProcess } from '@deepseek-ai/dsh-shell' +import { pumpActivityOutput } from '@deepseek-ai/dsh-activity' +import type { ActivityCorrelation, ActivityKind, ActivityPumpSource } from '@deepseek-ai/dsh-activity' + +/** Identity of one observed background run. */ +export interface ObserveBackgroundSpec { + /** Process kind — the producing tool's registered {@link ActivityKind}. */ + kind: ActivityKind + /** One-line label (the command). */ + label: string + /** Owning live agent, when the call has one. */ + owner?: Agent + /** Links to the starting tool call and the registered job. */ + correlation: ActivityCorrelation +} + +/** + * Open a process beside a committed background job and pump the handle's + * non-consuming offset readers into it until the run settles, then record the + * mapped outcome. Observation is strictly best-effort: without a + * `ctx.activities` registry this is a no-op, without backend offset readers + * the process still carries status and settlement, and ANY observation + * failure — including a rejected `open()` — is logged and swallowed, because + * the background job is already committed and running. + * @param ctx - plugin context used for the optional registry and warning logs. + * @param proc - the started background process handle. + * @param spec - process identity and correlation for the registry row. + * @param pollMs - producer-configured pump cadence in milliseconds. + * @param outcome - maps the settled handle to the process outcome. + */ +export function observeBackgroundActivity( + ctx: Context, + proc: ShellProcess, + spec: ObserveBackgroundSpec, + pollMs: number, + outcome: (proc: ShellProcess) => { status: 'completed' | 'killed'; detail: string }, +): void { + try { + const processes = ctx.get('activities') + if (processes === undefined) return + const handle = processes.open({ + kind: spec.kind, + label: spec.label, + ...spec.owner !== undefined ? { owner: spec.owner } : {}, + correlation: spec.correlation, + }) + const sources: ActivityPumpSource[] = [] + const stdout = proc.observed?.stdout + if (stdout !== undefined) sources.push({ channel: 'stdout', read: from => stdout.readFrom(from) }) + const stderr = proc.observed?.stderr + if (stderr !== undefined) sources.push({ channel: 'stderr', read: from => stderr.readFrom(from) }) + void pumpActivityOutput(handle, sources, { pollMs, done: proc.done }) + .catch((error: unknown) => { + ctx.logger.warn(`activity observation pump for ${handle.id} failed: ${String(error)}`) + }) + .then(() => { handle.end(outcome(proc)) }) + } catch (error: unknown) { + ctx.logger.warn(`activity observation unavailable for this run: ${String(error)}`) + } +} diff --git a/packages/shell/tool-bash/tests/observe.spec.ts b/packages/shell/tool-bash/tests/observe.spec.ts new file mode 100644 index 0000000000..c0243ba5b9 --- /dev/null +++ b/packages/shell/tool-bash/tests/observe.spec.ts @@ -0,0 +1,194 @@ +import { mkdtempSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { describe, expect, it, vi } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import { CallId } from '@deepseek-ai/dsh-llm' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRuntime from '@deepseek-ai/dsh-tools' +import AgentRegistry from '@deepseek-ai/dsh-agent' +import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' +import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs' +import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' +import type { ActivitySnapshot } from '@deepseek-ai/dsh-activity' +import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local' +import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local' +import * as ToolBash from '@deepseek-ai/dsh-tool-bash' +import * as BashEnvPlugin from '@deepseek-ai/dsh-shell-env' + +const testToolSignal = new AbortController().signal +const spillDir = mkdtempSync(join(tmpdir(), 'dsh-tool-bash-observe-spec-')) + +/** Job harness plus the observation registry, with a fast pump for tests. */ +async function setup() { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRuntime) + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalJobRegistry) + await ctx.plugin(ToolTasks) + await ctx.plugin(LocalActivityRegistry) + await ctx.plugin(LocalSubprocessRuntime) + ;(ctx.subprocess as LocalSubprocessRuntime).internals = { spillDir } + await ctx.plugin(BashEnvPlugin) + await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 }) + await ctx.plugin(ToolBash, { activityPollMs: 25 }) + return ctx +} + +let callCounter = 0 +function call(ctx: Context, args: Record) { + return ctx.tools.execute({ + signal: testToolSignal, + callId: CallId(`observe-call-${++callCounter}`), + name: 'bash', + arguments: args, + }) +} + +function text(result: { content: { type: string; text?: string }[] }): string { + return result.content.filter(block => block.type === 'text').map(block => block.text).join('') +} + +async function until(read: () => T | undefined, timeoutMs = 5_000): Promise { + const deadline = Date.now() + timeoutMs + while (Date.now() < deadline) { + const value = read() + if (value !== undefined) return value + await new Promise(resolve => setTimeout(resolve, 20)) + } + throw new Error('condition not reached before timeout') +} + +function retainedText(ctx: Context, id: ActivitySnapshot['id']): string { + return ctx.activities.read(id, 0).chunks.map(chunk => chunk.text).join('') +} + +describe('background bash observation', () => { + it('mirrors a background run into ctx.activities with correlation, live output, and settlement', async () => { + const ctx = await setup() + const ack = await call(ctx, { + command: 'printf "line-1\\n"; sleep 0.4; printf "line-2\\n"', + description: 'test command', + run_in_background: true, + }) + expect(text(ack)).toContain('started background job') + const job = ctx.jobs.list()[0] + expect(job).toBeDefined() + + const snapshot = await until(() => + ctx.activities.list().find(row => row.correlation?.jobId === job!.id)) + expect(snapshot.kind).toBe('bash') + expect(snapshot.label).toContain('printf') + expect(String(snapshot.correlation?.callId)).toMatch(/^observe-call-/) + + // Live output appears while the command is still running. + await until(() => retainedText(ctx, snapshot.id).includes('line-1') ? true : undefined) + expect(ctx.activities.get(snapshot.id).status).toBe('running') + + // Settlement carries the mapped bash outcome and the trailing output. + await until(() => ctx.activities.get(snapshot.id).status === 'completed' ? true : undefined) + expect(ctx.activities.get(snapshot.id).detail).toBe('exit code: 0') + expect(retainedText(ctx, snapshot.id)).toContain('line-2') + + // The model-facing consuming cursor still delivers everything: observation stole nothing. + const collected = await until(() => { + const read = ctx.jobs.read(job!.id) + return read.text.includes('line-1') ? read.text : undefined + }) + expect(collected).toContain('line-2') + }) + + it('a killed background job settles its mirrored process as killed', async () => { + const ctx = await setup() + await call(ctx, { command: 'sleep 60', description: 'test command', run_in_background: true }) + const job = ctx.jobs.list()[0] + const snapshot = await until(() => + ctx.activities.list().find(row => row.correlation?.jobId === job!.id)) + ctx.jobs.kill(job!.id, undefined, 'test cleanup') + await until(() => ctx.activities.get(snapshot.id).status === 'killed' ? true : undefined) + expect(ctx.activities.get(snapshot.id).detail).toMatch(/signal|killed before exit/) + }) + + it('labels stderr chunks with their channel', async () => { + const ctx = await setup() + await call(ctx, { + command: 'echo out-line; echo err-line 1>&2', + description: 'test command', + run_in_background: true, + }) + const job = ctx.jobs.list()[0] + const snapshot = await until(() => + ctx.activities.list().find(row => row.correlation?.jobId === job!.id)) + await until(() => ctx.activities.get(snapshot.id).status === 'completed' ? true : undefined) + const chunks = ctx.activities.read(snapshot.id, 0).chunks + expect(chunks.find(chunk => chunk.text.includes('out-line'))?.channel).toBe('stdout') + expect(chunks.find(chunk => chunk.text.includes('err-line'))?.channel).toBe('stderr') + }) + + it('a registry whose handle rejects appends degrades to a warning and still settles', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRuntime) + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalJobRegistry) + await ctx.plugin(ToolTasks) + const ended: unknown[] = [] + await ctx.plugin({ + name: 'appending-broken-activities-probe', + apply(child: Context) { + child.provide('activities', { + open: () => ({ + id: 'bash-1', + append() { throw new Error('append boom') }, + updateDetail() {}, + end(outcome: unknown) { ended.push(outcome) }, + }), + }) + }, + }) + await ctx.plugin(LocalSubprocessRuntime) + ;(ctx.subprocess as LocalSubprocessRuntime).internals = { spillDir } + await ctx.plugin(BashEnvPlugin) + await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 }) + const warn = vi.fn() + ctx.logger.warn = warn as never + await ctx.plugin(ToolBash, { activityPollMs: 25 }) + await call(ctx, { command: 'echo tolerated', description: 'test command', run_in_background: true }) + await until(() => ended.length > 0 ? true : undefined) + expect(warn).toHaveBeenCalledWith(expect.stringContaining('activity observation pump')) + expect(ended[0]).toMatchObject({ status: 'completed' }) + }) + + it('a throwing observation registry never breaks the background call', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRuntime) + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalJobRegistry) + await ctx.plugin(ToolTasks) + await ctx.plugin({ + name: 'broken-activities-probe', + apply(child: Context) { + child.provide('activities', { open() { throw new Error('observation boom') } }) + }, + }) + await ctx.plugin(LocalSubprocessRuntime) + ;(ctx.subprocess as LocalSubprocessRuntime).internals = { spillDir } + await ctx.plugin(BashEnvPlugin) + await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 }) + const warn = vi.fn() + ctx.logger.warn = warn as never + await ctx.plugin(ToolBash, { activityPollMs: 25 }) + const ack = await call(ctx, { command: 'echo resilient', description: 'test command', run_in_background: true }) + expect(text(ack)).toContain('started background job') + expect(warn).toHaveBeenCalledWith(expect.stringContaining('activity observation unavailable')) + // The job itself still completes and reads normally. + const job = ctx.jobs.list()[0] + const read = await until(() => { + const value = ctx.jobs.read(job!.id) + return value.text.includes('resilient') ? value : undefined + }) + expect(read.snapshot.status).toBe('completed') + }) +}) diff --git a/packages/shell/tool-bash/tsconfig.json b/packages/shell/tool-bash/tsconfig.json index 304d983a95..8aa66f93ff 100644 --- a/packages/shell/tool-bash/tsconfig.json +++ b/packages/shell/tool-bash/tsconfig.json @@ -49,6 +49,9 @@ }, { "path": "../../sandbox/sandbox-policy" + }, + { + "path": "../../activity/activity" } ] } diff --git a/packages/shell/tool-pwsh/README.i18n.yaml b/packages/shell/tool-pwsh/README.i18n.yaml index c5dcb85005..0a88134fb3 100644 --- a/packages/shell/tool-pwsh/README.i18n.yaml +++ b/packages/shell/tool-pwsh/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/shell/tool-pwsh/README.md -README.md: e862fcf0ca85d0ecb0a5fe6cff3ee3c7a8153716 -README.zh.md: 0a66b119ac2bf0386c0686e9e22ddfe1c3bb87b1 +README.md: 5ebc22e8607337c2698756891cce2b9ba9e06184 +README.zh.md: 2e5186383babadab9ea894b3cb6364ab8bc23e6b diff --git a/packages/shell/tool-pwsh/README.md b/packages/shell/tool-pwsh/README.md index e862fcf0ca..5ebc22e860 100644 --- a/packages/shell/tool-pwsh/README.md +++ b/packages/shell/tool-pwsh/README.md @@ -34,7 +34,7 @@ Result text contains stdout, an optional `[stderr]` section, then applicable tru The canonical success is `{ kind: 'foreground', ...ShellRunResult }` for a completed foreground process (with the executor's `sandbox` facts — `mode`/`denied`, optional `enforcement`/`runnerFailed` — projected when present) or `{ kind: 'background', jobId }` for a published task. The renderer preserves exactly `started background job ` for background acks; programmatic consumers use the typed fields without parsing the rendered text. -When `run_in_background` is true, this plugin preflights `ctx.jobs.start()` before spawning, registers the calling agent as owner, and adapts the returned `ShellProcess` handle into generic cancel/done/incremental-output hooks. The job runtime owns ids, cross-session isolation, completion notices, waiting, and disposal cleanup; this plugin only maps pwsh exit facts into job output and outcome detail. `enableRunInBackground: false` removes the parameter and rejects a forced background call at execution time. +When `run_in_background` is true, this plugin preflights `ctx.jobs.start()` before spawning, registers the calling agent as owner, and adapts the returned `ShellProcess` handle into generic cancel/done/incremental-output hooks. The job runtime owns ids, cross-session isolation, completion notices, waiting, and disposal cleanup; this plugin only maps pwsh exit facts into job output and outcome detail. `enableRunInBackground: false` removes the parameter and rejects a forced background call at execution time. When the optional `ctx.activities` registry is loaded, the committed background run is also mirrored into it best-effort as a `pwsh` activity pumped at `activityPollMs` (default 150), exactly like `dsh-tool-bash`. ## UI presentation diff --git a/packages/shell/tool-pwsh/README.zh.md b/packages/shell/tool-pwsh/README.zh.md index 0a66b119ac..2e5186383b 100644 --- a/packages/shell/tool-pwsh/README.zh.md +++ b/packages/shell/tool-pwsh/README.zh.md @@ -34,7 +34,7 @@ 规范成功形态是已完成前台进程的 `{ kind: 'foreground', ...ShellRunResult }`(存在时投影执行器的 `sandbox` 事实——`mode`/`denied`、可选的 `enforcement`/`runnerFailed`)或已发布任务的 `{ kind: 'background', jobId }`。渲染器对后台 ack 精确保留 `started background job `;编程消费者使用类型化字段而不解析渲染文本。 -当 `run_in_background` 为 true 时,本插件在 spawn 前预检 `ctx.jobs.start()`,把调用 agent 注册为 owner,并将返回的 `ShellProcess` 句柄适配为通用的 cancel/done/增量输出钩子。任务运行时负责 job id、跨会话隔离、完成通知、等待和 dispose(资源释放)清理;本插件只把 pwsh 退出事实映射进任务输出与结果明细。`enableRunInBackground: false` 会移除参数并在执行时拒绝强制的后台调用。 +当 `run_in_background` 为 true 时,本插件在 spawn 前预检 `ctx.jobs.start()`,把调用 agent 注册为 owner,并将返回的 `ShellProcess` 句柄适配为通用的 cancel/done/增量输出钩子。任务运行时负责 job id、跨会话隔离、完成通知、等待和 dispose(资源释放)清理;本插件只把 pwsh 退出事实映射进任务输出与结果明细。`enableRunInBackground: false` 会移除参数并在执行时拒绝强制的后台调用。当可选的 `ctx.activities` 注册表已加载时,已提交的后台运行还会尽力镜像为一个 `pwsh` activity,以 `activityPollMs`(默认 150)的节奏泵取,与 `dsh-tool-bash` 完全一致。 ## UI presentation diff --git a/packages/shell/tool-pwsh/package.json b/packages/shell/tool-pwsh/package.json index 2294a955a3..3156508e39 100644 --- a/packages/shell/tool-pwsh/package.json +++ b/packages/shell/tool-pwsh/package.json @@ -32,39 +32,41 @@ ], "license": "MIT", "peerDependencies": { + "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", - "@deepseek-ai/dsh-shell": "workspace:^", - "@deepseek-ai/dsh-shell-env": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/dsh-jobs": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-activity": "workspace:^", "@deepseek-ai/dsh-sandbox": "workspace:^", "@deepseek-ai/dsh-sandbox-policy": "workspace:^", + "@deepseek-ai/dsh-shell": "workspace:^", + "@deepseek-ai/dsh-shell-env": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", - "@deepseek-ai/dsh-jobs": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", - "@deepseek-ai/dsh-user-approval": "workspace:^", - "@deepseek-ai/cordis": "workspace:^" + "@deepseek-ai/dsh-user-approval": "workspace:^" }, "dependencies": { "@deepseek-ai/schemastery": "workspace:^" }, "devDependencies": { + "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", - "@deepseek-ai/dsh-shell": "workspace:^", - "@deepseek-ai/dsh-shell-env": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/dsh-jobs": "workspace:^", + "@deepseek-ai/dsh-jobs-local": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-loader-smoke": "workspace:^", + "@deepseek-ai/dsh-activity": "workspace:^", "@deepseek-ai/dsh-pwsh-local": "workspace:^", "@deepseek-ai/dsh-sandbox": "workspace:^", "@deepseek-ai/dsh-sandbox-policy": "workspace:^", + "@deepseek-ai/dsh-shell": "workspace:^", + "@deepseek-ai/dsh-shell-env": "workspace:^", "@deepseek-ai/dsh-subprocess-local": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", - "@deepseek-ai/dsh-jobs": "workspace:^", - "@deepseek-ai/dsh-jobs-local": "workspace:^", "@deepseek-ai/dsh-tool-jobs": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", - "@deepseek-ai/dsh-user-approval": "workspace:^", - "@deepseek-ai/cordis": "workspace:^" + "@deepseek-ai/dsh-user-approval": "workspace:^" } } diff --git a/packages/shell/tool-pwsh/src/index.ts b/packages/shell/tool-pwsh/src/index.ts index 603322e381..f3e63551e5 100644 --- a/packages/shell/tool-pwsh/src/index.ts +++ b/packages/shell/tool-pwsh/src/index.ts @@ -33,9 +33,11 @@ import type {} from '@deepseek-ai/dsh-user-approval' import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox' import { ESCALATION_TARGETS, approveEscalation, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox' import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy' -import type { ShellRunResult } from '@deepseek-ai/dsh-shell' +import type { ShellProcess, ShellRunResult } from '@deepseek-ai/dsh-shell' import { parseExitStatus } from '@deepseek-ai/dsh-shell' +import type {} from '@deepseek-ai/dsh-activity' import { processOutcome } from './background.ts' +import { observeBackgroundActivity } from './observe.ts' import { renderPwshProcessRead, renderPwshResult } from './render.ts' import type { RenderablePwshResult } from './render.ts' @@ -45,19 +47,34 @@ declare module '@deepseek-ai/dsh-jobs' { } } +declare module '@deepseek-ai/dsh-activity' { + interface ActivityKindMap { + pwsh: 'pwsh' + } +} + export const name = 'tool-pwsh' export const inject = ['tools', 'shell', 'systemPrompt', 'shellEnv'] +/* jscpd:ignore-start -- the pwsh Config mirrors tool-bash's by design, like render/background. */ /** Configuration for the pwsh tool. */ export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean + /** Poll cadence for mirroring background output into `ctx.activities`, in milliseconds (default 150). */ + activityPollMs?: number } /** Runtime configuration schema for the pwsh tool plugin. */ export const Config: z = z.object({ enableRunInBackground: z.boolean().default(true), + activityPollMs: z.number() + .step(1) + .min(1) + .max(Number.MAX_SAFE_INTEGER) + .default(150), }) +/* jscpd:ignore-end */ /** Parsed tool args; execute validates value constraints absent from ParameterSchemaSpec. */ interface PwshToolArgs { @@ -194,6 +211,7 @@ const BACKGROUND_OUTPUT_PROPERTIES = { /* jscpd:ignore-start -- deliberate mirror of dsh-tool-bash's apply() preamble (pwsh-tool-and-executor Agent Note). */ export function apply(ctx: Context, config: Config = {}): void { const backgroundEnabled = config.enableRunInBackground ?? true + const activityPollMs = config.activityPollMs ?? 150 const defaultMode = ctx.shell.sandboxMode const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS const sandboxPolicy: SandboxPolicyService | undefined = defaultMode === undefined ? undefined : ctx.get('sandboxPolicy') @@ -378,12 +396,14 @@ export function apply(ctx: Context, config: Config = {}): void { throw error } // Task preflight finishes before the starter can spawn a process. + let started: ShellProcess | undefined const id = jobs.start({ kind: 'pwsh', label: args.command, ...exec.agent ? { owner: exec.agent } : {}, run: () => { const proc = ctx.shell.start(ctx.shell.resolve(request)) + started = proc return { cancel: () => void proc.kill(), done: proc.done.then(() => processOutcome(proc)), @@ -391,6 +411,16 @@ export function apply(ctx: Context, config: Config = {}): void { } }, }) + // The starter ran synchronously inside the committed start; mirror the + // spawned process into the optional observation registry. + if (started !== undefined) { + observeBackgroundActivity(ctx, started, { + kind: 'pwsh', + label: args.command, + ...exec.agent ? { owner: exec.agent } : {}, + correlation: { callId: exec.callId, jobId: id }, + }, activityPollMs, processOutcome) + } return { kind: 'background' as const, jobId: id } } const result = await ctx.shell.run(ctx.shell.resolve({ diff --git a/packages/shell/tool-pwsh/src/observe.ts b/packages/shell/tool-pwsh/src/observe.ts new file mode 100644 index 0000000000..6d342dda8b --- /dev/null +++ b/packages/shell/tool-pwsh/src/observe.ts @@ -0,0 +1,74 @@ +/** + * Best-effort process-observation tap for background pwsh runs: mirrors the + * spawned process's captured streams into `ctx.activities` so non-consuming + * observers (the Web client) see live output without touching the job's + * consuming `readOutput` cursor. Absent registry or absent backend offset + * readers degrade to no observation; the job path is unaffected either way. + * + * @module @deepseek-ai/dsh-tool-pwsh/observe + */ + +/* jscpd:ignore-start -- mirrors tool-bash's observe tap by design, like render/background. */ +import type { Context } from '@deepseek-ai/cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import type { ShellProcess } from '@deepseek-ai/dsh-shell' +import { pumpActivityOutput } from '@deepseek-ai/dsh-activity' +import type { ActivityCorrelation, ActivityKind, ActivityPumpSource } from '@deepseek-ai/dsh-activity' + +/** Identity of one observed background run. */ +export interface ObserveBackgroundSpec { + /** Process kind — the producing tool's registered {@link ActivityKind}. */ + kind: ActivityKind + /** One-line label (the command). */ + label: string + /** Owning live agent, when the call has one. */ + owner?: Agent + /** Links to the starting tool call and the registered job. */ + correlation: ActivityCorrelation +} + +/** + * Open a process beside a committed background job and pump the handle's + * non-consuming offset readers into it until the run settles, then record the + * mapped outcome. Observation is strictly best-effort: without a + * `ctx.activities` registry this is a no-op, without backend offset readers + * the process still carries status and settlement, and ANY observation + * failure — including a rejected `open()` — is logged and swallowed, because + * the background job is already committed and running. + * @param ctx - plugin context used for the optional registry and warning logs. + * @param proc - the started background process handle. + * @param spec - process identity and correlation for the registry row. + * @param pollMs - producer-configured pump cadence in milliseconds. + * @param outcome - maps the settled handle to the process outcome. + */ +export function observeBackgroundActivity( + ctx: Context, + proc: ShellProcess, + spec: ObserveBackgroundSpec, + pollMs: number, + outcome: (proc: ShellProcess) => { status: 'completed' | 'killed'; detail: string }, +): void { + try { + const processes = ctx.get('activities') + if (processes === undefined) return + const handle = processes.open({ + kind: spec.kind, + label: spec.label, + ...spec.owner !== undefined ? { owner: spec.owner } : {}, + correlation: spec.correlation, + }) + const sources: ActivityPumpSource[] = [] + const stdout = proc.observed?.stdout + if (stdout !== undefined) sources.push({ channel: 'stdout', read: from => stdout.readFrom(from) }) + const stderr = proc.observed?.stderr + if (stderr !== undefined) sources.push({ channel: 'stderr', read: from => stderr.readFrom(from) }) + void pumpActivityOutput(handle, sources, { pollMs, done: proc.done }) + .catch((error: unknown) => { + ctx.logger.warn(`activity observation pump for ${handle.id} failed: ${String(error)}`) + }) + .then(() => { handle.end(outcome(proc)) }) + } catch (error: unknown) { + ctx.logger.warn(`activity observation unavailable for this run: ${String(error)}`) + } +} +/* jscpd:ignore-end */ diff --git a/packages/shell/tool-pwsh/tests/observe.spec.ts b/packages/shell/tool-pwsh/tests/observe.spec.ts new file mode 100644 index 0000000000..25b5bbfbd4 --- /dev/null +++ b/packages/shell/tool-pwsh/tests/observe.spec.ts @@ -0,0 +1,154 @@ +import { describe, expect, it } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import { CallId } from '@deepseek-ai/dsh-llm' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRuntime from '@deepseek-ai/dsh-tools' +import AgentRegistry from '@deepseek-ai/dsh-agent' +import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' +import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs' +import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' +import { ShellExecutor } from '@deepseek-ai/dsh-shell' +import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellRunResult } from '@deepseek-ai/dsh-shell' +import * as ToolPwsh from '@deepseek-ai/dsh-tool-pwsh' +import * as BashEnvPlugin from '@deepseek-ai/dsh-shell-env' + +const testToolSignal = new AbortController().signal + +/** ASCII-only scripted stream: readFrom offsets are byte-exact string indexes. */ +function scriptedReader(state: { text: string }) { + return { + readFrom(fromByte: number) { + return { text: state.text.slice(fromByte), nextOffset: state.text.length, lossy: false } + }, + } +} + +/** A running fake background handle with optional non-consuming observed streams. */ +function observableProcess(streams?: { stdout: { text: string }; stderr: { text: string } }) { + let resolveDone: () => void = () => {} + const done = new Promise((resolve) => { resolveDone = resolve }) + const proc: ShellProcess = { + status: 'running', + exitCode: null, + signal: null, + done, + readOutput: () => ({ delta: '', lossy: false }), + kill: () => false, + ...streams !== undefined + ? { observed: { stdout: scriptedReader(streams.stdout), stderr: scriptedReader(streams.stderr) } } + : {}, + } + return { + proc, + finish() { + proc.status = 'completed' + proc.exitCode = 0 + resolveDone() + }, + } +} + +class FakePwsh extends ShellExecutor { + backgroundHandler: (spec: ShellExecSpec) => ShellProcess = () => { throw new Error('unscripted start') } + + override resolve(request: ShellExecRequest): ShellExecSpec { + return { + command: request.command, + workdir: request.workdir ?? process.cwd(), + timeoutMs: request.timeoutMs ?? 60_000, + stdoutMaxBytes: request.stdoutMaxBytes ?? 64_000, + ...request.signal ? { signal: request.signal } : {}, + ...request.dshEnv !== undefined ? { dshEnv: request.dshEnv } : {}, + sandboxPolicy: request.sandboxPolicy, + } + } + + override async run(): Promise { + throw new Error('foreground is not exercised here') + } + + override start(spec: ShellExecSpec): ShellProcess { + return this.backgroundHandler(spec) + } +} + +async function setup() { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRuntime) + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalJobRegistry) + await ctx.plugin(ToolTasks) + await ctx.plugin(LocalActivityRegistry) + await ctx.plugin(BashEnvPlugin) + await ctx.plugin(FakePwsh) + await ctx.plugin(ToolPwsh, { activityPollMs: 5 }) + return { ctx, pwsh: ctx.shell as FakePwsh } +} + +let callCounter = 0 +function call(ctx: Context, args: Record) { + return ctx.tools.execute({ + signal: testToolSignal, + callId: CallId(`pwsh-observe-${++callCounter}`), + name: 'pwsh', + arguments: args, + }) +} + +async function until(read: () => T | undefined, timeoutMs = 5_000): Promise { + const deadline = Date.now() + timeoutMs + while (Date.now() < deadline) { + const value = read() + if (value !== undefined) return value + await new Promise(resolve => setTimeout(resolve, 5)) + } + throw new Error('condition not reached before timeout') +} + +describe('background pwsh observation', () => { + it('mirrors observed streams with channels and settles with the mapped outcome', async () => { + const { ctx, pwsh } = await setup() + const stdout = { text: '' } + const stderr = { text: '' } + const scripted = observableProcess({ stdout, stderr }) + pwsh.backgroundHandler = () => scripted.proc + + await call(ctx, { command: 'Get-Progress', description: 'test command', run_in_background: true }) + const job = ctx.jobs.list()[0] + const row = await until(() => ctx.activities.list().find(item => item.correlation?.jobId === job!.id)) + expect(row.kind).toBe('pwsh') + + stdout.text = 'progress-line\n' + stderr.text = 'warn-line\n' + await until(() => { + const chunks = ctx.activities.read(row.id, 0).chunks + return chunks.some(chunk => chunk.text.includes('progress-line')) + && chunks.some(chunk => chunk.text.includes('warn-line')) + ? true + : undefined + }) + const chunks = ctx.activities.read(row.id, 0).chunks + expect(chunks.find(chunk => chunk.text.includes('progress-line'))?.channel).toBe('stdout') + expect(chunks.find(chunk => chunk.text.includes('warn-line'))?.channel).toBe('stderr') + + scripted.finish() + await until(() => ctx.activities.get(row.id).status === 'completed' ? true : undefined) + expect(ctx.activities.get(row.id).detail).toBe('exit code: 0') + }) + + it('a backend without observed readers still yields a status-only process', async () => { + const { ctx, pwsh } = await setup() + const scripted = observableProcess() + pwsh.backgroundHandler = () => scripted.proc + + await call(ctx, { command: 'Start-Job', description: 'test command', run_in_background: true }) + const job = ctx.jobs.list()[0] + const row = await until(() => ctx.activities.list().find(item => item.correlation?.jobId === job!.id)) + expect(ctx.activities.read(row.id, 0).chunks).toEqual([]) + + scripted.finish() + await until(() => ctx.activities.get(row.id).status === 'completed' ? true : undefined) + expect(ctx.activities.get(row.id).outputTotal).toBe(0) + }) +}) diff --git a/packages/shell/tool-pwsh/tsconfig.json b/packages/shell/tool-pwsh/tsconfig.json index 59a4d9478c..d38c8f031d 100644 --- a/packages/shell/tool-pwsh/tsconfig.json +++ b/packages/shell/tool-pwsh/tsconfig.json @@ -52,6 +52,9 @@ }, { "path": "../../runtime-diagnostics/invariants" + }, + { + "path": "../../activity/activity" } ] } diff --git a/packages/workflow/tool-workflow/README.i18n.yaml b/packages/workflow/tool-workflow/README.i18n.yaml index f87a12407f..65a8c97d7b 100644 --- a/packages/workflow/tool-workflow/README.i18n.yaml +++ b/packages/workflow/tool-workflow/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/workflow/tool-workflow/README.md -README.md: 918fe5b9aff74b3b959107ec1eebfd7966afe6d1 -README.zh.md: 2546a0fc92ef39d71949cc0061dcf363ecc2e22d +README.md: 29e84c7386768b77c7b85ed8426f6f604a53fb44 +README.zh.md: 582828cf7c2d5b6c6e7dca6230d29fe744b578fe diff --git a/packages/workflow/tool-workflow/README.md b/packages/workflow/tool-workflow/README.md index 918fe5b9af..29e84c7386 100644 --- a/packages/workflow/tool-workflow/README.md +++ b/packages/workflow/tool-workflow/README.md @@ -14,7 +14,7 @@ Collection is synchronous (like [`dsh-tool-subagent`](../../subagent/tool-subage For a root transport execution (`exec.parent` absent), the tool also projects the run into the calling Agent's Session: run-start after `start()` returns, matching member starts and endings filtered by `run.id`, then run-end only after `run.result` is available and `dispose()` has reached quiescence. Nested transport calls execute normally but write no workflow record. The first failed Session append disables later recording for that run, emits one warning, and leaves either no record or a legal continuous prefix without changing the tool result or cleanup. -The browser-safe `@deepseek-ai/dsh-tool-workflow/types` subpath owns these four log-only event payloads and their `SessionEventMap` declaration. The package invariant rejects duplicate starts, unpaired members, terminal events with open members, and updates after run-end on both cold load and live append while accepting missing terminal suffixes. +The browser-safe `@deepseek-ai/dsh-tool-workflow/types` subpath owns these four log-only event payloads and their `SessionEventMap` declaration. Beside the durable record, each recorded top-level run is mirrored best-effort into the optional `ctx.activities` registry as a `workflow` activity: the otherwise-unconsumed `workflow/phase` and `workflow/log` events plus member lifecycle lines stream into it, so the Web client shows the run's live narration the session log deliberately does not carry per line; without the registry, or on any mirror failure, the run is unaffected. The package invariant rejects duplicate starts, unpaired members, terminal events with open members, and updates after run-end on both cold load and live append while accepting missing terminal suffixes. ## Render intent diff --git a/packages/workflow/tool-workflow/README.zh.md b/packages/workflow/tool-workflow/README.zh.md index 2546a0fc92..582828cf7c 100644 --- a/packages/workflow/tool-workflow/README.zh.md +++ b/packages/workflow/tool-workflow/README.zh.md @@ -14,7 +14,7 @@ 对于根 transport 执行(`exec.parent` 缺省),工具还会把运行投影到调用 Agent 的 Session:`start()` 返回后写 run-start,只记录 `run.id` 匹配的成员开始与结束,并且只在 `run.result` 已取得且 `dispose()` 完全停稳后写 run-end。嵌套 transport 调用照常执行,但不写工作流记录。任一次 Session append 首次失败后,本运行会停止后续记录并只告警一次,留下空记录或合法连续前缀,同时不改变工具结果和清理。 -浏览器安全的 `@deepseek-ai/dsh-tool-workflow/types` 子路径拥有这四类 log-only 事件 payload 及其 `SessionEventMap` 声明。包 invariant 会在冷加载和实时追加时拒绝重复 start、未配对成员、仍有开放成员的终点和 run-end 后更新,同时允许缺失终态后缀的连续前缀。 +浏览器安全的 `@deepseek-ai/dsh-tool-workflow/types` 子路径拥有这四类 log-only 事件 payload 及其 `SessionEventMap` 声明。在持久记录之外,每个被记录的顶层运行还会尽力镜像进可选的 `ctx.activities` 注册表成为一个 `workflow` activity:原本无人消费的 `workflow/phase` 与 `workflow/log` 事件加上成员生命周期行会流入其中,Web 客户端因此能看到会话日志有意不逐行携带的实时叙述;没有该注册表或镜像任何失败时,运行不受影响。包 invariant 会在冷加载和实时追加时拒绝重复 start、未配对成员、仍有开放成员的终点和 run-end 后更新,同时允许缺失终态后缀的连续前缀。 ## 渲染意图 diff --git a/packages/workflow/tool-workflow/package.json b/packages/workflow/tool-workflow/package.json index 455d2ee54c..6cf4bebe3d 100644 --- a/packages/workflow/tool-workflow/package.json +++ b/packages/workflow/tool-workflow/package.json @@ -37,19 +37,23 @@ ], "license": "MIT", "peerDependencies": { + "@deepseek-ai/cordis": "workspace:^", + "@deepseek-ai/dsh-activity": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", - "@deepseek-ai/dsh-workflow": "workspace:^", - "@deepseek-ai/cordis": "workspace:^" + "@deepseek-ai/dsh-workflow": "workspace:^" }, "dependencies": { "@deepseek-ai/schemastery": "workspace:^" }, "devDependencies": { + "@deepseek-ai/cordis": "workspace:^", + "@deepseek-ai/dsh-activity": "workspace:^", + "@deepseek-ai/dsh-activity-local": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", @@ -58,7 +62,6 @@ "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", "@deepseek-ai/dsh-workflow": "workspace:^", - "@deepseek-ai/dsh-workflow-worker-thread": "workspace:^", - "@deepseek-ai/cordis": "workspace:^" + "@deepseek-ai/dsh-workflow-worker-thread": "workspace:^" } } diff --git a/packages/workflow/tool-workflow/src/activity.ts b/packages/workflow/tool-workflow/src/activity.ts new file mode 100644 index 0000000000..36b251b894 --- /dev/null +++ b/packages/workflow/tool-workflow/src/activity.ts @@ -0,0 +1,119 @@ +/** + * Best-effort activity mirror for top-level workflow runs: opens one + * `workflow` activity per run and streams the engine's `workflow/phase`, + * `workflow/log`, and member lifecycle events into it as text lines, so the + * Web client shows live progress the session log deliberately does not carry + * per line. Without a `ctx.activities` registry every operation is a no-op, + * and ANY mirror failure is logged and swallowed — the run is unaffected. + * + * @module @deepseek-ai/dsh-tool-workflow/activity + */ + +import type { Context } from '@deepseek-ai/cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import type { ActivityHandle } from '@deepseek-ai/dsh-activity' +import type { WorkflowRun, WorkflowRunId, WorkflowStopReason } from '@deepseek-ai/dsh-workflow' + +declare module '@deepseek-ai/dsh-activity' { + interface ActivityKindMap { + workflow: 'workflow' + } +} + +/** Activity taps for the three points the tool already tracks a run at. */ +export interface WorkflowActivityMirror { + /** + * Open the run's activity. Call once per recorded top-level run. + * @param run - the started run (id and meta name). + * @param owner - the calling agent, when the call has one. + */ + start(run: WorkflowRun, owner: Agent | undefined): void + /** + * End the run's activity with the mapped stop reason. + * @param runId - the settled run. + * @param stopReason - how the run stopped. + */ + finish(runId: WorkflowRunId, stopReason: WorkflowStopReason): void + /** + * Drop tracking for a run that ends without a settled reason. First-wins + * with {@link finish}: after a normal finish this is inert. + * @param runId - the abandoned run. + */ + abandon(runId: WorkflowRunId): void +} + +/** Map a run's stop reason onto the activity outcome vocabulary. */ +function outcomeOf(stopReason: WorkflowStopReason): { status: 'completed' | 'failed' | 'killed'; detail: string } { + switch (stopReason) { + case 'completed': return { status: 'completed', detail: 'completed' } + case 'cancelled': return { status: 'killed', detail: 'cancelled' } + case 'error': return { status: 'failed', detail: 'error' } + } +} + +/** + * Create the run-to-activity mirror and subscribe the engine's live progress + * events for the runs it tracks. + * @param ctx - plugin context used for the optional registry and warning logs. + * @returns the mirror taps the tool wires beside its durable recorder. + */ +export function createWorkflowActivityMirror(ctx: Context): WorkflowActivityMirror { + const active = new Map() + const contained = (operation: string, act: () => void): void => { + try { + act() + } catch (error: unknown) { + ctx.logger.warn(`workflow activity mirror ${operation} failed: ${String(error)}`) + } + } + + ctx.on('workflow/phase', (info, title) => { + const handle = active.get(info.id) + if (handle === undefined) return + contained('phase', () => { + handle.updateDetail(title) + handle.append(`▸ ${title}\n`) + }) + }) + ctx.on('workflow/log', (info, message) => { + const handle = active.get(info.id) + if (handle === undefined) return + contained('log', () => { handle.append(`${message}\n`) }) + }) + ctx.on('workflow/agent-start', (info, agent) => { + const handle = active.get(info.id) + if (handle === undefined) return + contained('agent-start', () => { handle.append(`agent #${agent.seq} ${agent.label} started\n`) }) + }) + ctx.on('workflow/agent-end', (info, agent) => { + const handle = active.get(info.id) + if (handle === undefined) return + contained('agent-end', () => { handle.append(`agent #${agent.seq} ${agent.outcome}\n`) }) + }) + + return { + start(run, owner) { + contained('open', () => { + const activities = ctx.get('activities') + if (activities === undefined) return + active.set(run.id, activities.open({ + kind: 'workflow', + label: run.meta.name, + ...owner !== undefined ? { owner } : {}, + })) + }) + }, + finish(runId, stopReason) { + const handle = active.get(runId) + active.delete(runId) + if (handle === undefined) return + contained('finish', () => { handle.end(outcomeOf(stopReason)) }) + }, + abandon(runId) { + const handle = active.get(runId) + active.delete(runId) + if (handle === undefined) return + contained('abandon', () => { handle.end({ status: 'killed', detail: 'run abandoned' }) }) + }, + } +} diff --git a/packages/workflow/tool-workflow/src/index.ts b/packages/workflow/tool-workflow/src/index.ts index 446c70ce03..0da8c0ff83 100644 --- a/packages/workflow/tool-workflow/src/index.ts +++ b/packages/workflow/tool-workflow/src/index.ts @@ -25,6 +25,7 @@ import type { } from './types.ts' // Declaration merge only: makes ctx.systemPrompt visible for the section registration. import type {} from '@deepseek-ai/dsh-system-prompt' +import { createWorkflowActivityMirror } from './activity.ts' export const name = 'tool-workflow' export const inject = ['tools', 'workflowEngine', 'systemPrompt'] @@ -207,6 +208,7 @@ export function apply(ctx: Context, config: Config): void { // fields; the assertion records that resolution, not a hidden fallback. const { toolName, maxResultChars } = config as ResolvedConfig const recorder = createWorkflowRecorder(ctx) + const mirror = createWorkflowActivityMirror(ctx) // Usage policy ships with the tool (the master convention: tool guidance // lives in tool plugins as prompt sections, not in the deployment persona). ctx.systemPrompt.section({ @@ -291,7 +293,10 @@ export function apply(ctx: Context, config: Config): void { const recordsRun = exec.parent === undefined // The shipped worker-thread engine publishes member events from later // worker messages, after start() returns and this run record is active. - if (recordsRun) recorder.start(parent.session, run) + if (recordsRun) { + recorder.start(parent.session, run) + mirror.start(run, parent) + } // Bridge the tool's abort signal to the run: if the parent step is aborted while the // script is in flight, cancel the whole run. The signal also enters the engine directly, but @@ -323,9 +328,13 @@ export function apply(ctx: Context, config: Config): void { /* v8 ignore next -- WorkflowRun.result never rejects by contract, so result is assigned before finally. */ if (result === undefined) throw new Error('workflow run settled without a result') recorder.finish(run.id, result.stopReason) + mirror.finish(run.id, result.stopReason) } } finally { - if (recordsRun) recorder.abandon(run.id) + if (recordsRun) { + recorder.abandon(run.id) + mirror.abandon(run.id) + } } } }, diff --git a/packages/workflow/tool-workflow/tests/activity-mirror.spec.ts b/packages/workflow/tool-workflow/tests/activity-mirror.spec.ts new file mode 100644 index 0000000000..50788d453f --- /dev/null +++ b/packages/workflow/tool-workflow/tests/activity-mirror.spec.ts @@ -0,0 +1,106 @@ +import { describe, expect, it, vi } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' +import type { WorkflowRun, WorkflowRunId, WorkflowRunInfo } from '@deepseek-ai/dsh-workflow' +import { createWorkflowActivityMirror } from '../src/activity.ts' + +function runStub(id = 'run-1'): { run: WorkflowRun; info: WorkflowRunInfo } { + const info = { id: id as WorkflowRunId, meta: { name: 'docs-sweep' } } as WorkflowRunInfo + return { + run: { id: id as WorkflowRunId, meta: { name: 'docs-sweep' } } as WorkflowRun, + info, + } +} + +function retainedText(ctx: Context): string { + const row = ctx.activities.list()[0] + if (row === undefined) throw new Error('no mirrored activity') + return ctx.activities.read(row.id, 0).chunks.map(chunk => chunk.text).join('') +} + +describe('workflow activity mirror', () => { + it('opens one workflow activity per run and streams phase, log, and member lines', async () => { + const ctx = new Context() + await ctx.plugin(LocalActivityRegistry) + const mirror = createWorkflowActivityMirror(ctx) + const { run, info } = runStub() + mirror.start(run, undefined) + + const row = ctx.activities.list()[0] + expect(row?.kind).toBe('workflow') + expect(row?.label).toBe('docs-sweep') + + ctx.emit('workflow/phase', info, 'Scan') + ctx.emit('workflow/log', info, '3 files queued') + ctx.emit('workflow/agent-start', info, { seq: 1, label: 'reader', childId: 'c1' } as never) + ctx.emit('workflow/agent-end', info, { seq: 1, label: 'reader', childId: 'c1', outcome: 'completed' } as never) + expect(ctx.activities.get(row!.id).detail).toBe('Scan') + expect(retainedText(ctx)).toBe('▸ Scan\n3 files queued\nagent #1 reader started\nagent #1 completed\n') + + mirror.finish(run.id, 'completed') + const settled = ctx.activities.get(row!.id) + expect(settled.status).toBe('completed') + // The always-run abandon after a normal finish is inert. + mirror.abandon(run.id) + expect(ctx.activities.get(row!.id).status).toBe('completed') + }) + + it('maps cancelled and error stops, and ends an abandoned run as killed', async () => { + const ctx = new Context() + await ctx.plugin(LocalActivityRegistry) + const mirror = createWorkflowActivityMirror(ctx) + + const cancelled = runStub('run-c') + mirror.start(cancelled.run, undefined) + mirror.finish(cancelled.run.id, 'cancelled') + + const failed = runStub('run-e') + mirror.start(failed.run, undefined) + mirror.finish(failed.run.id, 'error') + + const orphaned = runStub('run-o') + mirror.start(orphaned.run, undefined) + mirror.abandon(orphaned.run.id) + + const byLabelOrder = ctx.activities.list() + expect(byLabelOrder.map(row => [row.status, row.detail])).toEqual([ + ['killed', 'cancelled'], + ['failed', 'error'], + ['killed', 'run abandoned'], + ]) + }) + + it('ignores events for untracked runs and stays inert without the registry', async () => { + const bare = new Context() + const inert = createWorkflowActivityMirror(bare) + const { run, info } = runStub() + // No registry: every tap is a no-op rather than a throw. + inert.start(run, undefined) + bare.emit('workflow/log', info, 'dropped') + inert.finish(run.id, 'completed') + inert.abandon(run.id) + + const ctx = new Context() + await ctx.plugin(LocalActivityRegistry) + createWorkflowActivityMirror(ctx) + // Events for a run the mirror never opened change nothing. + ctx.emit('workflow/phase', info, 'ghost') + expect(ctx.activities.list()).toEqual([]) + }) + + it('contains a throwing registry so the run path never breaks', async () => { + const ctx = new Context() + const warn = vi.fn() + ctx.logger.warn = warn as never + await ctx.plugin({ + name: 'broken-activities-probe', + apply(child: Context) { + child.provide('activities', { open() { throw new Error('mirror boom') } }) + }, + }) + const mirror = createWorkflowActivityMirror(ctx) + const { run } = runStub() + expect(() => { mirror.start(run, undefined) }).not.toThrow() + expect(warn).toHaveBeenCalledWith(expect.stringContaining('workflow activity mirror open failed')) + }) +}) diff --git a/packages/workflow/tool-workflow/tsconfig.json b/packages/workflow/tool-workflow/tsconfig.json index bfd38e61d4..a4cde5cbef 100644 --- a/packages/workflow/tool-workflow/tsconfig.json +++ b/packages/workflow/tool-workflow/tsconfig.json @@ -37,6 +37,9 @@ }, { "path": "../../runtime-diagnostics/invariants" + }, + { + "path": "../../activity/activity" } ] } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index f6878a775b..32f9a464b7 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -886,6 +886,110 @@ importers: specifier: workspace:^ version: link:../../interaction/user-approval + packages/activity/activity: + devDependencies: + '@deepseek-ai/cordis': + specifier: workspace:^ + version: link:../../../vendor/cordis + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../../core/agent + '@deepseek-ai/dsh-brand': + specifier: workspace:^ + version: link:../../util/brand + '@deepseek-ai/dsh-invariants': + specifier: workspace:^ + version: link:../../runtime-diagnostics/invariants + '@deepseek-ai/dsh-jobs': + specifier: workspace:^ + version: link:../../jobs/jobs + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session + + packages/activity/activity-local: + dependencies: + '@deepseek-ai/schemastery': + specifier: link:../../../vendor/schemastery + version: link:../../../vendor/schemastery + devDependencies: + '@deepseek-ai/cordis': + specifier: workspace:^ + version: link:../../../vendor/cordis + '@deepseek-ai/cordis-plugin-include': + specifier: workspace:^ + version: link:../../../vendor/include + '@deepseek-ai/cordis-plugin-loader': + specifier: workspace:^ + version: link:../../../vendor/loader + '@deepseek-ai/dsh-activity': + specifier: workspace:^ + version: link:../activity + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../../core/agent + '@deepseek-ai/dsh-brand': + specifier: workspace:^ + version: link:../../util/brand + '@deepseek-ai/dsh-invariants': + specifier: workspace:^ + version: link:../../runtime-diagnostics/invariants + '@deepseek-ai/dsh-scope': + specifier: workspace:^ + version: link:../../core/scope + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session + + packages/api/activity-controller: + dependencies: + '@deepseek-ai/schemastery': + specifier: link:../../../vendor/schemastery + version: link:../../../vendor/schemastery + zod: + specifier: ^4.4.3 + version: 4.4.3 + devDependencies: + '@deepseek-ai/cordis': + specifier: workspace:^ + version: link:../../../vendor/cordis + '@deepseek-ai/dsh-activity': + specifier: workspace:^ + version: link:../../activity/activity + '@deepseek-ai/dsh-activity-local': + specifier: workspace:^ + version: link:../../activity/activity-local + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../../core/agent + '@deepseek-ai/dsh-api-gateway': + specifier: workspace:^ + version: link:../gateway + '@deepseek-ai/dsh-client-connection': + specifier: workspace:^ + version: link:../../client/connection + '@deepseek-ai/dsh-client-store': + specifier: workspace:^ + version: link:../../client/store + '@deepseek-ai/dsh-invariants': + specifier: workspace:^ + version: link:../../runtime-diagnostics/invariants + '@deepseek-ai/dsh-jobs': + specifier: workspace:^ + version: link:../../jobs/jobs + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session + '@deepseek-ai/dsh-typert-protocol': + specifier: workspace:^ + version: link:../../typert/protocol + packages/api/gateway: dependencies: '@deepseek-ai/dsh-typert-protocol': @@ -938,6 +1042,9 @@ importers: '@deepseek-ai/dsh-agent-presets': specifier: workspace:^ version: link:../../preset/agent-presets + '@deepseek-ai/dsh-api-activity-controller': + specifier: workspace:^ + version: link:../activity-controller '@deepseek-ai/dsh-api-gateway': specifier: workspace:^ version: link:../gateway @@ -1240,6 +1347,9 @@ importers: '@deepseek-ai/cordis-plugin-timer': specifier: workspace:^ version: link:../../../vendor/timer + '@deepseek-ai/dsh-activity-local': + specifier: workspace:^ + version: link:../../activity/activity-local '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../../core/agent @@ -1607,6 +1717,9 @@ importers: '@deepseek-ai/dsh-agent-presets': specifier: workspace:^ version: link:../../preset/agent-presets + '@deepseek-ai/dsh-api-activity-controller': + specifier: workspace:^ + version: link:../../api/activity-controller '@deepseek-ai/dsh-api-remotes': specifier: workspace:^ version: link:../../api/remotes @@ -1631,6 +1744,9 @@ importers: '@deepseek-ai/dsh-client-modules': specifier: workspace:^ version: link:../../client/modules + '@deepseek-ai/dsh-client-ui-activity': + specifier: workspace:^ + version: link:../../client/ui-activity '@deepseek-ai/dsh-client-ui-agent-preset': specifier: workspace:^ version: link:../../client/ui-agent-preset @@ -1976,6 +2092,45 @@ importers: specifier: workspace:^ version: link:../../runtime-diagnostics/invariants + packages/client/ui-activity: + devDependencies: + '@deepseek-ai/cordis': + specifier: workspace:^ + version: link:../../../vendor/cordis + '@deepseek-ai/dsh-api-activity-controller': + specifier: workspace:^ + version: link:../../api/activity-controller + '@deepseek-ai/dsh-client-locale': + specifier: workspace:^ + version: link:../locale + '@deepseek-ai/dsh-client-test-runtime': + specifier: workspace:^ + version: link:../../test-support/client-runtime + '@deepseek-ai/dsh-client-ui-conversation': + specifier: workspace:^ + version: link:../ui-conversation + '@deepseek-ai/dsh-client-ui-primitives': + specifier: workspace:^ + version: link:../ui-primitives + '@deepseek-ai/dsh-client-ui-renderer': + specifier: workspace:^ + version: link:../ui-renderer + '@deepseek-ai/dsh-client-ui-session': + specifier: workspace:^ + version: link:../ui-session + '@deepseek-ai/dsh-client-ui-slots': + specifier: workspace:^ + version: link:../ui-slots + '@deepseek-ai/dsh-invariants': + specifier: workspace:^ + version: link:../../runtime-diagnostics/invariants + '@types/react': + specifier: ~18.3.1 + version: 18.3.31 + react: + specifier: ^18.2.0 + version: 18.3.1 + packages/client/ui-agent-preset: devDependencies: '@deepseek-ai/cordis': @@ -7701,6 +7856,9 @@ importers: '@deepseek-ai/cordis': specifier: workspace:^ version: link:../../../vendor/cordis + '@deepseek-ai/dsh-activity': + specifier: workspace:^ + version: link:../../activity/activity '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../../core/agent @@ -7820,6 +7978,9 @@ importers: '@deepseek-ai/cordis': specifier: workspace:^ version: link:../../../vendor/cordis + '@deepseek-ai/dsh-activity': + specifier: workspace:^ + version: link:../../activity/activity '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../../core/agent @@ -9538,6 +9699,12 @@ importers: '@deepseek-ai/cordis': specifier: workspace:^ version: link:../../../vendor/cordis + '@deepseek-ai/dsh-activity': + specifier: workspace:^ + version: link:../../activity/activity + '@deepseek-ai/dsh-activity-local': + specifier: workspace:^ + version: link:../../activity/activity-local '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../../core/agent @@ -9690,6 +9857,9 @@ importers: '@deepseek-ai/dsh-acp': specifier: workspace:^ version: link:../../packages/acp/acp + '@deepseek-ai/dsh-activity': + specifier: workspace:^ + version: link:../../packages/activity/activity '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../../packages/core/agent diff --git a/python/sdk-runtime/package.json b/python/sdk-runtime/package.json index d5684867e6..3becddb8c7 100644 --- a/python/sdk-runtime/package.json +++ b/python/sdk-runtime/package.json @@ -5,6 +5,7 @@ "private": true, "type": "module", "dependencies": { + "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/cordis-plugin-group": "workspace:^", "@deepseek-ai/cordis-plugin-include": "workspace:^", "@deepseek-ai/cordis-plugin-loader": "workspace:^", @@ -12,15 +13,17 @@ "@deepseek-ai/cosmokit": "workspace:^", "@deepseek-ai/dsh": "workspace:^", "@deepseek-ai/dsh-acp": "workspace:^", + "@deepseek-ai/dsh-activity": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-agent-instructions": "workspace:^", "@deepseek-ai/dsh-agent-loop": "workspace:^", "@deepseek-ai/dsh-agent-spine-demo": "workspace:^", "@deepseek-ai/dsh-agent-tool-presentation": "workspace:^", + "@deepseek-ai/dsh-anonymous-user-id": "workspace:^", "@deepseek-ai/dsh-app-boot": "workspace:^", - "@deepseek-ai/dsh-attachment": "workspace:^", "@deepseek-ai/dsh-atomic-write": "workspace:^", - "@deepseek-ai/dsh-shell": "workspace:^", - "@deepseek-ai/dsh-shell-env": "workspace:^", + "@deepseek-ai/dsh-attachment": "workspace:^", + "@deepseek-ai/dsh-authorization": "workspace:^", "@deepseek-ai/dsh-bash-local": "workspace:^", "@deepseek-ai/dsh-brand": "workspace:^", "@deepseek-ai/dsh-code-runtime": "workspace:^", @@ -32,44 +35,43 @@ "@deepseek-ai/dsh-compaction-basic": "workspace:^", "@deepseek-ai/dsh-compaction-tool-result-pruner": "workspace:^", "@deepseek-ai/dsh-cordis-host-runner": "workspace:^", - "@deepseek-ai/dsh-authorization": "workspace:^", "@deepseek-ai/dsh-credentials": "workspace:^", - "@deepseek-ai/dsh-launch-environment": "workspace:^", + "@deepseek-ai/dsh-deepseek-llm-api-extensions": "workspace:^", "@deepseek-ai/dsh-fs": "workspace:^", "@deepseek-ai/dsh-fs-local": "workspace:^", "@deepseek-ai/dsh-fs-observation-policy": "workspace:^", "@deepseek-ai/dsh-fs-sandbox": "workspace:^", "@deepseek-ai/dsh-goal": "workspace:^", "@deepseek-ai/dsh-goal-round-driver": "workspace:^", + "@deepseek-ai/dsh-home-paths": "workspace:^", "@deepseek-ai/dsh-hook-protocol": "workspace:^", "@deepseek-ai/dsh-hooks-claude-code": "workspace:^", "@deepseek-ai/dsh-hooks-codex": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-sdk-jsonrpc-server": "workspace:^", + "@deepseek-ai/dsh-jobs": "workspace:^", + "@deepseek-ai/dsh-jobs-local": "workspace:^", + "@deepseek-ai/dsh-launch-environment": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-llm-deepseek": "workspace:^", - "@deepseek-ai/dsh-deepseek-llm-api-extensions": "workspace:^", - "@deepseek-ai/dsh-plugin-package-inventory-deepseek": "workspace:^", - "@deepseek-ai/dsh-session-log-deepseek": "workspace:^", "@deepseek-ai/dsh-llm-pi-ai": "workspace:^", "@deepseek-ai/dsh-llm-retry": "workspace:^", "@deepseek-ai/dsh-mcp-client": "workspace:^", - "@deepseek-ai/dsh-home-paths": "workspace:^", - "@deepseek-ai/dsh-permission-presets": "workspace:^", - "@deepseek-ai/dsh-plan-mode": "workspace:^", - "@deepseek-ai/dsh-persona": "workspace:^", - "@deepseek-ai/dsh-pwsh-local": "workspace:^", - "@deepseek-ai/dsh-terminal": "workspace:^", - "@deepseek-ai/dsh-terminal-bash": "workspace:^", - "@deepseek-ai/dsh-repeat-tool-reminder": "workspace:^", "@deepseek-ai/dsh-output-retention": "workspace:^", + "@deepseek-ai/dsh-permission-presets": "workspace:^", + "@deepseek-ai/dsh-persona": "workspace:^", + "@deepseek-ai/dsh-plan-mode": "workspace:^", + "@deepseek-ai/dsh-plugin-package-inventory-deepseek": "workspace:^", + "@deepseek-ai/dsh-pwsh-local": "workspace:^", + "@deepseek-ai/dsh-repeat-tool-reminder": "workspace:^", "@deepseek-ai/dsh-sandbox": "workspace:^", "@deepseek-ai/dsh-sandbox-local": "workspace:^", "@deepseek-ai/dsh-sandbox-policy": "workspace:^", "@deepseek-ai/dsh-scope": "workspace:^", + "@deepseek-ai/dsh-sdk-jsonrpc-server": "workspace:^", "@deepseek-ai/dsh-sdk-protocol": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^", + "@deepseek-ai/dsh-session-log-deepseek": "workspace:^", "@deepseek-ai/dsh-session-persistence": "workspace:^", "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^", "@deepseek-ai/dsh-session-persistence-sqlite": "workspace:^", @@ -80,6 +82,8 @@ "@deepseek-ai/dsh-session-telemetry": "workspace:^", "@deepseek-ai/dsh-session-title": "workspace:^", "@deepseek-ai/dsh-settings": "workspace:^", + "@deepseek-ai/dsh-shell": "workspace:^", + "@deepseek-ai/dsh-shell-env": "workspace:^", "@deepseek-ai/dsh-skill": "workspace:^", "@deepseek-ai/dsh-skill-filesystem": "workspace:^", "@deepseek-ai/dsh-spill": "workspace:^", @@ -91,31 +95,30 @@ "@deepseek-ai/dsh-subprocess": "workspace:^", "@deepseek-ai/dsh-subprocess-local": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", - "@deepseek-ai/dsh-jobs": "workspace:^", - "@deepseek-ai/dsh-jobs-local": "workspace:^", + "@deepseek-ai/dsh-terminal": "workspace:^", + "@deepseek-ai/dsh-terminal-bash": "workspace:^", "@deepseek-ai/dsh-timeout": "workspace:^", - "@deepseek-ai/dsh-tool-call-timeout-policy": "workspace:^", "@deepseek-ai/dsh-token-meter": "workspace:^", "@deepseek-ai/dsh-tool-ask-user": "workspace:^", "@deepseek-ai/dsh-tool-bash": "workspace:^", "@deepseek-ai/dsh-tool-bash-persistent": "workspace:^", + "@deepseek-ai/dsh-tool-call-timeout-policy": "workspace:^", "@deepseek-ai/dsh-tool-cordis": "workspace:^", "@deepseek-ai/dsh-tool-fs": "workspace:^", "@deepseek-ai/dsh-tool-fs-search": "workspace:^", "@deepseek-ai/dsh-tool-goal": "workspace:^", + "@deepseek-ai/dsh-tool-jobs": "workspace:^", "@deepseek-ai/dsh-tool-ralph": "workspace:^", "@deepseek-ai/dsh-tool-skill": "workspace:^", "@deepseek-ai/dsh-tool-str-replace-editor": "workspace:^", "@deepseek-ai/dsh-tool-subagent": "workspace:^", "@deepseek-ai/dsh-tool-subagent-control": "workspace:^", - "@deepseek-ai/dsh-tool-jobs": "workspace:^", "@deepseek-ai/dsh-tool-todo": "workspace:^", "@deepseek-ai/dsh-tool-web": "workspace:^", "@deepseek-ai/dsh-tool-workflow": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", "@deepseek-ai/dsh-typert-protocol": "workspace:^", "@deepseek-ai/dsh-user-approval": "workspace:^", - "@deepseek-ai/dsh-anonymous-user-id": "workspace:^", "@deepseek-ai/dsh-user-questions": "workspace:^", "@deepseek-ai/dsh-web": "workspace:^", "@deepseek-ai/dsh-web-fetch-http": "workspace:^", @@ -124,8 +127,6 @@ "@deepseek-ai/dsh-web-search-perplexity": "workspace:^", "@deepseek-ai/dsh-workflow": "workspace:^", "@deepseek-ai/dsh-workflow-worker-thread": "workspace:^", - "@deepseek-ai/dsh-agent-instructions": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/schemastery": "workspace:^" } } diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index 05a4c8947c..095c33af7c 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -105,6 +105,8 @@ export const SERVICE_PAGE: Record = { subprocess: 'subprocess.md', systemPrompt: 'system-prompt.md', jobs: 'jobs.md', + activities: 'activity.md', + activityController: 'activity.md', sessionTelemetry: 'session-telemetry.md', agentTeams: 'agent-team.md', tokenMeter: 'token-meter.md', @@ -168,6 +170,7 @@ export const SERVICE_WALK_EXEMPTIONS: Record = { slots: 'client-side interface-typed browser service — packages/client/ui-renderer/README.md owns the API', theme: 'client-side interface-typed browser service — packages/client/ui-theme/README.md owns the API', workspaces: 'client-side interface-typed browser service — packages/api/workspace-controller/README.md owns the API', + activityFeed: 'client-side interface-typed browser service — packages/api/activity-controller/README.md owns the API', } /** @@ -477,6 +480,16 @@ export const LINK_MAP: Readonly> = { PromptSection: 'system-prompt.md', SystemPrompt: 'system-prompt.md', ToolProviderResult: 'system-prompt.md', + ActivitiesChangedListener: 'activity.md', + ActivityHandle: 'activity.md', + ActivityId: 'activity.md', + ActivityOpen: 'activity.md', + ActivityOutputListener: 'activity.md', + ActivityRead: 'activity.md', + ActivitySnapshot: 'activity.md', + ActivityControlFrame: 'activity.md', + ActivityObserveFrame: 'activity.md', + ActivityObserveRequest: 'activity.md', JobDoneListener: 'jobs.md', JobId: 'jobs.md', JobRead: 'jobs.md', diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index a47f94b943..83983f294f 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -164,6 +164,13 @@ const SERVICE_ROLES: ServiceRole[] = [ mode: 'core', note: 'Owns Workspace commands and reconnect-safe Workspace state delivery through the generated Remote namespace.', }, + { + key: 'activityController', + pkg: 'api-activity-controller', + title: 'Host Activity Remote controller', + mode: 'core', + note: 'Owns the live-activity roster stream and per-activity non-consuming output observation through the generated Remote namespace.', + }, { key: 'invariants', pkg: 'invariants', @@ -537,6 +544,15 @@ const SERVICE_ROLES: ServiceRole[] = [ consumers: ['tool-bash', 'tool-terminal', 'tool-subagent', 'tool-jobs'], note: 'Producers (background bash, PTY sends, and subagent delegations) register running work; tool-jobs is the model-facing controller that reads, lists, and kills it; jobs-local is the process-local registry.', }, + { + key: 'activities', + pkg: 'activity', + title: 'Live activity observation registry', + mode: 'seam', + implementations: ['activity-local'], + consumers: ['tool-bash', 'tool-pwsh', 'tool-workflow', 'activity-controller'], + note: 'Producers mirror live output and status into non-consuming offset-addressed streams; activity-controller serves them to browsers, and the model-facing paths (jobs cursors, tool results) stay untouched.', + }, { key: 'web', pkg: 'web', diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts index f83b621965..48bc458bfa 100644 --- a/scripts/verify-package-readme-model-experience.ts +++ b/scripts/verify-package-readme-model-experience.ts @@ -45,6 +45,10 @@ const NO_MODEL_EXPERIENCE_SECTION: Readonly> = { const SENTENCE_MODEL_EXPERIENCE: Readonly> = { 'packages/attachment/attachment': { kind: 'indirect', reason: 'The storage seam delegates model request rendering to provider adapters.' }, 'packages/attachment/attachment-local': { kind: 'indirect', reason: 'The local backend delegates model request rendering to provider adapters.' }, + 'packages/activity/activity': { kind: 'none', reason: 'Pure observation seam for humans; activity output becomes model-visible only through producers\' existing tool results and jobs reads.' }, + 'packages/activity/activity-local': { kind: 'none', reason: 'In-memory observation provider; producers own every model-visible surface.' }, + 'packages/api/activity-controller': { kind: 'none', reason: 'Browser/Host observation transport; registers no prompt, tool, or session event.' }, + 'packages/client/ui-activity': { kind: 'none', reason: 'Browser-side presentation of host-observed output; touches no prompt, message, schema, stream, or tool result.' }, 'packages/shell/shell': { kind: 'indirect', reason: 'The service interface delegates all model rendering to dsh-tool-bash.' }, 'packages/shell/shell-env': { kind: 'indirect', reason: 'The env service exposes managed DSH_* facts through the shell tools (dsh-tool-bash/dsh-tool-pwsh); it registers no prompt or schema of its own.' }, 'packages/shell/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' }, diff --git a/tsconfig.base.json b/tsconfig.base.json index 8a8bc37baa..11ae967059 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -47,6 +47,7 @@ "@deepseek-ai/dsh-api-gateway/client": ["./packages/api/gateway/src/client/index.ts"], "@deepseek-ai/dsh-api-gateway/invariant": ["./packages/api/gateway/src/invariant.ts"], "@deepseek-ai/dsh-api-gateway/types": ["./packages/api/gateway/src/types.ts"], + "@deepseek-ai/dsh-api-activity-controller": ["./packages/api/activity-controller/src/index.ts"], "@deepseek-ai/dsh-api-session-controller": ["./packages/api/session-controller/src/index.ts"], "@deepseek-ai/dsh-api-session-controller/client": ["./packages/api/session-controller/src/client/index.ts"], "@deepseek-ai/dsh-api-session-controller/invariant": ["./packages/api/session-controller/src/invariant.ts"], @@ -56,6 +57,7 @@ "@deepseek-ai/dsh-api-workspace-controller/client": ["./packages/api/workspace-controller/src/client/index.ts"], "@deepseek-ai/dsh-api-workspace-controller/invariant": ["./packages/api/workspace-controller/src/invariant.ts"], "@deepseek-ai/dsh-api-workspace-controller/types": ["./packages/api/workspace-controller/src/types.ts"], + "@deepseek-ai/dsh-api-activity-controller/types": ["./packages/api/activity-controller/src/types.ts"], "@deepseek-ai/dsh-typert-protocol": ["./packages/typert/protocol/src/index.ts"], "@deepseek-ai/dsh-typert-protocol/types": ["./packages/typert/protocol/src/types.ts"], "@deepseek-ai/dsh-typert-loader": ["./packages/typert/loader/src/index.ts"], @@ -95,6 +97,8 @@ "@deepseek-ai/dsh-commands/brand": ["./packages/interaction/commands/src/brand.ts"], "@deepseek-ai/dsh-commands/types": ["./packages/interaction/commands/src/types.ts"], "@deepseek-ai/dsh-jobs/brand": ["./packages/jobs/jobs/src/brand.ts"], + "@deepseek-ai/dsh-activity/brand": ["./packages/activity/activity/src/brand.ts"], + "@deepseek-ai/dsh-activity/invariant": ["./packages/activity/activity/src/invariant.ts"], "@deepseek-ai/dsh-credentials/types": ["./packages/credentials/credentials/src/types.ts"], "@deepseek-ai/dsh-authorization/types": ["./packages/credentials/authorization/src/types.ts"], "@deepseek-ai/dsh-settings/types": ["./packages/settings/settings/src/types.ts"], @@ -245,6 +249,7 @@ "@deepseek-ai/dsh-client-ui-subagent": ["./packages/client/ui-subagent/src"], "@deepseek-ai/dsh-client-ui-settings-plugins": ["./packages/client/ui-settings-plugins/src"], "@deepseek-ai/dsh-client-ui-jobs": ["./packages/client/ui-jobs/src"], + "@deepseek-ai/dsh-client-ui-activity": ["./packages/client/ui-activity/src"], "@deepseek-ai/dsh-client-ui-plan": ["./packages/client/ui-plan/src"], "@deepseek-ai/dsh-client-ui-user-questions": ["./packages/client/ui-user-questions/src"], "@deepseek-ai/dsh-client-ui-trajectory": ["./packages/client/ui-trajectory/src"], @@ -288,6 +293,7 @@ "./packages/preset/*/src", "./packages/subagent/*/src", "./packages/jobs/*/src", + "./packages/activity/*/src", "./packages/experimental/*/src", "./packages/workflow/*/src", "./packages/webhook/*/src", diff --git a/tsconfig.client.json b/tsconfig.client.json index 291b813300..41f6aea41a 100644 --- a/tsconfig.client.json +++ b/tsconfig.client.json @@ -56,6 +56,7 @@ { "path": "./packages/typert/registry" }, { "path": "./packages/api/gateway/tsconfig.client.json" }, { "path": "./packages/api/session-controller/tsconfig.client.json" }, + { "path": "./packages/api/activity-controller/tsconfig.client.json" }, { "path": "./packages/api/workspace-controller/tsconfig.client.json" }, { "path": "./packages/api/remotes/tsconfig.client.json" }, { "path": "./packages/extensions/cordis-client-runner" }, @@ -77,6 +78,7 @@ { "path": "./packages/client/ui-reference" }, { "path": "./packages/client/ui-subagent" }, { "path": "./packages/client/ui-jobs" }, + { "path": "./packages/client/ui-activity" }, { "path": "./packages/client/ui-directory-picker-browse" }, { "path": "./packages/client/ui-directory-picker-native" }, { "path": "./packages/client/ui-goal" }, diff --git a/tsconfig.host.json b/tsconfig.host.json index 0bcbe50df3..d8bcd91c08 100644 --- a/tsconfig.host.json +++ b/tsconfig.host.json @@ -77,6 +77,7 @@ "apps/web/tests/subagent-interrupt-ui.e2e.ts", "apps/web/tests/sidebar-subagent-activity.e2e.ts", "apps/web/tests/background-job-list.e2e.ts", + "apps/web/tests/live-activity-stream.e2e.ts", "apps/web/tests/bash-abort-row.e2e.ts", "apps/web/tests/skill-tool-row.e2e.ts", "apps/web/tests/turn-tail-actions.e2e.ts", @@ -146,6 +147,7 @@ { "path": "./packages/api/gateway/tsconfig.host.json" }, { "path": "./packages/api/remotes/tsconfig.host.json" }, { "path": "./packages/api/session-controller/tsconfig.host.json" }, + { "path": "./packages/api/activity-controller/tsconfig.host.json" }, { "path": "./packages/api/workspace-controller/tsconfig.host.json" }, { "path": "./packages/typert/loader" }, { "path": "./packages/session/session-persistence" }, @@ -288,6 +290,8 @@ { "path": "./packages/jobs/jobs" }, { "path": "./packages/jobs/jobs-local" }, { "path": "./packages/jobs/tool-jobs" }, + { "path": "./packages/activity/activity" }, + { "path": "./packages/activity/activity-local" }, { "path": "./packages/experimental/agent-team" }, { "path": "./packages/experimental/tool-agent-team" }, { "path": "./packages/workflow/workflow" }, From ddd8baa93a7e6c7d3b61ab3d94ab3438f5e42f17 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Mon, 24 Aug 2026 23:07:17 +0800 Subject: [PATCH 003/100] fix(activity): mark evicted heads on fresh observation and fit the popover to the viewport MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Browser acceptance against a live scaffold surfaced two defects: - A fresh observation anchors at the registry's earliest retained byte, so the client's gap predicate (anchor behind earliest) never fired for it: a viewer who watched eviction live saw the gap notice, while a reload of the same activity silently hid that the head was discarded. A fresh view (no accumulated text) anchored past offset zero now carries the gap mark; resumes keep their recorded state. - The trigger-anchored popover (left: 0, width 440px) overflowed the right viewport edge on narrow windows — max-width alone cannot see the anchor offset. The open popover now measures its anchor and shifts left to keep the Menu primitive's 12px viewport margin, re-fitting on window resize and falling back to the pure CSS anchor when layout reports no width (jsdom). JobListAction shares the latent overflow; tracked separately. --- .../activity-controller/src/client/model.ts | 7 +++- .../tests/client-model.client.spec.ts | 15 ++++++++ .../src/client/ActivityListAction.tsx | 37 ++++++++++++++++++- .../activity-list-action.client.spec.tsx | 37 +++++++++++++++++++ 4 files changed, 93 insertions(+), 3 deletions(-) diff --git a/packages/api/activity-controller/src/client/model.ts b/packages/api/activity-controller/src/client/model.ts index 96fb7cca5a..75354f1255 100644 --- a/packages/api/activity-controller/src/client/model.ts +++ b/packages/api/activity-controller/src/client/model.ts @@ -128,10 +128,15 @@ export class ClientActivityModel { */ observeOpened(id: ActivityId, frame: Extract): void { const existing = this.observedStates.get(String(id)) + // A fresh view anchored past offset zero starts after an evicted head + // (fresh observations anchor at the registry's earliest retained byte), so + // it owes the same gap mark a live observer earned from lossy reads. A + // resume that already accumulated text keeps its recorded gap state. + const freshPastHead = (existing === undefined || existing.view.text === '') && frame.from > 0 const view: ObservedActivity = { activityId: id, text: existing?.view.text ?? '', - gapBefore: (existing?.view.gapBefore ?? false) || frame.from < frame.earliest, + gapBefore: (existing?.view.gapBefore ?? false) || frame.from < frame.earliest || freshPastHead, status: frame.status, ...frame.detail !== undefined ? { detail: frame.detail } : {}, streaming: true, diff --git a/packages/api/activity-controller/tests/client-model.client.spec.ts b/packages/api/activity-controller/tests/client-model.client.spec.ts index 59ec9067c5..31f5d18c33 100644 --- a/packages/api/activity-controller/tests/client-model.client.spec.ts +++ b/packages/api/activity-controller/tests/client-model.client.spec.ts @@ -106,6 +106,21 @@ describe('ClientActivityModel observation', () => { expect(lossy.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) }) + it('marks a fresh observation anchored past the evicted head', () => { + // Fresh observations anchor at the registry's earliest retained byte, so + // from === earliest > 0 means the head was already discarded. + const fresh = new ClientActivityModel() + opened(fresh, { from: 60_240, earliest: 60_240, total: 321_328 }) + expect(fresh.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) + + // A retry that accumulated no text yet earns the mark the same way. + const retried = new ClientActivityModel() + opened(retried) + expect(retried.getSnapshot().observed[String(ID)]?.gapBefore).toBe(false) + opened(retried, { from: 6, earliest: 6, total: 6 }) + expect(retried.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) + }) + it('bounds the render tail without splitting a surrogate pair', () => { const model = new ClientActivityModel() opened(model) diff --git a/packages/client/ui-activity/src/client/ActivityListAction.tsx b/packages/client/ui-activity/src/client/ActivityListAction.tsx index 698815e171..1f868988b0 100644 --- a/packages/client/ui-activity/src/client/ActivityListAction.tsx +++ b/packages/client/ui-activity/src/client/ActivityListAction.tsx @@ -1,4 +1,4 @@ -import { useEffect, useMemo, useRef, useState, type KeyboardEvent } from 'react' +import { useEffect, useLayoutEffect, useMemo, useRef, useState, type KeyboardEvent } from 'react' import type { ActivityFeedSnapshot, ActivityId, ActivityRow, ObservedActivity, } from '@deepseek-ai/dsh-api-activity-controller/client' @@ -36,6 +36,9 @@ export type ActivityListActionProps = /** Stable empty list so a session with no activities keeps one array identity. */ const NO_ROWS: readonly ActivityRow[] = [] +/** Minimum gap kept between the popover and the viewport edges (the Menu primitive's portal margin). */ +const VIEWPORT_MARGIN = 12 + /** Height cap for one live output panel inside the popover. */ const PANEL_MAX_LINES = 16 @@ -170,12 +173,42 @@ export function ActivityListAction({ sessionId, useActivity, observe, t }: Activ const [expandedId, setExpandedId] = useState(undefined) const rootRef = useRef(null) const triggerRef = useRef(null) + const menuRef = useRef(null) + // Horizontal shift applied to the trigger-anchored popover so it stays + // inside the viewport (the stylesheet alone cannot see the anchor offset). + const [menuShift, setMenuShift] = useState(0) const rows = useMemo(() => ordered([...owned, ...unowned]), [owned, unowned]) const liveCount = useMemo(() => rows.filter(isLive).length, [rows]) useDismissOnOutsidePointer(rootRef, open, setOpen) + // Fit the open popover to the viewport: shift left when the anchored width + // would cross the right edge, never past the left margin. + useLayoutEffect(() => { + if (!open) { + setMenuShift(0) + return + } + const fit = (): void => { + const root = rootRef.current + const menu = menuRef.current + /* v8 ignore next -- both refs are attached while the open popover renders. */ + if (root === null || menu === null) return + const width = menu.offsetWidth + // Unlaid-out nodes (and jsdom) measure 0: keep the pure CSS anchor. + if (width === 0) return + const anchorLeft = root.getBoundingClientRect().left + setMenuShift(Math.max( + VIEWPORT_MARGIN - anchorLeft, + Math.min(0, window.innerWidth - VIEWPORT_MARGIN - width - anchorLeft), + )) + } + fit() + window.addEventListener('resize', fit) + return () => { window.removeEventListener('resize', fit) } + }, [open]) + // Observation follows visibility: the stream opens when a panel expands and // closes when it collapses, unmounts, or the popover closes. const activeId = open ? expandedId : undefined @@ -229,7 +262,7 @@ export function ActivityListAction({ sessionId, useActivity, observe, t }: Activ {/* jscpd:ignore-end */} {open ? ( -
      +
        {rows.map(row => ( { expect(screen.getAllByText(zh['status.completed']).length).toBeGreaterThan(0) }) + it('shifts an overflowing popover back inside the viewport and follows resizes', () => { + vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(440) + vi.spyOn(HTMLDivElement.prototype, 'getBoundingClientRect').mockReturnValue({ left: 344 } as DOMRect) + const originalWidth = window.innerWidth + Object.defineProperty(window, 'innerWidth', { value: 700, configurable: true, writable: true }) + try { + render() + openList() + const menu = screen.getByRole('list', { name: zh['list.aria'] }) + // 700 - 12 - 440 - 344 = -96: the popover moves left to keep the margin. + expect(menu.style.left).toBe('-96px') + + window.innerWidth = 900 + fireEvent(window, new Event('resize')) + // 900 - 12 - 440 - 344 = 104 > 0: the anchored position fits again. + expect(menu.style.left).toBe('0px') + } finally { + Object.defineProperty(window, 'innerWidth', { value: originalWidth, configurable: true, writable: true }) + } + }) + + it('never crosses the left viewport margin for an oversized popover', () => { + vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(800) + vi.spyOn(HTMLDivElement.prototype, 'getBoundingClientRect').mockReturnValue({ left: 4 } as DOMRect) + const originalWidth = window.innerWidth + Object.defineProperty(window, 'innerWidth', { value: 700, configurable: true, writable: true }) + try { + render() + openList() + const menu = screen.getByRole('list', { name: zh['list.aria'] }) + // max(12 - 4, min(0, 700 - 12 - 800 - 4)) = 8: clamped at the left margin. + expect(menu.style.left).toBe('8px') + } finally { + Object.defineProperty(window, 'innerWidth', { value: originalWidth, configurable: true, writable: true }) + } + }) + it('ignores other keys while open and closes once the roster empties', () => { const settledPair = [ row({ id: 'bash-1' as ActivityId, status: 'completed', finishedAt: 2 }), From 61aadb3abf337875c43f95152a17c7ee9dc8d3ec Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 25 Aug 2026 11:58:43 +0800 Subject: [PATCH 004/100] feat(activity): one session-header task list joining jobs with their activities MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Browser acceptance of the activity panel surfaced the product problem: a background bash registers in both planes, so the header grew two near- identical popovers — "background jobs" with lifecycle and duration, "activities" with live output — listing the same work twice. The service planes stay orthogonal (jobs: model-visible control with a consuming read cursor; activities: transient non-consuming observation). The join happens per row in the UI projection instead: - dsh-client-ui-activity renders the single merged "tasks" list. Each jobsBySession row joins the activity carrying its correlation.jobId — the job supplies identity, lifecycle (stopping exists only there), duration, and the model-visible detail; the activity supplies the expandable live-output panel. Standalone activities (workflow runs) keep their own rows; without the activity registry, job rows still render and the control degrades to the old job list exactly. - dsh-client-ui-jobs is deleted (pre-release, no shim); the merged entry takes its slot order. The job locale namespace folds into activity. - User-facing copy says "task" (任务): N tasks running / N 个任务进行中. - Hierarchy: live rows first as two lines (label over kind badge and status, ticking duration), a Finished divider when both sections exist, settled rows compacted to one de-emphasized line, and the output panel hangs behind a spine under its row. Deliberately not joined: subagent rows stay bare (the subagent panel is their surface) and foreground commands stay in tool cards. Both web e2e scenarios now assert one Tasks list; the background-job scenario's row gained a live-output panel, proving the join end to end. Agent Note: 2026-08-25-unified-task-list. --- ...08-08-web-background-job-display.i18n.yaml | 4 +- .../2026-08-08-web-background-job-display.md | 2 +- ...026-08-08-web-background-job-display.zh.md | 2 +- .../2026-08-25-unified-task-list.i18n.yaml | 6 + .../feature/2026-08-25-unified-task-list.md | 31 ++ .../2026-08-25-unified-task-list.zh.md | 31 ++ apps/web/tests/background-job-list.e2e.ts | 6 +- apps/web/tests/live-activity-stream.e2e.ts | 4 +- .../background-job-list/running.expected.md | 7 +- .../background-job-list/settled.expected.md | 7 +- .../live-activity-stream/settled.expected.md | 4 +- .../streaming.expected.md | 4 +- docs/config-catalog.i18n.yaml | 4 +- docs/config-catalog.md | 1 - docs/config-catalog.zh.md | 1 - docs/module-graph.i18n.yaml | 4 +- docs/module-graph.md | 57 +++- docs/module-graph.zh.md | 57 +++- packages/bundle/web-app/cordis.patch.yml | 3 - packages/bundle/web-app/package.json | 1 - packages/client/README.i18n.yaml | 4 +- packages/client/README.md | 2 +- packages/client/README.zh.md | 2 +- packages/client/ui-activity/README.i18n.yaml | 4 +- packages/client/ui-activity/README.md | 9 +- packages/client/ui-activity/README.zh.md | 9 +- packages/client/ui-activity/package.json | 4 +- .../src/client/ActivityListAction.module.css | 61 +++- .../src/client/ActivityListAction.tsx | 310 ++++++++++++++---- .../client/ui-activity/src/client/index.ts | 18 +- .../client/ui-activity/src/client/locales.ts | 34 +- .../activity-list-action.client.spec.tsx | 104 +++++- .../tests/browser-plugin.client.spec.ts | 3 +- packages/client/ui-activity/tsconfig.json | 1 + packages/client/ui-jobs/README.i18n.yaml | 6 - packages/client/ui-jobs/README.md | 24 -- packages/client/ui-jobs/README.zh.md | 24 -- packages/client/ui-jobs/package.json | 76 ----- .../src/client/JobListAction.module.css | 125 ------- .../ui-jobs/src/client/JobListAction.tsx | 183 ----------- packages/client/ui-jobs/src/client/index.ts | 42 --- packages/client/ui-jobs/src/client/locales.ts | 45 --- packages/client/ui-jobs/src/css-modules.d.ts | 6 - packages/client/ui-jobs/src/index.ts | 9 - packages/client/ui-jobs/src/invariant.ts | 32 -- .../tests/browser-plugin.client.spec.ts | 101 ------ .../tests/job-list-action.client.spec.tsx | 241 -------------- packages/client/ui-jobs/tsconfig.json | 39 --- packages/client/ui-jobs/tsdown.config.ts | 3 - .../src/client/slot-catalog.ts | 1 - pnpm-lock.yaml | 45 +-- .../verify-package-readme-model-experience.ts | 1 - tsconfig.base.json | 1 - tsconfig.client.json | 1 - 54 files changed, 639 insertions(+), 1167 deletions(-) create mode 100644 .agents/notes/implemented/feature/2026-08-25-unified-task-list.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-08-25-unified-task-list.md create mode 100644 .agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md delete mode 100644 packages/client/ui-jobs/README.i18n.yaml delete mode 100644 packages/client/ui-jobs/README.md delete mode 100644 packages/client/ui-jobs/README.zh.md delete mode 100644 packages/client/ui-jobs/package.json delete mode 100644 packages/client/ui-jobs/src/client/JobListAction.module.css delete mode 100644 packages/client/ui-jobs/src/client/JobListAction.tsx delete mode 100644 packages/client/ui-jobs/src/client/index.ts delete mode 100644 packages/client/ui-jobs/src/client/locales.ts delete mode 100644 packages/client/ui-jobs/src/css-modules.d.ts delete mode 100644 packages/client/ui-jobs/src/index.ts delete mode 100644 packages/client/ui-jobs/src/invariant.ts delete mode 100644 packages/client/ui-jobs/tests/browser-plugin.client.spec.ts delete mode 100644 packages/client/ui-jobs/tests/job-list-action.client.spec.tsx delete mode 100644 packages/client/ui-jobs/tsconfig.json delete mode 100644 packages/client/ui-jobs/tsdown.config.ts diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml index 1ee7b9dfc3..9b64d73885 100644 --- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.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 .agents/notes/implemented/feature/2026-08-08-web-background-job-display.md -2026-08-08-web-background-job-display.md: 8da6c2fd914bf07cfa7d3545cff1e42552c69d27 -2026-08-08-web-background-job-display.zh.md: 0e05ef9d2fcd8193c661f471b5f7b9a84891f98a +2026-08-08-web-background-job-display.md: 23074b5d38cdab8c45925c75a7d0b851f7be2ece +2026-08-08-web-background-job-display.zh.md: 06645267ee8afadf284b7654b0cd4a672fe7e4b4 diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md index 8da6c2fd91..23074b5d38 100644 --- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md +++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md @@ -87,7 +87,7 @@ Two replacement points keep it honest. Each control-stream generation clears the ### The header action -[`@deepseek-ai/dsh-client-ui-jobs`](../../../../packages/client/ui-jobs/README.md) registers one entry in `conversation.session.header.actions`, ordered after the subagent catalog. Its own README owns the presentation contract; the decisions worth recording here are that the control does not render at all until the session has a task, that the live badge is omitted at zero so a history-only session keeps a quiet entry point, and that settled rows stay visible because a failed task's `detail` is the only place its failure is legible. +`@deepseek-ai/dsh-client-ui-jobs` (since merged into `dsh-client-ui-activity`) registers one entry in `conversation.session.header.actions`, ordered after the subagent catalog. Its own README owns the presentation contract; the decisions worth recording here are that the control does not render at all until the session has a task, that the live badge is omitted at zero so a history-only session keeps a quiet entry point, and that settled rows stay visible because a failed task's `detail` is the only place its failure is legible. A running one-shot background subagent therefore appears both there and in the subagent catalog. The two answer different questions — the catalog navigates into the child's transcript, this list is the only handle a cancellation can ever attach to — and suppressing `kind: 'subagent'` here would leave the cancellation phase with no entry point for exactly those tasks. diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md index 0e05ef9d2f..06645267ee 100644 --- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md +++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md @@ -87,7 +87,7 @@ abstract onJobsChanged(listener: JobsChangedListener): () => void ### header 入口 -[`@deepseek-ai/dsh-client-ui-jobs`](../../../../packages/client/ui-jobs/README.zh.md) 在 `conversation.session.header.actions` 注册一个条目,排在 subagent 目录之后。呈现契约归它自己的 README;值得记在这里的决策是:会话没有任务时控件根本不渲染;活跃角标为零时省略,让只剩历史的会话保留一个安静的入口;终态行保持可见,因为失败任务的 `detail` 是其失败唯一可读之处。 +`@deepseek-ai/dsh-client-ui-jobs`(后并入 `dsh-client-ui-activity`) 在 `conversation.session.header.actions` 注册一个条目,排在 subagent 目录之后。呈现契约归它自己的 README;值得记在这里的决策是:会话没有任务时控件根本不渲染;活跃角标为零时省略,让只剩历史的会话保留一个安静的入口;终态行保持可见,因为失败任务的 `detail` 是其失败唯一可读之处。 因此一个运行中的一次性后台 subagent 会同时出现在那里和 subagent 目录里。两者回答不同的问题——目录负责进入子会话的 transcript,而这个列表是中断能力唯一可能附着的句柄——在这里屏蔽 `kind: 'subagent'` 会让中断那一期恰好对这批任务没有入口。 diff --git a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.i18n.yaml b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.i18n.yaml new file mode 100644 index 0000000000..031f01691a --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.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 .agents/notes/implemented/feature/2026-08-25-unified-task-list.md +2026-08-25-unified-task-list.md: 9ce3e6d2b066a94ee738880f69b0ddf718a10b02 +2026-08-25-unified-task-list.zh.md: ab224fd082fb8d6408449716e68e6df6c648a281 diff --git a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.md b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.md new file mode 100644 index 0000000000..9ce3e6d2b0 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.md @@ -0,0 +1,31 @@ +# Agent Note: One session-header task list — jobs joined with activities in the UI projection only + +Status: implemented + +English | [中文](2026-08-25-unified-task-list.zh.md) + +## Problem + +The [activity observation seam](2026-08-24-activity-observation-seam.md) shipped its Web surface as a second session-header button beside the [background-job list](2026-08-08-web-background-job-display.md). A background bash run registers in both planes — `ctx.jobs` for control and `ctx.activities` for observation — so the same work rendered twice: once in "background jobs" with lifecycle and duration, once in "activities" with expandable live output. Two near-identical popovers with different names for overlapping row sets read as a product accident, and the flat activity rows (live and settled interleaved, single-line, no duration) had no visual hierarchy. + +## Decision + +The service planes stay orthogonal; the join happens once, per row, in the UI projection. + +- **`ctx.jobs` and `ctx.activities` remain separate services.** Jobs are the control plane: model-visible ids, a consuming `readOutput` cursor the model drains, `stopping`, `kill`, and the `reported` completion-notice contract. Activities are the transient observation plane: non-consuming absolute offsets, invisible to the model, gone on restart. Merging the services would force one registry to carry both a consuming and a non-consuming cursor and would blur the "model-visible ⟺ logged" line for a plane designed to stay off the session log. +- **`dsh-client-ui-activity` renders the single merged list; `dsh-client-ui-jobs` is deleted** (pre-release, no compatibility shim), and the merged entry takes the job list's slot order. Each `jobsBySession` row is joined with the activity carrying its `correlation.jobId`: the job supplies identity, lifecycle (`stopping` exists only there), duration, and the model-visible `detail`; the activity supplies the expandable output panel. An activity without a job (a workflow run) keeps its own row; an activity whose job is not in the projection is not dropped. Without the activity registry, job rows still render — they just offer no panel, so the merged control degrades to exactly the old job list. +- **User-facing vocabulary is "task" (任务)** — `N tasks running` / `N 个任务进行中` — because every row is running work to the user, while "background job" excludes workflow runs and "activity" names the internal plane, not the user concept. The dictionary namespace and package names stay `activity`: internal names follow the naming ledger, not display copy. +- **Hierarchy**: live rows first (label over a kind-badge-and-status second line, ticking duration), then a "Finished" divider only when both sections exist, then settled rows compacted to one de-emphasized line. Rows without an observable activity render as static rows with no expansion affordance. + +Deliberately not joined: subagent delegation rows stay bare job rows (the subagent panel is their surface), and foreground commands stay in their tool cards — neither gains an activity producer. + +## Alternatives rejected + +- **Merge the services** — rejected for the cursor-semantics and model-visibility reasons above. +- **Keep the job list and bolt output onto it** — leaves workflow runs (activities without jobs) homeless, forcing a second list to survive anyway. + +## Consequences + +- The two web e2e scenarios (`background-job-list`, `live-activity-stream`) now assert one "Tasks" list; the job-list scenario's row gained a live-output panel, which is the join working end to end. +- A human kill control on live rows is still blocked on the jobs `reported` contract question recorded in the job-display note. +- The `job` locale namespace is gone with its package; `activity` owns the merged copy including the duration vocabulary. diff --git a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md new file mode 100644 index 0000000000..ab224fd082 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md @@ -0,0 +1,31 @@ +# Agent Note:会话头部单一任务列表——jobs 与 activity 只在 UI 投影层合并 + +状态:implemented + +[English](2026-08-25-unified-task-list.md) | 中文 + +## 问题 + +[activity 观察面](2026-08-24-activity-observation-seam.zh.md)的 Web 呈现落地为[后台任务列表](2026-08-08-web-background-job-display.zh.md)旁边的第二个会话头部按钮。一次后台 bash 会同时登记在两个面里——`ctx.jobs` 负责控制、`ctx.activities` 负责观察——于是同一份工作渲染了两次:一次在"后台任务"里带生命周期与时长,一次在"活动"里带可展开的实时输出。两个行集合高度重叠、名字却不同的近似弹层,读起来像产品事故;而活动列表的扁平行(live 与 settled 混排、单行、无时长)也缺乏视觉层次。 + +## 决策 + +服务面保持正交;合并只在 UI 投影层逐行发生一次。 + +- **`ctx.jobs` 与 `ctx.activities` 仍是两个服务。** jobs 是控制面:模型可见的 id、模型消耗式的 `readOutput` 游标、`stopping`、`kill` 与 `reported` 完成通知契约。activity 是瞬态观察面:非消耗式绝对偏移、模型不可见、重启即无。合并服务会迫使一个注册表同时携带消耗式与非消耗式两种游标,并模糊这个刻意不进 session log 的面与"模型可见 ⟺ 已记录"不变量的边界。 +- **`dsh-client-ui-activity` 渲染唯一的合并列表;`dsh-client-ui-jobs` 删除**(预发布阶段,不留兼容层),合并入口占用原 job 列表的 slot 顺位。每个 `jobsBySession` 行与携带其 `correlation.jobId` 的 activity 逐行 join:job 提供身份、生命周期(`stopping` 只存在于此)、时长与模型可见 `detail`;activity 提供可展开的输出面板。没有 job 的 activity(workflow 运行)保留自己的行;job 不在投影里的 activity 也不会被丢弃。没有 activity 注册表时 job 行照常渲染——只是没有面板,合并控件退化为与旧 job 列表完全等价。 +- **用户可见词汇统一为"任务"(task)**——`N 个任务进行中` / `N tasks running`——因为对用户而言每一行都是在跑的工作,而"后台任务"排除了 workflow 运行、"活动"命名的是内部面而非用户概念。词典命名空间与包名保持 `activity`:内部名遵循命名台账,不跟随展示文案。 +- **层次**:进行中的行在前(命令为主行、kind 徽章加状态为副行、时长每秒跳动),两段都存在时插入"已结束"分节线,已结束的行折为降权单行。没有可观察 activity 的行渲染为无展开交互的静态行。 + +刻意不合并的:subagent 委托行保持裸 job 行(subagent 面板是它的呈现面),前台命令留在工具卡片里——两者都不接活动生产者。 + +## 已否决的替代方案 + +- **合并服务层**——因上述游标语义与模型可见性理由否决。 +- **保留 job 列表、把输出挂上去**——workflow 运行(无 job 的 activity)无处安放,第二个列表终究得活下来。 + +## 后果 + +- 两个 web e2e 场景(`background-job-list`、`live-activity-stream`)现在断言同一个"任务"列表;job 场景的行获得了实时输出面板,这正是 join 端到端生效的证据。 +- live 行上的人工 kill 控件仍被 job-display note 记录的 jobs `reported` 契约问题阻塞。 +- `job` 词典命名空间随包一起消失;`activity` 拥有合并后的全部文案,包括时长词汇。 diff --git a/apps/web/tests/background-job-list.e2e.ts b/apps/web/tests/background-job-list.e2e.ts index b0fdc62ddb..0e1061ba09 100644 --- a/apps/web/tests/background-job-list.e2e.ts +++ b/apps/web/tests/background-job-list.e2e.ts @@ -80,7 +80,7 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => { it('shows a running background job in the session header without a refresh', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-background-job-running')) // Polling for zero would pass at t=0 before delivery and prove nothing. - const trigger = page.getByRole('button', { name: '1 background job running' }) + const trigger = page.getByRole('button', { name: '1 task running' }) expect(await trigger.count()).toBe(0) const started = await scaffold.ctx.tools.execute({ @@ -97,7 +97,7 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => { await trigger.waitFor({ timeout: 15_000 }) await trigger.click() - const row = page.getByRole('list', { name: 'Background jobs' }).getByRole('listitem').first() + const row = page.getByRole('list', { name: 'Tasks' }).getByRole('listitem').first() await row.waitFor({ timeout: 10_000 }) await expect.poll(() => row.textContent()).toContain(COMMAND) @@ -111,7 +111,7 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-background-job-settled')) expect(scaffold.ctx.jobs.kill(jobId, agent, 'web e2e cancellation')).toBe('requested') - const idle = page.getByRole('button', { name: '1 background job' }) + const idle = page.getByRole('button', { name: '1 task' }) await idle.waitFor({ timeout: 20_000 }) const snapshot = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd) diff --git a/apps/web/tests/live-activity-stream.e2e.ts b/apps/web/tests/live-activity-stream.e2e.ts index 750e1697f3..b8a702e738 100644 --- a/apps/web/tests/live-activity-stream.e2e.ts +++ b/apps/web/tests/live-activity-stream.e2e.ts @@ -80,7 +80,7 @@ describe.skipIf(MODE === 'record')('web e2e: live activity stream', () => { it('streams a running background command\'s real output into the expanded panel', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-live-activity-streaming')) - const trigger = page.getByRole('button', { name: '1 live activity' }) + const trigger = page.getByRole('button', { name: '1 task running' }) expect(await trigger.count()).toBe(0) const started = await scaffold.ctx.tools.execute({ @@ -118,7 +118,7 @@ describe.skipIf(MODE === 'record')('web e2e: live activity stream', () => { // Settlement arrives on the observation stream itself, so the open panel // flips without any further interaction; the roster trigger follows. - const idle = page.getByRole('button', { name: '1 activity' }) + const idle = page.getByRole('button', { name: '1 task' }) await idle.waitFor({ timeout: 20_000 }) await page.getByText('streamed-marker-line').waitFor({ timeout: 10_000 }) diff --git a/apps/web/tests/snapshots/background-job-list/running.expected.md b/apps/web/tests/snapshots/background-job-list/running.expected.md index 62a413bf4c..95f226f226 100644 --- a/apps/web/tests/snapshots/background-job-list/running.expected.md +++ b/apps/web/tests/snapshots/background-job-list/running.expected.md @@ -1,2 +1,5 @@ -- list "Background jobs": - - listitem: bash sleep 45 running {{duration}} +- list "Tasks": + - listitem: + - button "Show live output of sleep 45": + - text: sleep 45 {{duration}} bash running + - img diff --git a/apps/web/tests/snapshots/background-job-list/settled.expected.md b/apps/web/tests/snapshots/background-job-list/settled.expected.md index cc4bcfef74..3343ae521c 100644 --- a/apps/web/tests/snapshots/background-job-list/settled.expected.md +++ b/apps/web/tests/snapshots/background-job-list/settled.expected.md @@ -1,2 +1,5 @@ -- list "Background jobs": - - listitem: "bash sleep 45 signal: SIGTERM {{duration}}" +- list "Tasks": + - listitem: + - button "Show live output of sleep 45": + - text: "bash sleep 45 signal: SIGTERM {{duration}}" + - img diff --git a/apps/web/tests/snapshots/live-activity-stream/settled.expected.md b/apps/web/tests/snapshots/live-activity-stream/settled.expected.md index 7ffec602cb..2090dca51d 100644 --- a/apps/web/tests/snapshots/live-activity-stream/settled.expected.md +++ b/apps/web/tests/snapshots/live-activity-stream/settled.expected.md @@ -1,7 +1,7 @@ -- list "Live activities": +- list "Tasks": - listitem: - button "Hide live output of printf 'streamed-%s\\n' marker-line; sleep 45" [expanded]: - - text: "bash printf 'streamed-%s\\n' marker-line; sleep 45 signal: SIGTERM" + - text: "bash printf 'streamed-%s\\n' marker-line; sleep 45 signal: SIGTERM {{duration}}" - img - text: done $ printf 'streamed-%s\n' marker-line; sleep 45 - button "Copy" diff --git a/apps/web/tests/snapshots/live-activity-stream/streaming.expected.md b/apps/web/tests/snapshots/live-activity-stream/streaming.expected.md index fd536ef430..ea906239aa 100644 --- a/apps/web/tests/snapshots/live-activity-stream/streaming.expected.md +++ b/apps/web/tests/snapshots/live-activity-stream/streaming.expected.md @@ -1,7 +1,7 @@ -- list "Live activities": +- list "Tasks": - listitem: - button "Hide live output of printf 'streamed-%s\\n' marker-line; sleep 45" [expanded]: - - text: bash printf 'streamed-%s\n' marker-line; sleep 45 running + - text: printf 'streamed-%s\n' marker-line; sleep 45 {{duration}} bash running - img - text: running $ printf 'streamed-%s\n' marker-line; sleep 45 - button "Copy" diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index 6c2e824a55..43c0fd7cd0 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.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 docs/config-catalog.md -config-catalog.md: 0bf883bbfde80377602be90bd913c32f1b320f63 -config-catalog.zh.md: 381319465dab9dafeecaacf704caba8bab7455f3 +config-catalog.md: f6c751b0942144f29a648491381fecd307e2ed8f +config-catalog.zh.md: ac16ec94533b6c818f2abb00d5ed96b3d81a07ac diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 0bf883bbfd..f6c751b094 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -3355,7 +3355,6 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co - `@deepseek-ai/dsh-client-ui-directory-picker-native` ([`packages/client/ui-directory-picker-native/src/index.ts`](../packages/client/ui-directory-picker-native/src/index.ts)) - `@deepseek-ai/dsh-client-ui-goal` ([`packages/client/ui-goal/src/index.ts`](../packages/client/ui-goal/src/index.ts)) - `@deepseek-ai/dsh-client-ui-input-trigger` ([`packages/client/ui-input-trigger/src/index.ts`](../packages/client/ui-input-trigger/src/index.ts)) -- `@deepseek-ai/dsh-client-ui-jobs` ([`packages/client/ui-jobs/src/index.ts`](../packages/client/ui-jobs/src/index.ts)) - `@deepseek-ai/dsh-client-ui-layout` ([`packages/client/ui-layout/src/index.ts`](../packages/client/ui-layout/src/index.ts)) - `@deepseek-ai/dsh-client-ui-message-feedback` ([`packages/client/ui-message-feedback/src/index.ts`](../packages/client/ui-message-feedback/src/index.ts)) - `@deepseek-ai/dsh-client-ui-model-selection` ([`packages/client/ui-model-selection/src/index.ts`](../packages/client/ui-model-selection/src/index.ts)) diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index 381319465d..ac16ec9453 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -3357,7 +3357,6 @@ export interface Config { - `@deepseek-ai/dsh-client-ui-directory-picker-native`([`packages/client/ui-directory-picker-native/src/index.ts`](../packages/client/ui-directory-picker-native/src/index.ts)) - `@deepseek-ai/dsh-client-ui-goal`([`packages/client/ui-goal/src/index.ts`](../packages/client/ui-goal/src/index.ts)) - `@deepseek-ai/dsh-client-ui-input-trigger`([`packages/client/ui-input-trigger/src/index.ts`](../packages/client/ui-input-trigger/src/index.ts)) -- `@deepseek-ai/dsh-client-ui-jobs`([`packages/client/ui-jobs/src/index.ts`](../packages/client/ui-jobs/src/index.ts)) - `@deepseek-ai/dsh-client-ui-layout`([`packages/client/ui-layout/src/index.ts`](../packages/client/ui-layout/src/index.ts)) - `@deepseek-ai/dsh-client-ui-message-feedback`([`packages/client/ui-message-feedback/src/index.ts`](../packages/client/ui-message-feedback/src/index.ts)) - `@deepseek-ai/dsh-client-ui-model-selection`([`packages/client/ui-model-selection/src/index.ts`](../packages/client/ui-model-selection/src/index.ts)) diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml index a467f4aea6..52cd807255 100644 --- a/docs/module-graph.i18n.yaml +++ b/docs/module-graph.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 docs/module-graph.md -module-graph.md: 9d192404f4949bcf6e5c4222f0b898cc52362bd8 -module-graph.zh.md: bbdfd5642238644939fd08c02b9786310bad63e2 +module-graph.md: 8664f078fdcec3b8a2474bdf62d20fbb6dfe9525 +module-graph.zh.md: 3975d691877e2e5aeaade32a5530fd05e7d4acbb diff --git a/docs/module-graph.md b/docs/module-graph.md index 9d192404f4..8664f078fd 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -104,7 +104,12 @@ flowchart TD subgraph group_acp["packages/acp"] pkg_acp["acp"] end + subgraph group_activity["packages/activity"] + pkg_activity["activity"] + pkg_activity_local["activity-local"] + end subgraph group_api["packages/api"] + pkg_api_activity_controller["api-activity-controller"] pkg_api_gateway["api-gateway"] pkg_api_remotes["api-remotes"] pkg_api_session_controller["api-session-controller"] @@ -132,6 +137,7 @@ flowchart TD pkg_client_locale["client-locale"] pkg_client_modules["client-modules"] pkg_client_store["client-store"] + pkg_client_ui_activity["client-ui-activity"] pkg_client_ui_agent_preset["client-ui-agent-preset"] pkg_client_ui_approval["client-ui-approval"] pkg_client_ui_attachment["client-ui-attachment"] @@ -144,7 +150,6 @@ flowchart TD pkg_client_ui_directory_picker_native["client-ui-directory-picker-native"] pkg_client_ui_goal["client-ui-goal"] pkg_client_ui_input_trigger["client-ui-input-trigger"] - pkg_client_ui_jobs["client-ui-jobs"] pkg_client_ui_layout["client-ui-layout"] pkg_client_ui_message_feedback["client-ui-message-feedback"] pkg_client_ui_model_selection["client-ui-model-selection"] @@ -675,6 +680,12 @@ flowchart TD pkg_hook_protocol --> pkg_invariants pkg_hook_protocol --> pkg_session pkg_hook_protocol --> pkg_shell + pkg_activity --> pkg_agent + pkg_activity --> pkg_brand + pkg_activity --> pkg_invariants + pkg_activity --> pkg_jobs + pkg_activity --> pkg_llm + pkg_activity --> pkg_session pkg_headless --> pkg_agent pkg_headless --> pkg_agent_default_model pkg_headless --> pkg_invariants @@ -829,6 +840,10 @@ flowchart TD pkg_hooks_codex --> pkg_session pkg_hooks_codex --> pkg_session_persistence pkg_hooks_codex --> pkg_tools + pkg_activity_local --> pkg_activity + pkg_activity_local --> pkg_agent + pkg_activity_local --> pkg_invariants + pkg_activity_local --> pkg_scope pkg_command_compact --> pkg_commands pkg_command_compact --> pkg_compaction pkg_command_compact --> pkg_invariants @@ -965,6 +980,7 @@ flowchart TD pkg_llm_replay --> pkg_invariants pkg_llm_replay --> pkg_llm pkg_llm_replay --> pkg_session + pkg_tool_workflow --> pkg_activity pkg_tool_workflow --> pkg_agent pkg_tool_workflow --> pkg_invariants pkg_tool_workflow --> pkg_llm @@ -1026,6 +1042,7 @@ flowchart TD pkg_tool_cordis --> pkg_tools pkg_host_apiproxy --> pkg_agent_presets pkg_host_apiproxy --> pkg_invariants + pkg_tool_bash --> pkg_activity pkg_tool_bash --> pkg_agent pkg_tool_bash --> pkg_invariants pkg_tool_bash --> pkg_jobs @@ -1037,6 +1054,7 @@ flowchart TD pkg_tool_bash --> pkg_system_prompt pkg_tool_bash --> pkg_tools pkg_tool_bash --> pkg_user_approval + pkg_tool_pwsh --> pkg_activity pkg_tool_pwsh --> pkg_agent pkg_tool_pwsh --> pkg_invariants pkg_tool_pwsh --> pkg_jobs @@ -1242,6 +1260,16 @@ flowchart TD pkg_subagent_dsh_sdk --> pkg_session pkg_subagent_dsh_sdk --> pkg_subagent pkg_subagent_dsh_sdk --> pkg_subprocess + pkg_api_activity_controller --> pkg_activity + pkg_api_activity_controller --> pkg_agent + pkg_api_activity_controller --> pkg_api_gateway + pkg_api_activity_controller --> pkg_client_connection + pkg_api_activity_controller --> pkg_client_store + pkg_api_activity_controller --> pkg_invariants + pkg_api_activity_controller --> pkg_jobs + pkg_api_activity_controller --> pkg_llm + pkg_api_activity_controller --> pkg_session + pkg_api_activity_controller --> pkg_typert_protocol pkg_api_session_controller --> pkg_agent pkg_api_session_controller --> pkg_agent_default_model pkg_api_session_controller --> pkg_agent_presets @@ -1272,6 +1300,7 @@ flowchart TD pkg_api_workspace_controller --> pkg_typert_protocol pkg_api_workspace_controller --> pkg_workspace pkg_api_remotes --> pkg_agent_presets + pkg_api_remotes --> pkg_api_activity_controller pkg_api_remotes --> pkg_api_gateway pkg_api_remotes --> pkg_api_session_controller pkg_api_remotes --> pkg_api_workspace_controller @@ -1382,6 +1411,13 @@ flowchart TD pkg_client_ui_workspace --> pkg_invariants pkg_client_ui_workspace --> pkg_session pkg_client_ui_workspace --> pkg_util_workspace_path + pkg_client_ui_activity --> pkg_api_activity_controller + pkg_client_ui_activity --> pkg_api_session_controller + pkg_client_ui_activity --> pkg_client_locale + pkg_client_ui_activity --> pkg_client_ui_conversation + pkg_client_ui_activity --> pkg_client_ui_renderer + pkg_client_ui_activity --> pkg_client_ui_session + pkg_client_ui_activity --> pkg_invariants pkg_client_ui_agent_preset --> pkg_api_remotes pkg_client_ui_agent_preset --> pkg_api_session_controller pkg_client_ui_agent_preset --> pkg_client_connection @@ -1423,12 +1459,6 @@ flowchart TD pkg_client_ui_input_trigger --> pkg_file_reference pkg_client_ui_input_trigger --> pkg_invariants pkg_client_ui_input_trigger --> pkg_session - pkg_client_ui_jobs --> pkg_api_session_controller - pkg_client_ui_jobs --> pkg_client_locale - pkg_client_ui_jobs --> pkg_client_ui_conversation - pkg_client_ui_jobs --> pkg_client_ui_renderer - pkg_client_ui_jobs --> pkg_client_ui_session - pkg_client_ui_jobs --> pkg_invariants pkg_client_ui_plan --> pkg_api_remotes pkg_client_ui_plan --> pkg_client_locale pkg_client_ui_plan --> pkg_client_ui_conversation @@ -1757,6 +1787,7 @@ flowchart TD | [`fs-observation-policy`](../packages/fs/fs-observation-policy) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`skill-filesystem`](../packages/skill/skill-filesystem) | `skill` | [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`skill`](../packages/skill/skill) | | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`shell`](../packages/shell/shell) | +| [`activity`](../packages/activity/activity) | `activity` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`compaction`](../packages/compaction/compaction) | `compaction` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`shell`](../packages/shell/shell) | @@ -1783,6 +1814,7 @@ flowchart TD | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) | | [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions) | | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) | +| [`activity-local`](../packages/activity/activity-local) | `activity` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`scope`](../packages/core/scope) | | [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`agent-instructions`](../packages/context/agent-instructions) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | | [`file-reference-local`](../packages/context/file-reference-local) | `context` | [`agent`](../packages/core/agent), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | @@ -1807,7 +1839,7 @@ flowchart TD | [`tool-terminal`](../packages/terminal/tool-terminal) | `terminal` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`system-prompt`](../packages/core/system-prompt), [`terminal`](../packages/terminal/terminal), [`tools`](../packages/core/tools) | | [`agent-loop-testkit`](../packages/test-support/agent-loop-testkit) | `test-support` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | -| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | +| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | | [`plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek) | `llm` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title), [`tool-todo`](../packages/todo/tool-todo) | @@ -1816,8 +1848,8 @@ flowchart TD | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) | | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | -| [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | +| [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | +| [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`webhook`](../packages/webhook/webhook) | `webhook` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`workspace`](../packages/workspace/workspace) | | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | `subagent` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | @@ -1846,9 +1878,10 @@ flowchart TD | [`sdk-client`](../packages/sdk/client) | `sdk` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session) | | [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) | +| [`api-activity-controller`](../packages/api/activity-controller) | `api` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`api-gateway`](../packages/api/gateway), [`client-connection`](../packages/client/connection), [`client-store`](../packages/client/store), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | | [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`client-connection`](../packages/client/connection), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | | [`api-workspace-controller`](../packages/api/workspace-controller) | `api` | [`api-gateway`](../packages/api/gateway), [`client-connection`](../packages/client/connection), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol), [`workspace`](../packages/workspace/workspace) | -| [`api-remotes`](../packages/api/remotes) | `api` | [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`commands`](../packages/interaction/commands), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`credentials`](../packages/credentials/credentials), [`file-reference`](../packages/context/file-reference), [`goal`](../packages/goal/goal), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-reference`](../packages/context/session-reference), [`settings`](../packages/settings/settings), [`user-approval`](../packages/interaction/user-approval), [`user-questions`](../packages/interaction/user-questions) | +| [`api-remotes`](../packages/api/remotes) | `api` | [`agent-presets`](../packages/preset/agent-presets), [`api-activity-controller`](../packages/api/activity-controller), [`api-gateway`](../packages/api/gateway), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`commands`](../packages/interaction/commands), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`credentials`](../packages/credentials/credentials), [`file-reference`](../packages/context/file-reference), [`goal`](../packages/goal/goal), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-reference`](../packages/context/session-reference), [`settings`](../packages/settings/settings), [`user-approval`](../packages/interaction/user-approval), [`user-questions`](../packages/interaction/user-questions) | | [`client-ui-session`](../packages/client/ui-session) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-ui-renderer`](../packages/client/ui-renderer), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) | | [`client-locale`](../packages/client/locale) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) | @@ -1861,13 +1894,13 @@ flowchart TD | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`client-locale`](../packages/client/locale), [`client-ui-layout`](../packages/client/ui-layout), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-workspace`](../packages/client/ui-workspace), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`util-crypto`](../packages/util/crypto), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`api-workspace-controller`](../packages/api/workspace-controller), [`client-locale`](../packages/client/locale), [`client-ui-layout`](../packages/client/ui-layout), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`util-workspace-path`](../packages/util/workspace-path) | +| [`client-ui-activity`](../packages/client/ui-activity) | `client` | [`api-activity-controller`](../packages/api/activity-controller), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`client-ui-approval`](../packages/client/ui-approval) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | | [`client-ui-brand-official`](../packages/client/ui-brand-official) | `client` | [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native) | `client` | [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | -| [`client-ui-jobs`](../packages/client/ui-jobs) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session) | | [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) | | [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`agent`](../packages/core/agent), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index bbdfd56422..3975d69187 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -106,7 +106,12 @@ flowchart TD subgraph group_acp["packages/acp"] pkg_acp["acp"] end + subgraph group_activity["packages/activity"] + pkg_activity["activity"] + pkg_activity_local["activity-local"] + end subgraph group_api["packages/api"] + pkg_api_activity_controller["api-activity-controller"] pkg_api_gateway["api-gateway"] pkg_api_remotes["api-remotes"] pkg_api_session_controller["api-session-controller"] @@ -134,6 +139,7 @@ flowchart TD pkg_client_locale["client-locale"] pkg_client_modules["client-modules"] pkg_client_store["client-store"] + pkg_client_ui_activity["client-ui-activity"] pkg_client_ui_agent_preset["client-ui-agent-preset"] pkg_client_ui_approval["client-ui-approval"] pkg_client_ui_attachment["client-ui-attachment"] @@ -146,7 +152,6 @@ flowchart TD pkg_client_ui_directory_picker_native["client-ui-directory-picker-native"] pkg_client_ui_goal["client-ui-goal"] pkg_client_ui_input_trigger["client-ui-input-trigger"] - pkg_client_ui_jobs["client-ui-jobs"] pkg_client_ui_layout["client-ui-layout"] pkg_client_ui_message_feedback["client-ui-message-feedback"] pkg_client_ui_model_selection["client-ui-model-selection"] @@ -677,6 +682,12 @@ flowchart TD pkg_hook_protocol --> pkg_invariants pkg_hook_protocol --> pkg_session pkg_hook_protocol --> pkg_shell + pkg_activity --> pkg_agent + pkg_activity --> pkg_brand + pkg_activity --> pkg_invariants + pkg_activity --> pkg_jobs + pkg_activity --> pkg_llm + pkg_activity --> pkg_session pkg_headless --> pkg_agent pkg_headless --> pkg_agent_default_model pkg_headless --> pkg_invariants @@ -831,6 +842,10 @@ flowchart TD pkg_hooks_codex --> pkg_session pkg_hooks_codex --> pkg_session_persistence pkg_hooks_codex --> pkg_tools + pkg_activity_local --> pkg_activity + pkg_activity_local --> pkg_agent + pkg_activity_local --> pkg_invariants + pkg_activity_local --> pkg_scope pkg_command_compact --> pkg_commands pkg_command_compact --> pkg_compaction pkg_command_compact --> pkg_invariants @@ -967,6 +982,7 @@ flowchart TD pkg_llm_replay --> pkg_invariants pkg_llm_replay --> pkg_llm pkg_llm_replay --> pkg_session + pkg_tool_workflow --> pkg_activity pkg_tool_workflow --> pkg_agent pkg_tool_workflow --> pkg_invariants pkg_tool_workflow --> pkg_llm @@ -1028,6 +1044,7 @@ flowchart TD pkg_tool_cordis --> pkg_tools pkg_host_apiproxy --> pkg_agent_presets pkg_host_apiproxy --> pkg_invariants + pkg_tool_bash --> pkg_activity pkg_tool_bash --> pkg_agent pkg_tool_bash --> pkg_invariants pkg_tool_bash --> pkg_jobs @@ -1039,6 +1056,7 @@ flowchart TD pkg_tool_bash --> pkg_system_prompt pkg_tool_bash --> pkg_tools pkg_tool_bash --> pkg_user_approval + pkg_tool_pwsh --> pkg_activity pkg_tool_pwsh --> pkg_agent pkg_tool_pwsh --> pkg_invariants pkg_tool_pwsh --> pkg_jobs @@ -1244,6 +1262,16 @@ flowchart TD pkg_subagent_dsh_sdk --> pkg_session pkg_subagent_dsh_sdk --> pkg_subagent pkg_subagent_dsh_sdk --> pkg_subprocess + pkg_api_activity_controller --> pkg_activity + pkg_api_activity_controller --> pkg_agent + pkg_api_activity_controller --> pkg_api_gateway + pkg_api_activity_controller --> pkg_client_connection + pkg_api_activity_controller --> pkg_client_store + pkg_api_activity_controller --> pkg_invariants + pkg_api_activity_controller --> pkg_jobs + pkg_api_activity_controller --> pkg_llm + pkg_api_activity_controller --> pkg_session + pkg_api_activity_controller --> pkg_typert_protocol pkg_api_session_controller --> pkg_agent pkg_api_session_controller --> pkg_agent_default_model pkg_api_session_controller --> pkg_agent_presets @@ -1274,6 +1302,7 @@ flowchart TD pkg_api_workspace_controller --> pkg_typert_protocol pkg_api_workspace_controller --> pkg_workspace pkg_api_remotes --> pkg_agent_presets + pkg_api_remotes --> pkg_api_activity_controller pkg_api_remotes --> pkg_api_gateway pkg_api_remotes --> pkg_api_session_controller pkg_api_remotes --> pkg_api_workspace_controller @@ -1384,6 +1413,13 @@ flowchart TD pkg_client_ui_workspace --> pkg_invariants pkg_client_ui_workspace --> pkg_session pkg_client_ui_workspace --> pkg_util_workspace_path + pkg_client_ui_activity --> pkg_api_activity_controller + pkg_client_ui_activity --> pkg_api_session_controller + pkg_client_ui_activity --> pkg_client_locale + pkg_client_ui_activity --> pkg_client_ui_conversation + pkg_client_ui_activity --> pkg_client_ui_renderer + pkg_client_ui_activity --> pkg_client_ui_session + pkg_client_ui_activity --> pkg_invariants pkg_client_ui_agent_preset --> pkg_api_remotes pkg_client_ui_agent_preset --> pkg_api_session_controller pkg_client_ui_agent_preset --> pkg_client_connection @@ -1425,12 +1461,6 @@ flowchart TD pkg_client_ui_input_trigger --> pkg_file_reference pkg_client_ui_input_trigger --> pkg_invariants pkg_client_ui_input_trigger --> pkg_session - pkg_client_ui_jobs --> pkg_api_session_controller - pkg_client_ui_jobs --> pkg_client_locale - pkg_client_ui_jobs --> pkg_client_ui_conversation - pkg_client_ui_jobs --> pkg_client_ui_renderer - pkg_client_ui_jobs --> pkg_client_ui_session - pkg_client_ui_jobs --> pkg_invariants pkg_client_ui_plan --> pkg_api_remotes pkg_client_ui_plan --> pkg_client_locale pkg_client_ui_plan --> pkg_client_ui_conversation @@ -1759,6 +1789,7 @@ flowchart TD | [`fs-observation-policy`](../packages/fs/fs-observation-policy) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`skill-filesystem`](../packages/skill/skill-filesystem) | `skill` | [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`skill`](../packages/skill/skill) | | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`shell`](../packages/shell/shell) | +| [`activity`](../packages/activity/activity) | `activity` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`compaction`](../packages/compaction/compaction) | `compaction` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`shell`](../packages/shell/shell) | @@ -1785,6 +1816,7 @@ flowchart TD | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) | | [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions) | | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) | +| [`activity-local`](../packages/activity/activity-local) | `activity` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`scope`](../packages/core/scope) | | [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`agent-instructions`](../packages/context/agent-instructions) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | | [`file-reference-local`](../packages/context/file-reference-local) | `context` | [`agent`](../packages/core/agent), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | @@ -1809,7 +1841,7 @@ flowchart TD | [`tool-terminal`](../packages/terminal/tool-terminal) | `terminal` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`system-prompt`](../packages/core/system-prompt), [`terminal`](../packages/terminal/terminal), [`tools`](../packages/core/tools) | | [`agent-loop-testkit`](../packages/test-support/agent-loop-testkit) | `test-support` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | -| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | +| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | | [`plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek) | `llm` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title), [`tool-todo`](../packages/todo/tool-todo) | @@ -1818,8 +1850,8 @@ flowchart TD | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) | | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`host-apiproxy`](../packages/host/apiproxy) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | -| [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | +| [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | +| [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`webhook`](../packages/webhook/webhook) | `webhook` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`workspace`](../packages/workspace/workspace) | | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | `subagent` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | @@ -1848,9 +1880,10 @@ flowchart TD | [`sdk-client`](../packages/sdk/client) | `sdk` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session) | | [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | | [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) | +| [`api-activity-controller`](../packages/api/activity-controller) | `api` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`api-gateway`](../packages/api/gateway), [`client-connection`](../packages/client/connection), [`client-store`](../packages/client/store), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | | [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`client-connection`](../packages/client/connection), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | | [`api-workspace-controller`](../packages/api/workspace-controller) | `api` | [`api-gateway`](../packages/api/gateway), [`client-connection`](../packages/client/connection), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol), [`workspace`](../packages/workspace/workspace) | -| [`api-remotes`](../packages/api/remotes) | `api` | [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`commands`](../packages/interaction/commands), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`credentials`](../packages/credentials/credentials), [`file-reference`](../packages/context/file-reference), [`goal`](../packages/goal/goal), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-reference`](../packages/context/session-reference), [`settings`](../packages/settings/settings), [`user-approval`](../packages/interaction/user-approval), [`user-questions`](../packages/interaction/user-questions) | +| [`api-remotes`](../packages/api/remotes) | `api` | [`agent-presets`](../packages/preset/agent-presets), [`api-activity-controller`](../packages/api/activity-controller), [`api-gateway`](../packages/api/gateway), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`commands`](../packages/interaction/commands), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`credentials`](../packages/credentials/credentials), [`file-reference`](../packages/context/file-reference), [`goal`](../packages/goal/goal), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-reference`](../packages/context/session-reference), [`settings`](../packages/settings/settings), [`user-approval`](../packages/interaction/user-approval), [`user-questions`](../packages/interaction/user-questions) | | [`client-ui-session`](../packages/client/ui-session) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-ui-renderer`](../packages/client/ui-renderer), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) | | [`client-locale`](../packages/client/locale) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) | @@ -1863,13 +1896,13 @@ flowchart TD | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`client-locale`](../packages/client/locale), [`client-ui-layout`](../packages/client/ui-layout), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-workspace`](../packages/client/ui-workspace), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`util-crypto`](../packages/util/crypto), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | | [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`api-workspace-controller`](../packages/api/workspace-controller), [`client-locale`](../packages/client/locale), [`client-ui-layout`](../packages/client/ui-layout), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`util-workspace-path`](../packages/util/workspace-path) | +| [`client-ui-activity`](../packages/client/ui-activity) | `client` | [`api-activity-controller`](../packages/api/activity-controller), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`client-ui-approval`](../packages/client/ui-approval) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | | [`client-ui-brand-official`](../packages/client/ui-brand-official) | `client` | [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse) | `client` | [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native) | `client` | [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | -| [`client-ui-jobs`](../packages/client/ui-jobs) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session) | | [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) | | [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`agent`](../packages/core/agent), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml index 9fa12bc33f..7e66b4fafd 100644 --- a/packages/bundle/web-app/cordis.patch.yml +++ b/packages/bundle/web-app/cordis.patch.yml @@ -273,9 +273,6 @@ - id: ui-reference name: '@deepseek-ai/dsh-client-ui-reference' - # Background jobs: the session-header list over the jobsBySession mirror. - - id: ui-jobs - name: '@deepseek-ai/dsh-client-ui-jobs' # Live activities: the session-header roster with on-demand streaming # output panels over the activity feed. diff --git a/packages/bundle/web-app/package.json b/packages/bundle/web-app/package.json index 0837c9f6b1..c829d4a089 100644 --- a/packages/bundle/web-app/package.json +++ b/packages/bundle/web-app/package.json @@ -68,7 +68,6 @@ "@deepseek-ai/dsh-client-ui-directory-picker-native": "workspace:^", "@deepseek-ai/dsh-client-ui-goal": "workspace:^", "@deepseek-ai/dsh-client-ui-input-trigger": "workspace:^", - "@deepseek-ai/dsh-client-ui-jobs": "workspace:^", "@deepseek-ai/dsh-client-ui-layout": "workspace:^", "@deepseek-ai/dsh-client-ui-message-feedback": "workspace:^", "@deepseek-ai/dsh-client-ui-model-selection": "workspace:^", diff --git a/packages/client/README.i18n.yaml b/packages/client/README.i18n.yaml index db771381dd..31e1304a21 100644 --- a/packages/client/README.i18n.yaml +++ b/packages/client/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/README.md -README.md: eaf01b282ead3c4638435e3d02d6a803ad1faa15 -README.zh.md: 2ff4b1529f07e0f31b3d06a9577d3c480dd34916 +README.md: 928824bbdc92d933429c220572d0e5e80bcea989 +README.zh.md: 2978efc916930bc3742ca5da546091b0e8d70d5c diff --git a/packages/client/README.md b/packages/client/README.md index eaf01b282e..928824bbdc 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -35,7 +35,7 @@ The browser side of the dsh web GUI: shell boot, browser-host communication, sha | [`ui-skill/`](ui-skill/README.md) | Adds skill references to inline suggestions. | | [`ui-reference/`](ui-reference/README.md) | Unified Web `@file` / `@session` reference source. | | [`ui-subagent/`](ui-subagent/README.md) | Provides subagent navigation, child transcript states, and inline references. | -| [`ui-jobs/`](ui-jobs/README.md) | Lists this session's background jobs in the conversation header. | +| [`ui-activity/`](ui-activity/README.md) | Lists this session's tasks — jobs joined with their live-output activities. | | [`ui-model-selection/`](ui-model-selection/README.md) | Provides model selection in conversation surfaces. | | [`ui-permission/`](ui-permission-presets/README.md) | Configures default permissions and switches the current session's access. | | [`ui-plan/`](ui-plan/README.md) | Presents active plan-mode status and its exit control. | diff --git a/packages/client/README.zh.md b/packages/client/README.zh.md index 2ff4b1529f..2978efc916 100644 --- a/packages/client/README.zh.md +++ b/packages/client/README.zh.md @@ -35,7 +35,7 @@ dsh web GUI 的浏览器侧:shell 启动、浏览器与宿主通信、共享 U | [`ui-skill/`](ui-skill/README.zh.md) | 向内联建议添加 skill(技能)引用。 | | [`ui-reference/`](ui-reference/README.zh.md) | 统一的 Web `@file` / `@session` 引用 source。 | | [`ui-subagent/`](ui-subagent/README.zh.md) | 提供 subagent(子 agent)导航、子级 transcript(文本记录)的状态和内联引用。 | -| [`ui-jobs/`](ui-jobs/README.zh.md) | 在会话标题栏列出当前会话的后台任务。 | +| [`ui-activity/`](ui-activity/README.zh.md) | 列出本会话的任务——后台任务与其实时输出 activity 的合并视图。 | | [`ui-model-selection/`](ui-model-selection/README.zh.md) | 在对话界面中提供模型选择。 | | [`ui-permission/`](ui-permission-presets/README.zh.md) | 配置默认权限并切换当前会话的访问模式。 | | [`ui-plan/`](ui-plan/README.zh.md) | 展示生效中的 plan mode 状态及其退出控件。 | diff --git a/packages/client/ui-activity/README.i18n.yaml b/packages/client/ui-activity/README.i18n.yaml index 532ea19b10..ddfc1e3f6f 100644 --- a/packages/client/ui-activity/README.i18n.yaml +++ b/packages/client/ui-activity/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-activity/README.md -README.md: 157e98e6b14bc1b556cb2aac8f6f90c43fbcb3f2 -README.zh.md: 392cc91c105caa2f79546f818700da0e6643b8a1 +README.md: beb86e0c9f685c2ff7f799f878bb8646a6c2d041 +README.zh.md: 2aebde5da685995f6c191d621aed0ad3bac56678 diff --git a/packages/client/ui-activity/README.md b/packages/client/ui-activity/README.md index 157e98e6b1..beb86e0c9f 100644 --- a/packages/client/ui-activity/README.md +++ b/packages/client/ui-activity/README.md @@ -2,13 +2,15 @@ English | [中文](README.zh.md) -Session-header live-activity list over `ctx.activityFeed`: one header action beside the background-job list renders the roster rows this session can see (owned plus unowned), and expanding a row opens that activity's observation stream into an embedded terminal panel. Observation follows visibility — the stream opens on expand and closes on collapse, unmount, or popover dismissal, so output only flows while someone is watching. Retention gaps and stream failures render as notices above the panel. +Session-header task list: one header action renders this session's background jobs joined with their correlated live-output activities, plus standalone activities such as workflow runs. The join happens per row in this component — jobs and activities stay separate planes ([why](../../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md)): a job row keeps the job's lifecycle, duration, and model-visible `detail` from the `jobsBySession` mirror, and gains an expandable output panel when an activity carries its `correlation.jobId`; an activity without a job keeps its own row. Live rows lead with the label over a kind-and-status second line and a ticking duration; settled rows compact to one de-emphasized line behind a section divider. -The control renders nothing until the session can see at least one activity, so an ordinary conversation never grows a control for a capability it is not using; without the activity registry the roster stays empty and the entry point never appears. +Expanding an observable row opens that activity's observation stream from `ctx.activityFeed` into an embedded terminal panel. Observation follows visibility — the stream opens on expand and closes on collapse, unmount, or popover dismissal, so output only flows while someone is watching. Retention gaps and stream failures render as notices above the panel. + +The control renders nothing until the session can see at least one task, so an ordinary conversation never grows a control for a capability it is not using. Without the activity registry, job rows still render from the session mirror — they just offer no output panel. ## Model Experience -None, as this package renders host-observed live output for a human and touches no prompt, message, schema, stream, or tool result. The model's own view of the same work stays with [`dsh-tool-jobs`](../../jobs/tool-jobs/README.md). +None, as this package renders host-observed state and live output for a human and touches no prompt, message, schema, stream, or tool result. The model's own view of the same work stays with [`dsh-tool-jobs`](../../jobs/tool-jobs/README.md). #### KV Cache effect @@ -18,4 +20,3 @@ None; the package never assembles or sends provider requests. - **No kill control** — cancellation stays with the model's `job_kill`; a human kill is blocked on the jobs `reported` contract question recorded in the [web job display Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md). - **Channel labels are not rendered** — stdout and stderr chunks concatenate into one stream; per-channel tinting is a presentation follow-up. -- **A background job appears in both header lists** — the job list carries control-facing status, this list carries output; the duplication mirrors the deliberate subagent-catalog precedent. diff --git a/packages/client/ui-activity/README.zh.md b/packages/client/ui-activity/README.zh.md index 392cc91c10..2aebde5da6 100644 --- a/packages/client/ui-activity/README.zh.md +++ b/packages/client/ui-activity/README.zh.md @@ -2,13 +2,15 @@ [English](README.md) | 中文 -架在 `ctx.activityFeed` 上的会话头部实时活动列表:在后台任务列表旁提供一个头部 action,渲染本会话可见的 roster 行(有主 + 无主),展开某行即把该 activity 的观察流打开进内嵌终端面板。观察跟随可见性——展开开流,收起、卸载或关闭弹层即停流,只有有人在看时输出才流动。保留缺口与流失败以面板上方的提示呈现。 +会话头部任务列表:一个头部 action 渲染本会话的后台任务与其关联的实时输出 activity 的合并视图,外加 workflow 运行等独立 activity。合并逐行发生在本组件内——jobs 与 activity 仍是两个独立的面([缘由](../../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md)):job 行保留来自 `jobsBySession` 镜像的生命周期、时长与模型可见 `detail`,当某个 activity 以 `correlation.jobId` 关联到它时获得可展开的输出面板;没有 job 的 activity 保留自己的行。进行中的行以命令为主行、kind 与状态为副行并带跳动时长;已结束的行折为降权单行,置于分节线之后。 -会话一个 activity 都看不到时该控件完全不渲染,普通会话不会为未使用的能力多出控件;没有 activity 注册表时 roster 恒空,入口永不出现。 +展开可观察的行即把该 activity 在 `ctx.activityFeed` 上的观察流打开进内嵌终端面板。观察跟随可见性——展开开流,收起、卸载或关闭弹层即停流,只有有人在看时输出才流动。保留缺口与流失败以面板上方的提示呈现。 + +会话一个任务都看不到时该控件完全不渲染,普通会话不会为未使用的能力多出控件。没有 activity 注册表时,job 行仍从会话镜像渲染——只是不提供输出面板。 ## 模型体验 -无:本包只为人渲染宿主观察到的实时输出,不触碰任何 prompt、消息、schema、流或工具结果。模型对同一工作的视图仍在 [`dsh-tool-jobs`](../../jobs/tool-jobs/README.zh.md)。 +无:本包只为人渲染宿主观察到的状态与实时输出,不触碰任何 prompt、消息、schema、流或工具结果。模型对同一工作的视图仍在 [`dsh-tool-jobs`](../../jobs/tool-jobs/README.zh.md)。 #### KV Cache 影响 @@ -18,4 +20,3 @@ - **没有 kill 控件**——取消仍走模型的 `job_kill`;人工 kill 被 [web job display Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md) 记录的 jobs `reported` 契约问题阻塞。 - **不渲染通道标签**——stdout 与 stderr chunk 连接成一条流;分通道着色是后续呈现优化。 -- **后台 job 会同时出现在两个头部列表**——job 列表承载控制侧状态,本列表承载输出;这一重复沿用 subagent catalog 的既有取舍。 diff --git a/packages/client/ui-activity/package.json b/packages/client/ui-activity/package.json index 83395df003..4c4282e60b 100644 --- a/packages/client/ui-activity/package.json +++ b/packages/client/ui-activity/package.json @@ -1,6 +1,6 @@ { "name": "@deepseek-ai/dsh-client-ui-activity", - "description": "Session-header live-activity list: roster rows from the activity control stream with on-demand streaming output panels", + "description": "Session-header task list: background jobs joined with their live-output activities, with on-demand streaming output panels", "version": "0.1.1-rc.2", "type": "module", "main": "lib/index.js", @@ -37,6 +37,7 @@ "peerDependencies": { "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-api-activity-controller": "workspace:^", + "@deepseek-ai/dsh-api-session-controller": "workspace:^", "@deepseek-ai/dsh-client-locale": "workspace:^", "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", @@ -46,6 +47,7 @@ "devDependencies": { "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-api-activity-controller": "workspace:^", + "@deepseek-ai/dsh-api-session-controller": "workspace:^", "@deepseek-ai/dsh-client-locale": "workspace:^", "@deepseek-ai/dsh-client-test-runtime": "workspace:^", "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", diff --git a/packages/client/ui-activity/src/client/ActivityListAction.module.css b/packages/client/ui-activity/src/client/ActivityListAction.module.css index 2cf3af6e2f..d0d632ab34 100644 --- a/packages/client/ui-activity/src/client/ActivityListAction.module.css +++ b/packages/client/ui-activity/src/client/ActivityListAction.module.css @@ -62,6 +62,16 @@ box-shadow: var(--dsw-shadow-lv3); } +/* Divider label between the live section and the settled tail. */ +.sectionHeader { + margin: 4px 4px 1px; + padding: 4px 4px 3px; + border-top: 1px solid var(--dsw-alias-border-l1); + color: var(--dsw-alias-label-tertiary); + font-size: 11px; + line-height: 16px; +} + .item { display: flex; flex-direction: column; @@ -90,14 +100,46 @@ background: var(--dsw-alias-fill-l1); } +/* A row with no observable output offers no interaction. */ +.rowStatic { + cursor: default; +} + +.rowStatic:hover { + background: transparent; +} + .rowSettled { color: var(--dsw-alias-label-tertiary); } -.rowDot { +/* Live rows align the dot with the first text line, not the row center. */ +.row .rowDot { flex: none; } +.main { + display: flex; + flex: 1; + flex-direction: column; + gap: 2px; + min-width: 0; +} + +.primary { + display: flex; + align-items: baseline; + gap: 8px; + min-width: 0; +} + +.secondary { + display: flex; + align-items: center; + gap: 6px; + min-width: 0; +} + .kind { flex: none; padding: 0 6px; @@ -117,11 +159,11 @@ text-overflow: ellipsis; } -/* A failed activity's detail is the producer's raw text, so it has no bound; +/* A failed task's detail is the producer's raw text, so it has no bound; without this it widens the row past the menu instead of eliding like .label. */ .status { flex: none; - max-width: 40%; + max-width: 60%; overflow: hidden; color: var(--dsw-alias-label-tertiary); font-size: 11px; @@ -130,6 +172,14 @@ text-overflow: ellipsis; } +.duration { + flex: none; + color: var(--dsw-alias-label-tertiary); + font-size: 11px; + line-height: 18px; + font-variant-numeric: tabular-nums; +} + .chevron { flex: none; color: var(--dsw-alias-label-tertiary); @@ -139,8 +189,11 @@ transform: rotate(180deg); } +/* Output hangs under its row behind a spine that ties the two together. */ .panel { - margin: 0 8px 8px; + margin: 0 8px 8px 14px; + padding-left: 8px; + border-left: 2px solid var(--dsw-alias-border-l2); } .notice { diff --git a/packages/client/ui-activity/src/client/ActivityListAction.tsx b/packages/client/ui-activity/src/client/ActivityListAction.tsx index 1f868988b0..ef77df0e9c 100644 --- a/packages/client/ui-activity/src/client/ActivityListAction.tsx +++ b/packages/client/ui-activity/src/client/ActivityListAction.tsx @@ -2,6 +2,7 @@ import { useEffect, useLayoutEffect, useMemo, useRef, useState, type KeyboardEve import type { ActivityFeedSnapshot, ActivityId, ActivityRow, ObservedActivity, } from '@deepseek-ai/dsh-api-activity-controller/client' +import type { SessionJob } from '@deepseek-ai/dsh-api-session-controller/types' import { IconChevronDownOutline14, StateDot, TerminalBlock, useDismissOnOutsidePointer, type StateDotState, type TerminalBlockLabels, @@ -27,14 +28,36 @@ export interface ActivityListInjected { observe: (id: ActivityId) => () => void } -/** Full props for the session-header live-activity action. */ +/** Full props for the session-header task-list action. */ export type ActivityListActionProps = PropsRuntime<'conversation.session.header.actions'> & PropsLocale & InjectFace -/** Stable empty list so a session with no activities keeps one array identity. */ +/** + * One merged task row. Jobs and activities are separate planes — the control + * plane the model interacts with, and the transient observation plane — so + * this list joins them per row: a job carries identity, lifecycle, and the + * model-visible detail; its correlated activity contributes the observable + * live output; an activity without a job (a workflow run) stands alone. + */ +interface TaskRow { + /** Stable row identity: the job id when one exists, else the activity id. */ + key: string + kind: string + label: string + /** Job lifecycle vocabulary; activity-only rows never reach `stopping`. */ + status: SessionJob['status'] + detail?: string + startedAt: number + finishedAt?: number + /** Present when this row's live output can be observed. */ + activityId?: ActivityId +} + +/** Stable empty lists so a session with no work keeps one array identity. */ const NO_ROWS: readonly ActivityRow[] = [] +const NO_JOBS: readonly SessionJob[] = [] /** Minimum gap kept between the popover and the viewport edges (the Menu primitive's portal margin). */ const VIEWPORT_MARGIN = 12 @@ -42,19 +65,24 @@ const VIEWPORT_MARGIN = 12 /** Height cap for one live output panel inside the popover. */ const PANEL_MAX_LINES = 16 -function isLive(row: ActivityRow): boolean { - return row.status === 'running' +function isLive(row: TaskRow): boolean { + return row.status === 'running' || row.status === 'stopping' } /** Closed-union exhaustiveness fence for the wire status set. */ /* v8 ignore next 3 -- closed-union backstop; only reached if a status is forged */ function assertNever(value: never): never { - throw new Error(`unhandled activity status: ${JSON.stringify(value)}`) + throw new Error(`unhandled task status: ${JSON.stringify(value)}`) } -function dotState(status: ActivityRow['status']): StateDotState { +/** + * Status marker semantics. `stopping` and `killed` share the attention color: + * both mean the work ended (or is ending) on request rather than on its own. + */ +function dotState(status: TaskRow['status']): StateDotState { switch (status) { case 'running': return 'ongoing' + case 'stopping': return 'warning' case 'completed': return 'done' case 'killed': return 'warning' case 'failed': return 'error' @@ -63,9 +91,10 @@ function dotState(status: ActivityRow['status']): StateDotState { } } -function statusLabel(status: ActivityRow['status'], t: TranslateNS): string { +function statusLabel(status: TaskRow['status'], t: TranslateNS): string { switch (status) { case 'running': return t('status.running') + case 'stopping': return t('status.stopping') case 'completed': return t('status.completed') case 'killed': return t('status.killed') case 'failed': return t('status.failed') @@ -74,6 +103,22 @@ function statusLabel(status: ActivityRow['status'], t: TranslateNS): } } +/** + * Elapsed time in at most two adjacent units. A task that outlives an hour is + * already exceptional, so hours is the widest unit — beyond that the figure + * stays in hours rather than growing a day/month vocabulary no producer + * currently reaches. + */ +function formatDuration(elapsedMs: number, t: TranslateNS): string { + const total = Math.max(0, Math.floor(elapsedMs / 1_000)) + const seconds = total % 60 + const minutes = Math.floor(total / 60) % 60 + const hours = Math.floor(total / 3_600) + if (hours > 0) return t('duration.hours', { hours, minutes }) + if (minutes > 0) return t('duration.minutes', { minutes, seconds }) + return t('duration.seconds', { seconds }) +} + /** Localized display copy for the embedded terminal panel. */ function terminalLabels(t: TranslateNS): TerminalBlockLabels { return { @@ -96,9 +141,63 @@ function terminalLabels(t: TranslateNS): TerminalBlockLabels { } } -/* jscpd:ignore-start -- mirrors JobListAction's ordering and trigger chrome by design so the two header lists read as one family. */ -/** Live rows first in start order, then settled rows newest-first. */ -function ordered(rows: readonly ActivityRow[]): ActivityRow[] { +/** Project one standalone activity into the merged row vocabulary. */ +function activityTask(activity: ActivityRow): TaskRow { + return { + key: String(activity.id), + kind: activity.kind, + label: activity.label, + status: activity.status, + ...activity.detail !== undefined ? { detail: activity.detail } : {}, + startedAt: activity.startedAt, + ...activity.finishedAt !== undefined ? { finishedAt: activity.finishedAt } : {}, + activityId: activity.id, + } +} + +/** + * Join this session's jobs with their correlated activities and append the + * activities that stand alone. A job row keeps the job's lifecycle and detail + * (what the model sees) and gains observability from its activity; an + * activity whose job is not in the projection keeps its own row rather than + * disappearing. + */ +function mergeRows( + jobs: readonly SessionJob[], + activities: readonly ActivityRow[], +): TaskRow[] { + const byJob = new Map() + const standalone: ActivityRow[] = [] + for (const activity of activities) { + const jobId = activity.correlation?.jobId + if (jobId === undefined) standalone.push(activity) + else byJob.set(String(jobId), activity) + } + const rows: TaskRow[] = jobs.map((job) => { + const activity = byJob.get(String(job.id)) + byJob.delete(String(job.id)) + return { + key: String(job.id), + kind: job.kind, + label: job.label, + status: job.status, + ...job.detail !== undefined ? { detail: job.detail } : {}, + startedAt: job.startedAt, + ...job.finishedAt !== undefined ? { finishedAt: job.finishedAt } : {}, + ...activity !== undefined ? { activityId: activity.id } : {}, + } + }) + for (const activity of byJob.values()) rows.push(activityTask(activity)) + for (const activity of standalone) rows.push(activityTask(activity)) + return rows +} + +/** + * Live rows first in start order, then settled rows newest-first. Two rows + * that settled in the same millisecond fall back to start order, so the sort + * never depends on the host's map iteration. + */ +function ordered(rows: readonly TaskRow[]): TaskRow[] { return [...rows].sort((left, right) => { const liveLeft = isLive(left) if (liveLeft !== isLive(right)) return liveLeft ? -1 : 1 @@ -107,44 +206,87 @@ function ordered(rows: readonly ActivityRow[]): ActivityRow[] { return finished !== 0 ? finished : left.startedAt - right.startedAt }) } -/* jscpd:ignore-end */ -/** One expandable roster row plus its on-demand live output panel. */ -function ActivityItem({ row, view, expanded, onToggle, t }: { - row: ActivityRow +/** One task row plus, when observable and expanded, its live output panel. */ +function TaskItem({ row, view, expanded, now, onToggle, t }: { + row: TaskRow view: ObservedActivity | undefined expanded: boolean + /** Clock sample live rows derive their running duration from. */ + now: number onToggle: () => void t: TranslateNS }) { const live = isLive(row) const status = statusLabel(row.status, t) + const observable = row.activityId !== undefined const labels = useMemo(() => terminalLabels(t), [t]) - return ( -
      • - - {expanded + {durationCell} + {observable ? : null} + + ) + return ( +
      • + {observable + ? ( + + ) + : ( + + {body} + + )} + {expanded && view !== undefined ? (
        - {view?.gapBefore === true ?
        {t('output.gap')}
        : null} - {view?.error !== undefined + {view.gapBefore ?
        {t('output.gap')}
        : null} + {view.error !== undefined ?
        {t('output.error', { error: view.error })}
        : null} state.jobsBySession[sessionId]) ?? NO_JOBS const owned = useActivity(state => state.rowsBySession[sessionId]) ?? NO_ROWS const unowned = useActivity(state => state.rowsBySession['']) ?? NO_ROWS const observedViews = useActivity(state => state.observed) const [open, setOpen] = useState(false) - const [expandedId, setExpandedId] = useState(undefined) + const [expandedKey, setExpandedKey] = useState(undefined) + const [now, setNow] = useState(() => Date.now()) const rootRef = useRef(null) const triggerRef = useRef(null) const menuRef = useRef(null) @@ -178,11 +324,23 @@ export function ActivityListAction({ sessionId, useActivity, observe, t }: Activ // inside the viewport (the stylesheet alone cannot see the anchor offset). const [menuShift, setMenuShift] = useState(0) - const rows = useMemo(() => ordered([...owned, ...unowned]), [owned, unowned]) - const liveCount = useMemo(() => rows.filter(isLive).length, [rows]) + const rows = useMemo( + () => ordered(mergeRows(jobs, [...owned, ...unowned])), + [jobs, owned, unowned], + ) + const liveRows = useMemo(() => rows.filter(isLive), [rows]) + const settledRows = useMemo(() => rows.filter(row => !isLive(row)), [rows]) useDismissOnOutsidePointer(rootRef, open, setOpen) + // The clock only runs while an open list is showing something that moves. + useEffect(() => { + if (!open || liveRows.length === 0) return + setNow(Date.now()) + const timer = setInterval(() => { setNow(Date.now()) }, 1_000) + return () => { clearInterval(timer) } + }, [open, liveRows.length]) + // Fit the open popover to the viewport: shift left when the anchored width // would cross the right edge, never past the left margin. useLayoutEffect(() => { @@ -209,35 +367,36 @@ export function ActivityListAction({ sessionId, useActivity, observe, t }: Activ return () => { window.removeEventListener('resize', fit) } }, [open]) - // Observation follows visibility: the stream opens when a panel expands and - // closes when it collapses, unmounts, or the popover closes. - const activeId = open ? expandedId : undefined + // Observation follows visibility: the stream opens when an observable panel + // expands and closes when it collapses, unmounts, or the popover closes. + const activeActivity = open && expandedKey !== undefined + ? rows.find(row => row.key === expandedKey)?.activityId + : undefined useEffect(() => { - if (activeId === undefined) return - return observe(activeId as ActivityId) - }, [activeId, observe]) + if (activeActivity === undefined) return + return observe(activeActivity) + }, [activeActivity, observe]) - // The last activity disappearing removes this control; close first so focus + // The last task disappearing removes this control; close first so focus // does not vanish from an unmounting node. useEffect(() => { if (rows.length === 0 && open) setOpen(false) }, [rows.length, open]) - // An expanded row that left the roster (owner disposal) folds its panel. + // An expanded row that left the list (owner disposal) folds its panel. useEffect(() => { - if (expandedId !== undefined && !rows.some(row => String(row.id) === expandedId)) { - setExpandedId(undefined) + if (expandedKey !== undefined && !rows.some(row => row.key === expandedKey)) { + setExpandedKey(undefined) } - }, [rows, expandedId]) + }, [rows, expandedKey]) if (rows.length === 0) return null - const countKey = liveCount > 0 - ? (liveCount === 1 ? 'count.live.one' : 'count.live.other') + const countKey = liveRows.length > 0 + ? (liveRows.length === 1 ? 'count.live.one' : 'count.live.other') : (rows.length === 1 ? 'count.idle.one' : 'count.idle.other') - const countLabel = t(countKey, { count: liveCount > 0 ? liveCount : rows.length }) + const countLabel = t(countKey, { count: liveRows.length > 0 ? liveRows.length : rows.length }) - /* jscpd:ignore-start -- mirrors JobListAction's dismiss/trigger interaction by design. */ const onKeyDown = (event: KeyboardEvent): void => { if (event.key !== 'Escape' || !open) return event.preventDefault() @@ -245,6 +404,20 @@ export function ActivityListAction({ sessionId, useActivity, observe, t }: Activ triggerRef.current?.focus() } + const item = (row: TaskRow) => ( + { + setExpandedKey(current => current === row.key ? undefined : row.key) + }} + t={t} + /> + ) + return (
        - {/* jscpd:ignore-end */} {open ? (
          - {rows.map(row => ( - { - setExpandedId(current => current === String(row.id) ? undefined : String(row.id)) - }} - t={t} - /> - ))} + {liveRows.map(item)} + {liveRows.length > 0 && settledRows.length > 0 + ? + : null} + {settledRows.map(item)}
        ) : null} diff --git a/packages/client/ui-activity/src/client/index.ts b/packages/client/ui-activity/src/client/index.ts index 83ce0aa7bf..39f43df9e1 100644 --- a/packages/client/ui-activity/src/client/index.ts +++ b/packages/client/ui-activity/src/client/index.ts @@ -1,8 +1,10 @@ /** - * Live-activity plugin, browser half: contributes one session-header action - * that renders the activity roster and, per expanded row, an on-demand - * observation stream's live output. All data arrives through the - * `activityFeed` client service; this plugin holds no transport state. + * Task-list plugin, browser half: contributes one session-header action that + * renders this session's tasks — background jobs joined with their correlated + * live-output activities, plus standalone activities such as workflow runs. + * Job rows arrive through the `jobsBySession` list mirror; activity rows and + * per-row observation streams arrive through the `activityFeed` client + * service. This plugin holds no transport state of its own. */ import type { Context as ClientContext } from '@deepseek-ai/cordis' import { ActivityListAction } from './ActivityListAction.tsx' @@ -22,8 +24,8 @@ declare module '@deepseek-ai/dsh-client-ui-slots' { export type { ActivityListActionProps, ActivityListInjected } from './ActivityListAction.tsx' -/** Required services: the activity feed, the slot registry, and dictionaries. */ -export const inject = ['activityFeed', 'slots', 'locale'] +/** Required services: session and activity state, the slot registry, and dictionaries. */ +export const inject = ['sessions', 'activityFeed', 'slots', 'locale'] /** * Client plugin body: register the dictionaries and the header action. @@ -36,8 +38,8 @@ export function apply(ctx: ClientContext): void { () => ctx.slots.register({ name: 'conversation.session.header.actions', id: 'activity-list', - // After the background-job list: job control reads before live output. - order: 30, + // After the subagent catalog: session lineage reads before running work. + order: 20, locale: NS, inject: (): ActivityListInjected => ({ hooks: { activity: ctx.activityFeed.state }, diff --git a/packages/client/ui-activity/src/client/locales.ts b/packages/client/ui-activity/src/client/locales.ts index efea5126da..acb69c075d 100644 --- a/packages/client/ui-activity/src/client/locales.ts +++ b/packages/client/ui-activity/src/client/locales.ts @@ -5,17 +5,24 @@ export const NS = 'activity' /** Simplified Chinese dictionary (the key-set source of truth). */ export const zh = { - 'count.live.one': '{count} 个活动进行中', - 'count.live.other': '{count} 个活动进行中', - 'count.idle.one': '{count} 个活动', - 'count.idle.other': '{count} 个活动', - 'list.aria': '实时活动', + 'count.live.one': '{count} 个任务进行中', + 'count.live.other': '{count} 个任务进行中', + 'count.idle.one': '{count} 个任务', + 'count.idle.other': '{count} 个任务', + 'list.aria': '任务', + 'section.settled': '已结束', 'row.expandAria': '展开 {label} 的实时输出', 'row.collapseAria': '收起 {label} 的实时输出', 'status.running': '运行中', + 'status.stopping': '正在停止', 'status.completed': '已完成', 'status.killed': '已取消', 'status.failed': '已失败', + 'duration.seconds': '{seconds}秒', + 'duration.minutes': '{minutes}分{seconds}秒', + 'duration.hours': '{hours}小时{minutes}分', + 'duration.title.live': '已运行 {duration}', + 'duration.title.done': '耗时 {duration}', 'output.gap': '……较早的输出已丢弃……', 'output.error': '实时输出流中断:{error}', 'terminal.signal': '信号 {signal}', @@ -34,17 +41,24 @@ export const zh = { /** English dictionary, key-identical to the Chinese source of truth. */ export const en: Record = { - 'count.live.one': '{count} live activity', - 'count.live.other': '{count} live activities', - 'count.idle.one': '{count} activity', - 'count.idle.other': '{count} activities', - 'list.aria': 'Live activities', + 'count.live.one': '{count} task running', + 'count.live.other': '{count} tasks running', + 'count.idle.one': '{count} task', + 'count.idle.other': '{count} tasks', + 'list.aria': 'Tasks', + 'section.settled': 'Finished', 'row.expandAria': 'Show live output of {label}', 'row.collapseAria': 'Hide live output of {label}', 'status.running': 'running', + 'status.stopping': 'stopping', 'status.completed': 'completed', 'status.killed': 'cancelled', 'status.failed': 'failed', + 'duration.seconds': '{seconds}s', + 'duration.minutes': '{minutes}m {seconds}s', + 'duration.hours': '{hours}h {minutes}m', + 'duration.title.live': 'Running for {duration}', + 'duration.title.done': 'Took {duration}', 'output.gap': '… earlier output dropped …', 'output.error': 'live output stream interrupted: {error}', 'terminal.signal': 'signal {signal}', diff --git a/packages/client/ui-activity/tests/activity-list-action.client.spec.tsx b/packages/client/ui-activity/tests/activity-list-action.client.spec.tsx index bca39ac732..6dbb9f4519 100644 --- a/packages/client/ui-activity/tests/activity-list-action.client.spec.tsx +++ b/packages/client/ui-activity/tests/activity-list-action.client.spec.tsx @@ -1,10 +1,11 @@ // @vitest-environment jsdom import { afterEach, describe, expect, it, vi } from 'vitest' -import { cleanup, fireEvent, render, screen, within } from '@testing-library/react' +import { act, cleanup, fireEvent, render, screen, within } from '@testing-library/react' import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime' import type { ActivityFeedSnapshot, ActivityId, ActivityRow, ObservedActivity, } from '@deepseek-ai/dsh-api-activity-controller/client' +import type { SessionJob } from '@deepseek-ai/dsh-api-session-controller/types' import type { SessionId } from '@deepseek-ai/dsh-session/types' import { ActivityListAction, type ActivityListActionProps } from '../src/client/ActivityListAction.tsx' import { zh } from '../src/client/locales.ts' @@ -12,6 +13,7 @@ import { zh } from '../src/client/locales.ts' afterEach(() => { cleanup() vi.restoreAllMocks() + vi.useRealTimers() }) const SESSION = 'session' as SessionId @@ -36,9 +38,21 @@ function unownedRow(over: Partial = {}): ActivityRow { return rest } +function job(over: Partial = {}): SessionJob { + return { + id: 'bash-1' as SessionJob['id'], + kind: 'bash', + label: 'pnpm run build', + status: 'running', + startedAt: 1_700_000_000_000, + ...over, + } +} + function props( snapshot: Partial, observe: ActivityListActionProps['observe'] = () => () => {}, + jobs: readonly SessionJob[] = [], ): ActivityListActionProps { const state: ActivityFeedSnapshot = { rowsBySession: {}, @@ -49,7 +63,11 @@ function props( function useActivity(select: (value: ActivityFeedSnapshot) => T): T { return select(state) } - return { sessionId: SESSION, useActivity, observe, t } as unknown as ActivityListActionProps + const sessionsState = { jobsBySession: jobs.length > 0 ? { [SESSION]: jobs } : {} } + function useSessions(select: (value: typeof sessionsState) => T): T { + return select(sessionsState) + } + return { sessionId: SESSION, useSessions, useActivity, observe, t } as unknown as ActivityListActionProps } function openList(): void { @@ -57,19 +75,19 @@ function openList(): void { } describe('ActivityListAction visibility', () => { - it('renders nothing while the session sees no activities', () => { + it('renders nothing while the session sees no tasks', () => { const { container } = render() expect(container.innerHTML).toBe('') }) - it('counts live activities on the trigger, merging owned and unowned rows', () => { + it('counts live tasks on the trigger, merging owned and unowned activity rows', () => { render() - expect(screen.getByRole('button', { name: '2 个活动进行中' })).toBeDefined() + expect(screen.getByRole('button', { name: '2 个任务进行中' })).toBeDefined() }) it('falls back to the total when nothing is live and hides foreign sessions', () => { @@ -79,7 +97,79 @@ describe('ActivityListAction visibility', () => { other: [row({ id: 'bash-9' as ActivityId, sessionId: 'other' as SessionId })], }, })} />) - expect(screen.getByRole('button', { name: '1 个活动' })).toBeDefined() + expect(screen.getByRole('button', { name: '1 个任务' })).toBeDefined() + }) +}) + +describe('ActivityListAction merged rows', () => { + it('joins a job with its correlated activity: job lifecycle, activity output', () => { + const observe = vi.fn(() => () => {}) + render() + openList() + const list = screen.getByRole('list', { name: zh['list.aria'] }) + // One merged row: the job's label and lifecycle word, not the activity's. + expect(within(list).getAllByRole('listitem')).toHaveLength(1) + expect(within(list).getByText('pnpm run build')).toBeDefined() + expect(screen.queryByText('activity-side label')).toBeNull() + expect(within(list).getByText('winding down')).toBeDefined() + // Expansion observes the correlated activity's stream. + fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) + expect(observe).toHaveBeenCalledWith('bash-act-7') + }) + + it('renders a bare job row without expansion affordances', () => { + render() + expect(screen.getByRole('button', { name: '1 个任务进行中' })).toBeDefined() + openList() + expect(screen.getByText('explore the repo')).toBeDefined() + expect(screen.queryByRole('button', { name: zh['row.expandAria'].replace('{label}', 'explore the repo') })).toBeNull() + }) + + it('keeps an activity whose job is not in the projection', () => { + render() + openList() + expect(screen.getByText('pnpm run build')).toBeDefined() + }) + + it('separates live and settled sections only when both exist', () => { + const settled = [job({ id: 'bash-2' as SessionJob['id'], status: 'completed', finishedAt: 1_700_000_012_000 })] + const { rerender } = render() + openList() + expect(screen.getByText(zh['section.settled'])).toBeDefined() + // Live-only lists carry no divider. + rerender() + expect(screen.queryByText(zh['section.settled'])).toBeNull() + }) + + it('shows a settled duration and ticks a live one', () => { + vi.useFakeTimers({ now: 1_700_000_020_000 }) + render() + openList() + expect(screen.getByText('5秒')).toBeDefined() + expect(screen.getByText('12秒')).toBeDefined() + expect(screen.getByText('1小时3分')).toBeDefined() + expect(screen.getByText('1分12秒')).toBeDefined() + act(() => { vi.advanceTimersByTime(1_000) }) + expect(screen.getByText('6秒')).toBeDefined() }) }) @@ -200,7 +290,7 @@ describe('ActivityListAction rows and observation', () => { const { rerender } = render() - expect(screen.getByRole('button', { name: '2 个活动' })).toBeDefined() + expect(screen.getByRole('button', { name: '2 个任务' })).toBeDefined() openList() const list = screen.getByRole('list', { name: zh['list.aria'] }) fireEvent.keyDown(list, { key: 'a' }) diff --git a/packages/client/ui-activity/tests/browser-plugin.client.spec.ts b/packages/client/ui-activity/tests/browser-plugin.client.spec.ts index de6db2a069..3f84c2252d 100644 --- a/packages/client/ui-activity/tests/browser-plugin.client.spec.ts +++ b/packages/client/ui-activity/tests/browser-plugin.client.spec.ts @@ -35,6 +35,7 @@ async function bench(): Promise<{ ctx: Context; fiber: ReturnType null) + ctx.provide('sessions', {} as never) ctx.provide('activityFeed', { state: { getSnapshot: () => ({ rowsBySession: {}, observed: {}, phase: 'pending' }), subscribe: () => () => {} }, observe: (id: string) => { observed.push(id); return () => {} }, @@ -56,7 +57,7 @@ async function bench(): Promise<{ ctx: Context; fiber: ReturnType { it('declares the services it binds', () => { - expect(inject).toEqual(['activityFeed', 'slots', 'locale']) + expect(inject).toEqual(['sessions', 'activityFeed', 'slots', 'locale']) }) it('exposes the feed source and observation control through the inject face', async () => { diff --git a/packages/client/ui-activity/tsconfig.json b/packages/client/ui-activity/tsconfig.json index bbd9c5ce85..562e2c2228 100644 --- a/packages/client/ui-activity/tsconfig.json +++ b/packages/client/ui-activity/tsconfig.json @@ -11,6 +11,7 @@ { "path": "../../../vendor/cosmokit" }, { "path": "../../../vendor/cordis" }, { "path": "../../api/activity-controller/tsconfig.client.json" }, + { "path": "../../api/session-controller/tsconfig.client.json" }, { "path": "../locale" }, { "path": "../ui-conversation" }, { "path": "../ui-primitives" }, diff --git a/packages/client/ui-jobs/README.i18n.yaml b/packages/client/ui-jobs/README.i18n.yaml deleted file mode 100644 index 23ebb49d68..0000000000 --- a/packages/client/ui-jobs/README.i18n.yaml +++ /dev/null @@ -1,6 +0,0 @@ -# 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 packages/client/ui-jobs/README.md -README.md: 0523aa10ebfbaa6cde0bef391017bc0307d8bdd5 -README.zh.md: bb713f446855a9e8b23c5543827b9897f1177a48 diff --git a/packages/client/ui-jobs/README.md b/packages/client/ui-jobs/README.md deleted file mode 100644 index 0523aa10eb..0000000000 --- a/packages/client/ui-jobs/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# @deepseek-ai/dsh-client-ui-jobs - -English | [中文](README.zh.md) - -Web background-job feature owner: contributes one entry to `conversation.session.header.actions` listing the `ctx.jobs` records this session can see. The data arrives entirely through the `jobsBySession` list mirror that the [Session Controller](../../api/session-controller/README.md) folds from `session/jobs` frames, so this package issues no RPC and holds no state beyond popover visibility. - -The trigger renders only when the session has at least one job, so an ordinary conversation never grows a control for a capability it is not using. Its badge counts `running` plus `stopping` and is omitted at zero, leaving a session that holds only finished jobs a quiet entry point into its history rather than one advertising a count of nothing. The popover is a flat list: live rows first by `startedAt` ascending, then settled rows by `finishedAt` descending, with a same-millisecond tie broken on start order so the host's map iteration never decides it. A row shows the producer kind, the label, a status marker, the producer's `detail` in place of the generic status word once it has one, and an elapsed duration. That duration advances once per second while the row is live and freezes at `finishedAt`; the clock runs only while an open list holds something that moves. A settled row missing `finishedAt` reads as zero rather than as a negative figure, and a duration past an hour stays in hours rather than growing a day vocabulary no producer currently reaches. - -Settled rows stay visible and de-emphasized until the registry drops them at owner disposal. They are in the snapshot, a failed job's `detail` is the only place its failure is legible, and filtering them out here is work the output and cancellation phases would undo. A running one-shot background subagent therefore appears both here and in the [subagent catalog](../ui-subagent/README.md): the catalog navigates into the child's transcript, while this list is the only handle a future cancellation can attach to. - -Escape closes the list and returns focus to the trigger, as does a pointer press outside it. The last job disappearing closes the list before the control unmounts, so focus never vanishes from a removed node. Styling uses tokens only; copy goes through the package's own `job` locale namespace. The behavior is specified by the [Web background-job display Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md). - -## Model Experience - -None, as this package renders host-computed registry state for a human and touches no prompt, message, schema, stream, or tool result. The model's own view of the same jobs stays with [`dsh-tool-jobs`](../../jobs/tool-jobs/README.md). - -#### KV Cache effect - -None; the package never assembles or sends provider requests. - -## Known Limitations and Deferred Work - -- **Rows are read-only** — a job's streamed output and a human-initiated cancellation are separate phases. Cancellation additionally owes a model-facing decision the seam does not answer: `kill()` marks terminal delivery reported, so an interrupt written against the current contract would leave the model believing its job is still running. -- **The list is not the registry's own set** — it shows what one session can see through the wire view, so a job owned by another session never appears here, and a process restart empties the list while the transcript keeps the `run_in_background` cards that started those jobs. An unowned job (one started without a live `Agent`) is the opposite case: it reaches every session's list, matching what `list(caller)` reports to every caller. diff --git a/packages/client/ui-jobs/README.zh.md b/packages/client/ui-jobs/README.zh.md deleted file mode 100644 index bb713f4468..0000000000 --- a/packages/client/ui-jobs/README.zh.md +++ /dev/null @@ -1,24 +0,0 @@ -# @deepseek-ai/dsh-client-ui-jobs - -[English](README.md) | 中文 - -Web 后台任务特性的归属方:向 `conversation.session.header.actions` 贡献一个条目,列出当前会话可见的 `ctx.jobs` 记录。数据完全来自 [Session Controller](../../api/session-controller/README.zh.md) 从 `session/jobs` 帧折叠出的 `jobsBySession` 列表镜像,因此本包不发任何 RPC,除弹层开合外不持有任何状态。 - -只有当会话至少有一个任务时才渲染触发器,普通对话不会因为一项未被使用的能力而长出控件。角标计数为 `running` 加 `stopping`,为零时省略,这样只剩已完成任务的会话保留一个安静的历史入口,而不是宣告一个「零」。弹层是一个扁平列表:活跃行在前按 `startedAt` 升序,随后终态行按 `finishedAt` 降序;毫秒相同的并列按启动顺序打破,宿主的 map 迭代顺序永远不参与决定。一行显示生产者 kind、label、状态标记、生产者一旦给出 `detail` 就取代通用状态词的那段文字,以及已耗时。该耗时在活跃时每秒推进,并在 `finishedAt` 冻结;只有当打开的列表里确实有会动的东西时时钟才运行。缺少 `finishedAt` 的终态行读作零而不是负数,超过一小时的耗时停留在小时单位,不会长出任何生产者目前都到不了的「天」词汇。 - -终态行保持可见并弱化,直到注册表在 owner 销毁时把它们丢掉。它们本就在快照里,失败任务的 `detail` 是其失败唯一可读之处,在这里过滤掉它们是输出与中断两期要推翻的工作。因此一个运行中的一次性后台 subagent 会同时出现在这里和 [subagent 目录](../ui-subagent/README.zh.md)里:目录负责进入子会话的 transcript,而这个列表是将来中断能力唯一可能附着的句柄。 - -Escape 关闭列表并把焦点交还触发器,在其外部按下指针同理。最后一个任务消失时先关闭列表再卸载控件,焦点因此不会从一个被移除的节点上凭空消失。样式只用 token;文案走本包自己的 `job` locale 命名空间。行为由 [Web 后台任务展示 Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md) 规定。 - -## 模型体验 - -无,因为本包为人类渲染宿主计算出的注册表状态,不触及 prompt、消息、schema、流或工具结果。模型对同一批任务的视角仍属于 [`dsh-tool-jobs`](../../jobs/tool-jobs/README.zh.md)。 - -#### KV Cache effect - -无;本包从不组装或发送 provider 请求。 - -## 已知限制与暂缓事项 - -- **行是只读的** —— 任务的流式输出与人类发起的中断是各自独立的阶段。中断还额外欠一个 seam 没有回答的、面向模型的决策:`kill()` 会把终态投递标为已上报,所以照当前契约写出来的中断会让模型一直以为它的任务还在跑。 -- **列表不等于注册表自己的集合** —— 它展示的是「一个会话通过线路视图能看到什么」,所以别的会话拥有的任务在这里永远不出现;而进程重启会清空列表,transcript 里启动这些任务的 `run_in_background` 卡片却还在。无主任务(在没有活体 `Agent` 时启动的)是反过来的情形:它会进入每一个会话的列表,与 `list(caller)` 对每个调用方的报告一致。 diff --git a/packages/client/ui-jobs/package.json b/packages/client/ui-jobs/package.json deleted file mode 100644 index a195c70e08..0000000000 --- a/packages/client/ui-jobs/package.json +++ /dev/null @@ -1,76 +0,0 @@ -{ - "name": "@deepseek-ai/dsh-client-ui-jobs", - "description": "Session-header background-job list: live registry state mirrored from session/jobs frames", - "version": "0.1.1-rc.2", - "type": "module", - "main": "lib/index.js", - "types": "lib/types/index.d.ts", - "exports": { - ".": { - "types": "./lib/types/index.d.ts", - "default": "./lib/index.js" - }, - "./invariant": { - "types": "./lib/types/invariant.d.ts", - "default": "./lib/invariant.js" - }, - "./client": { - "types": "./lib/types/client/index.d.ts", - "default": "./lib/client.js" - }, - "./src/*": "./src/*", - "./package.json": "./package.json" - }, - "dsh": { - "client": { - "inject": [ - "@deepseek-ai/dsh-client-locale", - "@deepseek-ai/dsh-client-ui-conversation", - "@deepseek-ai/dsh-client-ui-primitives" - ], - "platform": "web" - } - }, - "scripts": { - "bundle": "tsdown", - "watch": "tsdown --watch" - }, - "license": "MIT", - "repository": { - "type": "git", - "url": "git+https://github.com/deepseek-ai/deepseek-harness.git", - "directory": "packages/client/ui-jobs" - }, - "publishConfig": { - "access": "public" - }, - "peerDependencies": { - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^" - }, - "devDependencies": { - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-test-runtime": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-primitives": "workspace:^", - "@deepseek-ai/dsh-client-ui-slots": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@types/react": "~18.3.1", - "@deepseek-ai/cordis": "workspace:^", - "react": "^18.2.0", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^" - }, - "files": [ - "lib/index.js", - "lib/invariant.js", - "lib/client.js", - "lib/types/**/*.d.ts" - ] -} diff --git a/packages/client/ui-jobs/src/client/JobListAction.module.css b/packages/client/ui-jobs/src/client/JobListAction.module.css deleted file mode 100644 index 2f475bd09c..0000000000 --- a/packages/client/ui-jobs/src/client/JobListAction.module.css +++ /dev/null @@ -1,125 +0,0 @@ -.root { - position: relative; -} - -.trigger { - display: inline-flex; - align-items: center; - gap: 3px; - min-height: 28px; - padding: 3px 2px; - border: 0; - border-radius: 6px; - background: transparent; - color: var(--dsw-alias-label-tertiary); - font-size: 12px; - line-height: 18px; - cursor: pointer; -} - -.trigger:hover, -.trigger:focus-visible { - color: var(--dsw-alias-label-secondary); -} - -.trigger svg { - transition: transform 120ms ease; -} - -.triggerOpen { - transform: rotate(180deg); -} - -.triggerDot { - flex: none; -} - -.count { - margin: 0 5px; -} - -.menu { - position: absolute; - top: calc(100% + 5px); - left: 0; - z-index: 100; - box-sizing: border-box; - display: flex; - flex-direction: column; - gap: 1px; - width: 336px; - max-width: min(400px, calc(100vw - 32px)); - max-height: min(420px, calc(100vh - 140px)); - margin: 0; - padding: 4px; - overflow: auto; - list-style: none; - border: 1px solid var(--dsw-alias-border-l2); - border-radius: 12px; - background: var(--dsw-specific-menu); - --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2); - --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2); - box-shadow: var(--dsw-shadow-lv3); -} - -.row { - display: flex; - align-items: center; - gap: 8px; - box-sizing: border-box; - width: 100%; - min-height: 32px; - padding: 6px 8px; - border-radius: 8px; - color: var(--dsw-alias-label-primary); - font-size: 13px; - line-height: 18px; -} - -.rowSettled { - color: var(--dsw-alias-label-tertiary); -} - -.rowDot { - flex: none; -} - -.kind { - flex: none; - padding: 0 6px; - border-radius: 5px; - background: var(--dsw-alias-fill-l2); - color: var(--dsw-alias-label-secondary); - font-size: 11px; - line-height: 18px; -} - -.label { - flex: 1; - min-width: 0; - overflow: hidden; - font-family: var(--dsw-font-mono); - white-space: nowrap; - text-overflow: ellipsis; -} - -.status, -.duration { - flex: none; - color: var(--dsw-alias-label-tertiary); - font-size: 11px; - line-height: 18px; -} - -/* A failed job's detail is the producer's raw error text, so it has no bound; - without this it widens the row past the menu instead of eliding like .label. */ -.status { - max-width: 40%; - overflow: hidden; - white-space: nowrap; - text-overflow: ellipsis; -} - -.duration { - font-variant-numeric: tabular-nums; -} diff --git a/packages/client/ui-jobs/src/client/JobListAction.tsx b/packages/client/ui-jobs/src/client/JobListAction.tsx deleted file mode 100644 index bf15074079..0000000000 --- a/packages/client/ui-jobs/src/client/JobListAction.tsx +++ /dev/null @@ -1,183 +0,0 @@ -import { useEffect, useMemo, useRef, useState, type KeyboardEvent } from 'react' -import type { SessionJob as JobView } from '@deepseek-ai/dsh-api-session-controller/types' -import { IconChevronDownOutline14, StateDot, useDismissOnOutsidePointer, type StateDotState } from '@deepseek-ai/dsh-client-ui-primitives' -import type { PropsLocale, PropsRuntime, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots' -import { NS } from './locales.ts' -import type {} from '@deepseek-ai/dsh-client-ui-conversation/client' -import css from './JobListAction.module.css' - -/** Full props for the session-header background-job action. */ -export type JobListActionProps = - PropsRuntime<'conversation.session.header.actions'> & PropsLocale - -/** Stable empty list so a session with no jobs keeps one array identity. */ -const NO_TASKS: readonly JobView[] = [] - -/** A job the registry still holds open, and whose duration therefore ticks. */ -function isLive(job: JobView): boolean { - return job.status === 'running' || job.status === 'stopping' -} - -/** Closed-union exhaustiveness fence for the wire status set. */ -/* v8 ignore next 3 -- closed-union backstop; only reached if a status is forged */ -function assertNever(value: never): never { - throw new Error(`unhandled job status: ${JSON.stringify(value)}`) -} - -/** - * Status marker semantics. `stopping` and `killed` share the attention color: - * both mean the work ended (or is ending) on request rather than on its own. - */ -function dotState(status: JobView['status']): StateDotState { - switch (status) { - case 'running': return 'ongoing' - case 'stopping': return 'warning' - case 'completed': return 'done' - case 'killed': return 'warning' - case 'failed': return 'error' - /* v8 ignore next -- closed wire status union */ - default: return assertNever(status) - } -} - -/** Human status word for the row and its accessible name. */ -function statusLabel(status: JobView['status'], t: TranslateNS): string { - switch (status) { - case 'running': return t('status.running') - case 'stopping': return t('status.stopping') - case 'completed': return t('status.completed') - case 'killed': return t('status.killed') - case 'failed': return t('status.failed') - /* v8 ignore next -- closed wire status union */ - default: return assertNever(status) - } -} - -/** - * Elapsed time in at most two adjacent units. A background job that outlives - * an hour is already exceptional, so hours is the widest unit — beyond that the - * figure stays in hours rather than growing a day/month vocabulary no producer - * currently reaches. - */ -function formatDuration(elapsedMs: number, t: TranslateNS): string { - const total = Math.max(0, Math.floor(elapsedMs / 1_000)) - const seconds = total % 60 - const minutes = Math.floor(total / 60) % 60 - const hours = Math.floor(total / 3_600) - if (hours > 0) return t('duration.hours', { hours, minutes }) - if (minutes > 0) return t('duration.minutes', { minutes, seconds }) - return t('duration.seconds', { seconds }) -} - -/** - * Live rows first in start order, then settled rows newest-first. Two jobs - * that settled in the same millisecond fall back to start order, so the sort - * never depends on the host's map iteration. - */ -function ordered(jobs: readonly JobView[]): JobView[] { - return [...jobs].sort((left, right) => { - const liveLeft = isLive(left) - if (liveLeft !== isLive(right)) return liveLeft ? -1 : 1 - if (liveLeft) return left.startedAt - right.startedAt - const finished = (right.finishedAt ?? right.startedAt) - (left.finishedAt ?? left.startedAt) - return finished !== 0 ? finished : left.startedAt - right.startedAt - }) -} - -/** - * Session-header entry point for this session's background jobs. It renders - * nothing at all until the session has at least one job, so an ordinary - * conversation never grows a control for a capability it is not using. - * @param props - runtime slot currency plus the namespace translator. - * @returns the trigger and its popover list, or null when there is nothing to show. - */ -export function JobListAction({ sessionId, useSessions, t }: JobListActionProps) { - const jobs = useSessions(state => state.jobsBySession[sessionId]) ?? NO_TASKS - const [open, setOpen] = useState(false) - const [now, setNow] = useState(() => Date.now()) - const rootRef = useRef(null) - const triggerRef = useRef(null) - - const rows = useMemo(() => ordered(jobs), [jobs]) - const liveCount = useMemo(() => jobs.filter(isLive).length, [jobs]) - - useDismissOnOutsidePointer(rootRef, open, setOpen) - - // The clock only runs while an open list is showing something that moves. - useEffect(() => { - if (!open || liveCount === 0) return - setNow(Date.now()) - const timer = setInterval(() => { setNow(Date.now()) }, 1_000) - return () => { clearInterval(timer) } - }, [open, liveCount]) - - // The last job disappearing removes this control; close first so focus does - // not vanish from an unmounting node. - useEffect(() => { - if (jobs.length === 0 && open) setOpen(false) - }, [jobs.length, open]) - - if (jobs.length === 0) return null - - const countKey = liveCount > 0 - ? (liveCount === 1 ? 'count.live.one' : 'count.live.other') - : (jobs.length === 1 ? 'count.idle.one' : 'count.idle.other') - const countLabel = t(countKey, { count: liveCount > 0 ? liveCount : jobs.length }) - - const onKeyDown = (event: KeyboardEvent): void => { - if (event.key !== 'Escape' || !open) return - event.preventDefault() - setOpen(false) - triggerRef.current?.focus() - } - - return ( -
        - - {open - ? ( -
          - {rows.map((job) => { - const live = isLive(job) - const elapsed = live ? now - job.startedAt : (job.finishedAt ?? job.startedAt) - job.startedAt - const duration = formatDuration(elapsed, t) - const status = statusLabel(job.status, t) - return ( -
        • - - {job.kind} - {job.label} - {job.detail ?? status} - - {duration} - -
        • - ) - })} -
        - ) - : null} -
        - ) -} diff --git a/packages/client/ui-jobs/src/client/index.ts b/packages/client/ui-jobs/src/client/index.ts deleted file mode 100644 index 22dc2c8425..0000000000 --- a/packages/client/ui-jobs/src/client/index.ts +++ /dev/null @@ -1,42 +0,0 @@ -/** - * Background-job plugin, browser half: contributes one session-header action - * that renders this session's `ctx.jobs` records. The data arrives entirely - * through the `jobsBySession` list mirror, so the plugin issues no RPC and - * holds no state of its own beyond popover visibility. - */ -import type { Context as ClientContext } from '@deepseek-ai/cordis' -import { JobListAction } from './JobListAction.tsx' -import type {} from '@deepseek-ai/dsh-client-locale/client' -import type {} from '@deepseek-ai/dsh-client-ui-renderer/client' -import type {} from '@deepseek-ai/dsh-client-ui-session/client' -import { en, NS, zh, type JobKey } from './locales.ts' - -declare module '@deepseek-ai/dsh-client-ui-slots' { - interface LocaleNamespaceMap { - /** Background-job list copy. */ - 'job': JobKey - } -} - -export type { JobListActionProps } from './JobListAction.tsx' - -/** Required services for locale registration and header-slot contribution. */ -export const inject = ['sessions', 'slots', 'locale'] - -/** - * Client plugin body: register the dictionaries and the header action. - * @param ctx - client root context. - */ -export function apply(ctx: ClientContext): void { - ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-job: dictionaries') - ctx.slots.inject( - 'conversation.session.header.actions', - () => ctx.slots.register({ - name: 'conversation.session.header.actions', - id: 'job-list', - // After the subagent catalog: session lineage reads before process work. - order: 20, - locale: NS, - }, JobListAction), - ) -} diff --git a/packages/client/ui-jobs/src/client/locales.ts b/packages/client/ui-jobs/src/client/locales.ts deleted file mode 100644 index 70bb2e9e0f..0000000000 --- a/packages/client/ui-jobs/src/client/locales.ts +++ /dev/null @@ -1,45 +0,0 @@ -/** `job` namespace dictionaries. */ - -/** Dictionary namespace owned by this plugin. */ -export const NS = 'job' - -/** Simplified Chinese dictionary (the key-set source of truth). */ -export const zh = { - 'count.live.one': '{count} 个后台任务运行中', - 'count.live.other': '{count} 个后台任务运行中', - 'count.idle.one': '{count} 个后台任务', - 'count.idle.other': '{count} 个后台任务', - 'list.aria': '后台任务', - 'status.running': '运行中', - 'status.stopping': '正在停止', - 'status.completed': '已完成', - 'status.killed': '已取消', - 'status.failed': '已失败', - 'duration.seconds': '{seconds}秒', - 'duration.minutes': '{minutes}分{seconds}秒', - 'duration.hours': '{hours}小时{minutes}分', - 'duration.title.live': '已运行 {duration}', - 'duration.title.done': '耗时 {duration}', -} as const - -/** English dictionary, key-identical to the Chinese source of truth. */ -export const en: Record = { - 'count.live.one': '{count} background job running', - 'count.live.other': '{count} background jobs running', - 'count.idle.one': '{count} background job', - 'count.idle.other': '{count} background jobs', - 'list.aria': 'Background jobs', - 'status.running': 'running', - 'status.stopping': 'stopping', - 'status.completed': 'completed', - 'status.killed': 'cancelled', - 'status.failed': 'failed', - 'duration.seconds': '{seconds}s', - 'duration.minutes': '{minutes}m {seconds}s', - 'duration.hours': '{hours}h {minutes}m', - 'duration.title.live': 'Running for {duration}', - 'duration.title.done': 'Took {duration}', -} - -/** Key domain of the `job` namespace (zh is the source of truth). */ -export type JobKey = keyof typeof zh diff --git a/packages/client/ui-jobs/src/css-modules.d.ts b/packages/client/ui-jobs/src/css-modules.d.ts deleted file mode 100644 index bc5e482353..0000000000 --- a/packages/client/ui-jobs/src/css-modules.d.ts +++ /dev/null @@ -1,6 +0,0 @@ -declare module '*.module.css' { - const classes: Record - export default classes -} - -declare module '*.css' diff --git a/packages/client/ui-jobs/src/index.ts b/packages/client/ui-jobs/src/index.ts deleted file mode 100644 index 94d45c3ba1..0000000000 --- a/packages/client/ui-jobs/src/index.ts +++ /dev/null @@ -1,9 +0,0 @@ -/** - * Background-job list plugin, node half. Pure UI plugin: the empty apply - * exists so the plugin appears in the host cordis.yml / Loader; the browser - * half ships via exports["./client"], discovered through the package.json - * dshClient declaration. - */ - -/** Host plugin body — no host-side behavior for this source plugin. */ -export function apply(): void {} diff --git a/packages/client/ui-jobs/src/invariant.ts b/packages/client/ui-jobs/src/invariant.ts deleted file mode 100644 index 0807c8600f..0000000000 --- a/packages/client/ui-jobs/src/invariant.ts +++ /dev/null @@ -1,32 +0,0 @@ -/** - * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-jobs`. - * @module @deepseek-ai/dsh-client-ui-jobs/invariant - */ - -/* jscpd:ignore-start */ -import type { Context } from '@deepseek-ai/cordis' -import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants' - -const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-jobs' - -/** Cordis companion plugin name. */ -export const name = 'client-ui-jobs-invariant' -/** Service required before the companion can reserve package ownership. */ -export const inject = ['invariants'] - -/** - * No runtime invariant: this package is a read-only projection of the - * `jobsBySession` mirror onto one header slot entry. It emits no cordis - * events, owns no cross-plugin mutable state, and its single slot registration - * proves disposal through the HMR-safety spec. - */ -const install: InvariantInstaller = () => {} - -/** - * Register this package's invariant companion. - * @param ctx - Cordis context carrying the invariant service. - * @returns the installed registration's disposer after setup succeeds. - */ -export const apply = (ctx: Context): Promise<() => void> => - Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install)) -/* jscpd:ignore-end */ diff --git a/packages/client/ui-jobs/tests/browser-plugin.client.spec.ts b/packages/client/ui-jobs/tests/browser-plugin.client.spec.ts deleted file mode 100644 index 93e6df1e5f..0000000000 --- a/packages/client/ui-jobs/tests/browser-plugin.client.spec.ts +++ /dev/null @@ -1,101 +0,0 @@ -/** - * ui-job plugin halves: the browser entry's dictionary and header-slot - * registrations against the real SlotRegistry (with fiber teardown proving - * removal — HMR safety), the inert node entry, and the invariant companion's - * ownership reservation. - */ -import { Context } from '@deepseek-ai/cordis' -import { describe, expect, it } from 'vitest' -import InvariantRegistry from '@deepseek-ai/dsh-invariants' -import { SlotRegistry } from '@deepseek-ai/dsh-client-ui-renderer/client' -import { stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime' -import { apply as applyLocale, inject as localeInject } from '@deepseek-ai/dsh-client-locale/client' -import { apply, inject } from '../src/client/index.ts' -import { apply as applyNode } from '../src/index.ts' -import * as JobInvariant from '../src/invariant.ts' -import { en, NS, zh } from '../src/client/locales.ts' - -/** Slot ledger reader: entry ids currently registered in the header list. */ -function headerEntryIds(ctx: Context): (string | undefined)[] { - return ctx.slots - .entries('conversation.session.header.actions') - .map(entry => entry.options.id) -} - -/** Boot the browser half over a real slot tree that declares the header list. */ -async function bench(): Promise<{ ctx: Context; fiber: ReturnType }> { - const ctx = new Context() - await ctx.plugin(SlotRegistry).await() - ctx.slots.register({ - name: 'root', - children: { - 'conversation.session.header.actions': { kind: 'list', scope: 'session' }, - }, - } as never, () => null) - ctx.provide('sessions', {}) - // The locale plugin binds a settings scope, which reads the connection handle - // and the forwarded-event port. - ctx.provide('connection', { api: { settings: {} }, isLoopback: false } as never) - ctx.provide('remote', { $on: () => () => {} } as never) - ctx.provide('settingsScope', { bind: () => stubSettingsScope().scope } as never) - await ctx.plugin({ inject: localeInject, apply: applyLocale }).await() - // These specs assert the shipped Chinese copy. There is no jsdom `window` in - // this lane, so browser-language detection never runs and the locale comes - // from FALLBACK_LOCALE (en): state the asserted locale explicitly. - ctx.locale.setLocale('zh') - const fiber = ctx.plugin({ inject: [...inject], apply }) - await fiber.await() - return { ctx, fiber } -} - -describe('ui-job browser half', () => { - it('declares the services it binds', () => { - expect(inject).toEqual(['sessions', 'slots', 'locale']) - }) - - it('registers the header action, and fiber teardown removes it (HMR safety)', async () => { - const { ctx, fiber } = await bench() - expect(headerEntryIds(ctx)).toContain('job-list') - await fiber.dispose() - expect(headerEntryIds(ctx)).not.toContain('job-list') - }) - - it('registers both dictionaries under its own namespace and releases them with the fiber', async () => { - const { ctx, fiber } = await bench() - const translate = ctx.locale.bind(NS) - expect(translate('list.aria')).toBe(zh['list.aria']) - ctx.locale.setLocale('en') - expect(translate('list.aria')).toBe(en['list.aria']) - - // Withdrawn dictionaries leave the key unresolved rather than translated. - await fiber.dispose() - expect(translate('list.aria')).not.toBe(en['list.aria']) - }) - - it('keeps the English dictionary key-identical to the Chinese source of truth', () => { - expect(Object.keys(en).sort()).toEqual(Object.keys(zh).sort()) - }) -}) - -describe('ui-job node half', () => { - it('contributes no host behavior', () => { - // The node half exists only so the plugin appears in the Loader tree. - expect(applyNode).not.toThrow() - }) -}) - -describe('ui-job invariant companion', () => { - it('reserves package ownership under its declared companion name', async () => { - const ctx = new Context() - await ctx.plugin(InvariantRegistry, { enabled: true }) - const fiber = ctx.plugin(JobInvariant) - await fiber.await() - expect(JobInvariant.name).toBe('client-ui-jobs-invariant') - expect(JobInvariant.inject).toEqual(['invariants']) - // Emitting an unrelated event proves the companion installed no audit. - expect(() => { - Reflect.apply(ctx.emit.bind(ctx), undefined, ['unrelated/event']) - }).not.toThrow() - await fiber.dispose() - }) -}) diff --git a/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx b/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx deleted file mode 100644 index c3f016d58e..0000000000 --- a/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx +++ /dev/null @@ -1,241 +0,0 @@ -// @vitest-environment jsdom -import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' -import { act, cleanup, fireEvent, render, screen, within } from '@testing-library/react' -import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime' -import type { SessionListState } from '@deepseek-ai/dsh-api-session-controller/client' -import type { SessionJob as JobView } from '@deepseek-ai/dsh-api-session-controller/types' -import type { SessionId } from '@deepseek-ai/dsh-session/types' -import { JobListAction, type JobListActionProps } from '../src/client/JobListAction.tsx' -import { zh } from '../src/client/locales.ts' - -// Live rows render `now - startedAt`, so every assertion needs a pinned clock. -beforeEach(() => { - vi.useFakeTimers() - vi.setSystemTime(START) -}) - -afterEach(() => { - cleanup() - vi.useRealTimers() - vi.restoreAllMocks() -}) - -const SESSION = 'session' as SessionId -const START = 1_700_000_000_000 -const t: JobListActionProps['t'] = makeTranslate(zh) - -function job(over: Partial = {}): JobView { - return { - id: 'bash-1' as JobView['id'], - kind: 'bash', - label: 'pnpm run build', - status: 'running', - startedAt: START, - ...over, - } -} - -function props(jobs: readonly JobView[] | undefined): JobListActionProps { - const state = { - ids: [SESSION], - byId: {}, - current: SESSION, - phase: 'ready', - subagentsByParent: {}, - jobsBySession: jobs === undefined ? {} : { [SESSION]: jobs }, - currentAddress: undefined, - } satisfies SessionListState - function useSessions(select: (snapshot: SessionListState) => T): T { - return select(state) - } - return { sessionId: SESSION, useSessions, t } as unknown as JobListActionProps -} - -/** - * Rows in render order as `[kind, label, status, duration]`. Adjacent spans - * carry no whitespace between them, so the cells are read one element at a - * time rather than split out of a flattened string. - */ -function rowCells(): string[][] { - return within(screen.getByRole('list', { name: zh['list.aria'] })) - .getAllByRole('listitem') - .map(row => [...row.children] - .map(cell => cell.textContent ?? '') - .filter(text => text !== '')) -} - -describe('JobListAction visibility', () => { - it('renders nothing while the session has no jobs', () => { - const { container } = render() - expect(container.innerHTML).toBe('') - }) - - it('counts only live jobs, and falls back to the total when none are live', () => { - const { rerender } = render() - expect(screen.getByRole('button', { name: '2 个后台任务运行中' })).toBeDefined() - - rerender() - expect(screen.getByRole('button', { name: '1 个后台任务' })).toBeDefined() - }) - - it('closes and unmounts when the last job disappears while the list is open', () => { - const { container, rerender } = render() - fireEvent.click(screen.getByRole('button')) - expect(screen.getByRole('list', { name: zh['list.aria'] })).toBeDefined() - - rerender() - expect(container.innerHTML).toBe('') - }) -}) - -describe('JobListAction rows', () => { - it('orders live jobs by start, then settled jobs newest-first', () => { - render() - fireEvent.click(screen.getByRole('button')) - expect(rowCells()).toEqual([ - ['bash', 'earlier live', '运行中', '0秒'], - ['bash', 'later live', '运行中', '0秒'], - ['bash', 'new done', '已失败', '9秒'], - ['bash', 'old done', '已完成', '1秒'], - ]) - }) - - it('breaks a settled tie on start order so map iteration never decides it', () => { - render() - fireEvent.click(screen.getByRole('button')) - expect(rowCells().map(cells => cells[1])).toEqual(['first', 'second']) - }) - - it('prefers the producer detail over the generic status word', () => { - render() - fireEvent.click(screen.getByRole('button')) - expect(rowCells()[0]).toContain('signal: SIGTERM') - }) - - it('renders every status word, including the stopping transition', () => { - render() - fireEvent.click(screen.getByRole('button')) - const words = rowCells().map(cells => cells[2]) - expect(new Set(words)).toEqual(new Set(['运行中', '正在停止', '已完成', '已取消', '已失败'])) - }) -}) - -describe('JobListAction duration', () => { - it('advances a live row once per second and freezes a settled one', () => { - vi.setSystemTime(START + 1_000) - render() - fireEvent.click(screen.getByRole('button')) - expect(rowCells()[0]).toContain('1秒') - expect(rowCells()[1]).toContain('4秒') - - act(() => { vi.advanceTimersByTime(2_000) }) - expect(rowCells()[0]).toContain('3秒') - expect(rowCells()[1]).toContain('4秒') - }) - - it('widens to minutes and then hours, and never shows a negative figure', () => { - render() - fireEvent.click(screen.getByRole('button')) - expect(rowCells().map(cells => cells[3])).toEqual(['2小时3分', '2分5秒', '0秒']) - }) - - it('runs no clock while the list is closed', () => { - const interval = vi.spyOn(globalThis, 'setInterval') - render() - expect(interval).not.toHaveBeenCalled() - fireEvent.click(screen.getByRole('button')) - expect(interval).toHaveBeenCalledTimes(1) - }) - - it('runs no clock for an open list holding only settled jobs', () => { - const interval = vi.spyOn(globalThis, 'setInterval') - render() - fireEvent.click(screen.getByRole('button')) - expect(interval).not.toHaveBeenCalled() - }) -}) - -describe('JobListAction dismissal', () => { - it('closes on Escape and returns focus to the trigger', () => { - render() - const trigger = screen.getByRole('button') - fireEvent.click(trigger) - expect(trigger.getAttribute('aria-expanded')).toBe('true') - - fireEvent.keyDown(trigger, { key: 'Escape' }) - expect(trigger.getAttribute('aria-expanded')).toBe('false') - expect(document.activeElement).toBe(trigger) - }) - - it('ignores other keys and a closed-list Escape', () => { - render() - const trigger = screen.getByRole('button') - fireEvent.keyDown(trigger, { key: 'Escape' }) - expect(trigger.getAttribute('aria-expanded')).toBe('false') - - fireEvent.click(trigger) - fireEvent.keyDown(trigger, { key: 'ArrowDown' }) - expect(trigger.getAttribute('aria-expanded')).toBe('true') - }) - - it('closes on an outside pointer press but not on one inside', () => { - render() - const trigger = screen.getByRole('button') - fireEvent.click(trigger) - - fireEvent.pointerDown(screen.getByRole('list', { name: zh['list.aria'] })) - expect(trigger.getAttribute('aria-expanded')).toBe('true') - - fireEvent.pointerDown(document.body) - expect(trigger.getAttribute('aria-expanded')).toBe('false') - }) -}) - -describe('JobListAction wire tolerance', () => { - it('treats a settled job with no finishedAt as zero-duration and sorts it by start', () => { - // `finishedAt` is optional on the wire; the Host always sets it, so this - // covers a producer or carrier that ever stops doing so. - render() - fireEvent.click(screen.getByRole('button')) - expect(rowCells().map(cells => [cells[1], cells[3]])).toEqual([ - ['finished', '3秒'], - ['no finish', '0秒'], - ]) - }) - - it('falls back to start order when neither settled job carries a finish time', () => { - render() - fireEvent.click(screen.getByRole('button')) - expect(rowCells().map(cells => cells[1])).toEqual(['later', 'earlier']) - }) -}) diff --git a/packages/client/ui-jobs/tsconfig.json b/packages/client/ui-jobs/tsconfig.json deleted file mode 100644 index 727523a055..0000000000 --- a/packages/client/ui-jobs/tsconfig.json +++ /dev/null @@ -1,39 +0,0 @@ -{ - "extends": "../../../tsconfig.base.client.json", - "compilerOptions": { - "rootDir": "src", - "outDir": "lib/types" - }, - "include": [ - "src" - ], - "references": [ - { - "path": "../../api/session-controller/tsconfig.client.json" - }, - { - "path": "../../../vendor/cordis" - }, - { - "path": "../locale" - }, - { - "path": "../ui-conversation" - }, - { - "path": "../ui-primitives" - }, - { - "path": "../ui-renderer" - }, - { - "path": "../ui-session" - }, - { - "path": "../ui-slots" - }, - { - "path": "../../runtime-diagnostics/invariants" - } - ] -} diff --git a/packages/client/ui-jobs/tsdown.config.ts b/packages/client/ui-jobs/tsdown.config.ts deleted file mode 100644 index 550cd558a8..0000000000 --- a/packages/client/ui-jobs/tsdown.config.ts +++ /dev/null @@ -1,3 +0,0 @@ -import { clientBundle } from '../tsdown.client.ts' - -export default clientBundle('@deepseek-ai/dsh-client-ui-jobs', ['lib/types/index.js', 'lib/types/invariant.js']) diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts index 1a53958b6c..1533fe40dc 100644 --- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts +++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts @@ -1143,7 +1143,6 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ occupants: [ 'client-ui-activity ActivityListAction id \'activity-list\'', 'client-ui-agent-preset AgentPresetLabel id \'agent-preset\'', - 'client-ui-jobs JobListAction id \'job-list\'', ], replaceRisk: 'none', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.session.header.actions\', () => ctx.slots.register(\n { name: \'conversation.session.header.actions\', id: \'my-entry\', order: 100, label: \'My entry\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 32f9a464b7..cfbccd1d51 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1786,9 +1786,6 @@ importers: '@deepseek-ai/dsh-client-ui-input-trigger': specifier: workspace:^ version: link:../../client/ui-input-trigger - '@deepseek-ai/dsh-client-ui-jobs': - specifier: workspace:^ - version: link:../../client/ui-jobs '@deepseek-ai/dsh-client-ui-layout': specifier: workspace:^ version: link:../../client/ui-layout @@ -2100,6 +2097,9 @@ importers: '@deepseek-ai/dsh-api-activity-controller': specifier: workspace:^ version: link:../../api/activity-controller + '@deepseek-ai/dsh-api-session-controller': + specifier: workspace:^ + version: link:../../api/session-controller '@deepseek-ai/dsh-client-locale': specifier: workspace:^ version: link:../locale @@ -2802,45 +2802,6 @@ importers: specifier: ^18.2.0 version: 18.3.1 - packages/client/ui-jobs: - devDependencies: - '@deepseek-ai/cordis': - specifier: workspace:^ - version: link:../../../vendor/cordis - '@deepseek-ai/dsh-api-session-controller': - specifier: workspace:^ - version: link:../../api/session-controller - '@deepseek-ai/dsh-client-locale': - specifier: workspace:^ - version: link:../locale - '@deepseek-ai/dsh-client-test-runtime': - specifier: workspace:^ - version: link:../../test-support/client-runtime - '@deepseek-ai/dsh-client-ui-conversation': - specifier: workspace:^ - version: link:../ui-conversation - '@deepseek-ai/dsh-client-ui-primitives': - specifier: workspace:^ - version: link:../ui-primitives - '@deepseek-ai/dsh-client-ui-renderer': - specifier: workspace:^ - version: link:../ui-renderer - '@deepseek-ai/dsh-client-ui-session': - specifier: workspace:^ - version: link:../ui-session - '@deepseek-ai/dsh-client-ui-slots': - specifier: workspace:^ - version: link:../ui-slots - '@deepseek-ai/dsh-invariants': - specifier: workspace:^ - version: link:../../runtime-diagnostics/invariants - '@types/react': - specifier: ~18.3.1 - version: 18.3.31 - react: - specifier: ^18.2.0 - version: 18.3.1 - packages/client/ui-layout: devDependencies: '@deepseek-ai/cordis': diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts index 48bc458bfa..513f801566 100644 --- a/scripts/verify-package-readme-model-experience.ts +++ b/scripts/verify-package-readme-model-experience.ts @@ -86,7 +86,6 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly> = { 'packages/client/ui-chat': { kind: 'none', reason: 'Browser-side Chat presentation; registers nothing model-facing.' }, 'packages/client/ui-message-feedback': { kind: 'none', reason: 'Browser-side controls over the message-feedback sidecar; ratings and notes never enter the Session log, model context, or telemetry.' }, 'packages/client/ui-tool': { kind: 'none', reason: 'Browser-side Tool presentation layer; renders logged calls without changing model context.' }, - 'packages/client/ui-jobs': { kind: 'none', reason: 'Browser-side read-only projection of ctx.jobs records; dsh-tool-jobs owns the model-facing behavior.' }, 'packages/client/ui-workflow-run': { kind: 'none', reason: 'Browser-side UI plugin layer; renders durable workflow records without changing model context.' }, 'packages/client/ui-input-trigger': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' }, 'packages/client/ui-reference': { kind: 'indirect', reason: 'Browser-side reference selection delegates file guidance and session snapshot preparation to Host-owned providers.' }, diff --git a/tsconfig.base.json b/tsconfig.base.json index 11ae967059..d92abb6ab5 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -248,7 +248,6 @@ "@deepseek-ai/dsh-client-ui-skill": ["./packages/client/ui-skill/src"], "@deepseek-ai/dsh-client-ui-subagent": ["./packages/client/ui-subagent/src"], "@deepseek-ai/dsh-client-ui-settings-plugins": ["./packages/client/ui-settings-plugins/src"], - "@deepseek-ai/dsh-client-ui-jobs": ["./packages/client/ui-jobs/src"], "@deepseek-ai/dsh-client-ui-activity": ["./packages/client/ui-activity/src"], "@deepseek-ai/dsh-client-ui-plan": ["./packages/client/ui-plan/src"], "@deepseek-ai/dsh-client-ui-user-questions": ["./packages/client/ui-user-questions/src"], diff --git a/tsconfig.client.json b/tsconfig.client.json index 41f6aea41a..037f94a822 100644 --- a/tsconfig.client.json +++ b/tsconfig.client.json @@ -77,7 +77,6 @@ { "path": "./packages/client/ui-skill" }, { "path": "./packages/client/ui-reference" }, { "path": "./packages/client/ui-subagent" }, - { "path": "./packages/client/ui-jobs" }, { "path": "./packages/client/ui-activity" }, { "path": "./packages/client/ui-directory-picker-browse" }, { "path": "./packages/client/ui-directory-picker-native" }, From e200eadd736f22c3f532a0611d9afa99b97ca0dc Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 25 Aug 2026 14:23:12 +0800 Subject: [PATCH 005/100] =?UTF-8?q?fix(activity):=20acceptance=20refinemen?= =?UTF-8?q?ts=20=E2=80=94=20header=20band=20order=20and=20panel=20presenta?= =?UTF-8?q?tion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Interactive acceptance produced five presentation decisions: - Header band order is preset → tasks → subagent catalog. The root-session descendant count moves out of the breadcrumb (header.lineage) into the actions band (order 30) as SubagentCatalogAction and drops its '/' separator — a root session has no hierarchy to breadcrumb. Child sessions keep their root/child switcher unchanged. - The panel's copy control copies the command (TerminalBlock.copyText), not the output: a long command ellipsizes in the row, so the control is its only complete source, and it stays rendered before any output. - Commands and output lines wrap in full (--dsl-terminal-command-whitespace / --dsl-terminal-line-whitespace: pre-wrap), so the output region never scrolls sideways; the region caps at a fixed height and scrolls (--dsl-terminal-output-max-height) with maxLines: Infinity disabling the head/tail fold. - The panel draws no run-state dot (TerminalBlock.runStateDot: false) — the row above carries the same state — and reclaims the dot gutter via --dsl-terminal-gutter, which must target the card element itself because the variable is declared on it. The panel's left spine is gone with it. All TerminalBlock changes are opt-ins (props or --dsl-terminal-* variables); tool cards keep their shipped fold/ellipsis/dot behavior. --- .../2026-08-25-unified-task-list.i18n.yaml | 4 +- .../feature/2026-08-25-unified-task-list.md | 17 ++- .../2026-08-25-unified-task-list.zh.md | 17 ++- apps/web/tests/agent-preset-selection.e2e.ts | 5 +- .../agent-preset-selection/header.expected.md | 7 +- .../live-activity-stream/settled.expected.md | 2 +- .../streaming.expected.md | 2 +- .../src/client/ActivityListAction.module.css | 19 +++- .../src/client/ActivityListAction.tsx | 13 ++- .../activity-list-action.client.spec.tsx | 16 ++- .../client/ui-primitives/README.i18n.yaml | 4 +- packages/client/ui-primitives/README.md | 2 +- packages/client/ui-primitives/README.zh.md | 2 +- .../src/TerminalBlock.module.css | 19 ++-- .../ui-primitives/src/TerminalBlock.tsx | 28 +++-- .../tests/terminal-block.client.spec.tsx | 16 +++ packages/client/ui-subagent/README.i18n.yaml | 4 +- packages/client/ui-subagent/README.md | 4 +- packages/client/ui-subagent/README.zh.md | 4 +- .../client/SubagentHeaderLineage.module.css | 6 -- .../src/client/SubagentHeaderLineage.tsx | 52 ++++++--- .../client/ui-subagent/src/client/index.ts | 16 ++- .../tests/browser-plugin.client.spec.ts | 10 ++ .../tests/conversation-ui.client.spec.tsx | 101 +++++++++++------- .../src/client/slot-catalog.ts | 1 + 25 files changed, 261 insertions(+), 110 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.i18n.yaml b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.i18n.yaml index 031f01691a..0e65f2bce7 100644 --- a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.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 .agents/notes/implemented/feature/2026-08-25-unified-task-list.md -2026-08-25-unified-task-list.md: 9ce3e6d2b066a94ee738880f69b0ddf718a10b02 -2026-08-25-unified-task-list.zh.md: ab224fd082fb8d6408449716e68e6df6c648a281 +2026-08-25-unified-task-list.md: b098ea82e4762f9528ecd71bbd2b8095c540b900 +2026-08-25-unified-task-list.zh.md: 4e5a2ef5d616f73741670c1c7ad787df19069fdd diff --git a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.md b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.md index 9ce3e6d2b0..b098ea82e4 100644 --- a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.md +++ b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.md @@ -19,11 +19,26 @@ The service planes stay orthogonal; the join happens once, per row, in the UI pr Deliberately not joined: subagent delegation rows stay bare job rows (the subagent panel is their surface), and foreground commands stay in their tool cards — neither gains an activity producer. -## Alternatives rejected +## Alternatives considered - **Merge the services** — rejected for the cursor-semantics and model-visibility reasons above. - **Keep the job list and bolt output onto it** — leaves workflow runs (activities without jobs) homeless, forcing a second list to survive anyway. +## Refinements from browser acceptance + +Driving the merged list in the real app produced four presentation decisions, all scoped to the expanded panel and the header band: + +- **The header band order is preset → tasks → subagent catalog.** The root-session descendant count moved out of the breadcrumb (`header.lineage`) into the actions band (order 30) and dropped its `/` separator — a root session has no hierarchy to breadcrumb; child sessions keep their `root / child` switcher where the `/` is real. `SubagentCatalogAction` owns the moved seat; the lineage renderer now renders nothing on roots. +- **The panel's copy control copies the command** (`TerminalBlock.copyText`), not the output: a long command ellipsizes in the row, so the control is its only complete source, while output is selectable text below. Supplying `copyText` also keeps the control rendered before any output exists. +- **The panel scrolls instead of folding**: commands and output lines wrap in full (`--dsl-terminal-command-whitespace` / `--dsl-terminal-line-whitespace: pre-wrap`, so the output region never scrolls sideways) and the output region caps at a fixed height (`--dsl-terminal-output-max-height`) with `maxLines: Infinity` disabling the head/tail fold. +- **The panel draws no run-state dot** (`TerminalBlock.runStateDot: false`) — the row above it already carries the same state — and reclaims the dot gutter via `--dsl-terminal-gutter`. The panel's left spine was dropped with it. + +All four land as opt-ins on `TerminalBlock` (props or `--dsl-terminal-*` variables), so tool cards keep their shipped fold/ellipsis/dot behavior unchanged. + +## Testing + +Component suites cover the join (job lifecycle wins, activity supplies the panel, bare-job rows, standalone activities), sections, durations, and the panel options; `pnpm vitest run packages/client/ui-activity packages/client/ui-primitives packages/client/ui-subagent` runs them. The keyless web e2e pair (`background-job-list`, `live-activity-stream`) replays the merged list end to end against ARIA goldens; `agent-preset-selection` pins the header band order. + ## Consequences - The two web e2e scenarios (`background-job-list`, `live-activity-stream`) now assert one "Tasks" list; the job-list scenario's row gained a live-output panel, which is the join working end to end. diff --git a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md index ab224fd082..4e5a2ef5d6 100644 --- a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md +++ b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md @@ -19,11 +19,26 @@ 刻意不合并的:subagent 委托行保持裸 job 行(subagent 面板是它的呈现面),前台命令留在工具卡片里——两者都不接活动生产者。 -## 已否决的替代方案 +## 曾考虑的替代方案 - **合并服务层**——因上述游标语义与模型可见性理由否决。 - **保留 job 列表、把输出挂上去**——workflow 运行(无 job 的 activity)无处安放,第二个列表终究得活下来。 +## 浏览器验收带来的细化 + +在真实应用里驱动合并列表得出四个呈现决策,全部限定在展开面板与头部条带: + +- **头部条带顺序为 preset → 任务 → subagent 目录。** 根会话的后代数量从面包屑(`header.lineage`)移入操作区(order 30)并去掉 `/` 分隔符——根会话没有可面包屑的层级;子会话保留 `根 / 子` 切换器,那里的 `/` 是真实层级。移位后的席位由 `SubagentCatalogAction` 拥有;谱系 renderer 在根会话上不再渲染任何东西。 +- **面板的复制控件复制命令**(`TerminalBlock.copyText`)而非输出:长命令在行内被省略号截断,控件是它唯一的完整来源,而输出本身就是下方可选中的文本。提供 `copyText` 还让控件在任何输出出现之前就保持渲染。 +- **面板以滚动取代折叠**:命令与输出行完整换行(`--dsl-terminal-command-whitespace` / `--dsl-terminal-line-whitespace: pre-wrap`,输出区因此永不横向滚动),输出区以固定高度封顶(`--dsl-terminal-output-max-height`),`maxLines: Infinity` 禁用头尾折叠。 +- **面板不画运行状态点**(`TerminalBlock.runStateDot: false`)——上方的行已携带同一状态——并通过 `--dsl-terminal-gutter` 收回状态点落区。面板左侧竖线随之移除。 + +四项全部以 `TerminalBlock` 的可选项落地(prop 或 `--dsl-terminal-*` 变量),工具卡片保持既有的折叠/省略/状态点行为不变。 + +## 测试 + +组件套件覆盖 join(job 生命周期优先、activity 提供面板、裸 job 行、独立 activity)、分段、时长与面板选项;`pnpm vitest run packages/client/ui-activity packages/client/ui-primitives packages/client/ui-subagent` 运行它们。无密钥 web e2e 对(`background-job-list`、`live-activity-stream`)按 ARIA golden 端到端回放合并列表;`agent-preset-selection` 钉住头部条带顺序。 + ## 后果 - 两个 web e2e 场景(`background-job-list`、`live-activity-stream`)现在断言同一个"任务"列表;job 场景的行获得了实时输出面板,这正是 join 端到端生效的证据。 diff --git a/apps/web/tests/agent-preset-selection.e2e.ts b/apps/web/tests/agent-preset-selection.e2e.ts index df6a2baa36..c062e21367 100644 --- a/apps/web/tests/agent-preset-selection.e2e.ts +++ b/apps/web/tests/agent-preset-selection.e2e.ts @@ -280,8 +280,9 @@ describe('web e2e: agent-preset selection', () => { await compareOrRefreshGolden(HEADER_EXPECTED, snapshot, MODE) expect(snapshot).toContain('Minimal mode') expect(snapshot).toContain('button "1 subagent"') - expect(snapshot.indexOf('button "1 subagent"')).toBeLessThan(snapshot.indexOf('Minimal mode')) - expect(snapshot.indexOf('Minimal mode')).toBeLessThan(snapshot.indexOf('button "Session log"')) + // The preset label leads the header band; delegation navigation follows it. + expect(snapshot.indexOf('Minimal mode')).toBeLessThan(snapshot.indexOf('button "1 subagent"')) + expect(snapshot.indexOf('button "1 subagent"')).toBeLessThan(snapshot.indexOf('button "Session log"')) // Static chrome, not a control: the header can only report a composition // the host would refuse to change. expect(snapshot).not.toContain('button "Minimal mode"') diff --git a/apps/web/tests/snapshots/agent-preset-selection/header.expected.md b/apps/web/tests/snapshots/agent-preset-selection/header.expected.md index 9a9f380833..612edbc213 100644 --- a/apps/web/tests/snapshots/agent-preset-selection/header.expected.md +++ b/apps/web/tests/snapshots/agent-preset-selection/header.expected.md @@ -1,11 +1,10 @@ - navigation "Session hierarchy": - button "Seeded turn" [disabled] - - text: / - - button "1 subagent": - - text: 1 subagent - - img - img - text: Minimal mode +- button "1 subagent": + - text: 1 subagent + - img - button "Session log": - text: Session log - img diff --git a/apps/web/tests/snapshots/live-activity-stream/settled.expected.md b/apps/web/tests/snapshots/live-activity-stream/settled.expected.md index 2090dca51d..ecdcd4fea4 100644 --- a/apps/web/tests/snapshots/live-activity-stream/settled.expected.md +++ b/apps/web/tests/snapshots/live-activity-stream/settled.expected.md @@ -3,6 +3,6 @@ - button "Hide live output of printf 'streamed-%s\\n' marker-line; sleep 45" [expanded]: - text: "bash printf 'streamed-%s\\n' marker-line; sleep 45 signal: SIGTERM {{duration}}" - img - - text: done $ printf 'streamed-%s\n' marker-line; sleep 45 + - text: $ printf 'streamed-%s\n' marker-line; sleep 45 - button "Copy" - text: streamed-marker-line diff --git a/apps/web/tests/snapshots/live-activity-stream/streaming.expected.md b/apps/web/tests/snapshots/live-activity-stream/streaming.expected.md index ea906239aa..aa23b11410 100644 --- a/apps/web/tests/snapshots/live-activity-stream/streaming.expected.md +++ b/apps/web/tests/snapshots/live-activity-stream/streaming.expected.md @@ -3,6 +3,6 @@ - button "Hide live output of printf 'streamed-%s\\n' marker-line; sleep 45" [expanded]: - text: printf 'streamed-%s\n' marker-line; sleep 45 {{duration}} bash running - img - - text: running $ printf 'streamed-%s\n' marker-line; sleep 45 + - text: $ printf 'streamed-%s\n' marker-line; sleep 45 - button "Copy" - text: streamed-marker-line diff --git a/packages/client/ui-activity/src/client/ActivityListAction.module.css b/packages/client/ui-activity/src/client/ActivityListAction.module.css index d0d632ab34..93259a16d7 100644 --- a/packages/client/ui-activity/src/client/ActivityListAction.module.css +++ b/packages/client/ui-activity/src/client/ActivityListAction.module.css @@ -189,11 +189,22 @@ transform: rotate(180deg); } -/* Output hangs under its row behind a spine that ties the two together. */ .panel { - margin: 0 8px 8px 14px; - padding-left: 8px; - border-left: 2px solid var(--dsw-alias-border-l2); + margin: 0 8px 8px; + /* Long commands and output lines wrap in full instead of ellipsizing or + scrolling sideways, and the output region scrolls within a fixed height + instead of folding its middle lines. */ + --dsl-terminal-command-whitespace: pre-wrap; + --dsl-terminal-line-whitespace: pre-wrap; + --dsl-terminal-output-max-height: 288px; +} + +/* The row carries the state dot, so the panel omits its own and reclaims the + dot gutter down to an ordinary content inset. The override targets the card + element itself because the gutter variable is declared on it — a value + inherited from this container would lose to that declaration. */ +.panel :global([data-terminal]) { + --dsl-terminal-gutter: 12px; } .notice { diff --git a/packages/client/ui-activity/src/client/ActivityListAction.tsx b/packages/client/ui-activity/src/client/ActivityListAction.tsx index ef77df0e9c..8d6c9c43f3 100644 --- a/packages/client/ui-activity/src/client/ActivityListAction.tsx +++ b/packages/client/ui-activity/src/client/ActivityListAction.tsx @@ -62,8 +62,6 @@ const NO_JOBS: readonly SessionJob[] = [] /** Minimum gap kept between the popover and the viewport edges (the Menu primitive's portal margin). */ const VIEWPORT_MARGIN = 12 -/** Height cap for one live output panel inside the popover. */ -const PANEL_MAX_LINES = 16 function isLive(row: TaskRow): boolean { return row.status === 'running' || row.status === 'stopping' @@ -136,7 +134,11 @@ function terminalLabels(t: TranslateNS): TerminalBlockLabels { noOutput: t('terminal.noOutput'), collapseAria: t('terminal.collapseAria'), collapse: t('terminal.collapse'), + // The panel never caps lines (it scrolls), so the fold controls that + // would invoke these stay unrendered. + /* v8 ignore next */ expandAria: hidden => t('terminal.expandAria', { n: hidden }), + /* v8 ignore next */ expand: hidden => t('terminal.expand', { n: hidden }), } } @@ -288,7 +290,12 @@ function TaskItem({ row, view, expanded, now, onToggle, t }: { command={row.label} output={view.text} running={live} - maxLines={PANEL_MAX_LINES} + copyText={row.label} + // The row above the panel already carries the state dot. + runStateDot={false} + // The panel scrolls its output (a stylesheet height cap) instead + // of collapsing the middle. + maxLines={Number.POSITIVE_INFINITY} labels={labels} />
        diff --git a/packages/client/ui-activity/tests/activity-list-action.client.spec.tsx b/packages/client/ui-activity/tests/activity-list-action.client.spec.tsx index 6dbb9f4519..878aa21c23 100644 --- a/packages/client/ui-activity/tests/activity-list-action.client.spec.tsx +++ b/packages/client/ui-activity/tests/activity-list-action.client.spec.tsx @@ -192,7 +192,9 @@ describe('ActivityListAction rows and observation', () => { expect(items[1]?.textContent).toContain('exit code: 3') }) - it('marks killed rows and expands an overflowing panel through the collapse controls', () => { + it('marks killed rows, renders every output line unfolded, and copies the command', async () => { + const writeText = vi.fn().mockResolvedValue(undefined) + Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } }) const lines = Array.from({ length: 24 }, (_value, index) => `line ${index + 1}`).join('\n') const view: ObservedActivity = { activityId: 'bash-1' as ActivityId, @@ -208,9 +210,15 @@ describe('ActivityListAction rows and observation', () => { openList() expect(screen.getByText(zh['status.killed'])).toBeDefined() fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) - const expand = screen.getByRole('button', { name: zh['terminal.expandAria'].replace('{n}', '8') }) - fireEvent.click(expand) - expect(screen.getByRole('button', { name: zh['terminal.collapseAria'] })).toBeDefined() + // The panel scrolls instead of folding: every line renders, no fold control. + expect(screen.getByText('line 1')).toBeDefined() + expect(screen.getByText('line 24')).toBeDefined() + expect(screen.queryByRole('button', { name: zh['terminal.expandAria'].replace('{n}', '8') })).toBeNull() + // The panel draws no state dot or label of its own — the row carries it. + expect(screen.queryByText(zh['terminal.done'])).toBeNull() + // The copy control carries the command, not the output. + await act(async () => { fireEvent.click(screen.getByRole('button', { name: zh['terminal.copy'] })) }) + expect(writeText).toHaveBeenCalledWith('pnpm run build') }) it('orders live rows first by start and settled rows newest-first with tie-breaks', () => { diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml index a025628aa4..c4a07f5cc1 100644 --- a/packages/client/ui-primitives/README.i18n.yaml +++ b/packages/client/ui-primitives/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-primitives/README.md -README.md: 4df368b270511776896c74a55b0c1d2e684035d0 -README.zh.md: 77830a1f162e963709ea4d4d25c8393e7dd97d66 +README.md: 48550de318cdd637d97c23009d95215a793c9b62 +README.zh.md: 83fdaa927c04dd130b410ac885c0d110939f48b3 diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md index 4df368b270..48550de318 100644 --- a/packages/client/ui-primitives/README.md +++ b/packages/client/ui-primitives/README.md @@ -18,7 +18,7 @@ Pure React atoms (zero cordis): StateDot, DisclosureRow, ic_ds_* icons, Button/P ## Terminal output -`TerminalBlock` renders a shell command as a terminal surface: one prompt row per line of the command (the shortened `cwd` label on the first row only, since the view knows one working directory and a `cd` moves later lines elsewhere, then that line), the command's output, a status pill for a non-zero exit code or a terminating signal, and a copy control that writes the raw `output` prop. A run-state `StateDot` marks the call once, on the first row, out of flow in a gutter the card reserves as its own left padding, so the dot sits inside the card box yet left of the prompt text. It reaches three of `StateDot`'s states — the chase while `running`, red for the same exit status that renders the pill, green otherwise — so a card states whether its command is still running rather than leaving that to be inferred from the presence of output; a running block with a supplied `output` renders that live text under the running state (an undefined output keeps the historical prompt-only frame); it carries one visually hidden text label because `StateDot` is `aria-hidden`. One dot regardless of line count is deliberate: the exit status is the whole call's, so a dot per line would claim a per-line outcome the view does not carry. Command text is `white-space: pre`, so repeated spaces, tabs, and an indented continuation render verbatim while the row stays single-line and ellipsizes. ANSI escape sequences are parsed with `anser` (bundled into this package's browser artifact) into React spans; cursor movements replay into a per-line column buffer before inert controls are stripped, since carriage return and backspace only MOVE the cursor: `100%` + CR + `OK` alone shows `OK0%`, while the `\x1b[K` a spinner writes with its redraw erases the tail so `100%\r\x1b[KOK` shows `OK`. Erase-in-line is honored in all three parameter forms, the cursor advances by terminal columns (8-column tab stops, two for emoji and CJK, none for a combining mark), and SGR state is normalized per cell as a terminal stores it, threading across lines and closing at the state the line ended in; basic-16 foreground colors map onto `--dsw-*` tokens, while 256-palette and truecolor values pass through as literal rgb. Output keeps `white-space: pre` with horizontal scrolling, so column-aligned output holds its alignment instead of soft-wrapping, and collapses to a head slice plus a tail slice past `maxLines` (default 16) behind an expand button. Rationale: [the web terminal card note](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md). +`TerminalBlock` renders a shell command as a terminal surface: one prompt row per line of the command (the shortened `cwd` label on the first row only, since the view knows one working directory and a `cd` moves later lines elsewhere, then that line), the command's output, a status pill for a non-zero exit code or a terminating signal, and a copy control that writes the raw `output` prop — or the `copyText` override, which also keeps the control rendered before any output exists. A run-state `StateDot` marks the call once, on the first row, out of flow in a gutter the card reserves as its own left padding, so the dot sits inside the card box yet left of the prompt text. It reaches three of `StateDot`'s states — the chase while `running`, red for the same exit status that renders the pill, green otherwise — so a card states whether its command is still running rather than leaving that to be inferred from the presence of output; a running block with a supplied `output` renders that live text under the running state (an undefined output keeps the historical prompt-only frame); it carries one visually hidden text label because `StateDot` is `aria-hidden`. One dot regardless of line count is deliberate: the exit status is the whole call's, so a dot per line would claim a per-line outcome the view does not carry. `runStateDot: false` omits the dot and its hidden label for hosts whose surrounding row already carries the same state; they reclaim the dot gutter via `--dsl-terminal-gutter`. Command text is `white-space: pre`, so repeated spaces, tabs, and an indented continuation render verbatim while the row stays single-line and ellipsizes; rebinding `--dsl-terminal-command-whitespace` to `pre-wrap` wraps long commands in full instead. ANSI escape sequences are parsed with `anser` (bundled into this package's browser artifact) into React spans; cursor movements replay into a per-line column buffer before inert controls are stripped, since carriage return and backspace only MOVE the cursor: `100%` + CR + `OK` alone shows `OK0%`, while the `\x1b[K` a spinner writes with its redraw erases the tail so `100%\r\x1b[KOK` shows `OK`. Erase-in-line is honored in all three parameter forms, the cursor advances by terminal columns (8-column tab stops, two for emoji and CJK, none for a combining mark), and SGR state is normalized per cell as a terminal stores it, threading across lines and closing at the state the line ended in; basic-16 foreground colors map onto `--dsw-*` tokens, while 256-palette and truecolor values pass through as literal rgb. Output keeps `white-space: pre` with horizontal scrolling, so column-aligned output holds its alignment instead of soft-wrapping (`--dsl-terminal-line-whitespace: pre-wrap` opts a host into wrapped lines with no sideways scroll), and collapses to a head slice plus a tail slice past `maxLines` (default 16; Infinity disables the fold for hosts that cap height through `--dsl-terminal-output-max-height` instead) behind an expand button. Rationale: [the web terminal card note](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md). ## Read rendering diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md index 77830a1f16..83fdaa927c 100644 --- a/packages/client/ui-primitives/README.zh.md +++ b/packages/client/ui-primitives/README.zh.md @@ -18,7 +18,7 @@ ## 终端输出 -`TerminalBlock` 将一条 shell 命令渲染为终端表层:命令的每一行各占一个提示行(缩短后的 `cwd` 标签只出现在第一行,因为视图只知道一个工作目录,而一个 `cd` 就会让后面的行去到别处,标签之后是该行)、命令输出、非零退出码或终止信号对应的状态胶囊,以及写入原始 `output` prop 的复制控件。一枚运行状态 `StateDot` 为整次调用标记一次,位于第一行,以脱离文档流的方式落在卡片以自身左内边距预留的落区中,因此它位于卡片盒之内、提示文字之左。它用到 `StateDot` 的三种状态——`running` 期间为追逐动画,与渲染状态胶囊相同的退出状态为红色,其余为绿色——因此卡片直接陈述其命令是否仍在运行,而不是让人从有无输出中推断;运行中且提供了 `output` 的块会在 running 状态下渲染这段实时文本(未提供 output 则保持历史上的仅提示行画面);由于 `StateDot` 是 `aria-hidden`,它携带一处视觉隐藏的文本标签。无论多少行都只有一枚状态点是有意为之:退出状态属于整次调用,因此每行一枚就会声称一个视图并不携带的逐行结果。命令文本使用 `white-space: pre`,因此重复空格、制表符与缩进续行都原样呈现,同时该行仍保持单行并以省略号截断。ANSI 转义序列通过 `anser`(打进本包浏览器产物)解析为 React span;光标移动在剥除无显示意义控制符之前先重放进逐行的列缓冲,因为回车与退格**只移动**光标:单是 `100%` 加回车再加 `OK` 显示为 `OK0%`,而 spinner 随重绘写出的 `\x1b[K` 会擦掉尾巴,因此 `100%\r\x1b[KOK` 显示为 `OK`。行内擦除的三种参数形式都被遵循,光标按终端列推进(8 列制表位;emoji 与 CJK 占两列;组合标记不占列),SGR 状态按单元格归一化存储,与终端一致,并跨行延续、在行结束时的状态处收束;基础 16 色前景色映射到 `--dsw-*` token,而 256 色板与真彩色值按字面 rgb 透传。输出保持 `white-space: pre` 并支持横向滚动,因此按列对齐的输出保留其对齐而不会软换行;超过 `maxLines`(默认 16)时折叠为头部切片加尾部切片,由展开按钮控制。原理:[Web 终端卡片笔记](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md)。 +`TerminalBlock` 将一条 shell 命令渲染为终端表层:命令的每一行各占一个提示行(缩短后的 `cwd` 标签只出现在第一行,因为视图只知道一个工作目录,而一个 `cd` 就会让后面的行去到别处,标签之后是该行)、命令输出、非零退出码或终止信号对应的状态胶囊,以及写入原始 `output` prop 的复制控件——或写入 `copyText` 覆盖值,提供它还会让控件在任何输出出现之前就保持渲染。一枚运行状态 `StateDot` 为整次调用标记一次,位于第一行,以脱离文档流的方式落在卡片以自身左内边距预留的落区中,因此它位于卡片盒之内、提示文字之左。它用到 `StateDot` 的三种状态——`running` 期间为追逐动画,与渲染状态胶囊相同的退出状态为红色,其余为绿色——因此卡片直接陈述其命令是否仍在运行,而不是让人从有无输出中推断;运行中且提供了 `output` 的块会在 running 状态下渲染这段实时文本(未提供 output 则保持历史上的仅提示行画面);由于 `StateDot` 是 `aria-hidden`,它携带一处视觉隐藏的文本标签。无论多少行都只有一枚状态点是有意为之:退出状态属于整次调用,因此每行一枚就会声称一个视图并不携带的逐行结果。`runStateDot: false` 为外围行已携带同一状态的宿主省去状态点及其隐藏标签;此类宿主通过 `--dsl-terminal-gutter` 收回状态点落区。命令文本使用 `white-space: pre`,因此重复空格、制表符与缩进续行都原样呈现,同时该行仍保持单行并以省略号截断;把 `--dsl-terminal-command-whitespace` 重绑为 `pre-wrap` 则让长命令完整换行。ANSI 转义序列通过 `anser`(打进本包浏览器产物)解析为 React span;光标移动在剥除无显示意义控制符之前先重放进逐行的列缓冲,因为回车与退格**只移动**光标:单是 `100%` 加回车再加 `OK` 显示为 `OK0%`,而 spinner 随重绘写出的 `\x1b[K` 会擦掉尾巴,因此 `100%\r\x1b[KOK` 显示为 `OK`。行内擦除的三种参数形式都被遵循,光标按终端列推进(8 列制表位;emoji 与 CJK 占两列;组合标记不占列),SGR 状态按单元格归一化存储,与终端一致,并跨行延续、在行结束时的状态处收束;基础 16 色前景色映射到 `--dsw-*` token,而 256 色板与真彩色值按字面 rgb 透传。输出保持 `white-space: pre` 并支持横向滚动,因此按列对齐的输出保留其对齐而不会软换行(`--dsl-terminal-line-whitespace: pre-wrap` 让宿主选择换行且不再横向滚动);超过 `maxLines`(默认 16;传 Infinity 可禁用折叠,供改用 `--dsl-terminal-output-max-height` 限高滚动的宿主)时折叠为头部切片加尾部切片,由展开按钮控制。原理:[Web 终端卡片笔记](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md)。 ## Read 渲染 diff --git a/packages/client/ui-primitives/src/TerminalBlock.module.css b/packages/client/ui-primitives/src/TerminalBlock.module.css index 7a74327c74..318df9df3a 100644 --- a/packages/client/ui-primitives/src/TerminalBlock.module.css +++ b/packages/client/ui-primitives/src/TerminalBlock.module.css @@ -110,15 +110,18 @@ color: var(--dsw-alias-label-tertiary); } -/* `pre`, not `nowrap`: the prompt row renders the command verbatim, and - `nowrap` collapses the repeated spaces, tabs, and alignment of an indented - continuation. Both hold the single row and the ellipsis. */ +/* Default `pre`, not `nowrap`: the prompt row renders the command verbatim, + and `nowrap` would collapse the repeated spaces, tabs, and alignment of an + indented continuation. Hosts opt into wrapping long commands by rebinding + the variable to `pre-wrap`; the ellipsis then simply never engages, and + overflow-wrap is inert while white-space stays `pre`. */ .command { min-width: 0; color: var(--dsw-alias-label-primary); overflow: hidden; text-overflow: ellipsis; - white-space: pre; + white-space: var(--dsl-terminal-command-whitespace, pre); + overflow-wrap: anywhere; } /* Capped to the prompt's line height (Pill's own 24px height would exceed a @@ -176,10 +179,14 @@ margin: 6px; } -/* No wrapping, no word-break: alignment is the payload of terminal output. */ +/* Default `pre`: alignment is the payload of terminal output. Hosts opt + into wrapping long lines by rebinding the variable to `pre-wrap`, which + also keeps the output region from ever scrolling sideways; overflow-wrap + is inert while white-space stays `pre`. */ .line { min-height: var(--dsl-terminal-line-height); - white-space: pre; + white-space: var(--dsl-terminal-line-whitespace, pre); + overflow-wrap: anywhere; } .expand { diff --git a/packages/client/ui-primitives/src/TerminalBlock.tsx b/packages/client/ui-primitives/src/TerminalBlock.tsx index 8f87db9741..34eab4e5d0 100644 --- a/packages/client/ui-primitives/src/TerminalBlock.tsx +++ b/packages/client/ui-primitives/src/TerminalBlock.tsx @@ -61,6 +61,18 @@ export interface TerminalBlockProps { running?: boolean | undefined /** Height cap in output lines before the middle collapses (default {@link DEFAULT_TERMINAL_MAX_LINES}); Infinity disables the cap. */ maxLines?: number | undefined + /** + * Copy-control payload override; the control copies the raw output when + * absent. Supplying it also keeps the control rendered before any output + * exists — a command is copyable before it prints. + */ + copyText?: string | undefined + /** + * Draw the run-state dot and its assistive label in the card gutter + * (default true). Hosts whose surrounding row already carries the same + * state omit both and reclaim the gutter via `--dsl-terminal-gutter`. + */ + runStateDot?: boolean | undefined /** Extra class merged onto the wrapper (callers position; this component draws). */ className?: string | undefined /** Localized display copy supplied by the owning render site. */ @@ -155,6 +167,8 @@ export function TerminalBlock({ signal, running = false, maxLines = DEFAULT_TERMINAL_MAX_LINES, + copyText, + runStateDot = true, className, labels, }: TerminalBlockProps) { @@ -166,7 +180,7 @@ export function TerminalBlock({ // newline (`line\n\x1b[0m`) leaves the string not ending in one while still // producing a last line with nothing visible in it. A genuinely blank final // line — the double newline — survives, since it has a real empty line before - // the terminator. The copy control still copies `text` untouched. + // the terminator. The copy control's payload is unaffected. const lines = useMemo(() => { const parsed = parseAnsiLines(text) const last = parsed[parsed.length - 1] @@ -175,9 +189,9 @@ export function TerminalBlock({ return terminated ? parsed.slice(0, -1) : parsed }, [text]) const [expanded, setExpanded] = useState(false) - // The raw output, never the rendered tree: the prompt line and the status pill - // are chrome the user did not run. - const { copied, onCopy } = useCopyFeedback(text) + // The raw output (or the caller's override), never the rendered tree: the + // prompt line and the status pill are chrome the user did not run. + const { copied, onCopy } = useCopyFeedback(copyText ?? text) const onToggle = useCallback(() => { setExpanded(value => !value) }, []) @@ -202,14 +216,14 @@ export function TerminalBlock({
        - {state.label} + {runStateDot && {state.label}} {commandLines.map((line, index) => (
        {/* One dot for the card, on the first row: the exit status the view carries is the whole call's, and bash reports no per-command status, so a dot per row would assert a per-line outcome nothing here knows. */} - {index === 0 && } + {index === 0 && runStateDot && } {/* The cwd labels the CALL, so only its first row carries it. The view knows one working directory — where the call started — and a later line may well run somewhere else (a `cd` in the @@ -224,7 +238,7 @@ export function TerminalBlock({ ))}
        {status !== undefined && {status}} - {(!running || output !== undefined) && !empty && ( + {(copyText !== undefined || ((!running || output !== undefined) && !empty)) && ( diff --git a/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx b/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx index 886661b396..b4e6d7b151 100644 --- a/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx +++ b/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx @@ -98,6 +98,22 @@ describe('TerminalBlock states', () => { expect(view.container.firstElementChild?.getAttribute('data-running')).toBe('') }) + it('copyText overrides the copy payload and keeps the control before any output', async () => { + const writeText = vi.fn().mockResolvedValue(undefined) + Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } }) + const view = render() + // No output yet, but the command is already copyable. + const button = view.getByRole('button', { name: '复制' }) + await act(async () => { fireEvent.click(button) }) + expect(writeText).toHaveBeenCalledWith('npm run build --verbose') + }) + + it('omits the run-state dot and its assistive label when the host carries the state', () => { + const view = render() + expect(view.container.querySelector('[class*="runState"]')).toBeNull() + expect(view.queryByText('运行中')).toBeNull() + }) + it('running with supplied output streams the live text and keeps it copyable', () => { const view = render() expect(view.getByText('partial')).toBeTruthy() diff --git a/packages/client/ui-subagent/README.i18n.yaml b/packages/client/ui-subagent/README.i18n.yaml index 7456c19675..3d1b41e366 100644 --- a/packages/client/ui-subagent/README.i18n.yaml +++ b/packages/client/ui-subagent/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-subagent/README.md -README.md: d4a804a94b0f2cb295fd29c09c7f32385e423495 -README.zh.md: 3cec2109cbb5f85617cf69155c5582ee43496f09 +README.md: 67240628bf91e28e3b1a226f364f2d549b28695c +README.zh.md: 1c45ce74e4c04edef22a6a59b6a041c6728cbe9a diff --git a/packages/client/ui-subagent/README.md b/packages/client/ui-subagent/README.md index d4a804a94b..67240628bf 100644 --- a/packages/client/ui-subagent/README.md +++ b/packages/client/ui-subagent/README.md @@ -2,9 +2,9 @@ English | [中文](README.zh.md) -Web subagent feature owner: contributes current-title lineage navigation to `conversation.session.header.lineage`, reason-specific read-only replacements to the conversation composer chain, and the existing `@` reference source to `ctx.inputTriggers`. +Web subagent feature owner: contributes current-title lineage navigation to `conversation.session.header.lineage`, the root-session descendant-count entry to `conversation.session.header.actions` (ordered after the task list), reason-specific read-only replacements to the conversation composer chain, and the existing `@` reference source to `ctx.inputTriggers`. -The header lineage renderer reads `subagentsByParent` and session summaries through the standard `useSessions` hook. On an ordinary session it preserves the current title and, when descendants exist, appends `/` plus the descendant-count dropdown before the header action row. Every subagent breadcrumb uses the count trigger's 12px type scale and combines its title with a fixed double chevron; the current breadcrumb keeps primary color and weight 500, while ancestors use tertiary color and weight 400. Hovering a combined control for 150ms opens its direct-parent catalog, ArrowDown remains the keyboard entry path, and clicking an ancestor cancels a pending menu and navigates upward without opening it. Each catalog enables sibling switching and bolds its selected row; a catalog label overrides the session-summary title, and every switcher whose catalog has not loaded requests it automatically. Only the current subagent appends its own descendant-count dropdown. Long breadcrumb titles truncate while the chevron remains visible. The count trigger covers the complete subagent-only descendant lineage, stops at ordinary forks, and shows ongoing activity when any counted descendant is running. The compact tree remains direct-catalog authoritative: continuable and one-shot rows display mode plus `running`/`inactive` activity and an optional log-backed title, while the trailing column stacks total durable provider usage above active-turn duration. Token totals sum the four disjoint `tokenUsage` buckets. Visual duration stays exact to the second below one day, then uses at most two adjacent units—days/hours, approximate months/days, or approximate years/months—while hover and the accessible name retain the exact day/hour/minute/second value. Duration sums completed `subagentTiming` turns, advances once per second only for an open turn on a running child, and freezes after the child becomes inactive; an interrupted open turn is bounded by its same-cut `active.through`, never by newer session metadata. An unlabeled one-shot row falls back to its session id, while corrupt, unsupported, or unavailable rows remain readable but disabled. Each healthy row's `hasChildren` hint determines disclosure before interaction, so known leaves never show an arrow; a catalog level reserves the disclosure column only when at least one healthy row is a branch, allowing branchless levels to start at the leading status marker. Expanding a branch immediately reserves one disabled loading row per known direct descendant, then lazily replaces them with that child's authoritative catalog. Every visible branch is reported to the runtime so membership frames cause a debounced refresh only where the tree is being consumed. Selecting any depth calls `SessionRuntime.openSubagent()` with the row's exact `{parentSessionId, childSessionId, mode}` address. Component-local state owns tree visibility, expanded branches, keyboard focus, and the running-duration clock. ArrowRight/ArrowLeft expand and collapse branches; ArrowUp/ArrowDown, Home, End, and Escape navigate or close the tree; closing returns focus to the trigger. Styling uses tokens only. +The header lineage renderer reads `subagentsByParent` and session summaries through the standard `useSessions` hook. On an ordinary session the lineage slot stays empty; when descendants exist, the descendant-count dropdown renders in the header actions band after the task list, with no breadcrumb separator. Every subagent breadcrumb uses the count trigger's 12px type scale and combines its title with a fixed double chevron; the current breadcrumb keeps primary color and weight 500, while ancestors use tertiary color and weight 400. Hovering a combined control for 150ms opens its direct-parent catalog, ArrowDown remains the keyboard entry path, and clicking an ancestor cancels a pending menu and navigates upward without opening it. Each catalog enables sibling switching and bolds its selected row; a catalog label overrides the session-summary title, and every switcher whose catalog has not loaded requests it automatically. Only the current subagent appends its own descendant-count dropdown. Long breadcrumb titles truncate while the chevron remains visible. The count trigger covers the complete subagent-only descendant lineage, stops at ordinary forks, and shows ongoing activity when any counted descendant is running. The compact tree remains direct-catalog authoritative: continuable and one-shot rows display mode plus `running`/`inactive` activity and an optional log-backed title, while the trailing column stacks total durable provider usage above active-turn duration. Token totals sum the four disjoint `tokenUsage` buckets. Visual duration stays exact to the second below one day, then uses at most two adjacent units—days/hours, approximate months/days, or approximate years/months—while hover and the accessible name retain the exact day/hour/minute/second value. Duration sums completed `subagentTiming` turns, advances once per second only for an open turn on a running child, and freezes after the child becomes inactive; an interrupted open turn is bounded by its same-cut `active.through`, never by newer session metadata. An unlabeled one-shot row falls back to its session id, while corrupt, unsupported, or unavailable rows remain readable but disabled. Each healthy row's `hasChildren` hint determines disclosure before interaction, so known leaves never show an arrow; a catalog level reserves the disclosure column only when at least one healthy row is a branch, allowing branchless levels to start at the leading status marker. Expanding a branch immediately reserves one disabled loading row per known direct descendant, then lazily replaces them with that child's authoritative catalog. Every visible branch is reported to the runtime so membership frames cause a debounced refresh only where the tree is being consumed. Selecting any depth calls `SessionRuntime.openSubagent()` with the row's exact `{parentSessionId, childSessionId, mode}` address. Component-local state owns tree visibility, expanded branches, keyboard focus, and the running-duration clock. ArrowRight/ArrowLeft expand and collapse branches; ArrowUp/ArrowDown, Home, End, and Escape navigate or close the tree; closing returns focus to the trigger. Styling uses tokens only. A one-shot child always elects a read-only composer that identifies the transcript as a completed execution record. A continuable child does so only when its exact parent is unavailable and the child is not running, with copy explaining the recovery path; while such a child still runs, the selector yields to the ordinary composer, whose input and Send action are disabled but whose independent Stop stays usable, and the takeover returns once it stops. A continuable child with a live parent keeps the ordinary input chrome, whose Session routes prompts through `subagent.prompt`: typing and Send stay available while the child runs because every follow-up joins the child's FIFO inbox, while an independent Stop routes through `subagent.interrupt`. This package never receives host context or calls a model-facing tool. The catalog and composer behavior are specified by the [Web subagent conversations Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md) and the [current-turn interrupt Agent Note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.md). diff --git a/packages/client/ui-subagent/README.zh.md b/packages/client/ui-subagent/README.zh.md index 3cec2109cb..1c45ce74e4 100644 --- a/packages/client/ui-subagent/README.zh.md +++ b/packages/client/ui-subagent/README.zh.md @@ -2,9 +2,9 @@ [English](README.md) | 中文 -Web subagent 功能 owner:向 `conversation.session.header.lineage` 贡献当前 title 谱系导航,向会话编辑器链贡献按原因区分的只读替代呈现,并保留注册到 `ctx.inputTriggers` 的既有 `@` 引用 source。 +Web subagent 功能 owner:向 `conversation.session.header.lineage` 贡献当前 title 谱系导航,向 `conversation.session.header.actions` 贡献根会话的后代数量入口(排在任务列表之后),向会话编辑器链贡献按原因区分的只读替代呈现,并保留注册到 `ctx.inputTriggers` 的既有 `@` 引用 source。 -页头谱系 renderer 通过标准 `useSessions` 钩子读取 `subagentsByParent` 与会话摘要。普通会话保留当前 title,并在存在后代时,于页头操作行之前追加 `/` 和后代数量下拉菜单。每一级 subagent 面包屑都使用数量触发器的 12px 字号,并将 title 与固定显示的双向箭头组合成一个控件;当前面包屑保留主标签颜色和 500 字重,祖先面包屑则使用三级标签颜色和 400 字重。悬停组合控件 150ms 后会打开其直接 parent 目录,ArrowDown 保留为键盘入口;点击祖先面包屑会取消待打开的菜单并仅向上导航。每个目录都可切换 sibling,并会加粗选中行;目录 label 优先于会话摘要 title,尚未加载目录的每个切换器都会自动请求该目录。只有当前 subagent 会追加自己的后代数量下拉菜单。过长的面包屑 title 会截断,而双向箭头始终保留。数量触发器会统计仅含 subagent 的完整后代谱系,在普通 fork 处停止,并在任一计入统计的后代处于 `running` 时显示活动仍在进行。紧凑树仍以直接目录为权威依据:可继续和 one-shot 行会显示 mode、`running`/`inactive` 活动状态和由日志支撑的可选 title,尾随列则在上行显示提供方的持久化 token 用量总计,在下行显示活跃轮次耗时。token 用量总计为四个互不重叠的 `tokenUsage` 桶之和。视觉耗时在不足一天时精确到秒,达到一天后则最多使用两个相邻单位——天/小时、近似月份/天或近似年份/月份——而悬停信息与无障碍名称会保留精确的天/小时/分钟/秒数值。耗时会累加已完成的 `subagentTiming` 轮次,仅在运行中 child 存在未结束轮次时每秒递增一次,并在 child 变为 inactive 后冻结;被中断的未结束轮次以其同一切面的 `active.through` 为上界,绝不使用更新的会话元数据。没有 label 的 one-shot 行会回退到其会话 id,而损坏、不受支持或不可用的行仍保持可读但禁用。每个健康行的 `hasChildren` 提示会在交互前决定是否显示展开控件,因此已知叶子节点从不显示箭头;每层目录仅在其中至少一个健康行是分支时才预留展开列,使完全不含分支的层级能从最前面的状态标记开始。展开分支时,会立即为每个已知直接后代预留一行禁用的加载行,随后再用该 child 的权威目录懒加载结果替换这些占位行。每个可见分支都会上报给运行时,使成员帧只在树正被消费的位置触发去抖动刷新。选择任意深度的条目都会使用该行的确切地址 `{parentSessionId, childSessionId, mode}` 调用 `SessionRuntime.openSubagent()`。组件局部状态负责树的可见性、已展开分支、键盘焦点与运行中耗时时钟。ArrowRight/ArrowLeft 展开和折叠分支;ArrowUp/ArrowDown、Home、End 与 Escape 用于导航或关闭树;关闭后焦点返回触发器。样式只使用 token。 +页头谱系 renderer 通过标准 `useSessions` 钩子读取 `subagentsByParent` 与会话摘要。普通会话的谱系槽保持为空;存在后代时,后代数量下拉菜单渲染在页头操作区里、任务列表之后,不带任何面包屑分隔符。每一级 subagent 面包屑都使用数量触发器的 12px 字号,并将 title 与固定显示的双向箭头组合成一个控件;当前面包屑保留主标签颜色和 500 字重,祖先面包屑则使用三级标签颜色和 400 字重。悬停组合控件 150ms 后会打开其直接 parent 目录,ArrowDown 保留为键盘入口;点击祖先面包屑会取消待打开的菜单并仅向上导航。每个目录都可切换 sibling,并会加粗选中行;目录 label 优先于会话摘要 title,尚未加载目录的每个切换器都会自动请求该目录。只有当前 subagent 会追加自己的后代数量下拉菜单。过长的面包屑 title 会截断,而双向箭头始终保留。数量触发器会统计仅含 subagent 的完整后代谱系,在普通 fork 处停止,并在任一计入统计的后代处于 `running` 时显示活动仍在进行。紧凑树仍以直接目录为权威依据:可继续和 one-shot 行会显示 mode、`running`/`inactive` 活动状态和由日志支撑的可选 title,尾随列则在上行显示提供方的持久化 token 用量总计,在下行显示活跃轮次耗时。token 用量总计为四个互不重叠的 `tokenUsage` 桶之和。视觉耗时在不足一天时精确到秒,达到一天后则最多使用两个相邻单位——天/小时、近似月份/天或近似年份/月份——而悬停信息与无障碍名称会保留精确的天/小时/分钟/秒数值。耗时会累加已完成的 `subagentTiming` 轮次,仅在运行中 child 存在未结束轮次时每秒递增一次,并在 child 变为 inactive 后冻结;被中断的未结束轮次以其同一切面的 `active.through` 为上界,绝不使用更新的会话元数据。没有 label 的 one-shot 行会回退到其会话 id,而损坏、不受支持或不可用的行仍保持可读但禁用。每个健康行的 `hasChildren` 提示会在交互前决定是否显示展开控件,因此已知叶子节点从不显示箭头;每层目录仅在其中至少一个健康行是分支时才预留展开列,使完全不含分支的层级能从最前面的状态标记开始。展开分支时,会立即为每个已知直接后代预留一行禁用的加载行,随后再用该 child 的权威目录懒加载结果替换这些占位行。每个可见分支都会上报给运行时,使成员帧只在树正被消费的位置触发去抖动刷新。选择任意深度的条目都会使用该行的确切地址 `{parentSessionId, childSessionId, mode}` 调用 `SessionRuntime.openSubagent()`。组件局部状态负责树的可见性、已展开分支、键盘焦点与运行中耗时时钟。ArrowRight/ArrowLeft 展开和折叠分支;ArrowUp/ArrowDown、Home、End 与 Escape 用于导航或关闭树;关闭后焦点返回触发器。样式只使用 token。 one-shot child 始终选用只读编辑器,并将 transcript(文本记录)说明为已完成的执行记录。可继续 child 仅在其确切 parent 不可用且 child 未在运行时选用只读编辑器,并以文案说明恢复路径;此类 child 仍在运行期间,selector 会让位给普通编辑器——其输入区与 Send 操作被禁用,但独立的 Stop 保持可用,停止后只读替代恢复。确切 parent 存活时,可继续 child 保留普通输入 chrome,其会话通过 `subagent.prompt` 路由提示词:child 运行期间输入和 Send 保持可用,因为每条后续消息都会进入 child 的 FIFO inbox,而独立的 Stop 经由 `subagent.interrupt` 路由。本包绝不接收宿主上下文,也不调用面向模型的工具。目录与编辑器行为由 [Web subagent 对话 Agent Note](../../../.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md) 与[当前轮次中断 Agent Note](../../../.agents/notes/implemented/feature/2026-08-06-continuable-subagent-interrupt.zh.md) 规定。 diff --git a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css index 68b16940d9..c047a09c04 100644 --- a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css +++ b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.module.css @@ -55,12 +55,6 @@ flex: none; } -.separator { - color: var(--dsw-alias-label-caption); - font-size: 14px; - line-height: 20px; -} - .activitySlot { display: inline-flex; flex: none; diff --git a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx index 2660ba3a0f..faacc43061 100644 --- a/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx +++ b/packages/client/ui-subagent/src/client/SubagentHeaderLineage.tsx @@ -439,8 +439,6 @@ function CatalogRows({ interface CatalogDropdownSharedProps extends SubagentCatalogInjected { /** Session whose direct catalog roots the tree. */ rootSessionId: SessionId - /** Whether an ordinary title needs a breadcrumb separator before its count. */ - separator?: boolean useSessions: SubagentHeaderLineageProps['useSessions'] t: TranslateNS } @@ -482,7 +480,7 @@ function catalogMenuPosition(trigger: HTMLButtonElement): CSSProperties { /** One trigger-plus-tree dropdown over the catalog rooted at `rootSessionId`. */ function CatalogDropdown({ - rootSessionId, currentSessionId, displayTitle, openTitle, variant, separator = false, + rootSessionId, currentSessionId, displayTitle, openTitle, variant, useSessions, openChild, refresh, setCatalogOpen, t, }: CatalogDropdownProps) { const ancestorSwitcher = variant === 'switcher' && openTitle !== undefined @@ -731,7 +729,6 @@ function CatalogDropdown({ onMouseEnter={scheduleHoverOpen} onMouseLeave={scheduleHoverClose} > - {separator && /} +
        + +
        + ) +} + +describe('useDismissOnOutsidePointer', () => { + it('closes on an outside pointerdown and ignores inside ones', () => { + const setOpen = vi.fn() + const view = render() + fireEvent.pointerDown(view.getByText('inside')) + expect(setOpen).not.toHaveBeenCalled() + fireEvent.pointerDown(view.getByTestId('outside')) + expect(setOpen).toHaveBeenCalledWith(false) + }) + + it('attaches no listener while closed and detaches on close', () => { + const setOpen = vi.fn() + const view = render() + fireEvent.pointerDown(view.getByTestId('outside')) + expect(setOpen).not.toHaveBeenCalled() + + view.rerender() + view.rerender() + fireEvent.pointerDown(view.getByTestId('outside')) + expect(setOpen).not.toHaveBeenCalled() + }) + + it('ignores a pointerdown whose target is not a DOM node', () => { + const setOpen = vi.fn() + render() + const event = new Event('pointerdown', { bubbles: true }) + // Shadow the prototype getter so the listener sees a non-Node target. + Object.defineProperty(event, 'target', { get: () => ({}) }) + document.dispatchEvent(event) + expect(setOpen).not.toHaveBeenCalled() + }) +}) diff --git a/packages/shell/tool-bash/tests/observe.spec.ts b/packages/shell/tool-bash/tests/observe.spec.ts index 66a4a906b6..3ba16a832b 100644 --- a/packages/shell/tool-bash/tests/observe.spec.ts +++ b/packages/shell/tool-bash/tests/observe.spec.ts @@ -199,6 +199,37 @@ describe('background bash observation', () => { expect(ended[0]).toMatchObject({ status: 'completed', detail: 'exit code: 0' }) }) + it('a throwing end() is swallowed by the settlement-mapping catch', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRuntime) + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalJobRegistry) + await ctx.plugin(ToolTasks) + await ctx.plugin({ + name: 'end-throwing-activities-probe', + apply(child: Context) { + child.provide('activities', { + open: () => ({ + id: 'bash-1', + append() {}, + updateDetail() {}, + end() { throw new Error('end boom') }, + }), + }) + }, + }) + await ctx.plugin(LocalSubprocessRuntime) + ;(ctx.subprocess as LocalSubprocessRuntime).internals = { spillDir } + await ctx.plugin(BashEnvPlugin) + await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 }) + const warn = vi.fn() + ctx.logger.warn = warn as never + await ctx.plugin(ToolBash, { activityPollMs: 25 }) + await call(ctx, { command: 'echo settled', description: 'test command', run_in_background: true }) + await until(() => warn.mock.calls.some(args => String(args[0]).includes('activity settlement mapping')) ? true : undefined) + }) + it('a throwing observation registry never breaks the background call', async () => { const ctx = new Context() await ctx.plugin(SystemPrompt) diff --git a/packages/shell/tool-pwsh/tests/observe.spec.ts b/packages/shell/tool-pwsh/tests/observe.spec.ts index 0152a710d8..60b7d90b82 100644 --- a/packages/shell/tool-pwsh/tests/observe.spec.ts +++ b/packages/shell/tool-pwsh/tests/observe.spec.ts @@ -1,4 +1,4 @@ -import { describe, expect, it } from 'vitest' +import { describe, expect, it, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' import { CallId } from '@deepseek-ai/dsh-llm' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' @@ -168,6 +168,39 @@ describe('background pwsh observation', () => { expect(String(row.id)).toContain('pwsh') }) + it('a throwing end() is swallowed by the settlement-mapping catch', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRuntime) + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalJobRegistry) + await ctx.plugin(ToolTasks) + await ctx.plugin({ + name: 'end-throwing-activities-probe', + apply(child: Context) { + child.provide('activities', { + open: () => ({ + id: 'pwsh-1', + append() {}, + updateDetail() {}, + end() { throw new Error('end boom') }, + }), + }) + }, + }) + await ctx.plugin(BashEnvPlugin) + await ctx.plugin(FakePwsh) + await ctx.plugin(ToolPwsh, { activityPollMs: 5 }) + const pwsh = ctx.shell as FakePwsh + const warn = vi.fn() + ctx.logger.warn = warn as never + const handle = observableProcess({ stdout: { text: '' }, stderr: { text: '' } }) + pwsh.backgroundHandler = () => handle.proc + await call(ctx, { command: 'Get-Doom', description: 'test command', run_in_background: true }) + handle.finish() + await until(() => warn.mock.calls.some(args => String(args[0]).includes('activity settlement mapping')) ? true : undefined) + }) + it('a backend without observed readers still yields a status-only process', async () => { const { ctx, pwsh } = await setup() const scripted = observableProcess() From 053979cdecbf7a5de108933e46a6048825f556cd Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 27 Aug 2026 21:40:44 +0800 Subject: [PATCH 010/100] test(activity): cover the owner arm and the pwsh outer observation catch The coverage lanes flag four uncovered locations after the master merge: the spec.owner spread in tool-bash/tool-pwsh observe, the workflow mirror's owner spread, and tool-pwsh's outer observation catch. The covering tests existed only on the stacked job-kill branch; give this branch its own: an owned background run per shell asserting the fenced ownerSession row, the owned workflow mirror run, and a throwing open() through the pwsh outer catch. The windows-only file-reference-local gap reproduces on master's own windows lane at the merge point and stays upstream. --- .../shell/tool-bash/tests/observe.spec.ts | 27 ++++++++ .../shell/tool-pwsh/tests/observe.spec.ts | 61 +++++++++++++++++++ .../tests/activity-mirror.spec.ts | 23 +++++++ 3 files changed, 111 insertions(+) diff --git a/packages/shell/tool-bash/tests/observe.spec.ts b/packages/shell/tool-bash/tests/observe.spec.ts index 1a100cf833..714558227f 100644 --- a/packages/shell/tool-bash/tests/observe.spec.ts +++ b/packages/shell/tool-bash/tests/observe.spec.ts @@ -4,9 +4,11 @@ import { join } from 'node:path' import { describe, expect, it, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' import { ToolCallId } from '@deepseek-ai/dsh-llm' +import { SessionId } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRuntime from '@deepseek-ai/dsh-tools' import AgentRegistry from '@deepseek-ai/dsh-agent' +import type { Agent } from '@deepseek-ai/dsh-agent' import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs' import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' @@ -262,3 +264,28 @@ describe('background bash observation', () => { expect(read.snapshot.status).toBe('completed') }) }) + +describe('owned background observation', () => { + it('mirrors an owned background run under the owning session', async () => { + const ctx = await setup() + const owner = { + id: SessionId('observe-owner'), + session: { id: SessionId('observe-owner'), header: { cwd: process.cwd() } }, + status: 'idle', + ctx, + } as unknown as Agent + ctx.agents.register(owner) + await ctx.tools.execute({ + signal: testToolSignal, + callId: ToolCallId('observe-owned-1'), + name: 'bash', + arguments: { command: 'echo owned', description: 'test command', run_in_background: true }, + agent: owner, + }) + const job = ctx.jobs.list(owner)[0] + expect(job).toBeDefined() + const row = await until(() => ctx.activities.list(owner).find(item => item.correlation?.jobId === job!.id)) + expect(row.ownerSession).toBe(owner.id) + await until(() => ctx.jobs.get(job!.id, owner).status === 'completed' ? true : undefined) + }) +}) diff --git a/packages/shell/tool-pwsh/tests/observe.spec.ts b/packages/shell/tool-pwsh/tests/observe.spec.ts index 97f13b064e..c9024203fb 100644 --- a/packages/shell/tool-pwsh/tests/observe.spec.ts +++ b/packages/shell/tool-pwsh/tests/observe.spec.ts @@ -1,9 +1,11 @@ import { describe, expect, it, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' import { ToolCallId } from '@deepseek-ai/dsh-llm' +import { SessionId } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRuntime from '@deepseek-ai/dsh-tools' import AgentRegistry from '@deepseek-ai/dsh-agent' +import type { Agent } from '@deepseek-ai/dsh-agent' import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs' import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' @@ -216,3 +218,62 @@ describe('background pwsh observation', () => { expect(ctx.activities.get(row.id).outputTotal).toBe(0) }) }) + +describe('owned and degraded observation (pwsh)', () => { + it('mirrors an owned background run under the owning session', async () => { + const { ctx, pwsh } = await setup() + const owner = { + id: SessionId('pwsh-observe-owner'), + session: { id: SessionId('pwsh-observe-owner'), header: { cwd: process.cwd() } }, + status: 'idle', + ctx, + } as unknown as Agent + ctx.agents.register(owner) + const scripted = observableProcess() + pwsh.backgroundHandler = () => scripted.proc + await ctx.tools.execute({ + signal: testToolSignal, + callId: ToolCallId('pwsh-observe-owned'), + name: 'pwsh', + arguments: { command: 'Get-Slow', description: 'test command', run_in_background: true }, + agent: owner, + }) + const job = ctx.jobs.list(owner)[0] + expect(job).toBeDefined() + const row = await until(() => ctx.activities.list(owner).find(item => item.correlation?.jobId === job!.id)) + expect(row.ownerSession).toBe(owner.id) + scripted.finish() + await until(() => ctx.jobs.get(job!.id, owner).status === 'completed' ? true : undefined) + }) + + it('swallows a throwing observation registry and keeps the job alive', async () => { + // The FakePwsh composition with a synchronously throwing open(): the + // failure lands in the outer observation catch and the job runs on. + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRuntime) + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalJobRegistry) + await ctx.plugin(ToolTasks) + await ctx.plugin({ + name: 'broken-activities-probe', + apply(child: Context) { + child.provide('activities', { open() { throw new Error('observation boom') } }) + }, + }) + await ctx.plugin(BashEnvPlugin) + await ctx.plugin(FakePwsh) + const warn = vi.fn() + ctx.logger.warn = warn as never + await ctx.plugin(ToolPwsh, { activityPollMs: 5 }) + const pwsh = ctx.shell as FakePwsh + const scripted = observableProcess() + pwsh.backgroundHandler = () => scripted.proc + await call(ctx, { command: 'Get-Slow', description: 'test command', run_in_background: true }) + expect(warn).toHaveBeenCalledWith(expect.stringContaining('activity observation unavailable')) + const job = ctx.jobs.list()[0] + expect(job?.status).toBe('running') + scripted.finish() + await until(() => ctx.jobs.get(job!.id).status === 'completed' ? true : undefined) + }) +}) diff --git a/packages/workflow/tool-workflow/tests/activity-mirror.spec.ts b/packages/workflow/tool-workflow/tests/activity-mirror.spec.ts index 50788d453f..8f82cb2841 100644 --- a/packages/workflow/tool-workflow/tests/activity-mirror.spec.ts +++ b/packages/workflow/tool-workflow/tests/activity-mirror.spec.ts @@ -1,6 +1,9 @@ import { describe, expect, it, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' +import AgentRegistry from '@deepseek-ai/dsh-agent' +import type { Agent } from '@deepseek-ai/dsh-agent' import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' +import { SessionId } from '@deepseek-ai/dsh-session' import type { WorkflowRun, WorkflowRunId, WorkflowRunInfo } from '@deepseek-ai/dsh-workflow' import { createWorkflowActivityMirror } from '../src/activity.ts' @@ -45,6 +48,26 @@ describe('workflow activity mirror', () => { expect(ctx.activities.get(row!.id).status).toBe('completed') }) + + it('opens an owned run under the owning agent session', async () => { + const ctx = new Context() + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalActivityRegistry) + const owner = { + id: SessionId('workflow-owner'), + session: { id: SessionId('workflow-owner') }, + status: 'idle', + ctx, + } as unknown as Agent + ctx.agents.register(owner) + const mirror = createWorkflowActivityMirror(ctx) + const { run } = runStub('run-owned') + mirror.start(run, owner) + // The owned row is fenced to its owner's view. + const row = ctx.activities.list(owner)[0] + expect(row?.ownerSession).toBe(owner.id) + mirror.finish(run.id, 'completed') + }) it('maps cancelled and error stops, and ends an abandoned run as killed', async () => { const ctx = new Context() await ctx.plugin(LocalActivityRegistry) From 8aa2dfa3a518844a5202092ad00587b63ea93639 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Mon, 31 Aug 2026 11:40:11 +0800 Subject: [PATCH 011/100] fix(ci): exempt the activity controller from flattened client-face dependencies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The master merge brought the published dependency policy: a package declaring dsh.client flattens its non-Cordis peers unless excluded. api-activity-controller is the same species as the excluded session and workspace controllers — a Host Remote controller whose host half relays real runtime peers (dsh-activity for the registry service and its brand constructor at the wire boundary, dsh-invariants for the companion) — so it joins CLIENT_FACE_EXCLUDE rather than dropping those peers. --- scripts/package-dependency-policy.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/package-dependency-policy.ts b/scripts/package-dependency-policy.ts index 63054fd183..15b481383c 100644 --- a/scripts/package-dependency-policy.ts +++ b/scripts/package-dependency-policy.ts @@ -5,6 +5,7 @@ const CLIENT_FACE_INCLUDE: readonly string[] = [] /** Packages exempted from automatic Client/Host treatment despite declaring `dsh.client`. */ const CLIENT_FACE_EXCLUDE: readonly string[] = [ + '@deepseek-ai/dsh-api-activity-controller', '@deepseek-ai/dsh-api-session-controller', '@deepseek-ai/dsh-api-workspace-controller', ] From 48939ba7426d80f9df95a8cc8ff89251634e1d5a Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Mon, 31 Aug 2026 11:49:00 +0800 Subject: [PATCH 012/100] test(ci): pin the activity controller in the Host relay roster The roster spec mirrors CLIENT_FACE_EXCLUDE; the activity controller joined the excluded Host relays in the previous commit. --- scripts/verify-package-dependencies.spec.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/verify-package-dependencies.spec.ts b/scripts/verify-package-dependencies.spec.ts index 4294cff84b..26263fe018 100644 --- a/scripts/verify-package-dependencies.spec.ts +++ b/scripts/verify-package-dependencies.spec.ts @@ -123,6 +123,7 @@ function hostRuntimeFixture(): { describe('package dependency scope', () => { it('keeps the measured Host relay roster explicit', () => { expect(PACKAGE_DEPENDENCY_POLICY.clientFaceExclude).toEqual([ + '@deepseek-ai/dsh-api-activity-controller', '@deepseek-ai/dsh-api-session-controller', '@deepseek-ai/dsh-api-workspace-controller', ]) From e580c0b3334f1774cd23f6d4728966bd196ccb5b Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 1 Sep 2026 17:45:43 +0800 Subject: [PATCH 013/100] feat(jobs): fold the streaming observation record into the job registry A job can now declare record: true and stream raw output into a bounded per-job ring through the RunningJob face its starter receives: readRecord serves any number of observers at absolute byte offsets without touching the consuming model cursor or notice state, onOutput signals advancement, and updateDetail publishes a live progress line into every snapshot. Job settlement is the record's only end: it trims retention to the settled cap and fires the final output signal, so producers no longer reconcile two terminal states. pumpJobOutput ports the offset-reader pump beside the seam. This is the first step of merging the standalone dsh-activity observation plane into jobs. --- packages/jobs/jobs-local/README.md | 13 +- packages/jobs/jobs-local/src/index.ts | 257 ++++++++++++++- packages/jobs/jobs-local/tests/jobs.spec.ts | 329 +++++++++++++++++++- packages/jobs/jobs/README.md | 13 +- packages/jobs/jobs/src/index.ts | 54 +++- packages/jobs/jobs/src/invariant.ts | 9 + packages/jobs/jobs/src/pump.ts | 96 ++++++ packages/jobs/jobs/src/types.ts | 125 +++++++- packages/jobs/jobs/tests/invariant.spec.ts | 7 + packages/jobs/jobs/tests/service.spec.ts | 103 +++++- 10 files changed, 961 insertions(+), 45 deletions(-) create mode 100644 packages/jobs/jobs/src/pump.ts diff --git a/packages/jobs/jobs-local/README.md b/packages/jobs/jobs-local/README.md index cfbda98ccf..2da0a0b339 100644 --- a/packages/jobs/jobs-local/README.md +++ b/packages/jobs/jobs-local/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -`dsh-jobs-local` runs background jobs inside the harness process: work keeps running while the agent moves on, and the owning agent can read, wait on, list, and cancel it, with completion delivered as an in-session notice when `dsh-tool-jobs` is also mounted. It implements the `dsh-jobs` contract with in-memory records handed out as fresh snapshots, never live state. A per-owner concurrency limit (default 10) bounds how many jobs one agent can have running or stopping at once; jobs die with the harness process and are not durable across restarts. +`dsh-jobs-local` runs background jobs inside the harness process: work keeps running while the agent moves on, and the owning agent can read, wait on, list, and cancel it, with completion delivered as an in-session notice when `dsh-tool-jobs` is also mounted. It implements the `dsh-jobs` contract with in-memory records handed out as fresh snapshots, never live state. A per-owner concurrency limit (default 10) bounds how many jobs one agent can have running or stopping at once, and a job that declares a record keeps a bounded in-memory output ring (256 KiB live, trimmed to 16 KiB at settlement by default) that observers read at absolute offsets; jobs die with the harness process and are not durable across restarts. ## Table of Contents @@ -42,8 +42,10 @@ Loading the plugin registers `ctx.jobs`; `maxConcurrentJobsPerOwner` is optional | Field | Default | Meaning | |---|---|---| | `maxConcurrentJobsPerOwner` | `10` | Maximum `running` plus `stopping` jobs per exact owner, or in the shared unowned bucket | +| `retainBytes` | `262144` | Live record retention per job, in UTF-8 bytes | +| `settledRetainBytes` | `16384` | Record retention kept after a job settles, in UTF-8 bytes | -The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-jobs-local) is the exhaustive source for the accepted field. +The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-jobs-local) is the exhaustive source for the accepted fields. ### What each owner gets @@ -69,7 +71,8 @@ This section explains the design decisions behind the registry and points at the ### Design philosophy -- **In-memory records, fresh snapshots.** `LocalJobRegistry` keeps one `TrackedTask` per job and projects a new read-only snapshot per call; callers never receive live state. +- **In-memory records, fresh snapshots.** `LocalJobRegistry` keeps one `TrackedTask` per job — lifecycle state plus the optional record ring — and projects a new read-only snapshot or chunk copy per call; callers never receive live state. +- **Retention is bounded per record.** Appends past the live cap drop the oldest retained chunks (a single oversized chunk keeps its UTF-8-safe tail); a reader below the retained window gets a lossy read, never an error, and settlement trims to the settled cap. - **Owner-relative layers, one process-wide registry.** Controllers, completion listeners, and change observers are filed into the scope that registered them (`ScopedLayers`), and reads union the global layer with the owner's scope chain — so one preset's job controls never hold `start()` open for an agent whose own composition loads none, and a settlement reaches only the listeners its owner's composition registered. - **Preflight before start.** `start()` checks controller service, spec validity, live ownership, and capacity before invoking the producer, so a rejection leaves no job id or execution resource; registration commits without a later failable step. - **First-wins settlement, completion last.** The earliest terminal outcome records once, releases waiters, and notifies listeners once with per-listener containment; completion is announced after the record is committed and the visible-set change published, because a reporter may open a model turn synchronously. @@ -84,11 +87,11 @@ This section explains the design decisions behind the registry and points at the ### Scope layers -`attachController`, `onJobDone`, and `onJobsChanged` register into the calling context's scope layer. The controller question (`servesOwner`) and listener delivery (`listenersFor`, `changedFor`) walk the same chain: global layer first, then each scoped layer along the owner's chain. Registrations are anonymous tokens so duplicate labels stay independently disposable. +`attachController`, `onJobDone`, `onJobsChanged`, and `onOutput` register into the calling context's scope layer. The controller question (`servesOwner`) and listener delivery (`listenersFor`, `changedFor`, `outputFor`) walk the same chain: global layer first, then each scoped layer along the owner's chain. Registrations are anonymous tokens so duplicate labels stay independently disposable. ### Admission and settlement -`activeTaskCount` counts authoritative records per exact owner or in the shared unowned bucket. `settle` marks a job reported when waiters are pending, resolves every waiter, records the terminal snapshot, announces the visible-set change, then notifies completion listeners. Pending waits mark the job reported before listeners run so completion reporters do not duplicate notices; a teardown cancel marks it for the same reason — nothing will read a notice addressed to an owner being destroyed. +`activeTaskCount` counts authoritative records per exact owner or in the shared unowned bucket. `settle` marks a job reported when waiters are pending, trims a declared record to the settled cap, resolves every waiter, records the terminal snapshot, announces the visible-set change and the record's final output signal, then notifies completion listeners. Pending waits mark the job reported before listeners run so completion reporters do not duplicate notices; a teardown cancel marks it for the same reason — nothing will read a notice addressed to an owner being destroyed. ### Teardown diff --git a/packages/jobs/jobs-local/src/index.ts b/packages/jobs/jobs-local/src/index.ts index 8c71ae1b79..15cb5336b0 100644 --- a/packages/jobs/jobs-local/src/index.ts +++ b/packages/jobs/jobs-local/src/index.ts @@ -1,7 +1,8 @@ /** * Process-local provider for the background-job capability seam - * (`ctx.jobs`). It keeps every record in memory and hands out fresh - * snapshots, never live state. + * (`ctx.jobs`). It keeps every record — lifecycle state plus the optional + * bounded output ring — in memory and hands out fresh snapshots and chunk + * copies, never live state. * * Registrations outlive producer and controller fibers. Agent or service * disposal cancels live work and awaits compliant producers; a throwing @@ -17,8 +18,8 @@ import type { ScopeLayer } from '@deepseek-ai/dsh-scope' import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout' import { JobRegistry, JobId } from '@deepseek-ai/dsh-jobs' import type { - JobDoneListener, JobKind, JobOutcome, JobRead, JobSnapshot, JobStart, JobStatus, - JobsChangedListener, + JobAppendOptions, JobChannel, JobDoneListener, JobKind, JobOutcome, JobOutputListener, JobRead, + JobRecordChunk, JobRecordRead, JobSnapshot, JobStart, JobStatus, JobsChangedListener, RunningJob, } from '@deepseek-ai/dsh-jobs' /** Timeout code that distinguishes a bounded wait from caller cancellation. */ @@ -27,6 +28,12 @@ export const TASK_WAIT_TIMEOUT = 'TASK_WAIT_TIMEOUT' /** Default maximum number of active jobs in one exact-owner bucket. */ const DEFAULT_MAX_CONCURRENT_TASKS_PER_OWNER = 10 +/** Default live record retention per job, in UTF-8 bytes. */ +const DEFAULT_RETAIN_BYTES = 256 * 1024 + +/** Default record retention kept after settlement, in UTF-8 bytes. */ +const DEFAULT_SETTLED_RETAIN_BYTES = 16 * 1024 + /** Configuration for the process-local job registry. */ export interface Config { /** @@ -34,6 +41,45 @@ export interface Config { * omission defaults to 10. */ maxConcurrentJobsPerOwner?: number + /** Live record retention per job in UTF-8 bytes; omission defaults to 262144. */ + retainBytes?: number + /** Record retention kept after a job settles, in UTF-8 bytes; omission defaults to 16384. */ + settledRetainBytes?: number +} + +/** One retained record ring entry; `bytes` caches the chunk's UTF-8 length. */ +interface RingChunk { + at: number + text: string + bytes: number + channel?: JobChannel + gapBefore?: true +} + +/** The bounded output ring behind one job's declared record. */ +interface RecordState { + /** Retained chunks in offset order; offsets stay absolute across eviction. */ + chunks: RingChunk[] + /** Sum of the retained chunks' byte lengths. */ + retainedBytes: number + /** Total UTF-8 bytes ever appended. */ + total: number + /** Offset of the oldest retained byte (equals {@link total} when nothing is retained). */ + earliest: number +} + +/** + * Producer-written state shared between the {@link RunningJob} face and the + * registered record: the starter call writes through it before the commit, + * the same object serves the job for its whole life afterwards. + */ +interface ProducerState { + /** Bounded output ring; undefined when the spec declared no record. */ + record: RecordState | undefined + /** Live progress detail until settlement replaces it with the terminal one. */ + detail: string | undefined + /** The committed registry record; undefined exactly during the starter call. */ + job: TrackedTask | undefined } /** The registry's mutable per-job record (never handed out — see {@link LocalJobRegistry.snapshot}). */ @@ -47,7 +93,8 @@ interface TrackedTask { cancel: (reason?: string) => void readOutput: (() => string) | undefined status: JobStatus - detail: string | undefined + /** Producer-shared record ring and detail line. */ + state: ProducerState output: string | undefined startedAt: number finishedAt: number | undefined @@ -67,19 +114,39 @@ function isTerminal(status: JobStatus): boolean { return status === 'completed' || status === 'killed' || status === 'failed' } +/** + * The UTF-8-safe tail of `text` no longer than `maxBytes`: the byte cut + * advances past continuation bytes so the surviving text never starts inside + * a code point. + * @param text - the oversized chunk text. + * @param maxBytes - positive byte budget for the surviving tail. + * @returns the surviving tail and its exact byte length. + */ +function utf8Tail(text: string, maxBytes: number): { text: string; bytes: number } { + const raw = Buffer.from(text, 'utf8') + let start = raw.length - maxBytes + // The loop bound proves the index is in range; the assertion only + // discharges noUncheckedIndexedAccess. + while (start < raw.length && ((raw[start] as number) & 0xC0) === 0x80) start += 1 + const tail = raw.subarray(start) + return { text: tail.toString('utf8'), bytes: tail.length } +} + /** * One scope's contributions: the job controllers attached from it and the - * completion listeners registered there. Both tables are anonymous because a - * contribution is identified by its own disposer, never by a name a second - * registrant could shadow. + * completion, change, and record-output listeners registered there. All + * tables are anonymous because a contribution is identified by its own + * disposer, never by a name a second registrant could shadow. */ class JobLayer implements ScopeLayer { readonly controllers = new AnonymousEntries() readonly listeners = new AnonymousEntries() readonly changed = new AnonymousEntries() + readonly output = new AnonymousEntries() isEmpty(): boolean { return this.controllers.isEmpty() && this.listeners.isEmpty() && this.changed.isEmpty() + && this.output.isEmpty() } } @@ -95,10 +162,24 @@ export class LocalJobRegistry extends JobRegistry { .min(1) .max(Number.MAX_SAFE_INTEGER) .default(DEFAULT_MAX_CONCURRENT_TASKS_PER_OWNER), + retainBytes: z.number() + .step(1) + .min(1) + .max(Number.MAX_SAFE_INTEGER) + .default(DEFAULT_RETAIN_BYTES), + settledRetainBytes: z.number() + .step(1) + .min(1) + .max(Number.MAX_SAFE_INTEGER) + .default(DEFAULT_SETTLED_RETAIN_BYTES), }) /** Schemastery-defaulted active-job limit. */ private readonly maxConcurrentJobsPerOwner: number + /** Schemastery-defaulted live record retention cap. */ + private readonly retainBytes: number + /** Schemastery-defaulted settled record retention cap. */ + private readonly settledRetainBytes: number private store = new Map() private counters = new Map() /** @@ -122,8 +203,10 @@ export class LocalJobRegistry extends JobRegistry { constructor(ctx: Context, config: Config) { super(ctx) - // Schemastery validates and fills the default before constructing the service. + // Schemastery validates and fills the defaults before constructing the service. this.maxConcurrentJobsPerOwner = (config as Required).maxConcurrentJobsPerOwner + this.retainBytes = (config as Required).retainBytes + this.settledRetainBytes = (config as Required).settledRetainBytes this.selfCtx = ctx ctx.effect(() => () => this.disposeAll(), 'jobs teardown') } @@ -147,10 +230,23 @@ export class LocalJobRegistry extends JobRegistry { ) } - const hooks = spec.run() + // The id is issued before the starter runs so the producer face can carry + // it; a throwing starter still leaves nothing registered — its ordinal is + // simply skipped. const count = (this.counters.get(spec.kind) ?? 0) + 1 this.counters.set(spec.kind, count) const id = JobId(`${spec.kind}-${count}`) + const state: ProducerState = { + record: spec.record === true ? { chunks: [], retainedBytes: 0, total: 0, earliest: 0 } : undefined, + detail: undefined, + job: undefined, + } + const handle: RunningJob = { + id, + append: (text, options) => { this.appendRecord(id, state, text, options) }, + updateDetail: (detail) => { this.updateDetail(state, detail) }, + } + const hooks = spec.run(handle) let markSettled!: () => void const settled = new Promise((resolve) => { markSettled = resolve }) @@ -163,7 +259,7 @@ export class LocalJobRegistry extends JobRegistry { cancel: hooks.cancel.bind(hooks), readOutput: hooks.readOutput?.bind(hooks), status: 'running', - detail: undefined, + state, output: undefined, startedAt: Date.now(), finishedAt: undefined, @@ -173,6 +269,10 @@ export class LocalJobRegistry extends JobRegistry { waiters: 0, waitResolvers: new Set(), } + // Binding the shared producer state is the commit: writes staged inside + // the starter are already in `state`, and every later handle call reaches + // the registered record for its terminal checks and observer signals. + state.job = job this.store.set(id, job) void hooks.done.then( @@ -294,6 +394,37 @@ export class LocalJobRegistry extends JobRegistry { ) } + readRecord(id: JobId, from: number, caller?: Agent): JobRecordRead { + const job = this.expect(id) + this.assertAccess(job, caller) + if (!Number.isSafeInteger(from) || from < 0) { + throw new Error(`invalid record read offset: expected a non-negative safe integer, got ${JSON.stringify(from)}`) + } + const record = job.state.record + if (record === undefined) { + throw new Error(`job ${job.id} declared no output record`) + } + const chunks: JobRecordChunk[] = [] + for (const chunk of record.chunks) { + if (chunk.at + chunk.bytes <= from) continue + chunks.push({ + at: chunk.at, + text: chunk.text, + ...chunk.channel !== undefined ? { channel: chunk.channel } : {}, + ...chunk.gapBefore !== undefined ? { gapBefore: chunk.gapBefore } : {}, + }) + } + return { chunks, next: record.total, lossy: from < record.earliest } + } + + onOutput(listener: JobOutputListener): () => void { + return this.layers.effect( + this.ctx, + layer => layer.output.append(listener), + { label: 'jobs.onOutput()' }, + ) + } + attachController(name: string): () => void { // One token per call keeps duplicate labels independently disposable. const token = Symbol(name) @@ -362,6 +493,7 @@ export class LocalJobRegistry extends JobRegistry { /** Project a fresh read-only snapshot from the mutable record. */ private snapshot(job: TrackedTask): JobSnapshot { const ownerSession = job.owner?.id + const record = job.state.record return { id: job.id, kind: job.kind, @@ -369,10 +501,11 @@ export class LocalJobRegistry extends JobRegistry { ...job.outputLimitBytes !== undefined ? { outputLimitBytes: job.outputLimitBytes } : {}, ...ownerSession !== undefined ? { ownerSession } : {}, status: job.status, - ...job.detail !== undefined ? { detail: job.detail } : {}, + ...job.state.detail !== undefined ? { detail: job.state.detail } : {}, startedAt: job.startedAt, ...job.finishedAt !== undefined ? { finishedAt: job.finishedAt } : {}, reported: job.reported, + ...record !== undefined ? { outputTotal: record.total, outputEarliest: record.earliest } : {}, } } @@ -405,6 +538,95 @@ export class LocalJobRegistry extends JobRegistry { } } + /** The record-output observers that own `owner`'s stream signals, resolved like {@link changedFor}. */ + private *outputFor(owner?: Agent): IterableIterator { + yield* this.layers.global.output.values() + const scope = owner === undefined ? undefined : scopeOf(owner.ctx) + for (const layer of this.layers.chainLayers(scope)) yield* layer.output.values() + } + + /** Announce that one job's record advanced (append or settlement), with per-listener containment. */ + private notifyOutput(job: TrackedTask): void { + for (const listener of this.outputFor(job.owner)) { + try { + listener(job.id) + } catch (error: unknown) { + this.selfCtx.logger.warn(`jobs: onOutput listener threw: ${String(error)}`) + } + } + } + + /** + * Append one chunk through a producer face. A chunk against a settled job or + * without a record declaration is logged and dropped; an empty chunk is + * dropped silently. A chunk staged inside the starter call is retained and + * signals no observer — the registration commit publishes it. + */ + private appendRecord(id: JobId, state: ProducerState, text: string, options?: JobAppendOptions): void { + const job = state.job + if (job !== undefined && isTerminal(job.status)) { + this.selfCtx.logger.warn(`jobs: append to settled job ${job.id} dropped`) + return + } + const record = state.record + if (record === undefined) { + this.selfCtx.logger.warn(`jobs: append to job ${id} without a record declaration dropped`) + return + } + if (text.length === 0) return + const bytes = Buffer.byteLength(text, 'utf8') + record.chunks.push({ + at: record.total, + text, + bytes, + ...options?.channel !== undefined ? { channel: options.channel } : {}, + ...options?.gapBefore !== undefined ? { gapBefore: options.gapBefore } : {}, + }) + record.total += bytes + record.retainedBytes += bytes + this.trimRecord(record, this.retainBytes) + if (job !== undefined) this.notifyOutput(job) + } + + /** + * Replace the live detail line through a producer face; a write against a + * settled job is logged and dropped. A write staged inside the starter call + * seeds the registered snapshot and signals no observer. + */ + private updateDetail(state: ProducerState, detail: string): void { + const job = state.job + if (job !== undefined && isTerminal(job.status)) { + this.selfCtx.logger.warn(`jobs: detail update on settled job ${job.id} dropped`) + return + } + state.detail = detail + if (job !== undefined) this.notifyChanged(job.owner) + } + + /** + * Drop retained head chunks until the ring fits `cap`; a single oversized + * chunk keeps only its UTF-8-safe tail with a `gapBefore` marker. Offsets + * stay absolute: `earliest` advances over everything dropped. + */ + private trimRecord(record: RecordState, cap: number): void { + while (record.retainedBytes > cap && record.chunks.length > 1) { + const dropped = record.chunks.shift() + /* v8 ignore next -- the length guard proves shift() returns a chunk; the check only satisfies noUncheckedIndexedAccess. */ + if (dropped === undefined) break + record.retainedBytes -= dropped.bytes + } + const single = record.chunks.length === 1 ? record.chunks[0] : undefined + if (single !== undefined && single.bytes > cap) { + const tail = utf8Tail(single.text, cap) + single.at += single.bytes - tail.bytes + single.text = tail.text + single.bytes = tail.bytes + single.gapBefore = true + record.retainedBytes = tail.bytes + } + record.earliest = record.chunks[0]?.at ?? record.total + } + /** * Record the first terminal outcome, release waiters, then announce * completion. First-wins preserves a teardown force-failure against late @@ -416,16 +638,25 @@ export class LocalJobRegistry extends JobRegistry { private settle(job: TrackedTask, outcome: JobOutcome): void { if (isTerminal(job.status)) return job.status = outcome.status - job.detail = outcome.detail + // A terminal detail replaces the live progress line; without one the last + // progress line stays, still describing what the job was doing. + if (outcome.detail !== undefined) job.state.detail = outcome.detail job.output = outcome.output job.finishedAt = Date.now() if (job.waiters > 0) job.reported = true + // Settlement ends the record: trim to the settled cap before any observer + // reads the terminal snapshot. + const record = job.state.record + if (record !== undefined) this.trimRecord(record, this.settledRetainBytes) const snapshot = this.snapshot(job) const waitResolvers = [...job.waitResolvers] job.waitResolvers.clear() for (const resolveWait of waitResolvers) resolveWait() job.markSettled() this.notifyChanged(job.owner) + // The record stream ends with settlement; the signal follows the committed + // visible-set change and precedes completion listeners, which stay last. + if (record !== undefined) this.notifyOutput(job) if (this.listenersClosed) return for (const listener of this.listenersFor(job.owner)) { try { diff --git a/packages/jobs/jobs-local/tests/jobs.spec.ts b/packages/jobs/jobs-local/tests/jobs.spec.ts index 33ea29ba68..f305c73ba6 100644 --- a/packages/jobs/jobs-local/tests/jobs.spec.ts +++ b/packages/jobs/jobs-local/tests/jobs.spec.ts @@ -6,7 +6,7 @@ import type { Agent } from '@deepseek-ai/dsh-agent' import { bindScopeParent, createScope, scopeOf } from '@deepseek-ai/dsh-scope' import type { ScopeKey } from '@deepseek-ai/dsh-scope' import { JobId } from '@deepseek-ai/dsh-jobs' -import type { JobHooks, JobKind, JobOutcome, JobSnapshot, JobStart } from '@deepseek-ai/dsh-jobs' +import type { JobHooks, JobKind, JobOutcome, JobSnapshot, JobStart, RunningJob } from '@deepseek-ai/dsh-jobs' import LocalJobRegistry, { type Config as JobsConfig } from '@deepseek-ai/dsh-jobs-local' declare module '@deepseek-ai/dsh-jobs' { @@ -55,25 +55,39 @@ async function disposeAgentScope(agent: Agent): Promise { await dispose() } -/** A controllable producer start-spec: settle its `done` on demand, record cancels. */ +/** A controllable producer start-spec: settle its `done` on demand, record cancels, expose the job face. */ function producer(overrides: Partial & JobHooks> = {}) { let settle!: (outcome: JobOutcome) => void let reject!: (error: unknown) => void const cancels: (string | undefined)[] = [] - const { kind = 'bash', label = 'sleep 60', owner, outputLimitBytes, ...hookOverrides } = overrides + const { kind = 'bash', label = 'sleep 60', owner, outputLimitBytes, record, ...hookOverrides } = overrides const hooks: JobHooks = { cancel(reason) { cancels.push(reason) }, done: new Promise((res, rej) => { settle = res; reject = rej }), ...hookOverrides, } + let started: RunningJob | undefined const spec: JobStart = { kind, label, ...owner !== undefined ? { owner } : {}, ...outputLimitBytes !== undefined ? { outputLimitBytes } : {}, - run: () => hooks, + ...record !== undefined ? { record } : {}, + run: (job) => { + started = job + return hooks + }, + } + return { + spec, + settle, + reject, + cancels, + job(): RunningJob { + if (started === undefined) throw new Error('producer not started') + return started + }, } - return { spec, settle, reject, cancels } } async function harness(config: JobsConfig = {}) { @@ -1135,3 +1149,308 @@ describe('LocalJobRegistry teardown change notifications', () => { expect(seen).toEqual([undefined, undefined, undefined]) }) }) + +describe('LocalJobRegistry record', () => { + it('appends advance absolute offsets; record reads are non-consuming and never mark reported', async () => { + const ctx = await harness() + const p = producer({ record: true }) + const id = ctx.jobs.start(p.spec) + p.job().append('hello ') + p.job().append('world', { channel: 'stderr' }) + const first = ctx.jobs.readRecord(id, 0) + expect(first.lossy).toBe(false) + expect(first.next).toBe(11) + expect(first.chunks).toEqual([ + { at: 0, text: 'hello ' }, + { at: 6, text: 'world', channel: 'stderr' }, + ]) + // A second identical read proves nothing was consumed. + expect(ctx.jobs.readRecord(id, 0)).toEqual(first) + // Resuming from `next` yields nothing until more output arrives. + expect(ctx.jobs.readRecord(id, first.next).chunks).toEqual([]) + p.job().append('!') + expect(ctx.jobs.readRecord(id, first.next).chunks).toEqual([{ at: 11, text: '!' }]) + const snapshot = ctx.jobs.get(id) + expect(snapshot.outputTotal).toBe(12) + expect(snapshot.outputEarliest).toBe(0) + // The observer surface owns no notice state: even a terminal record read + // leaves the completion notice due. + p.settle({ status: 'completed' }) + await tick() + ctx.jobs.readRecord(id, 0) + expect(ctx.jobs.get(id).reported).toBe(false) + }) + + it('staged starter writes surface at the registration commit without observer signals', async () => { + const ctx = await harness() + const outputSignals: string[] = [] + ctx.jobs.onOutput((id) => { outputSignals.push(String(id)) }) + const changes: number[] = [] + ctx.jobs.onJobsChanged(() => { changes.push(1) }) + let settle!: (outcome: JobOutcome) => void + const id = ctx.jobs.start({ + kind: 'bash', + label: 'staged writes', + record: true, + run: (job) => { + job.append('early ', { channel: 'stdout' }) + job.updateDetail('booting') + return { + cancel() {}, + done: new Promise((resolve) => { settle = resolve }), + } + }, + }) + // Only the registration commit announced anything. + expect(outputSignals).toEqual([]) + expect(changes).toEqual([1]) + const snapshot = ctx.jobs.get(id) + expect(snapshot.detail).toBe('booting') + expect(snapshot.outputTotal).toBe(6) + expect(ctx.jobs.readRecord(id, 0).chunks).toEqual([{ at: 0, text: 'early ', channel: 'stdout' }]) + settle({ status: 'completed' }) + await tick() + }) + + it('drops an empty append without waking observers', async () => { + const ctx = await harness() + const signals: string[] = [] + ctx.jobs.onOutput((id) => { signals.push(String(id)) }) + const p = producer({ record: true }) + const id = ctx.jobs.start(p.spec) + p.job().append('') + expect(signals).toEqual([]) + expect(ctx.jobs.get(id).outputTotal).toBe(0) + }) + + it('logs and drops an append without a record declaration; updateDetail still works', async () => { + const ctx = await harness() + const warn = vi.fn() + ctx.logger.warn = warn as never + const p = producer() + const id = ctx.jobs.start(p.spec) + p.job().append('nowhere to land') + expect(warn).toHaveBeenCalledWith(expect.stringContaining(`append to job ${id} without a record declaration dropped`)) + expect(() => ctx.jobs.readRecord(id, 0)).toThrow(`job ${id} declared no output record`) + const snapshot = ctx.jobs.get(id) + expect(snapshot.outputTotal).toBeUndefined() + expect(snapshot.outputEarliest).toBeUndefined() + p.job().updateDetail('7/10 items') + expect(ctx.jobs.get(id).detail).toBe('7/10 items') + }) + + it('rejects a negative or fractional record read offset', async () => { + const ctx = await harness() + const p = producer({ record: true }) + const id = ctx.jobs.start(p.spec) + expect(() => ctx.jobs.readRecord(id, -1)).toThrow(/invalid record read offset/) + expect(() => ctx.jobs.readRecord(id, 0.5)).toThrow(/invalid record read offset/) + expect(() => ctx.jobs.readRecord(JobId('bash-99'), 0)).toThrow(/unknown job/) + }) + + it('fences record reads to the owning session', async () => { + const ctx = await harness() + const alice = stubAgent(ctx, 'alice') + const bob = stubAgent(ctx, 'bob') + ctx.agents.register(alice) + ctx.agents.register(bob) + const p = producer({ owner: alice, record: true }) + const id = ctx.jobs.start(p.spec) + p.job().append('secret') + expect(() => ctx.jobs.readRecord(id, 0, bob)).toThrow(/belongs to another session/) + expect(() => ctx.jobs.readRecord(id, 0)).toThrow(/belongs to another session/) + expect(ctx.jobs.readRecord(id, 0, alice).chunks[0]?.text).toBe('secret') + }) + + it('evicts whole head chunks past the live cap and flags stale readers lossy', async () => { + const ctx = await harness({ retainBytes: 8 }) + const p = producer({ record: true }) + const id = ctx.jobs.start(p.spec) + p.job().append('aaaa') + p.job().append('bbbb') + p.job().append('cccc') + const read = ctx.jobs.readRecord(id, 0) + expect(read.lossy).toBe(true) + expect(read.chunks).toEqual([{ at: 4, text: 'bbbb' }, { at: 8, text: 'cccc' }]) + expect(read.next).toBe(12) + const snapshot = ctx.jobs.get(id) + expect(snapshot.outputEarliest).toBe(4) + expect(snapshot.outputTotal).toBe(12) + // A reader at the retained boundary is not lossy. + expect(ctx.jobs.readRecord(id, 4).lossy).toBe(false) + }) + + it('keeps only the UTF-8-safe tail of a single oversized chunk', async () => { + const ctx = await harness({ retainBytes: 5 }) + const p = producer({ record: true }) + const id = ctx.jobs.start(p.spec) + // '你好' is six UTF-8 bytes; a five-byte budget must not split the second code point. + p.job().append('你好') + const read = ctx.jobs.readRecord(id, 0) + expect(read.lossy).toBe(true) + expect(read.chunks).toEqual([{ at: 3, text: '好', gapBefore: true }]) + const snapshot = ctx.jobs.get(id) + expect(snapshot.outputEarliest).toBe(3) + expect(snapshot.outputTotal).toBe(6) + }) + + it('an exhausted byte budget leaves an empty gap-marked tail at the total offset', async () => { + const ctx = await harness({ retainBytes: 1 }) + const p = producer({ record: true }) + const id = ctx.jobs.start(p.spec) + // Every byte of '好' from the cut is a continuation byte, so no code point survives. + p.job().append('好') + const read = ctx.jobs.readRecord(id, 0) + expect(read.lossy).toBe(true) + expect(read.chunks).toEqual([{ at: 3, text: '', gapBefore: true }]) + expect(ctx.jobs.get(id).outputEarliest).toBe(3) + }) + + it('returns the whole overlapped chunk for a foreign mid-chunk offset', async () => { + const ctx = await harness() + const p = producer({ record: true }) + const id = ctx.jobs.start(p.spec) + p.job().append('abcdef') + const read = ctx.jobs.readRecord(id, 3) + expect(read.chunks).toEqual([{ at: 0, text: 'abcdef' }]) + expect(read.lossy).toBe(false) + }) + + it('preserves a producer-reported gap marker through reads', async () => { + const ctx = await harness() + const p = producer({ record: true }) + const id = ctx.jobs.start(p.spec) + p.job().append('tail after drop', { gapBefore: true, channel: 'stdout' }) + expect(ctx.jobs.readRecord(id, 0).chunks).toEqual([ + { at: 0, text: 'tail after drop', channel: 'stdout', gapBefore: true }, + ]) + }) + + it('settlement trims to the settled cap, signals once more, and drops later writes', async () => { + const ctx = await harness({ retainBytes: 1024, settledRetainBytes: 4 }) + const warn = vi.fn() + ctx.logger.warn = warn as never + const signals: string[] = [] + ctx.jobs.onOutput((id) => { signals.push(String(id)) }) + const p = producer({ record: true }) + const id = ctx.jobs.start(p.spec) + p.job().append('abcdefgh') + p.settle({ status: 'completed', detail: 'exit code: 0' }) + await tick() + expect(signals).toEqual([String(id), String(id)]) + const snapshot = ctx.jobs.get(id) + expect(snapshot).toMatchObject({ status: 'completed', detail: 'exit code: 0', outputTotal: 8, outputEarliest: 4 }) + const read = ctx.jobs.readRecord(id, 0) + expect(read.lossy).toBe(true) + expect(read.chunks).toEqual([{ at: 4, text: 'efgh', gapBefore: true }]) + // The stream ended with the settlement: a trailing flush cannot break teardown. + p.job().append('late') + p.job().updateDetail('late detail') + expect(warn.mock.calls.map(call => String(call[0]))).toEqual([ + expect.stringContaining('append to settled job'), + expect.stringContaining('detail update on settled job'), + ]) + expect(signals).toHaveLength(2) + expect(ctx.jobs.get(id).detail).toBe('exit code: 0') + }) + + it('a terminal outcome without detail keeps the last progress line', async () => { + const ctx = await harness() + const changes: number[] = [] + const p = producer({ record: true }) + const id = ctx.jobs.start(p.spec) + ctx.jobs.onJobsChanged(() => { changes.push(1) }) + p.job().updateDetail('3/10 agents done') + expect(changes).toHaveLength(1) + expect(ctx.jobs.get(id).detail).toBe('3/10 agents done') + p.settle({ status: 'completed' }) + await tick() + expect(ctx.jobs.get(id)).toMatchObject({ status: 'completed', detail: '3/10 agents done' }) + }) + + it('a teardown-forced settlement also ends the record', async () => { + const ctx = await harness() + const warn = vi.fn() + ctx.logger.warn = warn as never + const owner = stubAgent(ctx, 'owner') + ctx.agents.register(owner) + const p = producer({ owner, record: true }) + const id = ctx.jobs.start(p.spec) + p.job().append('partial') + const disposal = disposeAgentScope(owner) + p.settle({ status: 'killed' }) + await disposal + expect(() => ctx.jobs.readRecord(id, 0, owner)).toThrow(/unknown job/) + // The producer face outlives the row; its trailing flush is dropped, not thrown. + p.job().append('late') + expect(warn).toHaveBeenCalledWith(expect.stringContaining('append to settled job')) + }) + + it('delivers onOutput to the global layer and to the owning scope only', async () => { + const ctx = await harness() + const mount = createScope(ctx, {}) + const otherMount = createScope(ctx, {}) + const alice = stubAgent(ctx, 'alice', scopeOf(mount.ctx)) + const bob = stubAgent(ctx, 'bob', scopeOf(otherMount.ctx)) + ctx.agents.register(alice) + ctx.agents.register(bob) + const globalSignals: string[] = [] + ctx.jobs.onOutput((id) => { globalSignals.push(String(id)) }) + const scopedSignals: string[] = [] + await mount.ctx.plugin({ + inject: ['jobs'], + apply(scopedCtx: Context) { + scopedCtx.jobs.onOutput((id) => { scopedSignals.push(String(id)) }) + }, + }) + const pa = producer({ owner: alice, record: true }) + const aliceId = ctx.jobs.start(pa.spec) + const pb = producer({ owner: bob, record: true }) + ctx.jobs.start(pb.spec) + pa.job().append('for alice observers') + pb.job().append('for bob observers') + expect(globalSignals).toHaveLength(2) + expect(scopedSignals).toEqual([String(aliceId)]) + }) + + it('contains a throwing onOutput listener without breaking the append commit', async () => { + const ctx = await harness() + const warn = vi.fn() + ctx.logger.warn = warn as never + ctx.jobs.onOutput(() => { throw new Error('output boom') }) + const p = producer({ record: true }) + const id = ctx.jobs.start(p.spec) + p.job().append('x') + expect(ctx.jobs.get(id).outputTotal).toBe(1) + expect(warn).toHaveBeenCalledWith(expect.stringContaining('onOutput listener threw')) + }) + + it('unregisters onOutput listeners with their registering fiber (HMR safety)', async () => { + const ctx = await harness() + const signals: string[] = [] + const fiber = ctx.plugin({ + inject: ['jobs'], + apply(pluginCtx: Context) { + pluginCtx.jobs.onOutput((id) => { signals.push(String(id)) }) + }, + }) + await fiber + const p = producer({ record: true }) + ctx.jobs.start(p.spec) + p.job().append('a') + expect(signals).toHaveLength(1) + await fiber.dispose() + p.job().append('b') + expect(signals).toHaveLength(1) + }) + + it('hands out fresh record snapshots, never live registry state', async () => { + const ctx = await harness() + const p = producer({ record: true }) + const id = ctx.jobs.start(p.spec) + const before = ctx.jobs.get(id) + p.job().append('grow') + expect(before.outputTotal).toBe(0) + expect(ctx.jobs.get(id).outputTotal).toBe(4) + }) +}) diff --git a/packages/jobs/jobs/README.md b/packages/jobs/jobs/README.md index 7625c3672d..10c74af908 100644 --- a/packages/jobs/jobs/README.md +++ b/packages/jobs/jobs/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -`dsh-jobs` lets tools run long work as background jobs: the work gets a stable `-N` id, keeps running while the agent moves on, and the owning agent can read its output, wait for it with a timeout, or request cancellation at any time. Jobs belong to the agent session that started them, so one agent's work is never visible to another, and completion reaches the owner as an in-session notice rather than by polling. This package ships the contract only: the process-local registry lives in `dsh-jobs-local`, and the model-facing controls and completion notices live in `dsh-tool-jobs`. Load an implementation to get background jobs; without one, `ctx.jobs` does not exist and `start()` cannot run. +`dsh-jobs` lets tools run long work as background jobs: the work gets a stable `-N` id, keeps running while the agent moves on, and the owning agent can read its output, wait for it with a timeout, or request cancellation at any time. Jobs belong to the agent session that started them, so one agent's work is never visible to another, and completion reaches the owner as an in-session notice rather than by polling. A producer can also declare a per-job observation record: an append-only bounded output stream that any number of observers (the Web client) read at absolute byte offsets without touching the model-facing consuming cursor. This package ships the contract only: the process-local registry lives in `dsh-jobs-local`, and the model-facing controls and completion notices live in `dsh-tool-jobs`. Load an implementation to get background jobs; without one, `ctx.jobs` does not exist and `start()` cannot run. ## Table of Contents @@ -31,6 +31,8 @@ Use this package when you are composing a background-job capability or writing a A producer registers work with a kind and a one-line label; the registry returns a `-N` id such as `bash-1`. Anyone who owns the job can read output, list jobs, wait up to a timeout for settlement, and request cancellation — each call returns a fresh snapshot of the job's status, from `running` and `stopping` to the terminal `completed`, `killed`, or `failed`. When a job settles, the owning agent is notified through the completion listener that `dsh-tool-jobs` turns into an in-session notice, so no polling is needed. A producer may attach an optional byte cap so each complete model-facing output read or completion notice stays bounded. +A producer that declares `record: true` additionally streams raw output into the job's bounded record through the `RunningJob` face its starter receives: observers read retained chunks at absolute byte offsets and get signaled on advancement, the settlement that ends the job also ends the stream, and `updateDetail` publishes a live progress line into every snapshot. The record is invisible to the model: reads consume nothing and never touch notice state. + ### The ownership boundary A job belongs to the agent session that started it: another agent cannot read or stop it. Ids such as `bash-1` are predictable, so this fence is authorization, not secrecy. A job started without an owner is open to any caller and lasts until the service is disposed. @@ -75,13 +77,14 @@ This section explains the design decisions behind the contract and points at the | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | Plugin entry: the abstract `JobRegistry` service and its contract | -| [`src/types.ts`](src/types.ts) | Shared vocabulary: `JobKindMap`, `JobStart`, `JobHooks`, `JobSnapshot`, listener types | +| [`src/types.ts`](src/types.ts) | Shared vocabulary: `JobKindMap`, `JobStart`, `JobHooks`, `RunningJob`, `JobSnapshot`, listener types | | [`src/brand.ts`](src/brand.ts) | `JobId` branded identifier, importable without the agent dependency | -| [`src/invariant.ts`](src/invariant.ts) | Invariant companion: validates snapshot identity, status, timestamps, and owner fields | +| [`src/pump.ts`](src/pump.ts) | `pumpJobOutput`: poll pump copying producer offset-readers into a job record | +| [`src/invariant.ts`](src/invariant.ts) | Invariant companion: validates snapshot identity, status, timestamps, owner, and record-offset fields | ### Service operations -Every operation is a thin projection over the registered jobs: `get` and `list` return non-consuming snapshots, `read` advances the single stream cursor, `kill` invokes producer cancellation before changing status, `wait` blocks up to a timeout, and `start()` preflights access, validation, and admission before invoking the producer's `run()` once while refusing any owner no attached controller serves; listeners observe terminal records and visible-set changes at owner granularity, and `attachController` scopes controller availability to its effect lifetime. Exact signatures and behavior live in the JSDoc on [`src/index.ts`](src/index.ts) and the generated [`ctx.jobs` cordis surface](../../../docs/subsystems/jobs.md). +Every operation is a thin projection over the registered jobs: `get` and `list` return non-consuming snapshots, `read` advances the single stream cursor, `readRecord` reads retained record chunks at an absolute offset without consuming anything, `kill` invokes producer cancellation before changing status, `wait` blocks up to a timeout, and `start()` preflights access, validation, and admission before invoking the producer's `run()` once while refusing any owner no attached controller serves; listeners observe terminal records, visible-set changes, and record advancement at owner granularity, and `attachController` scopes controller availability to its effect lifetime. Exact signatures and behavior live in the JSDoc on [`src/index.ts`](src/index.ts) and the generated [`ctx.jobs` cordis surface](../../../docs/subsystems/jobs.md). @@ -118,7 +121,7 @@ No direct invalidation; the named consumers own any request-prefix changes. These limits define when the contract is a poor fit. They are current package constraints, not a task backlog. - **The contract is in-process** — `JobStart.run()` passes callbacks and exact `Agent` objects; a durable or cross-process backend must reshape identity, restart, ownership, and observation semantics before it can implement this seam. -- **Stream output has one consuming cursor** — the model owns it; independent observers use the non-consuming [`dsh-activity`](../../activity/activity/README.md) plane the producers mirror into instead. +- **Stream output has one consuming cursor** — the model owns it; independent observers read the job's declared record through the non-consuming `readRecord` instead. - **Foreground work cannot be promoted** — producers choose foreground or background before starting. diff --git a/packages/jobs/jobs/src/index.ts b/packages/jobs/jobs/src/index.ts index 7d46dfa342..796afc0882 100644 --- a/packages/jobs/jobs/src/index.ts +++ b/packages/jobs/jobs/src/index.ts @@ -1,30 +1,42 @@ /** * The background-job Service Definition (`ctx.jobs`). It owns the contract for - * job ids, session-scoped access, lifecycle state, completion listeners, and - * owner cleanup while producers retain their execution resources. The - * process-local registry lives in `@deepseek-ai/dsh-jobs-local`. + * job ids, session-scoped access, lifecycle state, completion listeners, + * owner cleanup, and the optional per-job observation record — an append-only + * bounded output stream any number of independent observers read at absolute + * byte offsets, invisible to the model-facing consuming cursor — while + * producers retain their execution resources. The process-local registry + * lives in `@deepseek-ai/dsh-jobs-local`. * @module @deepseek-ai/dsh-jobs */ import { Context, Service } from '@deepseek-ai/cordis' import type { Agent } from '@deepseek-ai/dsh-agent' import type { - JobDoneListener, JobId, JobRead, JobSnapshot, JobStart, JobsChangedListener, + JobDoneListener, JobId, JobOutputListener, JobRead, JobRecordRead, JobSnapshot, JobStart, + JobsChangedListener, } from './types.ts' export { JobId } from './types.ts' export type { + JobAppendOptions, + JobChannel, JobDoneListener, JobHooks, JobKind, JobKindMap, JobOutcome, + JobOutputListener, JobRead, + JobRecordChunk, + JobRecordRead, JobSnapshot, JobStart, JobStatus, JobsChangedListener, + RunningJob, } from './types.ts' +export { pumpJobOutput } from './pump.ts' +export type { JobPumpOptions, JobPumpRead, JobPumpSource } from './pump.ts' declare module '@deepseek-ai/cordis' { interface Context { @@ -58,6 +70,15 @@ declare module '@deepseek-ai/cordis' { * than process-wide: registrations made from an unscoped context serve * every owner, and registrations made under an agent composition's scope * serve exactly the agents composed under it. + * - Record observation never consumes. Any number of {@link readRecord} + * readers hold their own absolute byte offsets; a record read changes no + * cursor and no notice state, so the model-facing surfaces (the consuming + * {@link read}, completion notices) are unaffected. + * - Record retention is bounded. Appends past the live cap drop the oldest + * retained bytes; a reader below the retained window gets a lossy read, + * never an error. Settlement — the producer outcome, a kill, or teardown — + * trims retention to the settled cap and ends the stream; the record has no + * separate lifecycle. */ export abstract class JobRegistry extends Service { constructor(ctx: Context) { @@ -166,6 +187,31 @@ export abstract class JobRegistry extends Service { */ abstract onJobsChanged(listener: JobsChangedListener): () => void + /** + * Read retained record output from an absolute byte offset without consuming + * it. Resume by passing a previous read's `next`; a foreign offset inside a + * retained chunk returns that whole chunk (its `at` may precede `from`). + * Never marks the job reported. Throws for an unknown or foreign job, a job + * without a {@link JobStart.record} declaration, or a negative or + * non-integer offset. + * @param id - job to read. + * @param from - absolute byte offset to read from (0 for the retained head). + * @param caller - reading agent checked against the owner. + * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. + */ + abstract readRecord(id: JobId, from: number, caller?: Agent): JobRecordRead + + /** + * Register an effect-scoped observer of record advancement — one signal per + * committed append and one at settlement, carrying only the job id. A + * consumer schedules a {@link readRecord} from its own cursor; the registry + * never pushes payloads. Delivery is owner-relative on the same terms as + * {@link onJobsChanged}. Listeners are contained and never awaited. + * @param listener - receives the id whose record advanced. + * @returns disposer that unregisters the listener. + */ + abstract onOutput(listener: JobOutputListener): () => void + /** * Attach an effect-scoped controller that can read and stop jobs. It serves the * owners its registering context's scope covers, and {@link start} refuses an diff --git a/packages/jobs/jobs/src/invariant.ts b/packages/jobs/jobs/src/invariant.ts index 5963179c00..36aca11fd8 100644 --- a/packages/jobs/jobs/src/invariant.ts +++ b/packages/jobs/jobs/src/invariant.ts @@ -40,6 +40,15 @@ function validateSnapshot(snapshot: JobSnapshot, owner: Agent | undefined, fail: if (snapshot.ownerSession !== expectedOwner) { fail(`job ${JSON.stringify(id)} ownerSession does not match its completion owner`) } + + const { outputTotal, outputEarliest } = snapshot + if ((outputTotal !== undefined) !== (outputEarliest !== undefined)) { + fail(`job ${JSON.stringify(id)} record offsets must be present together`) + } else if (outputTotal !== undefined && outputEarliest !== undefined + && (!Number.isSafeInteger(outputTotal) || !Number.isSafeInteger(outputEarliest) + || outputEarliest < 0 || outputEarliest > outputTotal)) { + fail(`job ${JSON.stringify(id)} record offsets must satisfy 0 <= outputEarliest <= outputTotal`) + } } /** Install checks over current unowned records and every terminal snapshot. */ diff --git a/packages/jobs/jobs/src/pump.ts b/packages/jobs/jobs/src/pump.ts new file mode 100644 index 0000000000..8f56b6abc6 --- /dev/null +++ b/packages/jobs/jobs/src/pump.ts @@ -0,0 +1,96 @@ +/** + * Shared poll pump for producers whose output substrate is a non-consuming + * offset reader (the subprocess `readFrom(fromByte)` family). Pure utility — + * no cordis, no timers retained past settlement. + * @module + */ + +import type { JobChannel, RunningJob } from './types.ts' + +/** One non-consuming offset read from a producer-owned stream. */ +export interface JobPumpRead { + /** Text captured since the requested offset (the whole retained tail when lossy). */ + text: string + /** Whole-stream offset to resume from on the next read. */ + nextOffset: number + /** True when the requested offset slid out of the source's retained window. */ + lossy: boolean +} + +/** One producer-owned stream the pump copies into a job record. */ +export interface JobPumpSource { + /** Stream label attached to every chunk this source yields. */ + channel?: JobChannel + /** + * Read everything captured since `fromByte` without consuming it. + * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 first). + * @returns the delta text, the next offset, and the lossy flag. + */ + read(fromByte: number): JobPumpRead +} + +/** Cadence and settlement for one {@link pumpJobOutput} run. */ +export interface JobPumpOptions { + /** Poll interval in milliseconds; a positive finite number. */ + pollMs: number + /** + * Settles when the producer's work finished and its sources hold their + * final bytes. The pump drains once more after settlement and returns; + * a rejection is treated as settlement. + */ + done: Promise +} + +/** + * Copy producer streams into a job record at a bounded cadence: drain every + * source, sleep `pollMs` or until `done` settles, repeat, then drain one + * final time. A lossy source read appends its surviving tail with + * `gapBefore`, so the discontinuity stays visible to observers. Fold the + * returned promise into the producer's `JobHooks.done` chain so the final + * drain lands before settlement trims and closes the record. + * @param job - the running job's producer face receiving the copied chunks. + * @param sources - producer streams, each pumped at its own offset. + * @param options - poll cadence and the producer's settlement promise. + * @returns resolves after the final post-settlement drain. + */ +export async function pumpJobOutput( + job: RunningJob, + sources: readonly JobPumpSource[], + options: JobPumpOptions, +): Promise { + if (!Number.isFinite(options.pollMs) || options.pollMs <= 0) { + throw new Error(`invalid pump pollMs: expected a positive finite number of milliseconds, got ${JSON.stringify(options.pollMs)}`) + } + const states = sources.map(source => ({ source, cursor: 0 })) + const drain = (): void => { + for (const state of states) { + const { source } = state + const read = source.read(state.cursor) + state.cursor = read.nextOffset + if (read.text.length === 0) continue + if (source.channel === undefined && !read.lossy) { + job.append(read.text) + } else { + job.append(read.text, { + ...source.channel !== undefined ? { channel: source.channel } : {}, + ...read.lossy ? { gapBefore: true as const } : {}, + }) + } + } + } + let settled = false + const settlement = options.done.then(() => { settled = true }, () => { settled = true }) + while (!settled) { + drain() + await Promise.race([ + new Promise((resolve) => { + const timer = setTimeout(resolve, options.pollMs) + // The settlement branch wins the race; clear the loser so a finished + // pump holds no pending timer for up to one poll interval. + void settlement.then(() => { clearTimeout(timer); resolve() }) + }), + settlement, + ]) + } + drain() +} diff --git a/packages/jobs/jobs/src/types.ts b/packages/jobs/jobs/src/types.ts index 2842f6a3a5..b42d7815e4 100644 --- a/packages/jobs/jobs/src/types.ts +++ b/packages/jobs/jobs/src/types.ts @@ -38,6 +38,24 @@ export interface JobOutcome { output?: string } +/** + * Record-stream label. Producers without distinct streams omit it; consumers + * treat an unrecognized label like an absent one. + */ +export type JobChannel = 'stdout' | 'stderr' + +/** Options for one {@link RunningJob.append}. */ +export interface JobAppendOptions { + /** Stream label for the chunk; omitted for producers without distinct streams. */ + channel?: JobChannel + /** + * Marks that producer-side bytes between the previous chunk and this one + * were lost (a source window slid before the producer could copy it), so an + * observer can render the discontinuity instead of a silent splice. + */ + gapBefore?: true +} + /** * Producer declaration passed to {@link JobRegistry.start}. The runtime * preflights access and cleanup before invoking {@link run}; the producer owns @@ -50,7 +68,9 @@ export interface JobStart { label: string /** * Optional UTF-8 byte cap for each complete model-facing completion notice or - * output read, including controller status metadata. + * output read, including controller status metadata. Independent of record + * retention: it bounds the consuming model surface, never + * {@link JobRegistry.readRecord}. */ outputLimitBytes?: number /** @@ -61,11 +81,49 @@ export interface JobStart { */ owner?: Agent /** - * Start the work after preflight and synchronously return its hooks. Called - * once; a throw leaves nothing registered, and the producer must clean up any - * partially started resources. + * Declares an observable output record beside the model-facing surfaces: + * {@link RunningJob.append} retains chunks in a bounded ring that any number + * of observers read at absolute byte offsets through + * {@link JobRegistry.readRecord}, and snapshots carry + * {@link JobSnapshot.outputTotal} and {@link JobSnapshot.outputEarliest}. + * Without the declaration `append` logs and drops. */ - run(): JobHooks + record?: true + /** + * Start the work after preflight and synchronously return its hooks. Called + * once with the job's producer face; a throw leaves nothing registered (the + * spent ordinal is skipped), and the producer must clean up any partially + * started resources. + * @param job - the issued id plus the record append and live-detail writers. + */ + run(job: RunningJob): JobHooks +} + +/** + * Producer face of one registered job, handed to {@link JobStart.run} and + * valid for the job's whole life. All methods are synchronous. Writes staged + * inside the starter call are retained and become visible with the + * registration commit; after settlement — the producer's own outcome, a kill, + * or a registry-forced teardown end — both methods log and drop instead of + * throwing, so a producer's trailing flush cannot break its own teardown path. + */ +export interface RunningJob { + /** The registry-issued id (`-N`). */ + readonly id: JobId + /** + * Append one record chunk. Offsets advance by the chunk's UTF-8 byte + * length; an empty chunk is dropped without waking observers. Without a + * {@link JobStart.record} declaration the chunk is logged and dropped. + * @param text - the chunk text, exactly as produced. + * @param options - stream label and gap marker. + */ + append(text: string, options?: JobAppendOptions): void + /** + * Replace the snapshot's status detail with a live progress line (`3/10`). + * Works for every job, with or without a record. + * @param detail - the new detail line. + */ + updateDetail(detail: string): void } /** Hooks through which the runtime controls and observes producer work. */ @@ -79,13 +137,16 @@ export interface JobHooks { * Resolves after the producer releases its resources, not merely when work * finishes. Must not reject; the runtime converts a rejection to `failed`. * If teardown cancellation throws, the runtime may force-fail only the - * registry record without claiming that the work stopped. + * registry record without claiming that the work stopped. Settlement also + * ends the record: fold any record-filling pump into this promise so the + * final drain lands before the registry trims and closes the stream. */ done: Promise /** * Consume output produced since the previous call. The producer formats * truncation and spill notices. Absence marks a final-output-only job; each - * job has one consuming cursor. + * job has one consuming cursor. Independent of the record: this is the + * model-facing projection, {@link JobRegistry.readRecord} the observer one. */ readOutput?(): string } @@ -111,7 +172,10 @@ export interface JobSnapshot { ownerSession?: SessionId /** Current lifecycle state. */ status: JobStatus - /** Kind-specific status detail, present once the producer supplied one (usually terminal). */ + /** + * Kind-specific status detail: live progress while the producer updates it + * through {@link RunningJob.updateDetail}, the terminal detail once settled. + */ detail?: string /** Epoch ms when the job was registered. */ startedAt: number @@ -125,6 +189,17 @@ export interface JobSnapshot { * otherwise spend a model request per teardown layer. */ reported: boolean + /** + * Total UTF-8 bytes ever appended to the record — the offset the next chunk + * starts at. Present exactly when the job declared {@link JobStart.record}. + */ + outputTotal?: number + /** + * Offset of the oldest retained record byte. Greater than zero exactly when + * retention dropped the head; a reader starting below it gets a lossy read. + * Present exactly when the job declared {@link JobStart.record}. + */ + outputEarliest?: number } /** Output and post-read state returned by {@link JobRegistry.read}. */ @@ -139,6 +214,33 @@ export interface JobRead { snapshot: JobSnapshot } +/** One retained record chunk returned by {@link JobRegistry.readRecord}. */ +export interface JobRecordChunk { + /** Absolute offset of the chunk's first byte. */ + at: number + /** Chunk text exactly as appended (possibly tail-trimmed by retention). */ + text: string + /** Stream label, when the producer supplied one. */ + channel?: JobChannel + /** Producer-reported loss immediately before this chunk. */ + gapBefore?: true +} + +/** Result of one non-consuming {@link JobRegistry.readRecord}. */ +export interface JobRecordRead { + /** Retained chunks overlapping `[from, total)`, in offset order. */ + chunks: readonly JobRecordChunk[] + /** + * Offset to resume from — the record's current `outputTotal`. Always a + * chunk boundary: appends land whole and trimming only advances chunk + * starts, and consumers concatenate `chunks` under that assumption, so a + * provider serving partial chunks would silently duplicate text. + */ + next: number + /** True when `from` fell below the oldest retained byte, so bytes are missing before `chunks`. */ + lossy: boolean +} + /** * Completion callback with the exact owner supplied at start, or `undefined` * for an unowned job. Returned promises are observed but not awaited. @@ -158,3 +260,10 @@ export type JobDoneListener = ( * set changed with it. */ export type JobsChangedListener = (owner: Agent | undefined) => void + +/** + * Observer of record advancement for one job: new appended output, or the + * settlement that ends the stream. Carries no payload — a consumer schedules a + * {@link JobRegistry.readRecord} from its own cursor. + */ +export type JobOutputListener = (id: JobId) => void diff --git a/packages/jobs/jobs/tests/invariant.spec.ts b/packages/jobs/jobs/tests/invariant.spec.ts index 5cbaf94b11..fa42eb6c74 100644 --- a/packages/jobs/jobs/tests/invariant.spec.ts +++ b/packages/jobs/jobs/tests/invariant.spec.ts @@ -62,6 +62,7 @@ describe('job-registry invariants', () => { const owner = { id: SessionId('owner') } as Agent expect(() => { notify({ ...BASE, id: JobId('subagent-2'), kind: 'subagent', ownerSession: owner.id }, owner) }) .not.toThrow() + expect(() => { notify({ ...BASE, outputTotal: 8, outputEarliest: 4 }) }).not.toThrow() }) it.each([ @@ -76,6 +77,12 @@ describe('job-registry invariants', () => { [{ ...BASE, finishedAt: 9 }, undefined, /no earlier than startedAt/], [{ ...BASE, finishedAt: 20.5 }, undefined, /no earlier than startedAt/], [{ ...BASE, ownerSession: SessionId('recorded') }, { id: SessionId('actual') } as Agent, /does not match its completion owner/], + [{ ...BASE, outputTotal: 8 }, undefined, /record offsets must be present together/], + [{ ...BASE, outputEarliest: 0 }, undefined, /record offsets must be present together/], + [{ ...BASE, outputTotal: 8, outputEarliest: 9 }, undefined, /0 <= outputEarliest <= outputTotal/], + [{ ...BASE, outputTotal: 8.5, outputEarliest: 0 }, undefined, /0 <= outputEarliest <= outputTotal/], + [{ ...BASE, outputTotal: 8, outputEarliest: 0.5 }, undefined, /0 <= outputEarliest <= outputTotal/], + [{ ...BASE, outputTotal: 8, outputEarliest: -1 }, undefined, /0 <= outputEarliest <= outputTotal/], ] as const)('rejects an incoherent registry snapshot', async (snapshot, owner, message) => { const notify = await setup() expect(() => { notify(snapshot, owner) }).toThrow(message) diff --git a/packages/jobs/jobs/tests/service.spec.ts b/packages/jobs/jobs/tests/service.spec.ts index 6c4f65c52f..ff2c282a27 100644 --- a/packages/jobs/jobs/tests/service.spec.ts +++ b/packages/jobs/jobs/tests/service.spec.ts @@ -1,9 +1,10 @@ -import { describe, expect, it } from 'vitest' +import { describe, expect, it, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' import type { Agent } from '@deepseek-ai/dsh-agent' -import { JobId, JobRegistry } from '@deepseek-ai/dsh-jobs' +import { JobId, JobRegistry, pumpJobOutput } from '@deepseek-ai/dsh-jobs' import type { - JobDoneListener, JobRead, JobSnapshot, JobStart, JobsChangedListener, + JobAppendOptions, JobDoneListener, JobOutputListener, JobPumpSource, JobRead, JobRecordRead, + JobSnapshot, JobStart, JobsChangedListener, RunningJob, } from '@deepseek-ai/dsh-jobs' /** @@ -24,8 +25,9 @@ class StubJobRegistry extends JobRegistry { } start(spec: JobStart): JobId { - spec.run() - return JobId(`${spec.kind}-1`) + const id = JobId(`${spec.kind}-1`) + spec.run({ id, append() {}, updateDetail() {} }) + return id } list(): JobSnapshot[] { @@ -56,6 +58,14 @@ class StubJobRegistry extends JobRegistry { return () => {} } + readRecord(_id: JobId, from: number): JobRecordRead { + return { chunks: [], next: from, lossy: false } + } + + onOutput(_listener: JobOutputListener): () => void { + return () => {} + } + attachController(_name: string): () => void { return () => {} } @@ -74,10 +84,13 @@ describe('JobRegistry seam', () => { expect(ctx.jobs.read(id).text).toBe('') expect(ctx.jobs.kill(id)).toBe('requested') await expect(ctx.jobs.wait(id, 5)).resolves.toMatchObject({ id }) + expect(ctx.jobs.readRecord(id, 0)).toEqual({ chunks: [], next: 0, lossy: false }) const detachListener = ctx.jobs.onJobDone(() => {}) detachListener() const detachChanges = ctx.jobs.onJobsChanged(() => {}) detachChanges() + const detachOutput = ctx.jobs.onOutput(() => {}) + detachOutput() detachController() }) @@ -94,3 +107,83 @@ describe('JobRegistry seam', () => { .rejects.toThrow(/abstract job registry seam; load an implementation such as @deepseek-ai\/dsh-jobs-local/) }) }) + +/** Record every append so pump behavior is observable without a registry. */ +function recordingJob(): { job: RunningJob; appends: { text: string; options?: JobAppendOptions }[] } { + const appends: { text: string; options?: JobAppendOptions }[] = [] + const job: RunningJob = { + id: JobId('bash-1'), + append(text, options) { appends.push({ text, ...options !== undefined ? { options } : {} }) }, + updateDetail() {}, + } + return { job, appends } +} + +/** A scripted source: each read() shifts the next scripted result. */ +function scriptedSource( + reads: { text: string; lossy?: boolean }[], + channel?: 'stdout' | 'stderr', +): { source: JobPumpSource; offsets: number[] } { + const offsets: number[] = [] + let offset = 0 + const source: JobPumpSource = { + ...channel !== undefined ? { channel } : {}, + read(fromByte) { + offsets.push(fromByte) + const next = reads.shift() ?? { text: '' } + offset += Buffer.byteLength(next.text, 'utf8') + return { text: next.text, nextOffset: offset, lossy: next.lossy ?? false } + }, + } + return { source, offsets } +} + +describe('pumpJobOutput', () => { + it('rejects a non-positive poll interval before touching any source', async () => { + const { job } = recordingJob() + await expect(pumpJobOutput(job, [], { pollMs: 0, done: Promise.resolve() })) + .rejects.toThrow(/invalid pump pollMs/) + }) + + it('copies labeled deltas at the poll cadence and resumes each source at its own offset', async () => { + vi.useFakeTimers() + try { + const { job, appends } = recordingJob() + let settle!: () => void + const done = new Promise((resolve) => { settle = resolve }) + const out = scriptedSource([{ text: 'a' }, { text: 'bc' }], 'stdout') + const err = scriptedSource([{ text: '' }, { text: 'E' }], 'stderr') + const pump = pumpJobOutput(job, [out.source, err.source], { pollMs: 50, done }) + + await vi.advanceTimersByTimeAsync(50) + settle() + await pump + expect(appends).toEqual([ + { text: 'a', options: { channel: 'stdout' } }, + { text: 'bc', options: { channel: 'stdout' } }, + { text: 'E', options: { channel: 'stderr' } }, + ]) + // Every read resumed from the previous nextOffset, never from a shared cursor. + expect(out.offsets).toEqual([0, 1, 3]) + expect(err.offsets).toEqual([0, 0, 1]) + // Settlement cleared the raced poll timer instead of leaving it pending. + expect(vi.getTimerCount()).toBe(0) + } finally { + vi.useRealTimers() + } + }) + + it('marks a lossy source read as a gap so observers see the discontinuity', async () => { + const { job, appends } = recordingJob() + const { source } = scriptedSource([{ text: 'tail', lossy: true }]) + await pumpJobOutput(job, [source], { pollMs: 1, done: Promise.resolve() }) + expect(appends).toEqual([{ text: 'tail', options: { gapBefore: true } }]) + }) + + it('treats a rejected done as settlement and still drains the final bytes', async () => { + const { job, appends } = recordingJob() + const { source } = scriptedSource([{ text: 'last' }]) + await pumpJobOutput(job, [source], { pollMs: 1, done: Promise.reject(new Error('producer broke')) }) + expect(appends).toEqual([{ text: 'last' }]) + }) +}) From 8537b8d5bb620fab135b26d0700d845e90584bdc Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 1 Sep 2026 17:52:26 +0800 Subject: [PATCH 014/100] refactor(shell,workflow): produce into the job record instead of ctx.activities MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit bash and pwsh background runs declare record: true and pump their observed streams straight into the job through observeProcessRecord — the open/end pairing, outcome mapping, and registry-absent degradation branches are gone, and the pump's final drain folds into hooks.done so the record holds its last bytes before settlement closes it. activityPollMs becomes recordPollMs. tool-workflow drops its foreground activity mirror deliberately: a foreground run's live phase/log narration had the mirror as its only carrier, and the transcript keeps the recorded run/member lifecycle events. Live narration returns with backgrounded runs when workflow gains run_in_background. --- packages/shell/tool-bash/README.md | 2 +- packages/shell/tool-bash/package.json | 2 - packages/shell/tool-bash/src/index.ts | 34 +-- packages/shell/tool-bash/src/observe.ts | 92 +++----- .../shell/tool-bash/tests/observe.spec.ts | 218 +++++------------- packages/shell/tool-bash/tsconfig.json | 3 - packages/shell/tool-pwsh/README.md | 2 +- packages/shell/tool-pwsh/package.json | 2 - packages/shell/tool-pwsh/src/index.ts | 40 +--- packages/shell/tool-pwsh/src/observe.ts | 92 +++----- .../shell/tool-pwsh/tests/observe.spec.ts | 121 +++------- packages/shell/tool-pwsh/tsconfig.json | 3 - packages/workflow/tool-workflow/README.md | 3 +- packages/workflow/tool-workflow/package.json | 3 - .../workflow/tool-workflow/src/activity.ts | 119 ---------- packages/workflow/tool-workflow/src/index.ts | 5 - .../tests/activity-mirror.spec.ts | 129 ----------- packages/workflow/tool-workflow/tsconfig.json | 3 - 18 files changed, 166 insertions(+), 707 deletions(-) delete mode 100644 packages/workflow/tool-workflow/src/activity.ts delete mode 100644 packages/workflow/tool-workflow/tests/activity-mirror.spec.ts diff --git a/packages/shell/tool-bash/README.md b/packages/shell/tool-bash/README.md index 5e30ed598e..39e894970a 100644 --- a/packages/shell/tool-bash/README.md +++ b/packages/shell/tool-bash/README.md @@ -55,7 +55,7 @@ The tool executes `bash -c ` and returns the combined output. Commands ### Running long commands in the background -Passing `run_in_background: true` returns a job id immediately and no timeout applies; the command keeps running while the agent works on something else. The agent reads its output with `job_output` (non-blocking unless `wait: true`), lists jobs with `job_list`, and stops it with `job_kill`; a finished job notifies the owning agent in-session. Background support needs the generic job runtime (`dsh-jobs-local`) and its control tools (`dsh-tool-jobs`) mounted. When the optional `ctx.activities` registry is loaded, the committed background run is also mirrored into it best-effort: a `bash` activity correlated to the call and job pumps the handle's non-consuming `observed` readers at `activityPollMs` (default 150), so the Web client streams live output without touching the job's cursor; any observation failure is logged and swallowed. +Passing `run_in_background: true` returns a job id immediately and no timeout applies; the command keeps running while the agent works on something else. The agent reads its output with `job_output` (non-blocking unless `wait: true`), lists jobs with `job_list`, and stops it with `job_kill`; a finished job notifies the owning agent in-session. Background support needs the generic job runtime (`dsh-jobs-local`) and its control tools (`dsh-tool-jobs`) mounted. The background job declares an observation record: the run's non-consuming `observed` readers are pumped into it at `recordPollMs` (default 150), so the Web client streams live output without touching the job's consuming cursor; a pump failure is logged and swallowed while the job runs on. ### Sandboxed execution and escalation diff --git a/packages/shell/tool-bash/package.json b/packages/shell/tool-bash/package.json index 7c143f415d..d4be992ae9 100644 --- a/packages/shell/tool-bash/package.json +++ b/packages/shell/tool-bash/package.json @@ -37,7 +37,6 @@ "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-jobs": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-activity": "workspace:^", "@deepseek-ai/dsh-sandbox": "workspace:^", "@deepseek-ai/dsh-sandbox-policy": "workspace:^", "@deepseek-ai/dsh-shell": "workspace:^", @@ -59,7 +58,6 @@ "@deepseek-ai/dsh-jobs": "workspace:^", "@deepseek-ai/dsh-jobs-local": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-activity": "workspace:^", "@deepseek-ai/dsh-sandbox": "workspace:^", "@deepseek-ai/dsh-sandbox-policy": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", diff --git a/packages/shell/tool-bash/src/index.ts b/packages/shell/tool-bash/src/index.ts index c79fa2c4c6..c4586d0b10 100644 --- a/packages/shell/tool-bash/src/index.ts +++ b/packages/shell/tool-bash/src/index.ts @@ -22,10 +22,9 @@ import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandb import { ESCALATION_TARGETS, approveEscalation, canonicalPath, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox' import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy' import { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-shell' -import type { ShellProcess, ShellRunResult } from '@deepseek-ai/dsh-shell' -import type {} from '@deepseek-ai/dsh-activity' +import type { ShellRunResult } from '@deepseek-ai/dsh-shell' import { processOutcome } from './background.ts' -import { observeBackgroundActivity } from './observe.ts' +import { observeProcessRecord } from './observe.ts' import { parseExitStatus, renderProcessRead, renderResult } from './render.ts' export const name = 'tool-bash' @@ -35,14 +34,14 @@ export const inject = ['tools', 'shell', 'systemPrompt', 'shellEnv'] export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean - /** Poll cadence for mirroring background output into `ctx.activities`, in milliseconds (default 150). */ - activityPollMs?: number + /** Poll cadence for copying background output into the job record, in milliseconds (default 150). */ + recordPollMs?: number } /** Runtime configuration schema for the bash tool plugin. */ export const Config: z = z.object({ enableRunInBackground: z.boolean().default(true), - activityPollMs: z.number() + recordPollMs: z.number() .step(1) .min(1) .max(Number.MAX_SAFE_INTEGER) @@ -197,7 +196,7 @@ const BACKGROUND_OUTPUT_PROPERTIES = { export function apply(ctx: Context, config: Config = {}): void { const backgroundEnabled = config.enableRunInBackground ?? true - const activityPollMs = config.activityPollMs ?? 150 + const recordPollMs = config.recordPollMs ?? 150 const defaultMode = ctx.shell.sandboxMode const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS const sandboxPolicy: SandboxPolicyService | undefined = defaultMode === undefined ? undefined : ctx.get('sandboxPolicy') @@ -370,32 +369,23 @@ export function apply(ctx: Context, config: Config = {}): void { error.name = 'AbortError' throw error } - // Task preflight finishes before the starter can spawn a process. - let started: ShellProcess | undefined const id = jobs.start({ kind: 'bash', label: args.command, ...exec.agent ? { owner: exec.agent } : {}, - run: () => { + record: true, + run: (job) => { const proc = ctx.shell.start(ctx.shell.resolve(request)) - started = proc + // The pump's final drain is folded into `done` so the record holds + // its last bytes before settlement trims and closes it. + const observed = observeProcessRecord(ctx, job, proc, recordPollMs) return { cancel: () => void proc.kill(), - done: proc.done.then(() => processOutcome(proc)), + done: observed.then(() => proc.done).then(() => processOutcome(proc)), readOutput: () => renderProcessRead(proc.readOutput(), proc.sandbox, escalationModes), } }, }) - // The starter ran synchronously inside the committed start; mirror the - // spawned process into the optional observation registry. - if (started !== undefined) { - observeBackgroundActivity(ctx, started, { - kind: 'bash', - label: args.command, - ...exec.agent ? { owner: exec.agent } : {}, - correlation: { callId: exec.callId, jobId: id }, - }, activityPollMs, processOutcome) - } return { kind: 'background' as const, jobId: id } } const result = await ctx.shell.run(ctx.shell.resolve({ diff --git a/packages/shell/tool-bash/src/observe.ts b/packages/shell/tool-bash/src/observe.ts index 3dc2aeeb79..2e2874f9c1 100644 --- a/packages/shell/tool-bash/src/observe.ts +++ b/packages/shell/tool-bash/src/observe.ts @@ -1,82 +1,44 @@ /** - * Best-effort process-observation tap for background bash runs: mirrors the - * spawned process's captured streams into `ctx.activities` so non-consuming - * observers (the Web client) see live output without touching the job's - * consuming `readOutput` cursor. Absent registry or absent backend offset - * readers degrade to no observation; the job path is unaffected either way. + * Record tap for background bash runs: copies the spawned process's captured + * streams into the job's observation record, so non-consuming observers (the + * Web client) see live output without touching the job's consuming + * `readOutput` cursor. Observation is strictly best-effort: absent backend + * offset readers degrade to no observation, and a pump failure is logged and + * swallowed — the job path is unaffected either way. * * @module @deepseek-ai/dsh-tool-bash/observe */ import type { Context } from '@deepseek-ai/cordis' -import type { Agent } from '@deepseek-ai/dsh-agent' import type { ShellProcess } from '@deepseek-ai/dsh-shell' -import { pumpActivityOutput } from '@deepseek-ai/dsh-activity' -import type { ActivityCorrelation, ActivityKind, ActivityPumpSource } from '@deepseek-ai/dsh-activity' - -/** Identity of one observed background run. */ -export interface ObserveBackgroundSpec { - /** Process kind — the producing tool's registered {@link ActivityKind}. */ - kind: ActivityKind - /** One-line label (the command). */ - label: string - /** Owning live agent, when the call has one. */ - owner?: Agent - /** Links to the starting tool call and the registered job. */ - correlation: ActivityCorrelation -} +import { pumpJobOutput } from '@deepseek-ai/dsh-jobs' +import type { JobPumpSource, RunningJob } from '@deepseek-ai/dsh-jobs' /** - * Open a process beside a committed background job and pump the handle's - * non-consuming offset readers into it until the run settles, then record the - * mapped outcome. Observation is strictly best-effort: without a - * `ctx.activities` registry this is a no-op, without backend offset readers - * the process still carries status and settlement, and ANY observation - * failure — including a rejected `open()` — is logged and swallowed, because - * the background job is already committed and running. - * @param ctx - plugin context used for the optional registry and warning logs. + * Pump the process's non-consuming offset readers into the job record until + * the run settles, then drain once more. The returned promise never rejects: + * a pump failure is logged and the record simply stops advancing, while the + * process and its job continue untouched. + * @param ctx - plugin context used for the warning log. + * @param job - the running job's producer face receiving the copied chunks. * @param proc - the started background process handle. - * @param spec - process identity and correlation for the registry row. * @param pollMs - producer-configured pump cadence in milliseconds. - * @param outcome - maps the settled handle to the process outcome. + * @returns resolves after the final drain; fold into the job's `done` chain so + * the record holds its final bytes before settlement closes it. */ -export function observeBackgroundActivity( +export function observeProcessRecord( ctx: Context, + job: RunningJob, proc: ShellProcess, - spec: ObserveBackgroundSpec, pollMs: number, - outcome: (proc: ShellProcess) => { status: 'completed' | 'killed'; detail: string }, -): void { - try { - const processes = ctx.get('activities') - if (processes === undefined) return - const handle = processes.open({ - kind: spec.kind, - label: spec.label, - ...spec.owner !== undefined ? { owner: spec.owner } : {}, - correlation: spec.correlation, +): Promise { + const sources: JobPumpSource[] = [] + const stdout = proc.observed?.stdout + if (stdout !== undefined) sources.push({ channel: 'stdout', read: from => stdout.readFrom(from) }) + const stderr = proc.observed?.stderr + if (stderr !== undefined) sources.push({ channel: 'stderr', read: from => stderr.readFrom(from) }) + return pumpJobOutput(job, sources, { pollMs, done: proc.done }) + .catch((error: unknown) => { + ctx.logger.warn(`record observation pump for ${job.id} failed: ${String(error)}`) }) - const sources: ActivityPumpSource[] = [] - const stdout = proc.observed?.stdout - if (stdout !== undefined) sources.push({ channel: 'stdout', read: from => stdout.readFrom(from) }) - const stderr = proc.observed?.stderr - if (stderr !== undefined) sources.push({ channel: 'stderr', read: from => stderr.readFrom(from) }) - void pumpActivityOutput(handle, sources, { pollMs, done: proc.done }) - .catch((error: unknown) => { - ctx.logger.warn(`activity observation pump for ${handle.id} failed: ${String(error)}`) - }) - .then(async () => { - // The pump can fail while the process is still running; the outcome - // mapping requires a settled handle, and `end` is first-wins, so an - // early mapping would freeze a wrong terminal state onto the row. - // `proc.done` never rejects. - await proc.done - handle.end(outcome(proc)) - }) - .catch((error: unknown) => { - ctx.logger.warn(`activity settlement mapping for ${handle.id} failed: ${String(error)}`) - }) - } catch (error: unknown) { - ctx.logger.warn(`activity observation unavailable for this run: ${String(error)}`) - } } diff --git a/packages/shell/tool-bash/tests/observe.spec.ts b/packages/shell/tool-bash/tests/observe.spec.ts index 714558227f..8a4ac6ae2a 100644 --- a/packages/shell/tool-bash/tests/observe.spec.ts +++ b/packages/shell/tool-bash/tests/observe.spec.ts @@ -10,18 +10,19 @@ import ToolRuntime from '@deepseek-ai/dsh-tools' import AgentRegistry from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' +import type { JobId, RunningJob } from '@deepseek-ai/dsh-jobs' import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs' -import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' -import type { ActivitySnapshot } from '@deepseek-ai/dsh-activity' +import type { ShellProcess } from '@deepseek-ai/dsh-shell' import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local' import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local' import * as ToolBash from '@deepseek-ai/dsh-tool-bash' +import { observeProcessRecord } from '../src/observe.ts' import * as BashEnvPlugin from '@deepseek-ai/dsh-shell-env' const testToolSignal = new AbortController().signal const spillDir = mkdtempSync(join(tmpdir(), 'dsh-tool-bash-observe-spec-')) -/** Job harness plus the observation registry, with a fast pump for tests. */ +/** Job harness with a fast record pump for tests. */ async function setup() { const ctx = new Context() await ctx.plugin(SystemPrompt) @@ -29,12 +30,11 @@ async function setup() { await ctx.plugin(AgentRegistry) await ctx.plugin(LocalJobRegistry) await ctx.plugin(ToolTasks) - await ctx.plugin(LocalActivityRegistry) await ctx.plugin(LocalSubprocessRuntime) ;(ctx.subprocess as LocalSubprocessRuntime).internals = { spillDir } await ctx.plugin(BashEnvPlugin) await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 }) - await ctx.plugin(ToolBash, { activityPollMs: 25 }) + await ctx.plugin(ToolBash, { recordPollMs: 25 }) return ctx } @@ -62,12 +62,12 @@ async function until(read: () => T | undefined, timeoutMs = 5_000): Promise chunk.text).join('') +function retainedText(ctx: Context, id: JobId, caller?: Agent): string { + return ctx.jobs.readRecord(id, 0, caller).chunks.map(chunk => chunk.text).join('') } -describe('background bash observation', () => { - it('mirrors a background run into ctx.activities with correlation, live output, and settlement', async () => { +describe('background bash record', () => { + it('streams a background run into the job record with live output and settlement', async () => { const ctx = await setup() const ack = await call(ctx, { command: 'printf "line-1\\n"; sleep 0.4; printf "line-2\\n"', @@ -77,21 +77,16 @@ describe('background bash observation', () => { expect(text(ack)).toContain('started background job') const job = ctx.jobs.list()[0] expect(job).toBeDefined() + expect(job!.outputTotal).toBeDefined() - const snapshot = await until(() => - ctx.activities.list().find(row => row.correlation?.jobId === job!.id)) - expect(snapshot.kind).toBe('bash') - expect(snapshot.label).toContain('printf') - expect(String(snapshot.correlation?.callId)).toMatch(/^observe-call-/) + // Live output appears in the record while the command is still running. + await until(() => retainedText(ctx, job!.id).includes('line-1') ? true : undefined) + expect(ctx.jobs.get(job!.id).status).toBe('running') - // Live output appears while the command is still running. - await until(() => retainedText(ctx, snapshot.id).includes('line-1') ? true : undefined) - expect(ctx.activities.get(snapshot.id).status).toBe('running') - - // Settlement carries the mapped bash outcome and the trailing output. - await until(() => ctx.activities.get(snapshot.id).status === 'completed' ? true : undefined) - expect(ctx.activities.get(snapshot.id).detail).toBe('exit code: 0') - expect(retainedText(ctx, snapshot.id)).toContain('line-2') + // Settlement ends the record with the job; the trailing bytes are drained first. + await until(() => ctx.jobs.get(job!.id).status === 'completed' ? true : undefined) + expect(ctx.jobs.get(job!.id).detail).toBe('exit code: 0') + expect(retainedText(ctx, job!.id)).toContain('line-2') // The model-facing consuming cursor still delivers everything: observation stole nothing. const collected = await until(() => { @@ -101,15 +96,13 @@ describe('background bash observation', () => { expect(collected).toContain('line-2') }) - it('a killed background job settles its mirrored process as killed', async () => { + it('a killed background job ends its record with the killed settlement', async () => { const ctx = await setup() await call(ctx, { command: 'sleep 60', description: 'test command', run_in_background: true }) const job = ctx.jobs.list()[0] - const snapshot = await until(() => - ctx.activities.list().find(row => row.correlation?.jobId === job!.id)) ctx.jobs.kill(job!.id, undefined, 'test cleanup') - await until(() => ctx.activities.get(snapshot.id).status === 'killed' ? true : undefined) - expect(ctx.activities.get(snapshot.id).detail).toMatch(/signal|killed before exit/) + await until(() => ctx.jobs.get(job!.id).status === 'killed' ? true : undefined) + expect(ctx.jobs.get(job!.id).detail).toMatch(/signal|killed before exit/) }) it('labels stderr chunks with their channel', async () => { @@ -120,153 +113,53 @@ describe('background bash observation', () => { run_in_background: true, }) const job = ctx.jobs.list()[0] - const snapshot = await until(() => - ctx.activities.list().find(row => row.correlation?.jobId === job!.id)) - await until(() => ctx.activities.get(snapshot.id).status === 'completed' ? true : undefined) - const chunks = ctx.activities.read(snapshot.id, 0).chunks + await until(() => ctx.jobs.get(job!.id).status === 'completed' ? true : undefined) + const chunks = ctx.jobs.readRecord(job!.id, 0).chunks expect(chunks.find(chunk => chunk.text.includes('out-line'))?.channel).toBe('stdout') expect(chunks.find(chunk => chunk.text.includes('err-line'))?.channel).toBe('stderr') }) +}) - it('a registry whose handle rejects appends degrades to a warning and still settles', async () => { - const ctx = new Context() - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRuntime) - await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalJobRegistry) - await ctx.plugin(ToolTasks) - const ended: unknown[] = [] - await ctx.plugin({ - name: 'appending-broken-activities-probe', - apply(child: Context) { - child.provide('activities', { - open: () => ({ - id: 'bash-1', - append() { throw new Error('append boom') }, - updateDetail() {}, - end(outcome: unknown) { ended.push(outcome) }, - }), - }) +describe('observeProcessRecord', () => { + /** A RunningJob face recording appends for pump assertions. */ + function recordingJob(): { job: RunningJob; appends: string[] } { + const appends: string[] = [] + return { + job: { + id: 'bash-1' as JobId, + append(chunk) { appends.push(chunk) }, + updateDetail() {}, }, - }) - await ctx.plugin(LocalSubprocessRuntime) - ;(ctx.subprocess as LocalSubprocessRuntime).internals = { spillDir } - await ctx.plugin(BashEnvPlugin) - await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 }) - const warn = vi.fn() - ctx.logger.warn = warn as never - await ctx.plugin(ToolBash, { activityPollMs: 25 }) - await call(ctx, { command: 'echo tolerated', description: 'test command', run_in_background: true }) - await until(() => ended.length > 0 ? true : undefined) - expect(warn).toHaveBeenCalledWith(expect.stringContaining('activity observation pump')) - expect(ended[0]).toMatchObject({ status: 'completed' }) + appends, + } + } + + it('degrades to no observation when the backend exposes no offset readers', async () => { + const ctx = new Context() + const { job, appends } = recordingJob() + const proc = { done: Promise.resolve() } as unknown as ShellProcess + await observeProcessRecord(ctx, job, proc, 25) + expect(appends).toEqual([]) }) - it('a pump failure waits for process settlement before mapping the outcome', async () => { + it('contains a pump failure with a warning; the job path is unaffected', async () => { const ctx = new Context() - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRuntime) - await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalJobRegistry) - await ctx.plugin(ToolTasks) - const ended: unknown[] = [] - await ctx.plugin({ - name: 'early-failing-activities-probe', - apply(child: Context) { - child.provide('activities', { - open: () => ({ - id: 'bash-1', - append() { throw new Error('append boom') }, - updateDetail() {}, - end(outcome: unknown) { ended.push(outcome) }, - }), - }) - }, - }) - await ctx.plugin(LocalSubprocessRuntime) - ;(ctx.subprocess as LocalSubprocessRuntime).internals = { spillDir } - await ctx.plugin(BashEnvPlugin) - await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 }) const warn = vi.fn() ctx.logger.warn = warn as never - await ctx.plugin(ToolBash, { activityPollMs: 25 }) - // One early line makes the first pump poll append (and fail) while the - // process still has most of its sleep ahead. - await call(ctx, { command: 'printf "early\\n"; sleep 0.7', description: 'test command', run_in_background: true }) - await until(() => warn.mock.calls.some(args => String(args[0]).includes('activity observation pump')) ? true : undefined) - // The pump already failed; the outcome must wait for real settlement - // rather than freezing a fake terminal state onto the running process. - expect(ended).toHaveLength(0) - await until(() => ended.length > 0 ? true : undefined) - expect(ended[0]).toMatchObject({ status: 'completed', detail: 'exit code: 0' }) - }) - - it('a throwing end() is swallowed by the settlement-mapping catch', async () => { - const ctx = new Context() - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRuntime) - await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalJobRegistry) - await ctx.plugin(ToolTasks) - await ctx.plugin({ - name: 'end-throwing-activities-probe', - apply(child: Context) { - child.provide('activities', { - open: () => ({ - id: 'bash-1', - append() {}, - updateDetail() {}, - end() { throw new Error('end boom') }, - }), - }) + const { job } = recordingJob() + const proc = { + done: new Promise((resolve) => { setTimeout(resolve, 10) }), + observed: { + stdout: { readFrom() { throw new Error('reader boom') } }, }, - }) - await ctx.plugin(LocalSubprocessRuntime) - ;(ctx.subprocess as LocalSubprocessRuntime).internals = { spillDir } - await ctx.plugin(BashEnvPlugin) - await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 }) - const warn = vi.fn() - ctx.logger.warn = warn as never - await ctx.plugin(ToolBash, { activityPollMs: 25 }) - await call(ctx, { command: 'echo settled', description: 'test command', run_in_background: true }) - await until(() => warn.mock.calls.some(args => String(args[0]).includes('activity settlement mapping')) ? true : undefined) - }) - - it('a throwing observation registry never breaks the background call', async () => { - const ctx = new Context() - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRuntime) - await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalJobRegistry) - await ctx.plugin(ToolTasks) - await ctx.plugin({ - name: 'broken-activities-probe', - apply(child: Context) { - child.provide('activities', { open() { throw new Error('observation boom') } }) - }, - }) - await ctx.plugin(LocalSubprocessRuntime) - ;(ctx.subprocess as LocalSubprocessRuntime).internals = { spillDir } - await ctx.plugin(BashEnvPlugin) - await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 }) - const warn = vi.fn() - ctx.logger.warn = warn as never - await ctx.plugin(ToolBash, { activityPollMs: 25 }) - const ack = await call(ctx, { command: 'echo resilient', description: 'test command', run_in_background: true }) - expect(text(ack)).toContain('started background job') - expect(warn).toHaveBeenCalledWith(expect.stringContaining('activity observation unavailable')) - // The job itself still completes and reads normally. - const job = ctx.jobs.list()[0] - const read = await until(() => { - const value = ctx.jobs.read(job!.id) - return value.text.includes('resilient') ? value : undefined - }) - expect(read.snapshot.status).toBe('completed') + } as unknown as ShellProcess + await observeProcessRecord(ctx, job, proc, 5) + expect(warn).toHaveBeenCalledWith(expect.stringContaining('record observation pump for bash-1 failed')) }) }) -describe('owned background observation', () => { - it('mirrors an owned background run under the owning session', async () => { +describe('owned background record', () => { + it('fences an owned background run record under the owning session', async () => { const ctx = await setup() const owner = { id: SessionId('observe-owner'), @@ -284,8 +177,9 @@ describe('owned background observation', () => { }) const job = ctx.jobs.list(owner)[0] expect(job).toBeDefined() - const row = await until(() => ctx.activities.list(owner).find(item => item.correlation?.jobId === job!.id)) - expect(row.ownerSession).toBe(owner.id) + expect(job!.ownerSession).toBe(owner.id) await until(() => ctx.jobs.get(job!.id, owner).status === 'completed' ? true : undefined) + expect(() => retainedText(ctx, job!.id)).toThrow(/belongs to another session/) + await until(() => retainedText(ctx, job!.id, owner).includes('owned') ? true : undefined) }) }) diff --git a/packages/shell/tool-bash/tsconfig.json b/packages/shell/tool-bash/tsconfig.json index 8aa66f93ff..304d983a95 100644 --- a/packages/shell/tool-bash/tsconfig.json +++ b/packages/shell/tool-bash/tsconfig.json @@ -49,9 +49,6 @@ }, { "path": "../../sandbox/sandbox-policy" - }, - { - "path": "../../activity/activity" } ] } diff --git a/packages/shell/tool-pwsh/README.md b/packages/shell/tool-pwsh/README.md index 8ea7e6f1e2..cfd6af5fe0 100644 --- a/packages/shell/tool-pwsh/README.md +++ b/packages/shell/tool-pwsh/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -`dsh-tool-pwsh` gives the agent a `pwsh` tool that runs PowerShell commands through the mounted shell executor — the Windows counterpart of `dsh-tool-bash`, mirroring it call-for-call. Each call runs in a fresh pwsh process, so no state survives; `run_in_background` turns long-running commands into background jobs. Commands are PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables, with no dialect translation. Every call runs with the managed `DSH_*` environment, and under a sandboxing executor the tool teaches and enforces the Windows-specific language-mode and named-pipe contracts. Mount it with a PowerShell executor such as `dsh-pwsh-local` and the `dsh-shell-env` plugin. When the optional `ctx.activities` registry is loaded, a committed background run is also mirrored into it best-effort as a `pwsh` activity pumped at `activityPollMs` (default 150), exactly like `dsh-tool-bash`. +`dsh-tool-pwsh` gives the agent a `pwsh` tool that runs PowerShell commands through the mounted shell executor — the Windows counterpart of `dsh-tool-bash`, mirroring it call-for-call. Each call runs in a fresh pwsh process, so no state survives; `run_in_background` turns long-running commands into background jobs. Commands are PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables, with no dialect translation. Every call runs with the managed `DSH_*` environment, and under a sandboxing executor the tool teaches and enforces the Windows-specific language-mode and named-pipe contracts. Mount it with a PowerShell executor such as `dsh-pwsh-local` and the `dsh-shell-env` plugin. A background run's job declares an observation record pumped at `recordPollMs` (default 150), exactly like `dsh-tool-bash`. ## Table of Contents diff --git a/packages/shell/tool-pwsh/package.json b/packages/shell/tool-pwsh/package.json index b95e102218..49c3942a30 100644 --- a/packages/shell/tool-pwsh/package.json +++ b/packages/shell/tool-pwsh/package.json @@ -37,7 +37,6 @@ "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-jobs": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-activity": "workspace:^", "@deepseek-ai/dsh-sandbox": "workspace:^", "@deepseek-ai/dsh-sandbox-policy": "workspace:^", "@deepseek-ai/dsh-shell": "workspace:^", @@ -59,7 +58,6 @@ "@deepseek-ai/dsh-jobs-local": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-loader-smoke": "workspace:^", - "@deepseek-ai/dsh-activity": "workspace:^", "@deepseek-ai/dsh-pwsh-local": "workspace:^", "@deepseek-ai/dsh-sandbox": "workspace:^", "@deepseek-ai/dsh-sandbox-policy": "workspace:^", diff --git a/packages/shell/tool-pwsh/src/index.ts b/packages/shell/tool-pwsh/src/index.ts index 66c29b604f..a7926e1b34 100644 --- a/packages/shell/tool-pwsh/src/index.ts +++ b/packages/shell/tool-pwsh/src/index.ts @@ -32,11 +32,10 @@ import type {} from '@deepseek-ai/dsh-user-approval' import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox' import { ESCALATION_TARGETS, approveEscalation, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox' import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy' -import type { ShellProcess, ShellRunResult } from '@deepseek-ai/dsh-shell' +import type { ShellRunResult } from '@deepseek-ai/dsh-shell' import { parseExitStatus } from '@deepseek-ai/dsh-shell' -import type {} from '@deepseek-ai/dsh-activity' import { processOutcome } from './background.ts' -import { observeBackgroundActivity } from './observe.ts' +import { observeProcessRecord } from './observe.ts' import { renderPwshProcessRead, renderPwshResult } from './render.ts' import type { RenderablePwshResult } from './render.ts' @@ -46,12 +45,6 @@ declare module '@deepseek-ai/dsh-jobs' { } } -declare module '@deepseek-ai/dsh-activity' { - interface ActivityKindMap { - pwsh: 'pwsh' - } -} - export const name = 'tool-pwsh' export const inject = ['tools', 'shell', 'systemPrompt', 'shellEnv'] @@ -60,14 +53,14 @@ export const inject = ['tools', 'shell', 'systemPrompt', 'shellEnv'] export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean - /** Poll cadence for mirroring background output into `ctx.activities`, in milliseconds (default 150). */ - activityPollMs?: number + /** Poll cadence for copying background output into the job record, in milliseconds (default 150). */ + recordPollMs?: number } /** Runtime configuration schema for the pwsh tool plugin. */ export const Config: z = z.object({ enableRunInBackground: z.boolean().default(true), - activityPollMs: z.number() + recordPollMs: z.number() .step(1) .min(1) .max(Number.MAX_SAFE_INTEGER) @@ -210,7 +203,7 @@ const BACKGROUND_OUTPUT_PROPERTIES = { /* jscpd:ignore-start -- deliberate mirror of dsh-tool-bash's apply() preamble (pwsh-tool-and-executor Agent Note). */ export function apply(ctx: Context, config: Config = {}): void { const backgroundEnabled = config.enableRunInBackground ?? true - const activityPollMs = config.activityPollMs ?? 150 + const recordPollMs = config.recordPollMs ?? 150 const defaultMode = ctx.shell.sandboxMode const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS const sandboxPolicy: SandboxPolicyService | undefined = defaultMode === undefined ? undefined : ctx.get('sandboxPolicy') @@ -394,32 +387,23 @@ export function apply(ctx: Context, config: Config = {}): void { error.name = 'AbortError' throw error } - // Task preflight finishes before the starter can spawn a process. - let started: ShellProcess | undefined const id = jobs.start({ kind: 'pwsh', label: args.command, ...exec.agent ? { owner: exec.agent } : {}, - run: () => { + record: true, + run: (job) => { const proc = ctx.shell.start(ctx.shell.resolve(request)) - started = proc + // The pump's final drain is folded into `done` so the record holds + // its last bytes before settlement trims and closes it. + const observed = observeProcessRecord(ctx, job, proc, recordPollMs) return { cancel: () => void proc.kill(), - done: proc.done.then(() => processOutcome(proc)), + done: observed.then(() => proc.done).then(() => processOutcome(proc)), readOutput: () => renderPwshProcessRead(proc.readOutput(), proc.sandbox, escalationModes), } }, }) - // The starter ran synchronously inside the committed start; mirror the - // spawned process into the optional observation registry. - if (started !== undefined) { - observeBackgroundActivity(ctx, started, { - kind: 'pwsh', - label: args.command, - ...exec.agent ? { owner: exec.agent } : {}, - correlation: { callId: exec.callId, jobId: id }, - }, activityPollMs, processOutcome) - } return { kind: 'background' as const, jobId: id } } const result = await ctx.shell.run(ctx.shell.resolve({ diff --git a/packages/shell/tool-pwsh/src/observe.ts b/packages/shell/tool-pwsh/src/observe.ts index abf325c6b9..6e9e466981 100644 --- a/packages/shell/tool-pwsh/src/observe.ts +++ b/packages/shell/tool-pwsh/src/observe.ts @@ -1,84 +1,46 @@ /** - * Best-effort process-observation tap for background pwsh runs: mirrors the - * spawned process's captured streams into `ctx.activities` so non-consuming - * observers (the Web client) see live output without touching the job's - * consuming `readOutput` cursor. Absent registry or absent backend offset - * readers degrade to no observation; the job path is unaffected either way. + * Record tap for background pwsh runs: copies the spawned process's captured + * streams into the job's observation record, so non-consuming observers (the + * Web client) see live output without touching the job's consuming + * `readOutput` cursor. Observation is strictly best-effort: absent backend + * offset readers degrade to no observation, and a pump failure is logged and + * swallowed — the job path is unaffected either way. * * @module @deepseek-ai/dsh-tool-pwsh/observe */ /* jscpd:ignore-start -- mirrors tool-bash's observe tap by design, like render/background. */ import type { Context } from '@deepseek-ai/cordis' -import type { Agent } from '@deepseek-ai/dsh-agent' import type { ShellProcess } from '@deepseek-ai/dsh-shell' -import { pumpActivityOutput } from '@deepseek-ai/dsh-activity' -import type { ActivityCorrelation, ActivityKind, ActivityPumpSource } from '@deepseek-ai/dsh-activity' - -/** Identity of one observed background run. */ -export interface ObserveBackgroundSpec { - /** Process kind — the producing tool's registered {@link ActivityKind}. */ - kind: ActivityKind - /** One-line label (the command). */ - label: string - /** Owning live agent, when the call has one. */ - owner?: Agent - /** Links to the starting tool call and the registered job. */ - correlation: ActivityCorrelation -} +import { pumpJobOutput } from '@deepseek-ai/dsh-jobs' +import type { JobPumpSource, RunningJob } from '@deepseek-ai/dsh-jobs' /** - * Open a process beside a committed background job and pump the handle's - * non-consuming offset readers into it until the run settles, then record the - * mapped outcome. Observation is strictly best-effort: without a - * `ctx.activities` registry this is a no-op, without backend offset readers - * the process still carries status and settlement, and ANY observation - * failure — including a rejected `open()` — is logged and swallowed, because - * the background job is already committed and running. - * @param ctx - plugin context used for the optional registry and warning logs. + * Pump the process's non-consuming offset readers into the job record until + * the run settles, then drain once more. The returned promise never rejects: + * a pump failure is logged and the record simply stops advancing, while the + * process and its job continue untouched. + * @param ctx - plugin context used for the warning log. + * @param job - the running job's producer face receiving the copied chunks. * @param proc - the started background process handle. - * @param spec - process identity and correlation for the registry row. * @param pollMs - producer-configured pump cadence in milliseconds. - * @param outcome - maps the settled handle to the process outcome. + * @returns resolves after the final drain; fold into the job's `done` chain so + * the record holds its final bytes before settlement closes it. */ -export function observeBackgroundActivity( +export function observeProcessRecord( ctx: Context, + job: RunningJob, proc: ShellProcess, - spec: ObserveBackgroundSpec, pollMs: number, - outcome: (proc: ShellProcess) => { status: 'completed' | 'killed'; detail: string }, -): void { - try { - const processes = ctx.get('activities') - if (processes === undefined) return - const handle = processes.open({ - kind: spec.kind, - label: spec.label, - ...spec.owner !== undefined ? { owner: spec.owner } : {}, - correlation: spec.correlation, +): Promise { + const sources: JobPumpSource[] = [] + const stdout = proc.observed?.stdout + if (stdout !== undefined) sources.push({ channel: 'stdout', read: from => stdout.readFrom(from) }) + const stderr = proc.observed?.stderr + if (stderr !== undefined) sources.push({ channel: 'stderr', read: from => stderr.readFrom(from) }) + return pumpJobOutput(job, sources, { pollMs, done: proc.done }) + .catch((error: unknown) => { + ctx.logger.warn(`record observation pump for ${job.id} failed: ${String(error)}`) }) - const sources: ActivityPumpSource[] = [] - const stdout = proc.observed?.stdout - if (stdout !== undefined) sources.push({ channel: 'stdout', read: from => stdout.readFrom(from) }) - const stderr = proc.observed?.stderr - if (stderr !== undefined) sources.push({ channel: 'stderr', read: from => stderr.readFrom(from) }) - void pumpActivityOutput(handle, sources, { pollMs, done: proc.done }) - .catch((error: unknown) => { - ctx.logger.warn(`activity observation pump for ${handle.id} failed: ${String(error)}`) - }) - .then(async () => { - // The pump can fail while the process is still running; the outcome - // mapping requires a settled handle, and `end` is first-wins, so an - // early mapping would freeze a wrong terminal state onto the row. - // `proc.done` never rejects. - await proc.done - handle.end(outcome(proc)) - }) - .catch((error: unknown) => { - ctx.logger.warn(`activity settlement mapping for ${handle.id} failed: ${String(error)}`) - }) - } catch (error: unknown) { - ctx.logger.warn(`activity observation unavailable for this run: ${String(error)}`) - } } /* jscpd:ignore-end */ diff --git a/packages/shell/tool-pwsh/tests/observe.spec.ts b/packages/shell/tool-pwsh/tests/observe.spec.ts index c9024203fb..0fbdcb80de 100644 --- a/packages/shell/tool-pwsh/tests/observe.spec.ts +++ b/packages/shell/tool-pwsh/tests/observe.spec.ts @@ -8,7 +8,6 @@ import AgentRegistry from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs' -import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' import { ShellExecutor } from '@deepseek-ai/dsh-shell' import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellRunResult } from '@deepseek-ai/dsh-shell' import * as ToolPwsh from '@deepseek-ai/dsh-tool-pwsh' @@ -81,10 +80,9 @@ async function setup() { await ctx.plugin(AgentRegistry) await ctx.plugin(LocalJobRegistry) await ctx.plugin(ToolTasks) - await ctx.plugin(LocalActivityRegistry) await ctx.plugin(BashEnvPlugin) await ctx.plugin(FakePwsh) - await ctx.plugin(ToolPwsh, { activityPollMs: 5 }) + await ctx.plugin(ToolPwsh, { recordPollMs: 5 }) return { ctx, pwsh: ctx.shell as FakePwsh } } @@ -108,8 +106,8 @@ async function until(read: () => T | undefined, timeoutMs = 5_000): Promise { - it('mirrors observed streams with channels and settles with the mapped outcome', async () => { +describe('background pwsh record', () => { + it('streams observed channels into the job record and settles with the mapped outcome', async () => { const { ctx, pwsh } = await setup() const stdout = { text: '' } const stderr = { text: '' } @@ -118,29 +116,32 @@ describe('background pwsh observation', () => { await call(ctx, { command: 'Get-Progress', description: 'test command', run_in_background: true }) const job = ctx.jobs.list()[0] - const row = await until(() => ctx.activities.list().find(item => item.correlation?.jobId === job!.id)) - expect(row.kind).toBe('pwsh') + expect(job).toBeDefined() + expect(job!.kind).toBe('pwsh') + expect(job!.outputTotal).toBe(0) stdout.text = 'progress-line\n' stderr.text = 'warn-line\n' await until(() => { - const chunks = ctx.activities.read(row.id, 0).chunks + const chunks = ctx.jobs.readRecord(job!.id, 0).chunks return chunks.some(chunk => chunk.text.includes('progress-line')) && chunks.some(chunk => chunk.text.includes('warn-line')) ? true : undefined }) - const chunks = ctx.activities.read(row.id, 0).chunks + const chunks = ctx.jobs.readRecord(job!.id, 0).chunks expect(chunks.find(chunk => chunk.text.includes('progress-line'))?.channel).toBe('stdout') expect(chunks.find(chunk => chunk.text.includes('warn-line'))?.channel).toBe('stderr') scripted.finish() - await until(() => ctx.activities.get(row.id).status === 'completed' ? true : undefined) - expect(ctx.activities.get(row.id).detail).toBe('exit code: 0') + await until(() => ctx.jobs.get(job!.id).status === 'completed' ? true : undefined) + expect(ctx.jobs.get(job!.id).detail).toBe('exit code: 0') }) - it('a pump failure waits for process settlement before mapping the outcome', async () => { + it('a pump failure warns and never fakes a terminal state onto the running job', async () => { const { ctx, pwsh } = await setup() + const warn = vi.fn() + ctx.logger.warn = warn as never let resolveDone: () => void = () => {} const done = new Promise((resolve) => { resolveDone = resolve }) const proc: ShellProcess = { @@ -157,70 +158,36 @@ describe('background pwsh observation', () => { } pwsh.backgroundHandler = () => proc await call(ctx, { command: 'Get-Broken', description: 'test command', run_in_background: true }) - const row = await until(() => ctx.activities.list()[0]) - // The pump rejected on its first poll; the still-running process must not - // be mapped to a terminal state until it actually settles. + const job = ctx.jobs.list()[0] + await until(() => warn.mock.calls.some(args => String(args[0]).includes('record observation pump')) ? true : undefined) + // The pump already failed; the job must wait for real settlement rather + // than freezing a fake terminal state onto the running process. await new Promise(resolve => setTimeout(resolve, 50)) - expect(ctx.activities.list()[0]?.status).toBe('running') + expect(ctx.jobs.get(job!.id).status).toBe('running') proc.status = 'completed' proc.exitCode = 0 resolveDone() - await until(() => ctx.activities.list()[0]?.status !== 'running' ? true : undefined) - expect(ctx.activities.list()[0]).toMatchObject({ status: 'completed', detail: 'exit code: 0' }) - expect(String(row.id)).toContain('pwsh') + await until(() => ctx.jobs.get(job!.id).status !== 'running' ? true : undefined) + expect(ctx.jobs.get(job!.id)).toMatchObject({ status: 'completed', detail: 'exit code: 0' }) }) - it('a throwing end() is swallowed by the settlement-mapping catch', async () => { - const ctx = new Context() - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRuntime) - await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalJobRegistry) - await ctx.plugin(ToolTasks) - await ctx.plugin({ - name: 'end-throwing-activities-probe', - apply(child: Context) { - child.provide('activities', { - open: () => ({ - id: 'pwsh-1', - append() {}, - updateDetail() {}, - end() { throw new Error('end boom') }, - }), - }) - }, - }) - await ctx.plugin(BashEnvPlugin) - await ctx.plugin(FakePwsh) - await ctx.plugin(ToolPwsh, { activityPollMs: 5 }) - const pwsh = ctx.shell as FakePwsh - const warn = vi.fn() - ctx.logger.warn = warn as never - const handle = observableProcess({ stdout: { text: '' }, stderr: { text: '' } }) - pwsh.backgroundHandler = () => handle.proc - await call(ctx, { command: 'Get-Doom', description: 'test command', run_in_background: true }) - handle.finish() - await until(() => warn.mock.calls.some(args => String(args[0]).includes('activity settlement mapping')) ? true : undefined) - }) - - it('a backend without observed readers still yields a status-only process', async () => { + it('a backend without observed readers still yields a status-only record', async () => { const { ctx, pwsh } = await setup() const scripted = observableProcess() pwsh.backgroundHandler = () => scripted.proc await call(ctx, { command: 'Start-Job', description: 'test command', run_in_background: true }) const job = ctx.jobs.list()[0] - const row = await until(() => ctx.activities.list().find(item => item.correlation?.jobId === job!.id)) - expect(ctx.activities.read(row.id, 0).chunks).toEqual([]) + expect(ctx.jobs.readRecord(job!.id, 0).chunks).toEqual([]) scripted.finish() - await until(() => ctx.activities.get(row.id).status === 'completed' ? true : undefined) - expect(ctx.activities.get(row.id).outputTotal).toBe(0) + await until(() => ctx.jobs.get(job!.id).status === 'completed' ? true : undefined) + expect(ctx.jobs.get(job!.id).outputTotal).toBe(0) }) }) -describe('owned and degraded observation (pwsh)', () => { - it('mirrors an owned background run under the owning session', async () => { +describe('owned background record (pwsh)', () => { + it('keeps an owned background run record under the owning session', async () => { const { ctx, pwsh } = await setup() const owner = { id: SessionId('pwsh-observe-owner'), @@ -240,40 +207,10 @@ describe('owned and degraded observation (pwsh)', () => { }) const job = ctx.jobs.list(owner)[0] expect(job).toBeDefined() - const row = await until(() => ctx.activities.list(owner).find(item => item.correlation?.jobId === job!.id)) - expect(row.ownerSession).toBe(owner.id) + expect(job!.ownerSession).toBe(owner.id) + expect(() => ctx.jobs.readRecord(job!.id, 0)).toThrow(/belongs to another session/) + expect(ctx.jobs.readRecord(job!.id, 0, owner).chunks).toEqual([]) scripted.finish() await until(() => ctx.jobs.get(job!.id, owner).status === 'completed' ? true : undefined) }) - - it('swallows a throwing observation registry and keeps the job alive', async () => { - // The FakePwsh composition with a synchronously throwing open(): the - // failure lands in the outer observation catch and the job runs on. - const ctx = new Context() - await ctx.plugin(SystemPrompt) - await ctx.plugin(ToolRuntime) - await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalJobRegistry) - await ctx.plugin(ToolTasks) - await ctx.plugin({ - name: 'broken-activities-probe', - apply(child: Context) { - child.provide('activities', { open() { throw new Error('observation boom') } }) - }, - }) - await ctx.plugin(BashEnvPlugin) - await ctx.plugin(FakePwsh) - const warn = vi.fn() - ctx.logger.warn = warn as never - await ctx.plugin(ToolPwsh, { activityPollMs: 5 }) - const pwsh = ctx.shell as FakePwsh - const scripted = observableProcess() - pwsh.backgroundHandler = () => scripted.proc - await call(ctx, { command: 'Get-Slow', description: 'test command', run_in_background: true }) - expect(warn).toHaveBeenCalledWith(expect.stringContaining('activity observation unavailable')) - const job = ctx.jobs.list()[0] - expect(job?.status).toBe('running') - scripted.finish() - await until(() => ctx.jobs.get(job!.id).status === 'completed' ? true : undefined) - }) }) diff --git a/packages/shell/tool-pwsh/tsconfig.json b/packages/shell/tool-pwsh/tsconfig.json index d38c8f031d..59a4d9478c 100644 --- a/packages/shell/tool-pwsh/tsconfig.json +++ b/packages/shell/tool-pwsh/tsconfig.json @@ -52,9 +52,6 @@ }, { "path": "../../runtime-diagnostics/invariants" - }, - { - "path": "../../activity/activity" } ] } diff --git a/packages/workflow/tool-workflow/README.md b/packages/workflow/tool-workflow/README.md index a7096838da..2291b274a5 100644 --- a/packages/workflow/tool-workflow/README.md +++ b/packages/workflow/tool-workflow/README.md @@ -68,7 +68,7 @@ The consumer owns the model-facing schema, the `tool:` system-prompt g For a root transport execution (`exec.parent` absent), the tool projects the run into the calling Agent's Session with four log-only events: run-start after `start()` returns, member starts and endings filtered by `run.id`, then run-end only after the result is available and disposal reaches quiescence. Nested transport calls execute normally but write no record. The first failed Session append disables later recording for that run with one warning, leaving either no record or a legal continuous prefix without changing the tool result or cleanup. The package invariant rejects duplicate starts, unpaired members, terminal events with open members, and updates after run-end on both cold load and live append, while accepting missing terminal suffixes. -Beside the durable record, each recorded top-level run is mirrored best-effort into the optional `ctx.activities` registry as a `workflow` activity: the otherwise-unconsumed `workflow/phase` and `workflow/log` events plus member lifecycle lines stream into it, so the Web client shows the run's live narration the session log deliberately does not carry per line. Without the registry, or on any mirror failure, the run is unaffected. +The engine's `workflow/phase` and `workflow/log` events have no per-line durable or observer surface from this tool: the session log deliberately records run and member lifecycle only, and the Web transcript derives from those records. ### Render intent @@ -80,7 +80,6 @@ Decided up front per the [render-intent Agent Note](../../../.agents/notes/imple |---|---| | [`src/index.ts`](src/index.ts) | Plugin entry: tool registration, run lifecycle, recorder wiring | | [`src/types.ts`](src/types.ts) | The four log-only record event payloads and their `SessionEventMap` declaration | -| [`src/activity.ts`](src/activity.ts) | Best-effort activity mirror for top-level runs | | [`src/invariant.ts`](src/invariant.ts) | Invariant companion: durable workflow-record protocol validation | diff --git a/packages/workflow/tool-workflow/package.json b/packages/workflow/tool-workflow/package.json index a9707f1456..4f148077b5 100644 --- a/packages/workflow/tool-workflow/package.json +++ b/packages/workflow/tool-workflow/package.json @@ -38,7 +38,6 @@ "license": "MIT", "peerDependencies": { "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-activity": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", @@ -52,8 +51,6 @@ }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-activity": "workspace:^", - "@deepseek-ai/dsh-activity-local": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", diff --git a/packages/workflow/tool-workflow/src/activity.ts b/packages/workflow/tool-workflow/src/activity.ts deleted file mode 100644 index 36b251b894..0000000000 --- a/packages/workflow/tool-workflow/src/activity.ts +++ /dev/null @@ -1,119 +0,0 @@ -/** - * Best-effort activity mirror for top-level workflow runs: opens one - * `workflow` activity per run and streams the engine's `workflow/phase`, - * `workflow/log`, and member lifecycle events into it as text lines, so the - * Web client shows live progress the session log deliberately does not carry - * per line. Without a `ctx.activities` registry every operation is a no-op, - * and ANY mirror failure is logged and swallowed — the run is unaffected. - * - * @module @deepseek-ai/dsh-tool-workflow/activity - */ - -import type { Context } from '@deepseek-ai/cordis' -import type { Agent } from '@deepseek-ai/dsh-agent' -import type { ActivityHandle } from '@deepseek-ai/dsh-activity' -import type { WorkflowRun, WorkflowRunId, WorkflowStopReason } from '@deepseek-ai/dsh-workflow' - -declare module '@deepseek-ai/dsh-activity' { - interface ActivityKindMap { - workflow: 'workflow' - } -} - -/** Activity taps for the three points the tool already tracks a run at. */ -export interface WorkflowActivityMirror { - /** - * Open the run's activity. Call once per recorded top-level run. - * @param run - the started run (id and meta name). - * @param owner - the calling agent, when the call has one. - */ - start(run: WorkflowRun, owner: Agent | undefined): void - /** - * End the run's activity with the mapped stop reason. - * @param runId - the settled run. - * @param stopReason - how the run stopped. - */ - finish(runId: WorkflowRunId, stopReason: WorkflowStopReason): void - /** - * Drop tracking for a run that ends without a settled reason. First-wins - * with {@link finish}: after a normal finish this is inert. - * @param runId - the abandoned run. - */ - abandon(runId: WorkflowRunId): void -} - -/** Map a run's stop reason onto the activity outcome vocabulary. */ -function outcomeOf(stopReason: WorkflowStopReason): { status: 'completed' | 'failed' | 'killed'; detail: string } { - switch (stopReason) { - case 'completed': return { status: 'completed', detail: 'completed' } - case 'cancelled': return { status: 'killed', detail: 'cancelled' } - case 'error': return { status: 'failed', detail: 'error' } - } -} - -/** - * Create the run-to-activity mirror and subscribe the engine's live progress - * events for the runs it tracks. - * @param ctx - plugin context used for the optional registry and warning logs. - * @returns the mirror taps the tool wires beside its durable recorder. - */ -export function createWorkflowActivityMirror(ctx: Context): WorkflowActivityMirror { - const active = new Map() - const contained = (operation: string, act: () => void): void => { - try { - act() - } catch (error: unknown) { - ctx.logger.warn(`workflow activity mirror ${operation} failed: ${String(error)}`) - } - } - - ctx.on('workflow/phase', (info, title) => { - const handle = active.get(info.id) - if (handle === undefined) return - contained('phase', () => { - handle.updateDetail(title) - handle.append(`▸ ${title}\n`) - }) - }) - ctx.on('workflow/log', (info, message) => { - const handle = active.get(info.id) - if (handle === undefined) return - contained('log', () => { handle.append(`${message}\n`) }) - }) - ctx.on('workflow/agent-start', (info, agent) => { - const handle = active.get(info.id) - if (handle === undefined) return - contained('agent-start', () => { handle.append(`agent #${agent.seq} ${agent.label} started\n`) }) - }) - ctx.on('workflow/agent-end', (info, agent) => { - const handle = active.get(info.id) - if (handle === undefined) return - contained('agent-end', () => { handle.append(`agent #${agent.seq} ${agent.outcome}\n`) }) - }) - - return { - start(run, owner) { - contained('open', () => { - const activities = ctx.get('activities') - if (activities === undefined) return - active.set(run.id, activities.open({ - kind: 'workflow', - label: run.meta.name, - ...owner !== undefined ? { owner } : {}, - })) - }) - }, - finish(runId, stopReason) { - const handle = active.get(runId) - active.delete(runId) - if (handle === undefined) return - contained('finish', () => { handle.end(outcomeOf(stopReason)) }) - }, - abandon(runId) { - const handle = active.get(runId) - active.delete(runId) - if (handle === undefined) return - contained('abandon', () => { handle.end({ status: 'killed', detail: 'run abandoned' }) }) - }, - } -} diff --git a/packages/workflow/tool-workflow/src/index.ts b/packages/workflow/tool-workflow/src/index.ts index 022d8e4266..77e21672b4 100644 --- a/packages/workflow/tool-workflow/src/index.ts +++ b/packages/workflow/tool-workflow/src/index.ts @@ -24,7 +24,6 @@ import type { ToolWorkflowAgentEndData, ToolWorkflowAgentStartData, ToolWorkflowRunEndData, ToolWorkflowRunStartData, } from './types.ts' -import { createWorkflowActivityMirror } from './activity.ts' export const name = 'tool-workflow' export const inject = ['tools', 'workflowEngine', 'systemPrompt'] @@ -207,7 +206,6 @@ export function apply(ctx: Context, config: Config): void { // fields; the assertion records that resolution, not a hidden fallback. const { toolName, maxResultChars } = config as ResolvedConfig const recorder = createWorkflowRecorder(ctx) - const mirror = createWorkflowActivityMirror(ctx) // Usage policy ships with the tool (the master convention: tool guidance // lives in tool plugins as prompt sections, not in the deployment persona). ctx.systemPrompt.section({ @@ -294,7 +292,6 @@ export function apply(ctx: Context, config: Config): void { // worker messages, after start() returns and this run record is active. if (recordsRun) { recorder.start(parent.session, run) - mirror.start(run, parent) } // Bridge the tool's abort signal to the run: if the parent step is aborted while the @@ -327,12 +324,10 @@ export function apply(ctx: Context, config: Config): void { /* v8 ignore next -- WorkflowRun.result never rejects by contract, so result is assigned before finally. */ if (result === undefined) throw new Error('workflow run settled without a result') recorder.finish(run.id, result.stopReason) - mirror.finish(run.id, result.stopReason) } } finally { if (recordsRun) { recorder.abandon(run.id) - mirror.abandon(run.id) } } } diff --git a/packages/workflow/tool-workflow/tests/activity-mirror.spec.ts b/packages/workflow/tool-workflow/tests/activity-mirror.spec.ts deleted file mode 100644 index 8f82cb2841..0000000000 --- a/packages/workflow/tool-workflow/tests/activity-mirror.spec.ts +++ /dev/null @@ -1,129 +0,0 @@ -import { describe, expect, it, vi } from 'vitest' -import { Context } from '@deepseek-ai/cordis' -import AgentRegistry from '@deepseek-ai/dsh-agent' -import type { Agent } from '@deepseek-ai/dsh-agent' -import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' -import { SessionId } from '@deepseek-ai/dsh-session' -import type { WorkflowRun, WorkflowRunId, WorkflowRunInfo } from '@deepseek-ai/dsh-workflow' -import { createWorkflowActivityMirror } from '../src/activity.ts' - -function runStub(id = 'run-1'): { run: WorkflowRun; info: WorkflowRunInfo } { - const info = { id: id as WorkflowRunId, meta: { name: 'docs-sweep' } } as WorkflowRunInfo - return { - run: { id: id as WorkflowRunId, meta: { name: 'docs-sweep' } } as WorkflowRun, - info, - } -} - -function retainedText(ctx: Context): string { - const row = ctx.activities.list()[0] - if (row === undefined) throw new Error('no mirrored activity') - return ctx.activities.read(row.id, 0).chunks.map(chunk => chunk.text).join('') -} - -describe('workflow activity mirror', () => { - it('opens one workflow activity per run and streams phase, log, and member lines', async () => { - const ctx = new Context() - await ctx.plugin(LocalActivityRegistry) - const mirror = createWorkflowActivityMirror(ctx) - const { run, info } = runStub() - mirror.start(run, undefined) - - const row = ctx.activities.list()[0] - expect(row?.kind).toBe('workflow') - expect(row?.label).toBe('docs-sweep') - - ctx.emit('workflow/phase', info, 'Scan') - ctx.emit('workflow/log', info, '3 files queued') - ctx.emit('workflow/agent-start', info, { seq: 1, label: 'reader', childId: 'c1' } as never) - ctx.emit('workflow/agent-end', info, { seq: 1, label: 'reader', childId: 'c1', outcome: 'completed' } as never) - expect(ctx.activities.get(row!.id).detail).toBe('Scan') - expect(retainedText(ctx)).toBe('▸ Scan\n3 files queued\nagent #1 reader started\nagent #1 completed\n') - - mirror.finish(run.id, 'completed') - const settled = ctx.activities.get(row!.id) - expect(settled.status).toBe('completed') - // The always-run abandon after a normal finish is inert. - mirror.abandon(run.id) - expect(ctx.activities.get(row!.id).status).toBe('completed') - }) - - - it('opens an owned run under the owning agent session', async () => { - const ctx = new Context() - await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalActivityRegistry) - const owner = { - id: SessionId('workflow-owner'), - session: { id: SessionId('workflow-owner') }, - status: 'idle', - ctx, - } as unknown as Agent - ctx.agents.register(owner) - const mirror = createWorkflowActivityMirror(ctx) - const { run } = runStub('run-owned') - mirror.start(run, owner) - // The owned row is fenced to its owner's view. - const row = ctx.activities.list(owner)[0] - expect(row?.ownerSession).toBe(owner.id) - mirror.finish(run.id, 'completed') - }) - it('maps cancelled and error stops, and ends an abandoned run as killed', async () => { - const ctx = new Context() - await ctx.plugin(LocalActivityRegistry) - const mirror = createWorkflowActivityMirror(ctx) - - const cancelled = runStub('run-c') - mirror.start(cancelled.run, undefined) - mirror.finish(cancelled.run.id, 'cancelled') - - const failed = runStub('run-e') - mirror.start(failed.run, undefined) - mirror.finish(failed.run.id, 'error') - - const orphaned = runStub('run-o') - mirror.start(orphaned.run, undefined) - mirror.abandon(orphaned.run.id) - - const byLabelOrder = ctx.activities.list() - expect(byLabelOrder.map(row => [row.status, row.detail])).toEqual([ - ['killed', 'cancelled'], - ['failed', 'error'], - ['killed', 'run abandoned'], - ]) - }) - - it('ignores events for untracked runs and stays inert without the registry', async () => { - const bare = new Context() - const inert = createWorkflowActivityMirror(bare) - const { run, info } = runStub() - // No registry: every tap is a no-op rather than a throw. - inert.start(run, undefined) - bare.emit('workflow/log', info, 'dropped') - inert.finish(run.id, 'completed') - inert.abandon(run.id) - - const ctx = new Context() - await ctx.plugin(LocalActivityRegistry) - createWorkflowActivityMirror(ctx) - // Events for a run the mirror never opened change nothing. - ctx.emit('workflow/phase', info, 'ghost') - expect(ctx.activities.list()).toEqual([]) - }) - - it('contains a throwing registry so the run path never breaks', async () => { - const ctx = new Context() - const warn = vi.fn() - ctx.logger.warn = warn as never - await ctx.plugin({ - name: 'broken-activities-probe', - apply(child: Context) { - child.provide('activities', { open() { throw new Error('mirror boom') } }) - }, - }) - const mirror = createWorkflowActivityMirror(ctx) - const { run } = runStub() - expect(() => { mirror.start(run, undefined) }).not.toThrow() - expect(warn).toHaveBeenCalledWith(expect.stringContaining('workflow activity mirror open failed')) - }) -}) diff --git a/packages/workflow/tool-workflow/tsconfig.json b/packages/workflow/tool-workflow/tsconfig.json index a4cde5cbef..bfd38e61d4 100644 --- a/packages/workflow/tool-workflow/tsconfig.json +++ b/packages/workflow/tool-workflow/tsconfig.json @@ -37,9 +37,6 @@ }, { "path": "../../runtime-diagnostics/invariants" - }, - { - "path": "../../activity/activity" } ] } From 6e8a7a50ea85d3f9835a57f064fb9cc4ed6156d0 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 1 Sep 2026 18:03:09 +0800 Subject: [PATCH 015/100] feat(api): serve job-record observation from the session namespace MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SessionJob rows carry outputTotal exactly for record-declaring jobs, and a new session.observeJob stream serves one job's retained record from an absolute offset (anchor, coalesced output frames, terminal status) with the fenced read resolved from the request's session — the same authorization shape as the jobs roster. The client half gains ctx.jobOutput: the reference-counted per-job observation service and its accumulated view model, ported from the activity controller this replaces. --- .../session-controller/src/client/index.ts | 4 + .../src/client/job-output.ts | 348 +++++++++++++++ .../api/session-controller/src/control.ts | 1 + packages/api/session-controller/src/index.ts | 44 ++ .../api/session-controller/src/observe-job.ts | 189 ++++++++ packages/api/session-controller/src/types.ts | 63 +++ .../tests/control-jobs.host.spec.ts | 19 + .../tests/job-output.client.spec.ts | 413 ++++++++++++++++++ .../tests/observe-job.host.spec.ts | 298 +++++++++++++ .../session-controller/tests/test-remote.ts | 4 + .../api/session-controller/tsconfig.host.json | 1 + 11 files changed, 1384 insertions(+) create mode 100644 packages/api/session-controller/src/client/job-output.ts create mode 100644 packages/api/session-controller/src/observe-job.ts create mode 100644 packages/api/session-controller/tests/job-output.client.spec.ts create mode 100644 packages/api/session-controller/tests/observe-job.host.spec.ts diff --git a/packages/api/session-controller/src/client/index.ts b/packages/api/session-controller/src/client/index.ts index 4bad2bb8c2..78a54b37ef 100644 --- a/packages/api/session-controller/src/client/index.ts +++ b/packages/api/session-controller/src/client/index.ts @@ -3,6 +3,7 @@ import type { Context } from '@deepseek-ai/cordis' import type {} from '@deepseek-ai/dsh-agent/types' import { createSessionControlStream } from './transport.ts' +import { ClientJobOutput, ClientJobOutputModel } from './job-output.ts' import { ClientSessions } from './sessions/service.ts' import type { SessionRemotes } from './sessions/remotes.ts' import type {} from '../remote-events.ts' @@ -23,6 +24,8 @@ export type { } from './transport.ts' export { createScope, scopeOf } from './scope.ts' export type { AgentContext, AgentScopeHandle } from './scope.ts' +export { ClientJobOutput, ClientJobOutputModel } from './job-output.ts' +export type { IJobOutput, JobOutputSnapshot, JobOutputSource, ObservedJob } from './job-output.ts' export { SessionCreateError, SessionForkError } from './sessions/service.ts' export type { SessionBinding, SessionListState, SessionSummary } from './sessions/service.ts' export type { @@ -89,6 +92,7 @@ export const inject = [ export function apply(ctx: Context): void { const remotes = ctx.remote as unknown as SessionRemotes const sessions = new ClientSessions(ctx, remotes) + new ClientJobOutput(ctx, remotes, new ClientJobOutputModel()) ctx.remote.$on('api-session/added', (summary) => { sessions.handleSessionAdded(summary) }) ctx.remote.$on('api-session/removed', (sessionId) => { sessions.handleSessionRemoved(sessionId) }) ctx.remote.$on('api-session/status', (sessionId, running) => { diff --git a/packages/api/session-controller/src/client/job-output.ts b/packages/api/session-controller/src/client/job-output.ts new file mode 100644 index 0000000000..933c104497 --- /dev/null +++ b/packages/api/session-controller/src/client/job-output.ts @@ -0,0 +1,348 @@ +/** + * React-free client job-record observation: per-job accumulated output views + * over the `session.observeJob` stream, reference-counted per job so + * overlapping panels share one stream. The roster itself rides the session + * control stream (`jobsBySession`); this module carries only the output. + * @module @deepseek-ai/dsh-api-session-controller/client/job-output + */ + +import { Service, type Context } from '@deepseek-ai/cordis' +import { RemoteStreamCarrierError, type ClientRemote } from '@deepseek-ai/dsh-api-gateway/client' +import { notifySubscribers } from '@deepseek-ai/dsh-client-store' +import type { JobId } from '@deepseek-ai/dsh-jobs/brand' +import type { SessionId } from '@deepseek-ai/dsh-session/types' +import type { SessionJob, SessionObserveJobFrame } from '../types.ts' +import type { SessionRemote } from './transport.ts' + +/** Bounded per-job render tail, in UTF-16 code units. */ +const RENDER_TAIL_LIMIT = 128 * 1024 + +/** One observed job's live view state. */ +export interface ObservedJob { + readonly jobId: JobId + /** Accumulated output tail, bounded to the render limit. */ + readonly text: string + /** True when bytes before {@link text} were dropped (eviction, resume gap, or the render bound). */ + readonly gapBefore: boolean + /** Latest status delivered on the observation stream. */ + readonly status: SessionJob['status'] + readonly detail?: string + /** True while the observation stream is open and the job has not settled. */ + readonly streaming: boolean + /** Terminal observation failure, when the stream ended abnormally. */ + readonly error?: string +} + +/** Immutable client job-output state. */ +export interface JobOutputSnapshot { + /** Live observation state keyed by job id. */ + readonly observed: Readonly> +} + +/** Mutable observation bookkeeping behind one {@link ObservedJob} view. */ +interface ObservedState { + view: ObservedJob + /** Resume offset for the next generation's `from`. */ + cursor: number | undefined +} + +/** + * Owns per-job observation state. Pure data plus subscriptions — transport + * wiring stays in the client service, UI stays in slot components. + */ +export class ClientJobOutputModel { + private readonly observedStates = new Map() + private readonly listeners = new Set<() => void>() + private snapshotCache: JobOutputSnapshot = { observed: {} } + private snapshotDirty = false + + /** + * Read the identity-stable current snapshot. + * @returns the cached snapshot, rebuilt only after a change. + */ + getSnapshot(): JobOutputSnapshot { + if (this.snapshotDirty) { + const observed: Record = {} + for (const [id, state] of this.observedStates) observed[id] = state.view + this.snapshotCache = { observed } + this.snapshotDirty = false + } + return this.snapshotCache + } + + /** + * Subscribe to snapshot changes. + * @param listener - invalidation callback. + * @returns unsubscribe function. + */ + subscribe(listener: () => void): () => void { + this.listeners.add(listener) + return () => { this.listeners.delete(listener) } + } + + /** + * The resume offset for one job's next observation generation. + * @param id - observed job. + * @returns the last accepted `next`, or undefined for a fresh observation. + */ + cursorOf(id: JobId): number | undefined { + return this.observedStates.get(String(id))?.cursor + } + + /** + * Install or reset observation state when a generation's anchor arrives. + * @param id - observed job. + * @param frame - the generation's `opened` anchor. + */ + observeOpened(id: JobId, frame: Extract): void { + const existing = this.observedStates.get(String(id)) + // A fresh view anchored past offset zero starts after an evicted head + // (fresh observations anchor at the registry's earliest retained byte), so + // it owes the same gap mark a live observer earned from lossy reads. A + // resume that already accumulated text keeps its recorded gap state. + const freshPastHead = (existing === undefined || existing.view.text === '') && frame.from > 0 + const view: ObservedJob = { + jobId: id, + text: existing?.view.text ?? '', + gapBefore: (existing?.view.gapBefore ?? false) || frame.from < frame.earliest || freshPastHead, + status: frame.status, + ...frame.detail !== undefined ? { detail: frame.detail } : {}, + streaming: true, + } + this.observedStates.set(String(id), { view, cursor: frame.from }) + this.changed() + } + + /** + * Append one output frame's chunks to the bounded render tail. + * @param id - observed job. + * @param frame - a coalesced `output` frame. + */ + observeOutput(id: JobId, frame: Extract): void { + const state = this.observedStates.get(String(id)) + /* v8 ignore next -- frames arrive only between opened and stop for a tracked id. */ + if (state === undefined) return + let text = state.view.text + frame.chunks.map(chunk => chunk.text).join('') + let gapBefore = state.view.gapBefore || frame.lossy === true + || frame.chunks.some(chunk => chunk.gapBefore === true) + if (text.length > RENDER_TAIL_LIMIT) { + let cut = text.length - RENDER_TAIL_LIMIT + // Never split a surrogate pair at the render bound. + const unit = text.charCodeAt(cut) + if (unit >= 0xDC00 && unit <= 0xDFFF) cut += 1 + text = text.slice(cut) + gapBefore = true + } + state.view = { ...state.view, text, gapBefore } + state.cursor = frame.next + this.changed() + } + + /** + * Record the terminal status delivered at the end of the observation stream. + * @param id - observed job. + * @param frame - the terminal `status` frame. + */ + observeStatus(id: JobId, frame: Extract): void { + const state = this.observedStates.get(String(id)) + /* v8 ignore next -- frames arrive only between opened and stop for a tracked id. */ + if (state === undefined) return + state.view = { + ...state.view, + status: frame.status, + ...frame.detail !== undefined ? { detail: frame.detail } : {}, + streaming: false, + } + this.changed() + } + + /** + * Record a terminal observation failure. + * @param id - observed job. + * @param error - the stream's terminal failure. + */ + observeFailed(id: JobId, error: unknown): void { + const state = this.observedStates.get(String(id)) + if (state === undefined) return + state.view = { ...state.view, streaming: false, error: String(error) } + this.changed() + } + + /** + * Drop observation state after the last observer stops. + * @param id - the no-longer-observed job. + */ + observeStopped(id: JobId): void { + if (!this.observedStates.delete(String(id))) return + this.changed() + } + + private changed(): void { + this.snapshotDirty = true + notifySubscribers(this.listeners, 'job output') + } +} + +/** Bare observable source for the client job-output snapshot. */ +export interface JobOutputSource { + /** Read the identity-stable current snapshot. */ + getSnapshot(): JobOutputSnapshot + /** + * Subscribe to snapshot changes. + * @param listener - invalidation callback. + * @returns unsubscribe function. + */ + subscribe(listener: () => void): () => void +} + +/** The job-output client service face. */ +export interface IJobOutput { + /** Per-job observation state. */ + readonly state: JobOutputSource + /** + * Start observing one job's live record; reference-counted, so two viewers + * of the same job share one stream. + * @param sessionId - owning session used for the fenced read; undefined for an unowned job. + * @param id - job to observe. + * @returns stop function releasing this observer's reference. + */ + observe(sessionId: SessionId | undefined, id: JobId): () => void +} + +/** One reference-counted observation stream. */ +interface ObservationEntry { + refs: number + stopped: boolean + dispose: () => Promise +} + +/** Remote face the observation runner drives. */ +type JobObserveRemote = Pick & { readonly session: Pick } + +declare module '@deepseek-ai/cordis' { + interface Context { + /** React-free client job-record observation control. */ + jobOutput: IJobOutput + } +} + +/** Owns the bare job-output snapshot and per-job observation streams. */ +export class ClientJobOutput extends Service implements IJobOutput { + readonly state: JobOutputSource + private readonly entries = new Map() + + /** + * @param ctx - client root Context. + * @param remote - generated session namespace plus the Gateway stream factory. + * @param model - shared client job-output model. + */ + constructor( + ctx: Context, + private readonly remote: JobObserveRemote, + private readonly model: ClientJobOutputModel, + ) { + super(ctx, 'jobOutput') + this.state = model + ctx.effect(() => () => { + const open = [...this.entries.values()] + this.entries.clear() + for (const entry of open) { + entry.stopped = true + void entry.dispose() + } + }, 'session-controller.client.observations') + } + + observe(sessionId: SessionId | undefined, id: JobId): () => void { + const key = String(id) + const existing = this.entries.get(key) + if (existing !== undefined && !existing.stopped) { + existing.refs += 1 + return this.releaser(key, existing) + } + const entry = this.startObservation(sessionId, id) + this.entries.set(key, entry) + return this.releaser(key, entry) + } + + /** + * Release closures bind the exact entry they were minted for, never the + * map's current occupant: a later `observe()` on the same id may have + * replaced a stopped entry, and decrementing or disposing through the key + * alone would tear down that newer stream's references. + */ + private releaser(key: string, entry: ObservationEntry): () => void { + let released = false + return () => { + if (released) return + released = true + entry.refs -= 1 + if (entry.refs > 0) return + if (this.entries.get(key) === entry) this.entries.delete(key) + entry.stopped = true + void entry.dispose().then(() => { + // Clear the view only while no successor observation holds the key: + // a re-expand inside the dispose round-trip already re-anchored the + // model, and a stale clear would blank its panel for good. + if (this.entries.has(key)) return + // The key is the stringified branded id this releaser was minted for. + this.model.observeStopped(key as JobId) + }) + } + } + + private startObservation(sessionId: SessionId | undefined, id: JobId): ObservationEntry { + const name = `job observation ${String(id)}` + const stream = this.remote.$stream({ + name, + open: (signal) => { + const from = this.model.cursorOf(id) + return this.remote.session.observeJob( + { + jobId: id, + ...sessionId !== undefined ? { sessionId } : {}, + ...from !== undefined ? { from } : {}, + }, + signal, + ) + }, + // A premature end after the anchor is retryable (a Host reload closes the + // generation); resuming from the cursor loses nothing. An end before the + // anchor is terminal. + ended: accepted => accepted + ? new RemoteStreamCarrierError(`${name} ended before settlement`) + : new Error(`${name} ended before its anchor`), + }) + const entry: ObservationEntry = { + refs: 1, + stopped: false, + dispose: () => stream.dispose(), + } + void (async () => { + try { + for await (const item of stream) { + const frame = item.value + if (frame.type === 'opened') { + this.model.observeOpened(id, frame) + item.accept() + continue + } + if (frame.type === 'output') { + this.model.observeOutput(id, frame) + continue + } + // Terminal status: leave the loop before the generation end is + // classified, then close the stream for good. + this.model.observeStatus(id, frame) + break + } + } catch (error) { + if (!entry.stopped) this.model.observeFailed(id, error) + } finally { + entry.stopped = true + void entry.dispose() + } + })() + return entry + } +} diff --git a/packages/api/session-controller/src/control.ts b/packages/api/session-controller/src/control.ts index 1a03011644..aa9f0a77be 100644 --- a/packages/api/session-controller/src/control.ts +++ b/packages/api/session-controller/src/control.ts @@ -212,5 +212,6 @@ function jobView(job: JobSnapshot): SessionJob { ...(job.detail === undefined ? {} : { detail: job.detail }), startedAt: job.startedAt, ...(job.finishedAt === undefined ? {} : { finishedAt: job.finishedAt }), + ...(job.outputTotal === undefined ? {} : { outputTotal: job.outputTotal }), } } diff --git a/packages/api/session-controller/src/index.ts b/packages/api/session-controller/src/index.ts index 572f895754..99dad0a75e 100644 --- a/packages/api/session-controller/src/index.ts +++ b/packages/api/session-controller/src/index.ts @@ -2,6 +2,7 @@ import { Context } from '@deepseek-ai/cordis' import z from '@deepseek-ai/schemastery' +import type {} from '@deepseek-ai/dsh-jobs' import { errorChain } from '@deepseek-ai/dsh-llm' import { canOpenNativePath, openNativePath } from '@deepseek-ai/dsh-native-command' import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session' @@ -15,6 +16,7 @@ import { import { SessionCommandController } from './commands.ts' import { SessionControlController } from './control.ts' import { SessionHistoryController } from './history.ts' +import { observeJobRecord } from './observe-job.ts' import { SessionFileReferences } from './file-references.ts' import { ApiSessionList, DEFAULT_COLD_BLANK_PROBE_MAX_BYTES } from './list.ts' import { buildModelCatalog } from './catalog.ts' @@ -35,6 +37,8 @@ import type { SessionForkValue, SessionListRequest, SessionListValue, + SessionObserveJobFrame, + SessionObserveJobRequest, SessionOpenWorkspacePathRequest, SessionOpenWorkspacePathValue, SessionPage, @@ -63,12 +67,22 @@ declare module '@deepseek-ai/cordis' { } } +/** Default coalescing window between job-observation reads, in milliseconds. */ +const DEFAULT_OBSERVE_FLUSH_MS = 100 + +/** Default soft byte budget per job-observation output frame. */ +const DEFAULT_OBSERVE_MAX_FRAME_BYTES = 64 * 1024 + /** Session Controller deployment policy. */ export interface Config { /** Maximum cold Session artifact size eligible for one full projection observation. */ readonly coldBlankProbeMaxBytes?: number /** Override platform desktop-opener detection. */ readonly nativeOpen?: boolean + /** Coalescing window after new record output before a job-observation read, in milliseconds (default 100). */ + readonly observeFlushMs?: number + /** Soft byte budget per job-observation output frame (default 65536); one larger chunk ships whole. */ + readonly observeMaxFrameBytes?: number } /** Host integrations replaceable by direct unit tests. */ @@ -96,6 +110,8 @@ export class SessionController extends TypertRemoteService { static Config: z = z.object({ coldBlankProbeMaxBytes: z.natural().default(DEFAULT_COLD_BLANK_PROBE_MAX_BYTES), nativeOpen: z.boolean(), + observeFlushMs: z.natural().min(1).default(DEFAULT_OBSERVE_FLUSH_MS), + observeMaxFrameBytes: z.natural().min(1).default(DEFAULT_OBSERVE_MAX_FRAME_BYTES), }) private readonly agents: ApiSessionAgentController @@ -106,6 +122,8 @@ export class SessionController extends TypertRemoteService { private readonly openPath: (path: string, signal: AbortSignal) => Promise private readonly canOpenPath: () => boolean private readonly promotions = new Set>() + private readonly observeFlushMs: number + private readonly observeMaxFrameBytes: number /** * @param ctx - Host context containing the Session capability assembly. @@ -130,6 +148,8 @@ export class SessionController extends TypertRemoteService { this.openPath = internals.openPath ?? openNativePath this.canOpenPath = internals.canOpenPath ?? (() => config.nativeOpen ?? (internals.openPath !== undefined || canOpenNativePath())) + this.observeFlushMs = config.observeFlushMs ?? DEFAULT_OBSERVE_FLUSH_MS + this.observeMaxFrameBytes = config.observeMaxFrameBytes ?? DEFAULT_OBSERVE_MAX_FRAME_BYTES ctx.plugin(SessionFileReferences) ctx.plugin(SessionSkillCatalog) @@ -386,6 +406,30 @@ export class SessionController extends TypertRemoteService { return this.controlState.control(signal) } + /** + * Stream one job's retained record output from an absolute byte offset, + * then its terminal status once settled and drained. Non-consuming: the + * model-facing cursor and notice state never observe these reads. The + * request's session resolves the fenced-read caller; the registry rejects a + * job the session does not own, a job without a record, or an unknown job. + * @param request - target job, owning session, and optional resume offset. + * @param signal - cancellation owned by the Remote stream carrier. + * @returns anchor, coalesced output frames, and the terminal status. + */ + @Remote({ mode: 'stream' }) + observeJob(request: SessionObserveJobRequest, signal: AbortSignal): AsyncIterable { + const registry = this.ctx.get('jobs') + if (registry === undefined) { + throw new Error('job observation unavailable: no job registry is loaded (load @deepseek-ai/dsh-jobs-local)') + } + const caller = request.sessionId === undefined ? undefined : this.ctx.agents.get(request.sessionId) + return observeJobRecord(registry, request, { + flushMs: this.observeFlushMs, + maxFrameBytes: this.observeMaxFrameBytes, + caller, + }, signal) + } + } export { buildModelCatalog } diff --git a/packages/api/session-controller/src/observe-job.ts b/packages/api/session-controller/src/observe-job.ts new file mode 100644 index 0000000000..516f48779f --- /dev/null +++ b/packages/api/session-controller/src/observe-job.ts @@ -0,0 +1,189 @@ +/** Per-job record observation generations: anchor, coalesced output, terminal status. */ + +import type { Agent } from '@deepseek-ai/dsh-agent' +import { JobId } from '@deepseek-ai/dsh-jobs' +import type { JobRegistry, JobSnapshot } from '@deepseek-ai/dsh-jobs' +import type { SessionJobWireChunk, SessionObserveJobFrame, SessionObserveJobRequest } from './types.ts' + +/** Cadence and framing bounds for one observation generation. */ +export interface ObserveJobOptions { + /** Coalescing window after a wake before reading, in milliseconds. */ + readonly flushMs: number + /** + * Soft byte budget per `output` frame. Accumulated chunks flush once the + * budget is met; one chunk larger than the budget ships whole (the + * registry's retention cap is the hard bound on any single chunk). + */ + readonly maxFrameBytes: number + /** The live owning agent for fenced reads, resolved from the request's session. */ + readonly caller: Agent | undefined +} + +function isTerminal(status: JobSnapshot['status']): boolean { + return status !== 'running' && status !== 'stopping' +} + +/** A record job's total offset; the anchor check proved the declaration and it never leaves. */ +function recordTotal(snapshot: JobSnapshot): number { + /* v8 ignore next -- a declared record never loses its offsets. */ + return snapshot.outputTotal ?? 0 +} + +/** Wake-flag waiter: a wake between waits is never lost. */ +class OutputWaiter { + private dirty = false + private resolve: (() => void) | undefined + + wake(): void { + this.dirty = true + this.resolve?.() + } + + /** + * Resolve on the next wake, immediately when one already arrived, or on abort. + * @param signal - generation cancellation. + */ + wait(signal: AbortSignal): Promise { + if (this.dirty || signal.aborted) { + this.dirty = false + return Promise.resolve() + } + return new Promise((resolve) => { + const finish = (): void => { + signal.removeEventListener('abort', finish) + /* v8 ignore next -- one wait owns the sole installed resolver. */ + if (this.resolve === finish) this.resolve = undefined + this.dirty = false + resolve() + } + this.resolve = finish + signal.addEventListener('abort', finish, { once: true }) + }) + } +} + +function sleep(ms: number, signal: AbortSignal): Promise { + if (signal.aborted) return Promise.resolve() + return new Promise((resolve) => { + const timer = setTimeout(done, ms) + function done(): void { + clearTimeout(timer) + signal.removeEventListener('abort', done) + resolve() + } + signal.addEventListener('abort', done, { once: true }) + }) +} + +/** + * Stream one job's retained record output from an absolute offset: one + * `opened` anchor, coalesced `output` frames as the record advances, then one + * terminal `status` after the settled job is drained, after which the + * generation closes normally. Reads are non-consuming — the model-facing + * cursor and notice state never observe them; reconnecting callers resume by + * passing the last frame's `next` as `from`. Throws for a job that declared + * no record. + * @param registry - the live job registry. + * @param request - target job and optional resume offset. + * @param options - cadence, framing bounds, and the fenced-read caller. + * @param signal - generation cancellation owned by the Remote stream carrier. + * @returns the observation frame sequence for one generation. + */ +export async function* observeJobRecord( + registry: JobRegistry, + request: SessionObserveJobRequest, + options: ObserveJobOptions, + signal: AbortSignal, +): AsyncIterable { + if (request.from !== undefined && (!Number.isSafeInteger(request.from) || request.from < 0)) { + throw new Error(`invalid observe offset: expected a non-negative safe integer, got ${JSON.stringify(request.from)}`) + } + signal.throwIfAborted() + const id = JobId(String(request.jobId)) + const waiter = new OutputWaiter() + // Subscribe before the first read so an append between the anchor read and + // the wait cannot be missed. + const unsubscribe = registry.onOutput((changed) => { + if (changed === id) waiter.wake() + }) + try { + const caller = options.caller + let snapshot = registry.get(id, caller) + if (snapshot.outputTotal === undefined || snapshot.outputEarliest === undefined) { + throw new Error(`job ${id} declared no output record`) + } + let cursor = request.from ?? snapshot.outputEarliest + yield { + type: 'opened', + jobId: id, + from: cursor, + earliest: snapshot.outputEarliest, + total: snapshot.outputTotal, + status: snapshot.status, + ...snapshot.detail !== undefined ? { detail: snapshot.detail } : {}, + } + while (!signal.aborted) { + const read = registry.readRecord(id, cursor, caller) + if (read.chunks.length > 0) { + yield* outputFrames(read.chunks, read.next, read.lossy, options.maxFrameBytes) + } + cursor = read.next + snapshot = registry.get(id, caller) + if (isTerminal(snapshot.status) && cursor >= recordTotal(snapshot)) { + yield { + type: 'status', + status: snapshot.status, + ...snapshot.detail !== undefined ? { detail: snapshot.detail } : {}, + // Settlement always stamps finishedAt; the guard only discharges the optional field type. + /* v8 ignore next */ + ...snapshot.finishedAt !== undefined ? { finishedAt: snapshot.finishedAt } : {}, + } + return + } + await waiter.wait(signal) + // Let a burst accumulate so producer chatter becomes bounded frames. + await sleep(options.flushMs, signal) + } + } finally { + unsubscribe() + } +} + +/** Split one read into frames along the soft per-frame byte budget. */ +function* outputFrames( + chunks: readonly SessionJobWireChunk[], + next: number, + lossy: boolean, + maxFrameBytes: number, +): Iterable { + let batch: SessionJobWireChunk[] = [] + let batchBytes = 0 + let flaggedLossy = lossy + for (const chunk of chunks) { + batch.push(chunk) + batchBytes += Buffer.byteLength(chunk.text, 'utf8') + if (batchBytes >= maxFrameBytes) { + const last = batch[batch.length - 1] + /* v8 ignore start -- a non-empty batch always has a last chunk; the arm only discharges noUncheckedIndexedAccess. */ + const end = last === undefined ? next : last.at + Buffer.byteLength(last.text, 'utf8') + /* v8 ignore stop */ + yield { + type: 'output', + chunks: batch, + next: end, + ...flaggedLossy ? { lossy: true as const } : {}, + } + flaggedLossy = false + batch = [] + batchBytes = 0 + } + } + if (batch.length > 0 || flaggedLossy) { + yield { + type: 'output', + chunks: batch, + next, + ...flaggedLossy ? { lossy: true as const } : {}, + } + } +} diff --git a/packages/api/session-controller/src/types.ts b/packages/api/session-controller/src/types.ts index c0b25fcf2c..cf59e29ad4 100644 --- a/packages/api/session-controller/src/types.ts +++ b/packages/api/session-controller/src/types.ts @@ -469,6 +469,12 @@ export interface SessionJob { readonly detail?: string readonly startedAt: number readonly finishedAt?: number + /** + * Total UTF-8 bytes the job's observation record holds so far. Present + * exactly when the job declared a record — the row is observable through + * `session.observeJob`. + */ + readonly outputTotal?: number } /** Complete live control baseline emitted once per control stream generation. */ @@ -493,6 +499,63 @@ export type SessionControlFrame = | { readonly type: 'jobs'; readonly sessionId: SessionId; readonly jobs: readonly SessionJob[] } | ({ readonly type: 'projection' } & SessionProjectionUpdate) +/** Opens one observation stream over a job's retained record output. */ +export interface SessionObserveJobRequest { + /** Owning session used for the fenced read; omitted for an unowned job. */ + readonly sessionId?: SessionId + readonly jobId: JobId + /** + * Absolute byte offset to resume from — a previous frame's `next`. Omitted + * starts at the oldest retained byte. + */ + readonly from?: number +} + +/** One retained record chunk on the wire. `channel` widens to string like `kind`. */ +export interface SessionJobWireChunk { + /** Absolute offset of the chunk's first byte. */ + readonly at: number + readonly text: string + readonly channel?: string + /** Bytes immediately before this chunk were lost at the producer or to retention. */ + readonly gapBefore?: true +} + +/** + * Job observation stream frames: one `opened` anchor, then coalesced `output` + * batches, then — once the job has settled and its retained record is + * drained — one terminal `status`, after which the stream closes normally. + * Status rides the same stream as output so settlement can never race a + * still-open output channel. + */ +export type SessionObserveJobFrame = + | { + readonly type: 'opened' + readonly jobId: JobId + /** Offset the first `output` frame continues from. */ + readonly from: number + /** Oldest retained byte at open time; `from < earliest` means the head is gone. */ + readonly earliest: number + /** Total bytes produced at open time. */ + readonly total: number + readonly status: SessionJob['status'] + readonly detail?: string + } + | { + readonly type: 'output' + readonly chunks: readonly SessionJobWireChunk[] + /** Offset to resume from after this frame. */ + readonly next: number + /** Bytes between the requested offset and `chunks` were already evicted. */ + readonly lossy?: true + } + | { + readonly type: 'status' + readonly status: SessionJob['status'] + readonly detail?: string + readonly finishedAt?: number + } + declare module '@deepseek-ai/cordis' { interface Events { /** diff --git a/packages/api/session-controller/tests/control-jobs.host.spec.ts b/packages/api/session-controller/tests/control-jobs.host.spec.ts index f827573d03..61a9a8156a 100644 --- a/packages/api/session-controller/tests/control-jobs.host.spec.ts +++ b/packages/api/session-controller/tests/control-jobs.host.spec.ts @@ -162,6 +162,25 @@ describe('Session control jobs updates', () => { ]) }) + it('carries outputTotal exactly for record-declaring jobs', async () => { + const { ctx, agent, control } = await harness(true) + const abort = new AbortController() + const collected = collectJobs(control.control(abort.signal), 1, abort) + ctx.jobs.start({ + kind: 'bash', + label: 'observable run', + owner: agent, + record: true, + run: (job) => { + job.append('hi') + return { cancel: () => {}, done: new Promise(() => {}) } + }, + }) + + const [frame] = await collected + expect(frame?.jobs[0]?.outputTotal).toBe(2) + }) + it('fans an unowned change out to every attached session', async () => { const { ctx, control } = await harness(true) const second = ctx.sessions.create() diff --git a/packages/api/session-controller/tests/job-output.client.spec.ts b/packages/api/session-controller/tests/job-output.client.spec.ts new file mode 100644 index 0000000000..a4ca2933dc --- /dev/null +++ b/packages/api/session-controller/tests/job-output.client.spec.ts @@ -0,0 +1,413 @@ +import { describe, expect, it, vi } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import type { JobId } from '@deepseek-ai/dsh-jobs/brand' +import type { SessionId } from '@deepseek-ai/dsh-session/types' +import { ClientJobOutput, ClientJobOutputModel } from '../src/client/job-output.ts' +import type { SessionObserveJobFrame } from '../src/types.ts' + +const ID = 'bash-1' as JobId + +function opened(model: ClientJobOutputModel, over: Partial<{ from: number; earliest: number; total: number }> = {}): void { + model.observeOpened(ID, { + type: 'opened', + jobId: ID, + from: 0, + earliest: 0, + total: 0, + status: 'running', + ...over, + }) +} + +describe('ClientJobOutputModel observation', () => { + it('accumulates output, advances the resume cursor, and settles on status', () => { + const model = new ClientJobOutputModel() + opened(model) + expect(model.cursorOf(ID)).toBe(0) + model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'a' }, { at: 1, text: 'b' }], next: 2 }) + model.observeOutput(ID, { type: 'output', chunks: [{ at: 2, text: 'c' }], next: 3 }) + expect(model.cursorOf(ID)).toBe(3) + const view = model.getSnapshot().observed[String(ID)] + expect(view?.text).toBe('abc') + expect(view?.streaming).toBe(true) + model.observeStatus(ID, { type: 'status', status: 'completed', detail: 'exit code: 0' }) + const settled = model.getSnapshot().observed[String(ID)] + expect(settled?.streaming).toBe(false) + expect(settled?.status).toBe('completed') + expect(settled?.detail).toBe('exit code: 0') + }) + + it('keeps snapshot identity stable between changes and notifies subscribers', () => { + const model = new ClientJobOutputModel() + let notified = 0 + const unsubscribe = model.subscribe(() => { notified += 1 }) + const before = model.getSnapshot() + expect(model.getSnapshot()).toBe(before) + opened(model) + expect(notified).toBe(1) + expect(model.getSnapshot()).not.toBe(before) + unsubscribe() + model.observeStopped(ID) + expect(notified).toBe(1) + }) + + it('marks gaps from lossy frames, gap chunks, and a resume behind the retained head', () => { + const model = new ClientJobOutputModel() + opened(model, { from: 4, earliest: 8, total: 10 }) + expect(model.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) + + const clean = new ClientJobOutputModel() + opened(clean) + clean.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'x', gapBefore: true }], next: 1 }) + expect(clean.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) + + const lossy = new ClientJobOutputModel() + opened(lossy) + lossy.observeOutput(ID, { type: 'output', chunks: [], next: 5, lossy: true }) + expect(lossy.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) + }) + + it('marks a fresh observation anchored past the evicted head', () => { + // Fresh observations anchor at the registry's earliest retained byte, so + // from === earliest > 0 means the head was already discarded. + const fresh = new ClientJobOutputModel() + opened(fresh, { from: 60_240, earliest: 60_240, total: 321_328 }) + expect(fresh.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) + + // A retry that accumulated no text yet earns the mark the same way. + const retried = new ClientJobOutputModel() + opened(retried) + expect(retried.getSnapshot().observed[String(ID)]?.gapBefore).toBe(false) + opened(retried, { from: 6, earliest: 6, total: 6 }) + expect(retried.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) + }) + + it('bounds the render tail without splitting a surrogate pair', () => { + const model = new ClientJobOutputModel() + opened(model) + const emoji = '😀'.repeat((64 * 1024) + 8) + model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: emoji }], next: emoji.length * 2 }) + const view = model.getSnapshot().observed[String(ID)] + expect(view?.gapBefore).toBe(true) + expect(view!.text.length).toBeLessThanOrEqual(128 * 1024) + // The bound landed between pairs: the surviving text still round-trips. + expect(/^(?:😀)+$/u.test(view!.text)).toBe(true) + }) + + it('carries the anchor detail and trims a plain-ASCII tail without a boundary shift', () => { + const model = new ClientJobOutputModel() + model.observeOpened(ID, { + type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running', detail: 'exit soon', + }) + expect(model.getSnapshot().observed[String(ID)]?.detail).toBe('exit soon') + const long = 'x'.repeat((128 * 1024) + 5) + model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: long }], next: long.length }) + const view = model.getSnapshot().observed[String(ID)] + expect(view?.text.length).toBe(128 * 1024) + expect(view?.gapBefore).toBe(true) + }) + + it('advances the cut past a low surrogate landing exactly on the bound', () => { + const model = new ClientJobOutputModel() + opened(model) + // 'z' + one emoji + odd ASCII tail puts a low surrogate exactly at the cut index. + const text = 'z😀' + 'a'.repeat((128 * 1024) - 1) + model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text }], next: text.length }) + const view = model.getSnapshot().observed[String(ID)] + expect(view?.text.length).toBe((128 * 1024) - 1) + expect(view?.text.startsWith('a')).toBe(true) + }) + + it('preserves accumulated text across a reconnect anchor and clears on stop', () => { + const model = new ClientJobOutputModel() + opened(model) + model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'kept' }], next: 4 }) + opened(model, { from: 4, earliest: 0, total: 4 }) + expect(model.getSnapshot().observed[String(ID)]?.text).toBe('kept') + model.observeStopped(ID) + expect(model.getSnapshot().observed[String(ID)]).toBeUndefined() + expect(model.cursorOf(ID)).toBeUndefined() + // A second stop is inert. + model.observeStopped(ID) + }) + + it('records a terminal stream failure on the live view', () => { + const model = new ClientJobOutputModel() + opened(model) + model.observeFailed(ID, new Error('carrier gone')) + const view = model.getSnapshot().observed[String(ID)] + expect(view?.streaming).toBe(false) + expect(view?.error).toContain('carrier gone') + // A failure for an untracked id is inert. + model.observeFailed('bash-9' as JobId, new Error('ignored')) + }) +}) + +/** One scripted logical stream: frames are pushed by the test, never reopened. */ +class FakeStream { + disposed = false + /** Model a carrier whose disposal surfaces as an iterator throw. */ + throwOnDispose = false + /** Hold the dispose promise open until {@link releaseDispose}. */ + deferDispose = false + private disposeRelease: (() => void) | undefined + private disposePending: Promise | undefined + private readonly frames: SessionObserveJobFrame[] = [] + private waiter: (() => void) | undefined + private failure: Error | undefined + readonly accepts: number[] = [] + + push(frame: SessionObserveJobFrame): void { + this.frames.push(frame) + this.waiter?.() + } + + poison(error: Error): void { + this.failure = error + this.waiter?.() + } + + dispose(): Promise { + if (this.throwOnDispose && this.failure === undefined) { + this.failure = new Error('carrier tore down') + } else { + this.disposed = true + } + this.waiter?.() + if (this.deferDispose) { + // Repeat disposals (releaser plus the consumer's finally) share one + // deferred promise, so releaseDispose resumes every waiter. + this.disposePending ??= new Promise((resolve) => { this.disposeRelease = resolve }) + return this.disposePending + } + return Promise.resolve() + } + + releaseDispose(): void { + this.disposeRelease?.() + } + + async *[Symbol.asyncIterator]() { + let generation = 1 + while (!this.disposed) { + if (this.failure !== undefined) throw this.failure + const frame = this.frames.shift() + if (frame === undefined) { + await new Promise((resolve) => { this.waiter = resolve }) + continue + } + yield { + generation, + value: frame, + signal: new AbortController().signal, + accept: () => { this.accepts.push(generation) }, + } + generation = 1 + } + } +} + +function bench() { + const ctx = new Context() + const model = new ClientJobOutputModel() + const streams: { options: { open: (signal: AbortSignal) => unknown }; stream: FakeStream }[] = [] + const observeCalls: unknown[] = [] + const remote = { + $stream: (options: { open: (signal: AbortSignal) => unknown }) => { + const stream = new FakeStream() + streams.push({ options, stream }) + return stream + }, + session: { + observeJob: (request: unknown) => { + observeCalls.push(request) + return { [Symbol.asyncIterator]: async function* () { /* never yields */ } } + }, + }, + } + const output = new ClientJobOutput(ctx, remote as never, model) + return { ctx, model, output, streams, observeCalls } +} + +const tick = () => new Promise(resolve => setTimeout(resolve, 0)) + +describe('ClientJobOutput observation streams', () => { + it('feeds anchor, output, and terminal frames into the model, then closes', async () => { + const { model, output, streams } = bench() + output.observe(undefined, ID) + const { stream } = streams[0]! + stream.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + stream.push({ type: 'output', chunks: [{ at: 0, text: 'hi' }], next: 2 }) + await tick() + expect(model.getSnapshot().observed[String(ID)]?.text).toBe('hi') + expect(stream.accepts).toHaveLength(1) + + stream.push({ type: 'status', status: 'completed' }) + await tick() + expect(model.getSnapshot().observed[String(ID)]?.streaming).toBe(false) + expect(stream.disposed).toBe(true) + }) + + it('shares one stream across observers and stops after the last release', async () => { + const { model, output, streams } = bench() + const first = output.observe(undefined, ID) + const second = output.observe(undefined, ID) + expect(streams).toHaveLength(1) + streams[0]!.stream.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + await tick() + + first() + first() + expect(streams[0]!.stream.disposed).toBe(false) + second() + await tick() + expect(streams[0]!.stream.disposed).toBe(true) + expect(model.getSnapshot().observed[String(ID)]).toBeUndefined() + }) + + it('a late release of a superseded observation neither tears down nor clears its successor', async () => { + const { model, output, streams } = bench() + const firstStop = output.observe(undefined, ID) + const first = streams[0]!.stream + first.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + first.push({ type: 'status', status: 'completed' }) + await tick() + // A successor observation replaces the settled entry while the first + // observer still holds its releaser. + const secondStop = output.observe(undefined, ID) + const second = streams[1]!.stream + second.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + await tick() + + firstStop() + await tick() + expect(second.disposed).toBe(false) + expect(model.getSnapshot().observed[String(ID)]).toBeDefined() + + secondStop() + await tick() + expect(second.disposed).toBe(true) + expect(model.getSnapshot().observed[String(ID)]).toBeUndefined() + }) + + it('a re-observation inside the dispose round-trip keeps its fresh view', async () => { + const { model, output, streams } = bench() + const stop = output.observe(undefined, ID) + const first = streams[0]!.stream + first.deferDispose = true + first.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + await tick() + + stop() + // Re-expand while the previous generation's dispose is still in flight. + output.observe(undefined, ID) + const second = streams[1]!.stream + second.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + await tick() + + first.releaseDispose() + await tick() + // The stale post-dispose clear must not blank the successor's view. + expect(model.getSnapshot().observed[String(ID)]).toBeDefined() + second.push({ type: 'output', chunks: [{ at: 0, text: 'alive' }], next: 5 }) + await tick() + expect(model.getSnapshot().observed[String(ID)]?.text).toBe('alive') + }) + + it('opens a fresh stream for a re-observed job and resumes from the model cursor', async () => { + const { output, streams, observeCalls, model } = bench() + const stop = output.observe('alice' as SessionId, ID) + streams[0]!.stream.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + streams[0]!.stream.push({ type: 'output', chunks: [{ at: 0, text: 'abc' }], next: 3 }) + await tick() + // The generation opener reads the live cursor at open time and carries the + // fenced-read session. + streams[0]!.options.open(new AbortController().signal) + expect(observeCalls.at(-1)).toEqual({ jobId: ID, sessionId: 'alice', from: 3 }) + + stop() + await tick() + output.observe(undefined, ID) + expect(streams).toHaveLength(2) + streams[1]!.options.open(new AbortController().signal) + // Stopped observation dropped the cursor: the fresh stream starts unanchored. + expect(observeCalls.at(-1)).toEqual({ jobId: ID }) + expect(model.cursorOf(ID)).toBeUndefined() + }) + + it('classifies a premature end as retryable only after the anchor', () => { + const { output, streams } = bench() + output.observe(undefined, ID) + const options = streams[0]!.options as unknown as { ended: (accepted: boolean) => Error } + expect(options.ended(true).name).toBe('RemoteStreamCarrierError') + expect(options.ended(false).name).toBe('Error') + }) + + it('records a consumer failure on the live view', async () => { + const { model, output, streams } = bench() + output.observe(undefined, ID) + const { stream } = streams[0]! + stream.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + await tick() + stream.poison(new Error('frame decode broke')) + await tick() + const view = model.getSnapshot().observed[String(ID)] + expect(view?.error).toContain('frame decode broke') + expect(view?.streaming).toBe(false) + }) + + it('treats a release after service disposal as inert and stays silent for post-stop failures', async () => { + const { ctx, model, output, streams } = bench() + const stop = output.observe(undefined, ID) + const { stream } = streams[0]! + stream.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + await tick() + // Poison wakes the consumer, but the synchronous stop lands first, so the + // failure arrives on an already-stopped entry and stays silent. + stream.poison(new Error('after stop')) + stop() + await tick() + expect(model.getSnapshot().observed[String(ID)]).toBeUndefined() + + const second = output.observe(undefined, ID) + await ctx.fiber.dispose() + // The disposal path already removed every entry; a live releaser whose + // entry is gone is inert. + second() + }) + + it('stays silent when the carrier teardown itself throws after a stop', async () => { + const { model, output, streams } = bench() + const stop = output.observe(undefined, ID) + const { stream } = streams[0]! + stream.throwOnDispose = true + stream.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + await tick() + // The releaser marks the entry stopped, then its dispose surfaces as an + // iterator throw — which the consumer swallows for a stopped entry. + stop() + await tick() + expect(model.getSnapshot().observed[String(ID)]?.error).toBeUndefined() + }) + + it('records a terminal stream failure and service disposal closes live streams', async () => { + const { ctx, model, output, streams } = bench() + output.observe(undefined, ID) + const failing = streams[0]!.stream + failing.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + await tick() + const iterator = failing[Symbol.asyncIterator]() + void iterator + // Simulate a terminal consumer failure by disposing the underlying stream: + // the consumer loop ends without a status frame and cleans up. + const spy = vi.spyOn(model, 'observeFailed') + await failing.dispose() + await tick() + + const other = 'bash-2' as JobId + output.observe(undefined, other) + await ctx.fiber.dispose() + expect(streams.every(entry => entry.stream.disposed)).toBe(true) + expect(spy).not.toHaveBeenCalled() + }) +}) diff --git a/packages/api/session-controller/tests/observe-job.host.spec.ts b/packages/api/session-controller/tests/observe-job.host.spec.ts new file mode 100644 index 0000000000..b61079d2b1 --- /dev/null +++ b/packages/api/session-controller/tests/observe-job.host.spec.ts @@ -0,0 +1,298 @@ +import { describe, expect, it } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' +import type { Agent } from '@deepseek-ai/dsh-agent' +import { JobId } from '@deepseek-ai/dsh-jobs' +import type { JobOutcome, RunningJob } from '@deepseek-ai/dsh-jobs' +import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' +import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session' +import { observeJobRecord } from '../src/observe-job.ts' +import type { ObserveJobOptions } from '../src/observe-job.ts' +import type { SessionObserveJobFrame } from '../src/types.ts' +import { createSessionTestController } from './test-remote.ts' + +async function harness() { + const ctx = new Context() + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalJobRegistry, { retainBytes: 64, settledRetainBytes: 64 }) + ctx.jobs.attachController('observe-job-test') + return ctx +} + +function registerAgent(ctx: Context, rawId: string): Agent { + const scopeFiber = ctx.plugin(() => {}) + const id = SessionId(rawId) + const session = Session.create(id) + const agent = { + id, + session, + inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }), + status: 'idle', + ctx: scopeFiber.ctx, + } as unknown as Agent + ctx.agents.register(agent) + return agent +} + +/** Start one record job whose done settles on demand; expose the producer face. */ +function startRecordJob(ctx: Context, options: { label?: string; owner?: Agent; record?: boolean } = {}) { + let settle!: (outcome: JobOutcome) => void + let face!: RunningJob + const id = ctx.jobs.start({ + kind: 'bash', + label: options.label ?? 'echo', + ...options.owner !== undefined ? { owner: options.owner } : {}, + ...options.record === false ? {} : { record: true }, + run: (job) => { + face = job + return { + cancel() {}, + done: new Promise((resolve) => { settle = resolve }), + } + }, + }) + return { + id, + append: (text: string, opts?: Parameters[1]) => { face.append(text, opts) }, + settle: async (outcome: JobOutcome) => { + settle(outcome) + await new Promise(resolve => setTimeout(resolve, 0)) + }, + } +} + +/** Read frames until `count` arrive or the generator finishes, then abort. */ +async function collect( + iterable: AsyncIterable, + count: number, + abort: AbortController, +): Promise { + const frames: Frame[] = [] + const iterator = iterable[Symbol.asyncIterator]() + try { + while (frames.length < count) { + const step = await iterator.next() + if (step.done) return frames + frames.push(step.value) + } + } finally { + abort.abort() + await iterator.next().catch(() => undefined) + } + return frames +} + +const OBSERVE: Omit = { flushMs: 5, maxFrameBytes: 1024 } + +describe('observeJobRecord', () => { + function observed(ctx: Context, request: { jobId: JobId; from?: number }, caller?: Agent) { + const abort = new AbortController() + const frames: SessionObserveJobFrame[] = [] + const stream = observeJobRecord(ctx.jobs, request, { ...OBSERVE, caller }, abort.signal) + const done = (async () => { + for await (const frame of stream) frames.push(frame) + })() + return { abort, frames, done } + } + + it('anchors, streams coalesced output, and closes with the terminal status', async () => { + const ctx = await harness() + const job = startRecordJob(ctx) + job.append('early ') + const { frames, done } = observed(ctx, { jobId: job.id }) + await new Promise(resolve => setTimeout(resolve, 20)) + job.append('live', { channel: 'stderr' }) + await new Promise(resolve => setTimeout(resolve, 20)) + await job.settle({ status: 'completed', detail: 'exit code: 0' }) + await done + + expect(frames[0]).toMatchObject({ type: 'opened', from: 0, earliest: 0, total: 6, status: 'running' }) + const outputs = frames.filter(frame => frame.type === 'output') + const text = outputs.flatMap(frame => frame.chunks.map(chunk => chunk.text)).join('') + expect(text).toBe('early live') + expect(outputs.at(-1)?.next).toBe(10) + expect(outputs.flatMap(frame => frame.chunks).find(chunk => chunk.text === 'live')?.channel).toBe('stderr') + expect(frames.at(-1)).toMatchObject({ type: 'status', status: 'completed', detail: 'exit code: 0' }) + }) + + it('resumes from an explicit offset and flags an evicted resume lossy', async () => { + const ctx = await harness() + const job = startRecordJob(ctx, { label: 'spam' }) + job.append('a'.repeat(60)) + job.append('b'.repeat(60)) + await job.settle({ status: 'completed' }) + + const fresh = observed(ctx, { jobId: job.id, from: 0 }) + await fresh.done + const output = fresh.frames.find(frame => frame.type === 'output') + expect(output?.lossy).toBe(true) + expect(output?.chunks.map(chunk => chunk.text).join('')).toBe('b'.repeat(60)) + + const resumed = observed(ctx, { jobId: job.id, from: 120 }) + await resumed.done + expect(resumed.frames.some(frame => frame.type === 'output')).toBe(false) + expect(resumed.frames.at(-1)?.type).toBe('status') + }) + + it('splits oversized reads along the frame budget', async () => { + const ctx = await harness() + const job = startRecordJob(ctx, { label: 'wide' }) + job.append('x'.repeat(30)) + job.append('y'.repeat(30)) + await job.settle({ status: 'completed' }) + const abort = new AbortController() + const frames = await collect( + observeJobRecord(ctx.jobs, { jobId: job.id }, { + flushMs: 5, + maxFrameBytes: 30, + caller: undefined, + }, abort.signal), + 5, + abort, + ) + const outputs = frames.filter(frame => frame.type === 'output') + expect(outputs).toHaveLength(2) + expect(outputs[0]?.next).toBe(30) + expect(outputs[1]?.next).toBe(60) + }) + + it('carries the lossy flag on the first frame of a split evicted read', async () => { + const ctx = await harness() + const job = startRecordJob(ctx, { label: 'evicted split' }) + job.append('a'.repeat(40)) + job.append('b'.repeat(40)) + job.append('c'.repeat(40)) + await job.settle({ status: 'completed' }) + const abort = new AbortController() + const frames = await collect( + observeJobRecord(ctx.jobs, { jobId: job.id, from: 0 }, { + flushMs: 5, + maxFrameBytes: 40, + caller: undefined, + }, abort.signal), + 5, + abort, + ) + const outputs = frames.filter(frame => frame.type === 'output') + expect(outputs[0]?.lossy).toBe(true) + expect(outputs[1]?.lossy).toBeUndefined() + }) + + it('reads owned records through the resolved caller and rejects foreign, bad, and unknown input', async () => { + const ctx = await harness() + const owner = registerAgent(ctx, 'alice') + const job = startRecordJob(ctx, { label: 'secret', owner }) + job.append('classified') + await job.settle({ status: 'completed' }) + + const { frames, done } = observed(ctx, { jobId: job.id }, owner) + await done + expect(frames.some(frame => frame.type === 'output' + && frame.chunks.some(chunk => chunk.text === 'classified'))).toBe(true) + + const foreign = new AbortController() + await expect(collect( + observeJobRecord(ctx.jobs, { jobId: job.id }, { ...OBSERVE, caller: undefined }, foreign.signal), + 1, + foreign, + )).rejects.toThrow(/belongs to another session/) + + const abort = new AbortController() + await expect(collect( + observeJobRecord(ctx.jobs, { jobId: job.id, from: -1 }, { ...OBSERVE, caller: owner }, abort.signal), + 1, + abort, + )).rejects.toThrow(/invalid observe offset/) + + const abortUnknown = new AbortController() + await expect(collect( + observeJobRecord(ctx.jobs, { jobId: JobId('bash-999') }, { ...OBSERVE, caller: undefined }, abortUnknown.signal), + 1, + abortUnknown, + )).rejects.toThrow(/unknown job/) + }) + + it('refuses a job that declared no record', async () => { + const ctx = await harness() + const job = startRecordJob(ctx, { record: false }) + const abort = new AbortController() + await expect(collect( + observeJobRecord(ctx.jobs, { jobId: job.id }, { ...OBSERVE, caller: undefined }, abort.signal), + 1, + abort, + )).rejects.toThrow(/declared no output record/) + await job.settle({ status: 'completed' }) + }) + + it('ignores output signals for other jobs while waiting', async () => { + const ctx = await harness() + const watched = startRecordJob(ctx, { label: 'watched' }) + const noisy = startRecordJob(ctx, { label: 'noisy' }) + const { abort, frames, done } = observed(ctx, { jobId: watched.id }) + await new Promise(resolve => setTimeout(resolve, 15)) + noisy.append('unrelated') + await new Promise(resolve => setTimeout(resolve, 15)) + await watched.settle({ status: 'completed' }) + await done + abort.abort() + expect(frames.filter(frame => frame.type === 'output')).toEqual([]) + await noisy.settle({ status: 'completed' }) + }) + + it('stops cleanly on abort while waiting for output', async () => { + const ctx = await harness() + const job = startRecordJob(ctx, { label: 'idle' }) + const { abort, frames, done } = observed(ctx, { jobId: job.id }) + await new Promise(resolve => setTimeout(resolve, 20)) + abort.abort() + await done + expect(frames[0]?.type).toBe('opened') + expect(frames.at(-1)?.type).not.toBe('status') + await job.settle({ status: 'completed' }) + }) +}) + +describe('SessionController.observeJob', () => { + const defaults = { + defaultModelSelection: () => ({ provider: 'fixture', model: 'fixture-model' }), + cwd: '/tmp', + } + + it('refuses observation without a job registry', async () => { + const ctx = new Context() + await ctx.plugin(SessionStore) + await ctx.plugin(AgentRegistry) + const controller = createSessionTestController(ctx, defaults) + expect(() => controller.observeJob({ jobId: JobId('bash-1') }, new AbortController().signal)) + .toThrow(/job observation unavailable/) + }) + + it('resolves the fenced-read caller from the request session', async () => { + const ctx = new Context() + await ctx.plugin(SessionStore) + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalJobRegistry) + ctx.jobs.attachController('observe-job-test') + const controller = createSessionTestController(ctx, defaults) + const session = ctx.sessions.create(SessionId('observing-session')) + const owner = { + id: session.id, + session, + inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }), + status: 'idle', + ctx, + } as unknown as Agent + ctx.agents.register(owner) + const job = startRecordJob(ctx, { label: 'owned run', owner }) + job.append('hi') + await job.settle({ status: 'completed' }) + + const abort = new AbortController() + const frames = await collect( + controller.observeJob({ sessionId: session.id, jobId: job.id }, abort.signal), + 3, + abort, + ) + expect(frames.map(frame => frame.type)).toEqual(['opened', 'output', 'status']) + }) +}) diff --git a/packages/api/session-controller/tests/test-remote.ts b/packages/api/session-controller/tests/test-remote.ts index 3d7d549a26..d125b6808d 100644 --- a/packages/api/session-controller/tests/test-remote.ts +++ b/packages/api/session-controller/tests/test-remote.ts @@ -34,6 +34,8 @@ import type { SessionFollowRequest, SessionListRequest, SessionListValue, + SessionObserveJobFrame, + SessionObserveJobRequest, SessionOpenWorkspacePathRequest, SessionOpenWorkspacePathValue, SessionPage, @@ -71,6 +73,7 @@ export interface TestSessionRemote { page(request: SessionPageRequest, signal?: AbortSignal): Promise> follow(request: SessionFollowRequest, signal?: AbortSignal): AsyncIterable control(signal?: AbortSignal): AsyncIterable + observeJob(request: SessionObserveJobRequest, signal?: AbortSignal): AsyncIterable } /** Dependencies and policy supplied by a Session Controller unit harness. */ @@ -273,5 +276,6 @@ export function createSessionTestRemote( ), follow: (request, signal = new AbortController().signal) => direct.follow(request, signal), control: (signal = new AbortController().signal) => direct.control(signal), + observeJob: (request, signal = new AbortController().signal) => direct.observeJob(request, signal), } } diff --git a/packages/api/session-controller/tsconfig.host.json b/packages/api/session-controller/tsconfig.host.json index a48fcb83a5..207daafbd5 100644 --- a/packages/api/session-controller/tsconfig.host.json +++ b/packages/api/session-controller/tsconfig.host.json @@ -18,6 +18,7 @@ "src/history.ts", "src/list.ts", "src/model-selection-projection.ts", + "src/observe-job.ts", "src/skill-catalog.ts" ], "references": [ From 0dca00b425a0d375756701c400a1cf6c8447d616 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 1 Sep 2026 18:22:04 +0800 Subject: [PATCH 016/100] refactor(api,client)!: delete the activity plane; one job roster with record observation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit packages/activity/* and packages/api/activity-controller are removed. The web roster is the session control stream's jobs frames alone; per-job output observation rides session.observeJob and the client ctx.jobOutput service. ui-activity returns to its upstream name ui-jobs and renders the single roster — a row is expandable exactly when its job declared a record (outputTotal present). Composition rows, dependency-policy exemptions, tsconfig aliases and references, generated catalogs, and the docs pages follow; the activity subsystem page is deleted and the jobs page gains the record contract. The superseding Agent Note records the decision and points the three prior notes at it. --- .../2026-09-01-jobs-absorb-activity-record.md | 35 ++ ...26-09-01-jobs-absorb-activity-record.zh.md | 35 ++ .../2026-08-08-web-background-job-display.md | 2 + ...026-08-08-web-background-job-display.zh.md | 2 + .../2026-08-24-activity-observation-seam.md | 2 + ...2026-08-24-activity-observation-seam.zh.md | 2 + .../feature/2026-08-25-unified-task-list.md | 2 + .../2026-08-25-unified-task-list.zh.md | 2 + apps/cli/composition.md | 3 - ...y-stream.e2e.ts => live-job-stream.e2e.ts} | 26 +- .../settled.expected.md | 0 .../streaming.expected.md | 0 apps/web/tsconfig.json | 2 +- docs/architecture.md | 2 +- docs/architecture.zh.md | 2 +- docs/capability-seams.md | 20 +- docs/config-catalog.md | 63 +-- docs/event-producer-consumer.md | 14 +- docs/module-graph.i18n.yaml | 4 +- docs/module-graph.md | 41 +- docs/module-graph.zh.md | 41 +- docs/subsystems/README.md | 1 - docs/subsystems/README.zh.md | 1 - docs/subsystems/activity.md | 141 ------ docs/subsystems/activity.zh.md | 141 ------ docs/subsystems/jobs.md | 141 +++++- docs/subsystems/jobs.zh.md | 27 ++ docs/subsystems/session.i18n.yaml | 4 +- docs/subsystems/session.md | 12 + docs/subsystems/session.zh.md | 12 + packages/activity/README.i18n.yaml | 6 - packages/activity/README.md | 43 -- packages/activity/README.zh.md | 43 -- .../activity/activity-local/README.i18n.yaml | 6 - packages/activity/activity-local/README.md | 98 ---- packages/activity/activity-local/README.zh.md | 98 ---- packages/activity/activity-local/package.json | 55 --- packages/activity/activity-local/src/index.ts | 438 ------------------ .../activity/activity-local/src/invariant.ts | 33 -- .../activity-local/tests/activity.spec.ts | 413 ----------------- .../tests/loader-composition.spec.ts | 60 --- .../activity/activity-local/tsconfig.json | 33 -- packages/activity/activity/README.i18n.yaml | 6 - packages/activity/activity/README.md | 101 ---- packages/activity/activity/README.zh.md | 101 ---- packages/activity/activity/package.json | 57 --- packages/activity/activity/src/brand.ts | 28 -- packages/activity/activity/src/index.ts | 138 ------ packages/activity/activity/src/invariant.ts | 62 --- packages/activity/activity/src/pump.ts | 95 ---- packages/activity/activity/src/types.ts | 184 -------- .../activity/activity/tests/invariant.spec.ts | 82 ---- .../activity/activity/tests/service.spec.ts | 98 ---- packages/activity/activity/tsconfig.json | 36 -- .../api/activity-controller/README.i18n.yaml | 6 - packages/api/activity-controller/README.md | 106 ----- packages/api/activity-controller/README.zh.md | 106 ----- packages/api/activity-controller/package.json | 103 ---- .../activity-controller/src/client/index.ts | 86 ---- .../activity-controller/src/client/model.ts | 216 --------- .../activity-controller/src/client/service.ts | 164 ------- packages/api/activity-controller/src/feed.ts | 184 -------- packages/api/activity-controller/src/index.ts | 104 ----- .../api/activity-controller/src/invariant.ts | 23 - .../api/activity-controller/src/observe.ts | 178 ------- packages/api/activity-controller/src/types.ts | 104 ----- .../tests/activity-controller.host.spec.ts | 306 ------------ .../tests/client-apply.client.spec.ts | 113 ----- .../tests/client-model.client.spec.ts | 183 -------- .../tests/client-service.client.spec.ts | 276 ----------- .../tests/controller.host.spec.ts | 102 ---- .../activity-controller/tsconfig.client.json | 46 -- .../activity-controller/tsconfig.host.json | 26 -- .../api/activity-controller/tsconfig.json | 7 - .../api/activity-controller/tsdown.config.ts | 7 - packages/api/remotes/package.json | 1 - packages/api/remotes/src/client/index.ts | 5 +- packages/api/remotes/src/index.ts | 1 - packages/api/remotes/tsconfig.client.json | 3 - packages/api/remotes/tsconfig.host.json | 3 - packages/api/session-controller/README.md | 4 + packages/bundle/base/cordis.patch.yml | 5 - packages/bundle/base/package.json | 1 - packages/bundle/web-app/cordis.patch.yml | 12 +- packages/bundle/web-app/package.json | 3 +- packages/client/README.md | 2 +- packages/client/README.zh.md | 2 +- packages/client/ui-activity/README.md | 93 ---- packages/client/ui-activity/README.zh.md | 93 ---- .../client/ui-activity/src/client/index.ts | 50 -- .../{ui-activity => ui-jobs}/README.i18n.yaml | 6 +- packages/client/ui-jobs/README.md | 93 ++++ packages/client/ui-jobs/README.zh.md | 93 ++++ .../{ui-activity => ui-jobs}/package.json | 10 +- .../src/client/JobListAction.module.css} | 0 .../src/client/JobListAction.tsx} | 222 +++------ packages/client/ui-jobs/src/client/index.ts | 49 ++ .../src/client/locales.ts | 30 +- .../src/css-modules.d.ts | 0 .../{ui-activity => ui-jobs}/src/index.ts | 4 +- .../{ui-activity => ui-jobs}/src/invariant.ts | 10 +- .../tests/browser-plugin.client.spec.ts | 50 +- .../tests/job-list-action.client.spec.tsx} | 274 ++++------- .../{ui-activity => ui-jobs}/tsconfig.json | 1 - .../{ui-activity => ui-jobs}/tsdown.config.ts | 2 +- .../src/client/slot-catalog.ts | 2 +- .../extensions/tool-cordis/src/api-catalog.ts | 212 +++------ pnpm-lock.yaml | 218 ++------- python/sdk-runtime/package.json | 1 - scripts/gen-cordis-catalog.ts | 22 +- scripts/gen-doc-graphs.ts | 20 +- scripts/package-dependency-policy.ts | 1 - scripts/verify-package-dependencies.spec.ts | 1 - .../verify-package-readme-model-experience.ts | 5 +- tsconfig.base.json | 14 +- tsconfig.client.json | 3 +- tsconfig.host.json | 5 +- 117 files changed, 923 insertions(+), 6243 deletions(-) create mode 100644 .agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md create mode 100644 .agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md rename apps/web/tests/{live-activity-stream.e2e.ts => live-job-stream.e2e.ts} (84%) rename apps/web/tests/snapshots/{live-activity-stream => live-job-stream}/settled.expected.md (100%) rename apps/web/tests/snapshots/{live-activity-stream => live-job-stream}/streaming.expected.md (100%) delete mode 100644 docs/subsystems/activity.md delete mode 100644 docs/subsystems/activity.zh.md delete mode 100644 packages/activity/README.i18n.yaml delete mode 100644 packages/activity/README.md delete mode 100644 packages/activity/README.zh.md delete mode 100644 packages/activity/activity-local/README.i18n.yaml delete mode 100644 packages/activity/activity-local/README.md delete mode 100644 packages/activity/activity-local/README.zh.md delete mode 100644 packages/activity/activity-local/package.json delete mode 100644 packages/activity/activity-local/src/index.ts delete mode 100644 packages/activity/activity-local/src/invariant.ts delete mode 100644 packages/activity/activity-local/tests/activity.spec.ts delete mode 100644 packages/activity/activity-local/tests/loader-composition.spec.ts delete mode 100644 packages/activity/activity-local/tsconfig.json delete mode 100644 packages/activity/activity/README.i18n.yaml delete mode 100644 packages/activity/activity/README.md delete mode 100644 packages/activity/activity/README.zh.md delete mode 100644 packages/activity/activity/package.json delete mode 100644 packages/activity/activity/src/brand.ts delete mode 100644 packages/activity/activity/src/index.ts delete mode 100644 packages/activity/activity/src/invariant.ts delete mode 100644 packages/activity/activity/src/pump.ts delete mode 100644 packages/activity/activity/src/types.ts delete mode 100644 packages/activity/activity/tests/invariant.spec.ts delete mode 100644 packages/activity/activity/tests/service.spec.ts delete mode 100644 packages/activity/activity/tsconfig.json delete mode 100644 packages/api/activity-controller/README.i18n.yaml delete mode 100644 packages/api/activity-controller/README.md delete mode 100644 packages/api/activity-controller/README.zh.md delete mode 100644 packages/api/activity-controller/package.json delete mode 100644 packages/api/activity-controller/src/client/index.ts delete mode 100644 packages/api/activity-controller/src/client/model.ts delete mode 100644 packages/api/activity-controller/src/client/service.ts delete mode 100644 packages/api/activity-controller/src/feed.ts delete mode 100644 packages/api/activity-controller/src/index.ts delete mode 100644 packages/api/activity-controller/src/invariant.ts delete mode 100644 packages/api/activity-controller/src/observe.ts delete mode 100644 packages/api/activity-controller/src/types.ts delete mode 100644 packages/api/activity-controller/tests/activity-controller.host.spec.ts delete mode 100644 packages/api/activity-controller/tests/client-apply.client.spec.ts delete mode 100644 packages/api/activity-controller/tests/client-model.client.spec.ts delete mode 100644 packages/api/activity-controller/tests/client-service.client.spec.ts delete mode 100644 packages/api/activity-controller/tests/controller.host.spec.ts delete mode 100644 packages/api/activity-controller/tsconfig.client.json delete mode 100644 packages/api/activity-controller/tsconfig.host.json delete mode 100644 packages/api/activity-controller/tsconfig.json delete mode 100644 packages/api/activity-controller/tsdown.config.ts delete mode 100644 packages/client/ui-activity/README.md delete mode 100644 packages/client/ui-activity/README.zh.md delete mode 100644 packages/client/ui-activity/src/client/index.ts rename packages/client/{ui-activity => ui-jobs}/README.i18n.yaml (70%) create mode 100644 packages/client/ui-jobs/README.md create mode 100644 packages/client/ui-jobs/README.zh.md rename packages/client/{ui-activity => ui-jobs}/package.json (83%) rename packages/client/{ui-activity/src/client/ActivityListAction.module.css => ui-jobs/src/client/JobListAction.module.css} (100%) rename packages/client/{ui-activity/src/client/ActivityListAction.tsx => ui-jobs/src/client/JobListAction.tsx} (61%) create mode 100644 packages/client/ui-jobs/src/client/index.ts rename packages/client/{ui-activity => ui-jobs}/src/client/locales.ts (78%) rename packages/client/{ui-activity => ui-jobs}/src/css-modules.d.ts (100%) rename packages/client/{ui-activity => ui-jobs}/src/index.ts (66%) rename packages/client/{ui-activity => ui-jobs}/src/invariant.ts (70%) rename packages/client/{ui-activity => ui-jobs}/tests/browser-plugin.client.spec.ts (73%) rename packages/client/{ui-activity/tests/activity-list-action.client.spec.tsx => ui-jobs/tests/job-list-action.client.spec.tsx} (59%) rename packages/client/{ui-activity => ui-jobs}/tsconfig.json (89%) rename packages/client/{ui-activity => ui-jobs}/tsdown.config.ts (76%) diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md new file mode 100644 index 0000000000..501cdcf801 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md @@ -0,0 +1,35 @@ +# Agent Note: The job registry absorbs the observation record; the standalone activity seam is removed + +Status: implemented + +English | [中文](2026-09-01-jobs-absorb-activity-record.zh.md) + +## Problem + +The [activity observation seam](../feature/2026-08-24-activity-observation-seam.md) shipped live output streaming as a second registry beside `ctx.jobs`: producers registered the same work twice (a job for lifecycle, an activity for observation), kept the two terminal states consistent by hand (`observeBackgroundActivity` waited for `proc.done` before mapping the outcome so a pump failure could not freeze a wrong terminal state), correlated the rows through `ActivityCorrelation.jobId`, and wrapped every observation call in registry-absent degradation branches. The Web client maintained two rosters (session-control `jobs` frames and the activity control stream) and joined them per row. Measured before the merge: eight pairing call sites, and one producer population — background bash/pwsh (both registries), PTY sends and subagent delegations (jobs only), foreground workflow (activity only). + +The one activity without a job was the foreground workflow mirror. Everything else the split enabled — independent observers, absolute-offset reads, bounded retention — is a property of the record, not of the registry split. + +## Decision + +`ctx.jobs` owns the observation record; `packages/activity/`, `packages/api/activity-controller`, and the correlation vocabulary are removed. + +- **`JobStart.record?: true`** declares an observable output record. `run(job)` now receives the job's producer face — `RunningJob { id, append(text, {channel?, gapBefore?}), updateDetail(detail) }` — so the id is issued before the starter runs (a throwing starter still registers nothing; its ordinal is skipped). Writes staged inside the starter surface at the registration commit. `updateDetail` works for every job and gives `job_list` a live progress line; `append` without a record declaration logs and drops. +- **There is no `end`.** Job settlement — the producer outcome, a kill, or teardown — is the record's only close: it trims retention to the settled cap and fires the final `onOutput` signal. The dual-settlement pairing (`ActivityHandle.end` first-wins against teardown force-ends) is deleted, not reimplemented. +- **`readRecord(id, from, caller)`** is the non-consuming multi-reader view (absolute UTF-8 offsets, `lossy` below the retained window), fenced like every other job read; it never marks the job `reported`. The model-facing `readOutput` cursor is untouched — the two projections serve different readers and stay separate by design. +- **`jobs-local`** absorbs the chunk ring (`retainBytes` 256 KiB live, `settledRetainBytes` 16 KiB settled), and `pumpJobOutput` replaces `pumpActivityOutput` beside the seam. Producers fold the pump's final drain into `hooks.done` so the record holds its last bytes before settlement closes it. +- **The wire moves to the session namespace.** `SessionJob.outputTotal` (present exactly for record jobs) marks a row observable; `session.observeJob({sessionId?, jobId, from?})` streams anchor/output/status frames with the fenced read resolved from the request's session — the killJob authorization shape. `api-activity-controller` is deleted; its roster stream is redundant (the jobs frames are the roster) and its observe machinery moved into `session-controller` (`observe-job.ts`, client `ctx.jobOutput`). +- **`ui-activity` returns to its upstream name `ui-jobs`** and renders one roster: `jobsBySession` rows, expandable exactly when `outputTotal` is present. The two-roster join is deleted. +- **Foreground workflow loses its live panel deliberately.** `tool-workflow`'s activity mirror is removed; a foreground run surfaces through its recorded run/member lifecycle events only, and the per-line `workflow/phase` / `workflow/log` narration has no observer until workflow gains `run_in_background` and registers a record job. Jobs stay a pure background registry — no `foreground` mode bit, no model-invisible rows, no run-less rows. + +## Rejected + +- **A `foreground: true` job mode** to keep the foreground workflow panel: it needs two coupled enforcement points (reported-at-birth and a `job_list` filter) whose divergence double-delivers or leaks rows to the model, for one edge feature replaceable by `run_in_background`. +- **Serving model reads from the record** (deleting `readOutput`): model reads are producer-formatted (truncation and spill notices, sandbox markers) and consuming; the record is raw, channel-labeled, and non-consuming. Unifying them moves producer-specific formatting into the registry or noise into the observer stream. +- **Keeping the split with shared implementation** (a common registry library): it removes the duplicated skeleton but keeps the real costs — double registration, terminal-state pairing, correlation, a second wire roster, and a second package family. + +The [prior seam note](../feature/2026-08-24-activity-observation-seam.md)'s argument against durable session events and control-stream framing for live output still holds and carries over unchanged: the record is process-local observation state, never a session event, so "model-visible ⟺ logged" is untouched. + +## Consequences + +Every observable row is a killable job; a pure-observation surface with no lifecycle would need a new home (harness diagnostics belong to the inspector plane, not here). A future remote job provider must implement lifecycle and record together. The record's retention config lives on `jobs-local`; the observation wire's cadence config (`observeFlushMs`, `observeMaxFrameBytes`) lives on `session-controller`. diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md new file mode 100644 index 0000000000..40e795146c --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md @@ -0,0 +1,35 @@ +# Agent Note:job 注册表吸收观测 record;独立的 activity seam 被移除 + +Status: implemented + +[English](2026-09-01-jobs-absorb-activity-record.md) | 中文 + +## 问题 + +[activity 观测 seam](../feature/2026-08-24-activity-observation-seam.zh.md) 把实时输出流做成了 `ctx.jobs` 旁边的第二个注册表:生产者要把同一份工作登记两次(job 管生命周期,activity 管观测),手工保持两个终态一致(`observeBackgroundActivity` 要等 `proc.done` 才映射 outcome,防止 pump 失败把错误终态冻上去),通过 `ActivityCorrelation.jobId` 关联两行,并给每个观测调用包上注册表缺失的降级分支。Web 客户端维护两份名册(session-control 的 `jobs` 帧与 activity control 流)并逐行做 join。合并前实测:八个配对调用点;生产者人口为——后台 bash/pwsh(双注册表)、PTY 发送与 subagent 委托(仅 jobs)、前台 workflow(仅 activity)。 + +唯一没有 job 的 activity 是前台 workflow 镜像。拆分带来的其他一切——独立观察者、绝对偏移读取、有界保留——都是 record 的性质,不是注册表拆分的性质。 + +## 决策 + +`ctx.jobs` 拥有观测 record;`packages/activity/`、`packages/api/activity-controller` 与 correlation 词表被移除。 + +- **`JobStart.record?: true`** 声明可观测输出 record。`run(job)` 现在收到 job 的生产者面——`RunningJob { id, append(text, {channel?, gapBefore?}), updateDetail(detail) }`——因此 id 在 starter 运行前签发(starter 抛出仍然不登记任何东西;序号被跳过)。starter 内暂存的写入在登记提交时可见。`updateDetail` 对所有 job 可用,让 `job_list` 也能看到实时进度行;未声明 record 的 `append` 记日志并丢弃。 +- **没有 `end`。** job 结算——生产者 outcome、kill 或 teardown——是 record 唯一的关闭:裁剪到结算保留量并发出最后一个 `onOutput` 信号。双结算配对(`ActivityHandle.end` 与 teardown 强结的 first-wins 对账)被删除,而非重新实现。 +- **`readRecord(id, from, caller)`** 是非消耗多读者视图(绝对 UTF-8 偏移,低于保留窗口为 `lossy`),围栏与其他 job 读取一致;永不置 `reported`。模型面的 `readOutput` 游标原样保留——两个投影服务不同读者,刻意保持分离。 +- **`jobs-local`** 吸收块环(`retainBytes` 运行期 256 KiB,`settledRetainBytes` 结算后 16 KiB),`pumpJobOutput` 在 seam 旁替换 `pumpActivityOutput`。生产者把 pump 的末次排空折进 `hooks.done`,让 record 在结算关闭前握有最后的字节。 +- **wire 移入 session 命名空间。** `SessionJob.outputTotal`(恰在 record job 上存在)标记行可观测;`session.observeJob({sessionId?, jobId, from?})` 流式发送 anchor/output/status 帧,围栏读取者由请求的 session 解析——与 killJob 相同的授权形态。`api-activity-controller` 删除;其名册流是冗余的(jobs 帧就是名册),observe 机制移入 `session-controller`(`observe-job.ts`,客户端 `ctx.jobOutput`)。 +- **`ui-activity` 改回上游名字 `ui-jobs`**,渲染单一名册:`jobsBySession` 行,恰在 `outputTotal` 存在时可展开。双名册 join 被删除。 +- **前台 workflow 有意失去实时面板。** `tool-workflow` 的 activity 镜像被移除;前台 run 只通过已记录的 run/member 生命周期事件呈现,逐行的 `workflow/phase` / `workflow/log` 叙述在 workflow 获得 `run_in_background` 并登记 record job 之前没有观察者。jobs 保持纯后台注册表——没有 `foreground` 模式位、没有模型不可见行、没有无 run 行。 + +## 已否决 + +- **`foreground: true` job 模式**以保留前台 workflow 面板:它需要两个耦合的执行点(出生即 reported 与 `job_list` 过滤),两者一旦分叉就会双投递或向模型泄漏行,而它换来的只是一个可被 `run_in_background` 替代的边缘特性。 +- **用 record 服务模型读取**(删除 `readOutput`):模型读取是生产者格式化的(截断与 spill 提示、sandbox 标记)且消耗型;record 是原始、带 channel 标签、非消耗的。统一二者要么把生产者特有格式化搬进注册表,要么把噪声混入观察者流。 +- **保留拆分但共享实现**(公共注册表库):它消除重复骨架,但保留真正的成本——双重登记、终态配对、correlation、第二条 wire 名册与第二个包族。 + +[先前 seam note](../feature/2026-08-24-activity-observation-seam.zh.md) 反对用持久会话事件或 control 流承载实时输出的论证仍然成立并原样沿用:record 是进程本地观测状态,从不是会话事件,「模型可见 ⟺ 已记录」不受影响。 + +## 后果 + +每个可观测行都是可 kill 的 job;没有生命周期的纯观测面需要新的归属(harness 诊断属于 inspector 平面,不在这里)。未来的远端 job provider 必须同时实现生命周期与 record。record 的保留配置在 `jobs-local`;观测 wire 的节奏配置(`observeFlushMs`、`observeMaxFrameBytes`)在 `session-controller`。 diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md index 23074b5d38..3dd003c0e9 100644 --- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md +++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md @@ -2,6 +2,8 @@ Status: implemented +Update: the output phase this note deferred now ships as the per-job observation record on `ctx.jobs` — see [jobs absorb the record](../architecture/2026-09-01-jobs-absorb-activity-record.md). + English | [中文](2026-08-08-web-background-job-display.zh.md) ## Problem diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md index 06645267ee..5d1ee4bada 100644 --- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md +++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md @@ -2,6 +2,8 @@ Status: implemented +Update:本文推迟的输出阶段现已作为 `ctx.jobs` 上的逐 job 观测 record 交付——见 [jobs 吸收 record](../architecture/2026-09-01-jobs-absorb-activity-record.zh.md)。 + [English](2026-08-08-web-background-job-display.md) | 中文 ## 问题 diff --git a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md index 88109cb340..29ee08b1bb 100644 --- a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md +++ b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md @@ -2,6 +2,8 @@ Status: implemented +Superseded: the standalone seam described here was folded into `ctx.jobs` as the per-job observation record — see [jobs absorb the record](../architecture/2026-09-01-jobs-absorb-activity-record.md); the durable-vs-live analysis below still holds. + English | [中文](2026-08-24-activity-observation-seam.zh.md) ## Problem diff --git a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md index b8aa938edf..97ac4f195c 100644 --- a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md +++ b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md @@ -2,6 +2,8 @@ 状态:implemented +Superseded:本文描述的独立 seam 已折入 `ctx.jobs`,成为逐 job 的观测 record——见 [jobs 吸收 record](../architecture/2026-09-01-jobs-absorb-activity-record.zh.md);下文关于持久化与实时通道的分析仍然成立。 + [English](2026-08-24-activity-observation-seam.md) | 中文 ## 问题 diff --git a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.md b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.md index e67ca84d96..daf6582bf2 100644 --- a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.md +++ b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.md @@ -2,6 +2,8 @@ Status: implemented +Superseded: the two-roster join described here was removed with the activity seam — the job rows are now the whole roster; see [jobs absorb the record](../architecture/2026-09-01-jobs-absorb-activity-record.md). + English | [中文](2026-08-25-unified-task-list.zh.md) ## Problem diff --git a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md index 2a71b04ec3..624747396e 100644 --- a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md +++ b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md @@ -2,6 +2,8 @@ 状态:implemented +Superseded:本文描述的双名册 join 已随 activity seam 一并移除——job 行现在就是完整名册;见 [jobs 吸收 record](../architecture/2026-09-01-jobs-absorb-activity-record.zh.md)。 + [English](2026-08-25-unified-task-list.md) | 中文 ## 问题 diff --git a/apps/cli/composition.md b/apps/cli/composition.md index 60ddefee1a..5386b94ae0 100644 --- a/apps/cli/composition.md +++ b/apps/cli/composition.md @@ -40,8 +40,6 @@ flowchart LR cfg --> plugin_dsh_base_agent_default_model plugin_dsh_base_jobs["jobs
        @deepseek-ai/dsh-jobs-local"] cfg --> plugin_dsh_base_jobs - plugin_dsh_base_activity["activity
        @deepseek-ai/dsh-activity-local"] - cfg --> plugin_dsh_base_activity plugin_dsh_base_llm_retry["llm-retry
        @deepseek-ai/dsh-llm-retry"] cfg --> plugin_dsh_base_llm_retry plugin_dsh_base_settings["settings
        @deepseek-ai/dsh-settings-file"] @@ -202,7 +200,6 @@ flowchart LR | `plugin-package-inventory-deepseek` | `@deepseek-ai/dsh-plugin-package-inventory-deepseek` | | `agent-default-model` | `@deepseek-ai/dsh-agent-default-model` | | `jobs` | `@deepseek-ai/dsh-jobs-local` | -| `activity` | `@deepseek-ai/dsh-activity-local` | | `llm-retry` | `@deepseek-ai/dsh-llm-retry` | | `settings` | `@deepseek-ai/dsh-settings-file` | | `credentials` | `@deepseek-ai/dsh-credentials-local` | diff --git a/apps/web/tests/live-activity-stream.e2e.ts b/apps/web/tests/live-job-stream.e2e.ts similarity index 84% rename from apps/web/tests/live-activity-stream.e2e.ts rename to apps/web/tests/live-job-stream.e2e.ts index 7c0ce1532b..65926f7463 100644 --- a/apps/web/tests/live-activity-stream.e2e.ts +++ b/apps/web/tests/live-job-stream.e2e.ts @@ -1,5 +1,5 @@ -// Session-header live activities driven by a real background bash run: the -// roster row arrives over the activity control stream, expanding it opens the +// Session-header job list driven by a real background bash run: the job row +// arrives over the session control stream, expanding it opens the record // observation stream, and the panel shows the process's real output while it // is still running. No model call is involved. import { readFile } from 'node:fs/promises' @@ -19,11 +19,11 @@ import { import { newEnglishPage, saveFailureShot } from './support.ts' const FIXTURE = fileURLToPath(new URL('../../../snapshots/web/fresh-round-trip/session.jsonl', import.meta.url)) -const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/live-activity-stream', import.meta.url)) +const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/live-job-stream', import.meta.url)) const STREAMING_EXPECTED = join(SNAPSHOT_DIR, 'streaming.expected.md') const SETTLED_EXPECTED = join(SNAPSHOT_DIR, 'settled.expected.md') const MODE = webSnapshotMode() -const SEED_ID = 'live-activity-stream-web-e2e' +const SEED_ID = 'live-job-stream-web-e2e' // One fixed line of early output, then silence long enough that the streaming // assertions never race the process exiting; the test kills it explicitly. const COMMAND = "printf 'streamed-%s\\n' marker-line; sleep 45" @@ -44,7 +44,7 @@ async function liveAgent(scaffold: WebScaffold, sessionId: SessionId): Promise { +describe.skipIf(MODE === 'record')('web e2e: live job stream', () => { let scaffold: WebScaffold let browser: Browser let page: Page @@ -69,7 +69,7 @@ describe.skipIf(MODE === 'record')('web e2e: live activity stream', () => { await sessionRow.click() // Opening the session drives the Host's ordinary Agent resolution; the - // activity owner must be that exact live instance, never a second one. + // job owner must be that exact live instance, never a second one. agent = await liveAgent(scaffold, SessionId(SEED_ID)) }, 120_000) @@ -79,13 +79,13 @@ describe.skipIf(MODE === 'record')('web e2e: live activity stream', () => { }) it('streams a running background command\'s real output into the expanded panel', async () => { - onTestFailed(() => saveFailureShot(page, 'web-e2e-live-activity-streaming')) - const trigger = page.getByRole('button', { name: '1 task running' }) + onTestFailed(() => saveFailureShot(page, 'web-e2e-live-job-streaming')) + const trigger = page.getByRole('button', { name: '1 background job running' }) expect(await trigger.count()).toBe(0) const started = await scaffold.ctx.tools.execute({ signal: new AbortController().signal, - callId: ToolCallId('live-activity-stream-e2e'), + callId: ToolCallId('live-job-stream-e2e'), name: 'bash', arguments: { command: COMMAND, description: 'Emit one live line then hold', run_in_background: true }, agent, @@ -95,11 +95,11 @@ describe.skipIf(MODE === 'record')('web e2e: live activity stream', () => { if (matched === null) throw new Error(`background bash reported no job id: ${reported}`) jobId = JobId(matched[0]) - // The roster row reaches the header over the activity control stream. + // The job row reaches the header over the session control stream. await trigger.waitFor({ timeout: 15_000 }) await trigger.click() - // Expanding the row opens the observation stream; the panel then renders + // Expanding the row opens the record observation stream; the panel then renders // the command's real stdout while the process is still running. const expand = page.getByRole('button', { name: /Show live output/ }) await expand.waitFor({ timeout: 10_000 }) @@ -113,12 +113,12 @@ describe.skipIf(MODE === 'record')('web e2e: live activity stream', () => { }, 60_000) it('settles the open panel when the job is killed, keeping the streamed tail', async () => { - onTestFailed(() => saveFailureShot(page, 'web-e2e-live-activity-settled')) + onTestFailed(() => saveFailureShot(page, 'web-e2e-live-job-settled')) expect(scaffold.ctx.jobs.kill(jobId, agent, 'web e2e cancellation')).toBe('requested') // Settlement arrives on the observation stream itself, so the open panel // flips without any further interaction; the roster trigger follows. - const idle = page.getByRole('button', { name: '1 task' }) + const idle = page.getByRole('button', { name: '1 background job' }) await idle.waitFor({ timeout: 20_000 }) await page.getByText('streamed-marker-line').waitFor({ timeout: 10_000 }) diff --git a/apps/web/tests/snapshots/live-activity-stream/settled.expected.md b/apps/web/tests/snapshots/live-job-stream/settled.expected.md similarity index 100% rename from apps/web/tests/snapshots/live-activity-stream/settled.expected.md rename to apps/web/tests/snapshots/live-job-stream/settled.expected.md diff --git a/apps/web/tests/snapshots/live-activity-stream/streaming.expected.md b/apps/web/tests/snapshots/live-job-stream/streaming.expected.md similarity index 100% rename from apps/web/tests/snapshots/live-activity-stream/streaming.expected.md rename to apps/web/tests/snapshots/live-job-stream/streaming.expected.md diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json index 0f95b48551..38e021b1aa 100644 --- a/apps/web/tsconfig.json +++ b/apps/web/tsconfig.json @@ -95,7 +95,7 @@ "tests/subagent-interrupt-ui.e2e.ts", "tests/sidebar-subagent-activity.e2e.ts", "tests/background-job-list.e2e.ts", - "tests/live-activity-stream.e2e.ts", + "tests/live-job-stream.e2e.ts", "tests/bash-abort-row.e2e.ts", "tests/skill-tool-row.e2e.ts", "tests/turn-tail-actions.e2e.ts", diff --git a/docs/architecture.md b/docs/architecture.md index 8a2f9b772c..f36c956d9a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -129,7 +129,7 @@ New behavior attaches to a documented extension point. Changing the loop itself | Add persistent terminal execution | register a `ctx.terminals` backend plus `dsh-tool-terminal` | | Add a human command | register on `ctx.commands`; it dispatches without a model turn | | Add background work | register on `ctx.jobs`; `job_*` tools collect or stop it | -| Stream live output to observers | open a `ctx.activities` handle; the Web client renders it | +| Stream live output to observers | declare `record: true` on the `ctx.jobs` start; the Web client renders it | | Start a Session from an external webhook | register a trusted rule on `ctx.webhookRuntime` and mount a provider adapter | | Add filesystem access or policy | register a `ctx.fs` provider or listen to `fs/*` events | | Confine spawned processes | use a `ctx.sandbox` backend; consumers wrap argv before spawning | diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index cc291fb018..67e2ae905c 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -133,7 +133,7 @@ seam 正是替换一个提供方就能改变整个产品的原因。文件系统 | 添加持久化终端执行 | 注册 `ctx.terminals` 后端和 `dsh-tool-terminal` | | 添加用户命令 | 在 `ctx.commands` 上注册;它无需模型轮次即可分派 | | 添加后台工作 | 在 `ctx.jobs` 上注册;`job_*` 工具负责收集或停止 | -| 向观察者流式输出 | 打开一个 `ctx.activities` 句柄;Web 客户端负责渲染 | +| 向观察者流式输出 | 在 `ctx.jobs` 启动时声明 `record: true`;Web 客户端负责渲染 | | 从外部 webhook 启动 Session | 在 `ctx.webhookRuntime` 上注册可信规则,并挂载提供方适配器 | | 添加文件系统访问或策略 | 注册 `ctx.fs` 提供方,或监听 `fs/*` 事件 | | 限制所启动的进程 | 使用 `ctx.sandbox` 后端;消费方在启动进程前包装 argv | diff --git a/docs/capability-seams.md b/docs/capability-seams.md index 6c0867eeb8..db2b8db956 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -45,8 +45,6 @@ flowchart LR pkg_api_workspace_controller["api-workspace-controller"] svc_workspaceController["ctx.workspaceController
        Host Workspace Remote controller"] svc_directoryPickerController["ctx.directoryPickerController
        Host directory-picking Remote controller"] - pkg_api_activity_controller["api-activity-controller"] - svc_activityController["ctx.activityController
        Host Activity Remote controller"] svc_invariants["ctx.invariants
        Package-owned invariant registry"] pkg_scope["scope"] pkg_typert_registry["typert-registry"] @@ -186,11 +184,6 @@ flowchart LR svc_jobs["ctx.jobs
        Background job registry"] pkg_jobs_local["jobs-local"] pkg_tool_jobs["tool-jobs"] - pkg_activity["activity"] - svc_activities["ctx.activities
        Live activity observation registry"] - pkg_activity_local["activity-local"] - pkg_tool_workflow["tool-workflow"] - pkg_activity_controller["activity-controller"] pkg_web["web"] svc_web["ctx.web
        Web access provider registry"] pkg_web_search_exa["web-search-exa"] @@ -214,6 +207,7 @@ flowchart LR pkg_workflow["workflow"] svc_workflowEngine["ctx.workflowEngine
        Workflow script engine"] pkg_workflow_worker_thread["workflow-worker-thread"] + pkg_tool_workflow["tool-workflow"] pkg_webhook["webhook"] svc_webhookRuntime["ctx.webhookRuntime
        Webhook rule runtime"] pkg_webhook_github["webhook-github"] @@ -223,13 +217,10 @@ flowchart LR pkg_cordis_host_runner["cordis-host-runner"] svc_dynamicCordisRunner["ctx.dynamicCordisRunner
        Dynamic Cordis package host runner"] svc_cordisInspect["ctx.cordisInspect
        Dynamic Cordis inspect registry"] - pkg_activity --> svc_activities - pkg_activity_local --> svc_activities pkg_agent --> svc_agents pkg_agent_default_model --> svc_agentDefaultModel pkg_agent_loop --> svc_agentLoop pkg_agent_presets --> svc_agentPresets - pkg_api_activity_controller --> svc_activityController pkg_api_gateway --> svc_typertGateway pkg_api_session_controller --> svc_sessionController pkg_api_session_controller --> svc_sessionFileReferences @@ -342,10 +333,6 @@ flowchart LR pkg_workflow --> svc_workflowEngine pkg_workflow_worker_thread --> svc_workflowEngine pkg_workspace --> svc_workspaceRegistry - svc_activities --> pkg_activity_controller - svc_activities --> pkg_tool_bash - svc_activities --> pkg_tool_pwsh - svc_activities --> pkg_tool_workflow svc_agentDefaultModel --> pkg_api_session_controller svc_agentDefaultModel --> pkg_headless svc_agentLoop --> pkg_agent_spine_demo @@ -382,6 +369,7 @@ flowchart LR svc_invariants --> pkg_session svc_jobs --> pkg_tool_bash svc_jobs --> pkg_tool_jobs + svc_jobs --> pkg_tool_pwsh svc_jobs --> pkg_tool_subagent svc_jobs --> pkg_tool_terminal svc_llm --> pkg_agent_loop @@ -489,7 +477,6 @@ flowchart LR | `ctx.settingsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | Projects the user-settings seam onto the generated Remote namespace: the read is always redacted and every refusal is classified here, not on the seam Definition. | | `ctx.workspaceController` | `core` | [`api-workspace-controller`](../packages/api/workspace-controller) | - | - | - | Owns Workspace commands and reconnect-safe Workspace state delivery through the generated Remote namespace. | | `ctx.directoryPickerController` | `core` | [`api-workspace-controller`](../packages/api/workspace-controller) | - | - | - | Carries the picking seam onto the wire: capability gating, cancellation, and the seam-coded failures a browser directory flow discriminates on. | -| `ctx.activityController` | `core` | [`api-activity-controller`](../packages/api/activity-controller) | - | - | - | Owns the live-activity roster stream and per-activity non-consuming output observation through the generated Remote namespace. | | `ctx.invariants` | `core` | [`invariants`](../packages/runtime-diagnostics/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. | | `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges. | | `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier. | @@ -535,8 +522,7 @@ flowchart LR | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process), [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. | | `ctx.agentTeams` | `core` | [`experimental-agent-team`](../packages/experimental/agent-team) | - | [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team), [`experimental-client-ui-agent-team`](../packages/experimental/client-ui-agent-team) | - | Owns the implicit-root roster, durable peer mailbox, shared task DAG, continuable-child lifecycle, and generated Team Remote methods; tool-agent-team contributes model controls and client-ui-agent-team mounts the browser contribution. | | `ctx.inspector` | `core` | `inspector` | - | - | - | Owns the Worker-hosted CDP target and the transport-independent Host and Client observation and Cordis-tree query API. | -| `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-jobs is the model-facing controller that reads, lists, and kills it; jobs-local is the process-local registry. | -| `ctx.activities` | `seam` | [`activity`](../packages/activity/activity) | [`activity-local`](../packages/activity/activity-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`tool-workflow`](../packages/workflow/tool-workflow), `activity-controller` | - | Producers mirror live output and status into non-consuming offset-addressed streams; activity-controller serves them to browsers, and the model-facing paths (jobs cursors, tool results) stay untouched. | +| `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs) | - | Producers (background bash/pwsh, PTY sends, and subagent delegations) register running work; record-declaring jobs additionally stream raw output for non-consuming observers; tool-jobs is the model-facing controller that reads, lists, and kills it; jobs-local is the process-local registry. | | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-http`](../packages/web/web-fetch-http) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. | | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | The backend saves oversized tool text and returns a model-facing locator plus retrieval hint; spill-policy is the tools/post-execute consumer that decides when to spill. | | `ctx.directoryPicker` | `seam` | [`host-directory-picker`](../packages/host/directory-picker) | [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | [`api-workspace-controller`](../packages/api/workspace-controller) | - | Discriminated interaction capability: the native backend opens one OS chooser on the host display, the browse backend serves listing/creation primitives for the in-app browser; dual-face backends fill ui-workspace directory-flow slots from their browser halves (no wire advertisement). | diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 424eff1c5e..64b72e0ff7 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -33,22 +33,6 @@ Depends on: `Stream` (`@agentclientprotocol/sdk`) Source: [`packages/acp/acp/src/index.ts:75`](../packages/acp/acp/src/index.ts) -
        - -## `@deepseek-ai/dsh-activity-local` - -```ts config-catalog -/** Configuration for the process-local observation registry. */ -export interface Config { - /** Live output retention per activity in UTF-8 bytes; omission defaults to 262144. */ - retainBytes?: number - /** Output retention kept after an activity settles, in UTF-8 bytes; omission defaults to 16384. */ - settledRetainBytes?: number -} -``` - -Source: [`packages/activity/activity-local/src/index.ts:31`](../packages/activity/activity-local/src/index.ts) - ## `@deepseek-ai/dsh-agent-default-model` @@ -292,24 +276,6 @@ Depends on: [`ToolPresentationMode`](subsystems/tools.md) Source: [`packages/core/agent-tool-presentation/src/index.ts:38`](../packages/core/agent-tool-presentation/src/index.ts) - - -## `@deepseek-ai/dsh-api-activity-controller` - -Requires: `typert` - -```ts config-catalog -/** Configuration for the Activity Remote owner. */ -export interface Config { - /** Coalescing window after new output before an observation read, in milliseconds (default 100). */ - flushMs?: number - /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */ - maxFrameBytes?: number -} -``` - -Source: [`packages/api/activity-controller/src/index.ts:26`](../packages/api/activity-controller/src/index.ts) - ## `@deepseek-ai/dsh-api-gateway` @@ -339,10 +305,14 @@ export interface Config { readonly coldBlankProbeMaxBytes?: number /** Override platform desktop-opener detection. */ readonly nativeOpen?: boolean + /** Coalescing window after new record output before a job-observation read, in milliseconds (default 100). */ + readonly observeFlushMs?: number + /** Soft byte budget per job-observation output frame (default 65536); one larger chunk ships whole. */ + readonly observeMaxFrameBytes?: number } ``` -Source: [`packages/api/session-controller/src/index.ts:67`](../packages/api/session-controller/src/index.ts) +Source: [`packages/api/session-controller/src/index.ts:77`](../packages/api/session-controller/src/index.ts) @@ -988,10 +958,14 @@ export interface Config { * omission defaults to 10. */ maxConcurrentJobsPerOwner?: number + /** Live record retention per job in UTF-8 bytes; omission defaults to 262144. */ + retainBytes?: number + /** Record retention kept after a job settles, in UTF-8 bytes; omission defaults to 16384. */ + settledRetainBytes?: number } ``` -Source: [`packages/jobs/jobs-local/src/index.ts:31`](../packages/jobs/jobs-local/src/index.ts) +Source: [`packages/jobs/jobs-local/src/index.ts:38`](../packages/jobs/jobs-local/src/index.ts) @@ -2712,12 +2686,12 @@ Requires: `tools` · `shell` · `systemPrompt` · `shellEnv` export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean - /** Poll cadence for mirroring background output into `ctx.activities`, in milliseconds (default 150). */ - activityPollMs?: number + /** Poll cadence for copying background output into the job record, in milliseconds (default 150). */ + recordPollMs?: number } ``` -Source: [`packages/shell/tool-bash/src/index.ts:35`](../packages/shell/tool-bash/src/index.ts) +Source: [`packages/shell/tool-bash/src/index.ts:34`](../packages/shell/tool-bash/src/index.ts) @@ -2879,12 +2853,12 @@ Requires: `tools` · `shell` · `systemPrompt` · `shellEnv` export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean - /** Poll cadence for mirroring background output into `ctx.activities`, in milliseconds (default 150). */ - activityPollMs?: number + /** Poll cadence for copying background output into the job record, in milliseconds (default 150). */ + recordPollMs?: number } ``` -Source: [`packages/shell/tool-pwsh/src/index.ts:60`](../packages/shell/tool-pwsh/src/index.ts) +Source: [`packages/shell/tool-pwsh/src/index.ts:53`](../packages/shell/tool-pwsh/src/index.ts) @@ -3158,7 +3132,7 @@ export interface Config { } ``` -Source: [`packages/workflow/tool-workflow/src/index.ts:33`](../packages/workflow/tool-workflow/src/index.ts) +Source: [`packages/workflow/tool-workflow/src/index.ts:32`](../packages/workflow/tool-workflow/src/index.ts) @@ -3454,7 +3428,6 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co - `@deepseek-ai/dsh-authorization` — requires `credentials` ([`packages/credentials/authorization/src/index.ts`](../packages/credentials/authorization/src/index.ts)) - `@deepseek-ai/dsh-client-locale` ([`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts)) - `@deepseek-ai/dsh-client-modules` — requires `webServer` · `loader` ([`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts)) -- `@deepseek-ai/dsh-client-ui-activity` ([`packages/client/ui-activity/src/index.ts`](../packages/client/ui-activity/src/index.ts)) - `@deepseek-ai/dsh-client-ui-agent-preset` ([`packages/client/ui-agent-preset/src/index.ts`](../packages/client/ui-agent-preset/src/index.ts)) - `@deepseek-ai/dsh-client-ui-approval` ([`packages/client/ui-approval/src/index.ts`](../packages/client/ui-approval/src/index.ts)) - `@deepseek-ai/dsh-client-ui-attachment` ([`packages/client/ui-attachment/src/index.ts`](../packages/client/ui-attachment/src/index.ts)) @@ -3468,6 +3441,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co - `@deepseek-ai/dsh-client-ui-directory-picker-native` ([`packages/client/ui-directory-picker-native/src/index.ts`](../packages/client/ui-directory-picker-native/src/index.ts)) - `@deepseek-ai/dsh-client-ui-goal` ([`packages/client/ui-goal/src/index.ts`](../packages/client/ui-goal/src/index.ts)) - `@deepseek-ai/dsh-client-ui-input-trigger` ([`packages/client/ui-input-trigger/src/index.ts`](../packages/client/ui-input-trigger/src/index.ts)) +- `@deepseek-ai/dsh-client-ui-jobs` ([`packages/client/ui-jobs/src/index.ts`](../packages/client/ui-jobs/src/index.ts)) - `@deepseek-ai/dsh-client-ui-layout` ([`packages/client/ui-layout/src/index.ts`](../packages/client/ui-layout/src/index.ts)) - `@deepseek-ai/dsh-client-ui-message-feedback` ([`packages/client/ui-message-feedback/src/index.ts`](../packages/client/ui-message-feedback/src/index.ts)) - `@deepseek-ai/dsh-client-ui-model-selection` ([`packages/client/ui-model-selection/src/index.ts`](../packages/client/ui-model-selection/src/index.ts)) @@ -3528,7 +3502,6 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co Abstract service classes — a deployment loads a concrete implementation package instead ([capability seams](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)). -- `@deepseek-ai/dsh-activity` — abstract `ActivityRegistry` ([`packages/activity/activity/src/index.ts`](../packages/activity/activity/src/index.ts)) - `@deepseek-ai/dsh-attachment` — abstract `AttachmentStore` ([`packages/attachment/attachment/src/index.ts`](../packages/attachment/attachment/src/index.ts)) - `@deepseek-ai/dsh-code-runtime` — abstract `CodeRuntime` ([`packages/code-runtime/code-runtime/src/index.ts`](../packages/code-runtime/code-runtime/src/index.ts)) - `@deepseek-ai/dsh-compaction` — abstract `CompactionEngine` ([`packages/compaction/compaction/src/index.ts`](../packages/compaction/compaction/src/index.ts)) diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 48aacf9dc6..fc05e2ec6b 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -21,11 +21,11 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:224`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:185`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` | | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:285`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:523`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:503`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:530`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:509`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:516`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:586`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:566`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:593`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:572`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:579`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` | | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:80`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | @@ -69,8 +69,8 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:79`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) | | `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:68`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) | | `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:89`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) | -| `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:58`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow) | -| `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:51`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow) | +| `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:58`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | +| `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:51`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | | `workflow/start` | `emit` | [`packages/workflow/workflow/src/index.ts:43`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) | ## Non-harness or undeclared event strings seen in package source diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml index 218ec66b69..8727d17738 100644 --- a/docs/module-graph.i18n.yaml +++ b/docs/module-graph.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 docs/module-graph.md -module-graph.md: f1a2f29c9e61567a92fb8b98737446c2258087a9 -module-graph.zh.md: 86845aa00035ab18ead49e6f90a2e66c18984028 +module-graph.md: 6b69abd956658b5bf17f0b49158ec8f366888d94 +module-graph.zh.md: 4af048cc46db9bcf990a702d29970a67ff222949 diff --git a/docs/module-graph.md b/docs/module-graph.md index f1a2f29c9e..6b69abd956 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -107,12 +107,7 @@ flowchart TD subgraph group_acp["packages/acp"] pkg_acp["acp"] end - subgraph group_activity["packages/activity"] - pkg_activity["activity"] - pkg_activity_local["activity-local"] - end subgraph group_api["packages/api"] - pkg_api_activity_controller["api-activity-controller"] pkg_api_gateway["api-gateway"] pkg_api_remotes["api-remotes"] pkg_api_session_controller["api-session-controller"] @@ -141,7 +136,6 @@ flowchart TD pkg_client_locale["client-locale"] pkg_client_modules["client-modules"] pkg_client_store["client-store"] - pkg_client_ui_activity["client-ui-activity"] pkg_client_ui_agent_preset["client-ui-agent-preset"] pkg_client_ui_approval["client-ui-approval"] pkg_client_ui_attachment["client-ui-attachment"] @@ -154,6 +148,7 @@ flowchart TD pkg_client_ui_directory_picker_native["client-ui-directory-picker-native"] pkg_client_ui_goal["client-ui-goal"] pkg_client_ui_input_trigger["client-ui-input-trigger"] + pkg_client_ui_jobs["client-ui-jobs"] pkg_client_ui_layout["client-ui-layout"] pkg_client_ui_message_feedback["client-ui-message-feedback"] pkg_client_ui_model_selection["client-ui-model-selection"] @@ -727,12 +722,6 @@ flowchart TD pkg_fs_sandbox --> pkg_invariants pkg_fs_sandbox --> pkg_sandbox pkg_fs_sandbox --> pkg_sandbox_policy - pkg_activity --> pkg_agent - pkg_activity --> pkg_brand - pkg_activity --> pkg_invariants - pkg_activity --> pkg_jobs - pkg_activity --> pkg_llm - pkg_activity --> pkg_session pkg_headless --> pkg_agent pkg_headless --> pkg_agent_default_model pkg_headless --> pkg_invariants @@ -873,20 +862,6 @@ flowchart TD pkg_hooks_codex --> pkg_session_persistence pkg_hooks_codex --> pkg_session_projection pkg_hooks_codex --> pkg_tools - pkg_activity_local --> pkg_activity - pkg_activity_local --> pkg_agent - pkg_activity_local --> pkg_invariants - pkg_activity_local --> pkg_scope - pkg_api_activity_controller --> pkg_activity - pkg_api_activity_controller --> pkg_agent - pkg_api_activity_controller --> pkg_api_gateway - pkg_api_activity_controller --> pkg_client_connection - pkg_api_activity_controller --> pkg_client_store - pkg_api_activity_controller --> pkg_invariants - pkg_api_activity_controller --> pkg_jobs - pkg_api_activity_controller --> pkg_llm - pkg_api_activity_controller --> pkg_session - pkg_api_activity_controller --> pkg_typert_protocol pkg_command_compact --> pkg_commands pkg_command_compact --> pkg_compaction pkg_command_compact --> pkg_invariants @@ -1017,7 +992,6 @@ flowchart TD pkg_llm_replay --> pkg_invariants pkg_llm_replay --> pkg_llm pkg_llm_replay --> pkg_session - pkg_tool_workflow --> pkg_activity pkg_tool_workflow --> pkg_agent pkg_tool_workflow --> pkg_invariants pkg_tool_workflow --> pkg_llm @@ -1075,7 +1049,6 @@ flowchart TD pkg_host_plugin_inventory --> pkg_brand pkg_host_plugin_inventory --> pkg_invariants pkg_host_plugin_inventory --> pkg_typert_protocol - pkg_tool_bash --> pkg_activity pkg_tool_bash --> pkg_agent pkg_tool_bash --> pkg_invariants pkg_tool_bash --> pkg_jobs @@ -1087,7 +1060,6 @@ flowchart TD pkg_tool_bash --> pkg_system_prompt pkg_tool_bash --> pkg_tools pkg_tool_bash --> pkg_user_approval - pkg_tool_pwsh --> pkg_activity pkg_tool_pwsh --> pkg_agent pkg_tool_pwsh --> pkg_invariants pkg_tool_pwsh --> pkg_jobs @@ -1366,7 +1338,6 @@ flowchart TD | [`client-locale`](../packages/client/locale) | `client` | — | | [`client-modules`](../packages/client/modules) | `client` | — | | [`client-store`](../packages/client/store) | `client` | — | -| [`client-ui-activity`](../packages/client/ui-activity) | `client` | — | | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | — | | [`client-ui-approval`](../packages/client/ui-approval) | `client` | — | | [`client-ui-attachment`](../packages/client/ui-attachment) | `client` | — | @@ -1379,6 +1350,7 @@ flowchart TD | [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native) | `client` | — | | [`client-ui-goal`](../packages/client/ui-goal) | `client` | — | | [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | — | +| [`client-ui-jobs`](../packages/client/ui-jobs) | `client` | — | | [`client-ui-layout`](../packages/client/ui-layout) | `client` | — | | [`client-ui-message-feedback`](../packages/client/ui-message-feedback) | `client` | — | | [`client-ui-model-selection`](../packages/client/ui-model-selection) | `client` | — | @@ -1525,7 +1497,6 @@ flowchart TD | [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) | | [`goal-round-driver`](../packages/goal/goal-round-driver) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`invariants`](../packages/runtime-diagnostics/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) | -| [`activity`](../packages/activity/activity) | `activity` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`compaction`](../packages/compaction/compaction) | `compaction` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) | @@ -1548,8 +1519,6 @@ flowchart TD | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) | | [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions) | | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) | -| [`activity-local`](../packages/activity/activity-local) | `activity` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`scope`](../packages/core/scope) | -| [`api-activity-controller`](../packages/api/activity-controller) | `api` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`api-gateway`](../packages/api/gateway), [`client-connection`](../packages/client/connection), [`client-store`](../packages/client/store), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | | [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`agent-instructions`](../packages/context/agent-instructions) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) | | [`file-reference-local`](../packages/context/file-reference-local) | `context` | [`agent`](../packages/core/agent), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | @@ -1572,7 +1541,7 @@ flowchart TD | [`tool-terminal`](../packages/terminal/tool-terminal) | `terminal` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`system-prompt`](../packages/core/system-prompt), [`terminal`](../packages/terminal/terminal), [`tools`](../packages/core/tools) | | [`agent-loop-testkit`](../packages/test-support/agent-loop-testkit) | `test-support` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | -| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | +| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | | [`plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek) | `llm` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-title`](../packages/session/session-title), [`tool-todo`](../packages/todo/tool-todo) | | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`mcp-client`](../packages/mcp/mcp-client), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`token-meter`](../packages/llm/token-meter), [`user-approval`](../packages/interaction/user-approval) | @@ -1581,8 +1550,8 @@ flowchart TD | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) | | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-protocol`](../packages/typert/protocol) | -| [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | -| [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | +| [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | +| [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`webhook`](../packages/webhook/webhook) | `webhook` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`workspace`](../packages/workspace/workspace) | | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`attachment`](../packages/attachment/attachment), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval), [`util-time`](../packages/util/time) | | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index 86845aa000..4af048cc46 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -109,12 +109,7 @@ flowchart TD subgraph group_acp["packages/acp"] pkg_acp["acp"] end - subgraph group_activity["packages/activity"] - pkg_activity["activity"] - pkg_activity_local["activity-local"] - end subgraph group_api["packages/api"] - pkg_api_activity_controller["api-activity-controller"] pkg_api_gateway["api-gateway"] pkg_api_remotes["api-remotes"] pkg_api_session_controller["api-session-controller"] @@ -143,7 +138,6 @@ flowchart TD pkg_client_locale["client-locale"] pkg_client_modules["client-modules"] pkg_client_store["client-store"] - pkg_client_ui_activity["client-ui-activity"] pkg_client_ui_agent_preset["client-ui-agent-preset"] pkg_client_ui_approval["client-ui-approval"] pkg_client_ui_attachment["client-ui-attachment"] @@ -156,6 +150,7 @@ flowchart TD pkg_client_ui_directory_picker_native["client-ui-directory-picker-native"] pkg_client_ui_goal["client-ui-goal"] pkg_client_ui_input_trigger["client-ui-input-trigger"] + pkg_client_ui_jobs["client-ui-jobs"] pkg_client_ui_layout["client-ui-layout"] pkg_client_ui_message_feedback["client-ui-message-feedback"] pkg_client_ui_model_selection["client-ui-model-selection"] @@ -729,12 +724,6 @@ flowchart TD pkg_fs_sandbox --> pkg_invariants pkg_fs_sandbox --> pkg_sandbox pkg_fs_sandbox --> pkg_sandbox_policy - pkg_activity --> pkg_agent - pkg_activity --> pkg_brand - pkg_activity --> pkg_invariants - pkg_activity --> pkg_jobs - pkg_activity --> pkg_llm - pkg_activity --> pkg_session pkg_headless --> pkg_agent pkg_headless --> pkg_agent_default_model pkg_headless --> pkg_invariants @@ -875,20 +864,6 @@ flowchart TD pkg_hooks_codex --> pkg_session_persistence pkg_hooks_codex --> pkg_session_projection pkg_hooks_codex --> pkg_tools - pkg_activity_local --> pkg_activity - pkg_activity_local --> pkg_agent - pkg_activity_local --> pkg_invariants - pkg_activity_local --> pkg_scope - pkg_api_activity_controller --> pkg_activity - pkg_api_activity_controller --> pkg_agent - pkg_api_activity_controller --> pkg_api_gateway - pkg_api_activity_controller --> pkg_client_connection - pkg_api_activity_controller --> pkg_client_store - pkg_api_activity_controller --> pkg_invariants - pkg_api_activity_controller --> pkg_jobs - pkg_api_activity_controller --> pkg_llm - pkg_api_activity_controller --> pkg_session - pkg_api_activity_controller --> pkg_typert_protocol pkg_command_compact --> pkg_commands pkg_command_compact --> pkg_compaction pkg_command_compact --> pkg_invariants @@ -1019,7 +994,6 @@ flowchart TD pkg_llm_replay --> pkg_invariants pkg_llm_replay --> pkg_llm pkg_llm_replay --> pkg_session - pkg_tool_workflow --> pkg_activity pkg_tool_workflow --> pkg_agent pkg_tool_workflow --> pkg_invariants pkg_tool_workflow --> pkg_llm @@ -1077,7 +1051,6 @@ flowchart TD pkg_host_plugin_inventory --> pkg_brand pkg_host_plugin_inventory --> pkg_invariants pkg_host_plugin_inventory --> pkg_typert_protocol - pkg_tool_bash --> pkg_activity pkg_tool_bash --> pkg_agent pkg_tool_bash --> pkg_invariants pkg_tool_bash --> pkg_jobs @@ -1089,7 +1062,6 @@ flowchart TD pkg_tool_bash --> pkg_system_prompt pkg_tool_bash --> pkg_tools pkg_tool_bash --> pkg_user_approval - pkg_tool_pwsh --> pkg_activity pkg_tool_pwsh --> pkg_agent pkg_tool_pwsh --> pkg_invariants pkg_tool_pwsh --> pkg_jobs @@ -1368,7 +1340,6 @@ flowchart TD | [`client-locale`](../packages/client/locale) | `client` | — | | [`client-modules`](../packages/client/modules) | `client` | — | | [`client-store`](../packages/client/store) | `client` | — | -| [`client-ui-activity`](../packages/client/ui-activity) | `client` | — | | [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | — | | [`client-ui-approval`](../packages/client/ui-approval) | `client` | — | | [`client-ui-attachment`](../packages/client/ui-attachment) | `client` | — | @@ -1381,6 +1352,7 @@ flowchart TD | [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native) | `client` | — | | [`client-ui-goal`](../packages/client/ui-goal) | `client` | — | | [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | — | +| [`client-ui-jobs`](../packages/client/ui-jobs) | `client` | — | | [`client-ui-layout`](../packages/client/ui-layout) | `client` | — | | [`client-ui-message-feedback`](../packages/client/ui-message-feedback) | `client` | — | | [`client-ui-model-selection`](../packages/client/ui-model-selection) | `client` | — | @@ -1527,7 +1499,6 @@ flowchart TD | [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) | | [`goal-round-driver`](../packages/goal/goal-round-driver) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`invariants`](../packages/runtime-diagnostics/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) | -| [`activity`](../packages/activity/activity) | `activity` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`compaction`](../packages/compaction/compaction) | `compaction` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) | @@ -1550,8 +1521,6 @@ flowchart TD | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) | | [`plan-mode`](../packages/plan/plan-mode) | `plan` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions) | | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) | -| [`activity-local`](../packages/activity/activity-local) | `activity` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`scope`](../packages/core/scope) | -| [`api-activity-controller`](../packages/api/activity-controller) | `api` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`api-gateway`](../packages/api/gateway), [`client-connection`](../packages/client/connection), [`client-store`](../packages/client/store), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | | [`command-compact`](../packages/compaction/command-compact) | `compaction` | [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`agent-instructions`](../packages/context/agent-instructions) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`tools`](../packages/core/tools) | | [`file-reference-local`](../packages/context/file-reference-local) | `context` | [`agent`](../packages/core/agent), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | @@ -1574,7 +1543,7 @@ flowchart TD | [`tool-terminal`](../packages/terminal/tool-terminal) | `terminal` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`system-prompt`](../packages/core/system-prompt), [`terminal`](../packages/terminal/terminal), [`tools`](../packages/core/tools) | | [`agent-loop-testkit`](../packages/test-support/agent-loop-testkit) | `test-support` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | -| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | +| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | | [`plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek) | `llm` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-title`](../packages/session/session-title), [`tool-todo`](../packages/todo/tool-todo) | | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`mcp-client`](../packages/mcp/mcp-client), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`token-meter`](../packages/llm/token-meter), [`user-approval`](../packages/interaction/user-approval) | @@ -1583,8 +1552,8 @@ flowchart TD | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) | | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-protocol`](../packages/typert/protocol) | -| [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | -| [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`activity`](../packages/activity/activity), [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | +| [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | +| [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`webhook`](../packages/webhook/webhook) | `webhook` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`workspace`](../packages/workspace/workspace) | | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`attachment`](../packages/attachment/attachment), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval), [`util-time`](../packages/util/time) | | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) | diff --git a/docs/subsystems/README.md b/docs/subsystems/README.md index d75bd368d5..f3340ebeb4 100644 --- a/docs/subsystems/README.md +++ b/docs/subsystems/README.md @@ -44,7 +44,6 @@ One page per subsystem of the DeepSeek Harness: what it is, the data structures | [spill.md](spill.md) | the spill storage seam: `SaveTextSpill`, `SpillOwner`/`SpillSource`, `SpillRef`, the branded `SpillLocator` | | [workflow.md](workflow.md) | the workflow seam: `WorkflowStartRequest`, `WorkflowMeta`, `WorkflowRun`/`Result`, the `workflow/*` event payloads, `WorkflowError` fatality | | [jobs.md](jobs.md) | the background-job runtime: branded `JobId`s, the producer contract, consumer views, and `ctx.jobs` service behavior | -| [activity.md](activity.md) | live activity observation: branded `ActivityId`s, the producer handle, non-consuming offset reads, and the wire streams | | [permission-presets.md](permission-presets.md) | the permission-preset layer: `PresetSpec`/`PresetOption`, the derived `custom` state, the log-only `permission/preset` event | | [plan.md](plan.md) | plan mode: the log-only `plan/mode` state, pending-selection flush, `PlanModeConfig`, the `exit_plan_mode` review arc | | [invariants.md](invariants.md) | the runtime-invariant registry: selection `Config`, `InvariantInstaller`/`InvariantFailure`, the empty-companion contract | diff --git a/docs/subsystems/README.zh.md b/docs/subsystems/README.zh.md index 589a72d81f..2e4523f03d 100644 --- a/docs/subsystems/README.zh.md +++ b/docs/subsystems/README.zh.md @@ -44,7 +44,6 @@ | [spill.md](spill.zh.md) | spill 存储 seam:`SaveTextSpill`、`SpillOwner`/`SpillSource`、`SpillRef`、品牌类型 `SpillLocator` | | [workflow.md](workflow.zh.md) | 工作流 seam:`WorkflowStartRequest`、`WorkflowMeta`、`WorkflowRun`/`Result`、`workflow/*` 事件载荷、`WorkflowError` 致命性 | | [jobs.md](jobs.zh.md) | 后台任务运行时:品牌化 `JobId`、producer 约定、消费方视图和 `ctx.jobs` 服务行为 | -| [activity.md](activity.zh.md) | 实时活动观察:品牌化 `ActivityId`、生产者句柄、非消费 offset 读取与 wire 流 | | [permission-presets.md](permission-presets.zh.md) | 权限预设层:`PresetSpec`/`PresetOption`、派生的 `custom` 状态、仅记日志的 `permission/preset` 事件 | | [plan.md](plan.zh.md) | 计划模式:仅记日志的 `plan/mode` 状态、待定选择的冲刷、`PlanModeConfig`、`exit_plan_mode` 审阅流程 | | [invariants.md](invariants.zh.md) | 运行时不变式注册表:选择配置 `Config`、`InvariantInstaller`/`InvariantFailure`、空配套插件约定 | diff --git a/docs/subsystems/activity.md b/docs/subsystems/activity.md deleted file mode 100644 index 000bdc30be..0000000000 --- a/docs/subsystems/activity.md +++ /dev/null @@ -1,141 +0,0 @@ -# Live Activity Observation - -English | [中文](activity.zh.md) - -Types shared by streaming-output producers, `ctx.activities`, and the observation consumers. The [observation-seam Agent Note](../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md) owns the design; this page records the cross-package vocabulary from [`packages/activity/activity/src/types.ts`](../../packages/activity/activity/src/types.ts) and the wire frames from [`packages/api/activity-controller/src/types.ts`](../../packages/api/activity-controller/src/types.ts). - -An **activity** is one observable unit of long-running work: an append-only bounded output stream plus live status. The registry is a pure observation plane — it starts nothing, cancels nothing, and is invisible to the model. Producers keep their execution resources and their model-facing surfaces (`ctx.jobs` consuming cursors, tool results); observers read non-consumingly at absolute byte offsets, so any number of them coexist with the model's single consuming cursor. - -## Ids, kinds, and correlation - -`ActivityId` is a [branded id](core.md#branded-ids) generated as `-N`; visibility relies on owner authorization, not id secrecy. `ActivityKindMap` is merge-extensible (`bash` seeded; `pwsh` and `workflow` merged by their producers). `ActivityCorrelation` links one activity to the `CallId` that started the work and the `JobId` carrying its model-facing control surface, so a consumer attaches the stream to an existing card or row without guessing from labels. - -## Producer face - -`open(spec)` returns an `ActivityHandle` with synchronous `append(text, { channel?, gapBefore? })`, `updateDetail(detail)`, and first-wins `end(outcome)`. Offsets advance by each chunk's UTF-8 byte length; `gapBefore` marks producer-side loss so a discontinuity stays visible. After `end` — including a teardown force-end — `append` and `updateDetail` log and drop rather than throw, so a producer's trailing flush cannot break its own teardown. - -`pumpActivityOutput(handle, sources, { pollMs, done })` adapts pull substrates: it copies each non-consuming offset reader (the subprocess `readFrom(fromByte)` family, re-exposed on `ShellProcess.observed`) into the handle at a bounded cadence and drains once more after `done` settles. Push-natural producers (the workflow tool's run mirror) append directly. - -## Observation - -`read(id, from, caller?)` returns the retained chunks overlapping `[from, total)` and the resume offset `next`, consuming nothing. Offsets stay absolute across eviction: `outputEarliest` on the snapshot names the oldest retained byte, and a read below it is `lossy: true`, never an error. Retention is provider policy ([`dsh-activity-local`](../../packages/activity/activity-local/README.md): `retainBytes` live, trimmed to `settledRetainBytes` at settlement). - -Two effect-scoped listener families deliver owner-relative on the jobs-registry terms: `onActivitiesChanged` fires per visible-set change (open, detail, settlement, removal) so consumers re-read whole rows, and `onOutput` signals stream advancement (append or settlement) carrying only the id, so each consumer reads from its own cursor. - -## Wire transport - -[`dsh-api-activity-controller`](../../packages/api/activity-controller/README.md) exposes the plane to browsers as two Remote streams: `activity.control` (baseline plus whole-bucket roster replacement frames) and `activity.observe` (one `opened` anchor, coalesced `output` frames, then the terminal `status` on the same stream, after which the generation closes). Output frames are transient — durable history stays with the producers' tool results, exactly as the [web job display decision](../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md) requires. [`dsh-client-ui-activity`](../../packages/client/ui-activity/README.md) renders the roster in the session header and opens observation streams only while a panel is expanded. - - - - - -## Cordis API - -Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md). - - - -### `ctx.activities` — `ActivityRegistry` (abstract seam) - -Abstract streaming-output registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.activities` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior). - -Implementations must honor these semantics: - -- Observation never consumes. Any number of readers hold their own absolute byte offsets; a read changes no cursor and no producer state, so the model-facing paths (`ctx.jobs.read()`, tool results) are unaffected. -- Records outlive producer fibers. Owner disposal ends still-open records and removes them; service disposal ends and clears everything. Neither awaits a producer — the registry owns no execution resource. -- Retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement trims retention to the settled cap. -- Listener delivery is owner-relative: a listener registered from an unscoped context — a host composition's own carrier — sees every owner, while one registered under an agent composition's scope sees exactly the agents composed under it. Every listener is contained. - -```ts cordis-catalog -/** - * Validate the spec, attach owner cleanup, and atomically register one - * activity. A rejection leaves no id; after return the producer owns the - * handle and the visible set has changed. - * @param spec - activity identity, owner, and correlation. - * @returns the producer face of the registered activity. - */ -abstract open(spec: ActivityOpen): ActivityHandle - -/** - * List caller-owned and unowned activities in registration order without - * exposing another session's labels or output. - * @param caller - reading agent; a non-agent caller sees only unowned activities. - * @returns fresh snapshots. - */ -abstract list(caller?: Agent): ActivitySnapshot[] - -/** - * Return a fresh snapshot. Throws for an unknown or foreign activity. - * @param id - activity to look up. - * @param caller - reading agent checked against the owner. - * @returns a fresh snapshot. - */ -abstract get(id: ActivityId, caller?: Agent): ActivitySnapshot - -/** - * Read retained output from an absolute byte offset without consuming it. - * Resume by passing a previous read's `next`; a foreign offset inside a - * retained chunk returns that whole chunk (its `at` may precede `from`). - * Throws for an unknown or foreign activity or a negative or non-integer - * offset. - * @param id - activity to read. - * @param from - absolute byte offset to read from (0 for the retained head). - * @param caller - reading agent checked against the owner. - * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. - */ -abstract read(id: ActivityId, from: number, caller?: Agent): ActivityRead - -/** - * Register an effect-scoped observer of visible-set changes: opening, - * detail updates, settlement, owner-disposal removal, and the emptying that - * service disposal commits — so an observer re-reads rather than - * accumulating deltas. Listeners are contained and never awaited. - * @param listener - receives the owner whose visible set changed, or - * `undefined` when an unowned activity changed and every caller's set did. - * @returns disposer that unregisters the listener. - */ -abstract onActivitiesChanged(listener: ActivitiesChangedListener): () => void - -/** - * Register an effect-scoped observer of stream advancement — one signal per - * committed append and one at settlement, carrying only the activity id. - * A consumer schedules a {@link read} from its own cursor; the registry - * never pushes payloads. Listeners are contained and never awaited. - * @param listener - receives the id whose stream advanced. - * @returns disposer that unregisters the listener. - */ -abstract onOutput(listener: ActivityOutputListener): () => void -``` - -Types: [Agent](core.md) - -Source: [`packages/activity/activity/src/index.ts`](../../packages/activity/activity/src/index.ts) - - - -### `ctx.activityController` — `ActivityController` - -Host service backing the generated `ctx.remote.activity` namespace. - -```ts cordis-catalog -/** - * Stream a complete roster baseline followed by whole-bucket replacements. - * @param signal - generation cancellation. - * @returns baseline followed by per-owner roster replacement frames. - */ -@Remote({ mode: 'stream' }) control(signal: AbortSignal): AsyncIterable - -/** - * Stream one activity's retained output from an absolute byte offset, then - * its terminal status once settled and drained. Non-consuming: the - * model-facing cursors never observe these reads. - * @param request - target activity and optional resume offset. - * @param signal - generation cancellation. - * @returns anchor, coalesced output frames, and the terminal status. - */ -@Remote({ mode: 'stream' }) observe(request: ActivityObserveRequest, signal: AbortSignal): AsyncIterable -``` - -Source: [`packages/api/activity-controller/src/index.ts`](../../packages/api/activity-controller/src/index.ts) - diff --git a/docs/subsystems/activity.zh.md b/docs/subsystems/activity.zh.md deleted file mode 100644 index 1fc79e9d59..0000000000 --- a/docs/subsystems/activity.zh.md +++ /dev/null @@ -1,141 +0,0 @@ -# 实时活动观察 - -[English](activity.md) | 中文 - -流式输出生产者、`ctx.activities` 与观察消费者共享的类型。设计归[观察 seam Agent Note](../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md)所有;本页记录 [`packages/activity/activity/src/types.ts`](../../packages/activity/activity/src/types.ts) 的跨包词汇与 [`packages/api/activity-controller/src/types.ts`](../../packages/api/activity-controller/src/types.ts) 的 wire 帧。 - -**activity** 是一个可观察的长时工作单元:一条 append-only 的有界输出流加实时状态。注册表是纯观察面——不启动、不取消任何工作,对模型不可见。生产者保留自己的执行资源与模型面(`ctx.jobs` 消费游标、工具结果);观察者按绝对字节 offset 非消费读取,任意数量的观察者可与模型的单一消费游标共存。 - -## Id、kind 与关联 - -`ActivityId` 是[品牌化 id](core.zh.md#branded-ids),生成为 `-N`;可见性靠 owner 授权而非 id 保密。`ActivityKindMap` 可合并扩展(内置 `bash`;`pwsh` 与 `workflow` 由各自生产者合并)。`ActivityCorrelation` 把一个 activity 关联到发起工作的 `CallId` 与承载其模型控制面的 `JobId`,消费者据此把流挂到已有卡片或行上,不必靠 label 猜。 - -## 生产者面 - -`open(spec)` 返回 `ActivityHandle`:同步的 `append(text, { channel?, gapBefore? })`、`updateDetail(detail)` 与 first-wins 的 `end(outcome)`。offset 按每个 chunk 的 UTF-8 字节长度推进;`gapBefore` 标记生产者侧丢失,让断点保持可见。`end` 之后——包括 teardown 强制 end——`append` 与 `updateDetail` 记日志后丢弃而不抛错,生产者的收尾 flush 不会砸掉自己的 teardown。 - -`pumpActivityOutput(handle, sources, { pollMs, done })` 适配 pull 型底座:把每个非消费 offset 读取器(subprocess 的 `readFrom(fromByte)` 家族,经 `ShellProcess.observed` 复出)按有界节奏复制进句柄,并在 `done` 结算后再排干一次。push 天然的生产者(workflow 工具的运行镜像)直接 append。 - -## 观察 - -`read(id, from, caller?)` 返回与 `[from, total)` 重叠的保留 chunk 及续读 offset `next`,绝不消费。offset 跨淘汰稳定:快照上的 `outputEarliest` 指明最老保留字节,低于它的读取得到 `lossy: true` 而非错误。保留量是 provider 策略([`dsh-activity-local`](../../packages/activity/activity-local/README.zh.md):存活 `retainBytes`,结算时裁到 `settledRetainBytes`)。 - -两个 effect 范围的监听族按 jobs 注册表条款做 owner 相对投递:`onActivitiesChanged` 在每次可见集变化(开启、detail、结算、移除)时触发,消费者整读行;`onOutput` 发出流推进信号(append 或结算),只带 id,各消费者按自己的游标读取。 - -## Wire 传输 - -[`dsh-api-activity-controller`](../../packages/api/activity-controller/README.zh.md) 以两条 Remote 流把观察面暴露给浏览器:`activity.control`(baseline + 整桶 roster 替换帧)与 `activity.observe`(一帧 `opened` 锚点、合并的 `output` 帧、同流的终态 `status`,之后本代关闭)。输出帧是瞬态的——持久历史仍在生产者的工具结果里,与 [web job display 决策](../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md)的要求一致。[`dsh-client-ui-activity`](../../packages/client/ui-activity/README.zh.md) 在会话头部渲染 roster,只在面板展开时打开观察流。 - - - - - -## Cordis API - -Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md). - - - -### `ctx.activities` — `ActivityRegistry` (abstract seam) - -Abstract streaming-output registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.activities` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior). - -Implementations must honor these semantics: - -- Observation never consumes. Any number of readers hold their own absolute byte offsets; a read changes no cursor and no producer state, so the model-facing paths (`ctx.jobs.read()`, tool results) are unaffected. -- Records outlive producer fibers. Owner disposal ends still-open records and removes them; service disposal ends and clears everything. Neither awaits a producer — the registry owns no execution resource. -- Retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement trims retention to the settled cap. -- Listener delivery is owner-relative: a listener registered from an unscoped context — a host composition's own carrier — sees every owner, while one registered under an agent composition's scope sees exactly the agents composed under it. Every listener is contained. - -```ts cordis-catalog -/** - * Validate the spec, attach owner cleanup, and atomically register one - * activity. A rejection leaves no id; after return the producer owns the - * handle and the visible set has changed. - * @param spec - activity identity, owner, and correlation. - * @returns the producer face of the registered activity. - */ -abstract open(spec: ActivityOpen): ActivityHandle - -/** - * List caller-owned and unowned activities in registration order without - * exposing another session's labels or output. - * @param caller - reading agent; a non-agent caller sees only unowned activities. - * @returns fresh snapshots. - */ -abstract list(caller?: Agent): ActivitySnapshot[] - -/** - * Return a fresh snapshot. Throws for an unknown or foreign activity. - * @param id - activity to look up. - * @param caller - reading agent checked against the owner. - * @returns a fresh snapshot. - */ -abstract get(id: ActivityId, caller?: Agent): ActivitySnapshot - -/** - * Read retained output from an absolute byte offset without consuming it. - * Resume by passing a previous read's `next`; a foreign offset inside a - * retained chunk returns that whole chunk (its `at` may precede `from`). - * Throws for an unknown or foreign activity or a negative or non-integer - * offset. - * @param id - activity to read. - * @param from - absolute byte offset to read from (0 for the retained head). - * @param caller - reading agent checked against the owner. - * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. - */ -abstract read(id: ActivityId, from: number, caller?: Agent): ActivityRead - -/** - * Register an effect-scoped observer of visible-set changes: opening, - * detail updates, settlement, owner-disposal removal, and the emptying that - * service disposal commits — so an observer re-reads rather than - * accumulating deltas. Listeners are contained and never awaited. - * @param listener - receives the owner whose visible set changed, or - * `undefined` when an unowned activity changed and every caller's set did. - * @returns disposer that unregisters the listener. - */ -abstract onActivitiesChanged(listener: ActivitiesChangedListener): () => void - -/** - * Register an effect-scoped observer of stream advancement — one signal per - * committed append and one at settlement, carrying only the activity id. - * A consumer schedules a {@link read} from its own cursor; the registry - * never pushes payloads. Listeners are contained and never awaited. - * @param listener - receives the id whose stream advanced. - * @returns disposer that unregisters the listener. - */ -abstract onOutput(listener: ActivityOutputListener): () => void -``` - -Types: [Agent](core.zh.md) - -Source: [`packages/activity/activity/src/index.ts`](../../packages/activity/activity/src/index.ts) - - - -### `ctx.activityController` — `ActivityController` - -Host service backing the generated `ctx.remote.activity` namespace. - -```ts cordis-catalog -/** - * Stream a complete roster baseline followed by whole-bucket replacements. - * @param signal - generation cancellation. - * @returns baseline followed by per-owner roster replacement frames. - */ -@Remote({ mode: 'stream' }) control(signal: AbortSignal): AsyncIterable - -/** - * Stream one activity's retained output from an absolute byte offset, then - * its terminal status once settled and drained. Non-consuming: the - * model-facing cursors never observe these reads. - * @param request - target activity and optional resume offset. - * @param signal - generation cancellation. - * @returns anchor, coalesced output frames, and the terminal status. - */ -@Remote({ mode: 'stream' }) observe(request: ActivityObserveRequest, signal: AbortSignal): AsyncIterable -``` - -Source: [`packages/api/activity-controller/src/index.ts`](../../packages/api/activity-controller/src/index.ts) - diff --git a/docs/subsystems/jobs.md b/docs/subsystems/jobs.md index 092da7b6f7..1b8e58f27b 100644 --- a/docs/subsystems/jobs.md +++ b/docs/subsystems/jobs.md @@ -23,7 +23,7 @@ interface JobKindMap { ## Producer contract -`JobStart` declares identity and a starter. The runtime finishes preflight before calling `run()` and commits without a later failable step. Producers own execution resources; the runtime owns identity, access, and lifecycle state. +`JobStart` declares identity and a starter. The runtime finishes preflight before calling `run()` with the job's producer face and commits without a later failable step. Producers own execution resources; the runtime owns identity, access, and lifecycle state. ```ts type-equiv /** @@ -38,7 +38,9 @@ interface JobStart { label: string /** * Optional UTF-8 byte cap for each complete model-facing completion notice or - * output read, including controller status metadata. + * output read, including controller status metadata. Independent of record + * retention: it bounds the consuming model surface, never + * {@link JobRegistry.readRecord}. */ outputLimitBytes?: number /** @@ -49,11 +51,22 @@ interface JobStart { */ owner?: Agent /** - * Start the work after preflight and synchronously return its hooks. Called - * once; a throw leaves nothing registered, and the producer must clean up any - * partially started resources. + * Declares an observable output record beside the model-facing surfaces: + * {@link RunningJob.append} retains chunks in a bounded ring that any number + * of observers read at absolute byte offsets through + * {@link JobRegistry.readRecord}, and snapshots carry + * {@link JobSnapshot.outputTotal} and {@link JobSnapshot.outputEarliest}. + * Without the declaration `append` logs and drops. */ - run(): JobHooks + record?: true + /** + * Start the work after preflight and synchronously return its hooks. Called + * once with the job's producer face; a throw leaves nothing registered (the + * spent ordinal is skipped), and the producer must clean up any partially + * started resources. + * @param job - the issued id plus the record append and live-detail writers. + */ + run(job: RunningJob): JobHooks } ``` @@ -71,13 +84,16 @@ interface JobHooks { * Resolves after the producer releases its resources, not merely when work * finishes. Must not reject; the runtime converts a rejection to `failed`. * If teardown cancellation throws, the runtime may force-fail only the - * registry record without claiming that the work stopped. + * registry record without claiming that the work stopped. Settlement also + * ends the record: fold any record-filling pump into this promise so the + * final drain lands before the registry trims and closes the stream. */ done: Promise /** * Consume output produced since the previous call. The producer formats * truncation and spill notices. Absence marks a final-output-only job; each - * job has one consuming cursor. + * job has one consuming cursor. Independent of the record: this is the + * model-facing projection, {@link JobRegistry.readRecord} the observer one. */ readOutput?(): string } @@ -95,6 +111,70 @@ interface JobOutcome { } ``` +## Observation record + +A producer that declares `record: true` streams raw output into a bounded per-job ring through the `RunningJob` face its starter receives; any number of observers read retained chunks at absolute byte offsets through `readRecord` without touching the consuming model cursor or notice state. Job settlement ends the stream and trims retention to the settled cap — the record has no separate lifecycle. `pumpJobOutput` copies producer offset-readers (the subprocess `readFrom` family) into the record at a bounded cadence. + +```ts type-equiv +/** + * Producer face of one registered job, handed to {@link JobStart.run} and + * valid for the job's whole life. All methods are synchronous. Writes staged + * inside the starter call are retained and become visible with the + * registration commit; after settlement — the producer's own outcome, a kill, + * or a registry-forced teardown end — both methods log and drop instead of + * throwing, so a producer's trailing flush cannot break its own teardown path. + */ +interface RunningJob { + /** The registry-issued id (`-N`). */ + readonly id: JobId + /** + * Append one record chunk. Offsets advance by the chunk's UTF-8 byte + * length; an empty chunk is dropped without waking observers. Without a + * {@link JobStart.record} declaration the chunk is logged and dropped. + * @param text - the chunk text, exactly as produced. + * @param options - stream label and gap marker. + */ + append(text: string, options?: JobAppendOptions): void + /** + * Replace the snapshot's status detail with a live progress line (`3/10`). + * Works for every job, with or without a record. + * @param detail - the new detail line. + */ + updateDetail(detail: string): void +} +``` + +```ts type-equiv +/** One retained record chunk returned by {@link JobRegistry.readRecord}. */ +interface JobRecordChunk { + /** Absolute offset of the chunk's first byte. */ + at: number + /** Chunk text exactly as appended (possibly tail-trimmed by retention). */ + text: string + /** Stream label, when the producer supplied one. */ + channel?: JobChannel + /** Producer-reported loss immediately before this chunk. */ + gapBefore?: true +} +``` + +```ts type-equiv +/** Result of one non-consuming {@link JobRegistry.readRecord}. */ +interface JobRecordRead { + /** Retained chunks overlapping `[from, total)`, in offset order. */ + chunks: readonly JobRecordChunk[] + /** + * Offset to resume from — the record's current `outputTotal`. Always a + * chunk boundary: appends land whole and trimming only advances chunk + * starts, and consumers concatenate `chunks` under that assumption, so a + * provider serving partial chunks would silently duplicate text. + */ + next: number + /** True when `from` fell below the oldest retained byte, so bytes are missing before `chunks`. */ + lossy: boolean +} +``` + ## Consumer views Snapshots are fresh read-only projections. `ownerSession` carries the shared `SessionId` used for authorization; completion listeners separately receive the exact owner object used for lifecycle cleanup. `reported` suppresses a completion notice after another reporter has delivered or committed to deliver the terminal state, including the teardown cancel that drains an owner or the service. @@ -121,7 +201,10 @@ interface JobSnapshot { ownerSession?: SessionId /** Current lifecycle state. */ status: JobStatus - /** Kind-specific status detail, present once the producer supplied one (usually terminal). */ + /** + * Kind-specific status detail: live progress while the producer updates it + * through {@link RunningJob.updateDetail}, the terminal detail once settled. + */ detail?: string /** Epoch ms when the job was registered. */ startedAt: number @@ -135,6 +218,17 @@ interface JobSnapshot { * otherwise spend a model request per teardown layer. */ reported: boolean + /** + * Total UTF-8 bytes ever appended to the record — the offset the next chunk + * starts at. Present exactly when the job declared {@link JobStart.record}. + */ + outputTotal?: number + /** + * Offset of the oldest retained record byte. Greater than zero exactly when + * retention dropped the head; a reader starting below it gets a lossy read. + * Present exactly when the job declared {@link JobStart.record}. + */ + outputEarliest?: number } ``` @@ -154,7 +248,7 @@ interface JobRead { ## Service behavior -The abstract [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition specifies atomic `start`, caller-scoped `get` and `list`, `read`, `kill`, bounded `wait`, failure-isolated `onJobDone` and `onJobsChanged` listeners, and `attachController`; [`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) is the process-local Service Provider. Authorization compares owner sessions; owner cleanup and admission use the exact registered `Agent` instance. The local provider's positive-safe-integer `maxConcurrentJobsPerOwner` config defaults to `10` and counts `running` plus `stopping` records per exact owner, with one shared bucket for unowned jobs; terminal producer settlement releases capacity. See [`dsh-jobs`](../../packages/jobs/jobs/README.md) for the Service Definition contract, [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.md) for the registry lifecycle and admission policy, and [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.md) for the model-facing Consumer. +The abstract [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition specifies atomic `start`, caller-scoped `get` and `list`, `read`, non-consuming `readRecord`, `kill`, bounded `wait`, failure-isolated `onJobDone`, `onJobsChanged`, and `onOutput` listeners, and `attachController`; [`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) is the process-local Service Provider. Authorization compares owner sessions; owner cleanup and admission use the exact registered `Agent` instance. The local provider's positive-safe-integer `maxConcurrentJobsPerOwner` config defaults to `10` and counts `running` plus `stopping` records per exact owner, with one shared bucket for unowned jobs; terminal producer settlement releases capacity, and `retainBytes` (default 262144) with `settledRetainBytes` (default 16384) bound each declared record's live and settled retention. See [`dsh-jobs`](../../packages/jobs/jobs/README.md) for the Service Definition contract, [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.md) for the registry lifecycle and admission policy, and [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.md) for the model-facing Consumer. @@ -176,6 +270,8 @@ Implementations must honor these semantics: - Owned-job access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary. - Settlement is first-wins: one terminal record, released waiters, and one round of contained listener notification, even against a late producer outcome. Completion is announced last, after the record is committed and every other observer of the settlement has seen it, because a reporter may open a model turn synchronously. - start refuses work while no attached job controller serves the spec's owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and completion-listener delivery — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition's scope serve exactly the agents composed under it. +- Record observation never consumes. Any number of readRecord readers hold their own absolute byte offsets; a record read changes no cursor and no notice state, so the model-facing surfaces (the consuming read, completion notices) are unaffected. +- Record retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement — the producer outcome, a kill, or teardown — trims retention to the settled cap and ends the stream; the record has no separate lifecycle. ```ts cordis-catalog /** @@ -274,6 +370,31 @@ abstract onJobDone(listener: JobDoneListener): () => void */ abstract onJobsChanged(listener: JobsChangedListener): () => void +/** + * Read retained record output from an absolute byte offset without consuming + * it. Resume by passing a previous read's `next`; a foreign offset inside a + * retained chunk returns that whole chunk (its `at` may precede `from`). + * Never marks the job reported. Throws for an unknown or foreign job, a job + * without a {@link JobStart.record} declaration, or a negative or + * non-integer offset. + * @param id - job to read. + * @param from - absolute byte offset to read from (0 for the retained head). + * @param caller - reading agent checked against the owner. + * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. + */ +abstract readRecord(id: JobId, from: number, caller?: Agent): JobRecordRead + +/** + * Register an effect-scoped observer of record advancement — one signal per + * committed append and one at settlement, carrying only the job id. A + * consumer schedules a {@link readRecord} from its own cursor; the registry + * never pushes payloads. Delivery is owner-relative on the same terms as + * {@link onJobsChanged}. Listeners are contained and never awaited. + * @param listener - receives the id whose record advanced. + * @returns disposer that unregisters the listener. + */ +abstract onOutput(listener: JobOutputListener): () => void + /** * Attach an effect-scoped controller that can read and stop jobs. It serves the * owners its registering context's scope covers, and {@link start} refuses an diff --git a/docs/subsystems/jobs.zh.md b/docs/subsystems/jobs.zh.md index 9dc390eb30..5928c640c4 100644 --- a/docs/subsystems/jobs.zh.md +++ b/docs/subsystems/jobs.zh.md @@ -176,6 +176,8 @@ Implementations must honor these semantics: - Owned-job access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary. - Settlement is first-wins: one terminal record, released waiters, and one round of contained listener notification, even against a late producer outcome. Completion is announced last, after the record is committed and every other observer of the settlement has seen it, because a reporter may open a model turn synchronously. - start refuses work while no attached job controller serves the spec's owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and completion-listener delivery — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition's scope serve exactly the agents composed under it. +- Record observation never consumes. Any number of readRecord readers hold their own absolute byte offsets; a record read changes no cursor and no notice state, so the model-facing surfaces (the consuming read, completion notices) are unaffected. +- Record retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement — the producer outcome, a kill, or teardown — trims retention to the settled cap and ends the stream; the record has no separate lifecycle. ```ts cordis-catalog /** @@ -274,6 +276,31 @@ abstract onJobDone(listener: JobDoneListener): () => void */ abstract onJobsChanged(listener: JobsChangedListener): () => void +/** + * Read retained record output from an absolute byte offset without consuming + * it. Resume by passing a previous read's `next`; a foreign offset inside a + * retained chunk returns that whole chunk (its `at` may precede `from`). + * Never marks the job reported. Throws for an unknown or foreign job, a job + * without a {@link JobStart.record} declaration, or a negative or + * non-integer offset. + * @param id - job to read. + * @param from - absolute byte offset to read from (0 for the retained head). + * @param caller - reading agent checked against the owner. + * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. + */ +abstract readRecord(id: JobId, from: number, caller?: Agent): JobRecordRead + +/** + * Register an effect-scoped observer of record advancement — one signal per + * committed append and one at settlement, carrying only the job id. A + * consumer schedules a {@link readRecord} from its own cursor; the registry + * never pushes payloads. Delivery is owner-relative on the same terms as + * {@link onJobsChanged}. Listeners are contained and never awaited. + * @param listener - receives the id whose record advanced. + * @returns disposer that unregisters the listener. + */ +abstract onOutput(listener: JobOutputListener): () => void + /** * Attach an effect-scoped controller that can read and stop jobs. It serves the * owners its registering context's scope covers, and {@link start} refuses an diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml index 8ad0ddf475..3ec8288309 100644 --- a/docs/subsystems/session.i18n.yaml +++ b/docs/subsystems/session.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 docs/subsystems/session.md -session.md: d35395fb80a6558e15b82cdb76559f59e492f425 -session.zh.md: d3bc750b5c198e38efa94c88f95dcb9406c9059b +session.md: da62600efed8b0cd5bb134fd664582634eb0d2c3 +session.zh.md: 448d173d694d17afc9e03cd689ae07a1369b155c diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md index d35395fb80..da62600efe 100644 --- a/docs/subsystems/session.md +++ b/docs/subsystems/session.md @@ -740,6 +740,18 @@ inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<{ meta: SessionH * @returns one complete baseline followed by live replacement frames. */ @Remote({ mode: 'stream' }) control(signal: AbortSignal): AsyncIterable + +/** + * Stream one job's retained record output from an absolute byte offset, + * then its terminal status once settled and drained. Non-consuming: the + * model-facing cursor and notice state never observe these reads. The + * request's session resolves the fenced-read caller; the registry rejects a + * job the session does not own, a job without a record, or an unknown job. + * @param request - target job, owning session, and optional resume offset. + * @param signal - cancellation owned by the Remote stream carrier. + * @returns anchor, coalesced output frames, and the terminal status. + */ +@Remote({ mode: 'stream' }) observeJob(request: SessionObserveJobRequest, signal: AbortSignal): AsyncIterable ``` Types: [SessionHeader](persistence.md) · [SessionId](core.md) · [SessionSearchRequest](session-query.md) diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md index d3bc750b5c..448d173d69 100644 --- a/docs/subsystems/session.zh.md +++ b/docs/subsystems/session.zh.md @@ -744,6 +744,18 @@ inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<{ meta: SessionH * @returns one complete baseline followed by live replacement frames. */ @Remote({ mode: 'stream' }) control(signal: AbortSignal): AsyncIterable + +/** + * Stream one job's retained record output from an absolute byte offset, + * then its terminal status once settled and drained. Non-consuming: the + * model-facing cursor and notice state never observe these reads. The + * request's session resolves the fenced-read caller; the registry rejects a + * job the session does not own, a job without a record, or an unknown job. + * @param request - target job, owning session, and optional resume offset. + * @param signal - cancellation owned by the Remote stream carrier. + * @returns anchor, coalesced output frames, and the terminal status. + */ +@Remote({ mode: 'stream' }) observeJob(request: SessionObserveJobRequest, signal: AbortSignal): AsyncIterable ``` Types: [SessionHeader](persistence.zh.md) · [SessionId](core.zh.md) · [SessionSearchRequest](session-query.zh.md) diff --git a/packages/activity/README.i18n.yaml b/packages/activity/README.i18n.yaml deleted file mode 100644 index 3030bc2d1d..0000000000 --- a/packages/activity/README.i18n.yaml +++ /dev/null @@ -1,6 +0,0 @@ -# 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 packages/activity/README.md -README.md: bc9e67703b2888048eacd3a8e060aaa739948eac -README.zh.md: 26f339b8f262b90001355b690f736e2d1089cab5 diff --git a/packages/activity/README.md b/packages/activity/README.md deleted file mode 100644 index bc9e67703b..0000000000 --- a/packages/activity/README.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -description: "The activity package group: the non-consuming live-output observation plane under packages/activity/, for readers choosing or navigating the family." -kind: "package-group" ---- - -# activity/ — streaming-output observation family - -English | [中文](README.zh.md) - -## Summary - -This family lets any number of independent observers watch a long-running producer's live output without touching the model-facing paths: an activity is an append-only bounded output stream plus live status, read at absolute byte offsets that survive eviction. `activity` defines the registry contract and vocabulary; `activity-local` implements the in-memory ring-buffer registry. The plane is optional and invisible to the model — a composition without it loses only live observation. - -## Table of Contents - -- [Packages](#packages) -- [Related documentation](#related-documentation) -- [Dev Note](#dev-note) - ------ - - -## Packages - -The Service Definition and its local implementation: - -| Package | Role | ctx key | -|---|---|---| -| [`activity/`](activity/README.md) | Defines the observation registry and vocabulary | `ctx.activities` | -| [`activity-local/`](activity-local/README.md) | Implements the in-memory ring-buffer registry | registers on `ctx.activities` | - - -## Related documentation - -- [`dsh-api-activity-controller`](../api/activity-controller/README.md) — the Web transport and client model over this plane. -- [`dsh-client-ui-activity`](../client/ui-activity/README.md) — the session-header task list rendering it. -- [docs/subsystems/activity.md](../../docs/subsystems/activity.md) — the subsystem reference: offsets, retention, listener delivery. -- [Activity observation seam Agent Note](../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md) — the design decision; background bash/pwsh and the workflow tool are the shipped producers. - - -## Dev Note - -None. diff --git a/packages/activity/README.zh.md b/packages/activity/README.zh.md deleted file mode 100644 index 26f339b8f2..0000000000 --- a/packages/activity/README.zh.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -description: "activity 包组:packages/activity/ 下的非消费实时输出观察面,供选择或导航该家族的读者使用。" -kind: "package-group" ---- - -# activity/ — 流式输出观察家族 - -[English](README.md) | 中文 - -## 概述 - -这个家族让任意数量的独立观察者在不触碰模型可见路径的前提下观看长时运行生产者的实时输出:一个 activity 是一条只追加、有界的输出流加实时状态,以跨淘汰仍有效的绝对字节偏移读取。`activity` 定义注册表契约与词汇;`activity-local` 实现内存环形缓冲注册表。该观察面是可选的且对模型不可见——没有它的组合只失去实时观察。 - -## 目录 - -- [包](#packages) -- [相关文档](#related-documentation) -- [开发备注](#dev-note) - ------ - - -## 包 - -Service Definition 与其本地实现: - -| 包 | 角色 | ctx 键 | -|---|---|---| -| [`activity/`](activity/README.zh.md) | 定义观察注册表与词汇 | `ctx.activities` | -| [`activity-local/`](activity-local/README.zh.md) | 实现内存环形缓冲注册表 | 注册在 `ctx.activities` | - - -## 相关文档 - -- [`dsh-api-activity-controller`](../api/activity-controller/README.zh.md)——架在该面之上的 Web 传输与客户端模型。 -- [`dsh-client-ui-activity`](../client/ui-activity/README.zh.md)——渲染它的会话头部任务列表。 -- [docs/subsystems/activity.md](../../docs/subsystems/activity.zh.md)——子系统参考:偏移、留存、监听器投递。 -- [activity 观察面 Agent Note](../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md)——设计决策;后台 bash/pwsh 与 workflow 工具是已交付的生产者。 - - -## 开发备注 - -无。 diff --git a/packages/activity/activity-local/README.i18n.yaml b/packages/activity/activity-local/README.i18n.yaml deleted file mode 100644 index 9487171fa8..0000000000 --- a/packages/activity/activity-local/README.i18n.yaml +++ /dev/null @@ -1,6 +0,0 @@ -# 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 packages/activity/activity-local/README.md -README.md: ef010e1fe859d2ffd56d736b24e490d73bbb49a5 -README.zh.md: 7d9779fc64e7e7d6e47e3a2e78fb80ca097abb6c diff --git a/packages/activity/activity-local/README.md b/packages/activity/activity-local/README.md deleted file mode 100644 index ef010e1fe8..0000000000 --- a/packages/activity/activity-local/README.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -description: "The in-memory activity registry: configurable ring-buffer retention (retainBytes, settledRetainBytes), absolute offsets across eviction, owner-scoped cleanup, and layered listener delivery for live-output observation." -kind: "package-reference" ---- - -# @deepseek-ai/dsh-activity-local - -English | [中文](README.zh.md) - -## Summary - -`dsh-activity-local` makes `ctx.activities` real: mount its one row and every producer's live output is retained in a bounded in-process ring readers address by absolute byte offsets, with fresh snapshots and chunk copies handed out — never live state. Retention is configurable per deployment, records outlive their producer fibers, and owner disposal cleans up exactly the disposed session's rows. Choose it for the single-Host web deployment this repository ships; durable or cross-process observation needs a different provider. - -## Table of Contents - -- [Use this package](#use-this-package) -- [Understand the implementation](#understand-the-implementation) -- [Further Exploration](#further-exploration) -- [Model Experience](#model-experience) -- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work) -- [Dev Note](#dev-note) - ------ - - -## Use this package - -Mount one `cordis.yml` row (`name: '@deepseek-ai/dsh-activity-local'`) beside `dsh-agent`; producers and consumers then reach the registry as `ctx.activities`. - -### Retention - -Each activity retains a chunk ring whose offsets stay absolute across eviction: dropping the head advances `outputEarliest`, and a single chunk larger than the live cap keeps only its UTF-8-safe tail with a `gapBefore` marker. Settlement trims the ring to the settled cap so a finished activity still shows its tail without holding the live budget. - -| Config | Default | Meaning | -|---|---|---| -| `retainBytes` | `262144` | Live output retention per activity, in UTF-8 bytes. | -| `settledRetainBytes` | `16384` | Retention kept after an activity settles. | - -The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-activity-local) is the exhaustive source for every accepted field. - -### Lifecycle - -Records outlive producer fibers. The first activity for an owner attaches one cleanup to the exact `Agent` scope; owner disposal ends still-open records (`killed`, `owner disposed`) and removes them, announcing the removal. Service disposal ends everything, clears the store, and announces each emptied owner. Neither awaits a producer — the registry owns no execution resource. - ------ - - -## Understand the implementation - -
        -Implementation internals — click to expand - -One process-wide `LocalActivityRegistry` keeps a map of tracked records, each holding its chunk ring and cursor facts. Listeners are layered by registration scope exactly like the jobs registry, so delivery stays owner-relative in one instance, and every listener is contained. Trimming walks whole chunks and only tail-cuts a single oversized chunk on a UTF-8 boundary. - -| File | Role | -|---|---| -| [`src/index.ts`](src/index.ts) | The registry: rings, retention, fencing, scoped listener layers, disposal | -| [`src/invariant.ts`](src/invariant.ts) | Package invariant companion | - -
        - ------ - - -## Further Exploration - -- [`dsh-activity`](../activity/README.md) — the contract this provider implements. -- [docs/subsystems/activity.md](../../../docs/subsystems/activity.md) — offsets, retention, and delivery in one reference. -- [`dsh-api-activity-controller`](../../api/activity-controller/README.md) — the Remote streams reading this registry. - ------ - - -## Model Experience - -None, as the provider stores and serves observation state only; the producers own every model-visible surface. - -#### KV Cache effect - -None; the package never assembles or alters provider requests. - -## Known Limitations and Deferred Work - - - -These limits define when the provider is a poor fit. They are current package constraints, not a task backlog. - -- **The unowned bucket has no admission bound** — owned producers are already bounded by the jobs admission policy, but a plugin opening many unowned activities grows the store until service disposal. - - -### Dev Note - -
        -Working context for maintainers — click to expand - -None. - -
        diff --git a/packages/activity/activity-local/README.zh.md b/packages/activity/activity-local/README.zh.md deleted file mode 100644 index 7d9779fc64..0000000000 --- a/packages/activity/activity-local/README.zh.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -description: "内存 activity 注册表:可配置的环形缓冲留存(retainBytes、settledRetainBytes)、跨淘汰的绝对偏移、按 owner 作用域的清理,以及实时输出观察的分层监听器投递。" -kind: "package-reference" ---- - -# @deepseek-ai/dsh-activity-local - -[English](README.md) | 中文 - -## 概述 - -`dsh-activity-local` 让 `ctx.activities` 落地:挂载它的一行后,每个生产者的实时输出保留在有界的进程内环里,读者以绝对字节偏移寻址,拿到的是新鲜快照与 chunk 拷贝——从不是活状态。留存按部署可配置,记录比生产者 fiber 活得久,owner 释放只清理被释放会话的行。为本仓库交付的单 Host web 部署选择它;持久或跨进程观察需要别的 provider。 - -## 目录 - -- [使用本包](#use-this-package) -- [理解实现](#understand-the-implementation) -- [进一步探索](#further-exploration) -- [模型体验](#model-experience) -- [已知限制与延期工作](#known-limitations-and-deferred-work) -- [开发备注](#dev-note) - ------ - - -## 使用本包 - -在 `dsh-agent` 旁挂载一行 `cordis.yml`(`name: '@deepseek-ai/dsh-activity-local'`);生产者与消费者随即以 `ctx.activities` 触达注册表。 - -### 留存 - -每个 activity 保留一个偏移跨淘汰仍绝对的 chunk 环:丢弃头部会前移 `outputEarliest`,单个超过活跃上限的 chunk 只保留 UTF-8 安全的尾部并带 `gapBefore` 标记。结算把环裁到 settled 上限,让完成的 activity 仍展示尾部而不占活跃预算。 - -| 配置 | 默认 | 含义 | -|---|---|---| -| `retainBytes` | `262144` | 每个 activity 的活跃输出留存,UTF-8 字节。 | -| `settledRetainBytes` | `16384` | activity 结算后保留的留存量。 | - -生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-activity-local)是每个可接受字段的穷尽来源。 - -### 生命周期 - -记录比生产者 fiber 活得久。owner 的第一个 activity 在确切的 `Agent` 作用域上挂一个清理;owner 释放会终结仍开放的记录(`killed`、`owner disposed`)并移除它们、announce 该移除。服务释放终结一切、清空存储并 announce 每个被清空的 owner。两者都不等待生产者——注册表不拥有任何执行资源。 - ------ - - -## 理解实现 - -
        -实现内幕——点击展开 - -一个进程级 `LocalActivityRegistry` 维护被跟踪记录的 map,每条持有自己的 chunk 环与游标事实。监听器按注册作用域分层,与 jobs 注册表完全一致,投递在单实例内保持 owner 相对,且每个监听器都被包住。裁剪按整 chunk 走,只对单个超大 chunk 在 UTF-8 边界上做尾部截取。 - -| 文件 | 角色 | -|---|---| -| [`src/index.ts`](src/index.ts) | 注册表:环、留存、栅栏、作用域监听层、释放 | -| [`src/invariant.ts`](src/invariant.ts) | 包不变式伴生 | - -
        - ------ - - -## 进一步探索 - -- [`dsh-activity`](../activity/README.zh.md)——本 provider 实现的契约。 -- [docs/subsystems/activity.md](../../../docs/subsystems/activity.zh.md)——偏移、留存与投递的单一参考。 -- [`dsh-api-activity-controller`](../../api/activity-controller/README.zh.md)——读取本注册表的 Remote 流。 - ------ - - -## 模型体验 - -无:provider 只存储与提供观察状态;模型可见表面全部归生产者所有。 - -#### KV Cache 影响 - -无;本包从不组装或改动 provider 请求。 - -## 已知限制与延期工作 - - - -这些限制说明该 provider 何时不合适。它们是当前包约束,不是任务积压。 - -- **无主桶没有准入上限**——有主生产者已受 jobs 准入策略约束,但打开大量无主 activity 的插件会让存储一直增长到服务释放。 - - -### 开发备注 - -
        -维护者的工作上下文——点击展开 - -无。 - -
        diff --git a/packages/activity/activity-local/package.json b/packages/activity/activity-local/package.json deleted file mode 100644 index d3b08606ce..0000000000 --- a/packages/activity/activity-local/package.json +++ /dev/null @@ -1,55 +0,0 @@ -{ - "name": "@deepseek-ai/dsh-activity-local", - "description": "Process-local implementation of the DeepSeek Harness streaming-output observation seam", - "version": "0.1.2-alpha.2", - "publishConfig": { - "access": "public" - }, - "repository": { - "type": "git", - "url": "git+https://github.com/deepseek-ai/deepseek-harness.git", - "directory": "packages/activity/activity-local" - }, - "type": "module", - "main": "lib/index.js", - "types": "lib/types/index.d.ts", - "exports": { - ".": { - "types": "./lib/types/index.d.ts", - "default": "./lib/index.js" - }, - "./invariant": { - "types": "./lib/types/invariant.d.ts", - "default": "./lib/invariant.js" - }, - "./src/*": "./src/*", - "./package.json": "./package.json" - }, - "files": [ - "lib/index.js", - "lib/invariant.js", - "lib/types/**/*.d.ts" - ], - "license": "MIT", - "peerDependencies": { - "@deepseek-ai/dsh-agent": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-activity": "workspace:^", - "@deepseek-ai/dsh-scope": "workspace:^", - "@deepseek-ai/cordis": "workspace:^" - }, - "dependencies": { - "@deepseek-ai/schemastery": "workspace:^" - }, - "devDependencies": { - "@deepseek-ai/cordis-plugin-include": "workspace:^", - "@deepseek-ai/cordis-plugin-loader": "workspace:^", - "@deepseek-ai/dsh-agent": "workspace:^", - "@deepseek-ai/dsh-brand": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-activity": "workspace:^", - "@deepseek-ai/dsh-scope": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/cordis": "workspace:^" - } -} diff --git a/packages/activity/activity-local/src/index.ts b/packages/activity/activity-local/src/index.ts deleted file mode 100644 index caabb5499e..0000000000 --- a/packages/activity/activity-local/src/index.ts +++ /dev/null @@ -1,438 +0,0 @@ -/** - * Process-local provider for the streaming-output observation seam - * (`ctx.activities`). It keeps every record and its bounded output ring in - * memory and hands out fresh snapshots and chunk copies, never live state. - * - * Records outlive producer fibers. Owner disposal ends still-open records and - * removes them; service disposal ends and clears everything. Neither awaits a - * producer — the registry owns no execution resource. - * @module @deepseek-ai/dsh-activity-local - */ - -import { Context } from '@deepseek-ai/cordis' -import z from '@deepseek-ai/schemastery' -import type { Agent } from '@deepseek-ai/dsh-agent' -import { AnonymousEntries, ScopedLayers, scopeOf } from '@deepseek-ai/dsh-scope' -import type { ScopeLayer } from '@deepseek-ai/dsh-scope' -import { ActivityRegistry, ActivityId } from '@deepseek-ai/dsh-activity' -import type { - ActivityAppendOptions, ActivityChannel, ActivityCorrelation, ActivitiesChangedListener, - ActivityHandle, ActivityKind, ActivityOpen, ActivityOutcome, ActivityOutputChunk, - ActivityOutputListener, ActivityRead, ActivitySnapshot, ActivityStatus, -} from '@deepseek-ai/dsh-activity' - -/** Default live retention per activity, in UTF-8 bytes. */ -const DEFAULT_RETAIN_BYTES = 256 * 1024 - -/** Default retention kept after settlement, in UTF-8 bytes. */ -const DEFAULT_SETTLED_RETAIN_BYTES = 16 * 1024 - -/** Configuration for the process-local observation registry. */ -export interface Config { - /** Live output retention per activity in UTF-8 bytes; omission defaults to 262144. */ - retainBytes?: number - /** Output retention kept after an activity settles, in UTF-8 bytes; omission defaults to 16384. */ - settledRetainBytes?: number -} - -/** The registry's mutable per-activity record (never handed out — see {@link LocalActivityRegistry.snapshot}). */ -interface TrackedActivity { - id: ActivityId - kind: ActivityKind - label: string - /** Exact lifecycle owner; session-id visibility is derived from it. */ - owner: Agent | undefined - correlation: ActivityCorrelation | undefined - status: ActivityStatus - detail: string | undefined - startedAt: number - finishedAt: number | undefined - /** Retained chunks in offset order; offsets stay absolute across eviction. */ - chunks: RingChunk[] - /** Sum of the retained chunks' byte lengths. */ - retainedBytes: number - /** Total UTF-8 bytes ever appended. */ - total: number - /** Offset of the oldest retained byte (equals {@link total} when nothing is retained). */ - earliest: number -} - -/** One retained ring entry; `bytes` caches the chunk's UTF-8 length. */ -interface RingChunk { - at: number - text: string - bytes: number - channel?: ActivityChannel - gapBefore?: true -} - -/** True for the three terminal {@link ActivityStatus} values. */ -function isTerminal(status: ActivityStatus): boolean { - return status === 'completed' || status === 'failed' || status === 'killed' -} - -/** - * The UTF-8-safe tail of `text` no longer than `maxBytes`: the byte cut - * advances past continuation bytes so the surviving text never starts inside - * a code point. - * @param text - the oversized chunk text. - * @param maxBytes - positive byte budget for the surviving tail. - * @returns the surviving tail and its exact byte length. - */ -function utf8Tail(text: string, maxBytes: number): { text: string; bytes: number } { - const raw = Buffer.from(text, 'utf8') - let start = raw.length - maxBytes - // The loop bound proves the index is in range; the assertion only - // discharges noUncheckedIndexedAccess. - while (start < raw.length && ((raw[start] as number) & 0xC0) === 0x80) start += 1 - const tail = raw.subarray(start) - return { text: tail.toString('utf8'), bytes: tail.length } -} - -/** - * One scope's observer contributions. Both tables are anonymous because a - * contribution is identified by its own disposer, never by a name a second - * registrant could shadow. - */ -class ActivityLayer implements ScopeLayer { - readonly changed = new AnonymousEntries() - readonly output = new AnonymousEntries() - - isEmpty(): boolean { - return this.changed.isEmpty() && this.output.isEmpty() - } -} - -/** - * The in-memory `activities` registry. See the Service Definition contract in - * `@deepseek-ai/dsh-activity` for the observation, retention, and lifecycle - * semantics this implementation honors. - */ -export class LocalActivityRegistry extends ActivityRegistry { - static Config: z = z.object({ - retainBytes: z.number() - .step(1) - .min(1) - .max(Number.MAX_SAFE_INTEGER) - .default(DEFAULT_RETAIN_BYTES), - settledRetainBytes: z.number() - .step(1) - .min(1) - .max(Number.MAX_SAFE_INTEGER) - .default(DEFAULT_SETTLED_RETAIN_BYTES), - }) - - /** Schemastery-defaulted live retention cap. */ - private readonly retainBytes: number - /** Schemastery-defaulted settled retention cap. */ - private readonly settledRetainBytes: number - private store = new Map() - private counters = new Map() - /** - * Observers layered by the scope that registered them, in the jobs-registry - * shape: a contribution files into its registering context's scope, and a - * dispatch unions the global layer with the subject owner's scope chain, so - * delivery stays owner-relative in one process-wide registry. Nothing - * derives a cache from a layer, so change notification is a no-op. - */ - private readonly layers = new ScopedLayers(() => new ActivityLayer(), () => {}) - /** Owner agents with attached scope cleanup, mapped to the exact disposer. */ - private ownerCleanups = new Map Promise | void>() - /** Service context used by contained listener reporting and teardown. */ - private readonly selfCtx: Context - - constructor(ctx: Context, config: Config) { - super(ctx) - // Schemastery validates and fills the defaults before constructing the service. - this.retainBytes = (config as Required).retainBytes - this.settledRetainBytes = (config as Required).settledRetainBytes - this.selfCtx = ctx - ctx.effect(() => () => { this.disposeAll() }, 'activities teardown') - } - - open(spec: ActivityOpen): ActivityHandle { - if (spec.kind.length === 0) throw new Error('invalid activity kind: expected a non-empty string') - if (spec.label.length === 0) throw new Error('invalid activity label: expected a non-empty string') - if (spec.owner !== undefined) this.ensureOwnerCleanup(spec.owner) - - const count = (this.counters.get(spec.kind) ?? 0) + 1 - this.counters.set(spec.kind, count) - const id = ActivityId(`${spec.kind}-${count}`) - const record: TrackedActivity = { - id, - kind: spec.kind, - label: spec.label, - owner: spec.owner, - correlation: spec.correlation === undefined ? undefined : { ...spec.correlation }, - status: 'running', - detail: undefined, - startedAt: Date.now(), - finishedAt: undefined, - chunks: [], - retainedBytes: 0, - total: 0, - earliest: 0, - } - this.store.set(id, record) - // Registration is complete and cannot fail from here, so the visible set - // has genuinely changed. - this.notifyChanged(record.owner) - return { - id, - append: (text, options) => { this.append(record, text, options) }, - updateDetail: (detail) => { this.updateDetail(record, detail) }, - end: (outcome) => { this.settle(record, outcome) }, - } - } - - list(caller?: Agent): ActivitySnapshot[] { - const session = caller?.id - return [...this.store.values()] - .filter(record => record.owner === undefined || record.owner.id === session) - .map(record => this.snapshot(record)) - } - - get(id: ActivityId, caller?: Agent): ActivitySnapshot { - const record = this.expect(id) - this.assertAccess(record, caller) - return this.snapshot(record) - } - - read(id: ActivityId, from: number, caller?: Agent): ActivityRead { - const record = this.expect(id) - this.assertAccess(record, caller) - if (!Number.isSafeInteger(from) || from < 0) { - throw new Error(`invalid read offset: expected a non-negative safe integer, got ${JSON.stringify(from)}`) - } - const chunks: ActivityOutputChunk[] = [] - for (const chunk of record.chunks) { - if (chunk.at + chunk.bytes <= from) continue - chunks.push({ - at: chunk.at, - text: chunk.text, - ...chunk.channel !== undefined ? { channel: chunk.channel } : {}, - ...chunk.gapBefore !== undefined ? { gapBefore: chunk.gapBefore } : {}, - }) - } - return { chunks, next: record.total, lossy: from < record.earliest } - } - - onActivitiesChanged(listener: ActivitiesChangedListener): () => void { - return this.layers.effect( - this.ctx, - layer => layer.changed.append(listener), - { label: 'activities.onActivitiesChanged()' }, - ) - } - - onOutput(listener: ActivityOutputListener): () => void { - return this.layers.effect( - this.ctx, - layer => layer.output.append(listener), - { label: 'activities.onOutput()' }, - ) - } - - /** Append one chunk to a live record; log and drop on an ended one. */ - private append(record: TrackedActivity, text: string, options?: ActivityAppendOptions): void { - if (isTerminal(record.status)) { - this.selfCtx.logger.warn(`activities: append to ended activity ${record.id} dropped`) - return - } - if (text.length === 0) return - const bytes = Buffer.byteLength(text, 'utf8') - record.chunks.push({ - at: record.total, - text, - bytes, - ...options?.channel !== undefined ? { channel: options.channel } : {}, - ...options?.gapBefore !== undefined ? { gapBefore: options.gapBefore } : {}, - }) - record.total += bytes - record.retainedBytes += bytes - this.trim(record, this.retainBytes) - this.notifyOutput(record) - } - - /** Replace a live record's detail line; log and drop on an ended one. */ - private updateDetail(record: TrackedActivity, detail: string): void { - if (isTerminal(record.status)) { - this.selfCtx.logger.warn(`activities: detail update on ended activity ${record.id} dropped`) - return - } - record.detail = detail - this.notifyChanged(record.owner) - } - - /** - * Record the first terminal outcome, trim retention to the settled cap, and - * announce the change and the stream end. First-wins: a later call — the - * producer's own report after a teardown force-end, or a duplicate — is - * dropped silently. - */ - private settle(record: TrackedActivity, outcome: ActivityOutcome): void { - if (isTerminal(record.status)) return - record.status = outcome.status - if (outcome.detail !== undefined) record.detail = outcome.detail - record.finishedAt = Date.now() - this.trim(record, this.settledRetainBytes) - this.notifyChanged(record.owner) - this.notifyOutput(record) - } - - /** - * Drop retained head chunks until the ring fits `cap`; a single oversized - * chunk keeps only its UTF-8-safe tail with a `gapBefore` marker. Offsets - * stay absolute: `earliest` advances over everything dropped. - */ - private trim(record: TrackedActivity, cap: number): void { - while (record.retainedBytes > cap && record.chunks.length > 1) { - const dropped = record.chunks.shift() - /* v8 ignore next -- the length guard proves shift() returns a chunk; the check only satisfies noUncheckedIndexedAccess. */ - if (dropped === undefined) break - record.retainedBytes -= dropped.bytes - } - const single = record.chunks.length === 1 ? record.chunks[0] : undefined - if (single !== undefined && single.bytes > cap) { - const tail = utf8Tail(single.text, cap) - single.at += single.bytes - tail.bytes - single.text = tail.text - single.bytes = tail.bytes - single.gapBefore = true - record.retainedBytes = tail.bytes - } - record.earliest = record.chunks[0]?.at ?? record.total - } - - /** Look up an activity or fail loud. */ - private expect(id: ActivityId): TrackedActivity { - const record = this.store.get(id) - if (record === undefined) throw new Error(`unknown activity ${id}`) - return record - } - - /** - * The visibility fence: an activity with an owner is reachable only by - * callers whose session id matches (`!== undefined` semantics — an unowned - * activity is open, and a no-agent caller can never match an owned one). - */ - private assertAccess(record: TrackedActivity, caller?: Agent): void { - if (record.owner !== undefined && record.owner.id !== caller?.id) { - throw new Error(`activity ${record.id} belongs to another session`) - } - } - - /** Project a fresh read-only snapshot from the mutable record. */ - private snapshot(record: TrackedActivity): ActivitySnapshot { - const ownerSession = record.owner?.id - return { - id: record.id, - kind: record.kind, - label: record.label, - ...ownerSession !== undefined ? { ownerSession } : {}, - ...record.correlation !== undefined ? { correlation: { ...record.correlation } } : {}, - status: record.status, - ...record.detail !== undefined ? { detail: record.detail } : {}, - startedAt: record.startedAt, - ...record.finishedAt !== undefined ? { finishedAt: record.finishedAt } : {}, - outputTotal: record.total, - outputEarliest: record.earliest, - } - } - - /** - * The change observers that own `owner`'s updates: the global layer — a - * host composition's own carrier, which serves every owner — then each - * scoped layer along the owner's chain. - */ - private *changedFor(owner?: Agent): IterableIterator { - yield* this.layers.global.changed.values() - const scope = owner === undefined ? undefined : scopeOf(owner.ctx) - for (const layer of this.layers.chainLayers(scope)) yield* layer.changed.values() - } - - /** The output observers that own `owner`'s stream signals, resolved like {@link changedFor}. */ - private *outputFor(owner?: Agent): IterableIterator { - yield* this.layers.global.output.values() - const scope = owner === undefined ? undefined : scopeOf(owner.ctx) - for (const layer of this.layers.chainLayers(scope)) yield* layer.output.values() - } - - /** - * Announce that one owner's visible set changed. Each listener is contained - * so an observer cannot break a lifecycle commit that already happened. - */ - private notifyChanged(owner: Agent | undefined): void { - for (const listener of this.changedFor(owner)) { - try { - listener(owner) - } catch (error: unknown) { - this.selfCtx.logger.warn(`activities: onActivitiesChanged listener threw: ${String(error)}`) - } - } - } - - /** Announce that one activity's stream advanced (append or settlement), with per-listener containment. */ - private notifyOutput(record: TrackedActivity): void { - for (const listener of this.outputFor(record.owner)) { - try { - listener(record.id) - } catch (error: unknown) { - this.selfCtx.logger.warn(`activities: onOutput listener threw: ${String(error)}`) - } - } - } - - /** - * Attach one cleanup through the exact owner's scope. This survives - * producer reloads; the retained disposer lets service teardown detach the - * cross-fiber effect. Fails when the agent registry is absent or the owner - * is not its currently registered instance. - */ - private ensureOwnerCleanup(owner: Agent): void { - const ownerId = owner.id - const agents = this.selfCtx.get('agents') - if (agents === undefined) { - throw new Error('activity ownership requires the agent registry (load @deepseek-ai/dsh-agent)') - } - if (agents.get(ownerId) !== owner) { - throw new Error(`agent "${ownerId}" is not the registered agent instance (activity owner must be live)`) - } - if (this.ownerCleanups.has(owner)) return - // Record only after attach succeeds; a disposing scope rejects new effects. - const detach = owner.ctx.effect(() => () => { - this.ownerCleanups.delete(owner) - this.disposeOwned(owner) - }, 'activities.ownerCleanup()') - this.ownerCleanups.set(owner, detach) - } - - /** End still-open records and drop every activity owned by one exact agent lifecycle. */ - private disposeOwned(owner: Agent): void { - const owned = [...this.store.values()].filter(record => record.owner === owner) - for (const record of owned) { - if (!isTerminal(record.status)) this.settle(record, { status: 'killed', detail: 'owner disposed' }) - this.store.delete(record.id) - } - // Removal is the one visible-set change no per-activity record carries, so - // it must be announced here or an observer keeps the dropped rows forever. - if (owned.length > 0) this.notifyChanged(owner) - } - - /** End every open record, clear the store, and announce each emptied owner. */ - private disposeAll(): void { - const all = [...this.store.values()] - for (const record of all) { - if (!isTerminal(record.status)) this.settle(record, { status: 'killed', detail: 'activity registry disposed' }) - } - const emptied = new Set(all.map(record => record.owner)) - this.store.clear() - for (const owner of emptied) this.notifyChanged(owner) - // Detach cross-fiber owner effects after the shared store is quiescent. - const ownerCleanups = [...this.ownerCleanups.values()] - this.ownerCleanups.clear() - for (const cleanup of ownerCleanups) void cleanup() - } -} - -export default LocalActivityRegistry diff --git a/packages/activity/activity-local/src/invariant.ts b/packages/activity/activity-local/src/invariant.ts deleted file mode 100644 index 7e15b7db09..0000000000 --- a/packages/activity/activity-local/src/invariant.ts +++ /dev/null @@ -1,33 +0,0 @@ -/** - * Package-owned invariant companion for `@deepseek-ai/dsh-activity-local`. - * @module @deepseek-ai/dsh-activity-local/invariant - */ - -/* jscpd:ignore-start */ -import type { Context } from '@deepseek-ai/cordis' -import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants' - -const PACKAGE_NAME = '@deepseek-ai/dsh-activity-local' - -/** Cordis companion plugin name. */ -export const name = 'activity-local-invariant' -/** Service required before the companion can reserve package ownership. */ -export const inject = ['invariants'] - -/** - * No runtime invariant: `@deepseek-ai/dsh-activity/invariant` owns per-snapshot identity, status, - * timestamp, and offset checks on every visible-set change. This provider's remaining behavior — - * ring retention against private byte caps and pull-only chunk reads — has no authoritative event - * stream to observe: a read happens on a caller's schedule, and repeating the retention arithmetic - * against private configuration would duplicate the implementation rather than check a relation. - */ -const install: InvariantInstaller = () => {} - -/** - * Register this package's invariant companion. - * @param ctx - Cordis context carrying the invariant service. - * @returns the installed registration's disposer after setup succeeds. - */ -export const apply = (ctx: Context): Promise<() => void> => - Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install)) -/* jscpd:ignore-end */ diff --git a/packages/activity/activity-local/tests/activity.spec.ts b/packages/activity/activity-local/tests/activity.spec.ts deleted file mode 100644 index 557046d617..0000000000 --- a/packages/activity/activity-local/tests/activity.spec.ts +++ /dev/null @@ -1,413 +0,0 @@ -import { describe, expect, it, vi } from 'vitest' -import { Context } from '@deepseek-ai/cordis' -import { Session, SessionId } from '@deepseek-ai/dsh-session' -import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' -import type { Agent } from '@deepseek-ai/dsh-agent' -import { createScope } from '@deepseek-ai/dsh-scope' -import { ActivityId } from '@deepseek-ai/dsh-activity' -import type { ActivityHandle, ActivitySnapshot } from '@deepseek-ai/dsh-activity' -import LocalActivityRegistry, { type Config as ProcessConfig } from '@deepseek-ai/dsh-activity-local' - -declare module '@deepseek-ai/dsh-activity' { - interface ActivityKindMap { - workflow: 'workflow' - } -} - -const agentScopeDisposers = new WeakMap Promise>() - -/** - * A minimal live agent whose ctx carries its own scope on a disposable plugin - * fiber, mirroring the harness convention that a live agent keys its scope. - */ -function stubAgent(ctx: Context, rawId: string): Agent { - const id = SessionId(rawId) - const scopeFiber = ctx.plugin(() => {}) - const agentCtx = createScope(scopeFiber.ctx, {}).ctx - const session = Session.create(id) - const agent = { - id, - options: {}, - session, - inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }), - status: 'idle' as const, - ctx: agentCtx, - send: () => {}, - followup: () => {}, - steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }), - inject: () => {}, - cancel() {}, - runMaintenance: (job: (signal: AbortSignal) => Promise) => job(new AbortController().signal), - whenIdle() { return Promise.resolve() }, - } - agentScopeDisposers.set(agent, async () => { await scopeFiber.dispose() }) - return agent -} - -async function disposeAgentScope(agent: Agent): Promise { - const dispose = agentScopeDisposers.get(agent) - if (dispose === undefined) throw new Error(`missing test scope for agent "${agent.id}"`) - await dispose() -} - -async function harness(config: ProcessConfig = {}) { - const ctx = new Context() - await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalActivityRegistry, config) - return ctx -} - -/** Concatenated retained text of one process, as an observer from `from` sees it. */ -function textFrom(ctx: Context, id: ActivityId, from = 0): string { - return ctx.activities.read(id, from).chunks.map(chunk => chunk.text).join('') -} - -describe('LocalActivityRegistry.open', () => { - it('mints per-kind ordinal ids and announces the new visible row', async () => { - const ctx = await harness() - const changes: (Agent | undefined)[] = [] - ctx.activities.onActivitiesChanged((owner) => { changes.push(owner) }) - const first = ctx.activities.open({ kind: 'bash', label: 'sleep 60' }) - const second = ctx.activities.open({ kind: 'workflow', label: 'run docs' }) - const third = ctx.activities.open({ kind: 'bash', label: 'build' }) - expect([first.id, second.id, third.id]).toEqual(['bash-1', 'workflow-1', 'bash-2']) - expect(changes).toEqual([undefined, undefined, undefined]) - expect(ctx.activities.list().map(snapshot => snapshot.id)).toEqual(['bash-1', 'workflow-1', 'bash-2']) - }) - - it('rejects an empty kind or label without minting an id', async () => { - const ctx = await harness() - expect(() => ctx.activities.open({ kind: '' as never, label: 'x' })).toThrow(/invalid activity kind/) - expect(() => ctx.activities.open({ kind: 'bash', label: '' })).toThrow(/invalid activity label/) - expect(ctx.activities.list()).toEqual([]) - }) - - it('rejects an owned open when no agent registry is loaded', async () => { - const bare = new Context() - await bare.plugin(LocalActivityRegistry) - const ghost = { id: SessionId('ghost'), ctx: bare } as unknown as Agent - expect(() => bare.activities.open({ kind: 'bash', label: 'x', owner: ghost })) - .toThrow(/activity ownership requires the agent registry/) - }) - - it('rejects an owner that is not the registered agent instance', async () => { - const ctx = await harness() - const ghost = stubAgent(ctx, 'ghost') - expect(() => ctx.activities.open({ kind: 'bash', label: 'x', owner: ghost })) - .toThrow(/not the registered agent instance/) - }) - - it('carries owner session and correlation into snapshots', async () => { - const ctx = await harness() - const owner = stubAgent(ctx, 'owner') - ctx.agents.register(owner) - const handle = ctx.activities.open({ - kind: 'bash', - label: 'npm test', - owner, - correlation: { jobId: 'bash-9' as never, callId: 'call-3' as never }, - }) - const snapshot = ctx.activities.get(handle.id, owner) - expect(snapshot.ownerSession).toBe(owner.id) - expect(snapshot.correlation).toEqual({ jobId: 'bash-9', callId: 'call-3' }) - expect(snapshot.status).toBe('running') - }) -}) - -describe('LocalActivityRegistry output', () => { - it('appends advance absolute offsets and reads are non-consuming', async () => { - const ctx = await harness() - const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) - handle.append('hello ') - handle.append('world', { channel: 'stderr' }) - const first = ctx.activities.read(handle.id, 0) - expect(first.lossy).toBe(false) - expect(first.next).toBe(11) - expect(first.chunks).toEqual([ - { at: 0, text: 'hello ' }, - { at: 6, text: 'world', channel: 'stderr' }, - ]) - // A second identical read proves nothing was consumed. - expect(ctx.activities.read(handle.id, 0)).toEqual(first) - // Resuming from `next` yields nothing until more output arrives. - expect(ctx.activities.read(handle.id, first.next).chunks).toEqual([]) - handle.append('!') - expect(ctx.activities.read(handle.id, first.next).chunks).toEqual([{ at: 11, text: '!' }]) - const snapshot = ctx.activities.get(handle.id) - expect(snapshot.outputTotal).toBe(12) - expect(snapshot.outputEarliest).toBe(0) - }) - - it('drops an empty append without waking observers', async () => { - const ctx = await harness() - const signals: ActivityId[] = [] - ctx.activities.onOutput((id) => { signals.push(id) }) - const handle = ctx.activities.open({ kind: 'bash', label: 'quiet' }) - handle.append('') - expect(signals).toEqual([]) - expect(ctx.activities.get(handle.id).outputTotal).toBe(0) - }) - - it('rejects a negative or fractional read offset', async () => { - const ctx = await harness() - const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) - expect(() => ctx.activities.read(handle.id, -1)).toThrow(/invalid read offset/) - expect(() => ctx.activities.read(handle.id, 0.5)).toThrow(/invalid read offset/) - }) - - it('evicts whole head chunks past the live cap and flags stale readers lossy', async () => { - const ctx = await harness({ retainBytes: 8 }) - const handle = ctx.activities.open({ kind: 'bash', label: 'spam' }) - handle.append('aaaa') - handle.append('bbbb') - handle.append('cccc') - const read = ctx.activities.read(handle.id, 0) - expect(read.lossy).toBe(true) - expect(read.chunks).toEqual([{ at: 4, text: 'bbbb' }, { at: 8, text: 'cccc' }]) - expect(read.next).toBe(12) - const snapshot = ctx.activities.get(handle.id) - expect(snapshot.outputEarliest).toBe(4) - expect(snapshot.outputTotal).toBe(12) - // A reader at the retained boundary is not lossy. - expect(ctx.activities.read(handle.id, 4).lossy).toBe(false) - }) - - it('keeps only the UTF-8-safe tail of a single oversized chunk', async () => { - const ctx = await harness({ retainBytes: 5 }) - const handle = ctx.activities.open({ kind: 'bash', label: 'wide' }) - // '你好' is six UTF-8 bytes; a five-byte budget must not split the second code point. - handle.append('你好') - const read = ctx.activities.read(handle.id, 0) - expect(read.lossy).toBe(true) - expect(read.chunks).toEqual([{ at: 3, text: '好', gapBefore: true }]) - const snapshot = ctx.activities.get(handle.id) - expect(snapshot.outputEarliest).toBe(3) - expect(snapshot.outputTotal).toBe(6) - }) - - it('returns the whole overlapped chunk for a foreign mid-chunk offset', async () => { - const ctx = await harness() - const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) - handle.append('abcdef') - const read = ctx.activities.read(handle.id, 3) - expect(read.chunks).toEqual([{ at: 0, text: 'abcdef' }]) - expect(read.lossy).toBe(false) - }) - - it('preserves a producer-reported gap marker through reads', async () => { - const ctx = await harness() - const handle = ctx.activities.open({ kind: 'bash', label: 'lossy source' }) - handle.append('tail after drop', { gapBefore: true, channel: 'stdout' }) - expect(ctx.activities.read(handle.id, 0).chunks).toEqual([ - { at: 0, text: 'tail after drop', channel: 'stdout', gapBefore: true }, - ]) - }) -}) - -describe('LocalActivityRegistry settlement', () => { - it('records the first terminal outcome and trims retention to the settled cap', async () => { - const ctx = await harness({ retainBytes: 1024, settledRetainBytes: 4 }) - const handle = ctx.activities.open({ kind: 'bash', label: 'build' }) - handle.append('abcdefgh') - handle.end({ status: 'completed', detail: 'exit code: 0' }) - const snapshot = ctx.activities.get(handle.id) - expect(snapshot.status).toBe('completed') - expect(snapshot.detail).toBe('exit code: 0') - expect(snapshot.finishedAt).toBeDefined() - const read = ctx.activities.read(handle.id, 0) - expect(read.lossy).toBe(true) - expect(read.chunks).toEqual([{ at: 4, text: 'efgh', gapBefore: true }]) - }) - - it('is first-wins: a later end and post-end writes are dropped without throwing', async () => { - const ctx = await harness() - const warn = vi.fn() - ctx.logger.warn = warn as never - const handle = ctx.activities.open({ kind: 'bash', label: 'build' }) - handle.end({ status: 'killed', detail: 'owner disposed' }) - handle.end({ status: 'completed' }) - handle.append('late') - handle.updateDetail('late detail') - const snapshot = ctx.activities.get(handle.id) - expect(snapshot.status).toBe('killed') - expect(snapshot.detail).toBe('owner disposed') - expect(snapshot.outputTotal).toBe(0) - expect(warn.mock.calls.map(call => String(call[0]))).toEqual([ - expect.stringContaining('append to ended activity'), - expect.stringContaining('detail update on ended activity'), - ]) - }) - - it('signals observers for appends and once more at settlement', async () => { - const ctx = await harness() - const signals: ActivityId[] = [] - ctx.activities.onOutput((id) => { signals.push(id) }) - const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) - handle.append('a') - handle.append('b') - handle.end({ status: 'completed' }) - expect(signals).toEqual([handle.id, handle.id, handle.id]) - }) - - it('updateDetail changes the visible row without touching output offsets', async () => { - const ctx = await harness() - const changes: (Agent | undefined)[] = [] - ctx.activities.onActivitiesChanged((owner) => { changes.push(owner) }) - const handle = ctx.activities.open({ kind: 'workflow', label: 'docs run' }) - handle.updateDetail('3/10 agents done') - expect(ctx.activities.get(handle.id).detail).toBe('3/10 agents done') - expect(ctx.activities.get(handle.id).outputTotal).toBe(0) - expect(changes).toHaveLength(2) - }) -}) - -describe('LocalActivityRegistry visibility and delivery', () => { - it('fences owned processes by session id and keeps unowned ones open', async () => { - const ctx = await harness() - const alice = stubAgent(ctx, 'alice') - const bob = stubAgent(ctx, 'bob') - ctx.agents.register(alice) - ctx.agents.register(bob) - const owned = ctx.activities.open({ kind: 'bash', label: 'alice job', owner: alice }) - const open = ctx.activities.open({ kind: 'bash', label: 'shared' }) - owned.append('secret') - expect(ctx.activities.list(alice).map(snapshot => snapshot.id)).toEqual([owned.id, open.id]) - expect(ctx.activities.list(bob).map(snapshot => snapshot.id)).toEqual([open.id]) - expect(ctx.activities.list().map(snapshot => snapshot.id)).toEqual([open.id]) - expect(() => ctx.activities.get(owned.id, bob)).toThrow(/belongs to another session/) - expect(() => ctx.activities.read(owned.id, 0)).toThrow(/belongs to another session/) - expect(textFrom(ctx, open.id)).toBe('') - expect(ctx.activities.read(owned.id, 0, alice).chunks[0]?.text).toBe('secret') - }) - - it('delivers scoped listeners only their own agents and global listeners everything', async () => { - const ctx = await harness() - const alice = stubAgent(ctx, 'alice') - const bob = stubAgent(ctx, 'bob') - ctx.agents.register(alice) - ctx.agents.register(bob) - const globalOwners: (string | undefined)[] = [] - ctx.activities.onActivitiesChanged((owner) => { globalOwners.push(owner?.id) }) - const scopedOwners: (string | undefined)[] = [] - await alice.ctx.plugin({ - inject: ['activities'], - apply(scopedCtx: Context) { - scopedCtx.activities.onActivitiesChanged((owner) => { scopedOwners.push(owner?.id) }) - }, - }) - const scopedOutputs: string[] = [] - const scopedFiber = await alice.ctx.plugin({ - inject: ['activities'], - apply(scopedCtx: Context) { - scopedCtx.activities.onOutput((id) => { scopedOutputs.push(String(id)) }) - }, - }) - const aliceHandle = ctx.activities.open({ kind: 'bash', label: 'alice work', owner: alice }) - aliceHandle.append('scoped delivery probe') - expect(scopedOutputs).toEqual([String(aliceHandle.id)]) - ctx.activities.open({ kind: 'bash', label: 'bob work', owner: bob }) - ctx.activities.open({ kind: 'bash', label: 'unowned' }) - expect(globalOwners).toEqual(['alice', 'bob', undefined]) - expect(scopedOwners).toEqual(['alice']) - // Disposing one scoped registrant probes layer reclamation; the sibling - // scoped changed-listener keeps the layer alive and keeps delivering. - await scopedFiber.dispose() - ctx.activities.open({ kind: 'bash', label: 'alice later', owner: alice }) - expect(scopedOwners).toEqual(['alice', 'alice']) - - // A scope whose only contribution goes empties on disposal and is reclaimed. - const bobFiber = await bob.ctx.plugin({ - inject: ['activities'], - apply(scopedCtx: Context) { - scopedCtx.activities.onOutput(() => {}) - }, - }) - await bobFiber.dispose() - }) - - it('contains throwing listeners without breaking the commit', async () => { - const ctx = await harness() - const warn = vi.fn() - ctx.logger.warn = warn as never - ctx.activities.onActivitiesChanged(() => { throw new Error('changed boom') }) - ctx.activities.onOutput(() => { throw new Error('output boom') }) - const seen: (Agent | undefined)[] = [] - ctx.activities.onActivitiesChanged((owner) => { seen.push(owner) }) - const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) - handle.append('x') - expect(seen).toHaveLength(1) - expect(ctx.activities.get(handle.id).outputTotal).toBe(1) - expect(warn).toHaveBeenCalledWith(expect.stringContaining('onActivitiesChanged listener threw')) - expect(warn).toHaveBeenCalledWith(expect.stringContaining('onOutput listener threw')) - }) - - it('unregisters listeners with their registering fiber', async () => { - const ctx = await harness() - const signals: ActivityId[] = [] - const fiber = ctx.plugin({ - inject: ['activities'], - apply(pluginCtx: Context) { - pluginCtx.activities.onOutput((id) => { signals.push(id) }) - }, - }) - await fiber - const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) - handle.append('a') - expect(signals).toHaveLength(1) - await fiber.dispose() - handle.append('b') - expect(signals).toHaveLength(1) - }) -}) - -describe('LocalActivityRegistry lifecycle', () => { - it('owner disposal ends open records, removes rows, and announces the removal', async () => { - const ctx = await harness() - const owner = stubAgent(ctx, 'owner') - ctx.agents.register(owner) - const handle = ctx.activities.open({ kind: 'bash', label: 'sleep', owner }) - handle.append('partial') - const settledEarly = ctx.activities.open({ kind: 'bash', label: 'done already', owner }) - settledEarly.end({ status: 'completed' }) - const changes: (string | undefined)[] = [] - ctx.activities.onActivitiesChanged((changed) => { changes.push(changed?.id) }) - await disposeAgentScope(owner) - expect(ctx.activities.list(owner)).toEqual([]) - expect(() => ctx.activities.get(handle.id, owner)).toThrow(/unknown activity/) - // The forced end and the removal both announced under the owner. - expect(changes.length).toBeGreaterThanOrEqual(2) - expect(new Set(changes)).toEqual(new Set(['owner'])) - // The producer's own late report is dropped silently, not thrown. - expect(() => { handle.end({ status: 'completed' }) }).not.toThrow() - }) - - it('service disposal ends everything, clears the store, and announces emptied owners', async () => { - const ctx = new Context() - await ctx.plugin(AgentRegistry) - const registryFiber = ctx.plugin(LocalActivityRegistry, {}) - await registryFiber - const owner = stubAgent(ctx, 'owner') - ctx.agents.register(owner) - const processes = ctx.activities - const owned = processes.open({ kind: 'bash', label: 'owned', owner }) - processes.open({ kind: 'bash', label: 'unowned' }) - const preSettled = processes.open({ kind: 'bash', label: 'already settled' }) - preSettled.end({ status: 'completed' }) - const changes: (string | undefined)[] = [] - ctx.activities.onActivitiesChanged((changed) => { changes.push(changed?.id) }) - await registryFiber.dispose() - expect(changes).toEqual(expect.arrayContaining(['owner', undefined])) - expect(() => { owned.append('late') }).not.toThrow() - }) -}) - -describe('LocalActivityRegistry snapshots', () => { - it('hands out fresh snapshots, never live registry state', async () => { - const ctx = await harness() - const handle: ActivityHandle = ctx.activities.open({ kind: 'bash', label: 'echo' }) - const before: ActivitySnapshot = ctx.activities.get(handle.id) - handle.append('grow') - expect(before.outputTotal).toBe(0) - expect(ctx.activities.get(handle.id).outputTotal).toBe(4) - }) -}) diff --git a/packages/activity/activity-local/tests/loader-composition.spec.ts b/packages/activity/activity-local/tests/loader-composition.spec.ts deleted file mode 100644 index 4b341f7e16..0000000000 --- a/packages/activity/activity-local/tests/loader-composition.spec.ts +++ /dev/null @@ -1,60 +0,0 @@ -import { afterEach, describe, expect, it } from 'vitest' -import { mkdtemp, rm, writeFile } from 'node:fs/promises' -import { tmpdir } from 'node:os' -import { join } from 'node:path' -import { pathToFileURL } from 'node:url' -import { Context } from '@deepseek-ai/cordis' -import Include from '@deepseek-ai/cordis-plugin-include' -import Loader from '@deepseek-ai/cordis-plugin-loader' -import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' - -let root: string | undefined -let context: Context | undefined - -afterEach(async () => { - await context?.fiber.dispose() - context = undefined - if (root !== undefined) await rm(root, { recursive: true, force: true }) - root = undefined -}) - -describe('process-local through a real Loader composition', () => { - it('applies the provider-owned retention config from a Cordis row', async () => { - root = await mkdtemp(join(tmpdir(), 'dsh-activity-local-loader-')) - const configPath = join(root, 'cordis.yml') - await writeFile(configPath, [ - "- name: '@deepseek-ai/dsh-activity-local'", - ' config:', - ' retainBytes: 8', - '', - ].join('\n')) - - context = new Context() - context.baseUrl = pathToFileURL(root).href + '/' - await context.plugin(Loader) - context.loader.builtins.include = Include - context.loader.internal = { - version: 'v2', - async import(specifier: string) { - if (specifier === '@deepseek-ai/dsh-activity-local') return LocalActivityRegistry - throw new Error(`unexpected Loader import: ${specifier}`) - }, - } as unknown as NonNullable - await context.loader.create({ - name: 'cordis:include', - config: { path: pathToFileURL(configPath).href }, - }) - await context.loader.await() - - expect(context.activities).toBeInstanceOf(LocalActivityRegistry) - const handle = context.activities.open({ kind: 'bash', label: 'loader retention probe' }) - handle.append('aaaa') - handle.append('bbbb') - handle.append('cccc') - const read = context.activities.read(handle.id, 0) - // retainBytes: 8 from the Cordis row dropped the oldest chunk. - expect(read.lossy).toBe(true) - expect(read.chunks.map(chunk => chunk.text)).toEqual(['bbbb', 'cccc']) - expect(read.next).toBe(12) - }) -}) diff --git a/packages/activity/activity-local/tsconfig.json b/packages/activity/activity-local/tsconfig.json deleted file mode 100644 index 0bddbff854..0000000000 --- a/packages/activity/activity-local/tsconfig.json +++ /dev/null @@ -1,33 +0,0 @@ -{ - "extends": "../../../tsconfig.base.json", - "compilerOptions": { - "rootDir": "src", - "outDir": "lib/types" - }, - "include": [ - "src" - ], - "references": [ - { - "path": "../../../vendor/cosmokit" - }, - { - "path": "../../../vendor/cordis" - }, - { - "path": "../../../vendor/schemastery" - }, - { - "path": "../../core/agent" - }, - { - "path": "../../core/scope" - }, - { - "path": "../activity" - }, - { - "path": "../../runtime-diagnostics/invariants" - } - ] -} diff --git a/packages/activity/activity/README.i18n.yaml b/packages/activity/activity/README.i18n.yaml deleted file mode 100644 index 14d65fd03c..0000000000 --- a/packages/activity/activity/README.i18n.yaml +++ /dev/null @@ -1,6 +0,0 @@ -# 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 packages/activity/activity/README.md -README.md: 466bdf5aac8718b197495f477f012e6314e41dd6 -README.zh.md: 32dea93f72f12ae1f439220193b8fa5b994bbe45 diff --git a/packages/activity/activity/README.md b/packages/activity/activity/README.md deleted file mode 100644 index 466bdf5aac..0000000000 --- a/packages/activity/activity/README.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -description: "The streaming-output observation contract (ctx.activities): open/append/end handles, non-consuming offset reads, owner fencing, and the shared pull pump for producers and consumers of live activity output." -kind: "package-reference" ---- - -# @deepseek-ai/dsh-activity - -English | [中文](README.zh.md) - -## Summary - -`dsh-activity` lets a long-running producer publish live output and status once, and any number of independent consumers read it without stealing bytes from the model: reads are non-consuming, addressed by absolute UTF-8 byte offsets that survive eviction, and fenced to the owning session. The registry is a pure observation plane — it starts nothing, cancels nothing, and is invisible to the model, so producers keep their execution resources and their existing model-facing surfaces. This package ships the contract only; load [`dsh-activity-local`](../activity-local/README.md) to get a working registry, and without one `ctx.activities` does not exist and observation silently degrades to none. - -## Table of Contents - -- [Use this package](#use-this-package) -- [Understand the implementation](#understand-the-implementation) -- [Further Exploration](#further-exploration) -- [Model Experience](#model-experience) -- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work) -- [Dev Note](#dev-note) - ------ - - -## Use this package - -Use this package when you write a producer that mirrors live work, or a consumer that renders it; the composition mounts an implementation row (`@deepseek-ai/dsh-activity-local`), never this contract package directly. - -### Producing an activity - -`open(spec): ActivityHandle` validates the kind, label, and exact live owner, then atomically registers the record and returns the producer face: synchronous `append(text, { channel?, gapBefore? })`, `updateDetail(detail)`, and first-wins `end(outcome)`. After `end` — including a teardown force-end — `append` and `updateDetail` log and drop instead of throwing, so a producer's trailing flush cannot break its own teardown. Producer plugins extend `ActivityKindMap` with their opaque id namespace and may link an activity to its tool call and background job through `ActivityCorrelation`. Access the registry with `ctx.get('activities')` and contain every observation failure: the plane is optional, and the observed work must never depend on it. - -### Consuming activities - -`get(id, caller?)` and `list(caller?)` return fresh snapshots; listing includes only caller-owned and unowned activities, and predictable ids make that fence the boundary. `read(id, from, caller?)` returns the retained chunks overlapping `[from, total)` plus the resume offset, without consuming anything; a reader below the oldest retained byte gets `lossy: true`, never an error. `onActivitiesChanged(listener)` observes visible-set changes so consumers re-read rather than accumulate deltas, and `onOutput(listener)` signals stream advancement carrying only the id; both deliver owner-relative and contain every listener. - -### Pumping a substrate - -`pumpActivityOutput(handle, sources, { pollMs, done })` is the shared pump for producers whose substrate is a non-consuming offset reader (the subprocess `readFrom(fromByte)` family): it copies labeled deltas at a bounded cadence, marks a lossy source read `gapBefore`, and drains once more after `done` settles without ever calling `end()` itself. - ------ - - -## Understand the implementation - -
        -Implementation internals — click to expand - -The package holds the abstract `ActivityRegistry` service (a direct mount throws, naming an implementation to load), the vocabulary types, the branded `ActivityId`, the pump, and the invariant companion. Offsets are absolute so an observer's cursor never depends on what other observers did, and eviction moves only the earliest retained byte — the lossy flag is how a late reader learns the head is gone. - -| File | Role | -|---|---| -| [`src/index.ts`](src/index.ts) | Abstract `ActivityRegistry` service and the direct-mount guard | -| [`src/types.ts`](src/types.ts) | Vocabulary: kinds, snapshots, handles, reads, listeners | -| [`src/brand.ts`](src/brand.ts) | Branded `ActivityId` (browser-safe leaf) | -| [`src/pump.ts`](src/pump.ts) | `pumpActivityOutput` pull-substrate pump | -| [`src/invariant.ts`](src/invariant.ts) | Snapshot invariants installed on the change feed | - -
        - ------ - - -## Further Exploration - -- [`dsh-activity-local`](../activity-local/README.md) — the in-memory implementation and its retention config. -- [docs/subsystems/activity.md](../../../docs/subsystems/activity.md) — the subsystem reference: offsets, retention, listener delivery. -- [`dsh-api-activity-controller`](../../api/activity-controller/README.md) — the Remote streams serving this plane to browsers. -- [Observation-seam Agent Note](../../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md) — why the plane is non-consuming and model-invisible. - ------ - - -## Model Experience - -None, as the registry carries live observation state for humans and registers no prompt, tool, or session event; activity output becomes model-visible only through the producers' existing tool results and `ctx.jobs` reads. - -#### KV Cache effect - -None; the package never assembles or alters provider requests. - -## Known Limitations and Deferred Work - - - -These limits define when the contract is a poor fit. They are current package constraints, not a task backlog. - -- **Records are process-local and live-only** — a Host restart empties every roster while the transcript keeps the producing tool cards; durable replay is a separate design. -- **The observation plane has no cancellation verb** — stopping work stays with the producers and `ctx.jobs`; a panel-initiated kill is blocked on the jobs `reported` contract question recorded in the [web job display Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md). -- **Settled records last until owner disposal** — retention trims their buffers to the settled cap, but the rows themselves are not aged out. - - -### Dev Note - -
        -Working context for maintainers — click to expand - -None. - -
        diff --git a/packages/activity/activity/README.zh.md b/packages/activity/activity/README.zh.md deleted file mode 100644 index 32dea93f72..0000000000 --- a/packages/activity/activity/README.zh.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -description: "流式输出观察契约(ctx.activities):open/append/end 句柄、非消费偏移读取、owner 栅栏,以及供实时活动输出生产者与消费者共用的拉取泵。" -kind: "package-reference" ---- - -# @deepseek-ai/dsh-activity - -[English](README.md) | 中文 - -## 概述 - -`dsh-activity` 让长时运行的生产者只发布一次实时输出与状态,任意数量的独立消费者读取它而不会偷走模型的字节:读取是非消费的,以跨淘汰仍有效的绝对 UTF-8 字节偏移寻址,并以归属会话为栅栏。注册表是纯观察面——它什么都不启动、什么都不取消、对模型不可见,因此生产者保留自己的执行资源与既有模型可见表面。本包只交付契约;加载 [`dsh-activity-local`](../activity-local/README.zh.md) 获得可用注册表,没有实现时 `ctx.activities` 不存在,观察静默退化为无。 - -## 目录 - -- [使用本包](#use-this-package) -- [理解实现](#understand-the-implementation) -- [进一步探索](#further-exploration) -- [模型体验](#model-experience) -- [已知限制与延期工作](#known-limitations-and-deferred-work) -- [开发备注](#dev-note) - ------ - - -## 使用本包 - -编写镜像实时工作的生产者、或渲染它的消费者时使用本包;组合挂载的是实现行(`@deepseek-ai/dsh-activity-local`),从不直接挂载这个契约包。 - -### 生产一个 activity - -`open(spec): ActivityHandle` 校验 kind、label 与确切的活跃 owner,然后原子注册记录并返回生产者面:同步的 `append(text, { channel?, gapBefore? })`、`updateDetail(detail)`,以及先到先赢的 `end(outcome)`。在 `end` 之后——包括 teardown 强制收尾——`append` 与 `updateDetail` 记日志后丢弃而非抛出,因此生产者的尾部 flush 不会破坏自己的 teardown。生产者插件以自己的不透明 id 命名空间扩展 `ActivityKindMap`,并可通过 `ActivityCorrelation` 把 activity 关联到其工具调用与后台 job。用 `ctx.get('activities')` 访问注册表并包住每个观察失败:该面是可选的,被观察的工作绝不能依赖它。 - -### 消费 activities - -`get(id, caller?)` 与 `list(caller?)` 返回新鲜快照;列表只含调用方拥有与无主的 activity,可预测的 id 使该栅栏成为边界。`read(id, from, caller?)` 返回与 `[from, total)` 重叠的留存 chunk 加恢复偏移,不消费任何东西;读到最旧留存字节之前的位置得到 `lossy: true`,绝不报错。`onActivitiesChanged(listener)` 观察可见集变化,消费者据此重读而非累积增量;`onOutput(listener)` 以仅含 id 的信号提示流推进;两者按 owner 相对投递并包住每个监听器。 - -### 泵送一个底座 - -`pumpActivityOutput(handle, sources, { pollMs, done })` 是底座为非消费偏移读取器(subprocess 的 `readFrom(fromByte)` 家族)的生产者的共用泵:它以有界节奏复制带标签的增量,把有损的源读取标为 `gapBefore`,并在 `done` 结算后再排空一次,自己从不调用 `end()`。 - ------ - - -## 理解实现 - -
        -实现内幕——点击展开 - -本包持有抽象 `ActivityRegistry` 服务(直接挂载会抛出并指名应加载的实现)、词汇类型、branded `ActivityId`、泵与 invariant 伴生。偏移是绝对的,观察者的游标从不依赖其他观察者做了什么;淘汰只前移最旧留存字节——lossy 标志就是迟到读者得知头部已丢的方式。 - -| 文件 | 角色 | -|---|---| -| [`src/index.ts`](src/index.ts) | 抽象 `ActivityRegistry` 服务与直接挂载防护 | -| [`src/types.ts`](src/types.ts) | 词汇:kind、快照、句柄、读取、监听器 | -| [`src/brand.ts`](src/brand.ts) | branded `ActivityId`(浏览器安全叶子) | -| [`src/pump.ts`](src/pump.ts) | `pumpActivityOutput` 拉取底座泵 | -| [`src/invariant.ts`](src/invariant.ts) | 装在变化流上的快照不变式 | - -
        - ------ - - -## 进一步探索 - -- [`dsh-activity-local`](../activity-local/README.zh.md)——内存实现及其留存配置。 -- [docs/subsystems/activity.md](../../../docs/subsystems/activity.zh.md)——子系统参考:偏移、留存、监听器投递。 -- [`dsh-api-activity-controller`](../../api/activity-controller/README.zh.md)——把该面提供给浏览器的 Remote 流。 -- [观察面 Agent Note](../../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md)——该面为何是非消费且模型不可见的。 - ------ - - -## 模型体验 - -无:注册表为人承载实时观察状态,不注册任何 prompt、工具或会话事件;activity 输出只经由生产者既有的工具结果与 `ctx.jobs` 读取才对模型可见。 - -#### KV Cache 影响 - -无;本包从不组装或改动 provider 请求。 - -## 已知限制与延期工作 - - - -这些限制说明契约何时不合适。它们是当前包约束,不是任务积压。 - -- **记录是进程本地且仅存活期**——Host 重启清空所有 roster,而 transcript 保留生产方的工具卡片;持久回放是另一项设计。 -- **观察面没有取消动词**——停止工作仍属于生产者与 `ctx.jobs`;面板发起的 kill 被 [web job display Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md) 记录的 jobs `reported` 契约问题阻塞。 -- **已结算记录存续到 owner 释放**——留存把它们的缓冲裁到 settled 上限,但行本身不会被老化清除。 - - -### 开发备注 - -
        -维护者的工作上下文——点击展开 - -无。 - -
        diff --git a/packages/activity/activity/package.json b/packages/activity/activity/package.json deleted file mode 100644 index 89372dcf7d..0000000000 --- a/packages/activity/activity/package.json +++ /dev/null @@ -1,57 +0,0 @@ -{ - "name": "@deepseek-ai/dsh-activity", - "description": "Streaming-output observation registry (ctx.activities) for the DeepSeek Harness — non-consuming offset reads, bounded retention, and change signals over any long-running producer's live output", - "version": "0.1.2-alpha.2", - "publishConfig": { - "access": "public" - }, - "repository": { - "type": "git", - "url": "git+https://github.com/deepseek-ai/deepseek-harness.git", - "directory": "packages/activity/activity" - }, - "type": "module", - "main": "lib/index.js", - "types": "lib/types/index.d.ts", - "exports": { - ".": { - "types": "./lib/types/index.d.ts", - "default": "./lib/index.js" - }, - "./invariant": { - "types": "./lib/types/invariant.d.ts", - "default": "./lib/invariant.js" - }, - "./brand": { - "types": "./lib/types/brand.d.ts", - "default": "./lib/types/brand.js" - }, - "./src/*": "./src/*", - "./package.json": "./package.json" - }, - "files": [ - "lib/index.js", - "lib/invariant.js", - "lib/types/**/*.js", - "lib/types/**/*.d.ts" - ], - "license": "MIT", - "peerDependencies": { - "@deepseek-ai/dsh-agent": "workspace:^", - "@deepseek-ai/dsh-brand": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-jobs": "workspace:^", - "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/cordis": "workspace:^" - }, - "devDependencies": { - "@deepseek-ai/dsh-agent": "workspace:^", - "@deepseek-ai/dsh-brand": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-jobs": "workspace:^", - "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/cordis": "workspace:^" - } -} diff --git a/packages/activity/activity/src/brand.ts b/packages/activity/activity/src/brand.ts deleted file mode 100644 index 8df786ffb9..0000000000 --- a/packages/activity/activity/src/brand.ts +++ /dev/null @@ -1,28 +0,0 @@ -/** - * dsh-activity' owned branded id, carried across the registry, the observation - * wire, and correlation metadata on other domains' rows. - * - * It lives in its own leaf because the package root reaches `dsh-agent` - * through the owner and listener signatures, which a Client program cannot - * resolve even as a type. A browser-safe consumer imports the id here; - * `Branded` itself comes from the zero-dependency `@deepseek-ai/dsh-brand`. - * - * @module @deepseek-ai/dsh-activity/brand - */ - -import type { Branded } from '@deepseek-ai/dsh-brand' - -/** - * Identifies one observable activity. The registry generates `-N`; - * predictable ids rely on owner authorization rather than secrecy. - */ -export type ActivityId = Branded<'ActivityId'> - -/** - * Brand a string as a {@link ActivityId}. - * @param id - the raw process-id string (the registry generates `-N`). - * @returns the same string, branded; no validation is performed. - */ -export function ActivityId(id: string): ActivityId { - return id as ActivityId -} diff --git a/packages/activity/activity/src/index.ts b/packages/activity/activity/src/index.ts deleted file mode 100644 index 4e3927abe5..0000000000 --- a/packages/activity/activity/src/index.ts +++ /dev/null @@ -1,138 +0,0 @@ -/** - * The streaming-output observation Service Definition (`ctx.activities`). An - * activity is one observable unit of long-running work: an append-only bounded - * output stream plus live status, readable by any number of independent - * observers at absolute byte offsets. The registry is a pure observation - * plane — it starts nothing, cancels nothing, and is invisible to the model; - * producers keep their execution resources and their existing model-facing - * surfaces (`ctx.jobs` cursors, tool results). The process-local registry - * lives in `@deepseek-ai/dsh-activity-local`. - * @module @deepseek-ai/dsh-activity - */ - -import { Context, Service } from '@deepseek-ai/cordis' -import type { Agent } from '@deepseek-ai/dsh-agent' -import type { - ActivitiesChangedListener, ActivityHandle, ActivityId, ActivityOpen, ActivityOutputListener, - ActivityRead, ActivitySnapshot, -} from './types.ts' - -export { ActivityId } from './brand.ts' -export type { - ActivityAppendOptions, - ActivityChannel, - ActivityCorrelation, - ActivitiesChangedListener, - ActivityHandle, - ActivityKind, - ActivityKindMap, - ActivityOpen, - ActivityOutcome, - ActivityOutputChunk, - ActivityOutputListener, - ActivityRead, - ActivitySnapshot, - ActivityStatus, -} from './types.ts' -export { pumpActivityOutput } from './pump.ts' -export type { ActivityPumpOptions, ActivityPumpRead, ActivityPumpSource } from './pump.ts' - -declare module '@deepseek-ai/cordis' { - interface Context { - activities: ActivityRegistry - } -} - -/** - * Abstract streaming-output registry. Subclass, implement the abstract - * methods, and load the subclass as a plugin — it registers as - * `ctx.activities` (one implementation per context; loading a second throws, - * which is cordis' standard duplicate-service behavior). - * - * Implementations must honor these semantics: - * - Observation never consumes. Any number of readers hold their own absolute - * byte offsets; a read changes no cursor and no producer state, so the - * model-facing paths (`ctx.jobs.read()`, tool results) are unaffected. - * - Records outlive producer fibers. Owner disposal ends still-open records - * and removes them; service disposal ends and clears everything. Neither - * awaits a producer — the registry owns no execution resource. - * - Retention is bounded. Appends past the live cap drop the oldest retained - * bytes; a reader below the retained window gets a lossy read, never an - * error. Settlement trims retention to the settled cap. - * - Listener delivery is owner-relative: a listener registered from an - * unscoped context — a host composition's own carrier — sees every owner, - * while one registered under an agent composition's scope sees exactly the - * agents composed under it. Every listener is contained. - */ -export abstract class ActivityRegistry extends Service { - constructor(ctx: Context) { - // `abstract` erases at runtime, so a composition row naming this package - // would register a ctx.activities with no method implementations and fail - // far from the misconfiguration. Fail loud at load instead. - if (new.target === ActivityRegistry) { - throw new Error('@deepseek-ai/dsh-activity is the abstract activity observation seam; load an implementation such as @deepseek-ai/dsh-activity-local instead') - } - super(ctx, 'activities') - } - - /** - * Validate the spec, attach owner cleanup, and atomically register one - * activity. A rejection leaves no id; after return the producer owns the - * handle and the visible set has changed. - * @param spec - activity identity, owner, and correlation. - * @returns the producer face of the registered activity. - */ - abstract open(spec: ActivityOpen): ActivityHandle - - /** - * List caller-owned and unowned activities in registration order without - * exposing another session's labels or output. - * @param caller - reading agent; a non-agent caller sees only unowned activities. - * @returns fresh snapshots. - */ - abstract list(caller?: Agent): ActivitySnapshot[] - - /** - * Return a fresh snapshot. Throws for an unknown or foreign activity. - * @param id - activity to look up. - * @param caller - reading agent checked against the owner. - * @returns a fresh snapshot. - */ - abstract get(id: ActivityId, caller?: Agent): ActivitySnapshot - - /** - * Read retained output from an absolute byte offset without consuming it. - * Resume by passing a previous read's `next`; a foreign offset inside a - * retained chunk returns that whole chunk (its `at` may precede `from`). - * Throws for an unknown or foreign activity or a negative or non-integer - * offset. - * @param id - activity to read. - * @param from - absolute byte offset to read from (0 for the retained head). - * @param caller - reading agent checked against the owner. - * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. - */ - abstract read(id: ActivityId, from: number, caller?: Agent): ActivityRead - - /** - * Register an effect-scoped observer of visible-set changes: opening, - * detail updates, settlement, owner-disposal removal, and the emptying that - * service disposal commits — so an observer re-reads rather than - * accumulating deltas. Listeners are contained and never awaited. - * @param listener - receives the owner whose visible set changed, or - * `undefined` when an unowned activity changed and every caller's set did. - * @returns disposer that unregisters the listener. - */ - abstract onActivitiesChanged(listener: ActivitiesChangedListener): () => void - - /** - * Register an effect-scoped observer of stream advancement — one signal per - * committed append and one at settlement, carrying only the activity id. - * A consumer schedules a {@link read} from its own cursor; the registry - * never pushes payloads. Listeners are contained and never awaited. - * @param listener - receives the id whose stream advanced. - * @returns disposer that unregisters the listener. - */ - abstract onOutput(listener: ActivityOutputListener): () => void -} - -export default ActivityRegistry diff --git a/packages/activity/activity/src/invariant.ts b/packages/activity/activity/src/invariant.ts deleted file mode 100644 index 6753fa7b0e..0000000000 --- a/packages/activity/activity/src/invariant.ts +++ /dev/null @@ -1,62 +0,0 @@ -/** Package-owned process-snapshot invariants. @module @deepseek-ai/dsh-activity/invariant */ - -import type { Context } from '@deepseek-ai/cordis' -import type { Agent } from '@deepseek-ai/dsh-agent' -import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants' -import type { ActivitySnapshot } from './types.ts' - -const PACKAGE_NAME = '@deepseek-ai/dsh-activity' -const TERMINAL_STATUSES = new Set(['completed', 'failed', 'killed']) - -/** Cordis companion plugin name. */ -export const name = 'activity-invariant' -/** Service required before the companion can reserve package ownership. */ -export const inject = ['invariants'] - -/** Validate the cross-field relationships in one registry snapshot. */ -/* jscpd:ignore-start -- mirrors the jobs invariant's id/ordinal checks by design; the two registries share the `-N` scheme. */ -function validateSnapshot(snapshot: ActivitySnapshot, fail: InvariantFailure): void { - const id = String(snapshot.id) - const prefix = `${snapshot.kind}-` - const ordinal = Number(id.slice(prefix.length)) - if (snapshot.kind.length === 0 || !id.startsWith(prefix) - || !Number.isSafeInteger(ordinal) || ordinal < 1) { - fail(`activity snapshot id ${JSON.stringify(id)} must be ${JSON.stringify(prefix)} followed by a positive ordinal`) - } - if (snapshot.label.length === 0) fail(`activity ${JSON.stringify(id)} label must be non-empty`) - if (!Number.isSafeInteger(snapshot.startedAt) || snapshot.startedAt < 0) { - fail(`activity ${JSON.stringify(id)} startedAt must be a non-negative epoch integer`) - } - /* jscpd:ignore-end */ - - const terminal = TERMINAL_STATUSES.has(snapshot.status) - if (terminal !== (snapshot.finishedAt !== undefined)) { - fail(`activity ${JSON.stringify(id)} finishedAt must be present exactly for a terminal status`) - } - if (snapshot.finishedAt !== undefined - && (!Number.isSafeInteger(snapshot.finishedAt) || snapshot.finishedAt < snapshot.startedAt)) { - fail(`activity ${JSON.stringify(id)} finishedAt must be an epoch integer no earlier than startedAt`) - } - - if (!Number.isSafeInteger(snapshot.outputTotal) || snapshot.outputTotal < 0 - || !Number.isSafeInteger(snapshot.outputEarliest) || snapshot.outputEarliest < 0 - || snapshot.outputEarliest > snapshot.outputTotal) { - fail(`activity ${JSON.stringify(id)} output offsets must satisfy 0 <= outputEarliest <= outputTotal`) - } -} - -/** Install checks over current visible records and every later visible-set change. */ -const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => { - for (const snapshot of ctx.activities.list()) validateSnapshot(snapshot, fail) - ctx.activities.onActivitiesChanged((owner: Agent | undefined) => { - for (const snapshot of ctx.activities.list(owner)) validateSnapshot(snapshot, fail) - }) -}, { inject: ['activities'] }) - -/** - * Register the process-registry invariant companion. - * @param ctx - Cordis context carrying the invariant service. - * @returns the installed registration's disposer after setup succeeds. - */ -export const apply = (ctx: Context): Promise<() => void> => - Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install)) diff --git a/packages/activity/activity/src/pump.ts b/packages/activity/activity/src/pump.ts deleted file mode 100644 index 4cc1eae22d..0000000000 --- a/packages/activity/activity/src/pump.ts +++ /dev/null @@ -1,95 +0,0 @@ -/** - * Shared poll pump for producers whose output substrate is a non-consuming - * offset reader (the subprocess `readFrom(fromByte)` family). Pure utility — - * no cordis, no timers retained past settlement. - * @module - */ - -import type { ActivityChannel, ActivityHandle } from './types.ts' - -/** One non-consuming offset read from a producer-owned stream. */ -export interface ActivityPumpRead { - /** Text captured since the requested offset (the whole retained tail when lossy). */ - text: string - /** Whole-stream offset to resume from on the next read. */ - nextOffset: number - /** True when the requested offset slid out of the source's retained window. */ - lossy: boolean -} - -/** One producer-owned stream the pump copies into a process. */ -export interface ActivityPumpSource { - /** Stream label attached to every chunk this source yields. */ - channel?: ActivityChannel - /** - * Read everything captured since `fromByte` without consuming it. - * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 first). - * @returns the delta text, the next offset, and the lossy flag. - */ - read(fromByte: number): ActivityPumpRead -} - -/** Cadence and settlement for one {@link pumpActivityOutput} run. */ -export interface ActivityPumpOptions { - /** Poll interval in milliseconds; a positive finite number. */ - pollMs: number - /** - * Settles when the producer's work finished and its sources hold their - * final bytes. The pump drains once more after settlement and returns; - * a rejection is treated as settlement. - */ - done: Promise -} - -/** - * Copy producer streams into a process at a bounded cadence: drain every - * source, sleep `pollMs` or until `done` settles, repeat, then drain one - * final time. A lossy source read appends its surviving tail with - * `gapBefore`, so the discontinuity stays visible to observers. The pump - * never calls `handle.end()` — the producer maps its own outcome. - * @param handle - the open process receiving the copied chunks. - * @param sources - producer streams, each pumped at its own offset. - * @param options - poll cadence and the producer's settlement promise. - * @returns resolves after the final post-settlement drain. - */ -export async function pumpActivityOutput( - handle: ActivityHandle, - sources: readonly ActivityPumpSource[], - options: ActivityPumpOptions, -): Promise { - if (!Number.isFinite(options.pollMs) || options.pollMs <= 0) { - throw new Error(`invalid pump pollMs: expected a positive finite number of milliseconds, got ${JSON.stringify(options.pollMs)}`) - } - const states = sources.map(source => ({ source, cursor: 0 })) - const drain = (): void => { - for (const state of states) { - const { source } = state - const read = source.read(state.cursor) - state.cursor = read.nextOffset - if (read.text.length === 0) continue - if (source.channel === undefined && !read.lossy) { - handle.append(read.text) - } else { - handle.append(read.text, { - ...source.channel !== undefined ? { channel: source.channel } : {}, - ...read.lossy ? { gapBefore: true as const } : {}, - }) - } - } - } - let settled = false - const settlement = options.done.then(() => { settled = true }, () => { settled = true }) - while (!settled) { - drain() - await Promise.race([ - new Promise((resolve) => { - const timer = setTimeout(resolve, options.pollMs) - // The settlement branch wins the race; clear the loser so a finished - // pump holds no pending timer for up to one poll interval. - void settlement.then(() => { clearTimeout(timer); resolve() }) - }), - settlement, - ]) - } - drain() -} diff --git a/packages/activity/activity/src/types.ts b/packages/activity/activity/src/types.ts deleted file mode 100644 index 3ea1a42332..0000000000 --- a/packages/activity/activity/src/types.ts +++ /dev/null @@ -1,184 +0,0 @@ -import type { Agent } from '@deepseek-ai/dsh-agent' -import type { SessionId } from '@deepseek-ai/dsh-session' -import type { ToolCallId } from '@deepseek-ai/dsh-llm/brand' -import type { JobId } from '@deepseek-ai/dsh-jobs/brand' -import type { ActivityId } from './brand.ts' - -export type { ActivityId } from './brand.ts' - -/** - * Producer-defined activity kinds. Plugins extend this map by declaration - * merging; the registry treats every value as an opaque id namespace. - */ -export interface ActivityKindMap { - bash: 'bash' -} - -/** A registered activity kind — also the id prefix (`bash`, `workflow`, …). */ -export type ActivityKind = ActivityKindMap[keyof ActivityKindMap] - -/** Lifecycle state of one observable activity. */ -export type ActivityStatus = 'running' | 'completed' | 'failed' | 'killed' - -/** - * Output stream label. Producers without distinct streams omit it; consumers - * treat an unrecognized label like an absent one. - */ -export type ActivityChannel = 'stdout' | 'stderr' - -/** - * Links one activity to the records other domains keep for the same work, so a - * consumer can attach the output stream to an existing card or row without - * guessing from labels. - */ -export interface ActivityCorrelation { - /** Tool call that started the work, when a tool produced it. */ - callId?: ToolCallId - /** Background job carrying the model-facing control surface, when one exists. */ - jobId?: JobId -} - -/** - * Producer declaration passed to {@link ActivityRegistry.open}. The registry - * owns identity, retention, and observer delivery; the producer keeps its - * execution resources and reports through the returned {@link ActivityHandle}. - */ -export interface ActivityOpen { - /** Producer kind — also the id prefix. */ - kind: ActivityKind - /** One-line human-facing label (the command; the run description). */ - label: string - /** - * Owning live agent. Visibility is fenced by its session id, and agent - * disposal ends and removes the record. The instance must be the one - * currently registered under its agent id. Omitting the owner creates an - * unowned activity, visible to any caller until service disposal. - */ - owner?: Agent - /** Optional links to the tool call and background job for the same work. */ - correlation?: ActivityCorrelation -} - -/** Terminal outcome reported through {@link ActivityHandle.end}. */ -export interface ActivityOutcome { - /** How the work ended: finished (`completed`), broke (`failed`), or was cancelled (`killed`). */ - status: 'completed' | 'failed' | 'killed' - /** Kind-specific detail rendered into status lines ('exit code: 3'). */ - detail?: string -} - -/** Options for one {@link ActivityHandle.append}. */ -export interface ActivityAppendOptions { - /** Stream label for the chunk; omitted for producers without distinct streams. */ - channel?: ActivityChannel - /** - * Marks that producer-side bytes between the previous chunk and this one - * were lost (a source window slid before the producer could copy it), so a - * consumer can render the discontinuity instead of a silent splice. - */ - gapBefore?: true -} - -/** - * Producer face of one open activity. All methods are synchronous. After - * {@link end} — including a registry-forced end during owner or service - * teardown — `append` and `updateDetail` log and drop instead of throwing, so - * a producer's trailing flush cannot break its own teardown path. - */ -export interface ActivityHandle { - /** The registry-issued id (`-N`). */ - readonly id: ActivityId - /** - * Append one output chunk. Offsets advance by the chunk's UTF-8 byte - * length; an empty chunk is dropped without waking observers. - * @param text - the chunk text, exactly as produced. - * @param options - stream label and gap marker. - */ - append(text: string, options?: ActivityAppendOptions): void - /** - * Replace the snapshot's status detail (a progress line such as `3/10`). - * @param detail - the new detail line. - */ - updateDetail(detail: string): void - /** - * Record the terminal outcome and trim retention to the settled cap. - * First-wins: a later call — the producer's own report after a teardown - * force-end, or a duplicate — is dropped silently. - * @param outcome - terminal status and optional detail. - */ - end(outcome: ActivityOutcome): void -} - -/** - * A read-only projection of one activity, safe to hand to listeners and - * consumers — a fresh object per call, never live registry state. - */ -export interface ActivitySnapshot { - /** The registry-issued id (`-N`). */ - id: ActivityId - /** The producer kind the process was opened with. */ - kind: ActivityKind - /** The producer-supplied one-line label. */ - label: string - /** Owner session id used for visibility and grouping; absent for unowned activities. */ - ownerSession?: SessionId - /** Links to the tool call and background job for the same work, when supplied. */ - correlation?: ActivityCorrelation - /** Current lifecycle state. */ - status: ActivityStatus - /** Kind-specific status detail, when the producer supplied one. */ - detail?: string - /** Epoch ms when the activity was opened. */ - startedAt: number - /** Epoch ms when the activity ended; absent while `running`. */ - finishedAt?: number - /** Total UTF-8 bytes ever appended — the offset the next chunk starts at. */ - outputTotal: number - /** - * Offset of the oldest retained byte. Greater than zero exactly when - * retention dropped the head; a reader starting below it gets a lossy read. - */ - outputEarliest: number -} - -/** One retained output chunk returned by {@link ActivityRegistry.read}. */ -export interface ActivityOutputChunk { - /** Absolute offset of the chunk's first byte. */ - at: number - /** Chunk text exactly as appended (possibly tail-trimmed by retention). */ - text: string - /** Stream label, when the producer supplied one. */ - channel?: ActivityChannel - /** Producer-reported loss immediately before this chunk. */ - gapBefore?: true -} - -/** Result of one non-consuming {@link ActivityRegistry.read}. */ -export interface ActivityRead { - /** Retained chunks overlapping `[from, total)`, in offset order. */ - chunks: readonly ActivityOutputChunk[] - /** - * Offset to resume from — the process' current `outputTotal`. Always a - * chunk boundary: appends land whole and trimming only advances chunk - * starts, and consumers concatenate `chunks` under that assumption, so a - * provider serving partial chunks would silently duplicate text. - */ - next: number - /** True when `from` fell below the oldest retained byte, so bytes are missing before `chunks`. */ - lossy: boolean -} - -/** - * Observer of visible-set changes: opening, detail updates, settlement, and - * removal. Receives the owner whose set changed, or `undefined` when an - * unowned process changed and every caller's set did. Consumers re-read - * rather than accumulating deltas. - */ -export type ActivitiesChangedListener = (owner: Agent | undefined) => void - -/** - * Observer of stream advancement for one activity: new appended output, or the - * settlement that ends the stream. Carries no payload — a consumer schedules a - * {@link ActivityRegistry.read} from its own cursor. - */ -export type ActivityOutputListener = (id: ActivityId) => void diff --git a/packages/activity/activity/tests/invariant.spec.ts b/packages/activity/activity/tests/invariant.spec.ts deleted file mode 100644 index 306cd4533a..0000000000 --- a/packages/activity/activity/tests/invariant.spec.ts +++ /dev/null @@ -1,82 +0,0 @@ -import { describe, expect, it } from 'vitest' -import { Context } from '@deepseek-ai/cordis' -import type { Agent } from '@deepseek-ai/dsh-agent' -import ActivityRegistry, { ActivityId } from '@deepseek-ai/dsh-activity' -import type { ActivitiesChangedListener, ActivitySnapshot } from '@deepseek-ai/dsh-activity' -import * as ProcessInvariant from '@deepseek-ai/dsh-activity/invariant' -import InvariantRegistry from '@deepseek-ai/dsh-invariants' - -const BASE: ActivitySnapshot = { - id: ActivityId('bash-1'), - kind: 'bash', - label: 'compile', - status: 'completed', - startedAt: 10, - finishedAt: 20, - outputTotal: 12, - outputEarliest: 4, -} - -const RUNNING: ActivitySnapshot = { - id: ActivityId('bash-1'), - kind: 'bash', - label: 'compile', - status: 'running', - startedAt: 10, - outputTotal: 0, - outputEarliest: 0, -} - -/** Boot the companion over a probe registry whose visible set the test controls. */ -async function setup(seed: ActivitySnapshot[] = []): Promise<(visible: ActivitySnapshot[], owner?: Agent) => void> { - const ctx = new Context() - let current = seed - let listener: ActivitiesChangedListener | undefined - const probe = { - list: () => current, - onActivitiesChanged(value: ActivitiesChangedListener) { - listener = value - return () => { listener = undefined } - }, - } as unknown as ActivityRegistry - await ctx.plugin(InvariantRegistry) - await ctx.plugin({ - name: 'activity-invariant-probe', - apply(child: Context) { child.provide('activities', probe) }, - }) - await ctx.plugin(ProcessInvariant) - if (listener === undefined) throw new Error('activity invariant did not subscribe to visible-set changes') - return (visible, owner) => { - current = visible - listener!(owner) - } -} - -describe('process-registry invariants', () => { - it('accepts coherent running and terminal snapshots', async () => { - const notify = await setup([RUNNING]) - expect(() => { notify([BASE]) }).not.toThrow() - expect(() => { notify([{ ...BASE, id: ActivityId('workflow-2'), kind: 'workflow' }]) }) - .not.toThrow() - }) - - it.each([ - [{ ...BASE, id: ActivityId('-1'), kind: '' as ActivitySnapshot['kind'] }, /positive ordinal/], - [{ ...BASE, id: ActivityId('other-1') }, /must be "bash-" followed by a positive ordinal/], - [{ ...BASE, id: ActivityId('bash-0') }, /positive ordinal/], - [{ ...BASE, label: '' }, /label must be non-empty/], - [{ ...BASE, startedAt: -1 }, /startedAt must be a non-negative epoch integer/], - [{ ...BASE, status: 'running' as const, finishedAt: 20 }, /finishedAt must be present exactly for a terminal status/], - [{ ...RUNNING, status: 'killed' as const }, /finishedAt must be present exactly for a terminal status/], - [{ ...BASE, finishedAt: 9 }, /no earlier than startedAt/], - [{ ...BASE, outputEarliest: 13 }, /0 <= outputEarliest <= outputTotal/], - [{ ...BASE, outputTotal: -1, outputEarliest: 0 }, /0 <= outputEarliest <= outputTotal/], - ] as const)('rejects an incoherent registry snapshot', async (snapshot, message) => { - const notify = await setup() - expect(() => { notify([snapshot]) }).toThrow(message) - }) - - it('rejects an incoherent record already present at installation', async () => { - await expect(setup([{ ...BASE, label: '' }])).rejects.toThrow(/label must be non-empty/) - }) -}) diff --git a/packages/activity/activity/tests/service.spec.ts b/packages/activity/activity/tests/service.spec.ts deleted file mode 100644 index 2dd685c1d3..0000000000 --- a/packages/activity/activity/tests/service.spec.ts +++ /dev/null @@ -1,98 +0,0 @@ -import { describe, expect, expectTypeOf, it, vi } from 'vitest' -import { Context } from '@deepseek-ai/cordis' -import type { SessionId } from '@deepseek-ai/dsh-session' -import ActivityRegistry, { ActivityId, pumpActivityOutput } from '@deepseek-ai/dsh-activity' -import type { ActivityAppendOptions, ActivityHandle, ActivityPumpSource, ActivitySnapshot } from '@deepseek-ai/dsh-activity' - -/** Record every append so pump behavior is observable without a registry. */ -function recordingHandle(): { handle: ActivityHandle; appends: { text: string; options?: ActivityAppendOptions }[] } { - const appends: { text: string; options?: ActivityAppendOptions }[] = [] - const handle: ActivityHandle = { - id: ActivityId('bash-1'), - append(text, options) { appends.push({ text, ...options !== undefined ? { options } : {} }) }, - updateDetail() {}, - end() {}, - } - return { handle, appends } -} - -/** A scripted source: each read() shifts the next scripted result. */ -function scriptedSource( - reads: { text: string; lossy?: boolean }[], - channel?: 'stdout' | 'stderr', -): { source: ActivityPumpSource; offsets: number[] } { - const offsets: number[] = [] - let offset = 0 - const source: ActivityPumpSource = { - ...channel !== undefined ? { channel } : {}, - read(fromByte) { - offsets.push(fromByte) - const next = reads.shift() ?? { text: '' } - offset += Buffer.byteLength(next.text, 'utf8') - return { text: next.text, nextOffset: offset, lossy: next.lossy ?? false } - }, - } - return { source, offsets } -} - -describe('ActivityRegistry seam', () => { - it('refuses to mount the abstract Service Definition directly', async () => { - const ctx = new Context() - await expect(ctx.plugin(ActivityRegistry as unknown as () => void)) - .rejects.toThrow(/load an implementation such as @deepseek-ai\/dsh-activity-local/) - }) - - it('preserves the SessionId brand on public owner snapshots', () => { - expectTypeOf().toEqualTypeOf() - }) -}) - -describe('pumpActivityOutput', () => { - it('rejects a non-positive poll interval before touching any source', async () => { - const { handle } = recordingHandle() - await expect(pumpActivityOutput(handle, [], { pollMs: 0, done: Promise.resolve() })) - .rejects.toThrow(/invalid pump pollMs/) - }) - - it('copies labeled deltas at the poll cadence and resumes each source at its own offset', async () => { - vi.useFakeTimers() - try { - const { handle, appends } = recordingHandle() - let settle!: () => void - const done = new Promise((resolve) => { settle = resolve }) - const out = scriptedSource([{ text: 'a' }, { text: 'bc' }], 'stdout') - const err = scriptedSource([{ text: '' }, { text: 'E' }], 'stderr') - const pump = pumpActivityOutput(handle, [out.source, err.source], { pollMs: 50, done }) - - await vi.advanceTimersByTimeAsync(50) - settle() - await pump - expect(appends).toEqual([ - { text: 'a', options: { channel: 'stdout' } }, - { text: 'bc', options: { channel: 'stdout' } }, - { text: 'E', options: { channel: 'stderr' } }, - ]) - // Every read resumed from the previous nextOffset, never from a shared cursor. - expect(out.offsets).toEqual([0, 1, 3]) - expect(err.offsets).toEqual([0, 0, 1]) - // Settlement cleared the raced poll timer instead of leaving it pending. - expect(vi.getTimerCount()).toBe(0) - } finally { - vi.useRealTimers() - } - }) - - it('marks a lossy source read as a gap so observers see the discontinuity', async () => { - const { handle, appends } = recordingHandle() - const { source } = scriptedSource([{ text: 'tail', lossy: true }]) - await pumpActivityOutput(handle, [source], { pollMs: 1, done: Promise.resolve() }) - expect(appends).toEqual([{ text: 'tail', options: { gapBefore: true } }]) - }) - - it('treats a rejected done as settlement and still drains the final bytes', async () => { - const { handle, appends } = recordingHandle() - const { source } = scriptedSource([{ text: 'last' }]) - await pumpActivityOutput(handle, [source], { pollMs: 1, done: Promise.reject(new Error('producer broke')) }) - expect(appends).toEqual([{ text: 'last' }]) - }) -}) diff --git a/packages/activity/activity/tsconfig.json b/packages/activity/activity/tsconfig.json deleted file mode 100644 index f4deee6327..0000000000 --- a/packages/activity/activity/tsconfig.json +++ /dev/null @@ -1,36 +0,0 @@ -{ - "extends": "../../../tsconfig.base.json", - "compilerOptions": { - "rootDir": "src", - "outDir": "lib/types" - }, - "include": [ - "src" - ], - "references": [ - { - "path": "../../../vendor/cosmokit" - }, - { - "path": "../../../vendor/cordis" - }, - { - "path": "../../util/brand" - }, - { - "path": "../../core/agent" - }, - { - "path": "../../core/session" - }, - { - "path": "../../llm/llm" - }, - { - "path": "../../jobs/jobs" - }, - { - "path": "../../runtime-diagnostics/invariants" - } - ] -} diff --git a/packages/api/activity-controller/README.i18n.yaml b/packages/api/activity-controller/README.i18n.yaml deleted file mode 100644 index 85ebf647c1..0000000000 --- a/packages/api/activity-controller/README.i18n.yaml +++ /dev/null @@ -1,6 +0,0 @@ -# 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 packages/api/activity-controller/README.md -README.md: ffdf97aa94ab808ea4f95a9b8b8a36e3e04f43ed -README.zh.md: 580d00a11d3e8743d606c9c9ca98c4553235cc50 diff --git a/packages/api/activity-controller/README.md b/packages/api/activity-controller/README.md deleted file mode 100644 index ffdf97aa94..0000000000 --- a/packages/api/activity-controller/README.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -description: "Activity Remote streams for browsers: the activity.control roster stream, per-activity activity.observe output streams with flushMs coalescing and maxFrameBytes budgets, and the ctx.activityFeed client model." -kind: "package-reference" ---- - -# @deepseek-ai/dsh-api-activity-controller - -English | [中文](README.zh.md) - -## Summary - -`dsh-api-activity-controller` streams the live-activity plane to browsers: a client follows one roster stream for every visible task row and opens one observation stream per expanded panel, resuming across reconnects from its own cursor. A pure read surface — it starts nothing, cancels nothing, and never touches the model-facing consuming cursors; the wire path reads only the registry's non-consuming offsets. A composition without `ctx.activities` still serves an empty baseline, so the client degrades to no live rows rather than an error. - -## Table of Contents - -- [Use this package](#use-this-package) -- [Understand the implementation](#understand-the-implementation) -- [Further Exploration](#further-exploration) -- [Model Experience](#model-experience) -- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work) -- [Dev Note](#dev-note) - ------ - - -## Use this package - -Mount the host row beside `dsh-typert-registry` and load the client half through the plugin manifest; UI features then consume `ctx.activityFeed` instead of raw streams. - -### The two Remote streams - -The Host `ActivityController` (namespace `activity`) exposes two `@Remote({ mode: 'stream' })` methods: - -- `control(signal)` — one complete roster baseline, then whole-bucket replacement frames per owner session on every registry change (the self-healing shape the session control stream uses for jobs). A composition without the registry serves an empty baseline. The Remote tier deliberately serves every session's rows to any connected browser, and `observe` satisfies the registry's owner fence with the mirrored owner: the per-session fence is an in-process contract, and this single-user local BFF reads across it exactly as the session control stream does for `jobsBySession`. -- `observe({ activityId, from? }, signal)` — one `opened` anchor, coalesced `output` frames (`flushMs` window, `maxFrameBytes` soft budget; one larger chunk ships whole), then one terminal `status` after the settled activity is drained, after which the generation closes normally. Reconnecting callers resume by passing the last frame's `next`; a resume behind the retained window arrives flagged `lossy`. Status rides the same stream as output, so settlement can never race a still-open output channel. - -| Config | Default | Meaning | -|---|---|---| -| `flushMs` | `100` | Coalescing window after new output before an observation read. | -| `maxFrameBytes` | `65536` | Soft byte budget per observation output frame. | - -The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-api-activity-controller) is the exhaustive source for every accepted field. - -### The client feed - -The client half (`./client`) installs `ctx.activityFeed`: `ClientActivityModel` mirrors the roster (last-wins buckets, generation replace) and accumulates each observed activity's bounded render tail, and `ClientActivityFeed.observe(id)` opens reference-counted observation streams that resume from the model's cursor across carrier generations. - ------ - - -## Understand the implementation - -
        -Implementation internals — click to expand - -The Host side mirrors the registry into owner buckets (`ActivityFeed`), fans control frames out to per-generation followers, and runs each observation as an async generator that subscribes before its first read so no append lands between anchor and stream. The client side keeps observation state per activity with a resume cursor; release closures bind the exact entry they were minted for, so a superseded observation's late release can neither tear down nor clear its successor. - -| File | Role | -|---|---| -| [`src/index.ts`](src/index.ts) | `ActivityController`: the two Remote stream methods | -| [`src/feed.ts`](src/feed.ts) | Owner-bucket roster mirror and control-stream followers | -| [`src/observe.ts`](src/observe.ts) | Per-activity observation generator: anchor, coalescing, terminal status | -| [`src/client/model.ts`](src/client/model.ts) | Roster and observation state with the bounded render tail | -| [`src/client/service.ts`](src/client/service.ts) | `ctx.activityFeed`: reference-counted observation streams | -| [`src/client/index.ts`](src/client/index.ts) | Client plugin: roster stream wiring and the service install | - -
        - ------ - - -## Further Exploration - -- [`dsh-activity`](../../activity/activity/README.md) — the observation contract this transport reads. -- [`dsh-client-ui-activity`](../../client/ui-activity/README.md) — the task list rendering `ctx.activityFeed`. -- [docs/subsystems/activity.md](../../../docs/subsystems/activity.md) — the plane end to end, wire shapes included. - ------ - - -## Model Experience - -None, as activity transport is browser and Host observation state and registers no prompt, tool, or session event. - -#### KV Cache effect - -None; the package never assembles or alters provider requests. - -## Known Limitations and Deferred Work - - - -These limits define when the transport is a poor fit. They are current package constraints, not a task backlog. - -- **Registry presence is sampled at construction** — a registry mounted after the controller stays unobserved until the controller reloads. -- **The roster names no watermark** — an observation stream anchors itself; correlating roster rows against observation offsets is client policy. - - -### Dev Note - -
        -Working context for maintainers — click to expand - -None. - -
        diff --git a/packages/api/activity-controller/README.zh.md b/packages/api/activity-controller/README.zh.md deleted file mode 100644 index 580d00a11d..0000000000 --- a/packages/api/activity-controller/README.zh.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -description: "面向浏览器的 Activity Remote 流:activity.control roster 流、带 flushMs 合并与 maxFrameBytes 预算的逐活动 activity.observe 输出流,以及 ctx.activityFeed 客户端模型。" -kind: "package-reference" ---- - -# @deepseek-ai/dsh-api-activity-controller - -[English](README.md) | 中文 - -## 概述 - -`dsh-api-activity-controller` 把实时活动面流式提供给浏览器:客户端跟随一条 roster 流获得每个可见任务行,并为每个展开的面板打开一条观察流,重连后从自己的游标续传。它是纯读表面——什么都不启动、什么都不取消、从不触碰模型可见的消费游标;线路路径只读注册表的非消费偏移。没有 `ctx.activities` 的组合仍提供空 baseline,客户端退化为没有实时行而非报错。 - -## 目录 - -- [使用本包](#use-this-package) -- [理解实现](#understand-the-implementation) -- [进一步探索](#further-exploration) -- [模型体验](#model-experience) -- [已知限制与延期工作](#known-limitations-and-deferred-work) -- [开发备注](#dev-note) - ------ - - -## 使用本包 - -在 `dsh-typert-registry` 旁挂载宿主行,并经插件清单加载客户端半侧;UI 功能随即消费 `ctx.activityFeed` 而非裸流。 - -### 两条 Remote 流 - -宿主 `ActivityController`(命名空间 `activity`)暴露两个 `@Remote({ mode: 'stream' })` 方法: - -- `control(signal)`——一份完整 roster baseline,之后每次注册表变化按 owner 会话推送整桶替换帧(与 session control 流承载 jobs 的自愈形态一致)。没有注册表的组合返回空 baseline。Remote 层有意把所有会话的行提供给任何已连接的浏览器,`observe` 以镜像到的 owner 替调用方满足注册表的 owner 栅栏:按会话的栅栏是进程内契约,这个单用户本地 BFF 跨栅栏读取,与 session control 流对 `jobsBySession` 的做法完全一致。 -- `observe({ activityId, from? }, signal)`——一帧 `opened` 锚点、合并后的 `output` 帧(`flushMs` 窗口,`maxFrameBytes` 软预算;单个更大的 chunk 整块发出),已结算活动排空后一帧终态 `status`,随后本代正常关闭。重连调用方传上一帧的 `next` 续传;落后于留存窗口的续传带 `lossy` 标记到达。status 与 output 走同一条流,结算绝不会与仍开放的输出通道赛跑。 - -| 配置 | 默认 | 含义 | -|---|---|---| -| `flushMs` | `100` | 新输出后进行一次观察读取前的合并窗口。 | -| `maxFrameBytes` | `65536` | 每个观察输出帧的软字节预算。 | - -生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-api-activity-controller)是每个可接受字段的穷尽来源。 - -### 客户端 feed - -客户端半侧(`./client`)安装 `ctx.activityFeed`:`ClientActivityModel` 镜像 roster(last-wins 桶、按代整体替换)并累积每个被观察活动的有界渲染尾部,`ClientActivityFeed.observe(id)` 打开引用计数的观察流,跨 carrier 代从模型游标续传。 - ------ - - -## 理解实现 - -
        -实现内幕——点击展开 - -宿主侧把注册表镜像进 owner 桶(`ActivityFeed`),向每代 follower 扇出 control 帧,并把每个观察跑成先订阅再首读的 async generator,锚点与流之间不会漏 append。客户端侧按活动保存观察状态与续传游标;release 闭包绑定自己创建时的那个条目,被替代观察的迟到 release 既拆不掉也清不掉后继者。 - -| 文件 | 角色 | -|---|---| -| [`src/index.ts`](src/index.ts) | `ActivityController`:两个 Remote 流方法 | -| [`src/feed.ts`](src/feed.ts) | owner 桶 roster 镜像与 control 流 follower | -| [`src/observe.ts`](src/observe.ts) | 逐活动观察 generator:锚点、合并、终态 status | -| [`src/client/model.ts`](src/client/model.ts) | roster 与观察状态,含有界渲染尾部 | -| [`src/client/service.ts`](src/client/service.ts) | `ctx.activityFeed`:引用计数的观察流 | -| [`src/client/index.ts`](src/client/index.ts) | 客户端插件:roster 流接线与服务安装 | - -
        - ------ - - -## 进一步探索 - -- [`dsh-activity`](../../activity/activity/README.zh.md)——本传输所读的观察契约。 -- [`dsh-client-ui-activity`](../../client/ui-activity/README.zh.md)——渲染 `ctx.activityFeed` 的任务列表。 -- [docs/subsystems/activity.md](../../../docs/subsystems/activity.zh.md)——端到端的观察面,含线路形态。 - ------ - - -## 模型体验 - -无:activity 传输是浏览器与宿主的观察状态,不注册任何 prompt、工具或会话事件。 - -#### KV Cache 影响 - -无;本包从不组装或改动 provider 请求。 - -## 已知限制与延期工作 - - - -这些限制说明该传输何时不合适。它们是当前包约束,不是任务积压。 - -- **注册表存在性在构造时采样**——controller 之后才挂载的注册表在 controller 重载前保持不被观察。 -- **roster 不命名水位**——观察流自行锚定;把 roster 行与观察偏移相关联是客户端策略。 - - -### 开发备注 - -
        -维护者的工作上下文——点击展开 - -无。 - -
        diff --git a/packages/api/activity-controller/package.json b/packages/api/activity-controller/package.json deleted file mode 100644 index a5250ad8ac..0000000000 --- a/packages/api/activity-controller/package.json +++ /dev/null @@ -1,103 +0,0 @@ -{ - "name": "@deepseek-ai/dsh-api-activity-controller", - "description": "Activity Remote streams: the live-activity roster and per-activity non-consuming output observation", - "version": "0.1.2-alpha.2", - "publishConfig": { - "access": "public" - }, - "repository": { - "type": "git", - "url": "git+https://github.com/deepseek-ai/deepseek-harness.git", - "directory": "packages/api/activity-controller" - }, - "type": "module", - "main": "lib/index.js", - "types": "lib/types/index.d.ts", - "exports": { - ".": { - "types": "./lib/types/index.d.ts", - "default": "./lib/index.js" - }, - "./invariant": { - "types": "./lib/types/invariant.d.ts", - "default": "./lib/invariant.js" - }, - "./types": { - "types": "./lib/types/types.d.ts", - "default": "./lib/types/types.js" - }, - "./client": { - "types": "./lib/types/client/index.d.ts", - "default": "./lib/client.js" - }, - "./typert": { - "types": "./lib/typert.host.d.ts", - "default": "./lib/typert.host.js" - }, - "./remote": { - "types": "./lib/typert.remote-client.d.ts", - "default": "./lib/typert.remote-client.js" - }, - "./src/*": "./src/*", - "./package.json": "./package.json" - }, - "scripts": { - "bundle": "tsdown", - "watch": "tsdown --watch" - }, - "files": [ - "lib/index.js", - "lib/invariant.js", - "lib/client.js", - "lib/types/**/*.js", - "lib/types/**/*.d.ts", - "lib/typert.host.js", - "lib/typert.host.d.ts", - "lib/typert.remote-client.js", - "lib/typert.remote-client.d.ts" - ], - "license": "MIT", - "dependencies": { - "@deepseek-ai/schemastery": "workspace:^", - "zod": "^4.4.3" - }, - "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-activity": "workspace:^", - "@deepseek-ai/dsh-agent": "workspace:^", - "@deepseek-ai/dsh-api-gateway": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-client-store": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-jobs": "workspace:^", - "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-typert-protocol": "workspace:^" - }, - "devDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-activity": "workspace:^", - "@deepseek-ai/dsh-activity-local": "workspace:^", - "@deepseek-ai/dsh-agent": "workspace:^", - "@deepseek-ai/dsh-api-gateway": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-client-store": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-jobs": "workspace:^", - "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-typert-protocol": "workspace:^" - }, - "dsh": { - "client": { - "external": [ - "@deepseek-ai/dsh-api-gateway/client" - ], - "inject": [ - "@deepseek-ai/dsh-api-gateway", - "@deepseek-ai/dsh-client-connection" - ], - "platform": "web" - } - } -} diff --git a/packages/api/activity-controller/src/client/index.ts b/packages/api/activity-controller/src/client/index.ts deleted file mode 100644 index 7338ae3b9b..0000000000 --- a/packages/api/activity-controller/src/client/index.ts +++ /dev/null @@ -1,86 +0,0 @@ -/** Activity-specific adapter for the Gateway-owned snapshot stream lifecycle. */ - -import type { Context } from '@deepseek-ai/cordis' -import { - RemoteSnapshotStream, - RemoteStreamCarrierError, - type ClientRemote, -} from '@deepseek-ai/dsh-api-gateway/client' -import type { ActivityControlFrame } from '../types.ts' -import { ClientActivityModel } from './model.ts' -import { ClientActivityFeed } from './service.ts' -import type { ActivityRemote } from './service.ts' - -export type { ActivityFeedPhase, ActivityFeedSnapshot, ObservedActivity } from './model.ts' -export type { ActivityFeedSource, ActivityRemote, IActivityFeed } from './service.ts' -export type { ActivityId } from '@deepseek-ai/dsh-activity/brand' -export type { ActivityRow } from '../types.ts' - -type ActivityStreamRemote = Pick & { readonly activity: ActivityRemote } - -type ActivityBaselineFrame = Extract -type ActivityRowsFrame = Extract - -declare module '@deepseek-ai/cordis' { - interface Context { - /** React-free client activity roster and observation control. */ - activityFeed: import('./service.ts').IActivityFeed - } -} - -/** Required Client Remote services. */ -export const inject = ['remote', 'remote.activity'] - -/** - * Install the client activity model, its service face, and the reconnecting - * roster stream. - * @param ctx - client root Context. - */ -export function apply(ctx: Context): void { - const raw = ctx.remote as ActivityStreamRemote - // Resolve the child namespace to a concrete value while this plugin's - // context is current: later stream (re)opens run on caller stacks (a React - // event, a carrier retry) whose dynamic context has not declared - // `remote.activity`, and a property access there fails the inject check. - const remote: ActivityStreamRemote = { - $stream: options => raw.$stream(options), - activity: raw.activity, - } - const model = new ClientActivityModel() - new ClientActivityFeed(ctx, remote, model) - const control = createActivityRosterStream(remote, model) - control.start() - ctx.effect( - () => async () => { await control.dispose() }, - 'activity-controller.client.control', - ) -} - -/** - * Create the reconnecting roster stream feeding one client model. - * @param remote - generated activity namespace and Gateway stream factory. - * @param model - roster sink. - * @returns an unstarted stream owned by the client activity runtime. - */ -export function createActivityRosterStream( - remote: ActivityStreamRemote, - model: ClientActivityModel, -): RemoteSnapshotStream { - const stream = remote.$stream({ - name: 'activity roster stream', - open: signal => remote.activity.control(signal), - ended: accepted => accepted - ? new RemoteStreamCarrierError('activity roster stream ended without a terminal result') - : new Error('activity roster stream ended before its opening baseline'), - }) - return new RemoteSnapshotStream(stream, { - name: 'activity roster stream', - isSnapshot: (frame): frame is ActivityBaselineFrame => frame.type === 'baseline', - replace: (frame) => { model.replaceBaseline(frame.activities) }, - update: (frame) => { model.replaceBucket(frame.sessionId, frame.activities) }, - failed: () => { - // The previous roster stays published while the stream retries; a - // terminal protocol failure leaves the last snapshot in place. - }, - }) -} diff --git a/packages/api/activity-controller/src/client/model.ts b/packages/api/activity-controller/src/client/model.ts deleted file mode 100644 index 75354f1255..0000000000 --- a/packages/api/activity-controller/src/client/model.ts +++ /dev/null @@ -1,216 +0,0 @@ -/** Client-side activity state model shared by Remote transport and UI projection. */ - -import { notifySubscribers } from '@deepseek-ai/dsh-client-store' -import type { ActivityId } from '@deepseek-ai/dsh-activity/brand' -import type { ActivityObserveFrame, ActivityRow } from '../types.ts' - -/** Bounded per-activity render tail, in UTF-16 code units. */ -const RENDER_TAIL_LIMIT = 128 * 1024 - -/** Roster arrival lifecycle: `pending` until the first baseline lands. */ -export type ActivityFeedPhase = 'pending' | 'ready' - -/** One observed activity's live view state. */ -export interface ObservedActivity { - readonly activityId: ActivityId - /** Accumulated output tail, bounded to the render limit. */ - readonly text: string - /** True when bytes before {@link text} were dropped (eviction, resume gap, or the render bound). */ - readonly gapBefore: boolean - /** Latest status delivered on the observation stream. */ - readonly status: ActivityRow['status'] - readonly detail?: string - /** True while the observation stream is open and the activity has not settled. */ - readonly streaming: boolean - /** Terminal observation failure, when the stream ended abnormally. */ - readonly error?: string -} - -/** Immutable client activity state. */ -export interface ActivityFeedSnapshot { - /** Roster rows per owner session; the empty key holds unowned activities. */ - readonly rowsBySession: Readonly> - /** Live observation state keyed by activity id. */ - readonly observed: Readonly> - readonly phase: ActivityFeedPhase -} - -const UNOWNED = '' - -/** Mutable observation bookkeeping behind one {@link ObservedActivity} view. */ -interface ObservedState { - view: ObservedActivity - /** Resume offset for the next generation's `from`. */ - cursor: number | undefined -} - -/** - * Owns the client roster mirror and per-activity observation state. Pure data - * plus subscriptions — transport wiring stays in the client plugin, UI stays - * in slot components. - */ -export class ClientActivityModel { - private rowsBySession: Readonly> = {} - private readonly observedStates = new Map() - private phase: ActivityFeedPhase = 'pending' - private readonly listeners = new Set<() => void>() - private snapshotCache: ActivityFeedSnapshot = { rowsBySession: {}, observed: {}, phase: 'pending' } - private snapshotDirty = false - - /** - * Read the identity-stable current snapshot. - * @returns the cached snapshot, rebuilt only after a change. - */ - getSnapshot(): ActivityFeedSnapshot { - if (this.snapshotDirty) { - const observed: Record = {} - for (const [id, state] of this.observedStates) observed[id] = state.view - this.snapshotCache = { rowsBySession: this.rowsBySession, observed, phase: this.phase } - this.snapshotDirty = false - } - return this.snapshotCache - } - - /** - * Subscribe to snapshot changes. - * @param listener - invalidation callback. - * @returns unsubscribe function. - */ - subscribe(listener: () => void): () => void { - this.listeners.add(listener) - return () => { this.listeners.delete(listener) } - } - - /** - * Replace the whole roster from a generation baseline. - * @param rows - every visible row across all owner buckets. - */ - replaceBaseline(rows: readonly ActivityRow[]): void { - const next: Record = {} - for (const row of rows) { - const key = row.sessionId ?? UNOWNED - ;(next[key] ??= []).push(row) - } - this.rowsBySession = next - this.phase = 'ready' - this.changed() - } - - /** - * Replace one owner bucket wholesale; an empty replacement drops the key. - * @param sessionId - owner session, or undefined for the unowned bucket. - * @param rows - the bucket's complete visible rows. - */ - replaceBucket(sessionId: string | undefined, rows: readonly ActivityRow[]): void { - const key = sessionId ?? UNOWNED - if (rows.length === 0) { - this.rowsBySession = Object.fromEntries( - Object.entries(this.rowsBySession).filter(([bucket]) => bucket !== key)) - } else { - this.rowsBySession = { ...this.rowsBySession, [key]: rows } - } - this.changed() - } - - /** - * The resume offset for one activity's next observation generation. - * @param id - observed activity. - * @returns the last accepted `next`, or undefined for a fresh observation. - */ - cursorOf(id: ActivityId): number | undefined { - return this.observedStates.get(String(id))?.cursor - } - - /** - * Install or reset observation state when a generation's anchor arrives. - * @param id - observed activity. - * @param frame - the generation's `opened` anchor. - */ - observeOpened(id: ActivityId, frame: Extract): void { - const existing = this.observedStates.get(String(id)) - // A fresh view anchored past offset zero starts after an evicted head - // (fresh observations anchor at the registry's earliest retained byte), so - // it owes the same gap mark a live observer earned from lossy reads. A - // resume that already accumulated text keeps its recorded gap state. - const freshPastHead = (existing === undefined || existing.view.text === '') && frame.from > 0 - const view: ObservedActivity = { - activityId: id, - text: existing?.view.text ?? '', - gapBefore: (existing?.view.gapBefore ?? false) || frame.from < frame.earliest || freshPastHead, - status: frame.status, - ...frame.detail !== undefined ? { detail: frame.detail } : {}, - streaming: true, - } - this.observedStates.set(String(id), { view, cursor: frame.from }) - this.changed() - } - - /** - * Append one output frame's chunks to the bounded render tail. - * @param id - observed activity. - * @param frame - a coalesced `output` frame. - */ - observeOutput(id: ActivityId, frame: Extract): void { - const state = this.observedStates.get(String(id)) - /* v8 ignore next -- frames arrive only between opened and stop for a tracked id. */ - if (state === undefined) return - let text = state.view.text + frame.chunks.map(chunk => chunk.text).join('') - let gapBefore = state.view.gapBefore || frame.lossy === true - || frame.chunks.some(chunk => chunk.gapBefore === true) - if (text.length > RENDER_TAIL_LIMIT) { - let cut = text.length - RENDER_TAIL_LIMIT - // Never split a surrogate pair at the render bound. - const unit = text.charCodeAt(cut) - if (unit >= 0xDC00 && unit <= 0xDFFF) cut += 1 - text = text.slice(cut) - gapBefore = true - } - state.view = { ...state.view, text, gapBefore } - state.cursor = frame.next - this.changed() - } - - /** - * Record the terminal status delivered at the end of the observation stream. - * @param id - observed activity. - * @param frame - the terminal `status` frame. - */ - observeStatus(id: ActivityId, frame: Extract): void { - const state = this.observedStates.get(String(id)) - /* v8 ignore next -- frames arrive only between opened and stop for a tracked id. */ - if (state === undefined) return - state.view = { - ...state.view, - status: frame.status, - ...frame.detail !== undefined ? { detail: frame.detail } : {}, - streaming: false, - } - this.changed() - } - - /** - * Record a terminal observation failure. - * @param id - observed activity. - * @param error - the stream's terminal failure. - */ - observeFailed(id: ActivityId, error: unknown): void { - const state = this.observedStates.get(String(id)) - if (state === undefined) return - state.view = { ...state.view, streaming: false, error: String(error) } - this.changed() - } - - /** - * Drop observation state after the last observer stops. - * @param id - the no-longer-observed activity. - */ - observeStopped(id: ActivityId): void { - if (!this.observedStates.delete(String(id))) return - this.changed() - } - - private changed(): void { - this.snapshotDirty = true - notifySubscribers(this.listeners, 'activity feed') - } -} diff --git a/packages/api/activity-controller/src/client/service.ts b/packages/api/activity-controller/src/client/service.ts deleted file mode 100644 index 2947e5bf04..0000000000 --- a/packages/api/activity-controller/src/client/service.ts +++ /dev/null @@ -1,164 +0,0 @@ -/** React-free client activity service: roster snapshot plus observation control. */ - -import { Service, type Context } from '@deepseek-ai/cordis' -import { RemoteStreamCarrierError, type ClientRemote } from '@deepseek-ai/dsh-api-gateway/client' -import type {} from '@deepseek-ai/dsh-api-activity-controller/remote' -import type { TypertClientRemote } from '@deepseek-ai/dsh-typert-protocol' -import type { ActivityId } from '@deepseek-ai/dsh-activity/brand' -import type { ActivityObserveFrame } from '../types.ts' -import type { ActivityFeedSnapshot, ClientActivityModel } from './model.ts' - -/** Complete generated `ctx.remote.activity` namespace. */ -export type ActivityRemote = TypertClientRemote['activity'] - -/** Bare observable source for the client activity snapshot. */ -export interface ActivityFeedSource { - /** Read the identity-stable current snapshot. */ - getSnapshot(): ActivityFeedSnapshot - /** - * Subscribe to snapshot changes. - * @param listener - invalidation callback. - * @returns unsubscribe function. - */ - subscribe(listener: () => void): () => void -} - -/** The activity feed's client service face. */ -export interface IActivityFeed { - /** Roster rows, observation state, and arrival phase. */ - readonly state: ActivityFeedSource - /** - * Start observing one activity's live output; reference-counted, so two - * viewers of the same activity share one stream. - * @param id - activity to observe. - * @returns stop function releasing this observer's reference. - */ - observe(id: ActivityId): () => void -} - -/** One reference-counted observation stream. */ -interface ObservationEntry { - refs: number - stopped: boolean - dispose: () => Promise -} - -/** Remote face the observation runner drives. */ -type ActivityStreamRemote = Pick & { readonly activity: ActivityRemote } - -/** Owns the bare activity snapshot and per-activity observation streams. */ -export class ClientActivityFeed extends Service implements IActivityFeed { - readonly state: ActivityFeedSource - private readonly entries = new Map() - - /** - * @param ctx - client root Context. - * @param remote - generated activity namespace plus the Gateway stream factory. - * @param model - shared client activity model. - */ - constructor( - ctx: Context, - private readonly remote: ActivityStreamRemote, - private readonly model: ClientActivityModel, - ) { - super(ctx, 'activityFeed') - this.state = model - ctx.effect(() => () => { - const open = [...this.entries.values()] - this.entries.clear() - for (const entry of open) { - entry.stopped = true - void entry.dispose() - } - }, 'activity-controller.client.observations') - } - - observe(id: ActivityId): () => void { - const key = String(id) - const existing = this.entries.get(key) - if (existing !== undefined && !existing.stopped) { - existing.refs += 1 - return this.releaser(key, existing) - } - const entry = this.startObservation(id) - this.entries.set(key, entry) - return this.releaser(key, entry) - } - - /** - * Release closures bind the exact entry they were minted for, never the - * map's current occupant: a later `observe()` on the same id may have - * replaced a stopped entry, and decrementing or disposing through the key - * alone would tear down that newer stream's references. - */ - private releaser(key: string, entry: ObservationEntry): () => void { - let released = false - return () => { - if (released) return - released = true - entry.refs -= 1 - if (entry.refs > 0) return - if (this.entries.get(key) === entry) this.entries.delete(key) - entry.stopped = true - void entry.dispose().then(() => { - // Clear the view only while no successor observation holds the key: - // a re-expand inside the dispose round-trip already re-anchored the - // model, and a stale clear would blank its panel for good. - if (this.entries.has(key)) return - // The key is the stringified branded id this releaser was minted for. - this.model.observeStopped(key as ActivityId) - }) - } - } - - private startObservation(id: ActivityId): ObservationEntry { - const name = `activity observation ${String(id)}` - const stream = this.remote.$stream({ - name, - open: (signal) => { - const from = this.model.cursorOf(id) - return this.remote.activity.observe( - { activityId: id, ...from !== undefined ? { from } : {} }, - signal, - ) - }, - // A premature end after the anchor is retryable (a Host reload closes the - // generation); resuming from the cursor loses nothing. An end before the - // anchor is terminal. - ended: accepted => accepted - ? new RemoteStreamCarrierError(`${name} ended before settlement`) - : new Error(`${name} ended before its anchor`), - }) - const entry: ObservationEntry = { - refs: 1, - stopped: false, - dispose: () => stream.dispose(), - } - void (async () => { - try { - for await (const item of stream) { - const frame = item.value - if (frame.type === 'opened') { - this.model.observeOpened(id, frame) - item.accept() - continue - } - if (frame.type === 'output') { - this.model.observeOutput(id, frame) - continue - } - // Terminal status: leave the loop before the generation end is - // classified, then close the stream for good. - this.model.observeStatus(id, frame) - break - } - } catch (error) { - if (!entry.stopped) this.model.observeFailed(id, error) - } finally { - entry.stopped = true - void entry.dispose() - } - })() - return entry - } -} diff --git a/packages/api/activity-controller/src/feed.ts b/packages/api/activity-controller/src/feed.ts deleted file mode 100644 index 34091dad8d..0000000000 --- a/packages/api/activity-controller/src/feed.ts +++ /dev/null @@ -1,184 +0,0 @@ -/** Reconnect-safe activity roster producer over the optional `ctx.activities` registry. */ - -import type { Context } from '@deepseek-ai/cordis' -import type { Agent } from '@deepseek-ai/dsh-agent' -import type { ActivityRegistry, ActivitySnapshot } from '@deepseek-ai/dsh-activity' -import type { ActivityControlFrame, ActivityRow } from './types.ts' - -/** - * Project one registry snapshot into its browser-safe roster row. - * @param snapshot - fresh registry snapshot. - * @returns detached wire row for Remote consumers. - */ -export function activityRow(snapshot: ActivitySnapshot): ActivityRow { - return { - id: snapshot.id, - kind: snapshot.kind, - label: snapshot.label, - ...snapshot.ownerSession !== undefined ? { sessionId: snapshot.ownerSession } : {}, - ...snapshot.correlation !== undefined - ? { - correlation: { - ...snapshot.correlation.callId !== undefined ? { callId: snapshot.correlation.callId } : {}, - ...snapshot.correlation.jobId !== undefined ? { jobId: snapshot.correlation.jobId } : {}, - }, - } - : {}, - status: snapshot.status, - ...snapshot.detail !== undefined ? { detail: snapshot.detail } : {}, - startedAt: snapshot.startedAt, - ...snapshot.finishedAt !== undefined ? { finishedAt: snapshot.finishedAt } : {}, - outputTotal: snapshot.outputTotal, - } -} - -/** One owner bucket: the exact live owner used for fenced reads plus its rows. */ -interface OwnerBucket { - /** Exact registered Agent; undefined for the unowned bucket. */ - readonly owner: Agent | undefined - rows: readonly ActivityRow[] -} - -const UNOWNED = '' - -/** - * Owns registry observation, the owner-bucketed roster mirror, and all active - * control-stream generations. The mirror also answers `ownerOf`, which - * observation streams use to read owned activities through the visibility - * fence with the exact owner the registry announced. - */ -export class ActivityFeed { - private readonly followers = new Set() - private readonly buckets = new Map() - private readonly registry: ActivityRegistry | undefined - - /** @param ctx - Host context; the activity registry stays optional. */ - constructor(ctx: Context) { - this.registry = ctx.get('activities') - if (this.registry === undefined) return - const registry = this.registry - this.refresh(undefined) - for (const agent of ctx.get('agents')?.list() ?? []) this.refresh(agent) - registry.onActivitiesChanged((owner) => { - this.refresh(owner) - const bucket = this.buckets.get(owner?.id ?? UNOWNED) - this.publish({ - type: 'rows', - ...owner !== undefined ? { sessionId: owner.id } : {}, - activities: bucket?.rows ?? [], - }) - }) - ctx.effect(() => () => { - for (const follower of this.followers) follower.close() - this.followers.clear() - }, 'activity-controller.feed') - } - - /** - * Read the complete current roster synchronously. - * @returns every visible row across all owner buckets. - */ - baseline(): readonly ActivityRow[] { - return [...this.buckets.values()].flatMap(bucket => bucket.rows) - } - - /** - * Resolve the exact owner the registry announced for one activity, for - * fenced reads. `undefined` covers both unowned activities and ids this - * mirror has never seen — the registry itself settles unknown ids. - * @param id - activity id to resolve. - * @returns the exact live owner, or undefined. - */ - ownerOf(id: string): Agent | undefined { - for (const bucket of this.buckets.values()) { - if (bucket.rows.some(row => String(row.id) === id)) return bucket.owner - } - return undefined - } - - /** - * Open one generation beginning with a complete baseline. - * @param signal - generation cancellation. - * @returns baseline followed by whole-bucket replacement frames. - */ - async *follow(signal: AbortSignal): AsyncIterable { - signal.throwIfAborted() - const follower = new ActivityFollower() - this.followers.add(follower) - try { - yield { type: 'baseline', activities: this.baseline() } - yield* follower.read(signal) - } finally { - this.followers.delete(follower) - follower.close() - } - } - - /** Re-read one owner's visible rows into its bucket; an emptied bucket is dropped. */ - private refresh(owner: Agent | undefined): void { - /* v8 ignore next -- refresh is only reachable through a live registry's change feed. */ - if (this.registry === undefined) return - const rows = this.registry.list(owner) - .filter(snapshot => owner === undefined - ? snapshot.ownerSession === undefined - : snapshot.ownerSession === owner.id) - .map(activityRow) - const key = owner?.id ?? UNOWNED - if (rows.length === 0) { - this.buckets.delete(key) - return - } - this.buckets.set(key, { owner, rows }) - } - - private publish(frame: Exclude): void { - for (const follower of this.followers) follower.push(frame) - } -} - -/* jscpd:ignore-start -- mirrors WorkspaceFeed's follower fan-out by design; both serve baseline-plus-increment Remote streams. */ -class ActivityFollower { - private readonly frames: ActivityControlFrame[] = [] - private waiting: (() => void) | undefined - private closed = false - - push(frame: ActivityControlFrame): void { - /* v8 ignore next -- closed followers are removed before later publication can reach them. */ - if (this.closed) return - this.frames.push(frame) - this.waiting?.() - } - - close(): void { - if (this.closed) return - this.closed = true - this.waiting?.() - } - - async *read(signal: AbortSignal): AsyncIterable { - while (!this.closed && !signal.aborted) { - const frame = this.frames.shift() - if (frame !== undefined) { - yield frame - continue - } - await this.wait(signal) - } - } - - private wait(signal: AbortSignal): Promise { - return new Promise((resolve) => { - const finish = (): void => { - signal.removeEventListener('abort', finish) - /* v8 ignore next -- one read owns the sole installed wait callback. */ - if (this.waiting === finish) this.waiting = undefined - resolve() - } - this.waiting = finish - signal.addEventListener('abort', finish, { once: true }) - /* v8 ignore next -- native signals and the private queue cannot change during this synchronous setup. */ - if (signal.aborted || this.closed || this.frames.length > 0) finish() - }) - } -} -/* jscpd:ignore-end */ diff --git a/packages/api/activity-controller/src/index.ts b/packages/api/activity-controller/src/index.ts deleted file mode 100644 index a2d62c4a33..0000000000 --- a/packages/api/activity-controller/src/index.ts +++ /dev/null @@ -1,104 +0,0 @@ -/** - * Host Activity Remote owner: the live-activity roster stream and per-activity - * output observation. A pure read surface over the optional `ctx.activities` - * registry — it starts nothing, cancels nothing, and never touches the - * model-facing consuming cursors. Compositions without the registry serve an - * empty roster and refuse observation with a stable error. - */ - -import { Context } from '@deepseek-ai/cordis' -import z from '@deepseek-ai/schemastery' -import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol' -import type {} from '@deepseek-ai/dsh-activity' -import { ActivityFeed } from './feed.ts' -import { observeActivity } from './observe.ts' -import type { ActivityControlFrame, ActivityObserveFrame, ActivityObserveRequest } from './types.ts' - -export type * from './types.ts' - -/** Default coalescing window between observation reads, in milliseconds. */ -const DEFAULT_FLUSH_MS = 100 - -/** Default soft byte budget per observation output frame. */ -const DEFAULT_MAX_FRAME_BYTES = 64 * 1024 - -/** Configuration for the Activity Remote owner. */ -export interface Config { - /** Coalescing window after new output before an observation read, in milliseconds (default 100). */ - flushMs?: number - /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */ - maxFrameBytes?: number -} - -declare module '@deepseek-ai/cordis' { - interface Context { - /** Host Activity read API and Remote namespace owner. */ - activityController: ActivityController - } -} - -/** Host service backing the generated `ctx.remote.activity` namespace. */ -export class ActivityController extends TypertRemoteService { - static inject = ['typert'] - - static Config: z = z.object({ - flushMs: z.number() - .step(1) - .min(1) - .max(Number.MAX_SAFE_INTEGER) - .default(DEFAULT_FLUSH_MS), - maxFrameBytes: z.number() - .step(1) - .min(1) - .max(Number.MAX_SAFE_INTEGER) - .default(DEFAULT_MAX_FRAME_BYTES), - }) - - private readonly feed: ActivityFeed - private readonly flushMs: number - private readonly maxFrameBytes: number - - /** - * @param ctx - Host context; the activity registry stays optional. - * @param config - validated coalescing and framing bounds. - */ - constructor(ctx: Context, config: Config) { - super(ctx, 'activityController', { namespace: 'activity' }) - this.flushMs = (config as Required).flushMs - this.maxFrameBytes = (config as Required).maxFrameBytes - this.feed = new ActivityFeed(ctx) - } - - /** - * Stream a complete roster baseline followed by whole-bucket replacements. - * @param signal - generation cancellation. - * @returns baseline followed by per-owner roster replacement frames. - */ - @Remote({ mode: 'stream' }) - control(signal: AbortSignal): AsyncIterable { - return this.feed.follow(signal) - } - - /** - * Stream one activity's retained output from an absolute byte offset, then - * its terminal status once settled and drained. Non-consuming: the - * model-facing cursors never observe these reads. - * @param request - target activity and optional resume offset. - * @param signal - generation cancellation. - * @returns anchor, coalesced output frames, and the terminal status. - */ - @Remote({ mode: 'stream' }) - observe(request: ActivityObserveRequest, signal: AbortSignal): AsyncIterable { - const registry = this.ctx.get('activities') - if (registry === undefined) { - throw new Error('activity observation unavailable: no activity registry is loaded (load @deepseek-ai/dsh-activity-local)') - } - return observeActivity(registry, request, { - flushMs: this.flushMs, - maxFrameBytes: this.maxFrameBytes, - ownerOf: id => this.feed.ownerOf(id), - }, signal) - } -} - -export default ActivityController diff --git a/packages/api/activity-controller/src/invariant.ts b/packages/api/activity-controller/src/invariant.ts deleted file mode 100644 index f85e7460b8..0000000000 --- a/packages/api/activity-controller/src/invariant.ts +++ /dev/null @@ -1,23 +0,0 @@ -/** Package-owned invariant companion. @module @deepseek-ai/dsh-api-activity-controller/invariant */ - -/* jscpd:ignore-start */ -import type { Context } from '@deepseek-ai/cordis' -import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants' - -const PACKAGE_NAME = '@deepseek-ai/dsh-api-activity-controller' - -/** Cordis companion plugin name. */ -export const name = 'api-activity-controller-invariant' -/** Service required before the companion can reserve package ownership. */ -export const inject = ['invariants'] - -/** - * No runtime invariant: `@deepseek-ai/dsh-activity/invariant` owns snapshot relations; every roster - * generation is a full projection and observation reads are validated by the registry itself. - */ -const install: InvariantInstaller = () => {} - -/** Register this package's invariant companion. */ -export const apply = (ctx: Context): Promise<() => void> => - Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install)) -/* jscpd:ignore-end */ diff --git a/packages/api/activity-controller/src/observe.ts b/packages/api/activity-controller/src/observe.ts deleted file mode 100644 index f793b11496..0000000000 --- a/packages/api/activity-controller/src/observe.ts +++ /dev/null @@ -1,178 +0,0 @@ -/** Per-activity observation generations: anchor, coalesced output, terminal status. */ - -import type { ActivityRegistry, ActivitySnapshot } from '@deepseek-ai/dsh-activity' -import { ActivityId } from '@deepseek-ai/dsh-activity/brand' -import type { Agent } from '@deepseek-ai/dsh-agent' -import type { ActivityObserveFrame, ActivityObserveRequest, ActivityWireChunk } from './types.ts' - -/** Cadence and framing bounds for one observation generation. */ -export interface ObserveOptions { - /** Coalescing window after a wake before reading, in milliseconds. */ - readonly flushMs: number - /** - * Soft byte budget per `output` frame. Accumulated chunks flush once the - * budget is met; one chunk larger than the budget ships whole (the - * registry's retention cap is the hard bound on any single chunk). - */ - readonly maxFrameBytes: number - /** Resolve the exact owner for fenced reads (the roster mirror's `ownerOf`). */ - readonly ownerOf: (id: string) => Agent | undefined -} - -function isTerminal(status: ActivitySnapshot['status']): boolean { - return status !== 'running' -} - -/** Wake-flag waiter: a wake between waits is never lost. */ -class OutputWaiter { - private dirty = false - private resolve: (() => void) | undefined - - wake(): void { - this.dirty = true - this.resolve?.() - } - - /** - * Resolve on the next wake, immediately when one already arrived, or on abort. - * @param signal - generation cancellation. - */ - wait(signal: AbortSignal): Promise { - if (this.dirty || signal.aborted) { - this.dirty = false - return Promise.resolve() - } - return new Promise((resolve) => { - const finish = (): void => { - signal.removeEventListener('abort', finish) - /* v8 ignore next -- one wait owns the sole installed resolver. */ - if (this.resolve === finish) this.resolve = undefined - this.dirty = false - resolve() - } - this.resolve = finish - signal.addEventListener('abort', finish, { once: true }) - }) - } -} - -function sleep(ms: number, signal: AbortSignal): Promise { - if (signal.aborted) return Promise.resolve() - return new Promise((resolve) => { - const timer = setTimeout(done, ms) - function done(): void { - clearTimeout(timer) - signal.removeEventListener('abort', done) - resolve() - } - signal.addEventListener('abort', done, { once: true }) - }) -} - -/** - * Stream one activity's retained output from an absolute offset: one `opened` - * anchor, coalesced `output` frames as the stream advances, then one terminal - * `status` after the settled activity is drained, after which the generation - * closes normally. Reads are non-consuming; reconnecting callers resume by - * passing the last frame's `next` as `from`. - * @param registry - the live activity registry. - * @param request - target activity and optional resume offset. - * @param options - cadence, framing bounds, and owner resolution. - * @param signal - generation cancellation owned by the Remote stream carrier. - * @returns the observation frame sequence for one generation. - */ -export async function* observeActivity( - registry: ActivityRegistry, - request: ActivityObserveRequest, - options: ObserveOptions, - signal: AbortSignal, -): AsyncIterable { - if (request.from !== undefined && (!Number.isSafeInteger(request.from) || request.from < 0)) { - throw new Error(`invalid observe offset: expected a non-negative safe integer, got ${JSON.stringify(request.from)}`) - } - signal.throwIfAborted() - const id = ActivityId(String(request.activityId)) - const waiter = new OutputWaiter() - // Subscribe before the first read so an append between the anchor read and - // the wait cannot be missed. - const unsubscribe = registry.onOutput((changed) => { - if (changed === id) waiter.wake() - }) - try { - const caller = options.ownerOf(String(id)) - let snapshot = registry.get(id, caller) - let cursor = request.from ?? snapshot.outputEarliest - yield { - type: 'opened', - activityId: id, - from: cursor, - earliest: snapshot.outputEarliest, - total: snapshot.outputTotal, - status: snapshot.status, - ...snapshot.detail !== undefined ? { detail: snapshot.detail } : {}, - } - while (!signal.aborted) { - const read = registry.read(id, cursor, caller) - if (read.chunks.length > 0) { - yield* outputFrames(read.chunks, read.next, read.lossy, options.maxFrameBytes) - } - cursor = read.next - snapshot = registry.get(id, caller) - if (isTerminal(snapshot.status) && cursor >= snapshot.outputTotal) { - yield { - type: 'status', - status: snapshot.status, - ...snapshot.detail !== undefined ? { detail: snapshot.detail } : {}, - // Settlement always stamps finishedAt; the guard only discharges the optional field type. - /* v8 ignore next */ - ...snapshot.finishedAt !== undefined ? { finishedAt: snapshot.finishedAt } : {}, - } - return - } - await waiter.wait(signal) - // Let a burst accumulate so producer chatter becomes bounded frames. - await sleep(options.flushMs, signal) - } - } finally { - unsubscribe() - } -} - -/** Split one read into frames along the soft per-frame byte budget. */ -function* outputFrames( - chunks: readonly ActivityWireChunk[], - next: number, - lossy: boolean, - maxFrameBytes: number, -): Iterable { - let batch: ActivityWireChunk[] = [] - let batchBytes = 0 - let flaggedLossy = lossy - for (const chunk of chunks) { - batch.push(chunk) - batchBytes += Buffer.byteLength(chunk.text, 'utf8') - if (batchBytes >= maxFrameBytes) { - const last = batch[batch.length - 1] - /* v8 ignore start -- a non-empty batch always has a last chunk; the arm only discharges noUncheckedIndexedAccess. */ - const end = last === undefined ? next : last.at + Buffer.byteLength(last.text, 'utf8') - /* v8 ignore stop */ - yield { - type: 'output', - chunks: batch, - next: end, - ...flaggedLossy ? { lossy: true as const } : {}, - } - flaggedLossy = false - batch = [] - batchBytes = 0 - } - } - if (batch.length > 0 || flaggedLossy) { - yield { - type: 'output', - chunks: batch, - next, - ...flaggedLossy ? { lossy: true as const } : {}, - } - } -} diff --git a/packages/api/activity-controller/src/types.ts b/packages/api/activity-controller/src/types.ts deleted file mode 100644 index bc2e39808d..0000000000 --- a/packages/api/activity-controller/src/types.ts +++ /dev/null @@ -1,104 +0,0 @@ -/** Browser-safe roster and observation vocabulary for the Activity Remote. */ - -import type { SessionId } from '@deepseek-ai/dsh-session/types' -import type { ActivityId } from '@deepseek-ai/dsh-activity/brand' -import type { JobId } from '@deepseek-ai/dsh-jobs/brand' -import type { ToolCallId } from '@deepseek-ai/dsh-llm/brand' - -export type { ActivityId } from '@deepseek-ai/dsh-activity/brand' - -/** Lifecycle state carried on the wire; mirrors the registry's status union. */ -export type ActivityRowStatus = 'running' | 'completed' | 'failed' | 'killed' - -/** Links one roster row to the tool call and background job for the same work. */ -export interface ActivityRowCorrelation { - /** Tool call that started the work, when a tool produced it. */ - readonly callId?: ToolCallId - /** Background job carrying the model-facing control surface, when one exists. */ - readonly jobId?: JobId -} - -/** - * Browser-safe activity row. `kind` is `string` on the wire because the kind - * map is merge-extensible by producer plugins; presentation falls through a - * documented default for an unrecognized kind. - */ -export interface ActivityRow { - readonly id: ActivityId - readonly kind: string - readonly label: string - /** Owning session for grouping; absent for an unowned activity, visible to every session. */ - readonly sessionId?: SessionId - readonly correlation?: ActivityRowCorrelation - readonly status: ActivityRowStatus - readonly detail?: string - readonly startedAt: number - readonly finishedAt?: number - /** Total UTF-8 bytes the activity has produced so far. */ - readonly outputTotal: number -} - -/** - * Roster stream frames. Each generation starts with exactly one complete - * baseline; later frames replace one owner bucket wholesale (absent - * `sessionId` = the unowned bucket), so start, settlement, removal, and a - * second browser tab all converge through one authoritative value. - */ -export type ActivityControlFrame = - | { readonly type: 'baseline'; readonly activities: readonly ActivityRow[] } - | { readonly type: 'rows'; readonly sessionId?: SessionId; readonly activities: readonly ActivityRow[] } - -/** Opens one observation stream over a single activity's retained output. */ -export interface ActivityObserveRequest { - readonly activityId: ActivityId - /** - * Absolute byte offset to resume from — a previous frame's `next`. Omitted - * starts at the oldest retained byte. - */ - readonly from?: number -} - -/** One retained output chunk on the wire. `channel` widens to string like `kind`. */ -export interface ActivityWireChunk { - /** Absolute offset of the chunk's first byte. */ - readonly at: number - readonly text: string - readonly channel?: string - /** Bytes immediately before this chunk were lost at the producer or to retention. */ - readonly gapBefore?: true -} - -/** - * Observation stream frames: one `opened` anchor, then coalesced `output` - * batches, then — once the activity has settled and its retained output is - * drained — one terminal `status`, after which the stream closes normally. - * Status rides the same stream as output so settlement can never race a - * still-open output channel. - */ -export type ActivityObserveFrame = - | { - readonly type: 'opened' - readonly activityId: ActivityId - /** Offset the first `output` frame continues from. */ - readonly from: number - /** Oldest retained byte at open time; `from < earliest` means the head is gone. */ - readonly earliest: number - /** Total bytes produced at open time. */ - readonly total: number - readonly status: ActivityRowStatus - readonly detail?: string - } - | { - readonly type: 'output' - readonly chunks: readonly ActivityWireChunk[] - /** Offset to resume from after this frame. */ - readonly next: number - /** Bytes between the requested offset and `chunks` were already evicted. */ - readonly lossy?: true - } - | { - readonly type: 'status' - readonly status: ActivityRowStatus - readonly detail?: string - readonly finishedAt?: number - } diff --git a/packages/api/activity-controller/tests/activity-controller.host.spec.ts b/packages/api/activity-controller/tests/activity-controller.host.spec.ts deleted file mode 100644 index 757a0af115..0000000000 --- a/packages/api/activity-controller/tests/activity-controller.host.spec.ts +++ /dev/null @@ -1,306 +0,0 @@ -import { describe, expect, it } from 'vitest' -import { Context } from '@deepseek-ai/cordis' -import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' -import type { Agent } from '@deepseek-ai/dsh-agent' -import { Session, SessionId } from '@deepseek-ai/dsh-session' -import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' -import { ActivityId } from '@deepseek-ai/dsh-activity' -import { ActivityFeed } from '../src/feed.ts' -import { observeActivity } from '../src/observe.ts' -import type { ObserveOptions } from '../src/observe.ts' -import type { ActivityControlFrame, ActivityObserveFrame } from '../src/types.ts' - -async function harness(withRegistry = true) { - const ctx = new Context() - await ctx.plugin(AgentRegistry) - if (withRegistry) await ctx.plugin(LocalActivityRegistry, { retainBytes: 64, settledRetainBytes: 64 }) - return ctx -} - -function registerAgent(ctx: Context, rawId: string): Agent { - const scopeFiber = ctx.plugin(() => {}) - const id = SessionId(rawId) - const session = Session.create(id) - const agent = { - id, - session, - inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }), - status: 'idle', - ctx: scopeFiber.ctx, - } as unknown as Agent - ctx.agents.register(agent) - return agent -} - -/** Read frames until `count` arrive or the generator finishes, then abort. */ -async function collect( - iterable: AsyncIterable, - count: number, - abort: AbortController, -): Promise { - const frames: Frame[] = [] - const iterator = iterable[Symbol.asyncIterator]() - try { - while (frames.length < count) { - const step = await iterator.next() - if (step.done) return frames - frames.push(step.value) - } - } finally { - abort.abort() - await iterator.next().catch(() => undefined) - } - return frames -} - -const OBSERVE: Omit = { flushMs: 5, maxFrameBytes: 1024 } - -describe('ActivityFeed roster', () => { - it('serves an empty baseline without the registry', async () => { - const ctx = await harness(false) - const feed = new ActivityFeed(ctx) - expect(feed.baseline()).toEqual([]) - }) - - it('projects owned and unowned rows into the baseline with correlation and no live objects', async () => { - const ctx = await harness() - const owner = registerAgent(ctx, 'alice') - ctx.activities.open({ kind: 'bash', label: 'unowned build' }) - ctx.activities.open({ - kind: 'bash', - label: 'owned build', - owner, - correlation: { jobId: 'bash-7' as never }, - }) - const feed = new ActivityFeed(ctx) - const rows = feed.baseline() - expect(rows).toHaveLength(2) - const owned = rows.find(row => row.sessionId !== undefined) - expect(owned?.sessionId).toBe('alice') - expect(owned?.correlation).toEqual({ jobId: 'bash-7' }) - expect(owned?.status).toBe('running') - for (const row of rows) { - expect(Object.keys(row)).not.toContain('owner') - expect(row.outputTotal).toBe(0) - } - }) - - it('pushes whole-bucket frames for open, detail, settlement, and removal', async () => { - const ctx = await harness() - const owner = registerAgent(ctx, 'alice') - const feed = new ActivityFeed(ctx) - const abort = new AbortController() - const frames = collect(feed.follow(abort.signal), 4, abort) - await new Promise(resolve => setTimeout(resolve, 0)) - const handle = ctx.activities.open({ kind: 'bash', label: 'work', owner }) - handle.updateDetail('halfway') - handle.end({ status: 'completed', detail: 'exit code: 0' }) - const seen = await frames - expect(seen[0]).toEqual({ type: 'baseline', activities: [] }) - const rows = seen.slice(1) as Extract[] - expect(rows.every(frame => frame.sessionId === 'alice')).toBe(true) - expect(rows[0]?.activities[0]?.status).toBe('running') - expect(rows[1]?.activities[0]?.detail).toBe('halfway') - expect(rows[2]?.activities[0]?.status).toBe('completed') - expect(feed.ownerOf(String(rows[0]!.activities[0]!.id))).toBe(owner) - }) - - it('projects callId-only correlation and serves rosters without an agent registry', async () => { - const bare = new Context() - await bare.plugin(LocalActivityRegistry) - bare.activities.open({ kind: 'bash', label: 'lone', correlation: { callId: 'call-1' as never } }) - const feed = new ActivityFeed(bare) - expect(feed.baseline()[0]?.correlation).toEqual({ callId: 'call-1' }) - }) - - it('pushes an empty bucket frame when owner disposal removes the last row', async () => { - const ctx = await harness() - const owner = registerAgent(ctx, 'alice') - const feed = new ActivityFeed(ctx) - ctx.activities.open({ kind: 'bash', label: 'doomed', owner }) - const abort = new AbortController() - const frames = collect(feed.follow(abort.signal), 3, abort) - await new Promise(resolve => setTimeout(resolve, 0)) - await (owner.ctx as unknown as { fiber: { dispose(): Promise } }).fiber?.dispose?.() - // Owner-disposal removal reaches the feed as an emptied bucket. - await new Promise(resolve => setTimeout(resolve, 10)) - abort.abort() - const seen = await frames - const last = seen.at(-1) as Extract | undefined - if (last !== undefined && last.type === 'rows') expect(Array.isArray(last.activities)).toBe(true) - }) - - it('resolves undefined for unowned and unknown activities', async () => { - const ctx = await harness() - const feed = new ActivityFeed(ctx) - const handle = ctx.activities.open({ kind: 'bash', label: 'shared' }) - expect(feed.ownerOf(String(handle.id))).toBeUndefined() - expect(feed.ownerOf('bash-999')).toBeUndefined() - }) -}) - -describe('observeActivity', () => { - async function observed(ctx: Context, feed: ActivityFeed, request: { activityId: ActivityId; from?: number }) { - const abort = new AbortController() - const frames: ActivityObserveFrame[] = [] - const stream = observeActivity( - ctx.activities, - request, - { ...OBSERVE, ownerOf: id => feed.ownerOf(id) }, - abort.signal, - ) - const done = (async () => { - for await (const frame of stream) frames.push(frame) - })() - return { abort, frames, done } - } - - it('anchors, streams coalesced output, and closes with the terminal status', async () => { - const ctx = await harness() - const feed = new ActivityFeed(ctx) - const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) - handle.append('early ') - const { frames, done } = await observed(ctx, feed, { activityId: handle.id }) - await new Promise(resolve => setTimeout(resolve, 20)) - handle.append('live', { channel: 'stderr' }) - await new Promise(resolve => setTimeout(resolve, 20)) - handle.end({ status: 'completed', detail: 'exit code: 0' }) - await done - - expect(frames[0]).toMatchObject({ type: 'opened', from: 0, earliest: 0, total: 6, status: 'running' }) - const outputs = frames.filter(frame => frame.type === 'output') - const text = outputs.flatMap(frame => frame.chunks.map(chunk => chunk.text)).join('') - expect(text).toBe('early live') - expect(outputs.at(-1)?.next).toBe(10) - expect(outputs.flatMap(frame => frame.chunks).find(chunk => chunk.text === 'live')?.channel).toBe('stderr') - expect(frames.at(-1)).toMatchObject({ type: 'status', status: 'completed', detail: 'exit code: 0' }) - }) - - it('resumes from an explicit offset and flags an evicted resume lossy', async () => { - const ctx = await harness() - const feed = new ActivityFeed(ctx) - const handle = ctx.activities.open({ kind: 'bash', label: 'spam' }) - handle.append('a'.repeat(60)) - handle.append('b'.repeat(60)) - handle.end({ status: 'completed' }) - - const fresh = await observed(ctx, feed, { activityId: handle.id, from: 0 }) - await fresh.done - const output = fresh.frames.find(frame => frame.type === 'output') - expect(output?.lossy).toBe(true) - expect(output?.chunks.map(chunk => chunk.text).join('')).toBe('b'.repeat(60)) - - const resumed = await observed(ctx, feed, { activityId: handle.id, from: 120 }) - await resumed.done - expect(resumed.frames.some(frame => frame.type === 'output')).toBe(false) - expect(resumed.frames.at(-1)?.type).toBe('status') - }) - - it('splits oversized reads along the frame budget', async () => { - const ctx = await harness() - const feed = new ActivityFeed(ctx) - const registry = ctx.activities - const handle = registry.open({ kind: 'bash', label: 'wide' }) - const abort = new AbortController() - handle.append('x'.repeat(30)) - handle.append('y'.repeat(30)) - handle.end({ status: 'completed' }) - const frames = await collect( - observeActivity(registry, { activityId: handle.id }, { - flushMs: 5, - maxFrameBytes: 30, - ownerOf: id => feed.ownerOf(id), - }, abort.signal), - 5, - abort, - ) - const outputs = frames.filter(frame => frame.type === 'output') - expect(outputs).toHaveLength(2) - expect(outputs[0]?.next).toBe(30) - expect(outputs[1]?.next).toBe(60) - }) - - it('carries the lossy flag on the first frame of a split evicted read', async () => { - const ctx = await harness() - const feed = new ActivityFeed(ctx) - const registry = ctx.activities - const handle = registry.open({ kind: 'bash', label: 'evicted split' }) - handle.append('a'.repeat(40)) - handle.append('b'.repeat(40)) - handle.append('c'.repeat(40)) - handle.end({ status: 'completed' }) - const abort = new AbortController() - const frames = await collect( - observeActivity(registry, { activityId: handle.id, from: 0 }, { - flushMs: 5, - maxFrameBytes: 40, - ownerOf: id => feed.ownerOf(id), - }, abort.signal), - 5, - abort, - ) - const outputs = frames.filter(frame => frame.type === 'output') - expect(outputs[0]?.lossy).toBe(true) - expect(outputs[1]?.lossy).toBeUndefined() - }) - - it('reads owned activities through the roster owner and rejects bad offsets and unknown ids', async () => { - const ctx = await harness() - const owner = registerAgent(ctx, 'alice') - const feed = new ActivityFeed(ctx) - const handle = ctx.activities.open({ kind: 'bash', label: 'secret', owner }) - handle.append('classified') - handle.end({ status: 'completed' }) - const { frames, done } = await observed(ctx, feed, { activityId: handle.id }) - await done - expect(frames.some(frame => frame.type === 'output' - && frame.chunks.some(chunk => chunk.text === 'classified'))).toBe(true) - - const abort = new AbortController() - await expect(collect( - observeActivity(ctx.activities, { activityId: handle.id, from: -1 }, { - ...OBSERVE, - ownerOf: id => feed.ownerOf(id), - }, abort.signal), - 1, - abort, - )).rejects.toThrow(/invalid observe offset/) - - const abortUnknown = new AbortController() - await expect(collect( - observeActivity(ctx.activities, { activityId: ActivityId('bash-999') }, { - ...OBSERVE, - ownerOf: id => feed.ownerOf(id), - }, abortUnknown.signal), - 1, - abortUnknown, - )).rejects.toThrow(/unknown activity/) - }) - - it('ignores output signals for other activities while waiting', async () => { - const ctx = await harness() - const feed = new ActivityFeed(ctx) - const watched = ctx.activities.open({ kind: 'bash', label: 'watched' }) - const noisy = ctx.activities.open({ kind: 'bash', label: 'noisy' }) - const { abort, frames, done } = await observed(ctx, feed, { activityId: watched.id }) - await new Promise(resolve => setTimeout(resolve, 15)) - noisy.append('unrelated') - await new Promise(resolve => setTimeout(resolve, 15)) - watched.end({ status: 'completed' }) - await done - abort.abort() - expect(frames.filter(frame => frame.type === 'output')).toEqual([]) - }) - - it('stops cleanly on abort while waiting for output', async () => { - const ctx = await harness() - const feed = new ActivityFeed(ctx) - const handle = ctx.activities.open({ kind: 'bash', label: 'idle' }) - const { abort, frames, done } = await observed(ctx, feed, { activityId: handle.id }) - await new Promise(resolve => setTimeout(resolve, 20)) - abort.abort() - await done - expect(frames[0]?.type).toBe('opened') - expect(frames.at(-1)?.type).not.toBe('status') - }) -}) diff --git a/packages/api/activity-controller/tests/client-apply.client.spec.ts b/packages/api/activity-controller/tests/client-apply.client.spec.ts deleted file mode 100644 index 231703ba13..0000000000 --- a/packages/api/activity-controller/tests/client-apply.client.spec.ts +++ /dev/null @@ -1,113 +0,0 @@ -import { describe, expect, it } from 'vitest' -import { Context } from '@deepseek-ai/cordis' -import { RemoteStreamCarrierError } from '@deepseek-ai/dsh-api-gateway/client' -import { apply, createActivityRosterStream } from '../src/client/index.ts' -import { ClientActivityModel } from '../src/client/model.ts' -import type { ActivityControlFrame, ActivityId, ActivityRow } from '../src/types.ts' - -function row(): ActivityRow { - return { - id: 'bash-1' as ActivityId, - kind: 'bash', - label: 'build', - status: 'running', - startedAt: 1, - outputTotal: 0, - } -} - -/** One scripted roster stream: frames pushed by the test, never reopened. */ -class FakeStream { - disposed = false - private readonly frames: ActivityControlFrame[] = [] - private waiter: (() => void) | undefined - private failure: Error | undefined - - push(frame: ActivityControlFrame): void { - this.frames.push(frame) - this.waiter?.() - } - - poison(error: Error): void { - this.failure = error - this.waiter?.() - } - - dispose(): Promise { - this.disposed = true - this.waiter?.() - return Promise.resolve() - } - - async *[Symbol.asyncIterator]() { - while (!this.disposed) { - if (this.failure !== undefined) throw this.failure - const frame = this.frames.shift() - if (frame === undefined) { - await new Promise((resolve) => { this.waiter = resolve }) - continue - } - yield { generation: 1, value: frame, signal: new AbortController().signal, accept: () => {} } - } - } -} - -const tick = () => new Promise(resolve => setTimeout(resolve, 0)) - -describe('activity-controller client plugin', () => { - it('installs ctx.activityFeed and folds roster frames from the control stream', async () => { - const ctx = new Context() - const streams: { options: { open: (signal: AbortSignal) => unknown; ended: (accepted: boolean) => Error }; stream: FakeStream }[] = [] - const controlCalls: AbortSignal[] = [] - ctx.provide('remote', { - $stream: (options: never) => { - const stream = new FakeStream() - streams.push({ options, stream }) - return stream - }, - activity: { - control: (signal: AbortSignal) => { - controlCalls.push(signal) - return { [Symbol.asyncIterator]: async function* () { /* never yields */ } } - }, - observe: () => { throw new Error('not exercised') }, - }, - } as never) - const fiber = ctx.plugin({ inject: ['remote'], apply }) - await fiber - - streams[0]!.stream.push({ type: 'baseline', activities: [row()] }) - streams[0]!.stream.push({ type: 'rows', activities: [] }) - await tick() - const snapshot = ctx.activityFeed.state.getSnapshot() - expect(snapshot.phase).toBe('ready') - expect(snapshot.rowsBySession['']).toBeUndefined() - - // The generation opener and end classification belong to the domain. - streams[0]!.options.open(new AbortController().signal) - expect(controlCalls).toHaveLength(1) - expect(streams[0]!.options.ended(true)).toBeInstanceOf(RemoteStreamCarrierError) - expect(streams[0]!.options.ended(false)).toBeInstanceOf(Error) - - // A terminal roster failure keeps the last snapshot in place. - streams[0]!.stream.poison(new Error('roster stream broke')) - await tick() - expect(ctx.activityFeed.state.getSnapshot().phase).toBe('ready') - - await fiber.dispose() - expect(streams[0]!.stream.disposed).toBe(true) - }) - - it('keeps the last roster on a terminal stream failure', async () => { - const model = new ClientActivityModel() - const remote = { - $stream: () => new FakeStream(), - activity: { control: () => { throw new Error('unused') }, observe: () => { throw new Error('unused') } }, - } - const stream = createActivityRosterStream(remote as never, model) - model.replaceBaseline([row()]) - stream.start() - await stream.dispose() - expect(model.getSnapshot().rowsBySession['']?.[0]?.label).toBe('build') - }) -}) diff --git a/packages/api/activity-controller/tests/client-model.client.spec.ts b/packages/api/activity-controller/tests/client-model.client.spec.ts deleted file mode 100644 index 31f5d18c33..0000000000 --- a/packages/api/activity-controller/tests/client-model.client.spec.ts +++ /dev/null @@ -1,183 +0,0 @@ -import { describe, expect, it } from 'vitest' -import { ClientActivityModel } from '../src/client/model.ts' -import type { ActivityId, ActivityRow } from '../src/types.ts' - -function row(over: Partial = {}): ActivityRow { - return { - id: 'bash-1' as ActivityId, - kind: 'bash', - label: 'build', - sessionId: 'alice' as ActivityRow['sessionId'], - status: 'running', - startedAt: 1, - outputTotal: 0, - ...over, - } as ActivityRow -} - -/** A row with no owner session, as the unowned bucket carries them. */ -function unownedRow(over: Partial = {}): ActivityRow { - const { sessionId: _drop, ...rest } = row(over) - return rest -} - -const ID = 'bash-1' as ActivityId - -function opened(model: ClientActivityModel, over: Partial<{ from: number; earliest: number; total: number }> = {}): void { - model.observeOpened(ID, { - type: 'opened', - activityId: ID, - from: 0, - earliest: 0, - total: 0, - status: 'running', - ...over, - }) -} - -describe('ClientActivityModel roster', () => { - it('folds baselines into per-session buckets and reports readiness', () => { - const model = new ClientActivityModel() - expect(model.getSnapshot().phase).toBe('pending') - model.replaceBaseline([row(), unownedRow({ id: 'workflow-1' as ActivityId })]) - const snapshot = model.getSnapshot() - expect(snapshot.phase).toBe('ready') - expect(snapshot.rowsBySession['alice']).toHaveLength(1) - expect(snapshot.rowsBySession['']).toHaveLength(1) - }) - - it('replaces buckets wholesale and drops emptied keys', () => { - const model = new ClientActivityModel() - model.replaceBaseline([row()]) - model.replaceBucket('alice', [row({ status: 'completed', finishedAt: 2 })]) - expect(model.getSnapshot().rowsBySession['alice']?.[0]?.status).toBe('completed') - model.replaceBucket('alice', []) - expect('alice' in model.getSnapshot().rowsBySession).toBe(false) - model.replaceBucket(undefined, [unownedRow()]) - expect(model.getSnapshot().rowsBySession['']).toHaveLength(1) - }) - - it('keeps snapshot identity stable between changes and notifies subscribers', () => { - const model = new ClientActivityModel() - let notified = 0 - const unsubscribe = model.subscribe(() => { notified += 1 }) - const before = model.getSnapshot() - expect(model.getSnapshot()).toBe(before) - model.replaceBaseline([row()]) - expect(notified).toBe(1) - expect(model.getSnapshot()).not.toBe(before) - unsubscribe() - model.replaceBucket('alice', []) - expect(notified).toBe(1) - }) -}) - -describe('ClientActivityModel observation', () => { - it('accumulates output, advances the resume cursor, and settles on status', () => { - const model = new ClientActivityModel() - opened(model) - expect(model.cursorOf(ID)).toBe(0) - model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'a' }, { at: 1, text: 'b' }], next: 2 }) - model.observeOutput(ID, { type: 'output', chunks: [{ at: 2, text: 'c' }], next: 3 }) - expect(model.cursorOf(ID)).toBe(3) - const view = model.getSnapshot().observed[String(ID)] - expect(view?.text).toBe('abc') - expect(view?.streaming).toBe(true) - model.observeStatus(ID, { type: 'status', status: 'completed', detail: 'exit code: 0' }) - const settled = model.getSnapshot().observed[String(ID)] - expect(settled?.streaming).toBe(false) - expect(settled?.status).toBe('completed') - expect(settled?.detail).toBe('exit code: 0') - }) - - it('marks gaps from lossy frames, gap chunks, and a resume behind the retained head', () => { - const model = new ClientActivityModel() - opened(model, { from: 4, earliest: 8, total: 10 }) - expect(model.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) - - const clean = new ClientActivityModel() - opened(clean) - clean.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'x', gapBefore: true }], next: 1 }) - expect(clean.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) - - const lossy = new ClientActivityModel() - opened(lossy) - lossy.observeOutput(ID, { type: 'output', chunks: [], next: 5, lossy: true }) - expect(lossy.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) - }) - - it('marks a fresh observation anchored past the evicted head', () => { - // Fresh observations anchor at the registry's earliest retained byte, so - // from === earliest > 0 means the head was already discarded. - const fresh = new ClientActivityModel() - opened(fresh, { from: 60_240, earliest: 60_240, total: 321_328 }) - expect(fresh.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) - - // A retry that accumulated no text yet earns the mark the same way. - const retried = new ClientActivityModel() - opened(retried) - expect(retried.getSnapshot().observed[String(ID)]?.gapBefore).toBe(false) - opened(retried, { from: 6, earliest: 6, total: 6 }) - expect(retried.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) - }) - - it('bounds the render tail without splitting a surrogate pair', () => { - const model = new ClientActivityModel() - opened(model) - const emoji = '😀'.repeat((64 * 1024) + 8) - model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: emoji }], next: emoji.length * 2 }) - const view = model.getSnapshot().observed[String(ID)] - expect(view?.gapBefore).toBe(true) - expect(view!.text.length).toBeLessThanOrEqual(128 * 1024) - // The bound landed between pairs: the surviving text still round-trips. - expect(/^(?:😀)+$/u.test(view!.text)).toBe(true) - }) - - it('carries the anchor detail and trims a plain-ASCII tail without a boundary shift', () => { - const model = new ClientActivityModel() - model.observeOpened(ID, { - type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running', detail: 'exit soon', - }) - expect(model.getSnapshot().observed[String(ID)]?.detail).toBe('exit soon') - const long = 'x'.repeat((128 * 1024) + 5) - model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: long }], next: long.length }) - const view = model.getSnapshot().observed[String(ID)] - expect(view?.text.length).toBe(128 * 1024) - expect(view?.gapBefore).toBe(true) - }) - - it('advances the cut past a low surrogate landing exactly on the bound', () => { - const model = new ClientActivityModel() - opened(model) - // 'z' + one emoji + odd ASCII tail puts a low surrogate exactly at the cut index. - const text = 'z😀' + 'a'.repeat((128 * 1024) - 1) - model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text }], next: text.length }) - const view = model.getSnapshot().observed[String(ID)] - expect(view?.text.length).toBe((128 * 1024) - 1) - expect(view?.text.startsWith('a')).toBe(true) - }) - - it('preserves accumulated text across a reconnect anchor and clears on stop', () => { - const model = new ClientActivityModel() - opened(model) - model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'kept' }], next: 4 }) - opened(model, { from: 4, earliest: 0, total: 4 }) - expect(model.getSnapshot().observed[String(ID)]?.text).toBe('kept') - model.observeStopped(ID) - expect(model.getSnapshot().observed[String(ID)]).toBeUndefined() - expect(model.cursorOf(ID)).toBeUndefined() - // A second stop is inert. - model.observeStopped(ID) - }) - - it('records a terminal stream failure on the live view', () => { - const model = new ClientActivityModel() - opened(model) - model.observeFailed(ID, new Error('carrier gone')) - const view = model.getSnapshot().observed[String(ID)] - expect(view?.streaming).toBe(false) - expect(view?.error).toContain('carrier gone') - // A failure for an untracked id is inert. - model.observeFailed('bash-9' as ActivityId, new Error('ignored')) - }) -}) diff --git a/packages/api/activity-controller/tests/client-service.client.spec.ts b/packages/api/activity-controller/tests/client-service.client.spec.ts deleted file mode 100644 index ba051d2e23..0000000000 --- a/packages/api/activity-controller/tests/client-service.client.spec.ts +++ /dev/null @@ -1,276 +0,0 @@ -import { describe, expect, it, vi } from 'vitest' -import { Context } from '@deepseek-ai/cordis' -import { ClientActivityModel } from '../src/client/model.ts' -import { ClientActivityFeed } from '../src/client/service.ts' -import type { ActivityId, ActivityObserveFrame } from '../src/types.ts' - -const ID = 'bash-1' as ActivityId - -/** One scripted logical stream: frames are pushed by the test, never reopened. */ -class FakeStream { - disposed = false - /** Model a carrier whose disposal surfaces as an iterator throw. */ - throwOnDispose = false - /** Hold the dispose promise open until {@link releaseDispose}. */ - deferDispose = false - private disposeRelease: (() => void) | undefined - private disposePending: Promise | undefined - private readonly frames: ActivityObserveFrame[] = [] - private waiter: (() => void) | undefined - private failure: Error | undefined - readonly accepts: number[] = [] - - push(frame: ActivityObserveFrame): void { - this.frames.push(frame) - this.waiter?.() - } - - poison(error: Error): void { - this.failure = error - this.waiter?.() - } - - dispose(): Promise { - if (this.throwOnDispose && this.failure === undefined) { - this.failure = new Error('carrier tore down') - } else { - this.disposed = true - } - this.waiter?.() - if (this.deferDispose) { - // Repeat disposals (releaser plus the consumer's finally) share one - // deferred promise, so releaseDispose resumes every waiter. - this.disposePending ??= new Promise((resolve) => { this.disposeRelease = resolve }) - return this.disposePending - } - return Promise.resolve() - } - - releaseDispose(): void { - this.disposeRelease?.() - } - - async *[Symbol.asyncIterator]() { - let generation = 1 - while (!this.disposed) { - if (this.failure !== undefined) throw this.failure - const frame = this.frames.shift() - if (frame === undefined) { - await new Promise((resolve) => { this.waiter = resolve }) - continue - } - yield { - generation, - value: frame, - signal: new AbortController().signal, - accept: () => { this.accepts.push(generation) }, - } - generation = 1 - } - } -} - -function bench() { - const ctx = new Context() - const model = new ClientActivityModel() - const streams: { options: { open: (signal: AbortSignal) => unknown }; stream: FakeStream }[] = [] - const observeCalls: unknown[] = [] - const remote = { - $stream: (options: { open: (signal: AbortSignal) => unknown }) => { - const stream = new FakeStream() - streams.push({ options, stream }) - return stream - }, - activity: { - observe: (request: unknown) => { - observeCalls.push(request) - return { [Symbol.asyncIterator]: async function* () { /* never yields */ } } - }, - control: () => { throw new Error('not exercised') }, - }, - } - const feed = new ClientActivityFeed(ctx, remote as never, model) - return { ctx, model, feed, streams, observeCalls } -} - -const tick = () => new Promise(resolve => setTimeout(resolve, 0)) - -describe('ClientActivityFeed observation streams', () => { - it('feeds anchor, output, and terminal frames into the model, then closes', async () => { - const { model, feed, streams } = bench() - feed.observe(ID) - const { stream } = streams[0]! - stream.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) - stream.push({ type: 'output', chunks: [{ at: 0, text: 'hi' }], next: 2 }) - await tick() - expect(model.getSnapshot().observed[String(ID)]?.text).toBe('hi') - expect(stream.accepts).toHaveLength(1) - - stream.push({ type: 'status', status: 'completed' }) - await tick() - expect(model.getSnapshot().observed[String(ID)]?.streaming).toBe(false) - expect(stream.disposed).toBe(true) - }) - - it('shares one stream across observers and stops after the last release', async () => { - const { model, feed, streams } = bench() - const first = feed.observe(ID) - const second = feed.observe(ID) - expect(streams).toHaveLength(1) - streams[0]!.stream.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) - await tick() - - first() - first() - expect(streams[0]!.stream.disposed).toBe(false) - second() - await tick() - expect(streams[0]!.stream.disposed).toBe(true) - expect(model.getSnapshot().observed[String(ID)]).toBeUndefined() - }) - - it('a late release of a superseded observation neither tears down nor clears its successor', async () => { - const { model, feed, streams } = bench() - const firstStop = feed.observe(ID) - const first = streams[0]!.stream - first.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) - first.push({ type: 'status', status: 'completed' }) - await tick() - // A successor observation replaces the settled entry while the first - // observer still holds its releaser. - const secondStop = feed.observe(ID) - const second = streams[1]!.stream - second.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) - await tick() - - firstStop() - await tick() - expect(second.disposed).toBe(false) - expect(model.getSnapshot().observed[String(ID)]).toBeDefined() - - secondStop() - await tick() - expect(second.disposed).toBe(true) - expect(model.getSnapshot().observed[String(ID)]).toBeUndefined() - }) - - it('a re-observation inside the dispose round-trip keeps its fresh view', async () => { - const { model, feed, streams } = bench() - const stop = feed.observe(ID) - const first = streams[0]!.stream - first.deferDispose = true - first.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) - await tick() - - stop() - // Re-expand while the previous generation's dispose is still in flight. - feed.observe(ID) - const second = streams[1]!.stream - second.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) - await tick() - - first.releaseDispose() - await tick() - // The stale post-dispose clear must not blank the successor's view. - expect(model.getSnapshot().observed[String(ID)]).toBeDefined() - second.push({ type: 'output', chunks: [{ at: 0, text: 'alive' }], next: 5 }) - await tick() - expect(model.getSnapshot().observed[String(ID)]?.text).toBe('alive') - }) - - it('opens a fresh stream for a re-observed activity and resumes from the model cursor', async () => { - const { feed, streams, observeCalls, model } = bench() - const stop = feed.observe(ID) - streams[0]!.stream.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) - streams[0]!.stream.push({ type: 'output', chunks: [{ at: 0, text: 'abc' }], next: 3 }) - await tick() - // The generation opener reads the live cursor at open time. - streams[0]!.options.open(new AbortController().signal) - expect(observeCalls.at(-1)).toEqual({ activityId: ID, from: 3 }) - - stop() - await tick() - feed.observe(ID) - expect(streams).toHaveLength(2) - streams[1]!.options.open(new AbortController().signal) - // Stopped observation dropped the cursor: the fresh stream starts unanchored. - expect(observeCalls.at(-1)).toEqual({ activityId: ID }) - expect(model.cursorOf(ID)).toBeUndefined() - }) - - it('classifies a premature end as retryable only after the anchor', () => { - const { feed, streams } = bench() - feed.observe(ID) - const options = streams[0]!.options as unknown as { ended: (accepted: boolean) => Error } - expect(options.ended(true).name).toBe('RemoteStreamCarrierError') - expect(options.ended(false).name).toBe('Error') - }) - - it('records a consumer failure on the live view', async () => { - const { model, feed, streams } = bench() - feed.observe(ID) - const { stream } = streams[0]! - stream.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) - await tick() - stream.poison(new Error('frame decode broke')) - await tick() - const view = model.getSnapshot().observed[String(ID)] - expect(view?.error).toContain('frame decode broke') - expect(view?.streaming).toBe(false) - }) - - it('treats a release after service disposal as inert and stays silent for post-stop failures', async () => { - const { ctx, model, feed, streams } = bench() - const stop = feed.observe(ID) - const { stream } = streams[0]! - stream.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) - await tick() - // Poison wakes the consumer, but the synchronous stop lands first, so the - // failure arrives on an already-stopped entry and stays silent. - stream.poison(new Error('after stop')) - stop() - await tick() - expect(model.getSnapshot().observed[String(ID)]).toBeUndefined() - - const second = feed.observe(ID) - await ctx.fiber.dispose() - // The disposal path already removed every entry; a live releaser whose - // entry is gone is inert. - second() - }) - - it('stays silent when the carrier teardown itself throws after a stop', async () => { - const { model, feed, streams } = bench() - const stop = feed.observe(ID) - const { stream } = streams[0]! - stream.throwOnDispose = true - stream.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) - await tick() - // The releaser marks the entry stopped, then its dispose surfaces as an - // iterator throw — which the consumer swallows for a stopped entry. - stop() - await tick() - expect(model.getSnapshot().observed[String(ID)]?.error).toBeUndefined() - }) - - it('records a terminal stream failure and service disposal closes live streams', async () => { - const { ctx, model, feed, streams } = bench() - feed.observe(ID) - const failing = streams[0]!.stream - failing.push({ type: 'opened', activityId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) - await tick() - const iterator = failing[Symbol.asyncIterator]() - void iterator - // Simulate a terminal consumer failure by disposing the underlying stream: - // the consumer loop ends without a status frame and cleans up. - const spy = vi.spyOn(model, 'observeFailed') - await failing.dispose() - await tick() - - const other = 'bash-2' as ActivityId - feed.observe(other) - await ctx.fiber.dispose() - expect(streams.every(entry => entry.stream.disposed)).toBe(true) - expect(spy).not.toHaveBeenCalled() - }) -}) diff --git a/packages/api/activity-controller/tests/controller.host.spec.ts b/packages/api/activity-controller/tests/controller.host.spec.ts deleted file mode 100644 index 4c3262f093..0000000000 --- a/packages/api/activity-controller/tests/controller.host.spec.ts +++ /dev/null @@ -1,102 +0,0 @@ -import { describe, expect, it } from 'vitest' -import { Context } from '@deepseek-ai/cordis' -import AgentRegistry from '@deepseek-ai/dsh-agent' -import LocalActivityRegistry from '@deepseek-ai/dsh-activity-local' -import { ActivityController } from '../src/index.ts' -import type { ActivityControlFrame, ActivityObserveFrame } from '../src/types.ts' - -async function collect( - iterable: AsyncIterable, - count: number, - abort: AbortController, -): Promise { - const frames: Frame[] = [] - const iterator = iterable[Symbol.asyncIterator]() - try { - while (frames.length < count) { - const step = await iterator.next() - if (step.done) return frames - frames.push(step.value) - } - } finally { - abort.abort() - await iterator.next().catch(() => undefined) - } - return frames -} - -describe('ActivityController', () => { - it('closes live roster followers when the owning fiber unwinds', async () => { - const ctx = new Context() - await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalActivityRegistry) - const controller = new ActivityController(ctx, { flushMs: 5, maxFrameBytes: 1024 }) - const abort = new AbortController() - const iterator = controller.control(abort.signal)[Symbol.asyncIterator]() - expect((await iterator.next()).value).toMatchObject({ type: 'baseline' }) - const pending = iterator.next() - await ctx.fiber.dispose() - // The feed effect closed the follower, ending the generation cleanly. - expect((await pending).done).toBe(true) - }) - - it('coalesces bursts that land inside the flush window and carries the anchor detail', async () => { - const ctx = new Context() - await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalActivityRegistry) - const controller = new ActivityController(ctx, { flushMs: 30, maxFrameBytes: 1024 }) - const handle = ctx.activities.open({ kind: 'bash', label: 'burst' }) - handle.updateDetail('warming up') - const abort = new AbortController() - const frames: ActivityObserveFrame[] = [] - const done = (async () => { - for await (const frame of controller.observe({ activityId: handle.id }, abort.signal)) frames.push(frame) - })() - await new Promise(resolve => setTimeout(resolve, 10)) - handle.append('a') - await new Promise(resolve => setTimeout(resolve, 5)) - // Lands inside the flush sleep, so the waiter is already dirty at the next wait. - handle.append('b') - await new Promise(resolve => setTimeout(resolve, 80)) - handle.end({ status: 'completed' }) - await done - expect(frames[0]).toMatchObject({ type: 'opened', detail: 'warming up' }) - const text = frames.filter(frame => frame.type === 'output') - .flatMap(frame => frame.chunks.map(chunk => chunk.text)).join('') - expect(text).toBe('ab') - }) - - it('serves an empty baseline and refuses observation without the registry', async () => { - const ctx = new Context() - const controller = new ActivityController(ctx, { flushMs: 5, maxFrameBytes: 1024 }) - const abort = new AbortController() - const frames = await collect(controller.control(abort.signal), 1, abort) - expect(frames).toEqual([{ type: 'baseline', activities: [] }]) - expect(() => controller.observe({ activityId: 'bash-1' as never }, new AbortController().signal)) - .toThrow(/activity observation unavailable/) - }) - - it('streams the roster and one activity end to end over a live registry', async () => { - const ctx = new Context() - await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalActivityRegistry) - const controller = new ActivityController(ctx, { flushMs: 5, maxFrameBytes: 1024 }) - - const handle = ctx.activities.open({ kind: 'bash', label: 'echo' }) - handle.append('hi') - handle.end({ status: 'completed', detail: 'exit code: 0' }) - - const rosterAbort = new AbortController() - const roster = await collect(controller.control(rosterAbort.signal), 1, rosterAbort) - expect(roster[0]).toMatchObject({ type: 'baseline' }) - expect((roster[0] as Extract).activities[0]?.label).toBe('echo') - - const observeAbort = new AbortController() - const observed = await collect( - controller.observe({ activityId: handle.id }, observeAbort.signal), - 3, - observeAbort, - ) - expect(observed.map(frame => frame.type)).toEqual(['opened', 'output', 'status']) - }) -}) diff --git a/packages/api/activity-controller/tsconfig.client.json b/packages/api/activity-controller/tsconfig.client.json deleted file mode 100644 index d2934629b4..0000000000 --- a/packages/api/activity-controller/tsconfig.client.json +++ /dev/null @@ -1,46 +0,0 @@ -{ - "extends": "../../../tsconfig.base.client.json", - "compilerOptions": { - "rootDir": "src", - "outDir": "lib/types", - "tsBuildInfoFile": "lib/tsconfig.client.tsbuildinfo" - }, - "files": [ - "src/client/index.ts", - "src/client/model.ts", - "src/client/service.ts", - "src/types.ts" - ], - "references": [ - { - "path": "../../../vendor/cordis" - }, - { - "path": "../gateway/tsconfig.client.json" - }, - { - "path": "../../client/connection/tsconfig.client.json" - }, - { - "path": "../../client/store" - }, - { - "path": "../../activity/activity" - }, - { - "path": "../../core/session" - }, - { - "path": "../../jobs/jobs" - }, - { - "path": "../../llm/llm" - }, - { - "path": "../../util/brand" - }, - { - "path": "../../typert/protocol" - } - ] -} diff --git a/packages/api/activity-controller/tsconfig.host.json b/packages/api/activity-controller/tsconfig.host.json deleted file mode 100644 index 4193d47109..0000000000 --- a/packages/api/activity-controller/tsconfig.host.json +++ /dev/null @@ -1,26 +0,0 @@ -{ - "extends": "../../../tsconfig.base.json", - "compilerOptions": { - "rootDir": "src", - "outDir": "lib/types", - "tsBuildInfoFile": "lib/tsconfig.host.tsbuildinfo" - }, - "files": [ - "src/index.ts", - "src/invariant.ts", - "src/types.ts", - "src/feed.ts", - "src/observe.ts" - ], - "references": [ - { "path": "../../../vendor/cordis" }, - { "path": "../../../vendor/schemastery" }, - { "path": "../../activity/activity" }, - { "path": "../../core/agent" }, - { "path": "../../core/session" }, - { "path": "../../jobs/jobs" }, - { "path": "../../llm/llm" }, - { "path": "../../runtime-diagnostics/invariants" }, - { "path": "../../typert/protocol" } - ] -} diff --git a/packages/api/activity-controller/tsconfig.json b/packages/api/activity-controller/tsconfig.json deleted file mode 100644 index 2a0b0e33f7..0000000000 --- a/packages/api/activity-controller/tsconfig.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "files": [], - "references": [ - { "path": "./tsconfig.host.json" }, - { "path": "./tsconfig.client.json" } - ] -} diff --git a/packages/api/activity-controller/tsdown.config.ts b/packages/api/activity-controller/tsdown.config.ts deleted file mode 100644 index 0552d1b1cf..0000000000 --- a/packages/api/activity-controller/tsdown.config.ts +++ /dev/null @@ -1,7 +0,0 @@ -import { clientBundle } from '../../client/tsdown.client.ts' - -export default clientBundle( - '@deepseek-ai/dsh-api-activity-controller', - ['lib/types/index.js', 'lib/types/invariant.js'], - { hostPhase: true }, -) diff --git a/packages/api/remotes/package.json b/packages/api/remotes/package.json index f6f3b74990..a4334e0e75 100644 --- a/packages/api/remotes/package.json +++ b/packages/api/remotes/package.json @@ -66,7 +66,6 @@ "devDependencies": { "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-agent-presets": "workspace:^", - "@deepseek-ai/dsh-api-activity-controller": "workspace:^", "@deepseek-ai/dsh-api-gateway": "workspace:^", "@deepseek-ai/dsh-api-settings-controller": "workspace:^", "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", diff --git a/packages/api/remotes/src/client/index.ts b/packages/api/remotes/src/client/index.ts index baaccbbdbf..e7fc7757e9 100644 --- a/packages/api/remotes/src/client/index.ts +++ b/packages/api/remotes/src/client/index.ts @@ -13,7 +13,6 @@ import sessionReferencesRemote from '@deepseek-ai/dsh-session-reference/remote' import subagentsRemote from '@deepseek-ai/dsh-subagent/remote' import sessionRemote from '@deepseek-ai/dsh-api-session-controller/remote' import workspaceRemote from '@deepseek-ai/dsh-api-workspace-controller/remote' -import activityRemote from '@deepseek-ai/dsh-api-activity-controller/remote' import type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client' export type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client' @@ -32,8 +31,6 @@ export type {} from '@deepseek-ai/dsh-api-session-controller/remote' export type * from '@deepseek-ai/dsh-api-session-controller/types' export type {} from '@deepseek-ai/dsh-api-workspace-controller/remote' export type * from '@deepseek-ai/dsh-api-workspace-controller/types' -export type {} from '@deepseek-ai/dsh-api-activity-controller/remote' -export type * from '@deepseek-ai/dsh-api-activity-controller/types' export type { SessionJob as JobView } from '@deepseek-ai/dsh-api-session-controller/types' // The forwarded-event allowlist's selection seat: without it in the consumer's // compilation face `TypertRemoteEvent` is `never` and every `$on` call fails. @@ -149,7 +146,7 @@ export async function apply(ctx: Context): Promise<() => Promise> { for (const contribution of [ agentPresetsRemote, commandsRemote, settingsControllerRemote, goalsRemote, llmRemote, dynamicRemote, pluginInventoryRemote, messageFeedbackRemote, sessionReferencesRemote, - subagentsRemote, sessionRemote, workspaceRemote, activityRemote, + subagentsRemote, sessionRemote, workspaceRemote, ]) { disposers.push(await ctx.remote.$mount(contribution)) } diff --git a/packages/api/remotes/src/index.ts b/packages/api/remotes/src/index.ts index f19acea2c2..5a11bae49d 100644 --- a/packages/api/remotes/src/index.ts +++ b/packages/api/remotes/src/index.ts @@ -26,7 +26,6 @@ import type {} from '@deepseek-ai/dsh-settings/types' import type {} from '@deepseek-ai/dsh-user-approval' import type {} from '@deepseek-ai/dsh-user-questions' export type {} from '@deepseek-ai/dsh-api-session-controller/types' -export type {} from '@deepseek-ai/dsh-api-activity-controller/types' export { API_REMOTE_FORWARDED_EVENTS } from './remote-events.ts' export type { ApiRemoteForwardedEvent } from './types.ts' diff --git a/packages/api/remotes/tsconfig.client.json b/packages/api/remotes/tsconfig.client.json index 1b4d4ca1ae..56f664d499 100644 --- a/packages/api/remotes/tsconfig.client.json +++ b/packages/api/remotes/tsconfig.client.json @@ -66,9 +66,6 @@ { "path": "../session-controller/tsconfig.client.json" }, - { - "path": "../activity-controller/tsconfig.client.json" - }, { "path": "../settings-controller" }, diff --git a/packages/api/remotes/tsconfig.host.json b/packages/api/remotes/tsconfig.host.json index a0aab5ea93..65fca35ee0 100644 --- a/packages/api/remotes/tsconfig.host.json +++ b/packages/api/remotes/tsconfig.host.json @@ -60,9 +60,6 @@ { "path": "../session-controller/tsconfig.host.json" }, - { - "path": "../activity-controller/tsconfig.host.json" - }, { "path": "../workspace-controller/tsconfig.host.json" }, diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md index 2f2192cde2..2e5ca38bf5 100644 --- a/packages/api/session-controller/README.md +++ b/packages/api/session-controller/README.md @@ -29,6 +29,8 @@ Each endpoint states its activation policy. List, search, attachment, history pa The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, and `append` changes, and repairs reconnect or sequence gaps through a tail page. Ordinary records cover `[event.seq, event.seq]`; packed rows cover `[event.seq, event.seq + memberCount - 1]`. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces queue, jobs, and projection state instead of treating transient values as durable events. +A `SessionJob` row carries `outputTotal` exactly when the job declared an observation record, and `session.observeJob` streams that record from an absolute byte offset — one `opened` anchor, coalesced `output` frames, then one terminal `status` — with the fenced read resolved from the request's session. Record reads are non-consuming: the model-facing cursor and completion-notice state never observe them. The Client adapter exposes `ctx.jobOutput`, the reference-counted per-job observation service whose accumulated views a task-list UI renders; observers share one stream per job and resume from their model cursor across reconnects. + The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. Session derives each echo's `transcript`, `queued`, or `steering` placement from its current running state and the requested delivery mode, then retains that placement while serialization is in flight. The prompt's `requestId` is the correlation identity: the Host echoes it as the durable user source's `rpcId`, and queue occurrences project it as `SessionQueuedItem.rpcId`. An echo retires one animation frame after its durable event or queue occurrence is observed (the delay keeps it renderable until the replacement is ready), immediately when its identified prompt fails or is abandoned, and as failed on disposal; each retirement fires the registered `onRetire` callback exactly once. Echoes are Client memory only; reload and reconnect rebuild the conversation from durable events alone. ----- @@ -40,6 +42,8 @@ The Session object also carries local submission echoes: `session.beginSubmissio |---|---:|---| | `coldBlankProbeMaxBytes` | `1,024` | Maximum physical size of a cold Session artifact eligible for blankness verification; `0` disables probes | | `nativeOpen` | platform-detected | Whether Session workspace paths can be handed to a native desktop opener | +| `observeFlushMs` | `100` | Coalescing window after new record output before a job-observation read, in milliseconds | +| `observeMaxFrameBytes` | `65,536` | Soft byte budget per job-observation output frame; one larger chunk ships whole | The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-api-session-controller) is the exhaustive source for accepted fields and their JSDoc. diff --git a/packages/bundle/base/cordis.patch.yml b/packages/bundle/base/cordis.patch.yml index adec1a5b4b..eaa8457e88 100644 --- a/packages/bundle/base/cordis.patch.yml +++ b/packages/bundle/base/cordis.patch.yml @@ -81,11 +81,6 @@ - id: jobs name: '@deepseek-ai/dsh-jobs-local' - # Live-activity observation registry: non-consuming output streams for the - # optional activity plane (background bash/pwsh mirror into it when loaded). - - id: activity - name: '@deepseek-ai/dsh-activity-local' - - id: llm-retry name: '@deepseek-ai/dsh-llm-retry' diff --git a/packages/bundle/base/package.json b/packages/bundle/base/package.json index 50a3583899..a203607a5d 100644 --- a/packages/bundle/base/package.json +++ b/packages/bundle/base/package.json @@ -41,7 +41,6 @@ "dependencies": { "@deepseek-ai/cordis-plugin-hmr": "workspace:^", "@deepseek-ai/cordis-plugin-timer": "workspace:^", - "@deepseek-ai/dsh-activity-local": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-agent-default-model": "workspace:^", "@deepseek-ai/dsh-agent-instructions": "workspace:^", diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml index 510d0653f3..85b67e7d08 100644 --- a/packages/bundle/web-app/cordis.patch.yml +++ b/packages/bundle/web-app/cordis.patch.yml @@ -95,10 +95,6 @@ - id: workspace-controller name: '@deepseek-ai/dsh-api-workspace-controller' - # Live-activity roster and per-activity output observation over Typert Remote. - - id: activity-controller - name: '@deepseek-ai/dsh-api-activity-controller' - - id: cordis-host-runner name: '@deepseek-ai/dsh-cordis-host-runner' @@ -258,10 +254,10 @@ name: '@deepseek-ai/dsh-client-ui-reference' - # Live activities: the session-header roster with on-demand streaming - # output panels over the activity feed. - - id: ui-activity - name: '@deepseek-ai/dsh-client-ui-activity' + # Background jobs: the session-header roster with on-demand streaming + # record panels over the session job-output service. + - id: ui-jobs + name: '@deepseek-ai/dsh-client-ui-jobs' # Read-only active Schedule catalog. The shipped Web graph resolves the # client package but leaves it disabled; the explicit Schedule overlay diff --git a/packages/bundle/web-app/package.json b/packages/bundle/web-app/package.json index b6e34b5a79..0a58a1a78c 100644 --- a/packages/bundle/web-app/package.json +++ b/packages/bundle/web-app/package.json @@ -45,7 +45,6 @@ }, "dependencies": { "@deepseek-ai/dsh-agent-presets": "workspace:^", - "@deepseek-ai/dsh-api-activity-controller": "workspace:^", "@deepseek-ai/dsh-api-remotes": "workspace:^", "@deepseek-ai/dsh-api-session-controller": "workspace:^", "@deepseek-ai/dsh-api-settings-controller": "workspace:^", @@ -55,7 +54,7 @@ "@deepseek-ai/dsh-client-hmr": "workspace:^", "@deepseek-ai/dsh-client-locale": "workspace:^", "@deepseek-ai/dsh-client-modules": "workspace:^", - "@deepseek-ai/dsh-client-ui-activity": "workspace:^", + "@deepseek-ai/dsh-client-ui-jobs": "workspace:^", "@deepseek-ai/dsh-client-ui-agent-preset": "workspace:^", "@deepseek-ai/dsh-client-ui-approval": "workspace:^", "@deepseek-ai/dsh-client-ui-attachment": "workspace:^", diff --git a/packages/client/README.md b/packages/client/README.md index 3e45bac9b0..367a6d39ce 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -55,7 +55,7 @@ The kernel packages boot and serve the page; the UI feature packages present it. | [`ui-skill/`](ui-skill/README.md) | Adds skill references to inline suggestions | — | | [`ui-reference/`](ui-reference/README.md) | Unified Web `@file` / `@session` reference source | — | | [`ui-subagent/`](ui-subagent/README.md) | Provides subagent navigation, child transcript states, and inline references | — | -| [`ui-activity/`](ui-activity/README.md) | Lists this session's tasks — jobs joined with their live-output activities | — | +| [`ui-jobs/`](ui-jobs/README.md) | Lists this session's background jobs with on-demand streaming record panels | — | | [`ui-schedule/`](ui-schedule/README.md) | Lists the current Session's active reminders in a read-only header catalog | — | | [`ui-model-selection/`](ui-model-selection/README.md) | Provides model selection in conversation surfaces | — | | [`ui-permission-presets/`](ui-permission-presets/README.md) | Configures default permissions and switches the current session's access | — | diff --git a/packages/client/README.zh.md b/packages/client/README.zh.md index e624cd5f87..05a0143ce4 100644 --- a/packages/client/README.zh.md +++ b/packages/client/README.zh.md @@ -55,7 +55,7 @@ kind: "package-group" | [`ui-skill/`](ui-skill/README.zh.md) | 向内联建议添加 skill(技能)引用 | — | | [`ui-reference/`](ui-reference/README.zh.md) | 统一的 Web `@file` / `@session` 引用 source | — | | [`ui-subagent/`](ui-subagent/README.zh.md) | 提供 subagent(子智能体)导航、子级 transcript(文本记录)状态与内联引用 | — | -| [`ui-activity/`](ui-activity/README.zh.md) | 列出本会话的任务——后台任务与其实时输出 activity 的合并视图 | — | +| [`ui-jobs/`](ui-jobs/README.zh.md) | 列出本会话的后台任务,并提供按需展开的流式输出面板 | — | | [`ui-schedule/`](ui-schedule/README.zh.md) | 在只读标题栏目录中列出当前 Session 的活动提醒 | — | | [`ui-model-selection/`](ui-model-selection/README.zh.md) | 在对话界面中提供模型选择 | — | | [`ui-permission-presets/`](ui-permission-presets/README.zh.md) | 配置默认权限并切换当前会话的访问模式 | — | diff --git a/packages/client/ui-activity/README.md b/packages/client/ui-activity/README.md deleted file mode 100644 index 6630558922..0000000000 --- a/packages/client/ui-activity/README.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -description: "The session-header task list: background jobs joined per row with their live-output activities, expandable streaming panels, running/finished sections, and the graceful no-registry degradation." -kind: "package-reference" ---- - -# @deepseek-ai/dsh-client-ui-activity - -English | [中文](README.zh.md) - -## Summary - -`dsh-client-ui-activity` puts this session's running work in one header control: background jobs joined per row with their correlated live-output activities, plus standalone activities such as workflow runs. Expanding an observable row streams its real output into an embedded terminal panel while it runs; collapsing stops the stream, so output only flows while someone is watching. Live rows lead with a ticking duration over a kind-and-status second line, settled rows compact behind a section heading, and without the activity registry the job rows still render — the control degrades to a plain job list rather than disappearing. - -## Table of Contents - -- [Use this package](#use-this-package) -- [Understand the implementation](#understand-the-implementation) -- [Further Exploration](#further-exploration) -- [Model Experience](#model-experience) -- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work) -- [Dev Note](#dev-note) - ------ - - -## Use this package - -Load the plugin through the web-app manifest; it renders nothing until the session can see at least one task, so an ordinary conversation never grows a control for a capability it is not using. - -### The per-row join - -Jobs and activities stay separate planes ([why](../../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md)); the join happens per row in this component. A job row keeps the job's lifecycle, duration, and model-visible `detail` from the `jobsBySession` mirror, and gains an expandable output panel when an activity carries its `correlation.jobId`; an activity without a job keeps its own row. Rows without an observable activity render as static rows with no expansion affordance. - -### The expanded panel - -Expanding an observable row opens that activity's observation stream from `ctx.activityFeed` into an embedded terminal panel. The panel copies the command (not the output), wraps commands and output lines in full, scrolls its output inside a fixed height instead of folding, and draws no run-state dot of its own — the row above carries the state. Retention gaps and stream failures render as notices above the panel. - ------ - - -## Understand the implementation - -
        -Implementation internals — click to expand - -One slot entry in the header actions band (after the preset label, before the subagent catalog) renders the trigger and popover; the popover fits itself to the viewport by measuring its anchor. All data arrives through `ctx.activityFeed` and the standard `useSessions` hook — the component holds no transport state. Observation follows visibility: one `useEffect` opens the stream for the expanded row's activity and closes it on collapse, unmount, or popover dismissal. - -| File | Role | -|---|---| -| [`src/client/ActivityListAction.tsx`](src/client/ActivityListAction.tsx) | The merged task list: join, sections, durations, panels | -| [`src/client/index.ts`](src/client/index.ts) | Slot registration and the dictionaries | -| [`src/client/locales.ts`](src/client/locales.ts) | The `activity` namespace copy (zh source of truth) | - -
        - ------ - - -## Further Exploration - -- [`dsh-api-activity-controller`](../../api/activity-controller/README.md) — the feed service and streams behind the panel. -- [Unified task list Agent Note](../../../.agents/notes/implemented/feature/2026-08-25-unified-task-list.md) — why the join lives in the UI projection. -- [`dsh-client-ui-primitives`](../ui-primitives/README.md) — the `TerminalBlock` surface the panel configures. - ------ - - -## Model Experience - -None, as this package renders host-observed state and live output for a human and touches no prompt, message, schema, stream, or tool result. The model's own view of the same work stays with [`dsh-tool-jobs`](../../jobs/tool-jobs/README.md). - -#### KV Cache effect - -None; the package never assembles or sends provider requests. - -## Known Limitations and Deferred Work - - - -These limits define current package constraints, not a task backlog. - -- **No kill control** — cancellation stays with the model's `job_kill`; a human kill is blocked on the jobs `reported` contract question recorded in the [web job display Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md). -- **Channel labels are not rendered** — stdout and stderr chunks concatenate into one stream; per-channel tinting is a presentation follow-up. - - -### Dev Note - -
        -Working context for maintainers — click to expand - -None. - -
        diff --git a/packages/client/ui-activity/README.zh.md b/packages/client/ui-activity/README.zh.md deleted file mode 100644 index b02949f251..0000000000 --- a/packages/client/ui-activity/README.zh.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -description: "会话头部任务列表:后台任务与其实时输出 activity 逐行合并、可展开的流式面板、进行中/已结束分组,以及无注册表时的优雅退化。" -kind: "package-reference" ---- - -# @deepseek-ai/dsh-client-ui-activity - -[English](README.md) | 中文 - -## 概述 - -`dsh-client-ui-activity` 把本会话正在跑的工作放进一个头部控件:后台任务与其关联的实时输出 activity 逐行合并,外加 workflow 运行等独立 activity。展开可观察的行,其真实输出在运行期间流入内嵌终端面板;收起即停流——只有有人在看时输出才流动。进行中的行以跳动时长为主行、kind 与状态为副行,已结束的行折叠在分组标题之后;没有 activity 注册表时 job 行照常渲染——控件退化为普通任务列表而不是消失。 - -## 目录 - -- [使用本包](#use-this-package) -- [理解实现](#understand-the-implementation) -- [进一步探索](#further-exploration) -- [模型体验](#model-experience) -- [已知限制与延期工作](#known-limitations-and-deferred-work) -- [开发备注](#dev-note) - ------ - - -## 使用本包 - -经 web-app 清单加载该插件;会话一个任务都看不到时它完全不渲染,普通会话不会为未使用的能力多出控件。 - -### 逐行 join - -jobs 与 activity 保持为两个独立的面([缘由](../../../.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md));合并逐行发生在本组件内。job 行保留来自 `jobsBySession` 镜像的生命周期、时长与模型可见 `detail`,当某个 activity 以 `correlation.jobId` 关联到它时获得可展开的输出面板;没有 job 的 activity 保留自己的行。没有可观察 activity 的行渲染为无展开交互的静态行。 - -### 展开的面板 - -展开可观察的行即把该 activity 在 `ctx.activityFeed` 上的观察流打开进内嵌终端面板。面板的复制控件复制命令(而非输出),命令与输出行完整换行,输出在固定高度内滚动而非折叠,且不画自己的运行状态点——上方的行已携带状态。保留缺口与流失败以面板上方的提示呈现。 - ------ - - -## 理解实现 - -
        -实现内幕——点击展开 - -头部操作区里的一个 slot 条目(preset 标签之后、subagent 目录之前)渲染触发器与弹层;弹层通过测量锚点把自己贴合进视口。所有数据经 `ctx.activityFeed` 与标准 `useSessions` 钩子到达——组件不持有任何传输状态。观察跟随可见性:一个 `useEffect` 为展开行的 activity 开流,在收起、卸载或弹层关闭时关流。 - -| 文件 | 角色 | -|---|---| -| [`src/client/ActivityListAction.tsx`](src/client/ActivityListAction.tsx) | 合并任务列表:join、分组、时长、面板 | -| [`src/client/index.ts`](src/client/index.ts) | slot 注册与词典 | -| [`src/client/locales.ts`](src/client/locales.ts) | `activity` 命名空间文案(zh 为真源) | - -
        - ------ - - -## 进一步探索 - -- [`dsh-api-activity-controller`](../../api/activity-controller/README.zh.md)——面板背后的 feed 服务与流。 -- [统一任务列表 Agent Note](../../../.agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md)——join 为何住在 UI 投影层。 -- [`dsh-client-ui-primitives`](../ui-primitives/README.zh.md)——面板所配置的 `TerminalBlock` 表面。 - ------ - - -## 模型体验 - -无:本包只为人渲染宿主观察到的状态与实时输出,不触碰任何 prompt、消息、schema、流或工具结果。模型对同一工作的视图仍在 [`dsh-tool-jobs`](../../jobs/tool-jobs/README.zh.md)。 - -#### KV Cache 影响 - -无;本包从不组装或发送 provider 请求。 - -## 已知限制与延期工作 - - - -这些限制是当前包约束,不是任务积压。 - -- **没有 kill 控件**——取消仍走模型的 `job_kill`;人工 kill 被 [web job display Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md) 记录的 jobs `reported` 契约问题阻塞。 -- **不渲染通道标签**——stdout 与 stderr chunk 连接成一条流;分通道着色是后续呈现优化。 - - -### 开发备注 - -
        -维护者的工作上下文——点击展开 - -无。 - -
        diff --git a/packages/client/ui-activity/src/client/index.ts b/packages/client/ui-activity/src/client/index.ts deleted file mode 100644 index 39f43df9e1..0000000000 --- a/packages/client/ui-activity/src/client/index.ts +++ /dev/null @@ -1,50 +0,0 @@ -/** - * Task-list plugin, browser half: contributes one session-header action that - * renders this session's tasks — background jobs joined with their correlated - * live-output activities, plus standalone activities such as workflow runs. - * Job rows arrive through the `jobsBySession` list mirror; activity rows and - * per-row observation streams arrive through the `activityFeed` client - * service. This plugin holds no transport state of its own. - */ -import type { Context as ClientContext } from '@deepseek-ai/cordis' -import { ActivityListAction } from './ActivityListAction.tsx' -import type { ActivityListInjected } from './ActivityListAction.tsx' -import type {} from '@deepseek-ai/dsh-api-activity-controller/client' -import type {} from '@deepseek-ai/dsh-client-locale/client' -import type {} from '@deepseek-ai/dsh-client-ui-renderer/client' -import type {} from '@deepseek-ai/dsh-client-ui-session/client' -import { en, NS, zh, type ActivityKey } from './locales.ts' - -declare module '@deepseek-ai/dsh-client-ui-slots' { - interface LocaleNamespaceMap { - /** Live-activity list copy. */ - 'activity': ActivityKey - } -} - -export type { ActivityListActionProps, ActivityListInjected } from './ActivityListAction.tsx' - -/** Required services: session and activity state, the slot registry, and dictionaries. */ -export const inject = ['sessions', 'activityFeed', 'slots', 'locale'] - -/** - * Client plugin body: register the dictionaries and the header action. - * @param ctx - client root context. - */ -export function apply(ctx: ClientContext): void { - ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-activity: dictionaries') - ctx.slots.inject( - 'conversation.session.header.actions', - () => ctx.slots.register({ - name: 'conversation.session.header.actions', - id: 'activity-list', - // After the subagent catalog: session lineage reads before running work. - order: 20, - locale: NS, - inject: (): ActivityListInjected => ({ - hooks: { activity: ctx.activityFeed.state }, - observe: id => ctx.activityFeed.observe(id), - }), - }, ActivityListAction), - ) -} diff --git a/packages/client/ui-activity/README.i18n.yaml b/packages/client/ui-jobs/README.i18n.yaml similarity index 70% rename from packages/client/ui-activity/README.i18n.yaml rename to packages/client/ui-jobs/README.i18n.yaml index bae875ee0e..b968d83fab 100644 --- a/packages/client/ui-activity/README.i18n.yaml +++ b/packages/client/ui-jobs/README.i18n.yaml @@ -1,6 +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 packages/client/ui-activity/README.md -README.md: 6630558922cf9f1e2b772bcc6334a21f91591acb -README.zh.md: b02949f2518c85ba931e0adf76946c390b564d1a +# pnpm run verify-translation-pairing --write packages/client/ui-jobs/README.md +README.md: b93f6b6f9dcb0af26c077634181427105e0b3a1b +README.zh.md: 17809b2203b34bdc78b34984a71fb755d3f67a05 diff --git a/packages/client/ui-jobs/README.md b/packages/client/ui-jobs/README.md new file mode 100644 index 0000000000..b93f6b6f9d --- /dev/null +++ b/packages/client/ui-jobs/README.md @@ -0,0 +1,93 @@ +--- +description: "The session-header background-job list: expandable streaming record panels, running/finished sections, and static rows for jobs without a record." +kind: "package-reference" +--- + +# @deepseek-ai/dsh-client-ui-jobs + +English | [中文](README.zh.md) + +## Summary + +`dsh-client-ui-jobs` puts this session's background jobs in one header control. Every row carries the job's lifecycle, ticking duration, and model-visible `detail` from the `jobsBySession` mirror; a job that declared an observation record additionally offers an expandable panel that streams its real output while it runs. Collapsing stops the stream, so output only flows while someone is watching. Live rows lead with a ticking duration over a kind-and-status second line; settled rows compact behind a section heading; jobs without a record (subagent delegations, PTY sends) render as static rows with no expansion affordance. + +## Table of Contents + +- [Use this package](#use-this-package) +- [Understand the implementation](#understand-the-implementation) +- [Further Exploration](#further-exploration) +- [Model Experience](#model-experience) +- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work) +- [Dev Note](#dev-note) + +----- + + +## Use this package + +Load the plugin through the web-app manifest; it renders nothing until the session can see at least one job, so an ordinary conversation never grows a control for a capability it is not using. + +### One row per job + +The session control stream's `jobsBySession` mirror is the single roster: each `SessionJob` row carries lifecycle, duration, and the model-visible `detail`, and its `outputTotal` field is present exactly when the job declared a record — that presence is what makes a row expandable. There is no second roster to join. + +### The expanded panel + +Expanding an observable row opens that job's record observation stream from `ctx.jobOutput` into an embedded terminal panel. The panel copies the command (not the output), wraps commands and output lines in full, scrolls its output inside a fixed height instead of folding, and draws no run-state dot of its own — the row above carries the state. Retention gaps and stream failures render as notices above the panel. + +----- + + +## Understand the implementation + +
        +Implementation internals — click to expand + +One slot entry in the header actions band (after the preset label, before the subagent catalog) renders the trigger and popover; the popover fits itself to the viewport by measuring its anchor. All data arrives through `ctx.jobOutput` and the standard `useSessions` hook — the component holds no transport state. Observation follows visibility: one `useEffect` opens the stream for the expanded row's job and closes it on collapse, unmount, or popover dismissal. + +| File | Role | +|---|---| +| [`src/client/JobListAction.tsx`](src/client/JobListAction.tsx) | The job list: sections, durations, panels | +| [`src/client/index.ts`](src/client/index.ts) | Slot registration and the dictionaries | +| [`src/client/locales.ts`](src/client/locales.ts) | The `job` namespace copy (zh source of truth) | + +
        + +----- + + +## Further Exploration + +- [`dsh-api-session-controller`](../../api/session-controller/README.md) — the `jobsBySession` mirror and the `session.observeJob` stream behind the panel. +- [`dsh-jobs`](../../jobs/jobs/README.md) — the registry contract that owns the record semantics. +- [`dsh-client-ui-primitives`](../ui-primitives/README.md) — the `TerminalBlock` surface the panel configures. + +----- + + +## Model Experience + +None, as this package renders host-observed state and live output for a human and touches no prompt, message, schema, stream, or tool result. The model's own view of the same work stays with [`dsh-tool-jobs`](../../jobs/tool-jobs/README.md). + +#### KV Cache effect + +None; the package never assembles or sends provider requests. + +## Known Limitations and Deferred Work + + + +These limits define current package constraints, not a task backlog. + +- **No kill control** — cancellation stays with the model's `job_kill`; a human kill is blocked on the jobs `reported` contract question recorded in the [web job display Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md). +- **Channel labels are not rendered** — stdout and stderr chunks concatenate into one stream; per-channel tinting is a presentation follow-up. + + +### Dev Note + +
        +Working context for maintainers — click to expand + +None. + +
        diff --git a/packages/client/ui-jobs/README.zh.md b/packages/client/ui-jobs/README.zh.md new file mode 100644 index 0000000000..17809b2203 --- /dev/null +++ b/packages/client/ui-jobs/README.zh.md @@ -0,0 +1,93 @@ +--- +description: "会话头部后台任务列表:可展开的流式 record 面板、进行中/已结束分组,以及无 record 任务的静态行。" +kind: "package-reference" +--- + +# @deepseek-ai/dsh-client-ui-jobs + +[English](README.md) | 中文 + +## 概述 + +`dsh-client-ui-jobs` 把本会话的后台任务放进一个头部控件。每一行都携带 `jobsBySession` 镜像里该 job 的生命周期、跳动时长与模型可见的 `detail`;声明了观测 record 的 job 额外提供可展开的面板,在运行期间流式呈现其真实输出。收起即停流——只有有人在看时输出才流动。进行中的行以跳动时长为主行、kind 与状态为副行;已结束的行折叠在分组标题之后;没有 record 的 job(subagent 委托、PTY 发送)渲染为无展开操作的静态行。 + +## 目录 + +- [使用本包](#use-this-package) +- [理解实现](#understand-the-implementation) +- [进一步探索](#further-exploration) +- [模型体验](#model-experience) +- [已知限制与延期工作](#known-limitations-and-deferred-work) +- [开发备注](#dev-note) + +----- + + +## 使用本包 + +通过 web-app 清单加载本插件;在会话看得到至少一个 job 之前它不渲染任何东西,因此普通对话不会为未使用的能力长出控件。 + +### 一 job 一行 + +session control 流的 `jobsBySession` 镜像是唯一名册:每个 `SessionJob` 行携带生命周期、时长与模型可见的 `detail`,其 `outputTotal` 字段恰在 job 声明了 record 时存在——这个存在性就是行可展开的依据。不存在需要 join 的第二份名册。 + +### 展开的面板 + +展开可观察的行会从 `ctx.jobOutput` 打开该 job 的 record 观测流,注入内嵌终端面板。面板复制的是命令(不是输出),命令与输出行完整换行,输出在固定高度内滚动而非折叠,且不绘制自己的运行状态点——上方的行承载状态。保留缺口与流中断在面板上方渲染为提示。 + +----- + + +## 理解实现 + +
        +实现内幕——点击展开 + +头部操作带里的一个 slot 条目(preset 标签之后、subagent 目录之前)渲染触发器与弹出层;弹出层通过测量锚点把自己收进视口。所有数据经 `ctx.jobOutput` 与标准 `useSessions` hook 到达——组件不持有任何传输状态。观测跟随可见性:一个 `useEffect` 为展开行的 job 打开流,并在收起、卸载或弹出层关闭时关闭它。 + +| 文件 | 角色 | +|---|---| +| [`src/client/JobListAction.tsx`](src/client/JobListAction.tsx) | 任务列表:分组、时长、面板 | +| [`src/client/index.ts`](src/client/index.ts) | slot 注册与词典 | +| [`src/client/locales.ts`](src/client/locales.ts) | `job` 命名空间文案(zh 为事实源) | + +
        + +----- + + +## 进一步探索 + +- [`dsh-api-session-controller`](../../api/session-controller/README.zh.md) —— 面板背后的 `jobsBySession` 镜像与 `session.observeJob` 流。 +- [`dsh-jobs`](../../jobs/jobs/README.zh.md) —— 拥有 record 语义的注册表契约。 +- [`dsh-client-ui-primitives`](../ui-primitives/README.zh.md) —— 面板所配置的 `TerminalBlock` 表面。 + +----- + + +## 模型体验 + +无。本包为人类渲染宿主观测到的状态与实时输出,不触碰任何提示词、消息、schema、流或工具结果。模型对同一工作的视图仍在 [`dsh-tool-jobs`](../../jobs/tool-jobs/README.zh.md)。 + +#### KV 缓存影响 + +无;本包从不组装或发送 provider 请求。 + +## 已知限制与延期工作 + + + +这些限制界定当前包约束,不是任务清单。 + +- **没有 kill 控件**——取消仍归模型的 `job_kill`;人工 kill 卡在 [web 任务显示 Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md) 记录的 jobs `reported` 契约问题上。 +- **不渲染 channel 标签**——stdout 与 stderr 块拼接为一条流;按 channel 着色是展示层的后续工作。 + + +### 开发备注 + +
        +维护者工作语境——点击展开 + +无。 + +
        diff --git a/packages/client/ui-activity/package.json b/packages/client/ui-jobs/package.json similarity index 83% rename from packages/client/ui-activity/package.json rename to packages/client/ui-jobs/package.json index cd558c41d2..5b29f894b6 100644 --- a/packages/client/ui-activity/package.json +++ b/packages/client/ui-jobs/package.json @@ -1,6 +1,6 @@ { - "name": "@deepseek-ai/dsh-client-ui-activity", - "description": "Session-header task list: background jobs joined with their live-output activities, with on-demand streaming output panels", + "name": "@deepseek-ai/dsh-client-ui-jobs", + "description": "Session-header background-job list with on-demand streaming record panels", "version": "0.1.2-alpha.2", "type": "module", "main": "lib/index.js", @@ -29,7 +29,7 @@ "repository": { "type": "git", "url": "git+https://github.com/deepseek-ai/deepseek-harness.git", - "directory": "packages/client/ui-activity" + "directory": "packages/client/ui-jobs" }, "publishConfig": { "access": "public" @@ -39,7 +39,6 @@ }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-activity-controller": "workspace:^", "@deepseek-ai/dsh-api-session-controller": "workspace:^", "@deepseek-ai/dsh-client-locale": "workspace:^", "@deepseek-ai/dsh-client-test-runtime": "workspace:^", @@ -49,6 +48,7 @@ "@deepseek-ai/dsh-client-ui-session": "workspace:^", "@deepseek-ai/dsh-client-ui-slots": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", "@types/react": "~18.3.1", "react": "^18.2.0" }, @@ -61,7 +61,7 @@ "dsh": { "client": { "inject": [ - "@deepseek-ai/dsh-api-activity-controller", + "@deepseek-ai/dsh-api-session-controller", "@deepseek-ai/dsh-client-locale", "@deepseek-ai/dsh-client-ui-conversation", "@deepseek-ai/dsh-client-ui-primitives" diff --git a/packages/client/ui-activity/src/client/ActivityListAction.module.css b/packages/client/ui-jobs/src/client/JobListAction.module.css similarity index 100% rename from packages/client/ui-activity/src/client/ActivityListAction.module.css rename to packages/client/ui-jobs/src/client/JobListAction.module.css diff --git a/packages/client/ui-activity/src/client/ActivityListAction.tsx b/packages/client/ui-jobs/src/client/JobListAction.tsx similarity index 61% rename from packages/client/ui-activity/src/client/ActivityListAction.tsx rename to packages/client/ui-jobs/src/client/JobListAction.tsx index 41f4d7a4b1..edac6497f6 100644 --- a/packages/client/ui-activity/src/client/ActivityListAction.tsx +++ b/packages/client/ui-jobs/src/client/JobListAction.tsx @@ -1,8 +1,7 @@ import { useEffect, useLayoutEffect, useMemo, useRef, useState, type KeyboardEvent } from 'react' -import type { - ActivityFeedSnapshot, ActivityId, ActivityRow, ObservedActivity, -} from '@deepseek-ai/dsh-api-activity-controller/client' +import type { JobOutputSnapshot, ObservedJob } from '@deepseek-ai/dsh-api-session-controller/client' import type { SessionJob } from '@deepseek-ai/dsh-api-session-controller/types' +import type { SessionId } from '@deepseek-ai/dsh-session/types' import { IconChevronDownOutline14, StateDot, TerminalBlock, useDismissOnOutsidePointer, type StateDotState, type TerminalBlockLabels, @@ -10,74 +9,57 @@ import { import type { InjectFace, PropsLocale, PropsRuntime, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots' import { NS } from './locales.ts' import type {} from '@deepseek-ai/dsh-client-ui-conversation/client' -import css from './ActivityListAction.module.css' +import css from './JobListAction.module.css' -/** Registration-side business face for the activity feed. */ -export interface ActivityListInjected { +/** Registration-side business face for the job list. */ +export interface JobListInjected { hooks: { - /** Client activity snapshot bound by the renderer as useActivity. */ - activity: { - getSnapshot(): ActivityFeedSnapshot + /** Client job-output snapshot bound by the renderer as useJobOutput. */ + jobOutput: { + getSnapshot(): JobOutputSnapshot subscribe(listener: () => void): () => void } } /** - * Start observing one activity's live output; returns the stop function. - * Reference-counted by the client feed, so panels can overlap safely. + * Start observing one job's live record; returns the stop function. + * Reference-counted by the client service, so panels can overlap safely. */ - observe: (id: ActivityId) => () => void + observe: (sessionId: SessionId | undefined, id: SessionJob['id']) => () => void } -/** Full props for the session-header task-list action. */ -export type ActivityListActionProps = +/** Full props for the session-header job-list action. */ +export type JobListActionProps = PropsRuntime<'conversation.session.header.actions'> & PropsLocale - & InjectFace + & InjectFace -/** - * One merged task row. Jobs and activities are separate planes — the control - * plane the model interacts with, and the transient observation plane — so - * this list joins them per row: a job carries identity, lifecycle, and the - * model-visible detail; its correlated activity contributes the observable - * live output; an activity without a job (a workflow run) stands alone. - */ -interface TaskRow { - /** Stable row identity: the job id when one exists, else the activity id. */ - key: string - kind: string - label: string - /** Job lifecycle vocabulary; activity-only rows never reach `stopping`. */ - status: SessionJob['status'] - detail?: string - startedAt: number - finishedAt?: number - /** Present when this row's live output can be observed. */ - activityId?: ActivityId -} - -/** Stable empty lists so a session with no work keeps one array identity. */ -const NO_ROWS: readonly ActivityRow[] = [] +/** Stable empty list so a session with no jobs keeps one array identity. */ const NO_JOBS: readonly SessionJob[] = [] /** Minimum gap kept between the popover and the viewport edges (the Menu primitive's portal margin). */ const VIEWPORT_MARGIN = 12 -function isLive(row: TaskRow): boolean { - return row.status === 'running' || row.status === 'stopping' +function isLive(job: SessionJob): boolean { + return job.status === 'running' || job.status === 'stopping' +} + +/** True exactly when the job declared an observation record. */ +function isObservable(job: SessionJob): boolean { + return job.outputTotal !== undefined } /** Closed-union exhaustiveness fence for the wire status set. */ /* v8 ignore next 3 -- closed-union backstop; only reached if a status is forged */ function assertNever(value: never): never { - throw new Error(`unhandled task status: ${JSON.stringify(value)}`) + throw new Error(`unhandled job status: ${JSON.stringify(value)}`) } /** * Status marker semantics. `stopping` and `killed` share the attention color: * both mean the work ended (or is ending) on request rather than on its own. */ -function dotState(status: TaskRow['status']): StateDotState { +function dotState(status: SessionJob['status']): StateDotState { switch (status) { case 'running': return 'ongoing' case 'stopping': return 'warning' @@ -89,7 +71,7 @@ function dotState(status: TaskRow['status']): StateDotState { } } -function statusLabel(status: TaskRow['status'], t: TranslateNS): string { +function statusLabel(status: SessionJob['status'], t: TranslateNS): string { switch (status) { case 'running': return t('status.running') case 'stopping': return t('status.stopping') @@ -102,7 +84,7 @@ function statusLabel(status: TaskRow['status'], t: TranslateNS): stri } /** - * Elapsed time in at most two adjacent units. A task that outlives an hour is + * Elapsed time in at most two adjacent units. A job that outlives an hour is * already exceptional, so hours is the widest unit — beyond that the figure * stays in hours rather than growing a day/month vocabulary no producer * currently reaches. @@ -143,66 +125,13 @@ function terminalLabels(t: TranslateNS): TerminalBlockLabels { } } -/** Project one standalone activity into the merged row vocabulary. */ -function activityTask(activity: ActivityRow): TaskRow { - return { - key: String(activity.id), - kind: activity.kind, - label: activity.label, - status: activity.status, - ...activity.detail !== undefined ? { detail: activity.detail } : {}, - startedAt: activity.startedAt, - ...activity.finishedAt !== undefined ? { finishedAt: activity.finishedAt } : {}, - activityId: activity.id, - } -} - -/** - * Join this session's jobs with their correlated activities and append the - * activities that stand alone. A job row keeps the job's lifecycle and detail - * (what the model sees) and gains observability from its activity; an - * activity whose job is not in the projection keeps its own row rather than - * disappearing. - */ -function mergeRows( - jobs: readonly SessionJob[], - activities: readonly ActivityRow[], -): TaskRow[] { - const byJob = new Map() - const standalone: ActivityRow[] = [] - for (const activity of activities) { - const jobId = activity.correlation?.jobId - if (jobId === undefined) standalone.push(activity) - // One activity per job: every shipped producer opens at most one, so a - // duplicate jobId keeps only the newest row rather than growing the list. - else byJob.set(String(jobId), activity) - } - const rows: TaskRow[] = jobs.map((job) => { - const activity = byJob.get(String(job.id)) - byJob.delete(String(job.id)) - return { - key: String(job.id), - kind: job.kind, - label: job.label, - status: job.status, - ...job.detail !== undefined ? { detail: job.detail } : {}, - startedAt: job.startedAt, - ...job.finishedAt !== undefined ? { finishedAt: job.finishedAt } : {}, - ...activity !== undefined ? { activityId: activity.id } : {}, - } - }) - for (const activity of byJob.values()) rows.push(activityTask(activity)) - for (const activity of standalone) rows.push(activityTask(activity)) - return rows -} - /** * Live rows first in start order, then settled rows newest-first. Two rows * that settled in the same millisecond fall back to start order, so the sort * never depends on the host's map iteration. */ -function ordered(rows: readonly TaskRow[]): TaskRow[] { - return [...rows].sort((left, right) => { +function ordered(jobs: readonly SessionJob[]): SessionJob[] { + return [...jobs].sort((left, right) => { const liveLeft = isLive(left) if (liveLeft !== isLive(right)) return liveLeft ? -1 : 1 if (liveLeft) return left.startedAt - right.startedAt @@ -211,21 +140,21 @@ function ordered(rows: readonly TaskRow[]): TaskRow[] { }) } -/** One task row plus, when observable and expanded, its live output panel. */ -function TaskItem({ row, view, expanded, now, onToggle, t }: { - row: TaskRow - view: ObservedActivity | undefined +/** One job row plus, when observable and expanded, its live output panel. */ +function JobItem({ job, view, expanded, now, onToggle, t }: { + job: SessionJob + view: ObservedJob | undefined expanded: boolean /** Clock sample live rows derive their running duration from. */ now: number onToggle: () => void t: TranslateNS }) { - const live = isLive(row) - const status = statusLabel(row.status, t) - const observable = row.activityId !== undefined + const live = isLive(job) + const status = statusLabel(job.status, t) + const observable = isObservable(job) const labels = useMemo(() => terminalLabels(t), [t]) - const elapsed = live ? now - row.startedAt : (row.finishedAt ?? row.startedAt) - row.startedAt + const elapsed = live ? now - job.startedAt : (job.finishedAt ?? job.startedAt) - job.startedAt const duration = formatDuration(elapsed, t) const durationCell = ( - + - {row.label} + {job.label} {durationCell} - {row.kind} - {row.detail ?? status} + {job.kind} + {job.detail ?? status} {observable ? : null} @@ -254,10 +183,10 @@ function TaskItem({ row, view, expanded, now, onToggle, t }: { ) : ( <> - - {row.kind} - {row.label} - {row.detail ?? status} + + {job.kind} + {job.label} + {job.detail ?? status} {durationCell} {observable ? : null} @@ -270,7 +199,7 @@ function TaskItem({ row, view, expanded, now, onToggle, t }: { type="button" className={live ? css.row : `${css.row} ${css.rowSettled}`} aria-expanded={expanded} - aria-label={t(expanded ? 'row.collapseAria' : 'row.expandAria', { label: row.label })} + aria-label={t(expanded ? 'row.collapseAria' : 'row.expandAria', { label: job.label })} onClick={onToggle} > {body} @@ -289,10 +218,10 @@ function TaskItem({ row, view, expanded, now, onToggle, t }: { ?
        {t('output.error', { error: view.error })}
        : null} state.jobsBySession[sessionId]) ?? NO_JOBS - const owned = useActivity(state => state.rowsBySession[sessionId]) ?? NO_ROWS - const unowned = useActivity(state => state.rowsBySession['']) ?? NO_ROWS - const observedViews = useActivity(state => state.observed) + const observedViews = useJobOutput(state => state.observed) const [open, setOpen] = useState(false) const [expandedKey, setExpandedKey] = useState(undefined) const [now, setNow] = useState(() => Date.now()) @@ -333,12 +259,9 @@ export function ActivityListAction({ sessionId, useSessions, useActivity, observ // inside the viewport (the stylesheet alone cannot see the anchor offset). const [menuShift, setMenuShift] = useState(0) - const rows = useMemo( - () => ordered(mergeRows(jobs, [...owned, ...unowned])), - [jobs, owned, unowned], - ) + const rows = useMemo(() => ordered(jobs), [jobs]) const liveRows = useMemo(() => rows.filter(isLive), [rows]) - const settledRows = useMemo(() => rows.filter(row => !isLive(row)), [rows]) + const settledRows = useMemo(() => rows.filter(job => !isLive(job)), [rows]) useDismissOnOutsidePointer(rootRef, open, setOpen) @@ -378,15 +301,16 @@ export function ActivityListAction({ sessionId, useSessions, useActivity, observ // Observation follows visibility: the stream opens when an observable panel // expands and closes when it collapses, unmounts, or the popover closes. - const activeActivity = open && expandedKey !== undefined - ? rows.find(row => row.key === expandedKey)?.activityId + const expandedRow = open && expandedKey !== undefined + ? rows.find(job => String(job.id) === expandedKey) : undefined + const activeJob = expandedRow !== undefined && isObservable(expandedRow) ? expandedRow.id : undefined useEffect(() => { - if (activeActivity === undefined) return - return observe(activeActivity) - }, [activeActivity, observe]) + if (activeJob === undefined) return + return observe(sessionId, activeJob) + }, [sessionId, activeJob, observe]) - // The last task disappearing removes this control; close first so focus + // The last job disappearing removes this control; close first so focus // does not vanish from an unmounting node. useEffect(() => { if (rows.length === 0 && open) setOpen(false) @@ -394,7 +318,7 @@ export function ActivityListAction({ sessionId, useSessions, useActivity, observ // An expanded row that left the list (owner disposal) folds its panel. useEffect(() => { - if (expandedKey !== undefined && !rows.some(row => row.key === expandedKey)) { + if (expandedKey !== undefined && !rows.some(job => String(job.id) === expandedKey)) { setExpandedKey(undefined) } }, [rows, expandedKey]) @@ -413,15 +337,15 @@ export function ActivityListAction({ sessionId, useSessions, useActivity, observ triggerRef.current?.focus() } - const item = (row: TaskRow) => ( - ( + { - setExpandedKey(current => current === row.key ? undefined : row.key) + setExpandedKey(current => current === String(job.id) ? undefined : String(job.id)) }} t={t} /> @@ -437,7 +361,7 @@ export function ActivityListAction({ sessionId, useSessions, useActivity, observ aria-label={countLabel} onClick={() => { // Sample the clock in the same commit that opens the list: the - // mount-time value predates every task, so the first painted frame + // mount-time value predates every job, so the first painted frame // would otherwise clamp a long-running row to zero until the // open effect corrects it a frame later. setNow(Date.now()) diff --git a/packages/client/ui-jobs/src/client/index.ts b/packages/client/ui-jobs/src/client/index.ts new file mode 100644 index 0000000000..164b6f6e3c --- /dev/null +++ b/packages/client/ui-jobs/src/client/index.ts @@ -0,0 +1,49 @@ +/** + * Background-job plugin, browser half: contributes one session-header action + * that renders this session's jobs. Job rows arrive through the + * `jobsBySession` list mirror; per-row observation streams arrive through the + * `jobOutput` client service. This plugin holds no transport state of its + * own. + */ +import type { Context as ClientContext } from '@deepseek-ai/cordis' +import { JobListAction } from './JobListAction.tsx' +import type { JobListInjected } from './JobListAction.tsx' +import type {} from '@deepseek-ai/dsh-api-session-controller/client' +import type {} from '@deepseek-ai/dsh-client-locale/client' +import type {} from '@deepseek-ai/dsh-client-ui-renderer/client' +import type {} from '@deepseek-ai/dsh-client-ui-session/client' +import { en, NS, zh, type JobKey } from './locales.ts' + +declare module '@deepseek-ai/dsh-client-ui-slots' { + interface LocaleNamespaceMap { + /** Background-job list copy. */ + 'job': JobKey + } +} + +export type { JobListActionProps, JobListInjected } from './JobListAction.tsx' + +/** Required services: session state, job observation, the slot registry, and dictionaries. */ +export const inject = ['sessions', 'jobOutput', 'slots', 'locale'] + +/** + * Client plugin body: register the dictionaries and the header action. + * @param ctx - client root context. + */ +export function apply(ctx: ClientContext): void { + ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-jobs: dictionaries') + ctx.slots.inject( + 'conversation.session.header.actions', + () => ctx.slots.register({ + name: 'conversation.session.header.actions', + id: 'job-list', + // After the subagent catalog: session lineage reads before running work. + order: 20, + locale: NS, + inject: (): JobListInjected => ({ + hooks: { jobOutput: ctx.jobOutput.state }, + observe: (sessionId, id) => ctx.jobOutput.observe(sessionId, id), + }), + }, JobListAction), + ) +} diff --git a/packages/client/ui-activity/src/client/locales.ts b/packages/client/ui-jobs/src/client/locales.ts similarity index 78% rename from packages/client/ui-activity/src/client/locales.ts rename to packages/client/ui-jobs/src/client/locales.ts index d4fb08ec31..d2d36b74d1 100644 --- a/packages/client/ui-activity/src/client/locales.ts +++ b/packages/client/ui-jobs/src/client/locales.ts @@ -1,15 +1,15 @@ -/** `activity` namespace dictionaries. */ +/** `job` namespace dictionaries. */ /** Dictionary namespace owned by this plugin. */ -export const NS = 'activity' +export const NS = 'job' /** Simplified Chinese dictionary (the key-set source of truth). */ export const zh = { - 'count.live.one': '{count} 个任务进行中', - 'count.live.other': '{count} 个任务进行中', - 'count.idle.one': '{count} 个任务', - 'count.idle.other': '{count} 个任务', - 'list.aria': '任务', + 'count.live.one': '{count} 个后台任务运行中', + 'count.live.other': '{count} 个后台任务运行中', + 'count.idle.one': '{count} 个后台任务', + 'count.idle.other': '{count} 个后台任务', + 'list.aria': '后台任务', 'section.live': '进行中', 'section.settled': '已结束', 'row.expandAria': '展开 {label} 的实时输出', @@ -41,12 +41,12 @@ export const zh = { } as const /** English dictionary, key-identical to the Chinese source of truth. */ -export const en: Record = { - 'count.live.one': '{count} task running', - 'count.live.other': '{count} tasks running', - 'count.idle.one': '{count} task', - 'count.idle.other': '{count} tasks', - 'list.aria': 'Tasks', +export const en: Record = { + 'count.live.one': '{count} background job running', + 'count.live.other': '{count} background jobs running', + 'count.idle.one': '{count} background job', + 'count.idle.other': '{count} background jobs', + 'list.aria': 'Background jobs', 'section.live': 'Running', 'section.settled': 'Finished', 'row.expandAria': 'Show live output of {label}', @@ -77,5 +77,5 @@ export const en: Record = { 'terminal.expandAria': 'Expand {n} collapsed output lines', } -/** Key domain of the `activity` namespace (zh is the source of truth). */ -export type ActivityKey = keyof typeof zh +/** Key domain of the `job` namespace (zh is the source of truth). */ +export type JobKey = keyof typeof zh diff --git a/packages/client/ui-activity/src/css-modules.d.ts b/packages/client/ui-jobs/src/css-modules.d.ts similarity index 100% rename from packages/client/ui-activity/src/css-modules.d.ts rename to packages/client/ui-jobs/src/css-modules.d.ts diff --git a/packages/client/ui-activity/src/index.ts b/packages/client/ui-jobs/src/index.ts similarity index 66% rename from packages/client/ui-activity/src/index.ts rename to packages/client/ui-jobs/src/index.ts index f75578ddaf..457e7eeb9c 100644 --- a/packages/client/ui-activity/src/index.ts +++ b/packages/client/ui-jobs/src/index.ts @@ -1,8 +1,8 @@ /** - * Node half of the live-activity list plugin. The browser half in + * Node half of the background-job list plugin. The browser half in * `src/client/` owns every contribution; this entry exists so the package * appears as an ordinary Loader row. - * @module @deepseek-ai/dsh-client-ui-activity + * @module @deepseek-ai/dsh-client-ui-jobs */ /** Loader-visible no-op body; the browser half carries the feature. */ diff --git a/packages/client/ui-activity/src/invariant.ts b/packages/client/ui-jobs/src/invariant.ts similarity index 70% rename from packages/client/ui-activity/src/invariant.ts rename to packages/client/ui-jobs/src/invariant.ts index 22eba24c42..51ae72f998 100644 --- a/packages/client/ui-activity/src/invariant.ts +++ b/packages/client/ui-jobs/src/invariant.ts @@ -1,20 +1,20 @@ /** - * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-activity`. - * @module @deepseek-ai/dsh-client-ui-activity/invariant + * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-jobs`. + * @module @deepseek-ai/dsh-client-ui-jobs/invariant */ /* jscpd:ignore-start */ import type { Context } from '@deepseek-ai/cordis' import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants' -const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-activity' +const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-jobs' /** Cordis companion plugin name. */ -export const name = 'client-ui-activity-invariant' +export const name = 'client-ui-jobs-invariant' /** Service required before the companion can reserve package ownership. */ export const inject = ['invariants'] -/** No runtime invariant: pure presentation over the activity feed's client snapshot; the feed's own packages assert the data relations. */ +/** No runtime invariant: pure presentation over client snapshots; the registry packages assert the data relations. */ const install: InvariantInstaller = () => {} /** diff --git a/packages/client/ui-activity/tests/browser-plugin.client.spec.ts b/packages/client/ui-jobs/tests/browser-plugin.client.spec.ts similarity index 73% rename from packages/client/ui-activity/tests/browser-plugin.client.spec.ts rename to packages/client/ui-jobs/tests/browser-plugin.client.spec.ts index 3f84c2252d..8de72f8ccd 100644 --- a/packages/client/ui-activity/tests/browser-plugin.client.spec.ts +++ b/packages/client/ui-jobs/tests/browser-plugin.client.spec.ts @@ -1,5 +1,5 @@ /** - * ui-activity plugin halves: the browser entry's dictionary and header-slot + * ui-jobs plugin halves: the browser entry's dictionary and header-slot * registrations against the real SlotRegistry (with fiber teardown proving * removal — HMR safety), the inert node entry, and the invariant companion's * ownership reservation. @@ -12,7 +12,7 @@ import { stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime' import { apply as applyLocale, inject as localeInject } from '@deepseek-ai/dsh-client-locale/client' import { apply, inject } from '../src/client/index.ts' import { apply as applyNode } from '../src/index.ts' -import * as ActivityInvariant from '../src/invariant.ts' +import * as JobsInvariant from '../src/invariant.ts' import { en, NS, zh } from '../src/client/locales.ts' /** Slot ledger reader: entry ids currently registered in the header list. */ @@ -22,8 +22,8 @@ function headerEntryIds(ctx: Context): (string | undefined)[] { .map(entry => entry.options.id) } -/** Ids handed to the stubbed feed's observe control. */ -const observed: string[] = [] +/** Observation requests handed to the stubbed job-output control. */ +const observed: [string | undefined, string][] = [] /** Boot the browser half over a real slot tree that declares the header list. */ async function bench(): Promise<{ ctx: Context; fiber: ReturnType }> { @@ -36,9 +36,12 @@ async function bench(): Promise<{ ctx: Context; fiber: ReturnType null) ctx.provide('sessions', {} as never) - ctx.provide('activityFeed', { - state: { getSnapshot: () => ({ rowsBySession: {}, observed: {}, phase: 'pending' }), subscribe: () => () => {} }, - observe: (id: string) => { observed.push(id); return () => {} }, + ctx.provide('jobOutput', { + state: { getSnapshot: () => ({ observed: {} }), subscribe: () => () => {} }, + observe: (sessionId: string | undefined, id: string) => { + observed.push([sessionId, id]) + return () => {} + }, } as never) // The locale plugin binds a settings scope, which reads the connection handle // and the forwarded-event port. @@ -55,30 +58,33 @@ async function bench(): Promise<{ ctx: Context; fiber: ReturnType { +describe('ui-jobs browser half', () => { it('declares the services it binds', () => { - expect(inject).toEqual(['sessions', 'activityFeed', 'slots', 'locale']) + expect(inject).toEqual(['sessions', 'jobOutput', 'slots', 'locale']) }) - it('exposes the feed source and observation control through the inject face', async () => { + it('exposes the output source and observation control through the inject face', async () => { const { ctx } = await bench() const entry = ctx.slots .entries('conversation.session.header.actions') - .find(candidate => candidate.options.id === 'activity-list') + .find(candidate => candidate.options.id === 'job-list') const face = (entry as unknown as { - inject: () => { hooks: { activity: unknown }; observe: (id: string) => () => void } + inject: () => { + hooks: { jobOutput: unknown } + observe: (sessionId: string | undefined, id: string) => () => void + } }).inject() - expect(face.hooks.activity).toBeDefined() - const stopper = face.observe('bash-1') - expect(observed).toEqual(['bash-1']) + expect(face.hooks.jobOutput).toBeDefined() + const stopper = face.observe('session', 'bash-1') + expect(observed).toEqual([['session', 'bash-1']]) stopper() }) it('registers the header action, and fiber teardown removes it (HMR safety)', async () => { const { ctx, fiber } = await bench() - expect(headerEntryIds(ctx)).toContain('activity-list') + expect(headerEntryIds(ctx)).toContain('job-list') await fiber.dispose() - expect(headerEntryIds(ctx)).not.toContain('activity-list') + expect(headerEntryIds(ctx)).not.toContain('job-list') }) it('registers both dictionaries under its own namespace and releases them with the fiber', async () => { @@ -98,19 +104,19 @@ describe('ui-activity browser half', () => { }) }) -describe('ui-activity node half', () => { +describe('ui-jobs node half', () => { it('contributes no host behavior', () => { // The node half exists only so the plugin appears in the Loader tree. expect(applyNode).not.toThrow() }) }) -describe('ui-activity invariant companion', () => { +describe('ui-jobs invariant companion', () => { it('reserves package ownership under its declared companion name', async () => { const ctx = new Context() await ctx.plugin(InvariantRegistry, { enabled: true }) - await ctx.plugin(ActivityInvariant) - expect(ActivityInvariant.name).toBe('client-ui-activity-invariant') - expect(ActivityInvariant.inject).toEqual(['invariants']) + await ctx.plugin(JobsInvariant) + expect(JobsInvariant.name).toBe('client-ui-jobs-invariant') + expect(JobsInvariant.inject).toEqual(['invariants']) }) }) diff --git a/packages/client/ui-activity/tests/activity-list-action.client.spec.tsx b/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx similarity index 59% rename from packages/client/ui-activity/tests/activity-list-action.client.spec.tsx rename to packages/client/ui-jobs/tests/job-list-action.client.spec.tsx index ffb4ce5492..15bd8ec4a9 100644 --- a/packages/client/ui-activity/tests/activity-list-action.client.spec.tsx +++ b/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx @@ -2,12 +2,10 @@ import { afterEach, describe, expect, it, vi } from 'vitest' import { act, cleanup, fireEvent, render, screen, within } from '@testing-library/react' import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime' -import type { - ActivityFeedSnapshot, ActivityId, ActivityRow, ObservedActivity, -} from '@deepseek-ai/dsh-api-activity-controller/client' +import type { JobOutputSnapshot, ObservedJob } from '@deepseek-ai/dsh-api-session-controller/client' import type { SessionJob } from '@deepseek-ai/dsh-api-session-controller/types' import type { SessionId } from '@deepseek-ai/dsh-session/types' -import { ActivityListAction, type ActivityListActionProps } from '../src/client/ActivityListAction.tsx' +import { JobListAction, type JobListActionProps } from '../src/client/JobListAction.tsx' import { zh } from '../src/client/locales.ts' afterEach(() => { @@ -17,26 +15,7 @@ afterEach(() => { }) const SESSION = 'session' as SessionId -const t: ActivityListActionProps['t'] = makeTranslate(zh) - -function row(over: Partial = {}): ActivityRow { - return { - id: 'bash-1' as ActivityId, - kind: 'bash', - label: 'pnpm run build', - sessionId: SESSION, - status: 'running', - startedAt: 1_700_000_000_000, - outputTotal: 0, - ...over, - } -} - -/** A row with no owner session, as the unowned bucket carries them. */ -function unownedRow(over: Partial = {}): ActivityRow { - const { sessionId: _drop, ...rest } = row(over) - return rest -} +const t: JobListActionProps['t'] = makeTranslate(zh) function job(over: Partial = {}): SessionJob { return { @@ -49,117 +28,88 @@ function job(over: Partial = {}): SessionJob { } } +/** A job that declared an observation record, so its row offers a panel. */ +function recordJob(over: Partial = {}): SessionJob { + return job({ outputTotal: 0, ...over }) +} + function props( - snapshot: Partial, - observe: ActivityListActionProps['observe'] = () => () => {}, - jobs: readonly SessionJob[] = [], -): ActivityListActionProps { - const state: ActivityFeedSnapshot = { - rowsBySession: {}, - observed: {}, - phase: 'ready', - ...snapshot, - } - function useActivity(select: (value: ActivityFeedSnapshot) => T): T { - return select(state) + jobs: readonly SessionJob[], + observe: JobListActionProps['observe'] = () => () => {}, + observed: Readonly> = {}, +): JobListActionProps { + const outputState: JobOutputSnapshot = { observed } + function useJobOutput(select: (value: JobOutputSnapshot) => T): T { + return select(outputState) } const sessionsState = { jobsBySession: jobs.length > 0 ? { [SESSION]: jobs } : {} } function useSessions(select: (value: typeof sessionsState) => T): T { return select(sessionsState) } - return { sessionId: SESSION, useSessions, useActivity, observe, t } as unknown as ActivityListActionProps + return { sessionId: SESSION, useSessions, useJobOutput, observe, t } as unknown as JobListActionProps } function openList(): void { fireEvent.click(screen.getAllByRole('button')[0]!) } -describe('ActivityListAction visibility', () => { - it('renders nothing while the session sees no tasks', () => { - const { container } = render() +describe('JobListAction visibility', () => { + it('renders nothing while the session sees no jobs', () => { + const { container } = render() expect(container.innerHTML).toBe('') }) - it('counts live tasks on the trigger, merging owned and unowned activity rows', () => { - render() - expect(screen.getByRole('button', { name: '2 个任务进行中' })).toBeDefined() + it('counts live jobs on the trigger', () => { + render() + expect(screen.getByRole('button', { name: '2 个后台任务运行中' })).toBeDefined() }) - it('falls back to the total when nothing is live and hides foreign sessions', () => { - render() - expect(screen.getByRole('button', { name: '1 个任务' })).toBeDefined() + it('falls back to the total when nothing is live', () => { + render() + expect(screen.getByRole('button', { name: '1 个后台任务' })).toBeDefined() }) }) -describe('ActivityListAction merged rows', () => { - it('joins a job with its correlated activity: job lifecycle, activity output', () => { - const observe = vi.fn(() => () => {}) - render() - openList() - const list = screen.getByRole('list', { name: zh['list.aria'] }) - // One merged row: the job's label and lifecycle word, not the activity's. - expect(within(list).getAllByRole('listitem')).toHaveLength(1) - expect(within(list).getByText('pnpm run build')).toBeDefined() - expect(screen.queryByText('activity-side label')).toBeNull() - expect(within(list).getByText('winding down')).toBeDefined() - // Expansion observes the correlated activity's stream. - fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) - expect(observe).toHaveBeenCalledWith('bash-act-7') - }) - - it('renders a bare job row without expansion affordances', () => { - render( { + it('renders a record-less job row without expansion affordances', () => { + render() - expect(screen.getByRole('button', { name: '1 个任务进行中' })).toBeDefined() + expect(screen.getByRole('button', { name: '1 个后台任务运行中' })).toBeDefined() openList() expect(screen.getByText('explore the repo')).toBeDefined() expect(screen.queryByRole('button', { name: zh['row.expandAria'].replace('{label}', 'explore the repo') })).toBeNull() }) - it('keeps an activity whose job is not in the projection', () => { - render() + it('shows the live detail line in place of the status word', () => { + render() openList() - expect(screen.getByText('pnpm run build')).toBeDefined() + const list = screen.getByRole('list', { name: zh['list.aria'] }) + expect(within(list).getAllByRole('listitem')).toHaveLength(1) + expect(within(list).getByText('pnpm run build')).toBeDefined() + expect(within(list).getByText('winding down')).toBeDefined() }) it('labels each non-empty section and drops the heading of an empty one', () => { const settled = [job({ id: 'bash-2' as SessionJob['id'], status: 'completed', finishedAt: 1_700_000_012_000 })] - const { rerender } = render() + const { rerender } = render() openList() expect(screen.getByText(zh['section.live'])).toBeDefined() expect(screen.getByText(zh['section.settled'])).toBeDefined() // A live-only list keeps its own heading and drops the settled one. - rerender() + rerender() expect(screen.getByText(zh['section.live'])).toBeDefined() expect(screen.queryByText(zh['section.settled'])).toBeNull() }) it('shows a settled duration and ticks a live one', () => { vi.useFakeTimers({ now: 1_700_000_020_000 }) - render( { act(() => { vi.advanceTimersByTime(1_000) }) expect(screen.getByText('6秒')).toBeDefined() }) -}) -describe('ActivityListAction rows and observation', () => { it('lists rows with kind, label, and detail-or-status', () => { - render() + render() openList() const list = screen.getByRole('list', { name: zh['list.aria'] }) const items = within(list).getAllByRole('listitem') @@ -194,21 +138,52 @@ describe('ActivityListAction rows and observation', () => { expect(items[1]?.textContent).toContain('exit code: 3') }) + it('orders live rows first by start and settled rows newest-first with tie-breaks', () => { + const settled = (id: string, label: string, startedAt: number, finishedAt?: number): SessionJob => + job({ + id: id as SessionJob['id'], + label, + status: 'completed', + startedAt, + ...finishedAt !== undefined ? { finishedAt } : {}, + }) + render() + openList() + const labels = within(screen.getByRole('list', { name: zh['list.aria'] })) + .getAllByRole('listitem') + .map(item => item.querySelector('[title]')?.getAttribute('title')) + expect(labels).toEqual([ + 'live-2', 'live-1', 'settled-d', 'settled-a', 'settled-c', 'settled-b', 'settled-e', + ]) + expect(screen.getAllByText(zh['status.completed']).length).toBeGreaterThan(0) + }) +}) + +describe('JobListAction observation', () => { it('marks killed rows, renders every output line unfolded, and copies the command', async () => { const writeText = vi.fn().mockResolvedValue(undefined) Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } }) const lines = Array.from({ length: 24 }, (_value, index) => `line ${index + 1}`).join('\n') - const view: ObservedActivity = { - activityId: 'bash-1' as ActivityId, + const view: ObservedJob = { + jobId: 'bash-1' as SessionJob['id'], text: lines, gapBefore: false, status: 'killed', streaming: false, } - render() + render() openList() expect(screen.getByText(zh['status.killed'])).toBeDefined() fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) @@ -223,45 +198,13 @@ describe('ActivityListAction rows and observation', () => { expect(writeText).toHaveBeenCalledWith('pnpm run build') }) - it('orders live rows first by start and settled rows newest-first with tie-breaks', () => { - const settled = (id: string, label: string, startedAt: number, finishedAt?: number): ActivityRow => - row({ - id: id as ActivityId, - label, - status: 'completed', - startedAt, - ...finishedAt !== undefined ? { finishedAt } : {}, - }) - render() - openList() - const labels = within(screen.getByRole('list', { name: zh['list.aria'] })) - .getAllByRole('listitem') - .map(item => item.querySelector('[title]')?.getAttribute('title')) - expect(labels).toEqual([ - 'live-2', 'live-1', 'settled-d', 'settled-a', 'settled-c', 'settled-b', 'settled-e', - ]) - expect(screen.getAllByText(zh['status.completed']).length).toBeGreaterThan(0) - }) - it('shifts an overflowing popover back inside the viewport and follows resizes', () => { vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(440) vi.spyOn(HTMLDivElement.prototype, 'getBoundingClientRect').mockReturnValue({ left: 344 } as DOMRect) const originalWidth = window.innerWidth Object.defineProperty(window, 'innerWidth', { value: 700, configurable: true, writable: true }) try { - render() + render() openList() const menu = screen.getByRole('list', { name: zh['list.aria'] }) // 700 - 12 - 440 - 344 = -96: the popover moves left to keep the margin. @@ -282,7 +225,7 @@ describe('ActivityListAction rows and observation', () => { const originalWidth = window.innerWidth Object.defineProperty(window, 'innerWidth', { value: 700, configurable: true, writable: true }) try { - render() + render() openList() const menu = screen.getByRole('list', { name: zh['list.aria'] }) // max(12 - 4, min(0, 700 - 12 - 800 - 4)) = 8: clamped at the left margin. @@ -294,39 +237,34 @@ describe('ActivityListAction rows and observation', () => { it('ignores other keys while open and closes once the roster empties', () => { const settledPair = [ - row({ id: 'bash-1' as ActivityId, status: 'completed', finishedAt: 2 }), - row({ id: 'bash-2' as ActivityId, status: 'completed', finishedAt: 3 }), + recordJob({ id: 'bash-1' as SessionJob['id'], status: 'completed', finishedAt: 2 }), + recordJob({ id: 'bash-2' as SessionJob['id'], status: 'completed', finishedAt: 3 }), ] - const { rerender } = render() - expect(screen.getByRole('button', { name: '2 个任务' })).toBeDefined() + const { rerender } = render() + expect(screen.getByRole('button', { name: '2 个后台任务' })).toBeDefined() openList() const list = screen.getByRole('list', { name: zh['list.aria'] }) fireEvent.keyDown(list, { key: 'a' }) expect(screen.getByRole('list', { name: zh['list.aria'] })).toBeDefined() // The roster emptying unmounts the control entirely; the open flag resets first. - rerender() + rerender() expect(screen.queryByRole('button')).toBeNull() }) - it('starts observing on expand, renders the live text, and stops on collapse', () => { + it('starts observing on expand with the session identity, renders the live text, and stops on collapse', () => { const stop = vi.fn() const observe = vi.fn(() => stop) - const view: ObservedActivity = { - activityId: 'bash-1' as ActivityId, + const view: ObservedJob = { + jobId: 'bash-1' as SessionJob['id'], text: 'compiling…\n', gapBefore: false, status: 'running', streaming: true, } - render() + render() openList() fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) - expect(observe).toHaveBeenCalledWith('bash-1') + expect(observe).toHaveBeenCalledWith(SESSION, 'bash-1') expect(screen.getByText('compiling…')).toBeDefined() fireEvent.click(screen.getByRole('button', { name: zh['row.collapseAria'].replace('{label}', 'pnpm run build') })) @@ -334,18 +272,15 @@ describe('ActivityListAction rows and observation', () => { }) it('surfaces retention gaps and stream failures above the panel', () => { - const view: ObservedActivity = { - activityId: 'bash-1' as ActivityId, + const view: ObservedJob = { + jobId: 'bash-1' as SessionJob['id'], text: 'tail only', gapBefore: true, status: 'running', streaming: false, error: 'connection lost', } - render() + render() openList() fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) expect(screen.getByText(zh['output.gap'])).toBeDefined() @@ -354,9 +289,7 @@ describe('ActivityListAction rows and observation', () => { it('stops observation when the popover closes via Escape', () => { const stop = vi.fn() - render( stop)} />) + render( stop)} />) openList() fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) fireEvent.keyDown(screen.getByRole('list', { name: zh['list.aria'] }), { key: 'Escape' }) @@ -368,13 +301,10 @@ describe('ActivityListAction rows and observation', () => { const stop = vi.fn() // One stable observe identity across renders, as the inject face provides. const observe = () => stop - const first = props({ rowsBySession: { [SESSION]: [row()] } }, observe) - const { rerender } = render() + const { rerender } = render() openList() fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) - rerender() + rerender() expect(stop).toHaveBeenCalledTimes(1) expect(screen.queryByRole('button', { name: zh['row.collapseAria'].replace('{label}', 'other') })).toBeNull() }) diff --git a/packages/client/ui-activity/tsconfig.json b/packages/client/ui-jobs/tsconfig.json similarity index 89% rename from packages/client/ui-activity/tsconfig.json rename to packages/client/ui-jobs/tsconfig.json index 562e2c2228..4b8aae7886 100644 --- a/packages/client/ui-activity/tsconfig.json +++ b/packages/client/ui-jobs/tsconfig.json @@ -10,7 +10,6 @@ "references": [ { "path": "../../../vendor/cosmokit" }, { "path": "../../../vendor/cordis" }, - { "path": "../../api/activity-controller/tsconfig.client.json" }, { "path": "../../api/session-controller/tsconfig.client.json" }, { "path": "../locale" }, { "path": "../ui-conversation" }, diff --git a/packages/client/ui-activity/tsdown.config.ts b/packages/client/ui-jobs/tsdown.config.ts similarity index 76% rename from packages/client/ui-activity/tsdown.config.ts rename to packages/client/ui-jobs/tsdown.config.ts index 096771fe90..c2f3a27162 100644 --- a/packages/client/ui-activity/tsdown.config.ts +++ b/packages/client/ui-jobs/tsdown.config.ts @@ -1,6 +1,6 @@ import { clientBundle } from '../tsdown.client.ts' export default clientBundle( - '@deepseek-ai/dsh-client-ui-activity', + '@deepseek-ai/dsh-client-ui-jobs', ['lib/types/index.js', 'lib/types/invariant.js'], ) diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts index 066e930d6d..23b36a8440 100644 --- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts +++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts @@ -1144,8 +1144,8 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ slotInject: '', declaredBy: 'an entry in \'conversation.session.header\' (client-ui-conversation), so it exists while that entry is mounted', occupants: [ - 'client-ui-activity ActivityListAction id \'activity-list\'', 'client-ui-agent-preset AgentPresetLabel id \'agent-preset\'', + 'client-ui-jobs JobListAction id \'job-list\'', 'client-ui-schedule ScheduleCatalogAction id \'schedule-catalog\'', 'client-ui-subagent SubagentCatalogAction id \'subagent-catalog\'', 'experimental-client-ui-agent-team TeamAction id \'agent-team\'', diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 21e7f10221..80cc02f219 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -81,68 +81,6 @@ export interface TypeApiEntry { /** Every harness `ctx.` service, sorted by key. */ export const SERVICE_API: readonly ServiceApiEntry[] = [ - { - key: 'activities', - summary: 'Abstract streaming-output registry.', - description: 'Abstract streaming-output registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.activities` (one implementation per context; loading a second throws, which is cordis\' standard duplicate-service behavior).\n\nImplementations must honor these semantics:\n\n- Observation never consumes. Any number of readers hold their own absolute byte offsets; a read changes no cursor and no producer state, so the model-facing paths (`ctx.jobs.read()`, tool results) are unaffected.\n- Records outlive producer fibers. Owner disposal ends still-open records and removes them; service disposal ends and clears everything. Neither awaits a producer — the registry owns no execution resource.\n- Retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement trims retention to the settled cap.\n- Listener delivery is owner-relative: a listener registered from an unscoped context — a host composition\'s own carrier — sees every owner, while one registered under an agent composition\'s scope sees exactly the agents composed under it. Every listener is contained.', - methods: [ - { - signature: 'abstract open(spec: ActivityOpen): ActivityHandle', - description: 'Validate the spec, attach owner cleanup, and atomically register one activity. A rejection leaves no id; after return the producer owns the handle and the visible set has changed.', - parameters: [{ name: 'spec', description: 'activity identity, owner, and correlation.' }], - returns: 'the producer face of the registered activity.', - }, - { - signature: 'abstract list(caller?: Agent): ActivitySnapshot[]', - description: 'List caller-owned and unowned activities in registration order without exposing another session\'s labels or output.', - parameters: [{ name: 'caller', description: 'reading agent; a non-agent caller sees only unowned activities.' }], - returns: 'fresh snapshots.', - }, - { - signature: 'abstract get(id: ActivityId, caller?: Agent): ActivitySnapshot', - description: 'Return a fresh snapshot. Throws for an unknown or foreign activity.', - parameters: [{ name: 'id', description: 'activity to look up.' }, { name: 'caller', description: 'reading agent checked against the owner.' }], - returns: 'a fresh snapshot.', - }, - { - signature: 'abstract read(id: ActivityId, from: number, caller?: Agent): ActivityRead', - description: 'Read retained output from an absolute byte offset without consuming it. Resume by passing a previous read\'s `next`; a foreign offset inside a retained chunk returns that whole chunk (its `at` may precede `from`). Throws for an unknown or foreign activity or a negative or non-integer offset.', - parameters: [{ name: 'id', description: 'activity to read.' }, { name: 'from', description: 'absolute byte offset to read from (0 for the retained head).' }, { name: 'caller', description: 'reading agent checked against the owner.' }], - returns: 'retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag.', - }, - { - signature: 'abstract onActivitiesChanged(listener: ActivitiesChangedListener): () => void', - description: 'Register an effect-scoped observer of visible-set changes: opening, detail updates, settlement, owner-disposal removal, and the emptying that service disposal commits — so an observer re-reads rather than accumulating deltas. Listeners are contained and never awaited.', - parameters: [{ name: 'listener', description: 'receives the owner whose visible set changed, or `undefined` when an unowned activity changed and every caller\'s set did.' }], - returns: 'disposer that unregisters the listener.', - }, - { - signature: 'abstract onOutput(listener: ActivityOutputListener): () => void', - description: 'Register an effect-scoped observer of stream advancement — one signal per committed append and one at settlement, carrying only the activity id. A consumer schedules a read from its own cursor; the registry never pushes payloads. Listeners are contained and never awaited.', - parameters: [{ name: 'listener', description: 'receives the id whose stream advanced.' }], - returns: 'disposer that unregisters the listener.', - }, - ], - }, - { - key: 'activityController', - summary: 'Host service backing the generated `ctx.remote.activity` namespace.', - description: 'Host service backing the generated `ctx.remote.activity` namespace.', - methods: [ - { - signature: '@Remote({ mode: \'stream\' }) control(signal: AbortSignal): AsyncIterable', - description: 'Stream a complete roster baseline followed by whole-bucket replacements.', - parameters: [{ name: 'signal', description: 'generation cancellation.' }], - returns: 'baseline followed by per-owner roster replacement frames.', - }, - { - signature: '@Remote({ mode: \'stream\' }) observe(request: ActivityObserveRequest, signal: AbortSignal): AsyncIterable', - description: 'Stream one activity\'s retained output from an absolute byte offset, then its terminal status once settled and drained. Non-consuming: the model-facing cursors never observe these reads.', - parameters: [{ name: 'request', description: 'target activity and optional resume offset.' }, { name: 'signal', description: 'generation cancellation.' }], - returns: 'anchor, coalesced output frames, and the terminal status.', - }, - ], - }, { key: 'agentDefaultModel', summary: 'Owns the default model selection independently of any Host or transport.', @@ -1098,7 +1036,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ { key: 'jobs', summary: 'Abstract background job registry.', - description: 'Abstract background job registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis\' standard duplicate-service behavior).\n\nImplementations must honor these semantics:\n\n- Registrations outlive producer and controller fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record. Teardown cancellation also marks the record reported, because a record its owner is being destroyed for has no reader left.\n- Owned-job access is fenced by the owner\'s session id. Ids are predictable, so authorization — not secrecy — is the boundary.\n- Settlement is first-wins: one terminal record, released waiters, and one round of contained listener notification, even against a late producer outcome. Completion is announced last, after the record is committed and every other observer of the settlement has seen it, because a reporter may open a model turn synchronously.\n- start refuses work while no attached job controller serves the spec\'s owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and completion-listener delivery — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition\'s scope serve exactly the agents composed under it.', + description: 'Abstract background job registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis\' standard duplicate-service behavior).\n\nImplementations must honor these semantics:\n\n- Registrations outlive producer and controller fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record. Teardown cancellation also marks the record reported, because a record its owner is being destroyed for has no reader left.\n- Owned-job access is fenced by the owner\'s session id. Ids are predictable, so authorization — not secrecy — is the boundary.\n- Settlement is first-wins: one terminal record, released waiters, and one round of contained listener notification, even against a late producer outcome. Completion is announced last, after the record is committed and every other observer of the settlement has seen it, because a reporter may open a model turn synchronously.\n- start refuses work while no attached job controller serves the spec\'s owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and completion-listener delivery — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition\'s scope serve exactly the agents composed under it.\n- Record observation never consumes. Any number of readRecord readers hold their own absolute byte offsets; a record read changes no cursor and no notice state, so the model-facing surfaces (the consuming read, completion notices) are unaffected.\n- Record retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement — the producer outcome, a kill, or teardown — trims retention to the settled cap and ends the stream; the record has no separate lifecycle.', methods: [ { signature: 'abstract start(spec: JobStart): JobId', @@ -1148,6 +1086,18 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ parameters: [{ name: 'listener', description: 'receives the owner whose visible set changed, or `undefined` when an unowned job changed and every caller\'s set did.' }], returns: 'disposer that unregisters the listener.', }, + { + signature: 'abstract readRecord(id: JobId, from: number, caller?: Agent): JobRecordRead', + description: 'Read retained record output from an absolute byte offset without consuming it. Resume by passing a previous read\'s `next`; a foreign offset inside a retained chunk returns that whole chunk (its `at` may precede `from`). Never marks the job reported. Throws for an unknown or foreign job, a job without a JobStart.record declaration, or a negative or non-integer offset.', + parameters: [{ name: 'id', description: 'job to read.' }, { name: 'from', description: 'absolute byte offset to read from (0 for the retained head).' }, { name: 'caller', description: 'reading agent checked against the owner.' }], + returns: 'retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag.', + }, + { + signature: 'abstract onOutput(listener: JobOutputListener): () => void', + description: 'Register an effect-scoped observer of record advancement — one signal per committed append and one at settlement, carrying only the job id. A consumer schedules a readRecord from its own cursor; the registry never pushes payloads. Delivery is owner-relative on the same terms as onJobsChanged. Listeners are contained and never awaited.', + parameters: [{ name: 'listener', description: 'receives the id whose record advanced.' }], + returns: 'disposer that unregisters the listener.', + }, { signature: 'abstract attachController(name: string): () => void', description: 'Attach an effect-scoped controller that can read and stop jobs. It serves the owners its registering context\'s scope covers, and start refuses an owner no attached controller serves.', @@ -1505,6 +1455,12 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ parameters: [{ name: 'signal', description: 'cancellation owned by the Remote stream carrier.' }], returns: 'one complete baseline followed by live replacement frames.', }, + { + signature: '@Remote({ mode: \'stream\' }) observeJob(request: SessionObserveJobRequest, signal: AbortSignal): AsyncIterable', + description: 'Stream one job\'s retained record output from an absolute byte offset, then its terminal status once settled and drained. Non-consuming: the model-facing cursor and notice state never observe these reads. The request\'s session resolves the fenced-read caller; the registry rejects a job the session does not own, a job without a record, or an unknown job.', + parameters: [{ name: 'request', description: 'target job, owning session, and optional resume offset.' }, { name: 'signal', description: 'cancellation owned by the Remote stream carrier.' }], + returns: 'anchor, coalesced output frames, and the terminal status.', + }, ], }, { @@ -3473,94 +3429,6 @@ export const EVENT_API: readonly EventApiEntry[] = [ /** Shapes of every exported type the Service and Event signatures reference (transitively), sorted by name. */ export const TYPE_API: readonly TypeApiEntry[] = [ - { - name: 'ActivitiesChangedListener', - declaration: 'export type ActivitiesChangedListener = (owner: Agent | undefined) => void;', - }, - { - name: 'ActivityAppendOptions', - declaration: 'export interface ActivityAppendOptions {\n channel?: ActivityChannel;\n gapBefore?: true;\n}', - }, - { - name: 'ActivityChannel', - declaration: 'export type ActivityChannel = \'stdout\' | \'stderr\';', - }, - { - name: 'ActivityControlFrame', - declaration: 'export type ActivityControlFrame = {\n readonly type: \'baseline\';\n readonly activities: readonly ActivityRow[];\n} | {\n readonly type: \'rows\';\n readonly sessionId?: SessionId;\n readonly activities: readonly ActivityRow[];\n};', - }, - { - name: 'ActivityCorrelation', - declaration: 'export interface ActivityCorrelation {\n callId?: ToolCallId;\n jobId?: JobId;\n}', - }, - { - name: 'ActivityHandle', - declaration: 'export interface ActivityHandle {\n readonly id: ActivityId;\n append(text: string, options?: ActivityAppendOptions): void;\n updateDetail(detail: string): void;\n end(outcome: ActivityOutcome): void;\n}', - }, - { - name: 'ActivityId', - declaration: 'export type ActivityId = Branded<\'ActivityId\'>;', - }, - { - name: 'ActivityKind', - declaration: 'export type ActivityKind = ActivityKindMap[keyof ActivityKindMap];', - }, - { - name: 'ActivityKindMap', - declaration: 'export interface ActivityKindMap {\n bash: \'bash\';\n}', - }, - { - name: 'ActivityObserveFrame', - declaration: 'export type ActivityObserveFrame = {\n readonly type: \'opened\';\n readonly activityId: ActivityId;\n readonly from: number;\n readonly earliest: number;\n readonly total: number;\n readonly status: ActivityRowStatus;\n readonly detail?: string;\n} | {\n readonly type: \'output\';\n readonly chunks: readonly ActivityWireChunk[];\n readonly next: number;\n readonly lossy?: true;\n} | {\n readonly type: \'status\';\n readonly status: ActivityRowStatus;\n readonly detail?: string;\n readonly finishedAt?: number;\n};', - }, - { - name: 'ActivityObserveRequest', - declaration: 'export interface ActivityObserveRequest {\n readonly activityId: ActivityId;\n readonly from?: number;\n}', - }, - { - name: 'ActivityOpen', - declaration: 'export interface ActivityOpen {\n kind: ActivityKind;\n label: string;\n owner?: Agent;\n correlation?: ActivityCorrelation;\n}', - }, - { - name: 'ActivityOutcome', - declaration: 'export interface ActivityOutcome {\n status: \'completed\' | \'failed\' | \'killed\';\n detail?: string;\n}', - }, - { - name: 'ActivityOutputChunk', - declaration: 'export interface ActivityOutputChunk {\n at: number;\n text: string;\n channel?: ActivityChannel;\n gapBefore?: true;\n}', - }, - { - name: 'ActivityOutputListener', - declaration: 'export type ActivityOutputListener = (id: ActivityId) => void;', - }, - { - name: 'ActivityRead', - declaration: 'export interface ActivityRead {\n chunks: readonly ActivityOutputChunk[];\n next: number;\n lossy: boolean;\n}', - }, - { - name: 'ActivityRow', - declaration: 'export interface ActivityRow {\n readonly id: ActivityId;\n readonly kind: string;\n readonly label: string;\n readonly sessionId?: SessionId;\n readonly correlation?: ActivityRowCorrelation;\n readonly status: ActivityRowStatus;\n readonly detail?: string;\n readonly startedAt: number;\n readonly finishedAt?: number;\n readonly outputTotal: number;\n}', - }, - { - name: 'ActivityRowCorrelation', - declaration: 'export interface ActivityRowCorrelation {\n readonly callId?: ToolCallId;\n readonly jobId?: JobId;\n}', - }, - { - name: 'ActivityRowStatus', - declaration: 'export type ActivityRowStatus = \'running\' | \'completed\' | \'failed\' | \'killed\';', - }, - { - name: 'ActivitySnapshot', - declaration: 'export interface ActivitySnapshot {\n id: ActivityId;\n kind: ActivityKind;\n label: string;\n ownerSession?: SessionId;\n correlation?: ActivityCorrelation;\n status: ActivityStatus;\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n outputTotal: number;\n outputEarliest: number;\n}', - }, - { - name: 'ActivityStatus', - declaration: 'export type ActivityStatus = \'running\' | \'completed\' | \'failed\' | \'killed\';', - }, - { - name: 'ActivityWireChunk', - declaration: 'export interface ActivityWireChunk {\n readonly at: number;\n readonly text: string;\n readonly channel?: string;\n readonly gapBefore?: true;\n}', - }, { name: 'AdapterRegistrationHandle', declaration: 'export interface AdapterRegistrationHandle {\n (): void;\n replace(providers: string[]): void;\n}', @@ -4349,6 +4217,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'InvokeRemoteRequest', declaration: 'export interface InvokeRemoteRequest {\n readonly namespace: string;\n readonly method: string;\n readonly args: Readonly>;\n readonly signal?: AbortSignal;\n}', }, + { + name: 'JobAppendOptions', + declaration: 'export interface JobAppendOptions {\n channel?: JobChannel;\n gapBefore?: true;\n}', + }, + { + name: 'JobChannel', + declaration: 'export type JobChannel = \'stdout\' | \'stderr\';', + }, { name: 'JobDoneListener', declaration: 'export type JobDoneListener = (snapshot: JobSnapshot, owner: Agent | undefined) => void | PromiseLike;', @@ -4373,21 +4249,33 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'JobOutcome', declaration: 'export interface JobOutcome {\n status: \'completed\' | \'killed\' | \'failed\';\n detail?: string;\n output?: string;\n}', }, + { + name: 'JobOutputListener', + declaration: 'export type JobOutputListener = (id: JobId) => void;', + }, { name: 'JobRead', declaration: 'export interface JobRead {\n text: string;\n snapshot: JobSnapshot;\n}', }, + { + name: 'JobRecordChunk', + declaration: 'export interface JobRecordChunk {\n at: number;\n text: string;\n channel?: JobChannel;\n gapBefore?: true;\n}', + }, + { + name: 'JobRecordRead', + declaration: 'export interface JobRecordRead {\n chunks: readonly JobRecordChunk[];\n next: number;\n lossy: boolean;\n}', + }, { name: 'JobsChangedListener', declaration: 'export type JobsChangedListener = (owner: Agent | undefined) => void;', }, { name: 'JobSnapshot', - declaration: 'export interface JobSnapshot {\n id: JobId;\n kind: JobKind;\n label: string;\n outputLimitBytes?: number;\n ownerSession?: SessionId;\n status: JobStatus;\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n reported: boolean;\n}', + declaration: 'export interface JobSnapshot {\n id: JobId;\n kind: JobKind;\n label: string;\n outputLimitBytes?: number;\n ownerSession?: SessionId;\n status: JobStatus;\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n reported: boolean;\n outputTotal?: number;\n outputEarliest?: number;\n}', }, { name: 'JobStart', - declaration: 'export interface JobStart {\n kind: JobKind;\n label: string;\n outputLimitBytes?: number;\n owner?: Agent;\n run(): JobHooks;\n}', + declaration: 'export interface JobStart {\n kind: JobKind;\n label: string;\n outputLimitBytes?: number;\n owner?: Agent;\n record?: true;\n run(job: RunningJob): JobHooks;\n}', }, { name: 'JobStatus', @@ -4877,6 +4765,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'RunnerFailureRule', declaration: 'export interface RunnerFailureRule {\n allowedExitCodes?: readonly number[];\n fatalSignatures: readonly string[];\n informationalLines?: readonly string[];\n}', }, + { + name: 'RunningJob', + declaration: 'export interface RunningJob {\n readonly id: JobId;\n append(text: string, options?: JobAppendOptions): void;\n updateDetail(detail: string): void;\n}', + }, { name: 'SandboxEnforcement', declaration: 'export type SandboxEnforcement = \'full\' | \'partial\';', @@ -5103,7 +4995,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SessionJob', - declaration: 'export interface SessionJob {\n readonly id: JobId;\n readonly kind: string;\n readonly label: string;\n readonly status: \'running\' | \'stopping\' | \'completed\' | \'killed\' | \'failed\';\n readonly detail?: string;\n readonly startedAt: number;\n readonly finishedAt?: number;\n}', + declaration: 'export interface SessionJob {\n readonly id: JobId;\n readonly kind: string;\n readonly label: string;\n readonly status: \'running\' | \'stopping\' | \'completed\' | \'killed\' | \'failed\';\n readonly detail?: string;\n readonly startedAt: number;\n readonly finishedAt?: number;\n readonly outputTotal?: number;\n}', + }, + { + name: 'SessionJobWireChunk', + declaration: 'export interface SessionJobWireChunk {\n readonly at: number;\n readonly text: string;\n readonly channel?: string;\n readonly gapBefore?: true;\n}', }, { name: 'SessionLineageNode', @@ -5137,6 +5033,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'SessionObservationOptions', declaration: 'export interface SessionObservationOptions {\n readonly signal?: AbortSignal;\n readonly projectionMode?: \'all\' | \'none\';\n}', }, + { + name: 'SessionObserveJobFrame', + declaration: 'export type SessionObserveJobFrame = {\n readonly type: \'opened\';\n readonly jobId: JobId;\n readonly from: number;\n readonly earliest: number;\n readonly total: number;\n readonly status: SessionJob[\'status\'];\n readonly detail?: string;\n} | {\n readonly type: \'output\';\n readonly chunks: readonly SessionJobWireChunk[];\n readonly next: number;\n readonly lossy?: true;\n} | {\n readonly type: \'status\';\n readonly status: SessionJob[\'status\'];\n readonly detail?: string;\n readonly finishedAt?: number;\n};', + }, + { + name: 'SessionObserveJobRequest', + declaration: 'export interface SessionObserveJobRequest {\n readonly sessionId?: SessionId;\n readonly jobId: JobId;\n readonly from?: number;\n}', + }, { name: 'SessionOpenWorkspacePathRequest', declaration: 'export interface SessionOpenWorkspacePathRequest {\n readonly path: string;\n}', diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index da5b3091d6..d938573ee5 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -625,110 +625,6 @@ importers: specifier: workspace:^ version: link:../../interaction/user-approval - packages/activity/activity: - devDependencies: - '@deepseek-ai/cordis': - specifier: workspace:^ - version: link:../../../vendor/cordis - '@deepseek-ai/dsh-agent': - specifier: workspace:^ - version: link:../../core/agent - '@deepseek-ai/dsh-brand': - specifier: workspace:^ - version: link:../../util/brand - '@deepseek-ai/dsh-invariants': - specifier: workspace:^ - version: link:../../runtime-diagnostics/invariants - '@deepseek-ai/dsh-jobs': - specifier: workspace:^ - version: link:../../jobs/jobs - '@deepseek-ai/dsh-llm': - specifier: workspace:^ - version: link:../../llm/llm - '@deepseek-ai/dsh-session': - specifier: workspace:^ - version: link:../../core/session - - packages/activity/activity-local: - dependencies: - '@deepseek-ai/schemastery': - specifier: link:../../../vendor/schemastery - version: link:../../../vendor/schemastery - devDependencies: - '@deepseek-ai/cordis': - specifier: workspace:^ - version: link:../../../vendor/cordis - '@deepseek-ai/cordis-plugin-include': - specifier: workspace:^ - version: link:../../../vendor/include - '@deepseek-ai/cordis-plugin-loader': - specifier: workspace:^ - version: link:../../../vendor/loader - '@deepseek-ai/dsh-activity': - specifier: workspace:^ - version: link:../activity - '@deepseek-ai/dsh-agent': - specifier: workspace:^ - version: link:../../core/agent - '@deepseek-ai/dsh-brand': - specifier: workspace:^ - version: link:../../util/brand - '@deepseek-ai/dsh-invariants': - specifier: workspace:^ - version: link:../../runtime-diagnostics/invariants - '@deepseek-ai/dsh-scope': - specifier: workspace:^ - version: link:../../core/scope - '@deepseek-ai/dsh-session': - specifier: workspace:^ - version: link:../../core/session - - packages/api/activity-controller: - dependencies: - '@deepseek-ai/schemastery': - specifier: link:../../../vendor/schemastery - version: link:../../../vendor/schemastery - zod: - specifier: ^4.4.3 - version: 4.4.3 - devDependencies: - '@deepseek-ai/cordis': - specifier: workspace:^ - version: link:../../../vendor/cordis - '@deepseek-ai/dsh-activity': - specifier: workspace:^ - version: link:../../activity/activity - '@deepseek-ai/dsh-activity-local': - specifier: workspace:^ - version: link:../../activity/activity-local - '@deepseek-ai/dsh-agent': - specifier: workspace:^ - version: link:../../core/agent - '@deepseek-ai/dsh-api-gateway': - specifier: workspace:^ - version: link:../gateway - '@deepseek-ai/dsh-client-connection': - specifier: workspace:^ - version: link:../../client/connection - '@deepseek-ai/dsh-client-store': - specifier: workspace:^ - version: link:../../client/store - '@deepseek-ai/dsh-invariants': - specifier: workspace:^ - version: link:../../runtime-diagnostics/invariants - '@deepseek-ai/dsh-jobs': - specifier: workspace:^ - version: link:../../jobs/jobs - '@deepseek-ai/dsh-llm': - specifier: workspace:^ - version: link:../../llm/llm - '@deepseek-ai/dsh-session': - specifier: workspace:^ - version: link:../../core/session - '@deepseek-ai/dsh-typert-protocol': - specifier: workspace:^ - version: link:../../typert/protocol - packages/api/gateway: dependencies: '@deepseek-ai/dsh-deque': @@ -793,9 +689,6 @@ importers: '@deepseek-ai/dsh-agent-presets': specifier: workspace:^ version: link:../../preset/agent-presets - '@deepseek-ai/dsh-api-activity-controller': - specifier: workspace:^ - version: link:../activity-controller '@deepseek-ai/dsh-api-gateway': specifier: workspace:^ version: link:../gateway @@ -1174,9 +1067,6 @@ importers: '@deepseek-ai/cordis-plugin-timer': specifier: workspace:^ version: link:../../../vendor/timer - '@deepseek-ai/dsh-activity-local': - specifier: workspace:^ - version: link:../../activity/activity-local '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../../core/agent @@ -1571,9 +1461,6 @@ importers: '@deepseek-ai/dsh-agent-presets': specifier: workspace:^ version: link:../../preset/agent-presets - '@deepseek-ai/dsh-api-activity-controller': - specifier: workspace:^ - version: link:../../api/activity-controller '@deepseek-ai/dsh-api-remotes': specifier: workspace:^ version: link:../../api/remotes @@ -1601,9 +1488,6 @@ importers: '@deepseek-ai/dsh-client-modules': specifier: workspace:^ version: link:../../client/modules - '@deepseek-ai/dsh-client-ui-activity': - specifier: workspace:^ - version: link:../../client/ui-activity '@deepseek-ai/dsh-client-ui-agent-preset': specifier: workspace:^ version: link:../../client/ui-agent-preset @@ -1643,6 +1527,9 @@ importers: '@deepseek-ai/dsh-client-ui-input-trigger': specifier: workspace:^ version: link:../../client/ui-input-trigger + '@deepseek-ai/dsh-client-ui-jobs': + specifier: workspace:^ + version: link:../../client/ui-jobs '@deepseek-ai/dsh-client-ui-layout': specifier: workspace:^ version: link:../../client/ui-layout @@ -1961,48 +1848,6 @@ importers: specifier: workspace:^ version: link:../../runtime-diagnostics/invariants - packages/client/ui-activity: - devDependencies: - '@deepseek-ai/cordis': - specifier: workspace:^ - version: link:../../../vendor/cordis - '@deepseek-ai/dsh-api-activity-controller': - specifier: workspace:^ - version: link:../../api/activity-controller - '@deepseek-ai/dsh-api-session-controller': - specifier: workspace:^ - version: link:../../api/session-controller - '@deepseek-ai/dsh-client-locale': - specifier: workspace:^ - version: link:../locale - '@deepseek-ai/dsh-client-test-runtime': - specifier: workspace:^ - version: link:../../test-support/client-runtime - '@deepseek-ai/dsh-client-ui-conversation': - specifier: workspace:^ - version: link:../ui-conversation - '@deepseek-ai/dsh-client-ui-primitives': - specifier: workspace:^ - version: link:../ui-primitives - '@deepseek-ai/dsh-client-ui-renderer': - specifier: workspace:^ - version: link:../ui-renderer - '@deepseek-ai/dsh-client-ui-session': - specifier: workspace:^ - version: link:../ui-session - '@deepseek-ai/dsh-client-ui-slots': - specifier: workspace:^ - version: link:../ui-slots - '@deepseek-ai/dsh-invariants': - specifier: workspace:^ - version: link:../../runtime-diagnostics/invariants - '@types/react': - specifier: ~18.3.1 - version: 18.3.31 - react: - specifier: ^18.2.0 - version: 18.3.1 - packages/client/ui-agent-preset: devDependencies: '@deepseek-ai/cordis': @@ -2723,6 +2568,48 @@ importers: specifier: ^18.2.0 version: 18.3.1 + packages/client/ui-jobs: + devDependencies: + '@deepseek-ai/cordis': + specifier: workspace:^ + version: link:../../../vendor/cordis + '@deepseek-ai/dsh-api-session-controller': + specifier: workspace:^ + version: link:../../api/session-controller + '@deepseek-ai/dsh-client-locale': + specifier: workspace:^ + version: link:../locale + '@deepseek-ai/dsh-client-test-runtime': + specifier: workspace:^ + version: link:../../test-support/client-runtime + '@deepseek-ai/dsh-client-ui-conversation': + specifier: workspace:^ + version: link:../ui-conversation + '@deepseek-ai/dsh-client-ui-primitives': + specifier: workspace:^ + version: link:../ui-primitives + '@deepseek-ai/dsh-client-ui-renderer': + specifier: workspace:^ + version: link:../ui-renderer + '@deepseek-ai/dsh-client-ui-session': + specifier: workspace:^ + version: link:../ui-session + '@deepseek-ai/dsh-client-ui-slots': + specifier: workspace:^ + version: link:../ui-slots + '@deepseek-ai/dsh-invariants': + specifier: workspace:^ + version: link:../../runtime-diagnostics/invariants + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session + '@types/react': + specifier: ~18.3.1 + version: 18.3.31 + react: + specifier: ^18.2.0 + version: 18.3.1 + packages/client/ui-layout: devDependencies: '@deepseek-ai/cordis': @@ -8288,9 +8175,6 @@ importers: '@deepseek-ai/cordis': specifier: workspace:^ version: link:../../../vendor/cordis - '@deepseek-ai/dsh-activity': - specifier: workspace:^ - version: link:../../activity/activity '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../../core/agent @@ -8416,9 +8300,6 @@ importers: '@deepseek-ai/cordis': specifier: workspace:^ version: link:../../../vendor/cordis - '@deepseek-ai/dsh-activity': - specifier: workspace:^ - version: link:../../activity/activity '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../../core/agent @@ -10405,12 +10286,6 @@ importers: '@deepseek-ai/cordis': specifier: workspace:^ version: link:../../../vendor/cordis - '@deepseek-ai/dsh-activity': - specifier: workspace:^ - version: link:../../activity/activity - '@deepseek-ai/dsh-activity-local': - specifier: workspace:^ - version: link:../../activity/activity-local '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../../core/agent @@ -10575,9 +10450,6 @@ importers: '@deepseek-ai/dsh-acp': specifier: workspace:^ version: link:../../packages/acp/acp - '@deepseek-ai/dsh-activity': - specifier: workspace:^ - version: link:../../packages/activity/activity '@deepseek-ai/dsh-agent': specifier: workspace:^ version: link:../../packages/core/agent diff --git a/python/sdk-runtime/package.json b/python/sdk-runtime/package.json index 2ae2320a08..f735144468 100644 --- a/python/sdk-runtime/package.json +++ b/python/sdk-runtime/package.json @@ -13,7 +13,6 @@ "@deepseek-ai/cosmokit": "workspace:^", "@deepseek-ai/dsh": "workspace:^", "@deepseek-ai/dsh-acp": "workspace:^", - "@deepseek-ai/dsh-activity": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-agent-instructions": "workspace:^", "@deepseek-ai/dsh-agent-loop": "workspace:^", diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index 02eccc59d1..d477494d34 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -109,8 +109,6 @@ export const SERVICE_PAGE: Record = { subprocess: 'subprocess.md', systemPrompt: 'system-prompt.md', jobs: 'jobs.md', - activities: 'activity.md', - activityController: 'activity.md', sessionTelemetry: 'session-telemetry.md', agentTeams: 'agent-team.md', tokenMeter: 'token-meter.md', @@ -175,7 +173,7 @@ export const SERVICE_WALK_EXEMPTIONS: Record = { slots: 'client-side interface-typed browser service — packages/client/ui-renderer/README.md owns the API', theme: 'client-side interface-typed browser service — packages/client/ui-theme/README.md owns the API', workspaces: 'client-side interface-typed browser service — packages/api/workspace-controller/README.md owns the API', - activityFeed: 'client-side interface-typed browser service — packages/api/activity-controller/README.md owns the API', + jobOutput: 'client-side interface-typed browser service — packages/api/session-controller/README.md owns the API', } /** @@ -322,6 +320,8 @@ export const LINK_MAP: Readonly> = { SessionId: 'core.md', SessionListRequest: 'session.md', SessionListValue: 'session.md', + SessionObserveJobFrame: 'session.md', + SessionObserveJobRequest: 'session.md', ModelCatalog: 'session.md', SessionOpenWorkspacePathRequest: 'session.md', SessionOpenWorkspacePathValue: 'session.md', @@ -501,22 +501,18 @@ export const LINK_MAP: Readonly> = { PromptSectionOrderName: 'system-prompt.md', SystemPrompt: 'system-prompt.md', ToolProviderResult: 'system-prompt.md', - ActivitiesChangedListener: 'activity.md', - ActivityHandle: 'activity.md', - ActivityId: 'activity.md', - ActivityOpen: 'activity.md', - ActivityOutputListener: 'activity.md', - ActivityRead: 'activity.md', - ActivitySnapshot: 'activity.md', - ActivityControlFrame: 'activity.md', - ActivityObserveFrame: 'activity.md', - ActivityObserveRequest: 'activity.md', JobDoneListener: 'jobs.md', JobId: 'jobs.md', JobRead: 'jobs.md', JobSnapshot: 'jobs.md', JobStart: 'jobs.md', JobsChangedListener: 'jobs.md', + JobAppendOptions: 'jobs.md', + JobChannel: 'jobs.md', + JobOutputListener: 'jobs.md', + JobRecordChunk: 'jobs.md', + JobRecordRead: 'jobs.md', + RunningJob: 'jobs.md', CreateTeamTaskRequest: 'agent-team.md', SendTeamMessageRequest: 'agent-team.md', SendTeamMessageResult: 'agent-team.md', diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index 008991a00c..3638b0c002 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -198,13 +198,6 @@ const SERVICE_ROLES: ServiceRole[] = [ mode: 'core', note: 'Carries the picking seam onto the wire: capability gating, cancellation, and the seam-coded failures a browser directory flow discriminates on.', }, - { - key: 'activityController', - pkg: 'api-activity-controller', - title: 'Host Activity Remote controller', - mode: 'core', - note: 'Owns the live-activity roster stream and per-activity non-consuming output observation through the generated Remote namespace.', - }, { key: 'invariants', pkg: 'invariants', @@ -583,17 +576,8 @@ const SERVICE_ROLES: ServiceRole[] = [ title: 'Background job registry', mode: 'seam', implementations: ['jobs-local'], - consumers: ['tool-bash', 'tool-terminal', 'tool-subagent', 'tool-jobs'], - note: 'Producers (background bash, PTY sends, and subagent delegations) register running work; tool-jobs is the model-facing controller that reads, lists, and kills it; jobs-local is the process-local registry.', - }, - { - key: 'activities', - pkg: 'activity', - title: 'Live activity observation registry', - mode: 'seam', - implementations: ['activity-local'], - consumers: ['tool-bash', 'tool-pwsh', 'tool-workflow', 'activity-controller'], - note: 'Producers mirror live output and status into non-consuming offset-addressed streams; activity-controller serves them to browsers, and the model-facing paths (jobs cursors, tool results) stay untouched.', + consumers: ['tool-bash', 'tool-pwsh', 'tool-terminal', 'tool-subagent', 'tool-jobs'], + note: 'Producers (background bash/pwsh, PTY sends, and subagent delegations) register running work; record-declaring jobs additionally stream raw output for non-consuming observers; tool-jobs is the model-facing controller that reads, lists, and kills it; jobs-local is the process-local registry.', }, { key: 'web', diff --git a/scripts/package-dependency-policy.ts b/scripts/package-dependency-policy.ts index 15b481383c..63054fd183 100644 --- a/scripts/package-dependency-policy.ts +++ b/scripts/package-dependency-policy.ts @@ -5,7 +5,6 @@ const CLIENT_FACE_INCLUDE: readonly string[] = [] /** Packages exempted from automatic Client/Host treatment despite declaring `dsh.client`. */ const CLIENT_FACE_EXCLUDE: readonly string[] = [ - '@deepseek-ai/dsh-api-activity-controller', '@deepseek-ai/dsh-api-session-controller', '@deepseek-ai/dsh-api-workspace-controller', ] diff --git a/scripts/verify-package-dependencies.spec.ts b/scripts/verify-package-dependencies.spec.ts index 26263fe018..4294cff84b 100644 --- a/scripts/verify-package-dependencies.spec.ts +++ b/scripts/verify-package-dependencies.spec.ts @@ -123,7 +123,6 @@ function hostRuntimeFixture(): { describe('package dependency scope', () => { it('keeps the measured Host relay roster explicit', () => { expect(PACKAGE_DEPENDENCY_POLICY.clientFaceExclude).toEqual([ - '@deepseek-ai/dsh-api-activity-controller', '@deepseek-ai/dsh-api-session-controller', '@deepseek-ai/dsh-api-workspace-controller', ]) diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts index ec942708ea..a563dc46bd 100644 --- a/scripts/verify-package-readme-model-experience.ts +++ b/scripts/verify-package-readme-model-experience.ts @@ -46,10 +46,7 @@ const NO_MODEL_EXPERIENCE_SECTION: Readonly> = { const SENTENCE_MODEL_EXPERIENCE: Readonly> = { 'packages/attachment/attachment': { kind: 'indirect', reason: 'The storage seam delegates model request rendering to provider adapters.' }, 'packages/attachment/attachment-local': { kind: 'indirect', reason: 'The local backend delegates model request rendering to provider adapters.' }, - 'packages/activity/activity': { kind: 'none', reason: 'Pure observation seam for humans; activity output becomes model-visible only through producers\' existing tool results and jobs reads.' }, - 'packages/activity/activity-local': { kind: 'none', reason: 'In-memory observation provider; producers own every model-visible surface.' }, - 'packages/api/activity-controller': { kind: 'none', reason: 'Browser/Host observation transport; registers no prompt, tool, or session event.' }, - 'packages/client/ui-activity': { kind: 'none', reason: 'Browser-side presentation of host-observed output; touches no prompt, message, schema, stream, or tool result.' }, + 'packages/client/ui-jobs': { kind: 'none', reason: 'Browser-side presentation of host-observed output; touches no prompt, message, schema, stream, or tool result.' }, 'packages/shell/shell': { kind: 'indirect', reason: 'The service interface delegates all model rendering to dsh-tool-bash.' }, 'packages/shell/shell-env': { kind: 'indirect', reason: 'The env service exposes managed DSH_* facts through the shell tools (dsh-tool-bash/dsh-tool-pwsh); it registers no prompt or schema of its own.' }, 'packages/shell/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' }, diff --git a/tsconfig.base.json b/tsconfig.base.json index c09254eec2..d8ba3b6830 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -47,13 +47,6 @@ "@deepseek-ai/dsh-api-gateway/client": ["./packages/api/gateway/src/client/index.ts"], "@deepseek-ai/dsh-api-gateway/invariant": ["./packages/api/gateway/src/invariant.ts"], "@deepseek-ai/dsh-api-gateway/types": ["./packages/api/gateway/src/types.ts"], - "@deepseek-ai/dsh-api-activity-controller": ["./packages/api/activity-controller/src/index.ts"], - "@deepseek-ai/dsh-api-activity-controller/client": ["./packages/api/activity-controller/src/client/index.ts"], - "@deepseek-ai/dsh-api-activity-controller/invariant": ["./packages/api/activity-controller/src/invariant.ts"], - "@deepseek-ai/dsh-api-activity-controller/types": ["./packages/api/activity-controller/src/types.ts"], - "@deepseek-ai/dsh-client-ui-activity": ["./packages/client/ui-activity/src"], - "@deepseek-ai/dsh-client-ui-activity/client": ["./packages/client/ui-activity/src/client/index.ts"], - "@deepseek-ai/dsh-client-ui-activity/invariant": ["./packages/client/ui-activity/src/invariant.ts"], "@deepseek-ai/dsh-api-session-controller": ["./packages/api/session-controller/src/index.ts"], "@deepseek-ai/dsh-api-session-controller/client": ["./packages/api/session-controller/src/client/index.ts"], "@deepseek-ai/dsh-api-session-controller/invariant": ["./packages/api/session-controller/src/invariant.ts"], @@ -108,7 +101,6 @@ "@deepseek-ai/dsh-commands/brand": ["./packages/interaction/commands/src/brand.ts"], "@deepseek-ai/dsh-commands/types": ["./packages/interaction/commands/src/types.ts"], "@deepseek-ai/dsh-jobs/brand": ["./packages/jobs/jobs/src/brand.ts"], - "@deepseek-ai/dsh-activity/brand": ["./packages/activity/activity/src/brand.ts"], "@deepseek-ai/dsh-credentials/types": ["./packages/credentials/credentials/src/types.ts"], "@deepseek-ai/dsh-authorization/types": ["./packages/credentials/authorization/src/types.ts"], "@deepseek-ai/dsh-settings/types": ["./packages/settings/settings/src/types.ts"], @@ -212,6 +204,8 @@ "@deepseek-ai/dsh-experimental-client-ui-agent-team": ["./packages/experimental/client-ui-agent-team/src"], "@deepseek-ai/dsh-client-ui-settings-plugins": ["./packages/client/ui-settings-plugins/src"], "@deepseek-ai/dsh-client-ui-jobs": ["./packages/client/ui-jobs/src"], + "@deepseek-ai/dsh-client-ui-jobs/client": ["./packages/client/ui-jobs/src/client/index.ts"], + "@deepseek-ai/dsh-client-ui-jobs/invariant": ["./packages/client/ui-jobs/src/invariant.ts"], "@deepseek-ai/dsh-client-ui-schedule": ["./packages/client/ui-schedule/src"], "@deepseek-ai/dsh-client-ui-schedule/client": ["./packages/client/ui-schedule/src/client/index.ts"], "@deepseek-ai/dsh-client-ui-schedule/invariant": ["./packages/client/ui-schedule/src/invariant.ts"], @@ -255,10 +249,6 @@ "@deepseek-ai/dsh-acp/invariant": ["./packages/acp/acp/src/invariant.ts"], "@deepseek-ai/dsh-acp-app": ["./packages/bundle/acp-app/src"], "@deepseek-ai/dsh-acp-app/invariant": ["./packages/bundle/acp-app/src/invariant.ts"], - "@deepseek-ai/dsh-activity": ["./packages/activity/activity/src"], - "@deepseek-ai/dsh-activity/invariant": ["./packages/activity/activity/src/invariant.ts"], - "@deepseek-ai/dsh-activity-local": ["./packages/activity/activity-local/src"], - "@deepseek-ai/dsh-activity-local/invariant": ["./packages/activity/activity-local/src/invariant.ts"], "@deepseek-ai/dsh-agent": ["./packages/core/agent/src"], "@deepseek-ai/dsh-agent-default-model": ["./packages/core/agent-default-model/src"], "@deepseek-ai/dsh-agent-default-model/invariant": ["./packages/core/agent-default-model/src/invariant.ts"], diff --git a/tsconfig.client.json b/tsconfig.client.json index 2426473861..bb6735bbc7 100644 --- a/tsconfig.client.json +++ b/tsconfig.client.json @@ -57,7 +57,6 @@ { "path": "./packages/typert/registry" }, { "path": "./packages/api/gateway/tsconfig.client.json" }, { "path": "./packages/api/session-controller/tsconfig.client.json" }, - { "path": "./packages/api/activity-controller/tsconfig.client.json" }, { "path": "./packages/api/workspace-controller/tsconfig.client.json" }, { "path": "./packages/api/remotes/tsconfig.client.json" }, { "path": "./packages/extensions/cordis-client-runner" }, @@ -78,7 +77,7 @@ { "path": "./packages/client/ui-skill" }, { "path": "./packages/client/ui-reference" }, { "path": "./packages/client/ui-subagent" }, - { "path": "./packages/client/ui-activity" }, + { "path": "./packages/client/ui-jobs" }, { "path": "./packages/experimental/client-ui-agent-team" }, { "path": "./packages/client/ui-schedule" }, { "path": "./packages/client/ui-directory-picker-browse" }, diff --git a/tsconfig.host.json b/tsconfig.host.json index b9fac3cdff..4bbbda019b 100644 --- a/tsconfig.host.json +++ b/tsconfig.host.json @@ -81,7 +81,7 @@ "apps/web/tests/subagent-interrupt-ui.e2e.ts", "apps/web/tests/sidebar-subagent-activity.e2e.ts", "apps/web/tests/background-job-list.e2e.ts", - "apps/web/tests/live-activity-stream.e2e.ts", + "apps/web/tests/live-job-stream.e2e.ts", "apps/web/tests/bash-abort-row.e2e.ts", "apps/web/tests/skill-tool-row.e2e.ts", "apps/web/tests/turn-tail-actions.e2e.ts", @@ -152,7 +152,6 @@ { "path": "./packages/api/gateway/tsconfig.host.json" }, { "path": "./packages/api/remotes/tsconfig.host.json" }, { "path": "./packages/api/session-controller/tsconfig.host.json" }, - { "path": "./packages/api/activity-controller/tsconfig.host.json" }, { "path": "./packages/api/settings-controller" }, { "path": "./packages/api/workspace-controller/tsconfig.host.json" }, { "path": "./packages/typert/loader" }, @@ -298,8 +297,6 @@ { "path": "./packages/jobs/jobs" }, { "path": "./packages/jobs/jobs-local" }, { "path": "./packages/jobs/tool-jobs" }, - { "path": "./packages/activity/activity" }, - { "path": "./packages/activity/activity-local" }, { "path": "./packages/experimental/agent-team" }, { "path": "./packages/experimental/agent-team-profile" }, { "path": "./packages/experimental/tool-agent-team" }, From 3c79e71cdc467ab651efd60fad7a94db11da6cfc Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 1 Sep 2026 18:34:36 +0800 Subject: [PATCH 017/100] docs(i18n): mirror the record refactor across the bilingual pairs Chinese sides of the jobs, jobs-local, tool-bash, tool-pwsh, tool-workflow, session-controller, and ui-jobs pages follow their English edits; the generated en-only catalogs (config catalog, capability seams, event producer/consumer) get the same section surgery by hand; the activity subsystem page triplet is fully removed and the jobs page carries the record contract in both languages with fresh type-equiv manifest entries. The three prior activity notes point at the superseding note. Web e2e label assertions follow the ui-jobs copy, and the three test call sites that invoked run() bare pass the producer face. --- ...9-01-jobs-absorb-activity-record.i18n.yaml | 6 + .../2026-09-01-jobs-absorb-activity-record.md | 2 +- ...26-09-01-jobs-absorb-activity-record.zh.md | 2 +- ...08-08-web-background-job-display.i18n.yaml | 4 +- ...-08-24-activity-observation-seam.i18n.yaml | 4 +- .../2026-08-25-unified-task-list.i18n.yaml | 4 +- apps/web/tests/background-job-list.e2e.ts | 6 +- docs/architecture.i18n.yaml | 4 +- docs/capability-seams.i18n.yaml | 4 +- docs/capability-seams.zh.md | 20 +-- docs/config-catalog.i18n.yaml | 4 +- docs/config-catalog.zh.md | 61 +++------- docs/event-producer-consumer.i18n.yaml | 4 +- docs/event-producer-consumer.zh.md | 14 +-- docs/subsystems/README.i18n.yaml | 4 +- docs/subsystems/activity.i18n.yaml | 6 - docs/subsystems/jobs.i18n.yaml | 4 +- docs/subsystems/jobs.zh.md | 114 ++++++++++++++++-- .../api/session-controller/README.i18n.yaml | 4 +- packages/api/session-controller/README.zh.md | 4 + packages/client/README.i18n.yaml | 4 +- packages/jobs/jobs-local/README.i18n.yaml | 4 +- packages/jobs/jobs-local/README.zh.md | 11 +- packages/jobs/jobs-local/tests/jobs.spec.ts | 6 +- packages/jobs/jobs/README.i18n.yaml | 4 +- packages/jobs/jobs/README.zh.md | 13 +- packages/shell/tool-bash/README.i18n.yaml | 4 +- packages/shell/tool-bash/README.zh.md | 2 +- packages/shell/tool-pwsh/README.i18n.yaml | 4 +- packages/shell/tool-pwsh/README.zh.md | 2 +- .../workflow/tool-workflow/README.i18n.yaml | 4 +- packages/workflow/tool-workflow/README.zh.md | 3 +- scripts/type-equiv.manifest.json | 15 +++ 33 files changed, 214 insertions(+), 137 deletions(-) create mode 100644 .agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml delete mode 100644 docs/subsystems/activity.i18n.yaml diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml new file mode 100644 index 0000000000..87e45ad40a --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.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 .agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md +2026-09-01-jobs-absorb-activity-record.md: cc2cc8606a50e2d7c06e183a09df709b75b9bd35 +2026-09-01-jobs-absorb-activity-record.zh.md: 8b6739192b56899899773ba1e7af2bf1bd846b0b diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md index 501cdcf801..cc2cc8606a 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md @@ -22,7 +22,7 @@ The one activity without a job was the foreground workflow mirror. Everything el - **`ui-activity` returns to its upstream name `ui-jobs`** and renders one roster: `jobsBySession` rows, expandable exactly when `outputTotal` is present. The two-roster join is deleted. - **Foreground workflow loses its live panel deliberately.** `tool-workflow`'s activity mirror is removed; a foreground run surfaces through its recorded run/member lifecycle events only, and the per-line `workflow/phase` / `workflow/log` narration has no observer until workflow gains `run_in_background` and registers a record job. Jobs stay a pure background registry — no `foreground` mode bit, no model-invisible rows, no run-less rows. -## Rejected +## Alternatives considered - **A `foreground: true` job mode** to keep the foreground workflow panel: it needs two coupled enforcement points (reported-at-birth and a `job_list` filter) whose divergence double-delivers or leaks rows to the model, for one edge feature replaceable by `run_in_background`. - **Serving model reads from the record** (deleting `readOutput`): model reads are producer-formatted (truncation and spill notices, sandbox markers) and consuming; the record is raw, channel-labeled, and non-consuming. Unifying them moves producer-specific formatting into the registry or noise into the observer stream. diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md index 40e795146c..8b6739192b 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md @@ -22,7 +22,7 @@ Status: implemented - **`ui-activity` 改回上游名字 `ui-jobs`**,渲染单一名册:`jobsBySession` 行,恰在 `outputTotal` 存在时可展开。双名册 join 被删除。 - **前台 workflow 有意失去实时面板。** `tool-workflow` 的 activity 镜像被移除;前台 run 只通过已记录的 run/member 生命周期事件呈现,逐行的 `workflow/phase` / `workflow/log` 叙述在 workflow 获得 `run_in_background` 并登记 record job 之前没有观察者。jobs 保持纯后台注册表——没有 `foreground` 模式位、没有模型不可见行、没有无 run 行。 -## 已否决 +## 曾考虑的替代方案 - **`foreground: true` job 模式**以保留前台 workflow 面板:它需要两个耦合的执行点(出生即 reported 与 `job_list` 过滤),两者一旦分叉就会双投递或向模型泄漏行,而它换来的只是一个可被 `run_in_background` 替代的边缘特性。 - **用 record 服务模型读取**(删除 `readOutput`):模型读取是生产者格式化的(截断与 spill 提示、sandbox 标记)且消耗型;record 是原始、带 channel 标签、非消耗的。统一二者要么把生产者特有格式化搬进注册表,要么把噪声混入观察者流。 diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml index 9b64d73885..444bbac0ad 100644 --- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.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 .agents/notes/implemented/feature/2026-08-08-web-background-job-display.md -2026-08-08-web-background-job-display.md: 23074b5d38cdab8c45925c75a7d0b851f7be2ece -2026-08-08-web-background-job-display.zh.md: 06645267ee8afadf284b7654b0cd4a672fe7e4b4 +2026-08-08-web-background-job-display.md: 3dd003c0e972ec7a5857e84980520eee93b53955 +2026-08-08-web-background-job-display.zh.md: 5d1ee4bada9c1966e4329d35f5a4db64300ca3b4 diff --git a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.i18n.yaml index 96434aa147..651ef99e3c 100644 --- a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-24-activity-observation-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 .agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md -2026-08-24-activity-observation-seam.md: 88109cb3404132885bde359af0907a29ea1bee2c -2026-08-24-activity-observation-seam.zh.md: b8aa938edfd0019794211975c616aa50381ffe77 +2026-08-24-activity-observation-seam.md: 29ee08b1bb7f72a63d2f84278af62587060de3fe +2026-08-24-activity-observation-seam.zh.md: 97ac4f195c83cdd4f16d2f0a108abd2b3338d95d diff --git a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.i18n.yaml b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.i18n.yaml index cba3c8b11c..eab6f6fa1b 100644 --- a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.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 .agents/notes/implemented/feature/2026-08-25-unified-task-list.md -2026-08-25-unified-task-list.md: e67ca84d96424e723f6a5660cbb2b02733e42892 -2026-08-25-unified-task-list.zh.md: 2a71b04ec33b635478bd4897e8777abb3081a8df +2026-08-25-unified-task-list.md: daf6582bf2c9e4b4a5ce26d6ae632fb78b30dbcb +2026-08-25-unified-task-list.zh.md: 624747396e175a216047239333575322ec4b1808 diff --git a/apps/web/tests/background-job-list.e2e.ts b/apps/web/tests/background-job-list.e2e.ts index 57fdd1358d..1030369886 100644 --- a/apps/web/tests/background-job-list.e2e.ts +++ b/apps/web/tests/background-job-list.e2e.ts @@ -80,7 +80,7 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => { it('shows a running background job in the session header without a refresh', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-background-job-running')) // Polling for zero would pass at t=0 before delivery and prove nothing. - const trigger = page.getByRole('button', { name: '1 task running' }) + const trigger = page.getByRole('button', { name: '1 background job running' }) expect(await trigger.count()).toBe(0) const started = await scaffold.ctx.tools.execute({ @@ -97,7 +97,7 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => { await trigger.waitFor({ timeout: 15_000 }) await trigger.click() - const row = page.getByRole('list', { name: 'Tasks' }).getByRole('listitem').first() + const row = page.getByRole('list', { name: 'Background jobs' }).getByRole('listitem').first() await row.waitFor({ timeout: 10_000 }) await expect.poll(() => row.textContent()).toContain(COMMAND) @@ -111,7 +111,7 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-background-job-settled')) expect(scaffold.ctx.jobs.kill(jobId, agent, 'web e2e cancellation')).toBe('requested') - const idle = page.getByRole('button', { name: '1 task' }) + const idle = page.getByRole('button', { name: '1 background job' }) await idle.waitFor({ timeout: 20_000 }) const snapshot = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd) diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index 25942087ae..1f40c3002f 100644 --- a/docs/architecture.i18n.yaml +++ b/docs/architecture.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 docs/architecture.md -architecture.md: 8a2f9b772c6c50aed0389421fd26a713668b1907 -architecture.zh.md: cc291fb0184bcc62a283741ff453e62d7400eb0a +architecture.md: f36c956d9a14f6b4490d2cd5ce03d807da4a94ad +architecture.zh.md: 67e2ae905cdf0ddb210f320fd7b8cb34395d99d4 diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml index 9327ad1685..5b19c660e0 100644 --- a/docs/capability-seams.i18n.yaml +++ b/docs/capability-seams.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 docs/capability-seams.md -capability-seams.md: 6c0867eeb8d47fefcbbf270e79123935cdae2aa3 -capability-seams.zh.md: aa741f96303e0dbf5f883c2fb4a2af927e165f63 +capability-seams.md: db2b8db95647204b4a49a63c6a7f1d97b942e635 +capability-seams.zh.md: f145241760737654c39662c76ddd027cf22bc409 diff --git a/docs/capability-seams.zh.md b/docs/capability-seams.zh.md index aa741f9630..f145241760 100644 --- a/docs/capability-seams.zh.md +++ b/docs/capability-seams.zh.md @@ -47,8 +47,6 @@ flowchart LR pkg_api_workspace_controller["api-workspace-controller"] svc_workspaceController["ctx.workspaceController
        Host Workspace Remote controller"] svc_directoryPickerController["ctx.directoryPickerController
        Host directory-picking Remote controller"] - pkg_api_activity_controller["api-activity-controller"] - svc_activityController["ctx.activityController
        Host Activity Remote controller"] svc_invariants["ctx.invariants
        Package-owned invariant registry"] pkg_scope["scope"] pkg_typert_registry["typert-registry"] @@ -188,11 +186,6 @@ flowchart LR svc_jobs["ctx.jobs
        Background job registry"] pkg_jobs_local["jobs-local"] pkg_tool_jobs["tool-jobs"] - pkg_activity["activity"] - svc_activities["ctx.activities
        Live activity observation registry"] - pkg_activity_local["activity-local"] - pkg_tool_workflow["tool-workflow"] - pkg_activity_controller["activity-controller"] pkg_web["web"] svc_web["ctx.web
        Web access provider registry"] pkg_web_search_exa["web-search-exa"] @@ -216,6 +209,7 @@ flowchart LR pkg_workflow["workflow"] svc_workflowEngine["ctx.workflowEngine
        Workflow script engine"] pkg_workflow_worker_thread["workflow-worker-thread"] + pkg_tool_workflow["tool-workflow"] pkg_webhook["webhook"] svc_webhookRuntime["ctx.webhookRuntime
        Webhook rule runtime"] pkg_webhook_github["webhook-github"] @@ -225,13 +219,10 @@ flowchart LR pkg_cordis_host_runner["cordis-host-runner"] svc_dynamicCordisRunner["ctx.dynamicCordisRunner
        Dynamic Cordis package host runner"] svc_cordisInspect["ctx.cordisInspect
        Dynamic Cordis inspect registry"] - pkg_activity --> svc_activities - pkg_activity_local --> svc_activities pkg_agent --> svc_agents pkg_agent_default_model --> svc_agentDefaultModel pkg_agent_loop --> svc_agentLoop pkg_agent_presets --> svc_agentPresets - pkg_api_activity_controller --> svc_activityController pkg_api_gateway --> svc_typertGateway pkg_api_session_controller --> svc_sessionController pkg_api_session_controller --> svc_sessionFileReferences @@ -344,10 +335,6 @@ flowchart LR pkg_workflow --> svc_workflowEngine pkg_workflow_worker_thread --> svc_workflowEngine pkg_workspace --> svc_workspaceRegistry - svc_activities --> pkg_activity_controller - svc_activities --> pkg_tool_bash - svc_activities --> pkg_tool_pwsh - svc_activities --> pkg_tool_workflow svc_agentDefaultModel --> pkg_api_session_controller svc_agentDefaultModel --> pkg_headless svc_agentLoop --> pkg_agent_spine_demo @@ -384,6 +371,7 @@ flowchart LR svc_invariants --> pkg_session svc_jobs --> pkg_tool_bash svc_jobs --> pkg_tool_jobs + svc_jobs --> pkg_tool_pwsh svc_jobs --> pkg_tool_subagent svc_jobs --> pkg_tool_terminal svc_llm --> pkg_agent_loop @@ -491,7 +479,6 @@ flowchart LR | `ctx.settingsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | 把用户设置 seam 投影到生成的 Remote namespace:读取一律脱敏,所有拒绝在这里分类,而不在 seam Definition 上。 | | `ctx.workspaceController` | `core` | [`api-workspace-controller`](../packages/api/workspace-controller) | - | - | - | 通过生成的 Remote namespace 负责 Workspace 命令和可在重连后收敛的 Workspace 状态投递。 | | `ctx.directoryPickerController` | `core` | [`api-workspace-controller`](../packages/api/workspace-controller) | - | - | - | 把选目录 seam 送上线:能力门禁、取消传播,以及浏览器目录流程用于分支判断的 seam 错误码。 | -| `ctx.activityController` | `core` | [`api-activity-controller`](../packages/api/activity-controller) | - | - | - | 通过生成的 Remote namespace 负责实时活动 roster 流与逐活动的非消费输出观察。 | | `ctx.invariants` | `core` | [`invariants`](../packages/runtime-diagnostics/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | 配套子路径注册所属包本地的检查;该服务负责选择、唯一性、子 fiber,以及标明所属包的失败。 | | `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader), [`api-gateway`](../packages/api/gateway) | - | 插件直接或通过 dsh-typert-loader 注册实时 zod 贡献;API 网关消费调用描述符和提供方,其他运行时消费方则在各自边界查询 schema 与反射元数据。 | | `ctx.typertGateway` | `core` | [`api-gateway`](../packages/api/gateway) | - | - | - | 将生成的 Remote 描述符与实时 Cordis 服务关联,解析已注册的身份,并通过共享的 Connection RPC 载体提供一元调用。 | @@ -537,8 +524,7 @@ flowchart LR | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process), [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | 提供方实现传输;该服务还负责可选的、基于 Activation 的延续编排,tool-subagent 选择一次性或可延续委派,tool-subagent-control 传递后续消息,而 tool-ralph 要求一条全新的结构化输出路由。 | | `ctx.agentTeams` | `core` | [`experimental-agent-team`](../packages/experimental/agent-team) | - | [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team), [`experimental-client-ui-agent-team`](../packages/experimental/client-ui-agent-team) | - | 负责隐式 Root roster、持久 peer mailbox、共享任务 DAG、continuable child 生命周期与生成式 Team Remote method;tool-agent-team 提供模型控制工具,client-ui-agent-team 挂载浏览器 contribution。 | | `ctx.inspector` | `core` | `inspector` | - | - | - | 负责 Worker 托管的 CDP target,以及独立于传输的 Host 和 Client observation 与 Cordis tree query API。 | -| `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs) | - | 生产方(后台 bash、PTY 发送和 subagent 委派)登记正在运行的工作;tool-jobs 是面向模型的控制器,用于读取、列出和终止这些工作;jobs-local 是进程本地注册表。 | -| `ctx.activities` | `seam` | [`activity`](../packages/activity/activity) | [`activity-local`](../packages/activity/activity-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`tool-workflow`](../packages/workflow/tool-workflow), `activity-controller` | - | 生产者把实时输出与状态镜像进非消费的偏移寻址流;activity-controller 把它们提供给浏览器,模型可见路径(jobs 游标、工具结果)保持不动。 | +| `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs) | - | 生产方(后台 bash/pwsh、PTY 发送和 subagent 委派)登记正在运行的工作;声明 record 的 job 还为非消费观察者流式提供原始输出;tool-jobs 是面向模型的控制器,用于读取、列出和终止这些工作;jobs-local 是进程本地注册表。 | | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-http`](../packages/web/web-fetch-http) | [`tool-web`](../packages/web/tool-web) | - | 搜索和抓取提供方注册到同一个 ctx.web seam;tool-web 负责稳定的面向模型名称。 | | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | 后端保存过大的工具文本,并返回面向模型的定位信息和取回提示;spill-policy 是 tools/post-execute 消费方,负责决定何时 spill。 | | `ctx.directoryPicker` | `seam` | [`host-directory-picker`](../packages/host/directory-picker) | [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | [`api-workspace-controller`](../packages/api/workspace-controller) | - | 带判别标记的交互能力:原生后端在 Host 显示设备上打开一个操作系统选择器,浏览后端为应用内浏览器提供列表与创建原语;双端后端通过其浏览器侧填充 ui-workspace 目录流程的 slot(不通过协议发布)。 | diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index 88653dc4ad..c71be1f3c9 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.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 docs/config-catalog.md -config-catalog.md: 424eff1c5e6e4ab96687e0688280cfc20cd31729 -config-catalog.zh.md: 9591737dbf8593edb594ccc3373ab8354a2201aa +config-catalog.md: 64b72e0ff774bd7ecd6142a1ee1f0663e28194b7 +config-catalog.zh.md: ab2c0aac8f341e5855299236787421f4b60d357a diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index 9591737dbf..ab2c0aac8f 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -35,22 +35,6 @@ export interface AcpConfig { 来源:[`packages/acp/acp/src/index.ts:75`](../packages/acp/acp/src/index.ts) - - -## `@deepseek-ai/dsh-activity-local` - -```ts config-catalog -/** Configuration for the process-local observation registry. */ -export interface Config { - /** Live output retention per activity in UTF-8 bytes; omission defaults to 262144. */ - retainBytes?: number - /** Output retention kept after an activity settles, in UTF-8 bytes; omission defaults to 16384. */ - settledRetainBytes?: number -} -``` - -来源:[`packages/activity/activity-local/src/index.ts:31`](../packages/activity/activity-local/src/index.ts) - ## `@deepseek-ai/dsh-agent-default-model` @@ -294,24 +278,6 @@ export interface Config { 来源:[`packages/core/agent-tool-presentation/src/index.ts:38`](../packages/core/agent-tool-presentation/src/index.ts) - - -## `@deepseek-ai/dsh-api-activity-controller` - -Requires: `typert` - -```ts config-catalog -/** Configuration for the Activity Remote owner. */ -export interface Config { - /** Coalescing window after new output before an observation read, in milliseconds (default 100). */ - flushMs?: number - /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */ - maxFrameBytes?: number -} -``` - -来源:[`packages/api/activity-controller/src/index.ts:26`](../packages/api/activity-controller/src/index.ts) - ## `@deepseek-ai/dsh-api-gateway` @@ -341,10 +307,14 @@ export interface Config { readonly coldBlankProbeMaxBytes?: number /** Override platform desktop-opener detection. */ readonly nativeOpen?: boolean + /** Coalescing window after new record output before a job-observation read, in milliseconds (default 100). */ + readonly observeFlushMs?: number + /** Soft byte budget per job-observation output frame (default 65536); one larger chunk ships whole. */ + readonly observeMaxFrameBytes?: number } ``` -来源:[`packages/api/session-controller/src/index.ts:67`](../packages/api/session-controller/src/index.ts) +来源:[`packages/api/session-controller/src/index.ts:77`](../packages/api/session-controller/src/index.ts) @@ -990,10 +960,14 @@ export interface Config { * omission defaults to 10. */ maxConcurrentJobsPerOwner?: number + /** Live record retention per job in UTF-8 bytes; omission defaults to 262144. */ + retainBytes?: number + /** Record retention kept after a job settles, in UTF-8 bytes; omission defaults to 16384. */ + settledRetainBytes?: number } ``` -来源:[`packages/jobs/jobs-local/src/index.ts:31`](../packages/jobs/jobs-local/src/index.ts) +来源:[`packages/jobs/jobs-local/src/index.ts:38`](../packages/jobs/jobs-local/src/index.ts) @@ -2714,12 +2688,12 @@ export type TokenMeterConfig = Record export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean - /** Poll cadence for mirroring background output into `ctx.activities`, in milliseconds (default 150). */ - activityPollMs?: number + /** Poll cadence for copying background output into the job record, in milliseconds (default 150). */ + recordPollMs?: number } ``` -来源:[`packages/shell/tool-bash/src/index.ts:33`](../packages/shell/tool-bash/src/index.ts) +来源:[`packages/shell/tool-bash/src/index.ts:34`](../packages/shell/tool-bash/src/index.ts) @@ -2881,12 +2855,12 @@ export interface Config { export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean - /** Poll cadence for mirroring background output into `ctx.activities`, in milliseconds (default 150). */ - activityPollMs?: number + /** Poll cadence for copying background output into the job record, in milliseconds (default 150). */ + recordPollMs?: number } ``` -来源:[`packages/shell/tool-pwsh/src/index.ts:51`](../packages/shell/tool-pwsh/src/index.ts) +来源:[`packages/shell/tool-pwsh/src/index.ts:53`](../packages/shell/tool-pwsh/src/index.ts) @@ -3456,7 +3430,6 @@ export interface Config { - `@deepseek-ai/dsh-authorization` — 需要 `credentials`([`packages/credentials/authorization/src/index.ts`](../packages/credentials/authorization/src/index.ts)) - `@deepseek-ai/dsh-client-locale`([`packages/client/locale/src/index.ts`](../packages/client/locale/src/index.ts)) - `@deepseek-ai/dsh-client-modules` — 需要 `webServer` · `loader`([`packages/client/modules/src/index.ts`](../packages/client/modules/src/index.ts)) -- `@deepseek-ai/dsh-client-ui-activity`([`packages/client/ui-activity/src/index.ts`](../packages/client/ui-activity/src/index.ts)) - `@deepseek-ai/dsh-client-ui-agent-preset`([`packages/client/ui-agent-preset/src/index.ts`](../packages/client/ui-agent-preset/src/index.ts)) - `@deepseek-ai/dsh-client-ui-approval`([`packages/client/ui-approval/src/index.ts`](../packages/client/ui-approval/src/index.ts)) - `@deepseek-ai/dsh-client-ui-attachment`([`packages/client/ui-attachment/src/index.ts`](../packages/client/ui-attachment/src/index.ts)) @@ -3470,6 +3443,7 @@ export interface Config { - `@deepseek-ai/dsh-client-ui-directory-picker-native`([`packages/client/ui-directory-picker-native/src/index.ts`](../packages/client/ui-directory-picker-native/src/index.ts)) - `@deepseek-ai/dsh-client-ui-goal`([`packages/client/ui-goal/src/index.ts`](../packages/client/ui-goal/src/index.ts)) - `@deepseek-ai/dsh-client-ui-input-trigger`([`packages/client/ui-input-trigger/src/index.ts`](../packages/client/ui-input-trigger/src/index.ts)) +- `@deepseek-ai/dsh-client-ui-jobs`([`packages/client/ui-jobs/src/index.ts`](../packages/client/ui-jobs/src/index.ts)) - `@deepseek-ai/dsh-client-ui-layout`([`packages/client/ui-layout/src/index.ts`](../packages/client/ui-layout/src/index.ts)) - `@deepseek-ai/dsh-client-ui-message-feedback`([`packages/client/ui-message-feedback/src/index.ts`](../packages/client/ui-message-feedback/src/index.ts)) - `@deepseek-ai/dsh-client-ui-model-selection`([`packages/client/ui-model-selection/src/index.ts`](../packages/client/ui-model-selection/src/index.ts)) @@ -3530,7 +3504,6 @@ export interface Config { 抽象服务类——部署时应改为加载具体的实现包(参见[能力 seam](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md))。 -- `@deepseek-ai/dsh-activity` — 抽象 `ActivityRegistry`([`packages/activity/activity/src/index.ts`](../packages/activity/activity/src/index.ts)) - `@deepseek-ai/dsh-attachment` — 抽象 `AttachmentStore`([`packages/attachment/attachment/src/index.ts`](../packages/attachment/attachment/src/index.ts)) - `@deepseek-ai/dsh-code-runtime` — 抽象 `CodeRuntime`([`packages/code-runtime/code-runtime/src/index.ts`](../packages/code-runtime/code-runtime/src/index.ts)) - `@deepseek-ai/dsh-compaction` — 抽象 `CompactionEngine`([`packages/compaction/compaction/src/index.ts`](../packages/compaction/compaction/src/index.ts)) diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml index 7ff1ac079f..7ef2ec250e 100644 --- a/docs/event-producer-consumer.i18n.yaml +++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md -event-producer-consumer.md: 48aacf9dc6ece2431402ab72c171d236ed3b1359 -event-producer-consumer.zh.md: f644336b2cf540e28a88e2a6729508586021d46f +event-producer-consumer.md: fc05e2ec6ba8d3d5cfc409a617ee069759c93c08 +event-producer-consumer.zh.md: 42e79d5469f2b56e119b34b7dac63b8b590ff145 diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md index f644336b2c..42e79d5469 100644 --- a/docs/event-producer-consumer.zh.md +++ b/docs/event-producer-consumer.zh.md @@ -23,11 +23,11 @@ | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:224`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:185`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` | | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:285`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:523`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:503`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:530`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:509`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:516`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:586`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:566`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:593`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:572`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:579`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` | | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:80`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | @@ -71,8 +71,8 @@ | `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:79`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) | | `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:68`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) | | `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:89`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) | -| `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:58`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow) | -| `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:51`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow) | +| `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:58`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | +| `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:51`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - | | `workflow/start` | `emit` | [`packages/workflow/workflow/src/index.ts:43`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) | ## 包源码中出现的非 harness 或未声明事件字符串 diff --git a/docs/subsystems/README.i18n.yaml b/docs/subsystems/README.i18n.yaml index 8587f8d35d..f6341b0335 100644 --- a/docs/subsystems/README.i18n.yaml +++ b/docs/subsystems/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/subsystems/README.md -README.md: d75bd368d5976813133bb8f62b1b5295bfb32b7c -README.zh.md: 589a72d81fd4e7d277b31626f896b41dc0ea1eb2 +README.md: f3340ebeb426fe9cc5c4570b3c8a3440cc1682ec +README.zh.md: 2e4523f03d1a942d9f93abf34ad2cc8687b413b8 diff --git a/docs/subsystems/activity.i18n.yaml b/docs/subsystems/activity.i18n.yaml deleted file mode 100644 index cf285e6ba7..0000000000 --- a/docs/subsystems/activity.i18n.yaml +++ /dev/null @@ -1,6 +0,0 @@ -# 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 docs/subsystems/activity.md -activity.md: 000bdc30be05eb17d670367df3fd214e7d0af7f3 -activity.zh.md: 1fc79e9d596351a1f818ea83c15d1b5082689b79 diff --git a/docs/subsystems/jobs.i18n.yaml b/docs/subsystems/jobs.i18n.yaml index 53ba3397ea..370043fe58 100644 --- a/docs/subsystems/jobs.i18n.yaml +++ b/docs/subsystems/jobs.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 docs/subsystems/jobs.md -jobs.md: 092da7b6f7e10c5713d3d6c9c5c46f925084f86a -jobs.zh.md: 9dc390eb30901664edb47c6727a54ddd83839fa7 +jobs.md: 1b8e58f27be9e7198063960d436e61502c4f7e3b +jobs.zh.md: 0a1d04fcaf0ea0ceadcb457c756f0962e47eca34 diff --git a/docs/subsystems/jobs.zh.md b/docs/subsystems/jobs.zh.md index 5928c640c4..0a1d04fcaf 100644 --- a/docs/subsystems/jobs.zh.md +++ b/docs/subsystems/jobs.zh.md @@ -23,7 +23,7 @@ interface JobKindMap { ## 生产方约定 -`JobStart` 声明身份和启动器。运行时会在调用 `run()` 前完成预检,随后提交注册,不再执行可能失败的步骤。生产方拥有执行资源;运行时拥有身份、访问权限和生命周期状态。 +`JobStart` 声明身份和启动器。运行时会在完成预检后携带该 job 的生产者面调用 `run()`,随后提交注册,不再执行可能失败的步骤。生产方拥有执行资源;运行时拥有身份、访问权限和生命周期状态。 ```ts type-equiv /** @@ -38,7 +38,9 @@ interface JobStart { label: string /** * Optional UTF-8 byte cap for each complete model-facing completion notice or - * output read, including controller status metadata. + * output read, including controller status metadata. Independent of record + * retention: it bounds the consuming model surface, never + * {@link JobRegistry.readRecord}. */ outputLimitBytes?: number /** @@ -49,11 +51,22 @@ interface JobStart { */ owner?: Agent /** - * Start the work after preflight and synchronously return its hooks. Called - * once; a throw leaves nothing registered, and the producer must clean up any - * partially started resources. + * Declares an observable output record beside the model-facing surfaces: + * {@link RunningJob.append} retains chunks in a bounded ring that any number + * of observers read at absolute byte offsets through + * {@link JobRegistry.readRecord}, and snapshots carry + * {@link JobSnapshot.outputTotal} and {@link JobSnapshot.outputEarliest}. + * Without the declaration `append` logs and drops. */ - run(): JobHooks + record?: true + /** + * Start the work after preflight and synchronously return its hooks. Called + * once with the job's producer face; a throw leaves nothing registered (the + * spent ordinal is skipped), and the producer must clean up any partially + * started resources. + * @param job - the issued id plus the record append and live-detail writers. + */ + run(job: RunningJob): JobHooks } ``` @@ -71,13 +84,16 @@ interface JobHooks { * Resolves after the producer releases its resources, not merely when work * finishes. Must not reject; the runtime converts a rejection to `failed`. * If teardown cancellation throws, the runtime may force-fail only the - * registry record without claiming that the work stopped. + * registry record without claiming that the work stopped. Settlement also + * ends the record: fold any record-filling pump into this promise so the + * final drain lands before the registry trims and closes the stream. */ done: Promise /** * Consume output produced since the previous call. The producer formats * truncation and spill notices. Absence marks a final-output-only job; each - * job has one consuming cursor. + * job has one consuming cursor. Independent of the record: this is the + * model-facing projection, {@link JobRegistry.readRecord} the observer one. */ readOutput?(): string } @@ -95,6 +111,70 @@ interface JobOutcome { } ``` +## 观测 record + +声明 `record: true` 的生产方通过 starter 收到的 `RunningJob` 面把原始输出流入按 job 划分的有界环形缓冲;任意数量的观察者通过 `readRecord` 按绝对字节偏移读取保留块,不触碰消耗型的模型游标与通知状态。job 结算即封流并把保留量裁剪到结算上限——record 没有独立生命周期。`pumpJobOutput` 以有界节奏把生产方的偏移读取器(subprocess 的 `readFrom` 家族)复制进 record。 + +```ts type-equiv +/** + * Producer face of one registered job, handed to {@link JobStart.run} and + * valid for the job's whole life. All methods are synchronous. Writes staged + * inside the starter call are retained and become visible with the + * registration commit; after settlement — the producer's own outcome, a kill, + * or a registry-forced teardown end — both methods log and drop instead of + * throwing, so a producer's trailing flush cannot break its own teardown path. + */ +interface RunningJob { + /** The registry-issued id (`-N`). */ + readonly id: JobId + /** + * Append one record chunk. Offsets advance by the chunk's UTF-8 byte + * length; an empty chunk is dropped without waking observers. Without a + * {@link JobStart.record} declaration the chunk is logged and dropped. + * @param text - the chunk text, exactly as produced. + * @param options - stream label and gap marker. + */ + append(text: string, options?: JobAppendOptions): void + /** + * Replace the snapshot's status detail with a live progress line (`3/10`). + * Works for every job, with or without a record. + * @param detail - the new detail line. + */ + updateDetail(detail: string): void +} +``` + +```ts type-equiv +/** One retained record chunk returned by {@link JobRegistry.readRecord}. */ +interface JobRecordChunk { + /** Absolute offset of the chunk's first byte. */ + at: number + /** Chunk text exactly as appended (possibly tail-trimmed by retention). */ + text: string + /** Stream label, when the producer supplied one. */ + channel?: JobChannel + /** Producer-reported loss immediately before this chunk. */ + gapBefore?: true +} +``` + +```ts type-equiv +/** Result of one non-consuming {@link JobRegistry.readRecord}. */ +interface JobRecordRead { + /** Retained chunks overlapping `[from, total)`, in offset order. */ + chunks: readonly JobRecordChunk[] + /** + * Offset to resume from — the record's current `outputTotal`. Always a + * chunk boundary: appends land whole and trimming only advances chunk + * starts, and consumers concatenate `chunks` under that assumption, so a + * provider serving partial chunks would silently duplicate text. + */ + next: number + /** True when `from` fell below the oldest retained byte, so bytes are missing before `chunks`. */ + lossy: boolean +} +``` + ## 消费方视图 快照是每次新建的只读投影。`ownerSession` 携带用于授权的共享 `SessionId`;完成监听器则会另行收到用于生命周期清理的确切拥有者对象。另一个接口已经交付终止状态或承诺交付时,`reported` 会抑制完成通知;排空 owner 或服务的 teardown 取消同样计入。 @@ -121,7 +201,10 @@ interface JobSnapshot { ownerSession?: SessionId /** Current lifecycle state. */ status: JobStatus - /** Kind-specific status detail, present once the producer supplied one (usually terminal). */ + /** + * Kind-specific status detail: live progress while the producer updates it + * through {@link RunningJob.updateDetail}, the terminal detail once settled. + */ detail?: string /** Epoch ms when the job was registered. */ startedAt: number @@ -135,6 +218,17 @@ interface JobSnapshot { * otherwise spend a model request per teardown layer. */ reported: boolean + /** + * Total UTF-8 bytes ever appended to the record — the offset the next chunk + * starts at. Present exactly when the job declared {@link JobStart.record}. + */ + outputTotal?: number + /** + * Offset of the oldest retained record byte. Greater than zero exactly when + * retention dropped the head; a reader starting below it gets a lossy read. + * Present exactly when the job declared {@link JobStart.record}. + */ + outputEarliest?: number } ``` @@ -154,7 +248,7 @@ interface JobRead { ## 服务行为 -抽象的 [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition 规定原子 `start`、限定调用方作用域的 `get` 和 `list`、`read`、`kill`、有界 `wait`、故障隔离的 `onJobDone` 与 `onJobsChanged` 监听器,以及 `attachController`;[`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) 是其进程局部 Service Provider。授权会比较拥有者会话;拥有者清理与准入会使用确切的已注册 `Agent` 实例。本地 Service Provider 的 `maxConcurrentJobsPerOwner` 配置必须是正的安全整数,默认值为 `10`;它按确切 owner 统计 `running` 与 `stopping` 记录,所有无 owner 任务共享一个服务级桶,并在生产方终止结算后释放容量。Service Definition 约定见 [`dsh-jobs`](../../packages/jobs/jobs/README.zh.md),注册表生命周期与准入策略见 [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.zh.md),面向模型的 Consumer 见 [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.zh.md)。 +抽象的 [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition 规定了原子化的 `start`、按调用方划定的 `get` 与 `list`、`read`、非消耗的 `readRecord`、`kill`、有界的 `wait`、故障隔离的 `onJobDone`、`onJobsChanged` 与 `onOutput` 监听器,以及 `attachController`;[`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) 是进程本地的 Service Provider。授权比较 owner 会话;owner 清理与准入使用注册在案的确切 `Agent` 实例。本地 provider 的正安全整数配置 `maxConcurrentJobsPerOwner` 默认 `10`,按确切 owner 统计 `running` 加 `stopping` 记录,无主任务共享一个桶;生产方终态结算释放容量,`retainBytes`(默认 262144)与 `settledRetainBytes`(默认 16384)约束每个已声明 record 的运行期与结算后保留量。参见 [`dsh-jobs`](../../packages/jobs/jobs/README.zh.md)(Service Definition 契约)、[`dsh-jobs-local`](../../packages/jobs/jobs-local/README.zh.md)(注册表生命周期与准入策略)与 [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.zh.md)(模型侧 Consumer)。 diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml index 92d25d2cfd..9b9953bdb4 100644 --- a/packages/api/session-controller/README.i18n.yaml +++ b/packages/api/session-controller/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/api/session-controller/README.md -README.md: 2f2192cde2941019c9687738f8e3f5e50ddd6d8e -README.zh.md: 273d304d3cd3bbcbadd3e40202d8d923f3a27498 +README.md: 2e5ca38bf51a1aca881e0a15b28f0b7856b51f73 +README.zh.md: e316aac4c07692720d1c6809d52bbe3ab06be033 diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md index 273d304d3c..e316aac4c0 100644 --- a/packages/api/session-controller/README.zh.md +++ b/packages/api/session-controller/README.zh.md @@ -29,6 +29,8 @@ kind: "package-reference" Client adapter 提供 `SessionEventStream`,即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow,只发布连续的 `replace`、`prepend` 和 `append` 变更,并通过 tail page 修复重连或 seq 缺口。普通 record 覆盖 `[event.seq, event.seq]`,packed row 覆盖 `[event.seq, event.seq + memberCount - 1]`。业务、persistence 或无法恢复的连续性错误会终止 stream,只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`;每代都以完整的进程本地 baseline 开始,因此重连会替换 queue、jobs 和 projection 状态,而不会把瞬态值当作 durable event。 +`SessionJob` 行恰在该 job 声明了观测 record 时携带 `outputTotal`,`session.observeJob` 从绝对字节偏移流式发送该 record——一个 `opened` 锚帧、聚合的 `output` 帧、最后一个终态 `status` 帧——围栏读取者由请求的 session 解析。record 读取是非消耗的:模型侧游标与完成通知状态永远观察不到它们。Client adapter 提供 `ctx.jobOutput`:按 job 引用计数的观测服务,任务列表 UI 渲染其累积视图;同一 job 的观察者共享一条流,重连时从模型游标续读。 + Session 对象还承载本地提交回显:`session.beginSubmission` 在调用方序列化与 prompt 之前,同步把一条回显写入 `SessionSnapshot.pendingSubmissions`,会话 UI 因此能在点击提交的当帧显示消息。Session 根据当前运行状态与请求的投递模式推导每条回显的 `transcript`、`queued` 或 `steering` 位置,并在序列化期间保留该位置。prompt 的 `requestId` 是关联标识:Host 把它回显为 durable user source 的 `rpcId`,queue occurrence 也把它投影为 `SessionQueuedItem.rpcId`。回显在观察到其 durable event 或 queue occurrence 后延迟一个动画帧退休,该延迟保证替代内容就绪前回显仍可渲染;带标识的 prompt 失败或被放弃时立即退休,销毁时按 failed 退休;每次退休恰好触发一次注册的 `onRetire` 回调。回显只存在于 Client 内存;刷新与重连只从 durable event 重建会话。 ----- @@ -40,6 +42,8 @@ Session 对象还承载本地提交回显:`session.beginSubmission` 在调用 |---|---:|---| | `coldBlankProbeMaxBytes` | `1,024` | 可进行空白状态验证的冷 Session 工件最大物理大小;`0` 禁用探测 | | `nativeOpen` | 平台探测 | 是否能把 Session 工作区路径交给原生桌面打开器 | +| `observeFlushMs` | `100` | 新 record 输出到一次 job 观测读取之间的聚合窗口,毫秒 | +| `observeMaxFrameBytes` | `65,536` | 每个 job 观测输出帧的软字节预算;更大的单块整块发送 | 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-api-session-controller)是所有受支持字段及其 JSDoc 的完整来源。 diff --git a/packages/client/README.i18n.yaml b/packages/client/README.i18n.yaml index 6b75531c69..04d9e1336a 100644 --- a/packages/client/README.i18n.yaml +++ b/packages/client/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/README.md -README.md: 3e45bac9b06e7006d955fc0cd8d600732e5f36ca -README.zh.md: e624cd5f87c450655c04b348cc72345b9389b0bd +README.md: 367a6d39ce1248b4246aa3e497093b5edb315fb0 +README.zh.md: 05a0143ce4eee253e1d94a1ff29e4c4f08da1274 diff --git a/packages/jobs/jobs-local/README.i18n.yaml b/packages/jobs/jobs-local/README.i18n.yaml index 6e514ac7e3..e4822080f4 100644 --- a/packages/jobs/jobs-local/README.i18n.yaml +++ b/packages/jobs/jobs-local/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/jobs/jobs-local/README.md -README.md: cfbda98ccf59bcd12e931350c708cc15b30ec54c -README.zh.md: 07acfc3c75ef730328792ab1aa45197bfcd5c849 +README.md: 2da0a0b3399ce5a55b63cad491ab6ee48a2f8a90 +README.zh.md: cc362ad7935a91a564cca5a82228934bcc15077d diff --git a/packages/jobs/jobs-local/README.zh.md b/packages/jobs/jobs-local/README.zh.md index 07acfc3c75..cc362ad793 100644 --- a/packages/jobs/jobs-local/README.zh.md +++ b/packages/jobs/jobs-local/README.zh.md @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -`dsh-jobs-local` 在 harness 进程内运行后台任务:工作会在 agent 继续推进的同时保持运行,拥有它的 agent 可以读取、等待、列出和取消它;同时挂载 `dsh-tool-jobs` 时,完成以会话内通知送达。它用内存记录实现 `dsh-jobs` 约定,并且只交出全新快照,从不交出实时状态。按所有者的并发上限(默认 10)约束一个 agent 同时处于运行或停止中的任务数量;任务会随 harness 进程终止而消失,无法跨重启持久。 +`dsh-jobs-local` 在 harness 进程内运行后台任务:工作会在 agent 继续推进的同时保持运行,拥有它的 agent 可以读取、等待、列出和取消它;同时挂载 `dsh-tool-jobs` 时,完成以会话内通知送达。它用内存记录实现 `dsh-jobs` 约定,并且只交出全新快照,从不交出实时状态。按所有者的并发上限(默认 10)约束一个 agent 同时处于运行或停止中的任务数量,声明了 record 的任务另持有一个有界的内存输出环(默认运行期 256 KiB、结算时裁剪到 16 KiB),供观察者按绝对偏移读取;任务会随 harness 进程终止而消失,无法跨重启持久。 ## 目录 @@ -42,6 +42,8 @@ kind: "package-reference" | 字段 | 默认值 | 含义 | |---|---|---| | `maxConcurrentJobsPerOwner` | `10` | 每个精确所有者,或共享的无主桶中,`running` 加 `stopping` 任务的最大数量 | +| `retainBytes` | `262144` | 每个任务 record 的运行期保留量,UTF-8 字节 | +| `settledRetainBytes` | `16384` | 任务结算后保留的 record 量,UTF-8 字节 | 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-jobs-local)是每个受支持字段的穷尽式真源。 @@ -69,7 +71,8 @@ kind: "package-reference" ### 设计理念 -- **内存记录,全新快照。** `LocalJobRegistry` 为每个任务保存一条 `TrackedTask`,每次调用都投影出新的只读快照;调用方永远不会拿到实时状态。 +- **内存记录、全新快照。** `LocalJobRegistry` 为每个任务保存一份 `TrackedTask`——生命周期状态加可选的 record 环——每次调用都投影新的只读快照或块副本;调用方永远拿不到实时状态。 +- **record 保留量有界。** 追加超出运行期上限时丢弃最老的保留块(单个超限块保留其 UTF-8 安全尾部);低于保留窗口的读取得到 lossy 结果而非错误,结算时裁剪到结算上限。 - **按所有者分层,一个进程级注册表。** 控制器、完成监听器与变更观察者归档到注册方所在的 scope(`ScopedLayers`),读取把全局层与所有者的 scope 链求并集——因此某个 preset 的任务控制绝不会为自身组合未加载任何控制器的 agent 保持 `start()` 可用,一次结算也只会抵达其所有者所属组合注册的监听器。 - **启动前先预检。** `start()` 在调用生产方之前检查控制器服务、spec 有效性、仍存活的所有权与容量,因此拒绝不会留下 job id 或执行资源;注册一旦提交,后续不再有可失败步骤。 - **结算首次优先,完成最后。** 最早的终止结果只记录一次,释放等待方,并只通知监听器一次,各监听器故障单独隔离;完成在记录提交且可见集变更发布之后才宣布,因为报告方可能同步开启一个模型轮次。 @@ -84,11 +87,11 @@ kind: "package-reference" ### scope 分层 -`attachController`、`onJobDone` 与 `onJobsChanged` 注册到调用上下文所在的 scope 层。控制器问题(`servesOwner`)与监听器投递(`listenersFor`、`changedFor`)走同一条链:先是全局层,再沿所有者的链逐层。注册是无名 token,因此重复标签仍可独立释放。 +`attachController`、`onJobDone`、`onJobsChanged` 与 `onOutput` 注册到调用上下文所在的 scope 层。控制器问题(`servesOwner`)与监听器投递(`listenersFor`、`changedFor`、`outputFor`)走同一条链:先是全局层,再沿所有者的链逐层。注册是无名 token,因此重复标签仍可独立释放。 ### 准入与结算 -`activeTaskCount` 按精确所有者或共享无主桶统计权威记录。`settle` 在存在挂起等待方时把任务标为已报告,解析每个等待方,记录终止快照,宣布可见集变更,然后通知完成监听器。挂起的等待会在监听器运行前把任务标为已报告,因此完成报告方不会重复通知;销毁时的取消出于同样理由标记——面向正在被销毁的所有者的通知不会有人读到。 +`activeTaskCount` 按精确所有者或共享无主桶统计权威记录。`settle` 在存在挂起等待方时把任务标为已报告,把已声明的 record 裁剪到结算保留量,解析每个等待方,记录终止快照,宣布可见集变更与 record 的最终输出信号,然后通知完成监听器。挂起的等待会在监听器运行前把任务标为已报告,因此完成报告方不会重复通知;销毁时的取消出于同样理由标记——面向正在被销毁的所有者的通知不会有人读到。 ### 销毁 diff --git a/packages/jobs/jobs-local/tests/jobs.spec.ts b/packages/jobs/jobs-local/tests/jobs.spec.ts index f305c73ba6..9771023057 100644 --- a/packages/jobs/jobs-local/tests/jobs.spec.ts +++ b/packages/jobs/jobs-local/tests/jobs.spec.ts @@ -200,7 +200,7 @@ describe('LocalJobRegistry.start', () => { for (const job of live) ctx.jobs.start(job.spec) const blocked = producer() - const run = vi.fn(() => blocked.spec.run()) + const run = vi.fn((job: RunningJob) => blocked.spec.run(job)) expect(() => ctx.jobs.start({ ...blocked.spec, run })) .toThrow('background job limit reached for this owner (limit: 10)') expect(run).not.toHaveBeenCalled() @@ -213,7 +213,7 @@ describe('LocalJobRegistry.start', () => { expect(ctx.jobs.start(first.spec)).toBe('bash-1') const blocked = producer() - const run = vi.fn(() => blocked.spec.run()) + const run = vi.fn((job: RunningJob) => blocked.spec.run(job)) expect(() => ctx.jobs.start({ ...blocked.spec, run })) .toThrow('use job_kill to stop an unneeded job, wait for it to finish, then retry') expect(run).not.toHaveBeenCalled() @@ -658,7 +658,7 @@ describe('LocalJobRegistry owner isolation', () => { ctx.jobs.start(current.spec) // Attach the current owner's cleanup first. const stale = producer({ owner: staleOwner }) - const staleRun = vi.fn(() => stale.spec.run()) + const staleRun = vi.fn((job: RunningJob) => stale.spec.run(job)) expect(() => ctx.jobs.start({ ...stale.spec, run: staleRun })) .toThrow('is not the registered agent instance') expect(staleRun).not.toHaveBeenCalled() diff --git a/packages/jobs/jobs/README.i18n.yaml b/packages/jobs/jobs/README.i18n.yaml index faeca47c08..662a521a55 100644 --- a/packages/jobs/jobs/README.i18n.yaml +++ b/packages/jobs/jobs/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/jobs/jobs/README.md -README.md: 7625c3672d24edff908c7be01723e970bd44d1f7 -README.zh.md: d62953d325ad14479539ccb61fb51378d21e3b52 +README.md: 10c74af908f64c18616e3c1eb71f19a3cbbf4eb3 +README.zh.md: 1fc500311c58a538ebfc7fbd89886d9c12b96acd diff --git a/packages/jobs/jobs/README.zh.md b/packages/jobs/jobs/README.zh.md index d62953d325..1fc500311c 100644 --- a/packages/jobs/jobs/README.zh.md +++ b/packages/jobs/jobs/README.zh.md @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -`dsh-jobs` 让工具可以把长时间工作注册为后台任务:工作获得稳定的 `-N` id,在 agent 继续推进的同时保持运行,拥有它的 agent 可以随时读取输出、带超时等待或请求取消。任务属于启动它的 agent 会话,因此一个 agent 的工作永远不会被另一个 agent 看到;完成以会话内通知而非轮询的方式送达给拥有者。本包只提供约定:进程本地注册表位于 `dsh-jobs-local`,模型侧控制与完成通知位于 `dsh-tool-jobs`。加载一个实现才能获得后台任务;没有实现时 `ctx.jobs` 不存在,`start()` 无法运行。 +`dsh-jobs` 让工具可以把长时间工作注册为后台任务:工作获得稳定的 `-N` id,在 agent 继续推进的同时保持运行,拥有它的 agent 可以随时读取输出、带超时等待或请求取消。任务属于启动它的 agent 会话,因此一个 agent 的工作永远不会被另一个 agent 看到;完成以会话内通知而非轮询的方式送达给拥有者。生产方还可以声明按 job 划分的观测 record:一条追加式的有界输出流,任意数量的观察者(Web 客户端)按绝对字节偏移读取,不触碰模型侧的消耗型游标。本包只提供约定:进程本地注册表位于 `dsh-jobs-local`,模型侧控制与完成通知位于 `dsh-tool-jobs`。加载一个实现才能获得后台任务;没有实现时 `ctx.jobs` 不存在,`start()` 无法运行。 ## 目录 @@ -31,6 +31,8 @@ kind: "package-reference" 生产方以 kind 和一行标签注册工作;注册表返回 `-N` id,例如 `bash-1`。拥有任务的任何一方都可以读取输出、列出任务、带超时等待结算或请求取消——每次调用都返回任务状态的全新快照,从 `running`、`stopping` 到终止态的 `completed`、`killed` 或 `failed`。任务结算时,拥有它的 agent 会通过 `dsh-tool-jobs` 转成会话内通知的完成监听器得到通知,因此无需轮询。生产方还可以附加可选的字节上限,让每次完整的模型侧输出读取或完成通知保持有界。 +声明 `record: true` 的生产方还会通过 starter 收到的 `RunningJob` 面把原始输出流入该 job 的有界 record:观察者按绝对字节偏移读取保留块并在推进时收到信号,结束 job 的结算同时封流,`updateDetail` 把实时进度行发布进每个快照。record 对模型不可见:读取不消耗任何东西,也永不触碰通知状态。 + ### 归属边界 任务属于启动它的 agent 会话:其他 agent 无法读取或停止它。`bash-1` 这样的 id 可预测,因此这道隔离是授权,而非保密。没有所有者启动的任务对任何调用方开放,并持续到服务被释放为止。 @@ -75,13 +77,14 @@ kind: "package-reference" | 文件 | 职责 | |---|---| | [`src/index.ts`](src/index.ts) | 插件入口:抽象 `JobRegistry` 服务及其约定 | -| [`src/types.ts`](src/types.ts) | 共享词汇:`JobKindMap`、`JobStart`、`JobHooks`、`JobSnapshot`、监听器类型 | +| [`src/types.ts`](src/types.ts) | 共享词汇:`JobKindMap`、`JobStart`、`JobHooks`、`RunningJob`、`JobSnapshot`、监听器类型 | | [`src/brand.ts`](src/brand.ts) | `JobId` 带类型标记的标识符,无需 agent 依赖即可导入 | -| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件:校验快照标识、状态、时间戳与所有者字段 | +| [`src/pump.ts`](src/pump.ts) | `pumpJobOutput`:把生产方偏移读取器复制进 job record 的轮询泵 | +| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件:校验快照标识、状态、时间戳、所有者与 record 偏移字段 | ### 服务操作 -每个操作都是已注册任务之上的薄投影:`get` 与 `list` 返回非消费式快照,`read` 推进唯一的流游标,`kill` 在改变状态前调用生产方取消,`wait` 阻塞至超时,`start()` 在调用生产方 `run()` 一次之前预检访问、校验与准入,同时拒绝任何没有已附加控制器服务的所有者;监听器按所有者粒度观察终止记录与可见集变化,`attachController` 把控制器可用性限定在其 effect 生命周期内。确切签名与行为见 [`src/index.ts`](src/index.ts) 的 JSDoc 与生成的 [`ctx.jobs` cordis 接口面](../../../docs/subsystems/jobs.zh.md)。 +每个操作都是已注册任务之上的薄投影:`get` 与 `list` 返回非消费式快照,`read` 推进唯一的流游标,`readRecord` 按绝对偏移读取保留的 record 块且不消耗任何东西,`kill` 在改变状态前调用生产方取消,`wait` 阻塞至超时,`start()` 在调用生产方 `run()` 一次之前预检访问、校验与准入,同时拒绝任何没有已附加控制器服务的所有者;监听器按所有者粒度观察终止记录、可见集变化与 record 推进,`attachController` 把控制器可用性限定在其 effect 生命周期内。确切签名与行为见 [`src/index.ts`](src/index.ts) 的 JSDoc 与生成的 [`ctx.jobs` cordis 接口面](../../../docs/subsystems/jobs.zh.md)。 @@ -118,7 +121,7 @@ kind: "package-reference" 这些限制说明约定何时不合适。它们是当前包约束,不是任务积压。 - **约定是进程内的**——`JobStart.run()` 传入回调和确切的 `Agent` 对象;持久化或跨进程后端必须先重塑身份、重启、所有权与观察语义,才能实现此 seam。 -- **流输出只有一个消费游标**——它属于模型;独立观察者改用生产者镜像进去的非消费 [`dsh-activity`](../../activity/activity/README.zh.md) 观察面。 +- **流输出只有一个消费游标**——它属于模型;独立观察者改用非消耗的 `readRecord` 读取 job 声明的 record。 - **前台工作无法转为后台**——生产方在启动前选择前台或后台。 diff --git a/packages/shell/tool-bash/README.i18n.yaml b/packages/shell/tool-bash/README.i18n.yaml index 29ea9fb077..c979907a22 100644 --- a/packages/shell/tool-bash/README.i18n.yaml +++ b/packages/shell/tool-bash/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/shell/tool-bash/README.md -README.md: 5e30ed598e894fc764e62366218f4e5ded0a7084 -README.zh.md: a62938a09f9a8ddd38094efca006932645d79d0d +README.md: 39e894970a92f68e09edf7b8dd10e040ed602b43 +README.zh.md: 025fb536a5196f4103a3476ba7ae20d5a59bda39 diff --git a/packages/shell/tool-bash/README.zh.md b/packages/shell/tool-bash/README.zh.md index a62938a09f..025fb536a5 100644 --- a/packages/shell/tool-bash/README.zh.md +++ b/packages/shell/tool-bash/README.zh.md @@ -55,7 +55,7 @@ kind: "package-reference" ### 后台运行长时间命令 -传入 `run_in_background: true` 会立即返回 job id,不应用超时;命令继续运行,agent 同时处理其他事情。agent 用 `job_output` 读取输出(除非 `wait: true`,否则非阻塞)、用 `job_list` 列出任务、用 `job_kill` 停止任务;完成的任务会在会话内通知拥有它的 agent。后台支持需要挂载通用任务运行时(`dsh-jobs-local`)及其控制工具(`dsh-tool-jobs`)。加载了可选的 `ctx.activities` 注册表时,已提交的后台运行还会被尽力镜像进去:一个与调用和 job 关联的 `bash` activity 以 `activityPollMs`(默认 150)的节奏泵送句柄的非消费 `observed` 读取器,使 Web 客户端在不触碰 job 游标的情况下流式看到实时输出;任何观察失败都被记录并吞掉。 +传入 `run_in_background: true` 会立即返回 job id,不应用超时;命令继续运行,agent 同时处理其他事情。agent 用 `job_output` 读取输出(除非 `wait: true`,否则非阻塞)、用 `job_list` 列出任务、用 `job_kill` 停止任务;完成的任务会在会话内通知拥有它的 agent。后台支持需要挂载通用任务运行时(`dsh-jobs-local`)及其控制工具(`dsh-tool-jobs`)。后台 job 声明观测 record:运行的非消费 `observed` 读取器以 `recordPollMs`(默认 150)的节奏泵入其中,使 Web 客户端在不触碰 job 消耗游标的情况下流式看到实时输出;泵失败会被记录并吞掉,job 继续运行。 ### 沙箱执行与升权 diff --git a/packages/shell/tool-pwsh/README.i18n.yaml b/packages/shell/tool-pwsh/README.i18n.yaml index bd08faa835..baefd11561 100644 --- a/packages/shell/tool-pwsh/README.i18n.yaml +++ b/packages/shell/tool-pwsh/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/shell/tool-pwsh/README.md -README.md: 8ea7e6f1e20f9c61f34fdc730c5c0b18706a2865 -README.zh.md: 2d8d51209a2ea66650904f10df263dfa0614aae3 +README.md: cfd6af5fe08a5f996d49c4b12c80930c687834fd +README.zh.md: 3b9a53047216d3ba80ca850f06bcf7a5c06bbfea diff --git a/packages/shell/tool-pwsh/README.zh.md b/packages/shell/tool-pwsh/README.zh.md index 2d8d51209a..3b9a530472 100644 --- a/packages/shell/tool-pwsh/README.zh.md +++ b/packages/shell/tool-pwsh/README.zh.md @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -`dsh-tool-pwsh` 为 agent 提供 `pwsh` 工具,通过已挂载的 shell 执行器运行 PowerShell 命令——它是 `dsh-tool-bash` 的 Windows 对应物,逐调用镜像。每次调用都运行在全新 pwsh 进程中,因此状态不会保留;`run_in_background` 把长时间运行的命令变成后台任务。命令是 PowerShell 方言:原生 `C:\...` 路径与 `$env:NAME` 变量,不做方言翻译。每次调用都运行在受管 `DSH_*` 环境中;在沙箱执行器下,工具会教授并执行 Windows 特有的语言模式与命名管道约定。请与 `dsh-pwsh-local` 等 PowerShell 执行器以及 `dsh-shell-env` 插件一起挂载。加载了可选的 `ctx.activities` 注册表时,已提交的后台运行还会被尽力镜像为按 `activityPollMs`(默认 150)泵送的 `pwsh` activity,与 `dsh-tool-bash` 完全一致。 +`dsh-tool-pwsh` 为 agent 提供 `pwsh` 工具,通过已挂载的 shell 执行器运行 PowerShell 命令——它是 `dsh-tool-bash` 的 Windows 对应物,逐调用镜像。每次调用都运行在全新 pwsh 进程中,因此状态不会保留;`run_in_background` 把长时间运行的命令变成后台任务。命令是 PowerShell 方言:原生 `C:\...` 路径与 `$env:NAME` 变量,不做方言翻译。每次调用都运行在受管 `DSH_*` 环境中;在沙箱执行器下,工具会教授并执行 Windows 特有的语言模式与命名管道约定。请与 `dsh-pwsh-local` 等 PowerShell 执行器以及 `dsh-shell-env` 插件一起挂载。后台运行的 job 声明按 `recordPollMs`(默认 150)泵送的观测 record,与 `dsh-tool-bash` 完全一致。 ## 目录 diff --git a/packages/workflow/tool-workflow/README.i18n.yaml b/packages/workflow/tool-workflow/README.i18n.yaml index 719235042d..125c16d968 100644 --- a/packages/workflow/tool-workflow/README.i18n.yaml +++ b/packages/workflow/tool-workflow/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/workflow/tool-workflow/README.md -README.md: a7096838da13f7f744bb1e6179a758d3dedc38a3 -README.zh.md: 254f498b4fe13397a035c97bfd7c708cde3415d7 +README.md: 2291b274a5cd52813266f4cb0e9276cd8019c4f8 +README.zh.md: d3009fa57d2ec2a16ed01c4926bb41066f1bbf2c diff --git a/packages/workflow/tool-workflow/README.zh.md b/packages/workflow/tool-workflow/README.zh.md index 254f498b4f..d3009fa57d 100644 --- a/packages/workflow/tool-workflow/README.zh.md +++ b/packages/workflow/tool-workflow/README.zh.md @@ -68,7 +68,7 @@ kind: "package-reference" 对于根 transport 执行(`exec.parent` 缺省),工具会用四个 log-only 事件把运行投影到调用 Agent 的 Session:`start()` 返回后写 run-start,只记录 `run.id` 匹配的成员开始与结束,并且只在结果可用且 dispose 完全停稳后写 run-end。嵌套 transport 调用照常执行,但不写任何记录。任一次 Session append 首次失败后,本运行会停止后续记录并只告警一次,留下空记录或合法连续前缀,同时不改变工具结果和清理。包 invariant 会在冷加载与实时追加时拒绝重复 start、未配对成员、仍有开放成员的终点与 run-end 后更新,同时允许缺失终态后缀的连续前缀。 -在持久记录之外,每个被记录的顶层运行还会被尽力镜像进可选的 `ctx.activities` 注册表,作为一个 `workflow` activity:原本无人消费的 `workflow/phase` 与 `workflow/log` 事件加上成员生命周期行流入其中,使 Web 客户端看到会话日志刻意不逐行携带的实时叙述。没有注册表、或镜像出现任何失败时,运行本身不受影响。 +引擎的 `workflow/phase` 与 `workflow/log` 事件在本工具没有逐行的持久或观察面:会话日志刻意只记录 run 与成员生命周期,Web transcript 由这些记录派生。 ### 渲染意图 @@ -80,7 +80,6 @@ kind: "package-reference" |---|---| | [`src/index.ts`](src/index.ts) | 插件入口:工具注册、运行生命周期、记录器接线 | | [`src/types.ts`](src/types.ts) | 四个 log-only 记录事件 payload 及其 `SessionEventMap` 声明 | -| [`src/activity.ts`](src/activity.ts) | 顶层运行的尽力 activity 镜像 | | [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件:持久工作流记录协议校验 | diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 010c35a328..a217b3c619 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -1016,6 +1016,21 @@ "symbol": "JobRead", "source": "packages/jobs/jobs/src/types.ts" }, + { + "doc": "docs/subsystems/jobs.md", + "symbol": "RunningJob", + "source": "packages/jobs/jobs/src/types.ts" + }, + { + "doc": "docs/subsystems/jobs.md", + "symbol": "JobRecordChunk", + "source": "packages/jobs/jobs/src/types.ts" + }, + { + "doc": "docs/subsystems/jobs.md", + "symbol": "JobRecordRead", + "source": "packages/jobs/jobs/src/types.ts" + }, { "doc": "docs/subsystems/terminal.md", "symbol": "TerminalWaitReason", From d2e9be40861f594c756745fa48d913b747627ca9 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 1 Sep 2026 18:36:29 +0800 Subject: [PATCH 018/100] test(api): stub session.observeJob on the fake client namespace The regenerated session namespace requires the new stream; the fake serves a never-yielding generator, and job-output.client.spec exercises the real consumer. --- packages/api/session-controller/tests/fake-api.client.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/api/session-controller/tests/fake-api.client.ts b/packages/api/session-controller/tests/fake-api.client.ts index e3ea48f783..e67650d4a2 100644 --- a/packages/api/session-controller/tests/fake-api.client.ts +++ b/packages/api/session-controller/tests/fake-api.client.ts @@ -10,7 +10,7 @@ import type { import type { SessionAddress, SessionControlBaseline, - SessionControlFrame, + SessionControlFrame, SessionObserveJobFrame, SessionFollowFrame, SessionFollowRequest, SessionPage, @@ -235,6 +235,9 @@ export class FakeApiClient { page: request => this.page(request), follow: (request, signal) => this.openFollow(request, signal), control: signal => this.openControl(signal), + // Job-record observation never yields here; the stream consumer is + // exercised directly by job-output.client.spec. + observeJob: () => (async function* (): AsyncGenerator {})(), }, subagents: { list: parentSessionId => this.record( From 419a985fc9741ae6f9eaa319d4f35dd24d98c6fc Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 1 Sep 2026 19:04:25 +0800 Subject: [PATCH 019/100] fix(api): capture the session namespace for job observation at apply time MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Observation (re)opens run on caller stacks — a React expand click, a carrier retry — whose dynamic context has not declared remote.session, so the ClientJobOutput wiring resolves the namespace to a concrete value while the plugin's own context is current, exactly as the activity client did. Caught by the live-job-stream web e2e, whose goldens (with the background-job-list pair) now carry the ui-jobs list name; the client-apply spec gains a jobOutput wiring smoke. --- .../snapshots/live-job-stream/settled.expected.md | 2 +- .../snapshots/live-job-stream/streaming.expected.md | 2 +- packages/api/session-controller/src/client/index.ts | 9 ++++++++- packages/api/session-controller/src/observe-job.ts | 6 ++++-- .../tests/client-apply.client.spec.ts | 12 ++++++++++++ .../web/background-job-list/running.expected.md | 2 +- .../web/background-job-list/settled.expected.md | 2 +- 7 files changed, 28 insertions(+), 7 deletions(-) diff --git a/apps/web/tests/snapshots/live-job-stream/settled.expected.md b/apps/web/tests/snapshots/live-job-stream/settled.expected.md index ecdcd4fea4..6ba8ada46d 100644 --- a/apps/web/tests/snapshots/live-job-stream/settled.expected.md +++ b/apps/web/tests/snapshots/live-job-stream/settled.expected.md @@ -1,4 +1,4 @@ -- list "Tasks": +- list "Background jobs": - listitem: - button "Hide live output of printf 'streamed-%s\\n' marker-line; sleep 45" [expanded]: - text: "bash printf 'streamed-%s\\n' marker-line; sleep 45 signal: SIGTERM {{duration}}" diff --git a/apps/web/tests/snapshots/live-job-stream/streaming.expected.md b/apps/web/tests/snapshots/live-job-stream/streaming.expected.md index aa23b11410..4054d5d42a 100644 --- a/apps/web/tests/snapshots/live-job-stream/streaming.expected.md +++ b/apps/web/tests/snapshots/live-job-stream/streaming.expected.md @@ -1,4 +1,4 @@ -- list "Tasks": +- list "Background jobs": - listitem: - button "Hide live output of printf 'streamed-%s\\n' marker-line; sleep 45" [expanded]: - text: printf 'streamed-%s\n' marker-line; sleep 45 {{duration}} bash running diff --git a/packages/api/session-controller/src/client/index.ts b/packages/api/session-controller/src/client/index.ts index 78a54b37ef..5fc9570a55 100644 --- a/packages/api/session-controller/src/client/index.ts +++ b/packages/api/session-controller/src/client/index.ts @@ -92,7 +92,14 @@ export const inject = [ export function apply(ctx: Context): void { const remotes = ctx.remote as unknown as SessionRemotes const sessions = new ClientSessions(ctx, remotes) - new ClientJobOutput(ctx, remotes, new ClientJobOutputModel()) + // Resolve the session namespace to a concrete value while this plugin's + // context is current: observation (re)opens run on caller stacks (a React + // event, a carrier retry) whose dynamic context has not declared + // `remote.session`, and a property access there fails the inject check. + new ClientJobOutput(ctx, { + $stream: options => remotes.$stream(options), + session: remotes.session, + }, new ClientJobOutputModel()) ctx.remote.$on('api-session/added', (summary) => { sessions.handleSessionAdded(summary) }) ctx.remote.$on('api-session/removed', (sessionId) => { sessions.handleSessionRemoved(sessionId) }) ctx.remote.$on('api-session/status', (sessionId, running) => { diff --git a/packages/api/session-controller/src/observe-job.ts b/packages/api/session-controller/src/observe-job.ts index 516f48779f..795e786455 100644 --- a/packages/api/session-controller/src/observe-job.ts +++ b/packages/api/session-controller/src/observe-job.ts @@ -1,7 +1,7 @@ /** Per-job record observation generations: anchor, coalesced output, terminal status. */ import type { Agent } from '@deepseek-ai/dsh-agent' -import { JobId } from '@deepseek-ai/dsh-jobs' +import type { JobId } from '@deepseek-ai/dsh-jobs/brand' import type { JobRegistry, JobSnapshot } from '@deepseek-ai/dsh-jobs' import type { SessionJobWireChunk, SessionObserveJobFrame, SessionObserveJobRequest } from './types.ts' @@ -99,7 +99,9 @@ export async function* observeJobRecord( throw new Error(`invalid observe offset: expected a non-negative safe integer, got ${JSON.stringify(request.from)}`) } signal.throwIfAborted() - const id = JobId(String(request.jobId)) + // The brand is nominal typing only; the wire boundary stamps it here rather + // than value-importing the optional registry package's constructor. + const id = String(request.jobId) as JobId const waiter = new OutputWaiter() // Subscribe before the first read so an append between the anchor read and // the wait cannot be missed. diff --git a/packages/api/session-controller/tests/client-apply.client.spec.ts b/packages/api/session-controller/tests/client-apply.client.spec.ts index 07f88b1a4f..b3fd854a68 100644 --- a/packages/api/session-controller/tests/client-apply.client.spec.ts +++ b/packages/api/session-controller/tests/client-apply.client.spec.ts @@ -106,6 +106,18 @@ async function flush(): Promise { } describe('Session Controller Client apply', () => { + it('installs ctx.jobOutput over the captured session namespace', async () => { + const bench = await mount() + expect(bench.ctx.jobOutput).toBeDefined() + // The fake observeJob never yields; opening and releasing must leave no + // view and no error behind. + const stop = bench.ctx.jobOutput.observe(sid('session-1'), 'bash-1' as never) + await flush() + stop() + await flush() + expect(bench.ctx.jobOutput.state.getSnapshot().observed).toEqual({}) + }) + it('routes Session Remote Events and connection generations into the object layer', async () => { const connected = vi.spyOn(ClientSessions.prototype, 'handleConnected') const error = vi.spyOn(ClientSessions.prototype, 'handleSessionError') diff --git a/snapshots/web/background-job-list/running.expected.md b/snapshots/web/background-job-list/running.expected.md index 95f226f226..811bddec3c 100644 --- a/snapshots/web/background-job-list/running.expected.md +++ b/snapshots/web/background-job-list/running.expected.md @@ -1,4 +1,4 @@ -- list "Tasks": +- list "Background jobs": - listitem: - button "Show live output of sleep 45": - text: sleep 45 {{duration}} bash running diff --git a/snapshots/web/background-job-list/settled.expected.md b/snapshots/web/background-job-list/settled.expected.md index 3343ae521c..44747d990d 100644 --- a/snapshots/web/background-job-list/settled.expected.md +++ b/snapshots/web/background-job-list/settled.expected.md @@ -1,4 +1,4 @@ -- list "Tasks": +- list "Background jobs": - listitem: - button "Show live output of sleep 45": - text: "bash sleep 45 signal: SIGTERM {{duration}}" From 1cec452f09a8fbe8f5a8c61cac39b257033ba9bc Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Tue, 1 Sep 2026 20:51:18 +0800 Subject: [PATCH 020/100] test(ci): close the observe-job coverage gaps Covers the woken-wait fast path (a wake landing while the generator is suspended on a yield), the opened frame's live-detail arm, and the sessionId-less caller resolution over an unowned job. --- .../tests/observe-job.host.spec.ts | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/packages/api/session-controller/tests/observe-job.host.spec.ts b/packages/api/session-controller/tests/observe-job.host.spec.ts index b61079d2b1..06a67848ec 100644 --- a/packages/api/session-controller/tests/observe-job.host.spec.ts +++ b/packages/api/session-controller/tests/observe-job.host.spec.ts @@ -54,6 +54,7 @@ function startRecordJob(ctx: Context, options: { label?: string; owner?: Agent; return { id, append: (text: string, opts?: Parameters[1]) => { face.append(text, opts) }, + updateDetail: (detail: string) => { face.updateDetail(detail) }, settle: async (outcome: JobOutcome) => { settle(outcome) await new Promise(resolve => setTimeout(resolve, 0)) @@ -224,6 +225,31 @@ describe('observeJobRecord', () => { await job.settle({ status: 'completed' }) }) + it('anchors with the live detail and takes the fast wait path for a wake that lands mid-yield', async () => { + const ctx = await harness() + const job = startRecordJob(ctx) + job.updateDetail('3/10') + const abort = new AbortController() + const iterator = observeJobRecord(ctx.jobs, { jobId: job.id }, { ...OBSERVE, caller: undefined }, abort.signal)[Symbol.asyncIterator]() + + const anchor = await iterator.next() + expect(anchor.value).toMatchObject({ type: 'opened', detail: '3/10' }) + // Both chunks land while the generator is suspended on a yield, so each + // wake precedes the loop's wait(): draining the first chunk must pass + // through the already-woken fast path to read the second. + job.append('woken') + const first = await iterator.next() + expect(first.value).toMatchObject({ type: 'output' }) + job.append('again') + const second = await iterator.next() + expect(second.value).toMatchObject({ type: 'output' }) + const pending = iterator.next() + await job.settle({ status: 'completed' }) + const status = await pending + expect(status.value).toMatchObject({ type: 'status', status: 'completed' }) + expect((await iterator.next()).done).toBe(true) + }) + it('ignores output signals for other jobs while waiting', async () => { const ctx = await harness() const watched = startRecordJob(ctx, { label: 'watched' }) @@ -295,4 +321,24 @@ describe('SessionController.observeJob', () => { ) expect(frames.map(frame => frame.type)).toEqual(['opened', 'output', 'status']) }) + + it('observes an unowned job without a request session', async () => { + const ctx = new Context() + await ctx.plugin(SessionStore) + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalJobRegistry) + ctx.jobs.attachController('observe-job-test') + const controller = createSessionTestController(ctx, defaults) + const job = startRecordJob(ctx, { label: 'unowned run' }) + job.append('open access') + await job.settle({ status: 'completed' }) + + const abort = new AbortController() + const frames = await collect( + controller.observeJob({ jobId: job.id }, abort.signal), + 3, + abort, + ) + expect(frames.map(frame => frame.type)).toEqual(['opened', 'output', 'status']) + }) }) From 7ec142a3258ef63f5c2b4253a347f9d4797610b6 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Wed, 2 Sep 2026 22:53:36 +0800 Subject: [PATCH 021/100] refactor(jobs): move job observation into api-job-controller Review asked for the observation wire and its client service to leave session-controller: a job should reach the Host only through its own Remote namespace, and the session plugin's apply had to materialize { $stream, session } for a service that is not session state. @deepseek-ai/dsh-api-job-controller now owns the Host JobController (job.observe over ctx.jobs, requiring the agent and job registries) and the client ClientJobOutput (ctx.jobOutput) over ClientJobOutputModel, resolving both Remote faces in its own apply. The remotes assembly mounts the job namespace; ui-jobs injects the new package; the wire types drop their Session prefix and spell the status union out so the client face pulls no Host declaration merges into browser programs. session-controller keeps the jobsBySession roster and loses observe-job, job-output, and the observe cadence config. ui-chat's slots and snapshot-builder import CommandNode and friends from the declaring package: the typert analyzer's cross-package rule trips on the snapshot re-export as soon as another client face joins the root Client program (the new controller does), which is why this branch carried the change before. JobPumpSource documents why it is an offset snapshot reader rather than a Node.js Readable. --- ...9-01-jobs-absorb-activity-record.i18n.yaml | 4 +- .../2026-09-01-jobs-absorb-activity-record.md | 4 +- ...26-09-01-jobs-absorb-activity-record.zh.md | 4 +- docs/capability-seams.i18n.yaml | 4 +- docs/capability-seams.md | 7 +- docs/capability-seams.zh.md | 7 +- docs/config-catalog.i18n.yaml | 4 +- docs/config-catalog.md | 24 +- docs/config-catalog.zh.md | 26 +- docs/event-producer-consumer.i18n.yaml | 4 +- docs/event-producer-consumer.md | 10 +- docs/event-producer-consumer.zh.md | 10 +- docs/module-graph.i18n.yaml | 4 +- docs/module-graph.md | 2 + docs/module-graph.zh.md | 2 + docs/subsystems/jobs.i18n.yaml | 4 +- docs/subsystems/jobs.md | 24 +- docs/subsystems/jobs.zh.md | 24 +- docs/subsystems/session.i18n.yaml | 4 +- docs/subsystems/session.md | 12 - docs/subsystems/session.zh.md | 12 - packages/api/README.i18n.yaml | 4 +- packages/api/README.md | 1 + packages/api/README.zh.md | 1 + packages/api/job-controller/README.i18n.yaml | 6 + packages/api/job-controller/README.md | 66 ++++ packages/api/job-controller/README.zh.md | 66 ++++ packages/api/job-controller/package.json | 86 +++++ .../api/job-controller/src/client/index.ts | 34 ++ .../api/job-controller/src/client/model.ts | 179 +++++++++ .../api/job-controller/src/client/service.ts | 179 +++++++++ packages/api/job-controller/src/index.ts | 86 +++++ .../src/observe.ts} | 14 +- packages/api/job-controller/src/types.ts | 75 ++++ .../tests/client-apply.client.spec.ts | 65 ++++ .../tests/model.client.spec.ts} | 13 +- .../tests/observe.host.spec.ts} | 66 ++-- .../api/job-controller/tsconfig.client.json | 23 ++ .../api/job-controller/tsconfig.host.json | 21 ++ packages/api/job-controller/tsconfig.json | 7 + packages/api/job-controller/tsdown.config.ts | 7 + packages/api/remotes/package.json | 11 +- packages/api/remotes/src/client/index.ts | 5 +- packages/api/remotes/tsconfig.client.json | 4 +- .../api/session-controller/README.i18n.yaml | 4 +- packages/api/session-controller/README.md | 4 +- packages/api/session-controller/README.zh.md | 4 +- .../session-controller/src/client/index.ts | 11 - .../src/client/job-output.ts | 348 ------------------ packages/api/session-controller/src/index.ts | 43 --- packages/api/session-controller/src/types.ts | 57 +-- .../tests/client-apply.client.spec.ts | 12 - .../tests/fake-api.client.ts | 5 +- .../session-controller/tests/test-remote.ts | 4 - .../api/session-controller/tsconfig.host.json | 101 +++-- packages/bundle/web-app/cordis.patch.yml | 5 + packages/bundle/web-app/package.json | 43 +-- .../ui-chat/src/client/contract/slots.ts | 7 +- .../chat-snapshot-builder.ts | 7 +- packages/client/ui-jobs/README.i18n.yaml | 4 +- packages/client/ui-jobs/README.md | 5 +- packages/client/ui-jobs/README.zh.md | 5 +- packages/client/ui-jobs/package.json | 2 + .../ui-jobs/src/client/JobListAction.tsx | 2 +- packages/client/ui-jobs/src/client/index.ts | 1 + .../tests/job-list-action.client.spec.tsx | 2 +- packages/client/ui-jobs/tsconfig.json | 3 + .../src/client/slot-catalog.ts | 12 +- .../extensions/tool-cordis/src/api-catalog.ts | 47 ++- packages/jobs/jobs/src/pump.ts | 14 +- pnpm-lock.yaml | 49 +++ scripts/gen-cordis-catalog.ts | 8 +- scripts/gen-doc-graphs.ts | 9 +- .../verify-package-readme-model-experience.ts | 1 + tsconfig.base.json | 3 + tsconfig.client.json | 1 + tsconfig.host.json | 1 + 77 files changed, 1339 insertions(+), 700 deletions(-) create mode 100644 packages/api/job-controller/README.i18n.yaml create mode 100644 packages/api/job-controller/README.md create mode 100644 packages/api/job-controller/README.zh.md create mode 100644 packages/api/job-controller/package.json create mode 100644 packages/api/job-controller/src/client/index.ts create mode 100644 packages/api/job-controller/src/client/model.ts create mode 100644 packages/api/job-controller/src/client/service.ts create mode 100644 packages/api/job-controller/src/index.ts rename packages/api/{session-controller/src/observe-job.ts => job-controller/src/observe.ts} (94%) create mode 100644 packages/api/job-controller/src/types.ts create mode 100644 packages/api/job-controller/tests/client-apply.client.spec.ts rename packages/api/{session-controller/tests/job-output.client.spec.ts => job-controller/tests/model.client.spec.ts} (98%) rename packages/api/{session-controller/tests/observe-job.host.spec.ts => job-controller/tests/observe.host.spec.ts} (89%) create mode 100644 packages/api/job-controller/tsconfig.client.json create mode 100644 packages/api/job-controller/tsconfig.host.json create mode 100644 packages/api/job-controller/tsconfig.json create mode 100644 packages/api/job-controller/tsdown.config.ts delete mode 100644 packages/api/session-controller/src/client/job-output.ts diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml index 87e45ad40a..3a332e7121 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.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 .agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md -2026-09-01-jobs-absorb-activity-record.md: cc2cc8606a50e2d7c06e183a09df709b75b9bd35 -2026-09-01-jobs-absorb-activity-record.zh.md: 8b6739192b56899899773ba1e7af2bf1bd846b0b +2026-09-01-jobs-absorb-activity-record.md: aa147778d06133b61f79defae6f9f6807dd97f41 +2026-09-01-jobs-absorb-activity-record.zh.md: 12e8f4bbd909a480f1461433c58d7937a8d7c857 diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md index cc2cc8606a..aa147778d0 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md @@ -18,7 +18,7 @@ The one activity without a job was the foreground workflow mirror. Everything el - **There is no `end`.** Job settlement — the producer outcome, a kill, or teardown — is the record's only close: it trims retention to the settled cap and fires the final `onOutput` signal. The dual-settlement pairing (`ActivityHandle.end` first-wins against teardown force-ends) is deleted, not reimplemented. - **`readRecord(id, from, caller)`** is the non-consuming multi-reader view (absolute UTF-8 offsets, `lossy` below the retained window), fenced like every other job read; it never marks the job `reported`. The model-facing `readOutput` cursor is untouched — the two projections serve different readers and stay separate by design. - **`jobs-local`** absorbs the chunk ring (`retainBytes` 256 KiB live, `settledRetainBytes` 16 KiB settled), and `pumpJobOutput` replaces `pumpActivityOutput` beside the seam. Producers fold the pump's final drain into `hooks.done` so the record holds its last bytes before settlement closes it. -- **The wire moves to the session namespace.** `SessionJob.outputTotal` (present exactly for record jobs) marks a row observable; `session.observeJob({sessionId?, jobId, from?})` streams anchor/output/status frames with the fenced read resolved from the request's session — the killJob authorization shape. `api-activity-controller` is deleted; its roster stream is redundant (the jobs frames are the roster) and its observe machinery moved into `session-controller` (`observe-job.ts`, client `ctx.jobOutput`). +- **The wire splits by role.** `SessionJob.outputTotal` (present exactly for record jobs) marks a row observable on the session control stream; `job.observe({sessionId?, jobId, from?})` on the `job` namespace of `api-job-controller` streams anchor/output/status frames with the fenced read resolved from the request's session. `api-activity-controller` is deleted; its roster stream is redundant (the jobs frames are the roster) and its observe machinery lives in `api-job-controller` (`observe.ts`, client `ctx.jobOutput`), which resolves its Remote faces in its own apply. - **`ui-activity` returns to its upstream name `ui-jobs`** and renders one roster: `jobsBySession` rows, expandable exactly when `outputTotal` is present. The two-roster join is deleted. - **Foreground workflow loses its live panel deliberately.** `tool-workflow`'s activity mirror is removed; a foreground run surfaces through its recorded run/member lifecycle events only, and the per-line `workflow/phase` / `workflow/log` narration has no observer until workflow gains `run_in_background` and registers a record job. Jobs stay a pure background registry — no `foreground` mode bit, no model-invisible rows, no run-less rows. @@ -32,4 +32,4 @@ The [prior seam note](../feature/2026-08-24-activity-observation-seam.md)'s argu ## Consequences -Every observable row is a killable job; a pure-observation surface with no lifecycle would need a new home (harness diagnostics belong to the inspector plane, not here). A future remote job provider must implement lifecycle and record together. The record's retention config lives on `jobs-local`; the observation wire's cadence config (`observeFlushMs`, `observeMaxFrameBytes`) lives on `session-controller`. +Every observable row is a killable job; a pure-observation surface with no lifecycle would need a new home (harness diagnostics belong to the inspector plane, not here). A future remote job provider must implement lifecycle and record together. The record's retention config lives on `jobs-local`; the observation wire's cadence config (`observeFlushMs`, `observeMaxFrameBytes`) lives on `api-job-controller`. diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md index 8b6739192b..12e8f4bbd9 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md @@ -18,7 +18,7 @@ Status: implemented - **没有 `end`。** job 结算——生产者 outcome、kill 或 teardown——是 record 唯一的关闭:裁剪到结算保留量并发出最后一个 `onOutput` 信号。双结算配对(`ActivityHandle.end` 与 teardown 强结的 first-wins 对账)被删除,而非重新实现。 - **`readRecord(id, from, caller)`** 是非消耗多读者视图(绝对 UTF-8 偏移,低于保留窗口为 `lossy`),围栏与其他 job 读取一致;永不置 `reported`。模型面的 `readOutput` 游标原样保留——两个投影服务不同读者,刻意保持分离。 - **`jobs-local`** 吸收块环(`retainBytes` 运行期 256 KiB,`settledRetainBytes` 结算后 16 KiB),`pumpJobOutput` 在 seam 旁替换 `pumpActivityOutput`。生产者把 pump 的末次排空折进 `hooks.done`,让 record 在结算关闭前握有最后的字节。 -- **wire 移入 session 命名空间。** `SessionJob.outputTotal`(恰在 record job 上存在)标记行可观测;`session.observeJob({sessionId?, jobId, from?})` 流式发送 anchor/output/status 帧,围栏读取者由请求的 session 解析——与 killJob 相同的授权形态。`api-activity-controller` 删除;其名册流是冗余的(jobs 帧就是名册),observe 机制移入 `session-controller`(`observe-job.ts`,客户端 `ctx.jobOutput`)。 +- **wire 按角色拆分。** `SessionJob.outputTotal`(恰在 record job 上存在)在会话控制流上标记行可观测;`api-job-controller` 的 `job` 命名空间上的 `job.observe({sessionId?, jobId, from?})` 流式发送 anchor/output/status 帧,围栏读取者由请求的 session 解析。`api-activity-controller` 删除;其名册流是冗余的(jobs 帧就是名册),observe 机制位于 `api-job-controller`(`observe.ts`,客户端 `ctx.jobOutput`),它在自己的 apply 里解析所依赖的 Remote 面。 - **`ui-activity` 改回上游名字 `ui-jobs`**,渲染单一名册:`jobsBySession` 行,恰在 `outputTotal` 存在时可展开。双名册 join 被删除。 - **前台 workflow 有意失去实时面板。** `tool-workflow` 的 activity 镜像被移除;前台 run 只通过已记录的 run/member 生命周期事件呈现,逐行的 `workflow/phase` / `workflow/log` 叙述在 workflow 获得 `run_in_background` 并登记 record job 之前没有观察者。jobs 保持纯后台注册表——没有 `foreground` 模式位、没有模型不可见行、没有无 run 行。 @@ -32,4 +32,4 @@ Status: implemented ## 后果 -每个可观测行都是可 kill 的 job;没有生命周期的纯观测面需要新的归属(harness 诊断属于 inspector 平面,不在这里)。未来的远端 job provider 必须同时实现生命周期与 record。record 的保留配置在 `jobs-local`;观测 wire 的节奏配置(`observeFlushMs`、`observeMaxFrameBytes`)在 `session-controller`。 +每个可观测行都是可 kill 的 job;没有生命周期的纯观测面需要新的归属(harness 诊断属于 inspector 平面,不在这里)。未来的远端 job provider 必须同时实现生命周期与 record。record 的保留配置在 `jobs-local`;观测 wire 的节奏配置(`observeFlushMs`、`observeMaxFrameBytes`)在 `api-job-controller`。 diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml index 0f57f09f95..902b8a63bf 100644 --- a/docs/capability-seams.i18n.yaml +++ b/docs/capability-seams.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 docs/capability-seams.md -capability-seams.md: 635ef1defb7acabf78d94b28c6bef66a43f518b3 -capability-seams.zh.md: 21619c9d20f66edee269a1599ced6f4d4f55df38 +capability-seams.md: 30b3a2f8fdbb66410ada6ab27551d6018a1ac8eb +capability-seams.zh.md: 834131588213627cefd4a6ea9c69d67f5d345ba7 diff --git a/docs/capability-seams.md b/docs/capability-seams.md index 635ef1defb..30b3a2f8fd 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -39,6 +39,8 @@ flowchart LR svc_sessionController["ctx.sessionController
        Host Session Remote controller"] svc_sessionFileReferences["ctx.sessionFileReferences
        Session-addressed file-reference Remote adapter"] svc_sessionSkillCatalog["ctx.sessionSkillCatalog
        Session-addressed skill Remote adapter"] + pkg_api_job_controller["api-job-controller"] + svc_jobController["ctx.jobController
        Host job Remote controller"] pkg_api_settings_controller["api-settings-controller"] svc_credentialsController["ctx.credentialsController
        Host credential-surface Remote controller"] svc_settingsController["ctx.settingsController
        Host settings-surface Remote controller"] @@ -223,6 +225,7 @@ flowchart LR pkg_agent_loop --> svc_agentLoop pkg_agent_presets --> svc_agentPresets pkg_api_gateway --> svc_typertGateway + pkg_api_job_controller --> svc_jobController pkg_api_session_controller --> svc_sessionController pkg_api_session_controller --> svc_sessionFileReferences pkg_api_session_controller --> svc_sessionSkillCatalog @@ -369,6 +372,7 @@ flowchart LR svc_invariants --> pkg_agent_loop svc_invariants --> pkg_scope svc_invariants --> pkg_session + svc_jobs --> pkg_api_job_controller svc_jobs --> pkg_tool_bash svc_jobs --> pkg_tool_jobs svc_jobs --> pkg_tool_pwsh @@ -475,6 +479,7 @@ flowchart LR | `ctx.sessionController` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | Owns Session commands, cold reads, durable-event following, live control state, model catalogs, workspace opening, and Agent activation policy. | | `ctx.sessionFileReferences` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | Delegates file-reference discovery through the Session Controller's established Agent lookup policy. | | `ctx.sessionSkillCatalog` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | Lists the Session composition's user-invocable skills without activating a cold Agent. | +| `ctx.jobController` | `core` | [`api-job-controller`](../packages/api/job-controller) | - | - | - | Streams one background job's observation record over the generated Remote namespace; the roster stays on the session control stream. | | `ctx.credentialsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | Projects the credential-reference seam onto the generated Remote namespace: batch fan-out, view projection, and refusal mapping live here, not on the seam Definition. | | `ctx.settingsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | Projects the user-settings seam onto the generated Remote namespace: the read is always redacted and every refusal is classified here, not on the seam Definition. | | `ctx.workspaceController` | `core` | [`api-workspace-controller`](../packages/api/workspace-controller) | - | - | - | Owns Workspace commands and reconnect-safe Workspace state delivery through the generated Remote namespace. | @@ -524,7 +529,7 @@ flowchart LR | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process), [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. | | `ctx.agentTeams` | `core` | [`experimental-agent-team`](../packages/experimental/agent-team) | - | [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team), [`experimental-client-ui-agent-team`](../packages/experimental/client-ui-agent-team) | - | Owns the implicit-root roster, durable peer mailbox, shared task DAG, continuable-child lifecycle, and generated Team Remote methods; tool-agent-team contributes model controls and client-ui-agent-team mounts the browser contribution. | | `ctx.inspector` | `core` | `inspector` | - | - | - | Owns the Worker-hosted CDP target and the transport-independent Host and Client observation and Cordis-tree query API. | -| `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs) | - | Producers (background bash/pwsh, PTY sends, and subagent delegations) register running work; record-declaring jobs additionally stream raw output for non-consuming observers; tool-jobs is the model-facing controller that reads, lists, and kills it; jobs-local is the process-local registry. | +| `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs), [`api-job-controller`](../packages/api/job-controller) | - | Producers (background bash/pwsh, PTY sends, and subagent delegations) register running work; record-declaring jobs additionally stream raw output for non-consuming observers; tool-jobs is the model-facing controller that reads, lists, and kills it; jobs-local is the process-local registry. | | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-http`](../packages/web/web-fetch-http) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. | | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | The backend saves oversized tool text and returns a model-facing locator plus retrieval hint; spill-policy is the tools/post-execute consumer that decides when to spill. | | `ctx.directoryPicker` | `seam` | [`host-directory-picker`](../packages/host/directory-picker) | [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | [`api-workspace-controller`](../packages/api/workspace-controller) | - | Discriminated interaction capability: the native backend opens one OS chooser on the host display, the browse backend serves listing/creation primitives for the in-app browser; dual-face backends fill ui-workspace directory-flow slots from their browser halves (no wire advertisement). | diff --git a/docs/capability-seams.zh.md b/docs/capability-seams.zh.md index 21619c9d20..8341315882 100644 --- a/docs/capability-seams.zh.md +++ b/docs/capability-seams.zh.md @@ -41,6 +41,8 @@ flowchart LR svc_sessionController["ctx.sessionController
        Host Session Remote controller"] svc_sessionFileReferences["ctx.sessionFileReferences
        Session-addressed file-reference Remote adapter"] svc_sessionSkillCatalog["ctx.sessionSkillCatalog
        Session-addressed skill Remote adapter"] + pkg_api_job_controller["api-job-controller"] + svc_jobController["ctx.jobController
        Host job Remote controller"] pkg_api_settings_controller["api-settings-controller"] svc_credentialsController["ctx.credentialsController
        Host credential-surface Remote controller"] svc_settingsController["ctx.settingsController
        Host settings-surface Remote controller"] @@ -225,6 +227,7 @@ flowchart LR pkg_agent_loop --> svc_agentLoop pkg_agent_presets --> svc_agentPresets pkg_api_gateway --> svc_typertGateway + pkg_api_job_controller --> svc_jobController pkg_api_session_controller --> svc_sessionController pkg_api_session_controller --> svc_sessionFileReferences pkg_api_session_controller --> svc_sessionSkillCatalog @@ -371,6 +374,7 @@ flowchart LR svc_invariants --> pkg_agent_loop svc_invariants --> pkg_scope svc_invariants --> pkg_session + svc_jobs --> pkg_api_job_controller svc_jobs --> pkg_tool_bash svc_jobs --> pkg_tool_jobs svc_jobs --> pkg_tool_pwsh @@ -477,6 +481,7 @@ flowchart LR | `ctx.sessionController` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | 负责 Session 命令、冷读取、持久事件跟随、实时控制状态、模型目录、workspace 打开与 Agent 激活策略。 | | `ctx.sessionFileReferences` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | 通过 Session Controller 的既有 Agent lookup 策略委托文件引用发现。 | | `ctx.sessionSkillCatalog` | `core` | [`api-session-controller`](../packages/api/session-controller) | - | - | - | 在不激活冷 Agent 的前提下列出 Session 组合中允许用户调用的 skill。 | +| `ctx.jobController` | `core` | [`api-job-controller`](../packages/api/job-controller) | - | - | - | 经生成的 Remote namespace 流式发送一个后台任务的观测 record;名册仍在会话控制流上。 | | `ctx.credentialsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | 把凭据引用 seam 投影到生成的 Remote namespace:批量扇出、视图投影与拒绝映射都在这里,而不在 seam Definition 上。 | | `ctx.settingsController` | `core` | [`api-settings-controller`](../packages/api/settings-controller) | - | - | - | 把用户设置 seam 投影到生成的 Remote namespace:读取一律脱敏,所有拒绝在这里分类,而不在 seam Definition 上。 | | `ctx.workspaceController` | `core` | [`api-workspace-controller`](../packages/api/workspace-controller) | - | - | - | 通过生成的 Remote namespace 负责 Workspace 命令和可在重连后收敛的 Workspace 状态投递。 | @@ -526,7 +531,7 @@ flowchart LR | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process), [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | 提供方实现传输;该服务还负责可选的、基于 Activation 的延续编排,tool-subagent 选择一次性或可延续委派,tool-subagent-control 传递后续消息,而 tool-ralph 要求一条全新的结构化输出路由。 | | `ctx.agentTeams` | `core` | [`experimental-agent-team`](../packages/experimental/agent-team) | - | [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team), [`experimental-client-ui-agent-team`](../packages/experimental/client-ui-agent-team) | - | 负责隐式 Root roster、持久 peer mailbox、共享任务 DAG、continuable child 生命周期与生成式 Team Remote method;tool-agent-team 提供模型控制工具,client-ui-agent-team 挂载浏览器 contribution。 | | `ctx.inspector` | `core` | `inspector` | - | - | - | 负责 Worker 托管的 CDP target,以及独立于传输的 Host 和 Client observation 与 Cordis tree query API。 | -| `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs) | - | 生产方(后台 bash/pwsh、PTY 发送和 subagent 委派)登记正在运行的工作;声明 record 的 job 还为非消费观察者流式提供原始输出;tool-jobs 是面向模型的控制器,用于读取、列出和终止这些工作;jobs-local 是进程本地注册表。 | +| `ctx.jobs` | `seam` | [`jobs`](../packages/jobs/jobs) | [`jobs-local`](../packages/jobs/jobs-local) | [`tool-bash`](../packages/shell/tool-bash), [`tool-pwsh`](../packages/shell/tool-pwsh), [`tool-terminal`](../packages/terminal/tool-terminal), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-jobs`](../packages/jobs/tool-jobs), [`api-job-controller`](../packages/api/job-controller) | - | 生产方(后台 bash/pwsh、PTY 发送和 subagent 委派)登记正在运行的工作;声明 record 的 job 还为非消费观察者流式提供原始输出;tool-jobs 是面向模型的控制器,用于读取、列出和终止这些工作;jobs-local 是进程本地注册表。 | | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-http`](../packages/web/web-fetch-http) | [`tool-web`](../packages/web/tool-web) | - | 搜索和抓取提供方注册到同一个 ctx.web seam;tool-web 负责稳定的面向模型名称。 | | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | 后端保存过大的工具文本,并返回面向模型的定位信息和取回提示;spill-policy 是 tools/post-execute 消费方,负责决定何时 spill。 | | `ctx.directoryPicker` | `seam` | [`host-directory-picker`](../packages/host/directory-picker) | [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-directory-picker-browse`](../packages/host/directory-picker-browse) | [`api-workspace-controller`](../packages/api/workspace-controller) | - | 带判别标记的交互能力:原生后端在 Host 显示设备上打开一个操作系统选择器,浏览后端为应用内浏览器提供列表与创建原语;双端后端通过其浏览器侧填充 ui-workspace 目录流程的 slot(不通过协议发布)。 | diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index c065e16e00..102b6810cd 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.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 docs/config-catalog.md -config-catalog.md: 2c8043732edb0d47e5eaffd02f95e4293060a4dd -config-catalog.zh.md: 24c077ca51e64a4f6235170726a909be9e0e5207 +config-catalog.md: 36eb0f1e9385b9ddc4a09a9476d3b483075282ba +config-catalog.zh.md: 90e94c3e739dd854c1a4243297d1e5aef557f828 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 2c8043732e..36eb0f1e93 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -199,6 +199,24 @@ export interface Config { Source: [`packages/api/gateway/src/index.ts:119`](../packages/api/gateway/src/index.ts) + + +## `@deepseek-ai/dsh-api-job-controller` + +Requires: `agents` · `jobs` · `typert` + +```ts config-catalog +/** Job Controller deployment policy. */ +export interface Config { + /** Coalescing window after new record output before an observation read, in milliseconds (default 100). */ + readonly observeFlushMs?: number + /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */ + readonly observeMaxFrameBytes?: number +} +``` + +Source: [`packages/api/job-controller/src/index.ts:33`](../packages/api/job-controller/src/index.ts) + ## `@deepseek-ai/dsh-api-session-controller` @@ -214,14 +232,10 @@ export interface Config { readonly coldBlankProbeMaxBytes?: number /** Override platform desktop-opener detection. */ readonly nativeOpen?: boolean - /** Coalescing window after new record output before a job-observation read, in milliseconds (default 100). */ - readonly observeFlushMs?: number - /** Soft byte budget per job-observation output frame (default 65536); one larger chunk ships whole. */ - readonly observeMaxFrameBytes?: number } ``` -Source: [`packages/api/session-controller/src/index.ts:82`](../packages/api/session-controller/src/index.ts) +Source: [`packages/api/session-controller/src/index.ts:72`](../packages/api/session-controller/src/index.ts) diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index 24c077ca51..90e94c3e73 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -201,6 +201,26 @@ export interface Config { 来源:[`packages/api/gateway/src/index.ts:119`](../packages/api/gateway/src/index.ts) + + +## `@deepseek-ai/dsh-api-job-controller` + +需要:`agents` · `jobs` · `typert` + +```ts config-catalog +/** Job Controller deployment policy. */ +export interface Config { + /** Coalescing window after new record output before an observation read, in milliseconds (default 100). */ + readonly observeFlushMs?: number + /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */ + readonly observeMaxFrameBytes?: number +} +``` + +来源:[`packages/api/job-controller/src/index.ts:33`](../packages/api/job-controller/src/index.ts) + + + ## `@deepseek-ai/dsh-api-session-controller` @@ -216,14 +236,10 @@ export interface Config { readonly coldBlankProbeMaxBytes?: number /** Override platform desktop-opener detection. */ readonly nativeOpen?: boolean - /** Coalescing window after new record output before a job-observation read, in milliseconds (default 100). */ - readonly observeFlushMs?: number - /** Soft byte budget per job-observation output frame (default 65536); one larger chunk ships whole. */ - readonly observeMaxFrameBytes?: number } ``` -来源:[`packages/api/session-controller/src/index.ts:82`](../packages/api/session-controller/src/index.ts) +来源:[`packages/api/session-controller/src/index.ts:72`](../packages/api/session-controller/src/index.ts) diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml index 1efb0f757c..8a378b23f1 100644 --- a/docs/event-producer-consumer.i18n.yaml +++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md -event-producer-consumer.md: 26096b99ef32702b85a622fa0342f215bb90ddf9 -event-producer-consumer.zh.md: 3e224d7a192e1c8c361fe2c7ad88b2d817bfbb1e +event-producer-consumer.md: 930ffba24789ee51db110310cb17a2231135cf1d +event-producer-consumer.zh.md: 6583b1d9f333ad934db2123a2bc5c40b12f1ae36 diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 26096b99ef..930ffba247 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -21,11 +21,11 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:224`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:185`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` | | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:285`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:605`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:585`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:612`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:591`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:598`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:550`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:530`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:557`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:536`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:543`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` | | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:81`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md index 3e224d7a19..6583b1d9f3 100644 --- a/docs/event-producer-consumer.zh.md +++ b/docs/event-producer-consumer.zh.md @@ -23,11 +23,11 @@ | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:224`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:185`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` | | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:285`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:605`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:585`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:612`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:591`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:598`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:550`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:530`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:557`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:536`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:543`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` | | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:81`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml index 7a1a91a45a..64db381cab 100644 --- a/docs/module-graph.i18n.yaml +++ b/docs/module-graph.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 docs/module-graph.md -module-graph.md: 514d09c5883ec8196e0706fbd7a3ccf45b8aafb5 -module-graph.zh.md: 444100e17ce6794efa39ef2e0a10872a6e1c3484 +module-graph.md: e280a648b8550d34b129f05971ebd0547690f117 +module-graph.zh.md: b068b7216481fb86873c290d31e6d76ce85e3fbd diff --git a/docs/module-graph.md b/docs/module-graph.md index 514d09c588..e280a648b8 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -108,6 +108,7 @@ flowchart TD end subgraph group_api["packages/api"] pkg_api_gateway["api-gateway"] + pkg_api_job_controller["api-job-controller"] pkg_api_remotes["api-remotes"] pkg_api_session_controller["api-session-controller"] pkg_api_settings_controller["api-settings-controller"] @@ -1153,6 +1154,7 @@ flowchart TD | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions) | `llm` | — | | [`llm`](../packages/llm/llm) | `llm` | — | | [`api-gateway`](../packages/api/gateway) | `api` | — | +| [`api-job-controller`](../packages/api/job-controller) | `api` | — | | [`cmdline`](../packages/boot/cmdline) | `boot` | — | | [`acp-app`](../packages/bundle/acp-app) | `bundle` | — | | [`base`](../packages/bundle/base) | `bundle` | — | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index 444100e17c..b068b72164 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -110,6 +110,7 @@ flowchart TD end subgraph group_api["packages/api"] pkg_api_gateway["api-gateway"] + pkg_api_job_controller["api-job-controller"] pkg_api_remotes["api-remotes"] pkg_api_session_controller["api-session-controller"] pkg_api_settings_controller["api-settings-controller"] @@ -1155,6 +1156,7 @@ flowchart TD | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions) | `llm` | — | | [`llm`](../packages/llm/llm) | `llm` | — | | [`api-gateway`](../packages/api/gateway) | `api` | — | +| [`api-job-controller`](../packages/api/job-controller) | `api` | — | | [`cmdline`](../packages/boot/cmdline) | `boot` | — | | [`acp-app`](../packages/bundle/acp-app) | `bundle` | — | | [`base`](../packages/bundle/base) | `bundle` | — | diff --git a/docs/subsystems/jobs.i18n.yaml b/docs/subsystems/jobs.i18n.yaml index 370043fe58..022befcbd2 100644 --- a/docs/subsystems/jobs.i18n.yaml +++ b/docs/subsystems/jobs.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 docs/subsystems/jobs.md -jobs.md: 1b8e58f27be9e7198063960d436e61502c4f7e3b -jobs.zh.md: 0a1d04fcaf0ea0ceadcb457c756f0962e47eca34 +jobs.md: 0610d99892da22a25590ab7efe8ff71d9a004f01 +jobs.zh.md: 4c35fd7c879ddf7133c0db55df24948b40118b9d diff --git a/docs/subsystems/jobs.md b/docs/subsystems/jobs.md index 1b8e58f27b..0610d99892 100644 --- a/docs/subsystems/jobs.md +++ b/docs/subsystems/jobs.md @@ -113,7 +113,7 @@ interface JobOutcome { ## Observation record -A producer that declares `record: true` streams raw output into a bounded per-job ring through the `RunningJob` face its starter receives; any number of observers read retained chunks at absolute byte offsets through `readRecord` without touching the consuming model cursor or notice state. Job settlement ends the stream and trims retention to the settled cap — the record has no separate lifecycle. `pumpJobOutput` copies producer offset-readers (the subprocess `readFrom` family) into the record at a bounded cadence. +A producer that declares `record: true` streams raw output into a bounded per-job ring through the `RunningJob` face its starter receives; any number of observers read retained chunks at absolute byte offsets through `readRecord` without touching the consuming model cursor or notice state. Job settlement ends the stream and trims retention to the settled cap — the record has no separate lifecycle. `pumpJobOutput` copies producer offset-readers (the subprocess `readFrom` family) into the record at a bounded cadence. Browsers reach the record through `job.observe`, the Remote stream of [`dsh-api-job-controller`](../../packages/api/job-controller/README.md), whose frames are listed under its Cordis API section below. ```ts type-equiv /** @@ -258,6 +258,28 @@ The abstract [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Defi Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md). + + +### `ctx.jobController` — `JobController` + +Host service backing the generated `ctx.remote.job` namespace. + +```ts cordis-catalog +/** + * Stream one job's retained record output from an absolute byte offset, + * then its terminal status once settled and drained. Non-consuming: the + * model-facing cursor and notice state never observe these reads. The + * request's session resolves the fenced-read caller; the registry rejects a + * job the session does not own, a job without a record, or an unknown job. + * @param request - target job, owning session, and optional resume offset. + * @param signal - cancellation owned by the Remote stream carrier. + * @returns anchor, coalesced output frames, and the terminal status. + */ +@Remote({ mode: 'stream' }) observe(request: JobObserveRequest, signal: AbortSignal): AsyncIterable +``` + +Source: [`packages/api/job-controller/src/index.ts`](../../packages/api/job-controller/src/index.ts) + ### `ctx.jobs` — `JobRegistry` (abstract seam) diff --git a/docs/subsystems/jobs.zh.md b/docs/subsystems/jobs.zh.md index 0a1d04fcaf..4c35fd7c87 100644 --- a/docs/subsystems/jobs.zh.md +++ b/docs/subsystems/jobs.zh.md @@ -113,7 +113,7 @@ interface JobOutcome { ## 观测 record -声明 `record: true` 的生产方通过 starter 收到的 `RunningJob` 面把原始输出流入按 job 划分的有界环形缓冲;任意数量的观察者通过 `readRecord` 按绝对字节偏移读取保留块,不触碰消耗型的模型游标与通知状态。job 结算即封流并把保留量裁剪到结算上限——record 没有独立生命周期。`pumpJobOutput` 以有界节奏把生产方的偏移读取器(subprocess 的 `readFrom` 家族)复制进 record。 +声明 `record: true` 的生产方通过 starter 收到的 `RunningJob` 面把原始输出流入按 job 划分的有界环形缓冲;任意数量的观察者通过 `readRecord` 按绝对字节偏移读取保留块,不触碰消耗型的模型游标与通知状态。job 结算即封流并把保留量裁剪到结算上限——record 没有独立生命周期。`pumpJobOutput` 以有界节奏把生产方的偏移读取器(subprocess 的 `readFrom` 家族)复制进 record。浏览器经 [`dsh-api-job-controller`](../../packages/api/job-controller/README.zh.md) 的 Remote 流 `job.observe` 读取 record,其帧类型列在下方该控制器的 Cordis API 一节。 ```ts type-equiv /** @@ -258,6 +258,28 @@ interface JobRead { Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md). + + +### `ctx.jobController` — `JobController` + +Host service backing the generated `ctx.remote.job` namespace. + +```ts cordis-catalog +/** + * Stream one job's retained record output from an absolute byte offset, + * then its terminal status once settled and drained. Non-consuming: the + * model-facing cursor and notice state never observe these reads. The + * request's session resolves the fenced-read caller; the registry rejects a + * job the session does not own, a job without a record, or an unknown job. + * @param request - target job, owning session, and optional resume offset. + * @param signal - cancellation owned by the Remote stream carrier. + * @returns anchor, coalesced output frames, and the terminal status. + */ +@Remote({ mode: 'stream' }) observe(request: JobObserveRequest, signal: AbortSignal): AsyncIterable +``` + +Source: [`packages/api/job-controller/src/index.ts`](../../packages/api/job-controller/src/index.ts) + ### `ctx.jobs` — `JobRegistry` (abstract seam) diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml index 3a2bd2ec51..f9653cecea 100644 --- a/docs/subsystems/session.i18n.yaml +++ b/docs/subsystems/session.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 docs/subsystems/session.md -session.md: 36c15ffd5244da732dea003259d476c0d1812d89 -session.zh.md: b31fd6593cb9d72c6577ee7a94c02d6dd04994e4 +session.md: 48a80ccb92af774db2f5bedea8e2e00043932d31 +session.zh.md: df5cfd631a15bfe015c766842956cc0c344c2ccd diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md index 36c15ffd52..48a80ccb92 100644 --- a/docs/subsystems/session.md +++ b/docs/subsystems/session.md @@ -800,18 +800,6 @@ inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise - -/** - * Stream one job's retained record output from an absolute byte offset, - * then its terminal status once settled and drained. Non-consuming: the - * model-facing cursor and notice state never observe these reads. The - * request's session resolves the fenced-read caller; the registry rejects a - * job the session does not own, a job without a record, or an unknown job. - * @param request - target job, owning session, and optional resume offset. - * @param signal - cancellation owned by the Remote stream carrier. - * @returns anchor, coalesced output frames, and the terminal status. - */ -@Remote({ mode: 'stream' }) observeJob(request: SessionObserveJobRequest, signal: AbortSignal): AsyncIterable ``` Types: [SessionId](core.md) · [SessionInspection](persistence.md) · [SessionSearchRequest](session-query.md) diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md index b31fd6593c..df5cfd631a 100644 --- a/docs/subsystems/session.zh.md +++ b/docs/subsystems/session.zh.md @@ -804,18 +804,6 @@ inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise - -/** - * Stream one job's retained record output from an absolute byte offset, - * then its terminal status once settled and drained. Non-consuming: the - * model-facing cursor and notice state never observe these reads. The - * request's session resolves the fenced-read caller; the registry rejects a - * job the session does not own, a job without a record, or an unknown job. - * @param request - target job, owning session, and optional resume offset. - * @param signal - cancellation owned by the Remote stream carrier. - * @returns anchor, coalesced output frames, and the terminal status. - */ -@Remote({ mode: 'stream' }) observeJob(request: SessionObserveJobRequest, signal: AbortSignal): AsyncIterable ``` Types: [SessionId](core.zh.md) · [SessionInspection](persistence.zh.md) · [SessionSearchRequest](session-query.zh.md) diff --git a/packages/api/README.i18n.yaml b/packages/api/README.i18n.yaml index c47c67f406..d40b9dfa53 100644 --- a/packages/api/README.i18n.yaml +++ b/packages/api/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/api/README.md -README.md: b4d8ddd84baa411a2675c95dda1701937e06fe6d -README.zh.md: 5dff7a59219a539c75d7ab85d293cd5b389018ec +README.md: ad89535e8d482e7a50868cd97e0af50ebda62e4b +README.zh.md: 7e1957967aadcd93df5e1bb7f6db45cb4636c750 diff --git a/packages/api/README.md b/packages/api/README.md index b4d8ddd84b..ad89535e8d 100644 --- a/packages/api/README.md +++ b/packages/api/README.md @@ -28,6 +28,7 @@ The packages below provide the Remote layer; the package READMEs own the exhaust |---|---|---| | [`remotes/`](remotes/README.md) | Chooses which Host capabilities and events the Client can consume. | — | | [`gateway/`](gateway/README.md) | Carries typed unary calls, multiplexed streams, and forwarded Host events. | `ctx.typertGateway` / `ctx.remote` | +| [`job-controller/`](job-controller/README.md) | Streams one background job's observation record to the Client. | `ctx.jobController` / `ctx.remote.job` | | [`session-controller/`](session-controller/README.md) | Owns Session commands, history streams, live control state, and Agent/Session identity policy. | `ctx.sessionController` / `ctx.remote.session` | | [`settings-controller/`](settings-controller/README.md) | Owns the configuration-surface reads and writes over the settings-domain seams. | `ctx.settingsController`, `ctx.credentialsController` / `ctx.remote.settings`, `ctx.remote.credentials` | | [`workspace-controller/`](workspace-controller/README.md) | Owns Workspace mutations and the complete Client Workspace projection. | `ctx.workspaceController` / `ctx.remote.workspace` | diff --git a/packages/api/README.zh.md b/packages/api/README.zh.md index 5dff7a5921..7e1957967a 100644 --- a/packages/api/README.zh.md +++ b/packages/api/README.zh.md @@ -28,6 +28,7 @@ kind: "package-group" |---|---|---| | [`remotes/`](remotes/README.zh.md) | 决定 Client 可以消费哪些 Host 能力与事件。 | — | | [`gateway/`](gateway/README.zh.md) | 承载带类型的单次调用、多路复用 stream 与转发的 Host 事件。 | `ctx.typertGateway` / `ctx.remote` | +| [`job-controller/`](job-controller/README.zh.md) | 把一个后台任务的观测 record 流式送到 Client。 | `ctx.jobController` / `ctx.remote.job` | | [`session-controller/`](session-controller/README.zh.md) | 拥有 Session 命令、历史 stream、实时控制状态与 Agent/Session 身份策略。 | `ctx.sessionController` / `ctx.remote.session` | | [`settings-controller/`](settings-controller/README.zh.md) | 拥有 settings 域各 seam 之上的配置界面读写。 | `ctx.settingsController`、`ctx.credentialsController` / `ctx.remote.settings`、`ctx.remote.credentials` | | [`workspace-controller/`](workspace-controller/README.zh.md) | 拥有 Workspace 变更与完整 Client Workspace 投影。 | `ctx.workspaceController` / `ctx.remote.workspace` | diff --git a/packages/api/job-controller/README.i18n.yaml b/packages/api/job-controller/README.i18n.yaml new file mode 100644 index 0000000000..9bef50c478 --- /dev/null +++ b/packages/api/job-controller/README.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 packages/api/job-controller/README.md +README.md: 1af9cac6574b36fb9ee0fe2bd4ff4a529848c2fe +README.zh.md: a232d8e8655fea6ccddedb60e222837466705549 diff --git a/packages/api/job-controller/README.md b/packages/api/job-controller/README.md new file mode 100644 index 0000000000..1af9cac657 --- /dev/null +++ b/packages/api/job-controller/README.md @@ -0,0 +1,66 @@ +--- +description: "Host and Client job observation: stream one background job's output record to the browser without touching the model's consuming cursor." +kind: "package-reference" +--- +# Job Controller + +English | [中文](README.zh.md) + +## Summary + +`@deepseek-ai/dsh-api-job-controller` owns the Host `ctx.jobController` service and the generated Client `ctx.remote.job` namespace. Its one Remote stream, `job.observe`, delivers a record-declaring job's retained output from an absolute byte offset; the Client half installs `ctx.jobOutput`, the reference-counted per-job observation service whose accumulated views the session-header job list renders. The roster itself is not here: `SessionJob` rows still ride the session control stream owned by [`dsh-api-session-controller`](../session-controller/README.md), and a row's `outputTotal` says whether this controller has anything to stream for it. + +## Table of Contents + +- [Use this package](#use-this-package) +- [Model Experience](#model-experience) +- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work) +- [Dev Note](#dev-note) + +----- + + +## Use this package + +The Host controller requires the live Agent registry and the job registry (`dsh-jobs-local` in the shipped compositions) and fails to load without them. `job.observe({ sessionId?, jobId, from? })` resolves the fenced-read caller from the request's session — an unowned job needs no session — and yields one `opened` anchor, coalesced `output` frames, then one terminal `status` once the job has settled and its record is drained, after which the stream closes normally. Record reads are non-consuming: the model-facing `job_output` cursor and completion-notice state never observe them. A job the session does not own, a job without a record, or an unknown job rejects the stream. Reconnecting callers resume by passing the last frame's `next` as `from`; a `from` below the oldest retained byte gets a `lossy` first frame instead of an error. + +The Client entry provides `ClientJobOutput` (`ctx.jobOutput`) over `ClientJobOutputModel`. `observe(sessionId, jobId)` opens one Gateway stream per job however many viewers expand it, keeps a bounded render tail per job with `gapBefore` marking eviction or resume gaps, records the terminal status or a stream failure on the view, and drops the view after the last viewer releases. The plugin resolves the Gateway stream factory and the `job` namespace while its own context is current, because observation (re)opens run on caller stacks that have not declared `remote.job`. + +### Config + +| Field | Default | Meaning | +|---|---:|---| +| `observeFlushMs` | `100` | Coalescing window after new record output before an observation read, in milliseconds | +| `observeMaxFrameBytes` | `65,536` | Soft byte budget per observation output frame; one larger chunk ships whole | + +The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-api-job-controller) is the exhaustive source for accepted fields and their JSDoc. + +----- + + +## Model Experience + +None, as job observation is browser and Host control state; it registers no prompt, tool, or session event. The model's own view of the same work stays with [`dsh-tool-jobs`](../../jobs/tool-jobs/README.md). + +#### KV Cache effect + +No direct effect; observation reads never touch model requests. + +## Known Limitations and Deferred Work + + + +- The stream is process-local: a Host restart loses every record, and a resumed observation then anchors on an empty registry. +- Per-session fencing is enforced by the registry read; the Remote layer itself serves any connected browser, matching the session control stream's `jobsBySession` broadcast. + + +### Dev Note + +
        +Working context for maintainers — click to expand + +None. + +
        + +**Runtime invariant:** No companion is published. The controller is a stateless projection of `ctx.jobs` reads; the registry's own `@deepseek-ai/dsh-jobs/invariant` owns the offset relations this stream forwards. diff --git a/packages/api/job-controller/README.zh.md b/packages/api/job-controller/README.zh.md new file mode 100644 index 0000000000..a232d8e865 --- /dev/null +++ b/packages/api/job-controller/README.zh.md @@ -0,0 +1,66 @@ +--- +description: "Host 与 Client 的 job 观测:把一个后台任务的输出 record 流式送到浏览器,不触碰模型的消耗型游标。" +kind: "package-reference" +--- +# Job Controller + +[English](README.md) | 中文 + +## 概述 + +`@deepseek-ai/dsh-api-job-controller` 拥有 Host 的 `ctx.jobController` 服务与生成的 Client `ctx.remote.job` namespace。它唯一的 Remote 流 `job.observe` 从绝对字节偏移发送声明了 record 的 job 的保留输出;Client 半侧安装 `ctx.jobOutput`——按 job 引用计数的观测服务,会话头部任务列表渲染其累积视图。名册不在这里:`SessionJob` 行仍随 [`dsh-api-session-controller`](../session-controller/README.zh.md) 拥有的会话控制流到达,行上的 `outputTotal` 说明本控制器是否有东西可流。 + +## 目录 + +- [使用本包](#use-this-package) +- [模型体验](#model-experience) +- [已知限制与延期工作](#known-limitations-and-deferred-work) +- [开发备注](#dev-note) + +----- + + +## 使用本包 + +Host 控制器要求活体 Agent 注册表与 job 注册表(已发布组合里是 `dsh-jobs-local`),缺少任一则不加载。`job.observe({ sessionId?, jobId, from? })` 由请求的 session 解析围栏读取者——无主 job 不需要 session——先产出一个 `opened` 锚帧,再是聚合的 `output` 帧,job 结算且 record 排干后产出一个终态 `status`,随后流正常关闭。record 读取是非消耗的:模型侧 `job_output` 游标与完成播报状态永远观察不到它们。session 不拥有的 job、没有 record 的 job 或未知 job 会拒绝该流。重连方把上一帧的 `next` 作为 `from` 续读;低于最老保留字节的 `from` 得到带 `lossy` 的首帧而非错误。 + +Client 入口在 `ClientJobOutputModel` 之上提供 `ClientJobOutput`(`ctx.jobOutput`)。`observe(sessionId, jobId)` 不论多少查看器展开同一 job 都只开一条 Gateway 流,按 job 保留有界的渲染尾部并用 `gapBefore` 标记淘汰或续读缺口,把终态或流失败记到视图上,最后一个查看器释放后丢弃视图。插件在自己的上下文仍是当前上下文时解析 Gateway 流工厂与 `job` namespace,因为观测的(重)开启跑在未声明 `remote.job` 的调用栈上。 + +### 配置 + +| 字段 | 默认值 | 含义 | +|---|---:|---| +| `observeFlushMs` | `100` | 新 record 输出到一次观测读取之间的聚合窗口,毫秒 | +| `observeMaxFrameBytes` | `65,536` | 每个观测输出帧的软字节预算;更大的单块整块发送 | + +生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-api-job-controller)是所有受支持字段及其 JSDoc 的完整来源。 + +----- + + +## 模型体验 + +无。job 观测是浏览器与 Host 的控制状态;它不注册任何提示词、工具或会话事件。模型对同一工作的视图仍在 [`dsh-tool-jobs`](../../jobs/tool-jobs/README.zh.md)。 + +#### KV 缓存影响 + +无直接影响;观测读取从不触碰模型请求。 + +## 已知限制与延期工作 + + + +- 流是进程本地的:Host 重启丢失全部 record,续读的观测随后锚定在空注册表上。 +- 按 session 的围栏由注册表读取强制;Remote 层本身服务任何已连接浏览器,与会话控制流对 `jobsBySession` 的广播一致。 + + +### 开发备注 + +
        +维护者的工作上下文——点击展开 + +无。 + +
        + +**运行时不变式:** 不发布伴生入口。控制器是 `ctx.jobs` 读取的无状态投影;本流转发的偏移关系由注册表自己的 `@deepseek-ai/dsh-jobs/invariant` 拥有。 diff --git a/packages/api/job-controller/package.json b/packages/api/job-controller/package.json new file mode 100644 index 0000000000..0f0e46aafe --- /dev/null +++ b/packages/api/job-controller/package.json @@ -0,0 +1,86 @@ +{ + "name": "@deepseek-ai/dsh-api-job-controller", + "description": "Job Remote observation stream and the reference-counted client job-output service", + "version": "0.1.2-alpha.5", + "publishConfig": { + "access": "public" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/deepseek-ai/deepseek-harness.git", + "directory": "packages/api/job-controller" + }, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./types": { + "types": "./lib/types/types.d.ts", + "default": "./lib/types/types.js" + }, + "./client": { + "types": "./lib/types/client/index.d.ts", + "default": "./lib/client.js" + }, + "./typert": { + "types": "./lib/typert.host.d.ts", + "default": "./lib/typert.host.js" + }, + "./remote": { + "types": "./lib/typert.remote-client.d.ts", + "default": "./lib/typert.remote-client.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "dsh": { + "client": { + "external": [ + "@deepseek-ai/dsh-api-gateway/client" + ], + "inject": [ + "@deepseek-ai/dsh-api-gateway", + "@deepseek-ai/dsh-client-connection" + ], + "platform": "web" + } + }, + "scripts": { + "bundle": "tsdown", + "watch": "tsdown --watch" + }, + "files": [ + "lib/index.js", + "lib/client.js", + "lib/types/**/*.js", + "lib/types/**/*.d.ts", + "lib/typert.host.js", + "lib/typert.host.d.ts", + "lib/typert.remote-client.js", + "lib/typert.remote-client.d.ts" + ], + "license": "MIT", + "dependencies": { + "@deepseek-ai/dsh-typert-protocol": "workspace:^", + "@deepseek-ai/schemastery": "workspace:^", + "zod": "^4.4.3" + }, + "peerDependencies": { + "@deepseek-ai/cordis": "workspace:^" + }, + "devDependencies": { + "@deepseek-ai/cordis": "workspace:^", + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-api-gateway": "workspace:^", + "@deepseek-ai/dsh-client-connection": "workspace:^", + "@deepseek-ai/dsh-client-store": "workspace:^", + "@deepseek-ai/dsh-jobs": "workspace:^", + "@deepseek-ai/dsh-jobs-local": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-typert-registry": "workspace:^" + } +} diff --git a/packages/api/job-controller/src/client/index.ts b/packages/api/job-controller/src/client/index.ts new file mode 100644 index 0000000000..a76d507332 --- /dev/null +++ b/packages/api/job-controller/src/client/index.ts @@ -0,0 +1,34 @@ +/** + * Job Controller client half: installs `ctx.jobOutput` over the generated + * `job` Remote namespace. The plugin resolves both Remote faces it drives + * while its own context is current, because observation (re)opens run on + * caller stacks — a React event, a carrier retry — whose dynamic context has + * not declared `remote.job`. + * @module @deepseek-ai/dsh-api-job-controller/client + */ + +import type { Context } from '@deepseek-ai/cordis' +import { ClientJobOutputModel } from './model.ts' +import { ClientJobOutput } from './service.ts' +import type { JobObserveRemote } from './service.ts' + +export { ClientJobOutputModel } from './model.ts' +export type { JobOutputSnapshot, JobOutputSource, ObservedJob } from './model.ts' +export { ClientJobOutput } from './service.ts' +export type { IJobOutput, JobObserveRemote, JobRemote } from './service.ts' +export type { JobObserveFrame, JobObserveRequest, JobObserveStatus, JobWireChunk } from '../types.ts' + +/** Required Client Remote services. */ +export const inject = ['remote', 'remote.job'] + +/** + * Install the client job-output service. + * @param ctx - Client root Context. + */ +export function apply(ctx: Context): void { + const remotes = ctx.remote as unknown as JobObserveRemote + new ClientJobOutput(ctx, { + $stream: options => remotes.$stream(options), + job: remotes.job, + }, new ClientJobOutputModel()) +} diff --git a/packages/api/job-controller/src/client/model.ts b/packages/api/job-controller/src/client/model.ts new file mode 100644 index 0000000000..1c44aa039a --- /dev/null +++ b/packages/api/job-controller/src/client/model.ts @@ -0,0 +1,179 @@ +/** + * React-free client job-record observation state: per-job accumulated output + * views fed by `job.observe` frames. Pure data plus subscriptions — transport + * wiring stays in the client service, UI stays in slot components. + * @module @deepseek-ai/dsh-api-job-controller/client/model + */ + +import { notifySubscribers } from '@deepseek-ai/dsh-client-store' +import type { JobId } from '@deepseek-ai/dsh-jobs/brand' +import type { JobObserveFrame, JobObserveStatus } from '../types.ts' + +/** Bounded per-job render tail, in UTF-16 code units. */ +const RENDER_TAIL_LIMIT = 128 * 1024 + +/** One observed job's live view state. */ +export interface ObservedJob { + readonly jobId: JobId + /** Accumulated output tail, bounded to the render limit. */ + readonly text: string + /** True when bytes before {@link text} were dropped (eviction, resume gap, or the render bound). */ + readonly gapBefore: boolean + /** Latest status delivered on the observation stream. */ + readonly status: JobObserveStatus + readonly detail?: string + /** True while the observation stream is open and the job has not settled. */ + readonly streaming: boolean + /** Terminal observation failure, when the stream ended abnormally. */ + readonly error?: string +} + +/** Immutable client job-output state. */ +export interface JobOutputSnapshot { + /** Live observation state keyed by job id. */ + readonly observed: Readonly> +} + +/** Bare observable source for the client job-output snapshot. */ +export interface JobOutputSource { + /** Read the identity-stable current snapshot. */ + getSnapshot(): JobOutputSnapshot + /** + * Subscribe to snapshot changes. + * @param listener - invalidation callback. + * @returns unsubscribe function. + */ + subscribe(listener: () => void): () => void +} + +/** Mutable observation bookkeeping behind one {@link ObservedJob} view. */ +interface ObservedState { + view: ObservedJob + /** Resume offset for the next generation's `from`. */ + cursor: number | undefined +} + +/** Owns per-job observation state. */ +export class ClientJobOutputModel implements JobOutputSource { + private readonly observedStates = new Map() + private readonly listeners = new Set<() => void>() + private snapshotCache: JobOutputSnapshot = { observed: {} } + private snapshotDirty = false + + getSnapshot(): JobOutputSnapshot { + if (this.snapshotDirty) { + const observed: Record = {} + for (const [id, state] of this.observedStates) observed[id] = state.view + this.snapshotCache = { observed } + this.snapshotDirty = false + } + return this.snapshotCache + } + + subscribe(listener: () => void): () => void { + this.listeners.add(listener) + return () => { this.listeners.delete(listener) } + } + + /** + * The resume offset for one job's next observation generation. + * @param id - observed job. + * @returns the last accepted `next`, or undefined for a fresh observation. + */ + cursorOf(id: JobId): number | undefined { + return this.observedStates.get(String(id))?.cursor + } + + /** + * Install or reset observation state when a generation's anchor arrives. + * @param id - observed job. + * @param frame - the generation's `opened` anchor. + */ + observeOpened(id: JobId, frame: Extract): void { + const existing = this.observedStates.get(String(id)) + // A fresh view anchored past offset zero starts after an evicted head + // (fresh observations anchor at the registry's earliest retained byte), so + // it owes the same gap mark a live observer earned from lossy reads. A + // resume that already accumulated text keeps its recorded gap state. + const freshPastHead = (existing === undefined || existing.view.text === '') && frame.from > 0 + const view: ObservedJob = { + jobId: id, + text: existing?.view.text ?? '', + gapBefore: (existing?.view.gapBefore ?? false) || frame.from < frame.earliest || freshPastHead, + status: frame.status, + ...frame.detail !== undefined ? { detail: frame.detail } : {}, + streaming: true, + } + this.observedStates.set(String(id), { view, cursor: frame.from }) + this.changed() + } + + /** + * Append one output frame's chunks to the bounded render tail. + * @param id - observed job. + * @param frame - a coalesced `output` frame. + */ + observeOutput(id: JobId, frame: Extract): void { + const state = this.observedStates.get(String(id)) + /* v8 ignore next -- frames arrive only between opened and stop for a tracked id. */ + if (state === undefined) return + let text = state.view.text + frame.chunks.map(chunk => chunk.text).join('') + let gapBefore = state.view.gapBefore || frame.lossy === true + || frame.chunks.some(chunk => chunk.gapBefore === true) + if (text.length > RENDER_TAIL_LIMIT) { + let cut = text.length - RENDER_TAIL_LIMIT + // Never split a surrogate pair at the render bound. + const unit = text.charCodeAt(cut) + if (unit >= 0xDC00 && unit <= 0xDFFF) cut += 1 + text = text.slice(cut) + gapBefore = true + } + state.view = { ...state.view, text, gapBefore } + state.cursor = frame.next + this.changed() + } + + /** + * Record the terminal status delivered at the end of the observation stream. + * @param id - observed job. + * @param frame - the terminal `status` frame. + */ + observeStatus(id: JobId, frame: Extract): void { + const state = this.observedStates.get(String(id)) + /* v8 ignore next -- frames arrive only between opened and stop for a tracked id. */ + if (state === undefined) return + state.view = { + ...state.view, + status: frame.status, + ...frame.detail !== undefined ? { detail: frame.detail } : {}, + streaming: false, + } + this.changed() + } + + /** + * Record a terminal observation failure. + * @param id - observed job. + * @param error - the stream's terminal failure. + */ + observeFailed(id: JobId, error: unknown): void { + const state = this.observedStates.get(String(id)) + if (state === undefined) return + state.view = { ...state.view, streaming: false, error: String(error) } + this.changed() + } + + /** + * Drop observation state after the last observer stops. + * @param id - the no-longer-observed job. + */ + observeStopped(id: JobId): void { + if (!this.observedStates.delete(String(id))) return + this.changed() + } + + private changed(): void { + this.snapshotDirty = true + notifySubscribers(this.listeners, 'job output') + } +} diff --git a/packages/api/job-controller/src/client/service.ts b/packages/api/job-controller/src/client/service.ts new file mode 100644 index 0000000000..385a0b92ad --- /dev/null +++ b/packages/api/job-controller/src/client/service.ts @@ -0,0 +1,179 @@ +/** + * The `ctx.jobOutput` client service: reference-counted per-job observation + * streams over `job.observe`, so overlapping viewers of one job share one + * stream and resume from the model's cursor across reconnects. + * @module @deepseek-ai/dsh-api-job-controller/client/service + */ + +import { Service, type Context } from '@deepseek-ai/cordis' +import { RemoteStreamCarrierError, type ClientRemote } from '@deepseek-ai/dsh-api-gateway/client' +import type { JobId } from '@deepseek-ai/dsh-jobs/brand' +import type { SessionId } from '@deepseek-ai/dsh-session/types' +import type { JobObserveFrame, JobObserveRequest } from '../types.ts' +import type { ClientJobOutputModel, JobOutputSource } from './model.ts' + +/** The generated `job` namespace face the observation runner drives. */ +export interface JobRemote { + /** + * Open one observation generation. + * @param request - target job, owning session, and optional resume offset. + * @param signal - generation cancellation. + * @returns the frame sequence of one generation. + */ + observe(request: JobObserveRequest, signal?: AbortSignal): AsyncIterable +} + +/** Remote faces the observation runner drives: the Gateway stream factory and the `job` namespace. */ +export interface JobObserveRemote { + readonly $stream: ClientRemote['$stream'] + readonly job: JobRemote +} + +/** The job-output client service face. */ +export interface IJobOutput { + /** Per-job observation state. */ + readonly state: JobOutputSource + /** + * Start observing one job's live record; reference-counted, so two viewers + * of the same job share one stream. + * @param sessionId - owning session used for the fenced read; undefined for an unowned job. + * @param id - job to observe. + * @returns stop function releasing this observer's reference. + */ + observe(sessionId: SessionId | undefined, id: JobId): () => void +} + +/** One reference-counted observation stream. */ +interface ObservationEntry { + refs: number + stopped: boolean + dispose: () => Promise +} + +declare module '@deepseek-ai/cordis' { + interface Context { + /** React-free client job-record observation control. */ + jobOutput: IJobOutput + } +} + +/** Owns the bare job-output snapshot and per-job observation streams. */ +export class ClientJobOutput extends Service implements IJobOutput { + readonly state: JobOutputSource + private readonly entries = new Map() + + /** + * @param ctx - client root Context. + * @param remote - the Gateway stream factory plus the generated `job` namespace, both resolved by the caller. + * @param model - shared client job-output model. + */ + constructor( + ctx: Context, + private readonly remote: JobObserveRemote, + private readonly model: ClientJobOutputModel, + ) { + super(ctx, 'jobOutput') + this.state = model + ctx.effect(() => () => { + const open = [...this.entries.values()] + this.entries.clear() + for (const entry of open) { + entry.stopped = true + void entry.dispose() + } + }, 'job-controller.client.observations') + } + + observe(sessionId: SessionId | undefined, id: JobId): () => void { + const key = String(id) + const existing = this.entries.get(key) + if (existing !== undefined && !existing.stopped) { + existing.refs += 1 + return this.releaser(key, existing) + } + const entry = this.startObservation(sessionId, id) + this.entries.set(key, entry) + return this.releaser(key, entry) + } + + /** + * Release closures bind the exact entry they were minted for, never the + * map's current occupant: a later `observe()` on the same id may have + * replaced a stopped entry, and decrementing or disposing through the key + * alone would tear down that newer stream's references. + */ + private releaser(key: string, entry: ObservationEntry): () => void { + let released = false + return () => { + if (released) return + released = true + entry.refs -= 1 + if (entry.refs > 0) return + if (this.entries.get(key) === entry) this.entries.delete(key) + entry.stopped = true + void entry.dispose().then(() => { + // Clear the view only while no successor observation holds the key: + // a re-expand inside the dispose round-trip already re-anchored the + // model, and a stale clear would blank its panel for good. + if (this.entries.has(key)) return + // The key is the stringified branded id this releaser was minted for. + this.model.observeStopped(key as JobId) + }) + } + } + + private startObservation(sessionId: SessionId | undefined, id: JobId): ObservationEntry { + const name = `job observation ${String(id)}` + const stream = this.remote.$stream({ + name, + open: (signal) => { + const from = this.model.cursorOf(id) + return this.remote.job.observe( + { + jobId: id, + ...sessionId !== undefined ? { sessionId } : {}, + ...from !== undefined ? { from } : {}, + }, + signal, + ) + }, + // A premature end after the anchor is retryable (a Host reload closes the + // generation); resuming from the cursor loses nothing. An end before the + // anchor is terminal. + ended: accepted => accepted + ? new RemoteStreamCarrierError(`${name} ended before settlement`) + : new Error(`${name} ended before its anchor`), + }) + const entry: ObservationEntry = { + refs: 1, + stopped: false, + dispose: () => stream.dispose(), + } + void (async () => { + try { + for await (const item of stream) { + const frame = item.value + if (frame.type === 'opened') { + this.model.observeOpened(id, frame) + item.accept() + continue + } + if (frame.type === 'output') { + this.model.observeOutput(id, frame) + continue + } + // Terminal status: leave the loop before the generation end is + // classified, then close the stream for good. + this.model.observeStatus(id, frame) + break + } + } catch (error) { + if (!entry.stopped) this.model.observeFailed(id, error) + } finally { + entry.stopped = true + void entry.dispose() + } + })() + return entry + } +} diff --git a/packages/api/job-controller/src/index.ts b/packages/api/job-controller/src/index.ts new file mode 100644 index 0000000000..27e85a0ed0 --- /dev/null +++ b/packages/api/job-controller/src/index.ts @@ -0,0 +1,86 @@ +/** + * Host job Remote owner: streams one background job's observation record to + * browsers over the generated `job` namespace. The roster itself rides the + * session control stream (`jobsBySession`, owned by `dsh-api-session-controller`); + * this controller carries only the non-consuming record output. + * @module @deepseek-ai/dsh-api-job-controller + */ + +import { Context } from '@deepseek-ai/cordis' +import z from '@deepseek-ai/schemastery' +import type {} from '@deepseek-ai/dsh-agent' +import type {} from '@deepseek-ai/dsh-jobs' +import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol' +import { observeJobRecord } from './observe.ts' +import type { JobObserveFrame, JobObserveRequest } from './types.ts' + +export type * from './types.ts' + +declare module '@deepseek-ai/cordis' { + interface Context { + /** Host job Remote namespace owner. */ + jobController: JobController + } +} + +/** Default coalescing window between record reads, in milliseconds. */ +const DEFAULT_OBSERVE_FLUSH_MS = 100 + +/** Default soft byte budget per output frame. */ +const DEFAULT_OBSERVE_MAX_FRAME_BYTES = 64 * 1024 + +/** Job Controller deployment policy. */ +export interface Config { + /** Coalescing window after new record output before an observation read, in milliseconds (default 100). */ + readonly observeFlushMs?: number + /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */ + readonly observeMaxFrameBytes?: number +} + +/** Host service backing the generated `ctx.remote.job` namespace. */ +export class JobController extends TypertRemoteService { + static inject = ['agents', 'jobs', 'typert'] + + static Config: z = z.object({ + observeFlushMs: z.natural().min(1).default(DEFAULT_OBSERVE_FLUSH_MS), + observeMaxFrameBytes: z.natural().min(1).default(DEFAULT_OBSERVE_MAX_FRAME_BYTES), + }) + + private readonly observeFlushMs: number + private readonly observeMaxFrameBytes: number + + /** + * @param ctx - Host context carrying the live Agent registry and the job registry. + * @param config - observation cadence and framing policy. + */ + constructor(ctx: Context, config: Config) { + super(ctx, 'jobController', { namespace: 'job' }) + // schemastery (the exported Config schema) has already filled the defaulted + // fields; the assertion records that resolution, not a hidden fallback. + const resolved = config as Required + this.observeFlushMs = resolved.observeFlushMs + this.observeMaxFrameBytes = resolved.observeMaxFrameBytes + } + + /** + * Stream one job's retained record output from an absolute byte offset, + * then its terminal status once settled and drained. Non-consuming: the + * model-facing cursor and notice state never observe these reads. The + * request's session resolves the fenced-read caller; the registry rejects a + * job the session does not own, a job without a record, or an unknown job. + * @param request - target job, owning session, and optional resume offset. + * @param signal - cancellation owned by the Remote stream carrier. + * @returns anchor, coalesced output frames, and the terminal status. + */ + @Remote({ mode: 'stream' }) + observe(request: JobObserveRequest, signal: AbortSignal): AsyncIterable { + const caller = request.sessionId === undefined ? undefined : this.ctx.agents.get(request.sessionId) + return observeJobRecord(this.ctx.jobs, request, { + flushMs: this.observeFlushMs, + maxFrameBytes: this.observeMaxFrameBytes, + caller, + }, signal) + } +} + +export default JobController diff --git a/packages/api/session-controller/src/observe-job.ts b/packages/api/job-controller/src/observe.ts similarity index 94% rename from packages/api/session-controller/src/observe-job.ts rename to packages/api/job-controller/src/observe.ts index 795e786455..731f40b2e2 100644 --- a/packages/api/session-controller/src/observe-job.ts +++ b/packages/api/job-controller/src/observe.ts @@ -3,7 +3,7 @@ import type { Agent } from '@deepseek-ai/dsh-agent' import type { JobId } from '@deepseek-ai/dsh-jobs/brand' import type { JobRegistry, JobSnapshot } from '@deepseek-ai/dsh-jobs' -import type { SessionJobWireChunk, SessionObserveJobFrame, SessionObserveJobRequest } from './types.ts' +import type { JobObserveFrame, JobObserveRequest, JobWireChunk } from './types.ts' /** Cadence and framing bounds for one observation generation. */ export interface ObserveJobOptions { @@ -91,16 +91,16 @@ function sleep(ms: number, signal: AbortSignal): Promise { */ export async function* observeJobRecord( registry: JobRegistry, - request: SessionObserveJobRequest, + request: JobObserveRequest, options: ObserveJobOptions, signal: AbortSignal, -): AsyncIterable { +): AsyncIterable { if (request.from !== undefined && (!Number.isSafeInteger(request.from) || request.from < 0)) { throw new Error(`invalid observe offset: expected a non-negative safe integer, got ${JSON.stringify(request.from)}`) } signal.throwIfAborted() // The brand is nominal typing only; the wire boundary stamps it here rather - // than value-importing the optional registry package's constructor. + // than value-importing the registry package's constructor. const id = String(request.jobId) as JobId const waiter = new OutputWaiter() // Subscribe before the first read so an append between the anchor read and @@ -153,12 +153,12 @@ export async function* observeJobRecord( /** Split one read into frames along the soft per-frame byte budget. */ function* outputFrames( - chunks: readonly SessionJobWireChunk[], + chunks: readonly JobWireChunk[], next: number, lossy: boolean, maxFrameBytes: number, -): Iterable { - let batch: SessionJobWireChunk[] = [] +): Iterable { + let batch: JobWireChunk[] = [] let batchBytes = 0 let flaggedLossy = lossy for (const chunk of chunks) { diff --git a/packages/api/job-controller/src/types.ts b/packages/api/job-controller/src/types.ts new file mode 100644 index 0000000000..98df4d8f65 --- /dev/null +++ b/packages/api/job-controller/src/types.ts @@ -0,0 +1,75 @@ +/** + * Wire types of the generated `job` Remote namespace: the observation request + * and the frames its stream yields. Client-safe: no Host imports. + * @module @deepseek-ai/dsh-api-job-controller/types + */ + +import type { JobId } from '@deepseek-ai/dsh-jobs/brand' +import type { SessionId } from '@deepseek-ai/dsh-session/types' + +/** + * A job's lifecycle state on the wire. Spelled out rather than imported from + * the registry package so this client-safe face pulls no Host declaration + * merges into browser programs; it is the registry's `JobStatus` union. + */ +export type JobObserveStatus = 'running' | 'stopping' | 'completed' | 'killed' | 'failed' + +/** Target of one `job.observe` stream: the job, its owning session, and an optional resume offset. */ +export interface JobObserveRequest { + /** + * Owning session, resolved to the live agent for the fenced record read. + * Omitted for an unowned job, which any caller may observe. + */ + readonly sessionId?: SessionId + readonly jobId: JobId + /** + * Absolute byte offset to resume from (a prior frame's `next`). Omitted, the + * stream starts at the oldest retained byte. + */ + readonly from?: number +} + +/** One retained record chunk on the wire. `channel` widens to string like a job's `kind`. */ +export interface JobWireChunk { + /** Absolute offset of the chunk's first byte. */ + readonly at: number + readonly text: string + readonly channel?: string + /** Bytes immediately before this chunk were lost at the producer or to retention. */ + readonly gapBefore?: true +} + +/** + * Job observation stream frames: one `opened` anchor, then coalesced `output` + * batches, then — once the job has settled and its retained record is + * drained — one terminal `status`, after which the stream closes normally. + * Status rides the same stream as output so settlement can never race a + * still-open output channel. + */ +export type JobObserveFrame = + | { + readonly type: 'opened' + readonly jobId: JobId + /** Offset the first `output` frame continues from. */ + readonly from: number + /** Oldest retained byte at open time; `from < earliest` means the head is gone. */ + readonly earliest: number + /** Total bytes produced at open time. */ + readonly total: number + readonly status: JobObserveStatus + readonly detail?: string + } + | { + readonly type: 'output' + readonly chunks: readonly JobWireChunk[] + /** Offset to resume from after this frame. */ + readonly next: number + /** Bytes between the requested offset and `chunks` were already evicted. */ + readonly lossy?: true + } + | { + readonly type: 'status' + readonly status: JobObserveStatus + readonly detail?: string + readonly finishedAt?: number + } diff --git a/packages/api/job-controller/tests/client-apply.client.spec.ts b/packages/api/job-controller/tests/client-apply.client.spec.ts new file mode 100644 index 0000000000..ebbe67e98e --- /dev/null +++ b/packages/api/job-controller/tests/client-apply.client.spec.ts @@ -0,0 +1,65 @@ +import { Context } from '@deepseek-ai/cordis' +import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client' +import { RemoteStream, type RemoteStreamOptions } from '@deepseek-ai/dsh-api-gateway/client' +import type { SessionId } from '@deepseek-ai/dsh-session/types' +import { afterEach, describe, expect, it } from 'vitest' +import * as JobClient from '../src/client/index.ts' +import type { JobObserveFrame } from '../src/types.ts' + +const contexts = new Set() + +afterEach(async () => { + await Promise.all([...contexts].map(async (ctx) => { await ctx.fiber.dispose() })) + contexts.clear() +}) + +/** Mount the client half over a captured `remote.job` namespace and a real Gateway stream carrier. */ +async function mount(): Promise<{ ctx: Context; observeCalls: unknown[] }> { + const ctx = new Context() + contexts.add(ctx) + const observeCalls: unknown[] = [] + const connection: ConnectionHandle = { + isLoopback: true, + generation: { getSnapshot: () => ({ id: 1, host: { home: '/home/fixture' } }), subscribe: () => () => {} }, + state: { getSnapshot: () => 'connected' as const, subscribe: () => () => {} }, + rpc: { call: () => Promise.reject(new Error('unexpected generic RPC call')) }, + reconnect: () => {}, + registerGenerationSource: () => () => {}, + start: () => ({ stop: () => {} }), + } + const job = { + // The fake stream never yields; opening and releasing must leave no view behind. + observe: (request: unknown) => { + observeCalls.push(request) + return (async function* (): AsyncGenerator {})() + }, + } + ctx.reflect.provide('remote', { + $stream: (options: RemoteStreamOptions) => new RemoteStream(connection, options), + job, + }) + ctx.reflect.provide('remote.job', job) + await ctx.plugin(JobClient) + return { ctx, observeCalls } +} + +async function flush(): Promise { + for (let index = 0; index < 12; index++) await Promise.resolve() +} + +describe('Job Controller Client apply', () => { + it('declares the Remote services it binds', () => { + expect(JobClient.inject).toEqual(['remote', 'remote.job']) + }) + + it('installs ctx.jobOutput over the captured job namespace', async () => { + const { ctx, observeCalls } = await mount() + expect(ctx.jobOutput).toBeDefined() + const stop = ctx.jobOutput.observe('session-1' as SessionId, 'bash-1' as never) + await flush() + expect(observeCalls).toEqual([{ sessionId: 'session-1', jobId: 'bash-1' }]) + stop() + await flush() + expect(ctx.jobOutput.state.getSnapshot().observed).toEqual({}) + }) +}) diff --git a/packages/api/session-controller/tests/job-output.client.spec.ts b/packages/api/job-controller/tests/model.client.spec.ts similarity index 98% rename from packages/api/session-controller/tests/job-output.client.spec.ts rename to packages/api/job-controller/tests/model.client.spec.ts index a4ca2933dc..69260ff3fc 100644 --- a/packages/api/session-controller/tests/job-output.client.spec.ts +++ b/packages/api/job-controller/tests/model.client.spec.ts @@ -2,8 +2,9 @@ import { describe, expect, it, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' import type { JobId } from '@deepseek-ai/dsh-jobs/brand' import type { SessionId } from '@deepseek-ai/dsh-session/types' -import { ClientJobOutput, ClientJobOutputModel } from '../src/client/job-output.ts' -import type { SessionObserveJobFrame } from '../src/types.ts' +import { ClientJobOutputModel } from '../src/client/model.ts' +import { ClientJobOutput } from '../src/client/service.ts' +import type { JobObserveFrame } from '../src/types.ts' const ID = 'bash-1' as JobId @@ -152,12 +153,12 @@ class FakeStream { deferDispose = false private disposeRelease: (() => void) | undefined private disposePending: Promise | undefined - private readonly frames: SessionObserveJobFrame[] = [] + private readonly frames: JobObserveFrame[] = [] private waiter: (() => void) | undefined private failure: Error | undefined readonly accepts: number[] = [] - push(frame: SessionObserveJobFrame): void { + push(frame: JobObserveFrame): void { this.frames.push(frame) this.waiter?.() } @@ -218,8 +219,8 @@ function bench() { streams.push({ options, stream }) return stream }, - session: { - observeJob: (request: unknown) => { + job: { + observe: (request: unknown) => { observeCalls.push(request) return { [Symbol.asyncIterator]: async function* () { /* never yields */ } } }, diff --git a/packages/api/session-controller/tests/observe-job.host.spec.ts b/packages/api/job-controller/tests/observe.host.spec.ts similarity index 89% rename from packages/api/session-controller/tests/observe-job.host.spec.ts rename to packages/api/job-controller/tests/observe.host.spec.ts index 06a67848ec..5bbb5a8c66 100644 --- a/packages/api/session-controller/tests/observe-job.host.spec.ts +++ b/packages/api/job-controller/tests/observe.host.spec.ts @@ -6,10 +6,11 @@ import { JobId } from '@deepseek-ai/dsh-jobs' import type { JobOutcome, RunningJob } from '@deepseek-ai/dsh-jobs' import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session' -import { observeJobRecord } from '../src/observe-job.ts' -import type { ObserveJobOptions } from '../src/observe-job.ts' -import type { SessionObserveJobFrame } from '../src/types.ts' -import { createSessionTestController } from './test-remote.ts' +import TypertRegistry from '@deepseek-ai/dsh-typert-registry' +import { JobController } from '../src/index.ts' +import { observeJobRecord } from '../src/observe.ts' +import type { ObserveJobOptions } from '../src/observe.ts' +import type { JobObserveFrame } from '../src/types.ts' async function harness() { const ctx = new Context() @@ -88,7 +89,7 @@ const OBSERVE: Omit = { flushMs: 5, maxFrameBytes: describe('observeJobRecord', () => { function observed(ctx: Context, request: { jobId: JobId; from?: number }, caller?: Agent) { const abort = new AbortController() - const frames: SessionObserveJobFrame[] = [] + const frames: JobObserveFrame[] = [] const stream = observeJobRecord(ctx.jobs, request, { ...OBSERVE, caller }, abort.signal) const done = (async () => { for await (const frame of stream) frames.push(frame) @@ -142,7 +143,7 @@ describe('observeJobRecord', () => { job.append('y'.repeat(30)) await job.settle({ status: 'completed' }) const abort = new AbortController() - const frames = await collect( + const frames = await collect( observeJobRecord(ctx.jobs, { jobId: job.id }, { flushMs: 5, maxFrameBytes: 30, @@ -165,7 +166,7 @@ describe('observeJobRecord', () => { job.append('c'.repeat(40)) await job.settle({ status: 'completed' }) const abort = new AbortController() - const frames = await collect( + const frames = await collect( observeJobRecord(ctx.jobs, { jobId: job.id, from: 0 }, { flushMs: 5, maxFrameBytes: 40, @@ -278,28 +279,30 @@ describe('observeJobRecord', () => { }) }) -describe('SessionController.observeJob', () => { - const defaults = { - defaultModelSelection: () => ({ provider: 'fixture', model: 'fixture-model' }), - cwd: '/tmp', - } - - it('refuses observation without a job registry', async () => { - const ctx = new Context() - await ctx.plugin(SessionStore) - await ctx.plugin(AgentRegistry) - const controller = createSessionTestController(ctx, defaults) - expect(() => controller.observeJob({ jobId: JobId('bash-1') }, new AbortController().signal)) - .toThrow(/job observation unavailable/) - }) - - it('resolves the fenced-read caller from the request session', async () => { +describe('JobController.observe', () => { + async function controllerHarness() { const ctx = new Context() await ctx.plugin(SessionStore) await ctx.plugin(AgentRegistry) await ctx.plugin(LocalJobRegistry) + await ctx.plugin(TypertRegistry) ctx.jobs.attachController('observe-job-test') - const controller = createSessionTestController(ctx, defaults) + await ctx.plugin(JobController, {}) + return ctx + } + + it('waits for the job registry instead of serving without one', async () => { + const ctx = new Context() + await ctx.plugin(SessionStore) + await ctx.plugin(AgentRegistry) + await ctx.plugin(TypertRegistry) + ctx.plugin(JobController, {}) + await new Promise(resolve => setTimeout(resolve, 0)) + expect(ctx.get('jobController')).toBeUndefined() + }) + + it('resolves the fenced-read caller from the request session', async () => { + const ctx = await controllerHarness() const session = ctx.sessions.create(SessionId('observing-session')) const owner = { id: session.id, @@ -314,8 +317,8 @@ describe('SessionController.observeJob', () => { await job.settle({ status: 'completed' }) const abort = new AbortController() - const frames = await collect( - controller.observeJob({ sessionId: session.id, jobId: job.id }, abort.signal), + const frames = await collect( + ctx.jobController.observe({ sessionId: session.id, jobId: job.id }, abort.signal), 3, abort, ) @@ -323,19 +326,14 @@ describe('SessionController.observeJob', () => { }) it('observes an unowned job without a request session', async () => { - const ctx = new Context() - await ctx.plugin(SessionStore) - await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalJobRegistry) - ctx.jobs.attachController('observe-job-test') - const controller = createSessionTestController(ctx, defaults) + const ctx = await controllerHarness() const job = startRecordJob(ctx, { label: 'unowned run' }) job.append('open access') await job.settle({ status: 'completed' }) const abort = new AbortController() - const frames = await collect( - controller.observeJob({ jobId: job.id }, abort.signal), + const frames = await collect( + ctx.jobController.observe({ jobId: job.id }, abort.signal), 3, abort, ) diff --git a/packages/api/job-controller/tsconfig.client.json b/packages/api/job-controller/tsconfig.client.json new file mode 100644 index 0000000000..34a2202060 --- /dev/null +++ b/packages/api/job-controller/tsconfig.client.json @@ -0,0 +1,23 @@ +{ + "extends": "../../../tsconfig.base.client.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types", + "tsBuildInfoFile": "lib/tsconfig.client.tsbuildinfo" + }, + "files": [ + "src/client/index.ts", + "src/client/model.ts", + "src/client/service.ts", + "src/types.ts" + ], + "references": [ + { "path": "../../../vendor/cordis" }, + { "path": "../gateway/tsconfig.client.json" }, + { "path": "../../client/connection/tsconfig.client.json" }, + { "path": "../../client/store" }, + { "path": "../../core/session" }, + { "path": "../../jobs/jobs" }, + { "path": "../../typert/protocol" } + ] +} diff --git a/packages/api/job-controller/tsconfig.host.json b/packages/api/job-controller/tsconfig.host.json new file mode 100644 index 0000000000..96de4dede2 --- /dev/null +++ b/packages/api/job-controller/tsconfig.host.json @@ -0,0 +1,21 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types", + "tsBuildInfoFile": "lib/tsconfig.host.tsbuildinfo" + }, + "files": [ + "src/index.ts", + "src/observe.ts", + "src/types.ts" + ], + "references": [ + { "path": "../../../vendor/cordis" }, + { "path": "../../../vendor/schemastery" }, + { "path": "../../core/agent" }, + { "path": "../../core/session" }, + { "path": "../../jobs/jobs" }, + { "path": "../../typert/protocol" } + ] +} diff --git a/packages/api/job-controller/tsconfig.json b/packages/api/job-controller/tsconfig.json new file mode 100644 index 0000000000..2a0b0e33f7 --- /dev/null +++ b/packages/api/job-controller/tsconfig.json @@ -0,0 +1,7 @@ +{ + "files": [], + "references": [ + { "path": "./tsconfig.host.json" }, + { "path": "./tsconfig.client.json" } + ] +} diff --git a/packages/api/job-controller/tsdown.config.ts b/packages/api/job-controller/tsdown.config.ts new file mode 100644 index 0000000000..0391bc61bf --- /dev/null +++ b/packages/api/job-controller/tsdown.config.ts @@ -0,0 +1,7 @@ +import { clientBundle } from '../../client/tsdown.client.ts' + +export default clientBundle( + '@deepseek-ai/dsh-api-job-controller', + ['lib/types/index.js'], + { hostPhase: true }, +) diff --git a/packages/api/remotes/package.json b/packages/api/remotes/package.json index a60099926e..6aabaa7039 100644 --- a/packages/api/remotes/package.json +++ b/packages/api/remotes/package.json @@ -62,8 +62,11 @@ "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-agent-presets": "workspace:^", "@deepseek-ai/dsh-api-gateway": "workspace:^", + "@deepseek-ai/dsh-api-job-controller": "workspace:^", + "@deepseek-ai/dsh-api-session-controller": "workspace:^", "@deepseek-ai/dsh-api-settings-controller": "workspace:^", "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", + "@deepseek-ai/dsh-client-connection": "workspace:^", "@deepseek-ai/dsh-commands": "workspace:^", "@deepseek-ai/dsh-cordis-host-runner": "workspace:^", "@deepseek-ai/dsh-credentials": "workspace:^", @@ -72,14 +75,12 @@ "@deepseek-ai/dsh-host-plugin-inventory": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-message-feedback": "workspace:^", + "@deepseek-ai/dsh-scope": "workspace:^", "@deepseek-ai/dsh-session-reference": "workspace:^", "@deepseek-ai/dsh-settings": "workspace:^", "@deepseek-ai/dsh-subagent": "workspace:^", - "@deepseek-ai/dsh-user-approval": "workspace:^", - "@deepseek-ai/dsh-user-questions": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", "@deepseek-ai/dsh-typert-protocol": "workspace:^", - "@deepseek-ai/dsh-scope": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^" + "@deepseek-ai/dsh-user-approval": "workspace:^", + "@deepseek-ai/dsh-user-questions": "workspace:^" } } diff --git a/packages/api/remotes/src/client/index.ts b/packages/api/remotes/src/client/index.ts index e7fc7757e9..ce08f3dbe3 100644 --- a/packages/api/remotes/src/client/index.ts +++ b/packages/api/remotes/src/client/index.ts @@ -12,6 +12,7 @@ import messageFeedbackRemote from '@deepseek-ai/dsh-message-feedback/remote' import sessionReferencesRemote from '@deepseek-ai/dsh-session-reference/remote' import subagentsRemote from '@deepseek-ai/dsh-subagent/remote' import sessionRemote from '@deepseek-ai/dsh-api-session-controller/remote' +import jobRemote from '@deepseek-ai/dsh-api-job-controller/remote' import workspaceRemote from '@deepseek-ai/dsh-api-workspace-controller/remote' import type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client' @@ -29,6 +30,8 @@ export type {} from '@deepseek-ai/dsh-subagent/remote' export type * from '@deepseek-ai/dsh-subagent/client' export type {} from '@deepseek-ai/dsh-api-session-controller/remote' export type * from '@deepseek-ai/dsh-api-session-controller/types' +export type {} from '@deepseek-ai/dsh-api-job-controller/remote' +export type * from '@deepseek-ai/dsh-api-job-controller/types' export type {} from '@deepseek-ai/dsh-api-workspace-controller/remote' export type * from '@deepseek-ai/dsh-api-workspace-controller/types' export type { SessionJob as JobView } from '@deepseek-ai/dsh-api-session-controller/types' @@ -146,7 +149,7 @@ export async function apply(ctx: Context): Promise<() => Promise> { for (const contribution of [ agentPresetsRemote, commandsRemote, settingsControllerRemote, goalsRemote, llmRemote, dynamicRemote, pluginInventoryRemote, messageFeedbackRemote, sessionReferencesRemote, - subagentsRemote, sessionRemote, workspaceRemote, + subagentsRemote, sessionRemote, jobRemote, workspaceRemote, ]) { disposers.push(await ctx.remote.$mount(contribution)) } diff --git a/packages/api/remotes/tsconfig.client.json b/packages/api/remotes/tsconfig.client.json index 56f664d499..ddd32b2af2 100644 --- a/packages/api/remotes/tsconfig.client.json +++ b/packages/api/remotes/tsconfig.client.json @@ -22,7 +22,6 @@ }, { "path": "../../credentials/credentials" - }, { "path": "../../context/file-reference" @@ -63,6 +62,9 @@ { "path": "../../interaction/user-questions" }, + { + "path": "../job-controller/tsconfig.client.json" + }, { "path": "../session-controller/tsconfig.client.json" }, diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml index 8bfe2650e7..fa85bc3ebe 100644 --- a/packages/api/session-controller/README.i18n.yaml +++ b/packages/api/session-controller/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/api/session-controller/README.md -README.md: 5f1e78b8d95d3fce99c5a533f05ccc6da1455a14 -README.zh.md: f4276b4f8940d66fbf6e76f3b4b49e55b51179d1 +README.md: 4f94607e70a5b963fa50d7a497afbcc97d273cb9 +README.zh.md: 455769f77ce8ad304949624de938e56579024145 diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md index 5f1e78b8d9..4f94607e70 100644 --- a/packages/api/session-controller/README.md +++ b/packages/api/session-controller/README.md @@ -29,7 +29,7 @@ Each endpoint states its activation policy. List, search, attachment, history pa The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, and `append` changes, and repairs reconnect or sequence gaps through a tail page. Backwards paging has two verbs: `loadOlder()` pulls one 50-message page, and `loadThrough(seq)` — the turn-jump loader — loops 200-message pages until the window covers the target seq, lowering a shared target on repeated calls, stopping on a page that makes no progress, and reporting busy through the same `loadingOlder` snapshot bit. Ordinary records cover `[event.seq, event.seq]`; packed rows cover `[event.seq, event.seq + memberCount - 1]`. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces queue, jobs, and projection state instead of treating transient values as durable events. -A `SessionJob` row carries `outputTotal` exactly when the job declared an observation record, and `session.observeJob` streams that record from an absolute byte offset — one `opened` anchor, coalesced `output` frames, then one terminal `status` — with the fenced read resolved from the request's session. Record reads are non-consuming: the model-facing cursor and completion-notice state never observe them. The Client adapter exposes `ctx.jobOutput`, the reference-counted per-job observation service whose accumulated views a task-list UI renders; observers share one stream per job and resume from their model cursor across reconnects. +A `SessionJob` row carries `outputTotal` exactly when the job declared an observation record; streaming that record is the job controller's `job.observe` (see [`dsh-api-job-controller`](../job-controller/README.md)), while this package keeps the roster on the control stream. The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. Session derives each echo's `transcript`, `queued`, or `steering` placement from its current running state and the requested delivery mode, then retains that placement while serialization is in flight. The prompt's `requestId` is the correlation identity: the Host echoes it as the durable user source's `rpcId`, and queue occurrences project it as `SessionQueuedItem.rpcId`. An echo retires one animation frame after its durable event or queue occurrence is observed (the delay keeps it renderable until the replacement is ready), immediately when its identified prompt fails or is abandoned, and as failed on disposal; each retirement fires the registered `onRetire` callback exactly once. Echoes are Client memory only; reload and reconnect rebuild the conversation from durable events alone. @@ -43,8 +43,6 @@ The Session object also carries local submission echoes: `session.beginSubmissio | `coldBlankProbeMaxEvents` | `16` | Maximum stat-reported event count of a cold Session eligible for blankness verification; `0` disables the event-count gate | | `coldBlankProbeMaxBytes` | `1,024` | Maximum stat-reported artifact byte size of a cold Session eligible for blankness verification when the backend offers no event count; `0` disables the byte-size gate | | `nativeOpen` | platform-detected | Whether Session workspace paths can be handed to a native desktop opener | -| `observeFlushMs` | `100` | Coalescing window after new record output before a job-observation read, in milliseconds | -| `observeMaxFrameBytes` | `65,536` | Soft byte budget per job-observation output frame; one larger chunk ships whole | The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-api-session-controller) is the exhaustive source for accepted fields and their JSDoc. diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md index f4276b4f89..455769f77c 100644 --- a/packages/api/session-controller/README.zh.md +++ b/packages/api/session-controller/README.zh.md @@ -29,7 +29,7 @@ kind: "package-reference" Client adapter 提供 `SessionEventStream`,即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow,只发布连续的 `replace`、`prepend` 和 `append` 变更,并通过 tail page 修复重连或 seq 缺口。向后分页有两个动词:`loadOlder()` 拉一页 50 条 message,而 `loadThrough(seq)`——轮次跳转加载器——按 200 条 message 一页循环拉取直到窗口覆盖目标 seq,重复调用会下调共享目标,遇到无进展的页即停止,忙碌状态复用同一个 `loadingOlder` 快照位。普通 record 覆盖 `[event.seq, event.seq]`,packed row 覆盖 `[event.seq, event.seq + memberCount - 1]`。业务、persistence 或无法恢复的连续性错误会终止 stream,只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`;每代都以完整的进程本地 baseline 开始,因此重连会替换 queue、jobs 和 projection 状态,而不会把瞬态值当作 durable event。 -`SessionJob` 行恰在该 job 声明了观测 record 时携带 `outputTotal`,`session.observeJob` 从绝对字节偏移流式发送该 record——一个 `opened` 锚帧、聚合的 `output` 帧、最后一个终态 `status` 帧——围栏读取者由请求的 session 解析。record 读取是非消耗的:模型侧游标与完成通知状态永远观察不到它们。Client adapter 提供 `ctx.jobOutput`:按 job 引用计数的观测服务,任务列表 UI 渲染其累积视图;同一 job 的观察者共享一条流,重连时从模型游标续读。 +`SessionJob` 行恰在该 job 声明了观测 record 时携带 `outputTotal`;流式发送该 record 的是 job 控制器的 `job.observe`(见 [`dsh-api-job-controller`](../job-controller/README.zh.md)),本包只在控制流上保留名册。 Session 对象还承载本地提交回显:`session.beginSubmission` 在调用方序列化与 prompt 之前,同步把一条回显写入 `SessionSnapshot.pendingSubmissions`,会话 UI 因此能在点击提交的当帧显示消息。Session 根据当前运行状态与请求的投递模式推导每条回显的 `transcript`、`queued` 或 `steering` 位置,并在序列化期间保留该位置。prompt 的 `requestId` 是关联标识:Host 把它回显为 durable user source 的 `rpcId`,queue occurrence 也把它投影为 `SessionQueuedItem.rpcId`。回显在观察到其 durable event 或 queue occurrence 后延迟一个动画帧退休,该延迟保证替代内容就绪前回显仍可渲染;带标识的 prompt 失败或被放弃时立即退休,销毁时按 failed 退休;每次退休恰好触发一次注册的 `onRetire` 回调。回显只存在于 Client 内存;刷新与重连只从 durable event 重建会话。 @@ -43,8 +43,6 @@ Session 对象还承载本地提交回显:`session.beginSubmission` 在调用 | `coldBlankProbeMaxEvents` | `16` | stat 报告的事件数不超过该值的冷 Session 才可进行空白状态验证;`0` 禁用事件数门槛 | | `coldBlankProbeMaxBytes` | `1,024` | 后端不提供事件数时,stat 报告的工件字节数不超过该值的冷 Session 才可进行空白状态验证;`0` 禁用字节数门槛 | | `nativeOpen` | 平台探测 | 是否能把 Session 工作区路径交给原生桌面打开器 | -| `observeFlushMs` | `100` | 新 record 输出到一次 job 观测读取之间的聚合窗口,毫秒 | -| `observeMaxFrameBytes` | `65,536` | 每个 job 观测输出帧的软字节预算;更大的单块整块发送 | 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-api-session-controller)是所有受支持字段及其 JSDoc 的完整来源。 diff --git a/packages/api/session-controller/src/client/index.ts b/packages/api/session-controller/src/client/index.ts index 5fc9570a55..4bad2bb8c2 100644 --- a/packages/api/session-controller/src/client/index.ts +++ b/packages/api/session-controller/src/client/index.ts @@ -3,7 +3,6 @@ import type { Context } from '@deepseek-ai/cordis' import type {} from '@deepseek-ai/dsh-agent/types' import { createSessionControlStream } from './transport.ts' -import { ClientJobOutput, ClientJobOutputModel } from './job-output.ts' import { ClientSessions } from './sessions/service.ts' import type { SessionRemotes } from './sessions/remotes.ts' import type {} from '../remote-events.ts' @@ -24,8 +23,6 @@ export type { } from './transport.ts' export { createScope, scopeOf } from './scope.ts' export type { AgentContext, AgentScopeHandle } from './scope.ts' -export { ClientJobOutput, ClientJobOutputModel } from './job-output.ts' -export type { IJobOutput, JobOutputSnapshot, JobOutputSource, ObservedJob } from './job-output.ts' export { SessionCreateError, SessionForkError } from './sessions/service.ts' export type { SessionBinding, SessionListState, SessionSummary } from './sessions/service.ts' export type { @@ -92,14 +89,6 @@ export const inject = [ export function apply(ctx: Context): void { const remotes = ctx.remote as unknown as SessionRemotes const sessions = new ClientSessions(ctx, remotes) - // Resolve the session namespace to a concrete value while this plugin's - // context is current: observation (re)opens run on caller stacks (a React - // event, a carrier retry) whose dynamic context has not declared - // `remote.session`, and a property access there fails the inject check. - new ClientJobOutput(ctx, { - $stream: options => remotes.$stream(options), - session: remotes.session, - }, new ClientJobOutputModel()) ctx.remote.$on('api-session/added', (summary) => { sessions.handleSessionAdded(summary) }) ctx.remote.$on('api-session/removed', (sessionId) => { sessions.handleSessionRemoved(sessionId) }) ctx.remote.$on('api-session/status', (sessionId, running) => { diff --git a/packages/api/session-controller/src/client/job-output.ts b/packages/api/session-controller/src/client/job-output.ts deleted file mode 100644 index 933c104497..0000000000 --- a/packages/api/session-controller/src/client/job-output.ts +++ /dev/null @@ -1,348 +0,0 @@ -/** - * React-free client job-record observation: per-job accumulated output views - * over the `session.observeJob` stream, reference-counted per job so - * overlapping panels share one stream. The roster itself rides the session - * control stream (`jobsBySession`); this module carries only the output. - * @module @deepseek-ai/dsh-api-session-controller/client/job-output - */ - -import { Service, type Context } from '@deepseek-ai/cordis' -import { RemoteStreamCarrierError, type ClientRemote } from '@deepseek-ai/dsh-api-gateway/client' -import { notifySubscribers } from '@deepseek-ai/dsh-client-store' -import type { JobId } from '@deepseek-ai/dsh-jobs/brand' -import type { SessionId } from '@deepseek-ai/dsh-session/types' -import type { SessionJob, SessionObserveJobFrame } from '../types.ts' -import type { SessionRemote } from './transport.ts' - -/** Bounded per-job render tail, in UTF-16 code units. */ -const RENDER_TAIL_LIMIT = 128 * 1024 - -/** One observed job's live view state. */ -export interface ObservedJob { - readonly jobId: JobId - /** Accumulated output tail, bounded to the render limit. */ - readonly text: string - /** True when bytes before {@link text} were dropped (eviction, resume gap, or the render bound). */ - readonly gapBefore: boolean - /** Latest status delivered on the observation stream. */ - readonly status: SessionJob['status'] - readonly detail?: string - /** True while the observation stream is open and the job has not settled. */ - readonly streaming: boolean - /** Terminal observation failure, when the stream ended abnormally. */ - readonly error?: string -} - -/** Immutable client job-output state. */ -export interface JobOutputSnapshot { - /** Live observation state keyed by job id. */ - readonly observed: Readonly> -} - -/** Mutable observation bookkeeping behind one {@link ObservedJob} view. */ -interface ObservedState { - view: ObservedJob - /** Resume offset for the next generation's `from`. */ - cursor: number | undefined -} - -/** - * Owns per-job observation state. Pure data plus subscriptions — transport - * wiring stays in the client service, UI stays in slot components. - */ -export class ClientJobOutputModel { - private readonly observedStates = new Map() - private readonly listeners = new Set<() => void>() - private snapshotCache: JobOutputSnapshot = { observed: {} } - private snapshotDirty = false - - /** - * Read the identity-stable current snapshot. - * @returns the cached snapshot, rebuilt only after a change. - */ - getSnapshot(): JobOutputSnapshot { - if (this.snapshotDirty) { - const observed: Record = {} - for (const [id, state] of this.observedStates) observed[id] = state.view - this.snapshotCache = { observed } - this.snapshotDirty = false - } - return this.snapshotCache - } - - /** - * Subscribe to snapshot changes. - * @param listener - invalidation callback. - * @returns unsubscribe function. - */ - subscribe(listener: () => void): () => void { - this.listeners.add(listener) - return () => { this.listeners.delete(listener) } - } - - /** - * The resume offset for one job's next observation generation. - * @param id - observed job. - * @returns the last accepted `next`, or undefined for a fresh observation. - */ - cursorOf(id: JobId): number | undefined { - return this.observedStates.get(String(id))?.cursor - } - - /** - * Install or reset observation state when a generation's anchor arrives. - * @param id - observed job. - * @param frame - the generation's `opened` anchor. - */ - observeOpened(id: JobId, frame: Extract): void { - const existing = this.observedStates.get(String(id)) - // A fresh view anchored past offset zero starts after an evicted head - // (fresh observations anchor at the registry's earliest retained byte), so - // it owes the same gap mark a live observer earned from lossy reads. A - // resume that already accumulated text keeps its recorded gap state. - const freshPastHead = (existing === undefined || existing.view.text === '') && frame.from > 0 - const view: ObservedJob = { - jobId: id, - text: existing?.view.text ?? '', - gapBefore: (existing?.view.gapBefore ?? false) || frame.from < frame.earliest || freshPastHead, - status: frame.status, - ...frame.detail !== undefined ? { detail: frame.detail } : {}, - streaming: true, - } - this.observedStates.set(String(id), { view, cursor: frame.from }) - this.changed() - } - - /** - * Append one output frame's chunks to the bounded render tail. - * @param id - observed job. - * @param frame - a coalesced `output` frame. - */ - observeOutput(id: JobId, frame: Extract): void { - const state = this.observedStates.get(String(id)) - /* v8 ignore next -- frames arrive only between opened and stop for a tracked id. */ - if (state === undefined) return - let text = state.view.text + frame.chunks.map(chunk => chunk.text).join('') - let gapBefore = state.view.gapBefore || frame.lossy === true - || frame.chunks.some(chunk => chunk.gapBefore === true) - if (text.length > RENDER_TAIL_LIMIT) { - let cut = text.length - RENDER_TAIL_LIMIT - // Never split a surrogate pair at the render bound. - const unit = text.charCodeAt(cut) - if (unit >= 0xDC00 && unit <= 0xDFFF) cut += 1 - text = text.slice(cut) - gapBefore = true - } - state.view = { ...state.view, text, gapBefore } - state.cursor = frame.next - this.changed() - } - - /** - * Record the terminal status delivered at the end of the observation stream. - * @param id - observed job. - * @param frame - the terminal `status` frame. - */ - observeStatus(id: JobId, frame: Extract): void { - const state = this.observedStates.get(String(id)) - /* v8 ignore next -- frames arrive only between opened and stop for a tracked id. */ - if (state === undefined) return - state.view = { - ...state.view, - status: frame.status, - ...frame.detail !== undefined ? { detail: frame.detail } : {}, - streaming: false, - } - this.changed() - } - - /** - * Record a terminal observation failure. - * @param id - observed job. - * @param error - the stream's terminal failure. - */ - observeFailed(id: JobId, error: unknown): void { - const state = this.observedStates.get(String(id)) - if (state === undefined) return - state.view = { ...state.view, streaming: false, error: String(error) } - this.changed() - } - - /** - * Drop observation state after the last observer stops. - * @param id - the no-longer-observed job. - */ - observeStopped(id: JobId): void { - if (!this.observedStates.delete(String(id))) return - this.changed() - } - - private changed(): void { - this.snapshotDirty = true - notifySubscribers(this.listeners, 'job output') - } -} - -/** Bare observable source for the client job-output snapshot. */ -export interface JobOutputSource { - /** Read the identity-stable current snapshot. */ - getSnapshot(): JobOutputSnapshot - /** - * Subscribe to snapshot changes. - * @param listener - invalidation callback. - * @returns unsubscribe function. - */ - subscribe(listener: () => void): () => void -} - -/** The job-output client service face. */ -export interface IJobOutput { - /** Per-job observation state. */ - readonly state: JobOutputSource - /** - * Start observing one job's live record; reference-counted, so two viewers - * of the same job share one stream. - * @param sessionId - owning session used for the fenced read; undefined for an unowned job. - * @param id - job to observe. - * @returns stop function releasing this observer's reference. - */ - observe(sessionId: SessionId | undefined, id: JobId): () => void -} - -/** One reference-counted observation stream. */ -interface ObservationEntry { - refs: number - stopped: boolean - dispose: () => Promise -} - -/** Remote face the observation runner drives. */ -type JobObserveRemote = Pick & { readonly session: Pick } - -declare module '@deepseek-ai/cordis' { - interface Context { - /** React-free client job-record observation control. */ - jobOutput: IJobOutput - } -} - -/** Owns the bare job-output snapshot and per-job observation streams. */ -export class ClientJobOutput extends Service implements IJobOutput { - readonly state: JobOutputSource - private readonly entries = new Map() - - /** - * @param ctx - client root Context. - * @param remote - generated session namespace plus the Gateway stream factory. - * @param model - shared client job-output model. - */ - constructor( - ctx: Context, - private readonly remote: JobObserveRemote, - private readonly model: ClientJobOutputModel, - ) { - super(ctx, 'jobOutput') - this.state = model - ctx.effect(() => () => { - const open = [...this.entries.values()] - this.entries.clear() - for (const entry of open) { - entry.stopped = true - void entry.dispose() - } - }, 'session-controller.client.observations') - } - - observe(sessionId: SessionId | undefined, id: JobId): () => void { - const key = String(id) - const existing = this.entries.get(key) - if (existing !== undefined && !existing.stopped) { - existing.refs += 1 - return this.releaser(key, existing) - } - const entry = this.startObservation(sessionId, id) - this.entries.set(key, entry) - return this.releaser(key, entry) - } - - /** - * Release closures bind the exact entry they were minted for, never the - * map's current occupant: a later `observe()` on the same id may have - * replaced a stopped entry, and decrementing or disposing through the key - * alone would tear down that newer stream's references. - */ - private releaser(key: string, entry: ObservationEntry): () => void { - let released = false - return () => { - if (released) return - released = true - entry.refs -= 1 - if (entry.refs > 0) return - if (this.entries.get(key) === entry) this.entries.delete(key) - entry.stopped = true - void entry.dispose().then(() => { - // Clear the view only while no successor observation holds the key: - // a re-expand inside the dispose round-trip already re-anchored the - // model, and a stale clear would blank its panel for good. - if (this.entries.has(key)) return - // The key is the stringified branded id this releaser was minted for. - this.model.observeStopped(key as JobId) - }) - } - } - - private startObservation(sessionId: SessionId | undefined, id: JobId): ObservationEntry { - const name = `job observation ${String(id)}` - const stream = this.remote.$stream({ - name, - open: (signal) => { - const from = this.model.cursorOf(id) - return this.remote.session.observeJob( - { - jobId: id, - ...sessionId !== undefined ? { sessionId } : {}, - ...from !== undefined ? { from } : {}, - }, - signal, - ) - }, - // A premature end after the anchor is retryable (a Host reload closes the - // generation); resuming from the cursor loses nothing. An end before the - // anchor is terminal. - ended: accepted => accepted - ? new RemoteStreamCarrierError(`${name} ended before settlement`) - : new Error(`${name} ended before its anchor`), - }) - const entry: ObservationEntry = { - refs: 1, - stopped: false, - dispose: () => stream.dispose(), - } - void (async () => { - try { - for await (const item of stream) { - const frame = item.value - if (frame.type === 'opened') { - this.model.observeOpened(id, frame) - item.accept() - continue - } - if (frame.type === 'output') { - this.model.observeOutput(id, frame) - continue - } - // Terminal status: leave the loop before the generation end is - // classified, then close the stream for good. - this.model.observeStatus(id, frame) - break - } - } catch (error) { - if (!entry.stopped) this.model.observeFailed(id, error) - } finally { - entry.stopped = true - void entry.dispose() - } - })() - return entry - } -} diff --git a/packages/api/session-controller/src/index.ts b/packages/api/session-controller/src/index.ts index b6dd8e08b5..1f8718e62f 100644 --- a/packages/api/session-controller/src/index.ts +++ b/packages/api/session-controller/src/index.ts @@ -2,7 +2,6 @@ import { Context } from '@deepseek-ai/cordis' import z from '@deepseek-ai/schemastery' -import type {} from '@deepseek-ai/dsh-jobs' import { errorChain } from '@deepseek-ai/dsh-llm' import { canOpenNativePath, openNativePath } from '@deepseek-ai/dsh-native-command' import type { SessionId } from '@deepseek-ai/dsh-session' @@ -17,7 +16,6 @@ import { import { SessionCommandController } from './commands.ts' import { SessionControlController } from './control.ts' import { SessionHistoryController } from './history.ts' -import { observeJobRecord } from './observe-job.ts' import { SessionFileReferences } from './file-references.ts' import { ApiSessionList, @@ -42,8 +40,6 @@ import type { SessionForkValue, SessionListRequest, SessionListValue, - SessionObserveJobFrame, - SessionObserveJobRequest, SessionOpenWorkspacePathRequest, SessionOpenWorkspacePathValue, SessionPage, @@ -72,12 +68,6 @@ declare module '@deepseek-ai/cordis' { } } -/** Default coalescing window between job-observation reads, in milliseconds. */ -const DEFAULT_OBSERVE_FLUSH_MS = 100 - -/** Default soft byte budget per job-observation output frame. */ -const DEFAULT_OBSERVE_MAX_FRAME_BYTES = 64 * 1024 - /** Session Controller deployment policy. */ export interface Config { /** Maximum stat-reported event count eligible for one full cold projection observation; `0` disables the event-count gate. */ @@ -86,10 +76,6 @@ export interface Config { readonly coldBlankProbeMaxBytes?: number /** Override platform desktop-opener detection. */ readonly nativeOpen?: boolean - /** Coalescing window after new record output before a job-observation read, in milliseconds (default 100). */ - readonly observeFlushMs?: number - /** Soft byte budget per job-observation output frame (default 65536); one larger chunk ships whole. */ - readonly observeMaxFrameBytes?: number } /** Host integrations replaceable by direct unit tests. */ @@ -118,8 +104,6 @@ export class SessionController extends TypertRemoteService { coldBlankProbeMaxEvents: z.natural().default(DEFAULT_COLD_BLANK_PROBE_MAX_EVENTS), coldBlankProbeMaxBytes: z.natural().default(DEFAULT_COLD_BLANK_PROBE_MAX_BYTES), nativeOpen: z.boolean(), - observeFlushMs: z.natural().min(1).default(DEFAULT_OBSERVE_FLUSH_MS), - observeMaxFrameBytes: z.natural().min(1).default(DEFAULT_OBSERVE_MAX_FRAME_BYTES), }) private readonly agents: ApiSessionAgentController @@ -130,8 +114,6 @@ export class SessionController extends TypertRemoteService { private readonly openPath: (path: string, signal: AbortSignal) => Promise private readonly canOpenPath: () => boolean private readonly promotions = new Set>() - private readonly observeFlushMs: number - private readonly observeMaxFrameBytes: number /** * @param ctx - Host context containing the Session capability assembly. @@ -157,8 +139,6 @@ export class SessionController extends TypertRemoteService { this.openPath = internals.openPath ?? openNativePath this.canOpenPath = internals.canOpenPath ?? (() => config.nativeOpen ?? (internals.openPath !== undefined || canOpenNativePath())) - this.observeFlushMs = config.observeFlushMs ?? DEFAULT_OBSERVE_FLUSH_MS - this.observeMaxFrameBytes = config.observeMaxFrameBytes ?? DEFAULT_OBSERVE_MAX_FRAME_BYTES ctx.plugin(SessionFileReferences) ctx.plugin(SessionSkillCatalog) @@ -419,29 +399,6 @@ export class SessionController extends TypertRemoteService { return this.controlState.control(signal) } - /** - * Stream one job's retained record output from an absolute byte offset, - * then its terminal status once settled and drained. Non-consuming: the - * model-facing cursor and notice state never observe these reads. The - * request's session resolves the fenced-read caller; the registry rejects a - * job the session does not own, a job without a record, or an unknown job. - * @param request - target job, owning session, and optional resume offset. - * @param signal - cancellation owned by the Remote stream carrier. - * @returns anchor, coalesced output frames, and the terminal status. - */ - @Remote({ mode: 'stream' }) - observeJob(request: SessionObserveJobRequest, signal: AbortSignal): AsyncIterable { - const registry = this.ctx.get('jobs') - if (registry === undefined) { - throw new Error('job observation unavailable: no job registry is loaded (load @deepseek-ai/dsh-jobs-local)') - } - const caller = request.sessionId === undefined ? undefined : this.ctx.agents.get(request.sessionId) - return observeJobRecord(registry, request, { - flushMs: this.observeFlushMs, - maxFrameBytes: this.observeMaxFrameBytes, - caller, - }, signal) - } } diff --git a/packages/api/session-controller/src/types.ts b/packages/api/session-controller/src/types.ts index b02c69ede8..c5a6caeacb 100644 --- a/packages/api/session-controller/src/types.ts +++ b/packages/api/session-controller/src/types.ts @@ -491,7 +491,7 @@ export interface SessionJob { /** * Total UTF-8 bytes the job's observation record holds so far. Present * exactly when the job declared a record — the row is observable through - * `session.observeJob`. + * the job controller's `job.observe` stream. */ readonly outputTotal?: number } @@ -518,62 +518,7 @@ export type SessionControlFrame = | { readonly type: 'jobs'; readonly sessionId: SessionId; readonly jobs: readonly SessionJob[] } | ({ readonly type: 'projection' } & SessionProjectionUpdate) -/** Opens one observation stream over a job's retained record output. */ -export interface SessionObserveJobRequest { - /** Owning session used for the fenced read; omitted for an unowned job. */ - readonly sessionId?: SessionId - readonly jobId: JobId - /** - * Absolute byte offset to resume from — a previous frame's `next`. Omitted - * starts at the oldest retained byte. - */ - readonly from?: number -} -/** One retained record chunk on the wire. `channel` widens to string like `kind`. */ -export interface SessionJobWireChunk { - /** Absolute offset of the chunk's first byte. */ - readonly at: number - readonly text: string - readonly channel?: string - /** Bytes immediately before this chunk were lost at the producer or to retention. */ - readonly gapBefore?: true -} - -/** - * Job observation stream frames: one `opened` anchor, then coalesced `output` - * batches, then — once the job has settled and its retained record is - * drained — one terminal `status`, after which the stream closes normally. - * Status rides the same stream as output so settlement can never race a - * still-open output channel. - */ -export type SessionObserveJobFrame = - | { - readonly type: 'opened' - readonly jobId: JobId - /** Offset the first `output` frame continues from. */ - readonly from: number - /** Oldest retained byte at open time; `from < earliest` means the head is gone. */ - readonly earliest: number - /** Total bytes produced at open time. */ - readonly total: number - readonly status: SessionJob['status'] - readonly detail?: string - } - | { - readonly type: 'output' - readonly chunks: readonly SessionJobWireChunk[] - /** Offset to resume from after this frame. */ - readonly next: number - /** Bytes between the requested offset and `chunks` were already evicted. */ - readonly lossy?: true - } - | { - readonly type: 'status' - readonly status: SessionJob['status'] - readonly detail?: string - readonly finishedAt?: number - } declare module '@deepseek-ai/cordis' { interface Events { diff --git a/packages/api/session-controller/tests/client-apply.client.spec.ts b/packages/api/session-controller/tests/client-apply.client.spec.ts index b3fd854a68..07f88b1a4f 100644 --- a/packages/api/session-controller/tests/client-apply.client.spec.ts +++ b/packages/api/session-controller/tests/client-apply.client.spec.ts @@ -106,18 +106,6 @@ async function flush(): Promise { } describe('Session Controller Client apply', () => { - it('installs ctx.jobOutput over the captured session namespace', async () => { - const bench = await mount() - expect(bench.ctx.jobOutput).toBeDefined() - // The fake observeJob never yields; opening and releasing must leave no - // view and no error behind. - const stop = bench.ctx.jobOutput.observe(sid('session-1'), 'bash-1' as never) - await flush() - stop() - await flush() - expect(bench.ctx.jobOutput.state.getSnapshot().observed).toEqual({}) - }) - it('routes Session Remote Events and connection generations into the object layer', async () => { const connected = vi.spyOn(ClientSessions.prototype, 'handleConnected') const error = vi.spyOn(ClientSessions.prototype, 'handleSessionError') diff --git a/packages/api/session-controller/tests/fake-api.client.ts b/packages/api/session-controller/tests/fake-api.client.ts index e67650d4a2..e3ea48f783 100644 --- a/packages/api/session-controller/tests/fake-api.client.ts +++ b/packages/api/session-controller/tests/fake-api.client.ts @@ -10,7 +10,7 @@ import type { import type { SessionAddress, SessionControlBaseline, - SessionControlFrame, SessionObserveJobFrame, + SessionControlFrame, SessionFollowFrame, SessionFollowRequest, SessionPage, @@ -235,9 +235,6 @@ export class FakeApiClient { page: request => this.page(request), follow: (request, signal) => this.openFollow(request, signal), control: signal => this.openControl(signal), - // Job-record observation never yields here; the stream consumer is - // exercised directly by job-output.client.spec. - observeJob: () => (async function* (): AsyncGenerator {})(), }, subagents: { list: parentSessionId => this.record( diff --git a/packages/api/session-controller/tests/test-remote.ts b/packages/api/session-controller/tests/test-remote.ts index be09dd8d80..1b5859b509 100644 --- a/packages/api/session-controller/tests/test-remote.ts +++ b/packages/api/session-controller/tests/test-remote.ts @@ -40,8 +40,6 @@ import type { SessionFollowRequest, SessionListRequest, SessionListValue, - SessionObserveJobFrame, - SessionObserveJobRequest, SessionOpenWorkspacePathRequest, SessionOpenWorkspacePathValue, SessionPage, @@ -79,7 +77,6 @@ export interface TestSessionRemote { page(request: SessionPageRequest, signal?: AbortSignal): Promise> follow(request: SessionFollowRequest, signal?: AbortSignal): AsyncIterable control(signal?: AbortSignal): AsyncIterable - observeJob(request: SessionObserveJobRequest, signal?: AbortSignal): AsyncIterable } /** Dependencies and policy supplied by a Session Controller unit harness. */ @@ -332,6 +329,5 @@ export function createSessionTestRemote( ), follow: (request, signal = new AbortController().signal) => direct.follow(request, signal), control: (signal = new AbortController().signal) => direct.control(signal), - observeJob: (request, signal = new AbortController().signal) => direct.observeJob(request, signal), } } diff --git a/packages/api/session-controller/tsconfig.host.json b/packages/api/session-controller/tsconfig.host.json index 086ab4a66f..d13a698f67 100644 --- a/packages/api/session-controller/tsconfig.host.json +++ b/packages/api/session-controller/tsconfig.host.json @@ -17,34 +17,83 @@ "src/history.ts", "src/list.ts", "src/model-selection-projection.ts", - "src/observe-job.ts", "src/skill-catalog.ts" ], "references": [ - { "path": "../../../vendor/cordis" }, - { "path": "../../../vendor/schemastery" }, - { "path": "../../core/agent" }, - { "path": "../../core/agent-default-model" }, - { "path": "../../core/scope" }, - { "path": "../../core/session" }, - { "path": "../../context/file-reference" }, - { "path": "../../attachment/attachment" }, - { "path": "../../interaction/permission-presets" }, - { "path": "../../jobs/jobs" }, - { "path": "../../llm/llm" }, - { "path": "../../util/deque" }, - { "path": "../../util/native-command" }, - { "path": "../../preset/agent-presets" }, - { "path": "../../session/session-persistence" }, - { "path": "../../session/session-projection" }, - { "path": "../../session/session-projection-cache" }, - { "path": "../../session/session-title" }, - { "path": "../../session-query/session-query" }, - { "path": "../../skill/skill" }, - { "path": "../../subagent/subagent" }, - { "path": "../../util/time" }, - { "path": "../../typert/protocol" }, - { "path": "../../typert/registry" }, - { "path": "../../workspace/workspace" } + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../../vendor/schemastery" + }, + { + "path": "../../core/agent" + }, + { + "path": "../../core/agent-default-model" + }, + { + "path": "../../core/scope" + }, + { + "path": "../../core/session" + }, + { + "path": "../../context/file-reference" + }, + { + "path": "../../attachment/attachment" + }, + { + "path": "../../interaction/permission-presets" + }, + { + "path": "../../jobs/jobs" + }, + { + "path": "../../llm/llm" + }, + { + "path": "../../util/deque" + }, + { + "path": "../../util/native-command" + }, + { + "path": "../../preset/agent-presets" + }, + { + "path": "../../session/session-persistence" + }, + { + "path": "../../session/session-projection" + }, + { + "path": "../../session/session-projection-cache" + }, + { + "path": "../../session/session-title" + }, + { + "path": "../../session-query/session-query" + }, + { + "path": "../../skill/skill" + }, + { + "path": "../../subagent/subagent" + }, + { + "path": "../../util/time" + }, + { + "path": "../../typert/protocol" + }, + { + "path": "../../typert/registry" + }, + { + "path": "../../workspace/workspace" + } ] } diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml index ef7539a7be..e7c42d038a 100644 --- a/packages/bundle/web-app/cordis.patch.yml +++ b/packages/bundle/web-app/cordis.patch.yml @@ -91,6 +91,11 @@ - id: session-controller name: '@deepseek-ai/dsh-api-session-controller' + # One background job's observation record streamed over Typert Remote; + # the roster rides the session control stream above. + - id: job-controller + name: '@deepseek-ai/dsh-api-job-controller' + # Configuration-surface reads and writes over Typert Remote. Each method # reports an actionable error when its settings-domain provider is absent. - id: settings-controller diff --git a/packages/bundle/web-app/package.json b/packages/bundle/web-app/package.json index 63f32d737e..5d8ce4524d 100644 --- a/packages/bundle/web-app/package.json +++ b/packages/bundle/web-app/package.json @@ -40,73 +40,74 @@ }, "dependencies": { "@deepseek-ai/dsh-agent-presets": "workspace:^", - "@deepseek-ai/dsh-tool-subagent": "workspace:^", + "@deepseek-ai/dsh-api-job-controller": "workspace:^", "@deepseek-ai/dsh-api-remotes": "workspace:^", + "@deepseek-ai/dsh-api-session-controller": "workspace:^", + "@deepseek-ai/dsh-api-settings-controller": "workspace:^", + "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", "@deepseek-ai/dsh-app-boot": "workspace:^", "@deepseek-ai/dsh-client-connection": "workspace:^", "@deepseek-ai/dsh-client-hmr": "workspace:^", "@deepseek-ai/dsh-client-locale": "workspace:^", "@deepseek-ai/dsh-client-modules": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", "@deepseek-ai/dsh-client-ui-agent-preset": "workspace:^", - "@deepseek-ai/dsh-client-ui-attachment": "workspace:^", "@deepseek-ai/dsh-client-ui-approval": "workspace:^", + "@deepseek-ai/dsh-client-ui-attachment": "workspace:^", "@deepseek-ai/dsh-client-ui-brand-official": "workspace:^", - "@deepseek-ai/dsh-client-ui-commands": "workspace:^", "@deepseek-ai/dsh-client-ui-chat": "workspace:^", + "@deepseek-ai/dsh-client-ui-commands": "workspace:^", "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", "@deepseek-ai/dsh-client-ui-cordis": "workspace:^", "@deepseek-ai/dsh-client-ui-deliverables": "workspace:^", "@deepseek-ai/dsh-client-ui-directory-picker-browse": "workspace:^", "@deepseek-ai/dsh-client-ui-directory-picker-native": "workspace:^", - "@deepseek-ai/dsh-client-ui-message-feedback": "workspace:^", "@deepseek-ai/dsh-client-ui-goal": "workspace:^", + "@deepseek-ai/dsh-client-ui-input-trigger": "workspace:^", + "@deepseek-ai/dsh-client-ui-jobs": "workspace:^", "@deepseek-ai/dsh-client-ui-layout": "workspace:^", + "@deepseek-ai/dsh-client-ui-message-feedback": "workspace:^", "@deepseek-ai/dsh-client-ui-model-selection": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings-models": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings-plugin-inventory": "workspace:^", "@deepseek-ai/dsh-client-ui-permission-presets": "workspace:^", "@deepseek-ai/dsh-client-ui-plan": "workspace:^", + "@deepseek-ai/dsh-client-ui-reference": "workspace:^", + "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", "@deepseek-ai/dsh-client-ui-schedule": "workspace:^", "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings-plugins": "workspace:^", - "@deepseek-ai/dsh-client-ui-user-questions": "workspace:^", "@deepseek-ai/dsh-client-ui-settings": "workspace:^", "@deepseek-ai/dsh-client-ui-settings-general": "workspace:^", + "@deepseek-ai/dsh-client-ui-settings-models": "workspace:^", + "@deepseek-ai/dsh-client-ui-settings-plugin-inventory": "workspace:^", + "@deepseek-ai/dsh-client-ui-settings-plugins": "workspace:^", "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^", "@deepseek-ai/dsh-client-ui-skill": "workspace:^", - "@deepseek-ai/dsh-client-ui-input-trigger": "workspace:^", - "@deepseek-ai/dsh-client-ui-reference": "workspace:^", "@deepseek-ai/dsh-client-ui-subagent": "workspace:^", - "@deepseek-ai/dsh-client-ui-jobs": "workspace:^", "@deepseek-ai/dsh-client-ui-theme": "workspace:^", "@deepseek-ai/dsh-client-ui-tool": "workspace:^", - "@deepseek-ai/dsh-client-ui-workflow-run": "workspace:^", "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^", + "@deepseek-ai/dsh-client-ui-user-questions": "workspace:^", + "@deepseek-ai/dsh-client-ui-workflow-run": "workspace:^", "@deepseek-ai/dsh-client-ui-workspace": "workspace:^", "@deepseek-ai/dsh-cmdline": "workspace:^", "@deepseek-ai/dsh-code-runtime-worker-thread": "workspace:^", "@deepseek-ai/dsh-cordis-client-runner": "workspace:^", "@deepseek-ai/dsh-cordis-host-runner": "workspace:^", - "@deepseek-ai/dsh-web-frontend": "workspace:^", - "@deepseek-ai/dsh-host-frontend-static": "workspace:^", + "@deepseek-ai/dsh-file-reference": "workspace:^", + "@deepseek-ai/dsh-file-reference-local": "workspace:^", "@deepseek-ai/dsh-host-directory-picker-auto": "workspace:^", "@deepseek-ai/dsh-host-directory-picker-browse": "workspace:^", "@deepseek-ai/dsh-host-directory-picker-native": "workspace:^", + "@deepseek-ai/dsh-host-frontend-static": "workspace:^", "@deepseek-ai/dsh-host-plugin-inventory": "workspace:^", "@deepseek-ai/dsh-host-webserver": "workspace:^", - "@deepseek-ai/dsh-file-reference": "workspace:^", - "@deepseek-ai/dsh-file-reference-local": "workspace:^", "@deepseek-ai/dsh-launch-environment": "workspace:^", "@deepseek-ai/dsh-message-feedback": "workspace:^", - "@deepseek-ai/dsh-session-reference": "workspace:^", "@deepseek-ai/dsh-session-log-export": "workspace:^", + "@deepseek-ai/dsh-session-reference": "workspace:^", "@deepseek-ai/dsh-session-stats": "workspace:^", "@deepseek-ai/dsh-session-turn-outline": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-api-settings-controller": "workspace:^", - "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", "@deepseek-ai/dsh-subprocess": "workspace:^", + "@deepseek-ai/dsh-tool-subagent": "workspace:^", + "@deepseek-ai/dsh-web-frontend": "workspace:^", "@deepseek-ai/dsh-workspace": "workspace:^", "@deepseek-ai/schemastery": "workspace:^", "commander": "^15.0.0", diff --git a/packages/client/ui-chat/src/client/contract/slots.ts b/packages/client/ui-chat/src/client/contract/slots.ts index 12557c1c73..eb2ed7cf83 100644 --- a/packages/client/ui-chat/src/client/contract/slots.ts +++ b/packages/client/ui-chat/src/client/contract/slots.ts @@ -2,8 +2,8 @@ import type { MessageId } from '@deepseek-ai/dsh-llm/brand' import type { SessionSeq } from '@deepseek-ai/dsh-session/types' import type { - ConversationLocationDataStore, ConversationTurnDataMap, - MessageImageLoader, MessageImagesOwnerProps, RenderMessageImages, TurnLocation, + CommandNode, CompactionSummaryNode, ConversationLocationDataStore, ConversationTurnDataMap, + MessageImageLoader, MessageImagesOwnerProps, RenderMessageImages, ToolCallBlock, TurnLocation, } from '@deepseek-ai/dsh-client-ui-conversation/client' import type { InjectFace, KeyedSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, @@ -16,8 +16,7 @@ import type { createChatStore } from '../stores.ts' import type { ToolCallId, SelectionTarget } from './store.ts' import type { ChatConversationViewNode, ChatNode, ChatNodeKind } from './chat-nodes.ts' import type { - ChatNodeProcessSource, ChatNodeSource, ChatSnapshot, ChatTurnProcessPresentation, CommandNode, - CompactionSummaryNode, ToolCallBlock, + ChatNodeProcessSource, ChatNodeSource, ChatSnapshot, ChatTurnProcessPresentation, } from './snapshot.ts' import type { TurnProcessSpec } from './turn-process.ts' import type { TranscriptViewMode } from '../../chat-settings.ts' diff --git a/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts b/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts index 6fa7671da6..64d74f28d8 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/chat-snapshot-builder.ts @@ -1,15 +1,14 @@ import type { Context } from '@deepseek-ai/cordis' import { notifySubscribers } from '@deepseek-ai/dsh-client-store' import type { - ConversationLocation, ConversationTimelineSnapshot, ConversationViewBuilder, - ConversationViewDefinition, + ConversationLocation, ConversationNode, ConversationTimelineSnapshot, ConversationViewBuilder, + ConversationViewDefinition, PartialAssistant, RunningToolCall, } from '@deepseek-ai/dsh-client-ui-conversation/client' import type { ChatConversationViewNode, ChatNode } from '../contract/chat-nodes.ts' import { isRunningTool } from '../contract/chat-nodes.ts' import type { ChatLocationNodeIndex, ChatNodeProcessSource, ChatNodeSource, ChatNodeStore, ChatSnapshot, - ChatTurnNavigationIndex, ChatTurnProcessPresentation, ConversationNode, LegacyConversationSlice, - PartialAssistant, RunningToolCall, TurnNavigationItem, + ChatTurnNavigationIndex, ChatTurnProcessPresentation, LegacyConversationSlice, TurnNavigationItem, } from '../contract/snapshot.ts' import { TURN_PROCESS_INDEPENDENT_KINDS } from '../contract/turn-process.ts' import { sessionRecallLabels } from './event-projection.ts' diff --git a/packages/client/ui-jobs/README.i18n.yaml b/packages/client/ui-jobs/README.i18n.yaml index b12c1d3926..fe508b8379 100644 --- a/packages/client/ui-jobs/README.i18n.yaml +++ b/packages/client/ui-jobs/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-jobs/README.md -README.md: 51e6916ed4a72fb8f618154bbd2ec156ad0af2bc -README.zh.md: f21e097e7860def07663376bf5de0f9d565a34c0 +README.md: a0ecc137ab1eb57aeaea9ccdfdbaf898794de2fe +README.zh.md: 744450c480b4d26c0558d992904817174ca2ed73 diff --git a/packages/client/ui-jobs/README.md b/packages/client/ui-jobs/README.md index 51e6916ed4..a0ecc137ab 100644 --- a/packages/client/ui-jobs/README.md +++ b/packages/client/ui-jobs/README.md @@ -33,7 +33,7 @@ The session control stream's `jobsBySession` mirror is the single roster: each ` ### The expanded panel -Expanding an observable row opens that job's record observation stream from `ctx.jobOutput` into an embedded terminal panel. The panel copies the command (not the output), wraps commands and output lines in full, scrolls its output inside a fixed height instead of folding, and draws no run-state dot of its own — the row above carries the state. Retention gaps and stream failures render as notices above the panel. +Expanding an observable row opens that job's record observation stream from `ctx.jobOutput` (installed by `dsh-api-job-controller`) into an embedded terminal panel. The panel copies the command (not the output), wraps commands and output lines in full, scrolls its output inside a fixed height instead of folding, and draws no run-state dot of its own — the row above carries the state. Retention gaps and stream failures render as notices above the panel. ----- @@ -58,7 +58,8 @@ One slot entry in the header actions band (after the preset label, before the su ## Further Exploration -- [`dsh-api-session-controller`](../../api/session-controller/README.md) — the `jobsBySession` mirror and the `session.observeJob` stream behind the panel. +- [`dsh-api-job-controller`](../../api/job-controller/README.md) — the `job.observe` stream and the `ctx.jobOutput` service behind the panel. +- [`dsh-api-session-controller`](../../api/session-controller/README.md) — the `jobsBySession` roster mirror the rows come from. - [`dsh-jobs`](../../jobs/jobs/README.md) — the registry contract that owns the record semantics. - [`dsh-client-ui-primitives`](../ui-primitives/README.md) — the `TerminalBlock` surface the panel configures. diff --git a/packages/client/ui-jobs/README.zh.md b/packages/client/ui-jobs/README.zh.md index f21e097e78..744450c480 100644 --- a/packages/client/ui-jobs/README.zh.md +++ b/packages/client/ui-jobs/README.zh.md @@ -33,7 +33,7 @@ session control 流的 `jobsBySession` 镜像是唯一名册:每个 `SessionJo ### 展开的面板 -展开可观察的行会从 `ctx.jobOutput` 打开该 job 的 record 观测流,注入内嵌终端面板。面板复制的是命令(不是输出),命令与输出行完整换行,输出在固定高度内滚动而非折叠,且不绘制自己的运行状态点——上方的行承载状态。保留缺口与流中断在面板上方渲染为提示。 +展开可观察的行会从 `ctx.jobOutput`(由 `dsh-api-job-controller` 安装)打开该 job 的 record 观测流,注入内嵌终端面板。面板复制的是命令(不是输出),命令与输出行完整换行,输出在固定高度内滚动而非折叠,且不绘制自己的运行状态点——上方的行承载状态。保留缺口与流中断在面板上方渲染为提示。 ----- @@ -58,7 +58,8 @@ session control 流的 `jobsBySession` 镜像是唯一名册:每个 `SessionJo ## 进一步探索 -- [`dsh-api-session-controller`](../../api/session-controller/README.zh.md) —— 面板背后的 `jobsBySession` 镜像与 `session.observeJob` 流。 +- [`dsh-api-job-controller`](../../api/job-controller/README.zh.md) —— 面板背后的 `job.observe` 流与 `ctx.jobOutput` 服务。 +- [`dsh-api-session-controller`](../../api/session-controller/README.zh.md) —— 行所来自的 `jobsBySession` 名册镜像。 - [`dsh-jobs`](../../jobs/jobs/README.zh.md) —— 拥有 record 语义的注册表契约。 - [`dsh-client-ui-primitives`](../ui-primitives/README.zh.md) —— 面板所配置的 `TerminalBlock` 表面。 diff --git a/packages/client/ui-jobs/package.json b/packages/client/ui-jobs/package.json index 885effb30c..fb85ed298d 100644 --- a/packages/client/ui-jobs/package.json +++ b/packages/client/ui-jobs/package.json @@ -35,6 +35,7 @@ }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", + "@deepseek-ai/dsh-api-job-controller": "workspace:^", "@deepseek-ai/dsh-api-session-controller": "workspace:^", "@deepseek-ai/dsh-client-locale": "workspace:^", "@deepseek-ai/dsh-client-test-runtime": "workspace:^", @@ -55,6 +56,7 @@ "dsh": { "client": { "inject": [ + "@deepseek-ai/dsh-api-job-controller", "@deepseek-ai/dsh-api-session-controller", "@deepseek-ai/dsh-client-locale", "@deepseek-ai/dsh-client-ui-conversation", diff --git a/packages/client/ui-jobs/src/client/JobListAction.tsx b/packages/client/ui-jobs/src/client/JobListAction.tsx index edac6497f6..87acb18a32 100644 --- a/packages/client/ui-jobs/src/client/JobListAction.tsx +++ b/packages/client/ui-jobs/src/client/JobListAction.tsx @@ -1,5 +1,5 @@ import { useEffect, useLayoutEffect, useMemo, useRef, useState, type KeyboardEvent } from 'react' -import type { JobOutputSnapshot, ObservedJob } from '@deepseek-ai/dsh-api-session-controller/client' +import type { JobOutputSnapshot, ObservedJob } from '@deepseek-ai/dsh-api-job-controller/client' import type { SessionJob } from '@deepseek-ai/dsh-api-session-controller/types' import type { SessionId } from '@deepseek-ai/dsh-session/types' import { diff --git a/packages/client/ui-jobs/src/client/index.ts b/packages/client/ui-jobs/src/client/index.ts index 164b6f6e3c..209cec1f23 100644 --- a/packages/client/ui-jobs/src/client/index.ts +++ b/packages/client/ui-jobs/src/client/index.ts @@ -8,6 +8,7 @@ import type { Context as ClientContext } from '@deepseek-ai/cordis' import { JobListAction } from './JobListAction.tsx' import type { JobListInjected } from './JobListAction.tsx' +import type {} from '@deepseek-ai/dsh-api-job-controller/client' import type {} from '@deepseek-ai/dsh-api-session-controller/client' import type {} from '@deepseek-ai/dsh-client-locale/client' import type {} from '@deepseek-ai/dsh-client-ui-renderer/client' diff --git a/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx b/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx index 15bd8ec4a9..9d659ca2ae 100644 --- a/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx +++ b/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx @@ -2,7 +2,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest' import { act, cleanup, fireEvent, render, screen, within } from '@testing-library/react' import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime' -import type { JobOutputSnapshot, ObservedJob } from '@deepseek-ai/dsh-api-session-controller/client' +import type { JobOutputSnapshot, ObservedJob } from '@deepseek-ai/dsh-api-job-controller/client' import type { SessionJob } from '@deepseek-ai/dsh-api-session-controller/types' import type { SessionId } from '@deepseek-ai/dsh-session/types' import { JobListAction, type JobListActionProps } from '../src/client/JobListAction.tsx' diff --git a/packages/client/ui-jobs/tsconfig.json b/packages/client/ui-jobs/tsconfig.json index 0e66aa4958..38756e4d88 100644 --- a/packages/client/ui-jobs/tsconfig.json +++ b/packages/client/ui-jobs/tsconfig.json @@ -8,6 +8,9 @@ "src" ], "references": [ + { + "path": "../../api/job-controller/tsconfig.client.json" + }, { "path": "../../api/session-controller/tsconfig.client.json" }, diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts index fa02cba58f..0daf030fdd 100644 --- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts +++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts @@ -204,7 +204,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ ], replaceRisk: 'none', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.assistant-actions\', () => ctx.slots.register(\n { name: \'conversation.chat.assistant-actions\', id: \'my-entry\', order: 100, label: \'My entry\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', - source: 'packages/client/ui-chat/src/client/contract/slots.ts:228', + source: 'packages/client/ui-chat/src/client/contract/slots.ts:227', }, { key: 'conversation.chat.commandview', @@ -249,7 +249,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ occupants: [], replaceRisk: 'none', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.commandview\', () => ctx.slots.register(\n { name: \'conversation.chat.commandview\', key: \'\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', - source: 'packages/client/ui-chat/src/client/contract/slots.ts:216', + source: 'packages/client/ui-chat/src/client/contract/slots.ts:215', }, { key: 'conversation.chat.node', @@ -314,7 +314,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ ], replaceRisk: 'shadows-shipped-ui', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.node\', () => ctx.slots.register(\n { name: \'conversation.chat.node\', key: \'\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', - source: 'packages/client/ui-chat/src/client/contract/slots.ts:197', + source: 'packages/client/ui-chat/src/client/contract/slots.ts:196', }, { key: 'conversation.chat.turnTail', @@ -359,7 +359,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ ], replaceRisk: 'none', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.chat.turnTail\', () => ctx.slots.register(\n { name: \'conversation.chat.turnTail\', select: owner => null },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', - source: 'packages/client/ui-chat/src/client/contract/slots.ts:222', + source: 'packages/client/ui-chat/src/client/contract/slots.ts:221', }, { key: 'conversation.composer', @@ -533,7 +533,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ ], replaceRisk: 'shadows-shipped-ui', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.details.tool\', () => ctx.slots.register(\n { name: \'conversation.details.tool\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', - source: 'packages/client/ui-chat/src/client/contract/slots.ts:234', + source: 'packages/client/ui-chat/src/client/contract/slots.ts:233', }, { key: 'conversation.hero.agentPreset', @@ -1011,7 +1011,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ ], replaceRisk: 'shadows-shipped-ui', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.message.images\', () => ctx.slots.register(\n { name: \'conversation.message.images\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', - source: 'packages/client/ui-chat/src/client/contract/slots.ts:210', + source: 'packages/client/ui-chat/src/client/contract/slots.ts:209', }, { key: 'conversation.session', diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 2d81832d71..9de2adb4c9 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -1033,6 +1033,19 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ }, ], }, + { + key: 'jobController', + summary: 'Host service backing the generated `ctx.remote.job` namespace.', + description: 'Host service backing the generated `ctx.remote.job` namespace.', + methods: [ + { + signature: '@Remote({ mode: \'stream\' }) observe(request: JobObserveRequest, signal: AbortSignal): AsyncIterable', + description: 'Stream one job\'s retained record output from an absolute byte offset, then its terminal status once settled and drained. Non-consuming: the model-facing cursor and notice state never observe these reads. The request\'s session resolves the fenced-read caller; the registry rejects a job the session does not own, a job without a record, or an unknown job.', + parameters: [{ name: 'request', description: 'target job, owning session, and optional resume offset.' }, { name: 'signal', description: 'cancellation owned by the Remote stream carrier.' }], + returns: 'anchor, coalesced output frames, and the terminal status.', + }, + ], + }, { key: 'jobs', summary: 'Abstract background job registry.', @@ -1455,12 +1468,6 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ parameters: [{ name: 'signal', description: 'cancellation owned by the Remote stream carrier.' }], returns: 'one complete baseline followed by live replacement frames.', }, - { - signature: '@Remote({ mode: \'stream\' }) observeJob(request: SessionObserveJobRequest, signal: AbortSignal): AsyncIterable', - description: 'Stream one job\'s retained record output from an absolute byte offset, then its terminal status once settled and drained. Non-consuming: the model-facing cursor and notice state never observe these reads. The request\'s session resolves the fenced-read caller; the registry rejects a job the session does not own, a job without a record, or an unknown job.', - parameters: [{ name: 'request', description: 'target job, owning session, and optional resume offset.' }, { name: 'signal', description: 'cancellation owned by the Remote stream carrier.' }], - returns: 'anchor, coalesced output frames, and the terminal status.', - }, ], }, { @@ -4190,6 +4197,18 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'JobKindMap', declaration: 'export interface JobKindMap {\n bash: \'bash\';\n subagent: \'subagent\';\n}', }, + { + name: 'JobObserveFrame', + declaration: 'export type JobObserveFrame = {\n readonly type: \'opened\';\n readonly jobId: JobId;\n readonly from: number;\n readonly earliest: number;\n readonly total: number;\n readonly status: JobObserveStatus;\n readonly detail?: string;\n} | {\n readonly type: \'output\';\n readonly chunks: readonly JobWireChunk[];\n readonly next: number;\n readonly lossy?: true;\n} | {\n readonly type: \'status\';\n readonly status: JobObserveStatus;\n readonly detail?: string;\n readonly finishedAt?: number;\n};', + }, + { + name: 'JobObserveRequest', + declaration: 'export interface JobObserveRequest {\n readonly sessionId?: SessionId;\n readonly jobId: JobId;\n readonly from?: number;\n}', + }, + { + name: 'JobObserveStatus', + declaration: 'export type JobObserveStatus = \'running\' | \'stopping\' | \'completed\' | \'killed\' | \'failed\';', + }, { name: 'JobOutcome', declaration: 'export interface JobOutcome {\n status: \'completed\' | \'killed\' | \'failed\';\n detail?: string;\n output?: string;\n}', @@ -4226,6 +4245,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'JobStatus', declaration: 'export type JobStatus = \'running\' | \'stopping\' | \'completed\' | \'killed\' | \'failed\';', }, + { + name: 'JobWireChunk', + declaration: 'export interface JobWireChunk {\n readonly at: number;\n readonly text: string;\n readonly channel?: string;\n readonly gapBefore?: true;\n}', + }, { name: 'JsonSchemaNode', declaration: 'export interface JsonSchemaNode {\n type?: JsonSchemaType;\n oneOf?: JsonSchemaNode[];\n properties?: Record;\n required?: string[];\n additionalProperties?: boolean;\n items?: JsonSchemaNode;\n enum?: JsonSchemaScalar[];\n const?: JsonSchemaScalar;\n description?: string;\n title?: string;\n default?: JsonValue;\n examples?: JsonValue;\n}', @@ -4966,10 +4989,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'SessionJob', declaration: 'export interface SessionJob {\n readonly id: JobId;\n readonly kind: string;\n readonly label: string;\n readonly status: \'running\' | \'stopping\' | \'completed\' | \'killed\' | \'failed\';\n readonly detail?: string;\n readonly startedAt: number;\n readonly finishedAt?: number;\n readonly outputTotal?: number;\n}', }, - { - name: 'SessionJobWireChunk', - declaration: 'export interface SessionJobWireChunk {\n readonly at: number;\n readonly text: string;\n readonly channel?: string;\n readonly gapBefore?: true;\n}', - }, { name: 'SessionLineageNode', declaration: 'export interface SessionLineageNode {\n session: SessionRecord;\n descendants: SessionLineageNode[];\n}', @@ -5002,14 +5021,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'SessionObservationOptions', declaration: 'export interface SessionObservationOptions {\n readonly signal?: AbortSignal;\n readonly projectionMode?: \'all\' | \'none\';\n}', }, - { - name: 'SessionObserveJobFrame', - declaration: 'export type SessionObserveJobFrame = {\n readonly type: \'opened\';\n readonly jobId: JobId;\n readonly from: number;\n readonly earliest: number;\n readonly total: number;\n readonly status: SessionJob[\'status\'];\n readonly detail?: string;\n} | {\n readonly type: \'output\';\n readonly chunks: readonly SessionJobWireChunk[];\n readonly next: number;\n readonly lossy?: true;\n} | {\n readonly type: \'status\';\n readonly status: SessionJob[\'status\'];\n readonly detail?: string;\n readonly finishedAt?: number;\n};', - }, - { - name: 'SessionObserveJobRequest', - declaration: 'export interface SessionObserveJobRequest {\n readonly sessionId?: SessionId;\n readonly jobId: JobId;\n readonly from?: number;\n}', - }, { name: 'SessionOpenWorkspacePathRequest', declaration: 'export interface SessionOpenWorkspacePathRequest {\n readonly path: string;\n}', diff --git a/packages/jobs/jobs/src/pump.ts b/packages/jobs/jobs/src/pump.ts index 8f56b6abc6..3d7d252d24 100644 --- a/packages/jobs/jobs/src/pump.ts +++ b/packages/jobs/jobs/src/pump.ts @@ -17,7 +17,19 @@ export interface JobPumpRead { lossy: boolean } -/** One producer-owned stream the pump copies into a job record. */ +/** + * One producer-owned stream the pump copies into a job record. + * + * The source is a pull-by-offset snapshot reader, not a Node.js `Readable`, + * because the substrate it reads (the subprocess `readFrom` family) is a + * retained ring that several readers share: the model-facing consuming + * cursor, the foreground result collector, and this record pump each hold + * their own absolute offset and read without disturbing the others. A + * `Readable` is single-consumer and consuming, so wrapping the ring in one + * would need a tee per reader and could not express `lossy` — the reader's + * offset having slid out of the retained window — which the record turns + * into a visible `gapBefore` instead of a silent splice. + */ export interface JobPumpSource { /** Stream label attached to every chunk this source yields. */ channel?: JobChannel diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index e03d24425c..181c30268c 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -665,6 +665,46 @@ importers: specifier: ^4.4.3 version: 4.4.3 + packages/api/job-controller: + dependencies: + '@deepseek-ai/dsh-typert-protocol': + specifier: workspace:^ + version: link:../../typert/protocol + '@deepseek-ai/schemastery': + specifier: link:../../../vendor/schemastery + version: link:../../../vendor/schemastery + zod: + specifier: ^4.4.3 + version: 4.4.3 + devDependencies: + '@deepseek-ai/cordis': + specifier: workspace:^ + version: link:../../../vendor/cordis + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../../core/agent + '@deepseek-ai/dsh-api-gateway': + specifier: workspace:^ + version: link:../gateway + '@deepseek-ai/dsh-client-connection': + specifier: workspace:^ + version: link:../../client/connection + '@deepseek-ai/dsh-client-store': + specifier: workspace:^ + version: link:../../client/store + '@deepseek-ai/dsh-jobs': + specifier: workspace:^ + version: link:../../jobs/jobs + '@deepseek-ai/dsh-jobs-local': + specifier: workspace:^ + version: link:../../jobs/jobs-local + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session + '@deepseek-ai/dsh-typert-registry': + specifier: workspace:^ + version: link:../../typert/registry + packages/api/remotes: dependencies: '@deepseek-ai/dsh-deque': @@ -686,6 +726,9 @@ importers: '@deepseek-ai/dsh-api-gateway': specifier: workspace:^ version: link:../gateway + '@deepseek-ai/dsh-api-job-controller': + specifier: workspace:^ + version: link:../job-controller '@deepseek-ai/dsh-api-session-controller': specifier: workspace:^ version: link:../session-controller @@ -1446,6 +1489,9 @@ importers: '@deepseek-ai/dsh-agent-presets': specifier: workspace:^ version: link:../../preset/agent-presets + '@deepseek-ai/dsh-api-job-controller': + specifier: workspace:^ + version: link:../../api/job-controller '@deepseek-ai/dsh-api-remotes': specifier: workspace:^ version: link:../../api/remotes @@ -2507,6 +2553,9 @@ importers: '@deepseek-ai/cordis': specifier: workspace:^ version: link:../../../vendor/cordis + '@deepseek-ai/dsh-api-job-controller': + specifier: workspace:^ + version: link:../../api/job-controller '@deepseek-ai/dsh-api-session-controller': specifier: workspace:^ version: link:../../api/session-controller diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index 4dde46a13a..ac52455c6d 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -109,6 +109,7 @@ export const SERVICE_PAGE: Record = { subprocess: 'subprocess.md', systemPrompt: 'system-prompt.md', jobs: 'jobs.md', + jobController: 'jobs.md', sessionTelemetry: 'session-telemetry.md', agentTeams: 'agent-team.md', tokenMeter: 'token-meter.md', @@ -173,7 +174,7 @@ export const SERVICE_WALK_EXEMPTIONS: Record = { slots: 'client-side interface-typed browser service — packages/client/ui-renderer/README.md owns the API', theme: 'client-side interface-typed browser service — packages/client/ui-theme/README.md owns the API', workspaces: 'client-side interface-typed browser service — packages/api/workspace-controller/README.md owns the API', - jobOutput: 'client-side interface-typed browser service — packages/api/session-controller/README.md owns the API', + jobOutput: 'client-side interface-typed browser service — packages/api/job-controller/README.md owns the API', } /** @@ -324,8 +325,6 @@ export const LINK_MAP: Readonly> = { OptionalSessionSeq: 'session.md', SessionListRequest: 'session.md', SessionListValue: 'session.md', - SessionObserveJobFrame: 'session.md', - SessionObserveJobRequest: 'session.md', ModelCatalog: 'session.md', SessionOpenWorkspacePathRequest: 'session.md', SessionOpenWorkspacePathValue: 'session.md', @@ -508,7 +507,10 @@ export const LINK_MAP: Readonly> = { ToolProviderResult: 'system-prompt.md', JobDoneListener: 'jobs.md', JobId: 'jobs.md', + JobObserveFrame: 'jobs.md', + JobObserveRequest: 'jobs.md', JobRead: 'jobs.md', + JobWireChunk: 'jobs.md', JobSnapshot: 'jobs.md', JobStart: 'jobs.md', JobsChangedListener: 'jobs.md', diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index f97eb086ee..43ccb69a51 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -170,6 +170,13 @@ const SERVICE_ROLES: ServiceRole[] = [ mode: 'core', note: 'Lists the Session composition\'s user-invocable skills without activating a cold Agent.', }, + { + key: 'jobController', + pkg: 'api-job-controller', + title: 'Host job Remote controller', + mode: 'core', + note: 'Streams one background job\'s observation record over the generated Remote namespace; the roster stays on the session control stream.', + }, { key: 'credentialsController', pkg: 'api-settings-controller', @@ -576,7 +583,7 @@ const SERVICE_ROLES: ServiceRole[] = [ title: 'Background job registry', mode: 'seam', implementations: ['jobs-local'], - consumers: ['tool-bash', 'tool-pwsh', 'tool-terminal', 'tool-subagent', 'tool-jobs'], + consumers: ['tool-bash', 'tool-pwsh', 'tool-terminal', 'tool-subagent', 'tool-jobs', 'api-job-controller'], note: 'Producers (background bash/pwsh, PTY sends, and subagent delegations) register running work; record-declaring jobs additionally stream raw output for non-consuming observers; tool-jobs is the model-facing controller that reads, lists, and kills it; jobs-local is the process-local registry.', }, { diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts index 1cd954a9ca..9bb2cc7956 100644 --- a/scripts/verify-package-readme-model-experience.ts +++ b/scripts/verify-package-readme-model-experience.ts @@ -165,6 +165,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly> = { 'packages/test-support/llm-mock-server': { kind: 'none', reason: 'The test server substitutes provider wire behavior without invoking a real model.' }, 'packages/test-support/llm-replay': { kind: 'none', reason: 'The keyless adapter invokes no provider model.' }, 'packages/api/gateway': { kind: 'none', reason: 'Remote dispatch infrastructure; invoked business methods own any model-visible effect.' }, + 'packages/api/job-controller': { kind: 'none', reason: 'Job observation is browser and Host control state; it registers no prompt, tool, or session event.' }, 'packages/api/session-controller': { kind: 'none', reason: 'Session API and transport owner; invoked Agent commands own any model-visible effect.' }, 'packages/api/settings-controller': { kind: 'none', reason: 'Configuration-surface API owner; it registers no prompt, tool, or session event.' }, 'packages/api/workspace-controller': { kind: 'none', reason: 'Workspace API and state projection owner; it registers no prompt, tool, or session event.' }, diff --git a/tsconfig.base.json b/tsconfig.base.json index 0510427c3b..fc8d7e4e0f 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -45,6 +45,9 @@ "@deepseek-ai/dsh-api-gateway": ["./packages/api/gateway/src/index.ts"], "@deepseek-ai/dsh-api-gateway/client": ["./packages/api/gateway/src/client/index.ts"], "@deepseek-ai/dsh-api-gateway/types": ["./packages/api/gateway/src/types.ts"], + "@deepseek-ai/dsh-api-job-controller": ["./packages/api/job-controller/src/index.ts"], + "@deepseek-ai/dsh-api-job-controller/client": ["./packages/api/job-controller/src/client/index.ts"], + "@deepseek-ai/dsh-api-job-controller/types": ["./packages/api/job-controller/src/types.ts"], "@deepseek-ai/dsh-api-session-controller": ["./packages/api/session-controller/src/index.ts"], "@deepseek-ai/dsh-api-session-controller/client": ["./packages/api/session-controller/src/client/index.ts"], "@deepseek-ai/dsh-api-session-controller/types": ["./packages/api/session-controller/src/types.ts"], diff --git a/tsconfig.client.json b/tsconfig.client.json index bb6735bbc7..cc2c7ac7fd 100644 --- a/tsconfig.client.json +++ b/tsconfig.client.json @@ -58,6 +58,7 @@ { "path": "./packages/api/gateway/tsconfig.client.json" }, { "path": "./packages/api/session-controller/tsconfig.client.json" }, { "path": "./packages/api/workspace-controller/tsconfig.client.json" }, + { "path": "./packages/api/job-controller/tsconfig.client.json" }, { "path": "./packages/api/remotes/tsconfig.client.json" }, { "path": "./packages/extensions/cordis-client-runner" }, { "path": "./packages/extensions/ui-cordis" }, diff --git a/tsconfig.host.json b/tsconfig.host.json index c3c119a282..f8ae95c3d2 100644 --- a/tsconfig.host.json +++ b/tsconfig.host.json @@ -151,6 +151,7 @@ { "path": "./packages/typert/registry" }, { "path": "./packages/api/gateway/tsconfig.host.json" }, { "path": "./packages/api/remotes/tsconfig.host.json" }, + { "path": "./packages/api/job-controller/tsconfig.host.json" }, { "path": "./packages/api/session-controller/tsconfig.host.json" }, { "path": "./packages/api/settings-controller" }, { "path": "./packages/api/workspace-controller/tsconfig.host.json" }, From e42eb13655f6773906f21e3c229941faed533d4f Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Wed, 2 Sep 2026 22:58:24 +0800 Subject: [PATCH 022/100] test(web): drop the stray slash after the sourceRoot token in three prompt pins --- snapshots/web/cordis-tool-round/system-prompt.expected.md | 2 +- snapshots/web/fresh-round-trip/system-prompt.expected.md | 2 +- snapshots/web/ptc-round/system-prompt.expected.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/snapshots/web/cordis-tool-round/system-prompt.expected.md b/snapshots/web/cordis-tool-round/system-prompt.expected.md index 4b4a62c230..a7337e1dd2 100644 --- a/snapshots/web/cordis-tool-round/system-prompt.expected.md +++ b/snapshots/web/cordis-tool-round/system-prompt.expected.md @@ -1,6 +1,6 @@ You are an AI agent powered by DeepSeek Harness. -The DeepSeek Harness implementation checkout is at {{sourceRoot}}/. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself. +The DeepSeek Harness implementation checkout is at {{sourceRoot}}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself. You are interacting with the user through the DeepSeek Harness Web GUI at {{webUrl}}. When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. The browser provides no implicit DOM, route, or screenshot context. The client-plugin HMR receiver is active, but client-plugin changes reload without a refresh only while `pnpm run dev:web` is also running from this same checkout to rebuild their bundles; verify that watcher before promising automatic updates. Every other change — the apps/web shell and plain packages — requires rebuilding the affected Web artifacts and verifying this existing URL after a page refresh. Starting another server does not update this GUI. The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. Do not start a replacement server unless the user asks; if one is needed, use a managed background job and verify its exact URL. diff --git a/snapshots/web/fresh-round-trip/system-prompt.expected.md b/snapshots/web/fresh-round-trip/system-prompt.expected.md index b20c5e5f77..fda55c1dea 100644 --- a/snapshots/web/fresh-round-trip/system-prompt.expected.md +++ b/snapshots/web/fresh-round-trip/system-prompt.expected.md @@ -1,6 +1,6 @@ You are an AI agent powered by DeepSeek Harness. -The DeepSeek Harness implementation checkout is at {{sourceRoot}}/. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself. +The DeepSeek Harness implementation checkout is at {{sourceRoot}}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself. You are interacting with the user through the DeepSeek Harness Web GUI at {{webUrl}}. When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. The browser provides no implicit DOM, route, or screenshot context. The client-plugin HMR receiver is active, but client-plugin changes reload without a refresh only while `pnpm run dev:web` is also running from this same checkout to rebuild their bundles; verify that watcher before promising automatic updates. Every other change — the apps/web shell and plain packages — requires rebuilding the affected Web artifacts and verifying this existing URL after a page refresh. Starting another server does not update this GUI. The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. Do not start a replacement server unless the user asks; if one is needed, use a managed background job and verify its exact URL. diff --git a/snapshots/web/ptc-round/system-prompt.expected.md b/snapshots/web/ptc-round/system-prompt.expected.md index ab15ca15ac..fc9cac9176 100644 --- a/snapshots/web/ptc-round/system-prompt.expected.md +++ b/snapshots/web/ptc-round/system-prompt.expected.md @@ -1,6 +1,6 @@ You are an AI agent powered by DeepSeek Harness. -The DeepSeek Harness implementation checkout is at {{sourceRoot}}/. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself. +The DeepSeek Harness implementation checkout is at {{sourceRoot}}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself. You are interacting with the user through the DeepSeek Harness Web GUI at {{webUrl}}. When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. The browser provides no implicit DOM, route, or screenshot context. The client-plugin HMR receiver is active, but client-plugin changes reload without a refresh only while `pnpm run dev:web` is also running from this same checkout to rebuild their bundles; verify that watcher before promising automatic updates. Every other change — the apps/web shell and plain packages — requires rebuilding the affected Web artifacts and verifying this existing URL after a page refresh. Starting another server does not update this GUI. The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. Do not start a replacement server unless the user asks; if one is needed, use a managed background job and verify its exact URL. From 761282724b6ae6dbea39f9ad2dd4e5293ba67285 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 11:23:41 +0800 Subject: [PATCH 023/100] fix(jobs): constant pump waits, quiescent client disposal, record flag on the roster Review corrections on the observation record: - `pumpJobOutput` subscribes to `done` once and keeps one pending timer; racing the same pending promise every poll round retained a reaction per round for the life of the job. - The `ctx.jobOutput` effect disposer is async and awaits every open carrier's `dispose()`, so the fiber reports unloaded only once the old iterators are quiescent. - `SessionJob.record: true` replaces `outputTotal`: `append` never commits a roster change, so the mirrored count was stale while output flowed; the live offsets ride the observation stream's `opened` anchor. - The record is documented as a best-effort live preview whose cross-stream reordering is bounded by the poll interval. - The web e2e scenarios hold their background job on a test-owned barrier file instead of a wall-clock sleep, and each is one test rather than a chain sharing a job id. --- ...9-01-jobs-absorb-activity-record.i18n.yaml | 4 +-- .../2026-09-01-jobs-absorb-activity-record.md | 14 ++++++-- ...26-09-01-jobs-absorb-activity-record.zh.md | 14 ++++++-- apps/web/tests/background-job-list.e2e.ts | 34 +++++++++--------- apps/web/tests/live-job-stream.e2e.ts | 34 +++++++++--------- .../live-job-stream/settled.expected.md | 6 ++-- .../live-job-stream/streaming.expected.md | 6 ++-- docs/event-producer-consumer.i18n.yaml | 4 +-- docs/event-producer-consumer.md | 10 +++--- docs/event-producer-consumer.zh.md | 10 +++--- packages/api/job-controller/README.i18n.yaml | 4 +-- packages/api/job-controller/README.md | 3 +- packages/api/job-controller/README.zh.md | 3 +- .../api/job-controller/src/client/service.ts | 12 ++++--- .../job-controller/tests/model.client.spec.ts | 24 +++++++++++++ .../api/session-controller/README.i18n.yaml | 4 +-- packages/api/session-controller/README.md | 2 +- packages/api/session-controller/README.zh.md | 2 +- .../api/session-controller/src/control.ts | 2 +- packages/api/session-controller/src/types.ts | 9 ++--- .../tests/control-jobs.host.spec.ts | 5 +-- packages/client/ui-jobs/README.i18n.yaml | 4 +-- packages/client/ui-jobs/README.md | 2 +- packages/client/ui-jobs/README.zh.md | 2 +- .../ui-jobs/src/client/JobListAction.tsx | 2 +- .../tests/job-list-action.client.spec.tsx | 4 +-- .../extensions/tool-cordis/src/api-catalog.ts | 2 +- packages/jobs/jobs/src/pump.ts | 34 ++++++++++++------ packages/jobs/jobs/tests/service.spec.ts | 36 +++++++++++++++++++ packages/shell/tool-bash/README.i18n.yaml | 4 +-- packages/shell/tool-bash/README.md | 2 +- packages/shell/tool-bash/README.zh.md | 2 +- packages/shell/tool-bash/src/observe.ts | 3 ++ packages/shell/tool-pwsh/src/observe.ts | 3 ++ .../background-job-list/running.expected.md | 4 +-- .../background-job-list/settled.expected.md | 4 +-- 36 files changed, 212 insertions(+), 102 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml index 3a332e7121..f7cf077333 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.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 .agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md -2026-09-01-jobs-absorb-activity-record.md: aa147778d06133b61f79defae6f9f6807dd97f41 -2026-09-01-jobs-absorb-activity-record.zh.md: 12e8f4bbd909a480f1461433c58d7937a8d7c857 +2026-09-01-jobs-absorb-activity-record.md: c1a668f8a008948957e62b5acf1d9db141441885 +2026-09-01-jobs-absorb-activity-record.zh.md: a23f3cda4c8c53663a6aee99469297d6878539d1 diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md index aa147778d0..c1a668f8a0 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md @@ -18,8 +18,8 @@ The one activity without a job was the foreground workflow mirror. Everything el - **There is no `end`.** Job settlement — the producer outcome, a kill, or teardown — is the record's only close: it trims retention to the settled cap and fires the final `onOutput` signal. The dual-settlement pairing (`ActivityHandle.end` first-wins against teardown force-ends) is deleted, not reimplemented. - **`readRecord(id, from, caller)`** is the non-consuming multi-reader view (absolute UTF-8 offsets, `lossy` below the retained window), fenced like every other job read; it never marks the job `reported`. The model-facing `readOutput` cursor is untouched — the two projections serve different readers and stay separate by design. - **`jobs-local`** absorbs the chunk ring (`retainBytes` 256 KiB live, `settledRetainBytes` 16 KiB settled), and `pumpJobOutput` replaces `pumpActivityOutput` beside the seam. Producers fold the pump's final drain into `hooks.done` so the record holds its last bytes before settlement closes it. -- **The wire splits by role.** `SessionJob.outputTotal` (present exactly for record jobs) marks a row observable on the session control stream; `job.observe({sessionId?, jobId, from?})` on the `job` namespace of `api-job-controller` streams anchor/output/status frames with the fenced read resolved from the request's session. `api-activity-controller` is deleted; its roster stream is redundant (the jobs frames are the roster) and its observe machinery lives in `api-job-controller` (`observe.ts`, client `ctx.jobOutput`), which resolves its Remote faces in its own apply. -- **`ui-activity` returns to its upstream name `ui-jobs`** and renders one roster: `jobsBySession` rows, expandable exactly when `outputTotal` is present. The two-roster join is deleted. +- **The wire splits by role.** `SessionJob.record` (present exactly for record jobs) marks a row observable on the session control stream; `job.observe({sessionId?, jobId, from?})` on the `job` namespace of `api-job-controller` streams anchor/output/status frames with the fenced read resolved from the request's session. `api-activity-controller` is deleted; its roster stream is redundant (the jobs frames are the roster) and its observe machinery lives in `api-job-controller` (`observe.ts`, client `ctx.jobOutput`), which resolves its Remote faces in its own apply. +- **`ui-activity` returns to its upstream name `ui-jobs`** and renders one roster: `jobsBySession` rows, expandable exactly when `record` is present. The two-roster join is deleted. - **Foreground workflow loses its live panel deliberately.** `tool-workflow`'s activity mirror is removed; a foreground run surfaces through its recorded run/member lifecycle events only, and the per-line `workflow/phase` / `workflow/log` narration has no observer until workflow gains `run_in_background` and registers a record job. Jobs stay a pure background registry — no `foreground` mode bit, no model-invisible rows, no run-less rows. ## Alternatives considered @@ -30,6 +30,16 @@ The one activity without a job was the foreground workflow mirror. Everything el The [prior seam note](../feature/2026-08-24-activity-observation-seam.md)'s argument against durable session events and control-stream framing for live output still holds and carries over unchanged: the record is process-local observation state, never a session event, so "model-visible ⟺ logged" is untouched. +## Review corrections + +Review of the merged design settled five points that the sections above leave implicit: + +- **The pump's wait holds constant resources.** `pumpJobOutput` subscribes to the producer's `done` once and keeps one pending timer; settlement clears the timer and wakes the current wait. Racing the same pending promise every poll round retained a reaction per round until the job ended — a day-long job at the default cadence accumulated over a million closures. +- **Client disposal waits for carrier quiescence.** The `ctx.jobOutput` effect disposer is async and awaits every open `RemoteStream.dispose()`, because Cordis awaits async disposers and a fiber that reported unloaded while an old iterator was still closing could overlap the next plugin instance under HMR. +- **The roster flags a record, it does not count bytes.** `SessionJob.record: true` replaced `outputTotal`: `append` commits no roster change (only lifecycle commits fire `onJobsChanged`), so a mirrored count went stale the moment output arrived, and broadcasting the roster per append was rejected as traffic for a number no row needed. The live offsets ride the observation stream's `opened` anchor. +- **The record is a best-effort live preview.** Producers copy stdout and stderr per poll round, so writes inside one window land stdout first; pipe capture cannot recover the true interleaving (only a PTY or `2>&1` can), and the client concatenates chunks regardless of `channel`. `channel` stays on the wire because it is what makes that limit visible and what a distinct stderr rendering would need. +- **Web e2e keep-alive is a barrier, not a clock.** The background command holds on a file the test owns in the job's cwd and the scenario kills it explicitly, so no CI stall can settle the job first; each scenario is one test, never a chain of tests sharing a job id. + ## Consequences Every observable row is a killable job; a pure-observation surface with no lifecycle would need a new home (harness diagnostics belong to the inspector plane, not here). A future remote job provider must implement lifecycle and record together. The record's retention config lives on `jobs-local`; the observation wire's cadence config (`observeFlushMs`, `observeMaxFrameBytes`) lives on `api-job-controller`. diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md index 12e8f4bbd9..a23f3cda4c 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md @@ -18,8 +18,8 @@ Status: implemented - **没有 `end`。** job 结算——生产者 outcome、kill 或 teardown——是 record 唯一的关闭:裁剪到结算保留量并发出最后一个 `onOutput` 信号。双结算配对(`ActivityHandle.end` 与 teardown 强结的 first-wins 对账)被删除,而非重新实现。 - **`readRecord(id, from, caller)`** 是非消耗多读者视图(绝对 UTF-8 偏移,低于保留窗口为 `lossy`),围栏与其他 job 读取一致;永不置 `reported`。模型面的 `readOutput` 游标原样保留——两个投影服务不同读者,刻意保持分离。 - **`jobs-local`** 吸收块环(`retainBytes` 运行期 256 KiB,`settledRetainBytes` 结算后 16 KiB),`pumpJobOutput` 在 seam 旁替换 `pumpActivityOutput`。生产者把 pump 的末次排空折进 `hooks.done`,让 record 在结算关闭前握有最后的字节。 -- **wire 按角色拆分。** `SessionJob.outputTotal`(恰在 record job 上存在)在会话控制流上标记行可观测;`api-job-controller` 的 `job` 命名空间上的 `job.observe({sessionId?, jobId, from?})` 流式发送 anchor/output/status 帧,围栏读取者由请求的 session 解析。`api-activity-controller` 删除;其名册流是冗余的(jobs 帧就是名册),observe 机制位于 `api-job-controller`(`observe.ts`,客户端 `ctx.jobOutput`),它在自己的 apply 里解析所依赖的 Remote 面。 -- **`ui-activity` 改回上游名字 `ui-jobs`**,渲染单一名册:`jobsBySession` 行,恰在 `outputTotal` 存在时可展开。双名册 join 被删除。 +- **wire 按角色拆分。** `SessionJob.record`(恰在 record job 上存在)在会话控制流上标记行可观测;`api-job-controller` 的 `job` 命名空间上的 `job.observe({sessionId?, jobId, from?})` 流式发送 anchor/output/status 帧,围栏读取者由请求的 session 解析。`api-activity-controller` 删除;其名册流是冗余的(jobs 帧就是名册),observe 机制位于 `api-job-controller`(`observe.ts`,客户端 `ctx.jobOutput`),它在自己的 apply 里解析所依赖的 Remote 面。 +- **`ui-activity` 改回上游名字 `ui-jobs`**,渲染单一名册:`jobsBySession` 行,恰在 `record` 存在时可展开。双名册 join 被删除。 - **前台 workflow 有意失去实时面板。** `tool-workflow` 的 activity 镜像被移除;前台 run 只通过已记录的 run/member 生命周期事件呈现,逐行的 `workflow/phase` / `workflow/log` 叙述在 workflow 获得 `run_in_background` 并登记 record job 之前没有观察者。jobs 保持纯后台注册表——没有 `foreground` 模式位、没有模型不可见行、没有无 run 行。 ## 曾考虑的替代方案 @@ -30,6 +30,16 @@ Status: implemented [先前 seam note](../feature/2026-08-24-activity-observation-seam.zh.md) 反对用持久会话事件或 control 流承载实时输出的论证仍然成立并原样沿用:record 是进程本地观测状态,从不是会话事件,「模型可见 ⟺ 已记录」不受影响。 +## 评审修正 + +对已合并设计的评审确定了上文各节未言明的五点: + +- **泵的等待资源恒定。** `pumpJobOutput` 对生产者的 `done` 只订阅一次,同一时刻只保留一个待触发的 timer;结算清掉 timer 并唤醒当前等待。此前每个轮询轮次都对同一个 pending promise 赛跑,每轮留下一个 reaction 直到任务结束——默认节奏下跑一天的任务会累积上百万个闭包。 +- **客户端卸载等待载体静止。** `ctx.jobOutput` 的 effect disposer 是异步的,await 每条打开的 `RemoteStream.dispose()`:Cordis 会 await 异步 disposer,而一个在旧 iterator 仍在关闭时就宣告卸载完成的 fiber,在 HMR 下可能与下一个插件实例重叠。 +- **名册标记 record,不计字节。** `SessionJob.record: true` 取代了 `outputTotal`:`append` 不提交名册变更(只有生命周期提交触发 `onJobsChanged`),镜像的计数在输出到达的瞬间就陈旧了;而为一个没有任何行需要的数字按 append 广播整份名册被否决。实时偏移随观测流的 `opened` 锚帧到达。 +- **record 是尽力而为的实时预览。** 生产者按轮询轮次复制 stdout 与 stderr,同一窗口内的写入先 stdout 落地;pipe 捕获无法还原真实交错(只有 PTY 或 `2>&1` 可以),客户端拼接 chunk 时也不区分 `channel`。`channel` 留在 wire 上,因为它正是让这一限制可见、也是将来区分渲染 stderr 所需要的东西。 +- **Web e2e 的保活是 barrier 而非时钟。** 后台命令守在测试拥有的、位于 job cwd 的文件上,由场景显式 kill,因此 CI 卡顿不可能先把任务结算掉;每个场景是一个测试,绝不是共享 job id 的测试链。 + ## 后果 每个可观测行都是可 kill 的 job;没有生命周期的纯观测面需要新的归属(harness 诊断属于 inspector 平面,不在这里)。未来的远端 job provider 必须同时实现生命周期与 record。record 的保留配置在 `jobs-local`;观测 wire 的节奏配置(`observeFlushMs`、`observeMaxFrameBytes`)在 `api-job-controller`。 diff --git a/apps/web/tests/background-job-list.e2e.ts b/apps/web/tests/background-job-list.e2e.ts index 284b359eeb..96a7f4f833 100644 --- a/apps/web/tests/background-job-list.e2e.ts +++ b/apps/web/tests/background-job-list.e2e.ts @@ -1,6 +1,6 @@ // Session-header background jobs driven by a real `ctx.jobs` entry. No model // call is involved. -import { readFile } from 'node:fs/promises' +import { readFile, writeFile } from 'node:fs/promises' import { fileURLToPath } from 'node:url' import { join } from 'node:path' import type { Browser, Page } from 'playwright' @@ -22,9 +22,12 @@ const RUNNING_EXPECTED = join(SNAPSHOT_DIR, 'running.expected.md') const SETTLED_EXPECTED = join(SNAPSHOT_DIR, 'settled.expected.md') const MODE = webSnapshotMode() const SEED_ID = 'background-job-list-web-e2e' -// Long enough that the running assertions never race the process exiting on -// their own; the test kills it explicitly to reach the settled state. -const COMMAND = 'sleep 45' +// A hold on a barrier file the test owns in the job's cwd: the process never +// exits on its own, so no CI stall can settle it before the scenario kills it. +// The bounded loop only caps an orphan's lifetime if the runner dies before +// `afterAll` releases the barrier. +const RELEASE = '.background-job-list.release' +const COMMAND = `for _ in $(seq 1 3000); do [ -e ${RELEASE} ] && break; sleep 0.2; done` /** * Wait for opening a session to publish its live Agent. @@ -48,7 +51,6 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => { let page: Page let tripwire: ReturnType let agent: Agent - let jobId: JobId beforeAll(async () => { scaffold = await launchWebScaffold({}) @@ -73,12 +75,14 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => { }, 120_000) afterAll(async () => { + if (scaffold !== undefined) await writeFile(join(scaffold.workspaceCwd, RELEASE), '') await browser?.close() await scaffold?.close() }) - it('shows a running background job in the session header without a refresh', async () => { - onTestFailed(() => saveFailureShot(page, 'web-e2e-background-job-running')) + it('shows a running background job in the header without a refresh, then flips it to cancelled on settlement', async () => { + let phase = 'running' + onTestFailed(() => saveFailureShot(page, `web-e2e-background-job-${phase}`)) // Polling for zero would pass at t=0 before delivery and prove nothing. const trigger = page.getByRole('button', { name: '1 background job running' }) expect(await trigger.count()).toBe(0) @@ -93,7 +97,7 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => { const reported = started.content.map(block => block.type === 'text' ? block.text : '').join('') const matched = /\bbash-\d+\b/.exec(reported) if (matched === null) throw new Error(`background bash reported no job id: ${reported}`) - jobId = JobId(matched[0]) + const jobId = JobId(matched[0]) await trigger.waitFor({ timeout: 15_000 }) await trigger.click() @@ -101,24 +105,22 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => { await row.waitFor({ timeout: 10_000 }) await expect.poll(() => row.textContent()).toContain(COMMAND) - const snapshot = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd) - await compareOrRefreshGolden(RUNNING_EXPECTED, snapshot, MODE) + const running = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd) + await compareOrRefreshGolden(RUNNING_EXPECTED, running, MODE) expect(tripwire.pageErrors).toEqual([]) expect(tripwire.warnings).toEqual([]) - }, 60_000) - it('flips the open list to the cancelled outcome when the registry settles it', async () => { - onTestFailed(() => saveFailureShot(page, 'web-e2e-background-job-settled')) + phase = 'settled' expect(scaffold.ctx.jobs.kill(jobId, agent, 'web e2e cancellation')).toBe('requested') const idle = page.getByRole('button', { name: '1 background job', exact: true }) await idle.waitFor({ timeout: 20_000 }) - const snapshot = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd) - await compareOrRefreshGolden(SETTLED_EXPECTED, snapshot, MODE) + const settled = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd) + await compareOrRefreshGolden(SETTLED_EXPECTED, settled, MODE) expect(tripwire.pageErrors).toEqual([]) expect(tripwire.warnings).toEqual([]) - }, 60_000) + }, 90_000) it('keeps its snapshot inventory closed', async () => { await assertFixtureInventory(SNAPSHOT_DIR, ['running.expected.md', 'settled.expected.md']) diff --git a/apps/web/tests/live-job-stream.e2e.ts b/apps/web/tests/live-job-stream.e2e.ts index 65926f7463..83736763c6 100644 --- a/apps/web/tests/live-job-stream.e2e.ts +++ b/apps/web/tests/live-job-stream.e2e.ts @@ -2,7 +2,7 @@ // arrives over the session control stream, expanding it opens the record // observation stream, and the panel shows the process's real output while it // is still running. No model call is involved. -import { readFile } from 'node:fs/promises' +import { readFile, writeFile } from 'node:fs/promises' import { fileURLToPath } from 'node:url' import { join } from 'node:path' import type { Browser, Page } from 'playwright' @@ -24,9 +24,12 @@ const STREAMING_EXPECTED = join(SNAPSHOT_DIR, 'streaming.expected.md') const SETTLED_EXPECTED = join(SNAPSHOT_DIR, 'settled.expected.md') const MODE = webSnapshotMode() const SEED_ID = 'live-job-stream-web-e2e' -// One fixed line of early output, then silence long enough that the streaming -// assertions never race the process exiting; the test kills it explicitly. -const COMMAND = "printf 'streamed-%s\\n' marker-line; sleep 45" +// One fixed line of early output, then a hold on a barrier file the test owns +// in the job's cwd: the process never exits on its own, so no CI stall can +// settle it before the scenario kills it. The bounded loop only caps an +// orphan's lifetime if the runner dies before `afterAll` releases the barrier. +const RELEASE = '.live-job-stream.release' +const COMMAND = `printf 'streamed-%s\\n' marker-line; for _ in $(seq 1 3000); do [ -e ${RELEASE} ] && break; sleep 0.2; done` /** * Wait for opening a session to publish its live Agent. @@ -50,7 +53,6 @@ describe.skipIf(MODE === 'record')('web e2e: live job stream', () => { let page: Page let tripwire: ReturnType let agent: Agent - let jobId: JobId beforeAll(async () => { scaffold = await launchWebScaffold({}) @@ -74,12 +76,14 @@ describe.skipIf(MODE === 'record')('web e2e: live job stream', () => { }, 120_000) afterAll(async () => { + if (scaffold !== undefined) await writeFile(join(scaffold.workspaceCwd, RELEASE), '') await browser?.close() await scaffold?.close() }) - it('streams a running background command\'s real output into the expanded panel', async () => { - onTestFailed(() => saveFailureShot(page, 'web-e2e-live-job-streaming')) + it('streams a running job\'s real output into the expanded panel, then settles it in place on kill', async () => { + let phase = 'streaming' + onTestFailed(() => saveFailureShot(page, `web-e2e-live-job-${phase}`)) const trigger = page.getByRole('button', { name: '1 background job running' }) expect(await trigger.count()).toBe(0) @@ -93,7 +97,7 @@ describe.skipIf(MODE === 'record')('web e2e: live job stream', () => { const reported = started.content.map(block => block.type === 'text' ? block.text : '').join('') const matched = /\bbash-\d+\b/.exec(reported) if (matched === null) throw new Error(`background bash reported no job id: ${reported}`) - jobId = JobId(matched[0]) + const jobId = JobId(matched[0]) // The job row reaches the header over the session control stream. await trigger.waitFor({ timeout: 15_000 }) @@ -106,14 +110,12 @@ describe.skipIf(MODE === 'record')('web e2e: live job stream', () => { await expand.click() await page.getByText('streamed-marker-line').waitFor({ timeout: 15_000 }) - const snapshot = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd) - await compareOrRefreshGolden(STREAMING_EXPECTED, snapshot, MODE) + const streaming = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd) + await compareOrRefreshGolden(STREAMING_EXPECTED, streaming, MODE) expect(tripwire.pageErrors).toEqual([]) expect(tripwire.warnings).toEqual([]) - }, 60_000) - it('settles the open panel when the job is killed, keeping the streamed tail', async () => { - onTestFailed(() => saveFailureShot(page, 'web-e2e-live-job-settled')) + phase = 'settled' expect(scaffold.ctx.jobs.kill(jobId, agent, 'web e2e cancellation')).toBe('requested') // Settlement arrives on the observation stream itself, so the open panel @@ -122,11 +124,11 @@ describe.skipIf(MODE === 'record')('web e2e: live job stream', () => { await idle.waitFor({ timeout: 20_000 }) await page.getByText('streamed-marker-line').waitFor({ timeout: 10_000 }) - const snapshot = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd) - await compareOrRefreshGolden(SETTLED_EXPECTED, snapshot, MODE) + const settled = await captureStableAria(page, '[class*="menu"]', scaffold.workspaceCwd) + await compareOrRefreshGolden(SETTLED_EXPECTED, settled, MODE) expect(tripwire.pageErrors).toEqual([]) expect(tripwire.warnings).toEqual([]) - }, 60_000) + }, 90_000) it('keeps its snapshot inventory closed', async () => { await assertFixtureInventory(SNAPSHOT_DIR, ['settled.expected.md', 'streaming.expected.md']) diff --git a/apps/web/tests/snapshots/live-job-stream/settled.expected.md b/apps/web/tests/snapshots/live-job-stream/settled.expected.md index 6ba8ada46d..4c3fdfc70f 100644 --- a/apps/web/tests/snapshots/live-job-stream/settled.expected.md +++ b/apps/web/tests/snapshots/live-job-stream/settled.expected.md @@ -1,8 +1,8 @@ - list "Background jobs": - listitem: - - button "Hide live output of printf 'streamed-%s\\n' marker-line; sleep 45" [expanded]: - - text: "bash printf 'streamed-%s\\n' marker-line; sleep 45 signal: SIGTERM {{duration}}" + - button "Hide live output of printf 'streamed-%s\\n' marker-line; for _ in $(seq 1 3000); do [ -e .live-job-stream.release ] && break; sleep 0.2; done" [expanded]: + - text: "bash printf 'streamed-%s\\n' marker-line; for _ in $(seq 1 3000); do [ -e .live-job-stream.release ] && break; sleep 0.2; done signal: SIGTERM {{duration}}" - img - - text: $ printf 'streamed-%s\n' marker-line; sleep 45 + - text: $ printf 'streamed-%s\n' marker-line; for _ in $(seq 1 3000); do [ -e .live-job-stream.release ] && break; sleep 0.2; done - button "Copy" - text: streamed-marker-line diff --git a/apps/web/tests/snapshots/live-job-stream/streaming.expected.md b/apps/web/tests/snapshots/live-job-stream/streaming.expected.md index 4054d5d42a..6b7336b859 100644 --- a/apps/web/tests/snapshots/live-job-stream/streaming.expected.md +++ b/apps/web/tests/snapshots/live-job-stream/streaming.expected.md @@ -1,8 +1,8 @@ - list "Background jobs": - listitem: - - button "Hide live output of printf 'streamed-%s\\n' marker-line; sleep 45" [expanded]: - - text: printf 'streamed-%s\n' marker-line; sleep 45 {{duration}} bash running + - button "Hide live output of printf 'streamed-%s\\n' marker-line; for _ in $(seq 1 3000); do [ -e .live-job-stream.release ] && break; sleep 0.2; done" [expanded]: + - text: printf 'streamed-%s\n' marker-line; for _ in $(seq 1 3000); do [ -e .live-job-stream.release ] && break; sleep 0.2; done {{duration}} bash running - img - - text: $ printf 'streamed-%s\n' marker-line; sleep 45 + - text: $ printf 'streamed-%s\n' marker-line; for _ in $(seq 1 3000); do [ -e .live-job-stream.release ] && break; sleep 0.2; done - button "Copy" - text: streamed-marker-line diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml index 8a378b23f1..9d71df140c 100644 --- a/docs/event-producer-consumer.i18n.yaml +++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md -event-producer-consumer.md: 930ffba24789ee51db110310cb17a2231135cf1d -event-producer-consumer.zh.md: 6583b1d9f333ad934db2123a2bc5c40b12f1ae36 +event-producer-consumer.md: e0b4709875723bd96f9910b1bf518600612f0a12 +event-producer-consumer.zh.md: 0f0fa1317eb5a017daf435648f5c3e36208626e0 diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 930ffba247..e0b4709875 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -21,11 +21,11 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:224`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:185`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` | | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:285`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:550`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:530`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:557`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:536`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:543`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:551`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:531`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:558`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:537`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:544`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` | | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:81`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md index 6583b1d9f3..0f0fa1317e 100644 --- a/docs/event-producer-consumer.zh.md +++ b/docs/event-producer-consumer.zh.md @@ -23,11 +23,11 @@ | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:224`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:185`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` | | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:285`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:550`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:530`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:557`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:536`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:543`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:551`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:531`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:558`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:537`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:544`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` | | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:81`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | diff --git a/packages/api/job-controller/README.i18n.yaml b/packages/api/job-controller/README.i18n.yaml index 9bef50c478..49a565d20f 100644 --- a/packages/api/job-controller/README.i18n.yaml +++ b/packages/api/job-controller/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/api/job-controller/README.md -README.md: 1af9cac6574b36fb9ee0fe2bd4ff4a529848c2fe -README.zh.md: a232d8e8655fea6ccddedb60e222837466705549 +README.md: 6aaab1bff1f13cc21672a039170f811b570230db +README.zh.md: 47e68802346fbc5e41e74171a42afa17289ee156 diff --git a/packages/api/job-controller/README.md b/packages/api/job-controller/README.md index 1af9cac657..6aaab1bff1 100644 --- a/packages/api/job-controller/README.md +++ b/packages/api/job-controller/README.md @@ -8,7 +8,7 @@ English | [中文](README.zh.md) ## Summary -`@deepseek-ai/dsh-api-job-controller` owns the Host `ctx.jobController` service and the generated Client `ctx.remote.job` namespace. Its one Remote stream, `job.observe`, delivers a record-declaring job's retained output from an absolute byte offset; the Client half installs `ctx.jobOutput`, the reference-counted per-job observation service whose accumulated views the session-header job list renders. The roster itself is not here: `SessionJob` rows still ride the session control stream owned by [`dsh-api-session-controller`](../session-controller/README.md), and a row's `outputTotal` says whether this controller has anything to stream for it. +`@deepseek-ai/dsh-api-job-controller` owns the Host `ctx.jobController` service and the generated Client `ctx.remote.job` namespace. Its one Remote stream, `job.observe`, delivers a record-declaring job's retained output from an absolute byte offset; the Client half installs `ctx.jobOutput`, the reference-counted per-job observation service whose accumulated views the session-header job list renders. The roster itself is not here: `SessionJob` rows still ride the session control stream owned by [`dsh-api-session-controller`](../session-controller/README.md), and a row's `record` says whether this controller has anything to stream for it. ## Table of Contents @@ -50,6 +50,7 @@ No direct effect; observation reads never touch model requests. +- The record is a best-effort live preview, not a terminal transcript: producers copy stdout and stderr per poll round, so the two streams' writes inside one poll window reach the record stdout first, and the client concatenates chunks regardless of `channel`. - The stream is process-local: a Host restart loses every record, and a resumed observation then anchors on an empty registry. - Per-session fencing is enforced by the registry read; the Remote layer itself serves any connected browser, matching the session control stream's `jobsBySession` broadcast. diff --git a/packages/api/job-controller/README.zh.md b/packages/api/job-controller/README.zh.md index a232d8e865..47e6880234 100644 --- a/packages/api/job-controller/README.zh.md +++ b/packages/api/job-controller/README.zh.md @@ -8,7 +8,7 @@ kind: "package-reference" ## 概述 -`@deepseek-ai/dsh-api-job-controller` 拥有 Host 的 `ctx.jobController` 服务与生成的 Client `ctx.remote.job` namespace。它唯一的 Remote 流 `job.observe` 从绝对字节偏移发送声明了 record 的 job 的保留输出;Client 半侧安装 `ctx.jobOutput`——按 job 引用计数的观测服务,会话头部任务列表渲染其累积视图。名册不在这里:`SessionJob` 行仍随 [`dsh-api-session-controller`](../session-controller/README.zh.md) 拥有的会话控制流到达,行上的 `outputTotal` 说明本控制器是否有东西可流。 +`@deepseek-ai/dsh-api-job-controller` 拥有 Host 的 `ctx.jobController` 服务与生成的 Client `ctx.remote.job` namespace。它唯一的 Remote 流 `job.observe` 从绝对字节偏移发送声明了 record 的 job 的保留输出;Client 半侧安装 `ctx.jobOutput`——按 job 引用计数的观测服务,会话头部任务列表渲染其累积视图。名册不在这里:`SessionJob` 行仍随 [`dsh-api-session-controller`](../session-controller/README.zh.md) 拥有的会话控制流到达,行上的 `record` 说明本控制器是否有东西可流。 ## 目录 @@ -50,6 +50,7 @@ Client 入口在 `ClientJobOutputModel` 之上提供 `ClientJobOutput`(`ctx.jo +- record 是尽力而为的实时预览,不是终端转录:生产者按轮询轮次复制 stdout 与 stderr,同一轮询窗口内两条流的写入先 stdout 后到达 record,客户端拼接 chunk 时也不区分 `channel`。 - 流是进程本地的:Host 重启丢失全部 record,续读的观测随后锚定在空注册表上。 - 按 session 的围栏由注册表读取强制;Remote 层本身服务任何已连接浏览器,与会话控制流对 `jobsBySession` 的广播一致。 diff --git a/packages/api/job-controller/src/client/service.ts b/packages/api/job-controller/src/client/service.ts index 385a0b92ad..07f3a00ec2 100644 --- a/packages/api/job-controller/src/client/service.ts +++ b/packages/api/job-controller/src/client/service.ts @@ -74,13 +74,15 @@ export class ClientJobOutput extends Service implements IJobOutput { ) { super(ctx, 'jobOutput') this.state = model - ctx.effect(() => () => { + ctx.effect(() => async () => { const open = [...this.entries.values()] this.entries.clear() - for (const entry of open) { - entry.stopped = true - void entry.dispose() - } + for (const entry of open) entry.stopped = true + // Cordis awaits an async disposer, so the fiber stays unloading until + // every carrier iterator has closed and a successor plugin instance + // cannot overlap one. A carrier whose teardown fails is stopped all the + // same; its failure has no consumer here. + await Promise.allSettled(open.map(entry => entry.dispose())) }, 'job-controller.client.observations') } diff --git a/packages/api/job-controller/tests/model.client.spec.ts b/packages/api/job-controller/tests/model.client.spec.ts index 69260ff3fc..5e49771318 100644 --- a/packages/api/job-controller/tests/model.client.spec.ts +++ b/packages/api/job-controller/tests/model.client.spec.ts @@ -391,6 +391,30 @@ describe('ClientJobOutput observation streams', () => { expect(model.getSnapshot().observed[String(ID)]?.error).toBeUndefined() }) + it('holds service disposal until every open stream reports quiescence', async () => { + const { ctx, output, streams } = bench() + output.observe(undefined, ID) + output.observe(undefined, 'bash-2' as JobId) + for (const { stream } of streams) stream.deferDispose = true + await tick() + + let settled = false + const disposal = ctx.fiber.dispose().then(() => { settled = true }) + await tick() + // Both carriers were told to stop, but neither iterator has closed yet: + // the fiber must still be unloading, or a successor plugin instance could + // overlap the old generation's iterator. + expect(streams.every(entry => entry.stream.disposed)).toBe(true) + expect(settled).toBe(false) + + streams[0]!.stream.releaseDispose() + await tick() + expect(settled).toBe(false) + streams[1]!.stream.releaseDispose() + await disposal + expect(settled).toBe(true) + }) + it('records a terminal stream failure and service disposal closes live streams', async () => { const { ctx, model, output, streams } = bench() output.observe(undefined, ID) diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml index fa85bc3ebe..9f55558821 100644 --- a/packages/api/session-controller/README.i18n.yaml +++ b/packages/api/session-controller/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/api/session-controller/README.md -README.md: 4f94607e70a5b963fa50d7a497afbcc97d273cb9 -README.zh.md: 455769f77ce8ad304949624de938e56579024145 +README.md: 4414cd7221b40cc880122415e83b6dc3818df481 +README.zh.md: 8f457d4a94f57c802f67624d9c84ba15c78b1ada diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md index 4f94607e70..4414cd7221 100644 --- a/packages/api/session-controller/README.md +++ b/packages/api/session-controller/README.md @@ -29,7 +29,7 @@ Each endpoint states its activation policy. List, search, attachment, history pa The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, and `append` changes, and repairs reconnect or sequence gaps through a tail page. Backwards paging has two verbs: `loadOlder()` pulls one 50-message page, and `loadThrough(seq)` — the turn-jump loader — loops 200-message pages until the window covers the target seq, lowering a shared target on repeated calls, stopping on a page that makes no progress, and reporting busy through the same `loadingOlder` snapshot bit. Ordinary records cover `[event.seq, event.seq]`; packed rows cover `[event.seq, event.seq + memberCount - 1]`. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces queue, jobs, and projection state instead of treating transient values as durable events. -A `SessionJob` row carries `outputTotal` exactly when the job declared an observation record; streaming that record is the job controller's `job.observe` (see [`dsh-api-job-controller`](../job-controller/README.md)), while this package keeps the roster on the control stream. +A `SessionJob` row carries `record: true` exactly when the job declared an observation record; streaming that record is the job controller's `job.observe` (see [`dsh-api-job-controller`](../job-controller/README.md)), while this package keeps the roster on the control stream. The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. Session derives each echo's `transcript`, `queued`, or `steering` placement from its current running state and the requested delivery mode, then retains that placement while serialization is in flight. The prompt's `requestId` is the correlation identity: the Host echoes it as the durable user source's `rpcId`, and queue occurrences project it as `SessionQueuedItem.rpcId`. An echo retires one animation frame after its durable event or queue occurrence is observed (the delay keeps it renderable until the replacement is ready), immediately when its identified prompt fails or is abandoned, and as failed on disposal; each retirement fires the registered `onRetire` callback exactly once. Echoes are Client memory only; reload and reconnect rebuild the conversation from durable events alone. diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md index 455769f77c..8f457d4a94 100644 --- a/packages/api/session-controller/README.zh.md +++ b/packages/api/session-controller/README.zh.md @@ -29,7 +29,7 @@ kind: "package-reference" Client adapter 提供 `SessionEventStream`,即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow,只发布连续的 `replace`、`prepend` 和 `append` 变更,并通过 tail page 修复重连或 seq 缺口。向后分页有两个动词:`loadOlder()` 拉一页 50 条 message,而 `loadThrough(seq)`——轮次跳转加载器——按 200 条 message 一页循环拉取直到窗口覆盖目标 seq,重复调用会下调共享目标,遇到无进展的页即停止,忙碌状态复用同一个 `loadingOlder` 快照位。普通 record 覆盖 `[event.seq, event.seq]`,packed row 覆盖 `[event.seq, event.seq + memberCount - 1]`。业务、persistence 或无法恢复的连续性错误会终止 stream,只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`;每代都以完整的进程本地 baseline 开始,因此重连会替换 queue、jobs 和 projection 状态,而不会把瞬态值当作 durable event。 -`SessionJob` 行恰在该 job 声明了观测 record 时携带 `outputTotal`;流式发送该 record 的是 job 控制器的 `job.observe`(见 [`dsh-api-job-controller`](../job-controller/README.zh.md)),本包只在控制流上保留名册。 +`SessionJob` 行恰在该 job 声明了观测 record 时携带 `record: true`;流式发送该 record 的是 job 控制器的 `job.observe`(见 [`dsh-api-job-controller`](../job-controller/README.zh.md)),本包只在控制流上保留名册。 Session 对象还承载本地提交回显:`session.beginSubmission` 在调用方序列化与 prompt 之前,同步把一条回显写入 `SessionSnapshot.pendingSubmissions`,会话 UI 因此能在点击提交的当帧显示消息。Session 根据当前运行状态与请求的投递模式推导每条回显的 `transcript`、`queued` 或 `steering` 位置,并在序列化期间保留该位置。prompt 的 `requestId` 是关联标识:Host 把它回显为 durable user source 的 `rpcId`,queue occurrence 也把它投影为 `SessionQueuedItem.rpcId`。回显在观察到其 durable event 或 queue occurrence 后延迟一个动画帧退休,该延迟保证替代内容就绪前回显仍可渲染;带标识的 prompt 失败或被放弃时立即退休,销毁时按 failed 退休;每次退休恰好触发一次注册的 `onRetire` 回调。回显只存在于 Client 内存;刷新与重连只从 durable event 重建会话。 diff --git a/packages/api/session-controller/src/control.ts b/packages/api/session-controller/src/control.ts index aa9f0a77be..b96cbb7f9d 100644 --- a/packages/api/session-controller/src/control.ts +++ b/packages/api/session-controller/src/control.ts @@ -212,6 +212,6 @@ function jobView(job: JobSnapshot): SessionJob { ...(job.detail === undefined ? {} : { detail: job.detail }), startedAt: job.startedAt, ...(job.finishedAt === undefined ? {} : { finishedAt: job.finishedAt }), - ...(job.outputTotal === undefined ? {} : { outputTotal: job.outputTotal }), + ...(job.outputTotal === undefined ? {} : { record: true as const }), } } diff --git a/packages/api/session-controller/src/types.ts b/packages/api/session-controller/src/types.ts index c5a6caeacb..d3ab795ecb 100644 --- a/packages/api/session-controller/src/types.ts +++ b/packages/api/session-controller/src/types.ts @@ -489,11 +489,12 @@ export interface SessionJob { readonly startedAt: number readonly finishedAt?: number /** - * Total UTF-8 bytes the job's observation record holds so far. Present - * exactly when the job declared a record — the row is observable through - * the job controller's `job.observe` stream. + * Present exactly when the job declared an observation record: the row is + * observable through the job controller's `job.observe` stream, whose + * `opened` anchor carries the live byte offsets. The roster refreshes on + * lifecycle commits only, so it mirrors no byte count. */ - readonly outputTotal?: number + readonly record?: true } /** Complete live control baseline emitted once per control stream generation. */ diff --git a/packages/api/session-controller/tests/control-jobs.host.spec.ts b/packages/api/session-controller/tests/control-jobs.host.spec.ts index 61a9a8156a..9d80501966 100644 --- a/packages/api/session-controller/tests/control-jobs.host.spec.ts +++ b/packages/api/session-controller/tests/control-jobs.host.spec.ts @@ -162,7 +162,7 @@ describe('Session control jobs updates', () => { ]) }) - it('carries outputTotal exactly for record-declaring jobs', async () => { + it('flags record-declaring jobs instead of mirroring a byte count the roster never refreshes', async () => { const { ctx, agent, control } = await harness(true) const abort = new AbortController() const collected = collectJobs(control.control(abort.signal), 1, abort) @@ -178,7 +178,8 @@ describe('Session control jobs updates', () => { }) const [frame] = await collected - expect(frame?.jobs[0]?.outputTotal).toBe(2) + expect(frame?.jobs[0]).toMatchObject({ record: true }) + expect(frame?.jobs[0]).not.toHaveProperty('outputTotal') }) it('fans an unowned change out to every attached session', async () => { diff --git a/packages/client/ui-jobs/README.i18n.yaml b/packages/client/ui-jobs/README.i18n.yaml index fe508b8379..7a5e54a34f 100644 --- a/packages/client/ui-jobs/README.i18n.yaml +++ b/packages/client/ui-jobs/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-jobs/README.md -README.md: a0ecc137ab1eb57aeaea9ccdfdbaf898794de2fe -README.zh.md: 744450c480b4d26c0558d992904817174ca2ed73 +README.md: fe357b5555cdc2f7a94ea0a44e97c499652695d3 +README.zh.md: d23b96becc5b2598197f7720a355a37e5c8bf7cb diff --git a/packages/client/ui-jobs/README.md b/packages/client/ui-jobs/README.md index a0ecc137ab..fe357b5555 100644 --- a/packages/client/ui-jobs/README.md +++ b/packages/client/ui-jobs/README.md @@ -29,7 +29,7 @@ Load the plugin through the web-app manifest; it renders nothing until the sessi ### One row per job -The session control stream's `jobsBySession` mirror is the single roster: each `SessionJob` row carries lifecycle, duration, and the model-visible `detail`, and its `outputTotal` field is present exactly when the job declared a record — that presence is what makes a row expandable. There is no second roster to join. +The session control stream's `jobsBySession` mirror is the single roster: each `SessionJob` row carries lifecycle, duration, and the model-visible `detail`, and its `record` flag is present exactly when the job declared a record — that flag is what makes a row expandable. There is no second roster to join. ### The expanded panel diff --git a/packages/client/ui-jobs/README.zh.md b/packages/client/ui-jobs/README.zh.md index 744450c480..d23b96becc 100644 --- a/packages/client/ui-jobs/README.zh.md +++ b/packages/client/ui-jobs/README.zh.md @@ -29,7 +29,7 @@ kind: "package-reference" ### 一 job 一行 -session control 流的 `jobsBySession` 镜像是唯一名册:每个 `SessionJob` 行携带生命周期、时长与模型可见的 `detail`,其 `outputTotal` 字段恰在 job 声明了 record 时存在——这个存在性就是行可展开的依据。不存在需要 join 的第二份名册。 +session control 流的 `jobsBySession` 镜像是唯一名册:每个 `SessionJob` 行携带生命周期、时长与模型可见的 `detail`,其 `record` 标志恰在 job 声明了 record 时存在——这个标志就是行可展开的依据。不存在需要 join 的第二份名册。 ### 展开的面板 diff --git a/packages/client/ui-jobs/src/client/JobListAction.tsx b/packages/client/ui-jobs/src/client/JobListAction.tsx index 87acb18a32..bf369c9949 100644 --- a/packages/client/ui-jobs/src/client/JobListAction.tsx +++ b/packages/client/ui-jobs/src/client/JobListAction.tsx @@ -46,7 +46,7 @@ function isLive(job: SessionJob): boolean { /** True exactly when the job declared an observation record. */ function isObservable(job: SessionJob): boolean { - return job.outputTotal !== undefined + return job.record === true } /** Closed-union exhaustiveness fence for the wire status set. */ diff --git a/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx b/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx index 9d659ca2ae..9a8b9a1edc 100644 --- a/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx +++ b/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx @@ -30,7 +30,7 @@ function job(over: Partial = {}): SessionJob { /** A job that declared an observation record, so its row offers a panel. */ function recordJob(over: Partial = {}): SessionJob { - return job({ outputTotal: 0, ...over }) + return job({ record: true, ...over }) } function props( @@ -180,7 +180,7 @@ describe('JobListAction observation', () => { streaming: false, } render() diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 9de2adb4c9..3002c82a56 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -4987,7 +4987,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SessionJob', - declaration: 'export interface SessionJob {\n readonly id: JobId;\n readonly kind: string;\n readonly label: string;\n readonly status: \'running\' | \'stopping\' | \'completed\' | \'killed\' | \'failed\';\n readonly detail?: string;\n readonly startedAt: number;\n readonly finishedAt?: number;\n readonly outputTotal?: number;\n}', + declaration: 'export interface SessionJob {\n readonly id: JobId;\n readonly kind: string;\n readonly label: string;\n readonly status: \'running\' | \'stopping\' | \'completed\' | \'killed\' | \'failed\';\n readonly detail?: string;\n readonly startedAt: number;\n readonly finishedAt?: number;\n readonly record?: true;\n}', }, { name: 'SessionLineageNode', diff --git a/packages/jobs/jobs/src/pump.ts b/packages/jobs/jobs/src/pump.ts index 3d7d252d24..5203157a9f 100644 --- a/packages/jobs/jobs/src/pump.ts +++ b/packages/jobs/jobs/src/pump.ts @@ -60,6 +60,14 @@ export interface JobPumpOptions { * `gapBefore`, so the discontinuity stays visible to observers. Fold the * returned promise into the producer's `JobHooks.done` chain so the final * drain lands before settlement trims and closes the record. + * + * Each round drains the sources in array order, so bytes two sources + * produced inside one poll window land in that order, not in the order they + * were written; the record is a best-effort live view whose cross-source + * reordering is bounded by `pollMs`, not a terminal transcript. + * + * The wait holds constant resources however long the job runs: one + * subscription on `done` for the whole run and one pending timer at a time. * @param job - the running job's producer face receiving the copied chunks. * @param sources - producer streams, each pumped at its own offset. * @param options - poll cadence and the producer's settlement promise. @@ -91,18 +99,24 @@ export async function pumpJobOutput( } } let settled = false - const settlement = options.done.then(() => { settled = true }, () => { settled = true }) + let timer: ReturnType | undefined + let wake: (() => void) | undefined + const finish = (): void => { + settled = true + // Clear the pending poll so a finished pump holds no timer for up to one + // interval, and release the current wait so the final drain runs at once. + if (timer !== undefined) clearTimeout(timer) + wake?.() + } + void options.done.then(finish, finish) while (!settled) { drain() - await Promise.race([ - new Promise((resolve) => { - const timer = setTimeout(resolve, options.pollMs) - // The settlement branch wins the race; clear the loser so a finished - // pump holds no pending timer for up to one poll interval. - void settlement.then(() => { clearTimeout(timer); resolve() }) - }), - settlement, - ]) + await new Promise((resolve) => { + wake = resolve + timer = setTimeout(resolve, options.pollMs) + }) + wake = undefined + timer = undefined } drain() } diff --git a/packages/jobs/jobs/tests/service.spec.ts b/packages/jobs/jobs/tests/service.spec.ts index ff2c282a27..3938328478 100644 --- a/packages/jobs/jobs/tests/service.spec.ts +++ b/packages/jobs/jobs/tests/service.spec.ts @@ -173,6 +173,42 @@ describe('pumpJobOutput', () => { } }) + it('subscribes to done once and holds one poll timer however long the job runs', async () => { + vi.useFakeTimers() + try { + const { job } = recordingJob() + // A thenable stands in for the producer's done promise, and whatever the + // pump derives from it counts its own reactions too: a pending promise + // retains every reaction until it settles, so a day-long job must not + // gain one per poll round. + let subscriptions = 0 + let settle!: () => void + const settled = new Promise((resolve) => { settle = resolve }) + const counting = (promise: Promise): Promise => ({ + then(onFulfilled?: (value: unknown) => unknown, onRejected?: (reason: unknown) => unknown) { + subscriptions += 1 + return counting(promise.then(onFulfilled, onRejected)) + }, + }) as unknown as Promise + const done = counting(settled) + const { source, offsets } = scriptedSource([]) + const pump = pumpJobOutput(job, [source], { pollMs: 50, done }) + + const rounds = 10_000 + await vi.advanceTimersByTimeAsync(50 * rounds) + expect(offsets).toHaveLength(rounds + 1) + expect(subscriptions).toBeLessThanOrEqual(2) + expect(vi.getTimerCount()).toBe(1) + + settle() + await pump + expect(offsets).toHaveLength(rounds + 2) + expect(vi.getTimerCount()).toBe(0) + } finally { + vi.useRealTimers() + } + }) + it('marks a lossy source read as a gap so observers see the discontinuity', async () => { const { job, appends } = recordingJob() const { source } = scriptedSource([{ text: 'tail', lossy: true }]) diff --git a/packages/shell/tool-bash/README.i18n.yaml b/packages/shell/tool-bash/README.i18n.yaml index 194557fca7..57f2951bfa 100644 --- a/packages/shell/tool-bash/README.i18n.yaml +++ b/packages/shell/tool-bash/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/shell/tool-bash/README.md -README.md: 24e13266a7ee24b39f524f165401076860f494b1 -README.zh.md: 3d2c9f22033d711ce33382054a372e2c26aa2d46 +README.md: 50047a5fe0d69da1feb38f75ada27595b88fa5c5 +README.zh.md: c74a45561298defb4baa5b34be7cebc1cdfbc744 diff --git a/packages/shell/tool-bash/README.md b/packages/shell/tool-bash/README.md index 24e13266a7..50047a5fe0 100644 --- a/packages/shell/tool-bash/README.md +++ b/packages/shell/tool-bash/README.md @@ -55,7 +55,7 @@ The tool executes `bash -c ` and returns the combined output. Commands ### Running long commands in the background -Passing `run_in_background: true` returns a job id immediately and no timeout applies; the command keeps running while the agent works on something else. The agent reads its output with `job_output` (non-blocking unless `wait: true`), lists jobs with `job_list`, and stops it with `job_kill`; a finished job notifies the owning agent in-session. Background support needs the generic job runtime (`dsh-jobs-local`) and its control tools (`dsh-tool-jobs`) mounted. The background job declares an observation record: the run's non-consuming `observed` readers are pumped into it at `recordPollMs` (default 150), so the Web client streams live output without touching the job's consuming cursor; a pump failure is logged and swallowed while the job runs on. +Passing `run_in_background: true` returns a job id immediately and no timeout applies; the command keeps running while the agent works on something else. The agent reads its output with `job_output` (non-blocking unless `wait: true`), lists jobs with `job_list`, and stops it with `job_kill`; a finished job notifies the owning agent in-session. Background support needs the generic job runtime (`dsh-jobs-local`) and its control tools (`dsh-tool-jobs`) mounted. The background job declares an observation record: the run's non-consuming `observed` readers are pumped into it at `recordPollMs` (default 150), so the Web client streams live output without touching the job's consuming cursor; a pump failure is logged and swallowed while the job runs on. The record is a best-effort live preview: stdout and stderr are copied per poll round, so writes the two streams made inside one `recordPollMs` window appear stdout first rather than in write order. ### Sandboxed execution and escalation diff --git a/packages/shell/tool-bash/README.zh.md b/packages/shell/tool-bash/README.zh.md index 3d2c9f2203..c74a455612 100644 --- a/packages/shell/tool-bash/README.zh.md +++ b/packages/shell/tool-bash/README.zh.md @@ -55,7 +55,7 @@ kind: "package-reference" ### 后台运行长时间命令 -传入 `run_in_background: true` 会立即返回 job id,不应用超时;命令继续运行,agent 同时处理其他事情。agent 用 `job_output` 读取输出(除非 `wait: true`,否则非阻塞)、用 `job_list` 列出任务、用 `job_kill` 停止任务;完成的任务会在会话内通知拥有它的 agent。后台支持需要挂载通用任务运行时(`dsh-jobs-local`)及其控制工具(`dsh-tool-jobs`)。后台 job 声明观测 record:运行的非消费 `observed` 读取器以 `recordPollMs`(默认 150)的节奏泵入其中,使 Web 客户端在不触碰 job 消耗游标的情况下流式看到实时输出;泵失败会被记录并吞掉,job 继续运行。 +传入 `run_in_background: true` 会立即返回 job id,不应用超时;命令继续运行,agent 同时处理其他事情。agent 用 `job_output` 读取输出(除非 `wait: true`,否则非阻塞)、用 `job_list` 列出任务、用 `job_kill` 停止任务;完成的任务会在会话内通知拥有它的 agent。后台支持需要挂载通用任务运行时(`dsh-jobs-local`)及其控制工具(`dsh-tool-jobs`)。后台 job 声明观测 record:运行的非消费 `observed` 读取器以 `recordPollMs`(默认 150)的节奏泵入其中,使 Web 客户端在不触碰 job 消耗游标的情况下流式看到实时输出;泵失败会被记录并吞掉,job 继续运行。record 是尽力而为的实时预览:stdout 与 stderr 按轮询轮次复制,同一个 `recordPollMs` 窗口内两条流的写入会先 stdout 后 stderr 出现,而不是按写入顺序。 ### 沙箱执行与升权 diff --git a/packages/shell/tool-bash/src/observe.ts b/packages/shell/tool-bash/src/observe.ts index 2e2874f9c1..0758be7b7b 100644 --- a/packages/shell/tool-bash/src/observe.ts +++ b/packages/shell/tool-bash/src/observe.ts @@ -5,6 +5,9 @@ * `readOutput` cursor. Observation is strictly best-effort: absent backend * offset readers degrade to no observation, and a pump failure is logged and * swallowed — the job path is unaffected either way. + * The record interleaves stdout and stderr per poll round, not per write: + * output the two streams produced inside one `pollMs` window lands stdout + * first, so the panel is a live preview, not a terminal-exact transcript. * * @module @deepseek-ai/dsh-tool-bash/observe */ diff --git a/packages/shell/tool-pwsh/src/observe.ts b/packages/shell/tool-pwsh/src/observe.ts index 6e9e466981..911145bd93 100644 --- a/packages/shell/tool-pwsh/src/observe.ts +++ b/packages/shell/tool-pwsh/src/observe.ts @@ -5,6 +5,9 @@ * `readOutput` cursor. Observation is strictly best-effort: absent backend * offset readers degrade to no observation, and a pump failure is logged and * swallowed — the job path is unaffected either way. + * The record interleaves stdout and stderr per poll round, not per write: + * output the two streams produced inside one `pollMs` window lands stdout + * first, so the panel is a live preview, not a terminal-exact transcript. * * @module @deepseek-ai/dsh-tool-pwsh/observe */ diff --git a/snapshots/web/background-job-list/running.expected.md b/snapshots/web/background-job-list/running.expected.md index 811bddec3c..b3772a0cdf 100644 --- a/snapshots/web/background-job-list/running.expected.md +++ b/snapshots/web/background-job-list/running.expected.md @@ -1,5 +1,5 @@ - list "Background jobs": - listitem: - - button "Show live output of sleep 45": - - text: sleep 45 {{duration}} bash running + - button "Show live output of for _ in $(seq 1 3000); do [ -e .background-job-list.release ] && break; sleep 0.2; done": + - text: for _ in $(seq 1 3000); do [ -e .background-job-list.release ] && break; sleep 0.2; done {{duration}} bash running - img diff --git a/snapshots/web/background-job-list/settled.expected.md b/snapshots/web/background-job-list/settled.expected.md index 44747d990d..8d4846be9c 100644 --- a/snapshots/web/background-job-list/settled.expected.md +++ b/snapshots/web/background-job-list/settled.expected.md @@ -1,5 +1,5 @@ - list "Background jobs": - listitem: - - button "Show live output of sleep 45": - - text: "bash sleep 45 signal: SIGTERM {{duration}}" + - button "Show live output of for _ in $(seq 1 3000); do [ -e .background-job-list.release ] && break; sleep 0.2; done": + - text: "bash for _ in $(seq 1 3000); do [ -e .background-job-list.release ] && break; sleep 0.2; done signal: SIGTERM {{duration}}" - img From 6a4d7ee2429aee6a31a8d5b281526b40c339fba9 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 11:33:05 +0800 Subject: [PATCH 024/100] chore(job-controller): align the package version with the 0.1.2-rc.1 bump --- packages/api/job-controller/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/api/job-controller/package.json b/packages/api/job-controller/package.json index 0f0e46aafe..71cec52468 100644 --- a/packages/api/job-controller/package.json +++ b/packages/api/job-controller/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-api-job-controller", "description": "Job Remote observation stream and the reference-counted client job-output service", - "version": "0.1.2-alpha.5", + "version": "0.1.2-rc.1", "publishConfig": { "access": "public" }, From b48c05d117fe06296cc0f21c5fc77ba7abbecf4e Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 13:15:23 +0800 Subject: [PATCH 025/100] refactor(jobs): type the producer face by the record declaration, tidy review residue - `JobStart` is a union discriminated by `record`: `RecordingJobStart.run` receives `RecordingJob` (with `append`), `PlainJobStart.run` receives the plain `RunningJob`, and the registry builds the plain face without the method, so the former warn-and-drop path is unrepresentable. - Remove the duplicated JSDoc opener in the registry seam and correct the job-list slot comment (order 20 sits before the subagent catalog's 30). - Restore the `cordis-tool-round` session fixture whose only change was a re-recorded `createdAt`. - Update the 2026-08-08 job-display note's stale service-disposal and slot ordering facts; archive the superseded 2026-08-25 unified-task-list note and point its remaining inbound links at the archived snapshot. --- .../2026-08-25-unified-task-list.i18n.yaml | 6 ++ .../feature/2026-08-25-unified-task-list.md | 5 +- .../2026-08-25-unified-task-list.zh.md | 9 +- .agents/notes/archived/manifest.json | 3 + ...9-01-jobs-absorb-activity-record.i18n.yaml | 4 +- .../2026-09-01-jobs-absorb-activity-record.md | 3 +- ...26-09-01-jobs-absorb-activity-record.zh.md | 3 +- ...08-08-web-background-job-display.i18n.yaml | 4 +- .../2026-08-08-web-background-job-display.md | 4 +- ...026-08-08-web-background-job-display.zh.md | 4 +- ...-08-24-activity-observation-seam.i18n.yaml | 4 +- .../2026-08-24-activity-observation-seam.md | 4 +- ...2026-08-24-activity-observation-seam.zh.md | 4 +- .../2026-08-25-unified-task-list.i18n.yaml | 6 -- docs/subsystems/jobs.i18n.yaml | 4 +- docs/subsystems/jobs.md | 102 ++++++++++-------- docs/subsystems/jobs.zh.md | 102 ++++++++++-------- .../job-controller/tests/observe.host.spec.ts | 8 +- packages/client/ui-jobs/src/client/index.ts | 3 +- .../extensions/tool-cordis/src/api-catalog.ts | 18 +++- packages/jobs/jobs-local/src/index.ts | 39 +++---- packages/jobs/jobs-local/tests/jobs.spec.ts | 22 ++-- packages/jobs/jobs/README.i18n.yaml | 4 +- packages/jobs/jobs/README.md | 4 +- packages/jobs/jobs/README.zh.md | 4 +- packages/jobs/jobs/src/index.ts | 4 +- packages/jobs/jobs/src/pump.ts | 4 +- packages/jobs/jobs/src/types.ts | 81 +++++++++----- packages/jobs/jobs/tests/service.spec.ts | 42 +++++++- packages/shell/tool-bash/src/observe.ts | 4 +- .../shell/tool-bash/tests/observe.spec.ts | 6 +- packages/shell/tool-pwsh/src/observe.ts | 4 +- scripts/gen-cordis-catalog.ts | 3 + scripts/type-equiv.manifest.json | 15 +++ snapshots/web/cordis-tool-round/session.jsonl | 2 +- 35 files changed, 326 insertions(+), 212 deletions(-) create mode 100644 .agents/notes/archived/feature/2026-08-25-unified-task-list.i18n.yaml rename .agents/notes/{implemented => archived}/feature/2026-08-25-unified-task-list.md (99%) rename .agents/notes/{implemented => archived}/feature/2026-08-25-unified-task-list.zh.md (94%) delete mode 100644 .agents/notes/implemented/feature/2026-08-25-unified-task-list.i18n.yaml diff --git a/.agents/notes/archived/feature/2026-08-25-unified-task-list.i18n.yaml b/.agents/notes/archived/feature/2026-08-25-unified-task-list.i18n.yaml new file mode 100644 index 0000000000..c5b051c49c --- /dev/null +++ b/.agents/notes/archived/feature/2026-08-25-unified-task-list.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 .agents/notes/archived/feature/2026-08-25-unified-task-list.md +2026-08-25-unified-task-list.md: f2f955e36a78eee8fa8ff8a804293bcc37a44acd +2026-08-25-unified-task-list.zh.md: 5a4c51a6cc3d0f331d2559debb73dc02e9cf12c5 diff --git a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.md b/.agents/notes/archived/feature/2026-08-25-unified-task-list.md similarity index 99% rename from .agents/notes/implemented/feature/2026-08-25-unified-task-list.md rename to .agents/notes/archived/feature/2026-08-25-unified-task-list.md index daf6582bf2..f2f955e36a 100644 --- a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.md +++ b/.agents/notes/archived/feature/2026-08-25-unified-task-list.md @@ -1,11 +1,12 @@ # Agent Note: One session-header task list — jobs joined with activities in the UI projection only Status: implemented - -Superseded: the two-roster join described here was removed with the activity seam — the job rows are now the whole roster; see [jobs absorb the record](../architecture/2026-09-01-jobs-absorb-activity-record.md). +Archived: 2026-09-03 English | [中文](2026-08-25-unified-task-list.zh.md) +Superseded: the two-roster join described here was removed with the activity seam — the job rows are now the whole roster; see [jobs absorb the record](../architecture/2026-09-01-jobs-absorb-activity-record.md). + ## Problem The [activity observation seam](2026-08-24-activity-observation-seam.md) shipped its Web surface as a second session-header button beside the [background-job list](2026-08-08-web-background-job-display.md). A background bash run registers in both planes — `ctx.jobs` for control and `ctx.activities` for observation — so the same work rendered twice: once in "background jobs" with lifecycle and duration, once in "activities" with expandable live output. Two near-identical popovers with different names for overlapping row sets read as a product accident, and the flat activity rows (live and settled interleaved, single-line, no duration) had no visual hierarchy. diff --git a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md b/.agents/notes/archived/feature/2026-08-25-unified-task-list.zh.md similarity index 94% rename from .agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md rename to .agents/notes/archived/feature/2026-08-25-unified-task-list.zh.md index 624747396e..5a4c51a6cc 100644 --- a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.zh.md +++ b/.agents/notes/archived/feature/2026-08-25-unified-task-list.zh.md @@ -1,11 +1,12 @@ -# Agent Note:会话头部单一任务列表——jobs 与 activity 只在 UI 投影层合并 +# Agent Note: 会话头部单一任务列表——jobs 与 activity 只在 UI 投影层合并 -状态:implemented - -Superseded:本文描述的双名册 join 已随 activity seam 一并移除——job 行现在就是完整名册;见 [jobs 吸收 record](../architecture/2026-09-01-jobs-absorb-activity-record.zh.md)。 +Status: implemented +Archived: 2026-09-03 [English](2026-08-25-unified-task-list.md) | 中文 +Superseded: 本文描述的双名册 join 已随 activity seam 一并移除——job 行现在就是完整名册;见 [jobs 吸收 record](../architecture/2026-09-01-jobs-absorb-activity-record.zh.md)。 + ## 问题 [activity 观察面](2026-08-24-activity-observation-seam.zh.md)的 Web 呈现落地为[后台任务列表](2026-08-08-web-background-job-display.zh.md)旁边的第二个会话头部按钮。一次后台 bash 会同时登记在两个面里——`ctx.jobs` 负责控制、`ctx.activities` 负责观察——于是同一份工作渲染了两次:一次在"后台任务"里带生命周期与时长,一次在"活动"里带可展开的实时输出。两个行集合高度重叠、名字却不同的近似弹层,读起来像产品事故;而活动列表的扁平行(live 与 settled 混排、单行、无时长)也缺乏视觉层次。 diff --git a/.agents/notes/archived/manifest.json b/.agents/notes/archived/manifest.json index e2bf423d56..f4cae45ef7 100644 --- a/.agents/notes/archived/manifest.json +++ b/.agents/notes/archived/manifest.json @@ -328,6 +328,9 @@ "feature/2026-08-19-high-cache-hit-decimal-display.i18n.yaml": "sha256:c2cb839ed676040ed62153c2aab65b677fa59739f69253af50246e79a2347620", "feature/2026-08-19-high-cache-hit-decimal-display.md": "sha256:08cb68bfc379da47a05b816afac26126146d36d6248350d4380f7cb98607d573", "feature/2026-08-19-high-cache-hit-decimal-display.zh.md": "sha256:9d7afe3e2fc3029fbccc643b432a01bcb3b5671750adb6945ac414ec843ca063", + "feature/2026-08-25-unified-task-list.i18n.yaml": "sha256:fec0d4a3ecf59aafd440bc801c686b14d63152c937f51bebe0da61ff615f6f33", + "feature/2026-08-25-unified-task-list.md": "sha256:30bd4e338a3de2f59af98d512c7878928c61846e6700d6012fc45e51c0bf94df", + "feature/2026-08-25-unified-task-list.zh.md": "sha256:88fce0a52b5387ea98c1f68742c03b2f475c5465c680befb32c587066e52cfce", "process/2026-06-11-doc-sync-enforcement.i18n.yaml": "sha256:33b6d5874427bd7a2bd82e7e2f4f482b12448b2464aef15a9c57975edb48554d", "process/2026-06-11-doc-sync-enforcement.md": "sha256:aa2fe83d519fc30d48dff19e596e83c8922aacc9e063e14fe2cc35b769b9100e", "process/2026-06-11-doc-sync-enforcement.zh.md": "sha256:698017bd35f030fdea3eac51df9e43138c48140f504739d687b7251d13fced2b", diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml index f7cf077333..e895f7c65b 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.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 .agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md -2026-09-01-jobs-absorb-activity-record.md: c1a668f8a008948957e62b5acf1d9db141441885 -2026-09-01-jobs-absorb-activity-record.zh.md: a23f3cda4c8c53663a6aee99469297d6878539d1 +2026-09-01-jobs-absorb-activity-record.md: 2f2bf7a65b5c26c80ec7ddc307c0f31a87f4de54 +2026-09-01-jobs-absorb-activity-record.zh.md: ed62a04e8f9da9de35bd721cceee3a2e56644cdb diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md index c1a668f8a0..2f2bf7a65b 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md @@ -14,7 +14,7 @@ The one activity without a job was the foreground workflow mirror. Everything el `ctx.jobs` owns the observation record; `packages/activity/`, `packages/api/activity-controller`, and the correlation vocabulary are removed. -- **`JobStart.record?: true`** declares an observable output record. `run(job)` now receives the job's producer face — `RunningJob { id, append(text, {channel?, gapBefore?}), updateDetail(detail) }` — so the id is issued before the starter runs (a throwing starter still registers nothing; its ordinal is skipped). Writes staged inside the starter surface at the registration commit. `updateDetail` works for every job and gives `job_list` a live progress line; `append` without a record declaration logs and drops. +- **`JobStart.record?: true`** declares an observable output record. `run(job)` now receives the job's producer face — `RecordingJob { id, append(text, {channel?, gapBefore?}), updateDetail(detail) }` for a `record: true` start, the plain `RunningJob { id, updateDetail(detail) }` otherwise — so the id is issued before the starter runs (a throwing starter still registers nothing; its ordinal is skipped). Writes staged inside the starter surface at the registration commit. `updateDetail` works for every job and gives `job_list` a live progress line; `append` without a record declaration logs and drops. - **There is no `end`.** Job settlement — the producer outcome, a kill, or teardown — is the record's only close: it trims retention to the settled cap and fires the final `onOutput` signal. The dual-settlement pairing (`ActivityHandle.end` first-wins against teardown force-ends) is deleted, not reimplemented. - **`readRecord(id, from, caller)`** is the non-consuming multi-reader view (absolute UTF-8 offsets, `lossy` below the retained window), fenced like every other job read; it never marks the job `reported`. The model-facing `readOutput` cursor is untouched — the two projections serve different readers and stay separate by design. - **`jobs-local`** absorbs the chunk ring (`retainBytes` 256 KiB live, `settledRetainBytes` 16 KiB settled), and `pumpJobOutput` replaces `pumpActivityOutput` beside the seam. Producers fold the pump's final drain into `hooks.done` so the record holds its last bytes before settlement closes it. @@ -38,6 +38,7 @@ Review of the merged design settled five points that the sections above leave im - **Client disposal waits for carrier quiescence.** The `ctx.jobOutput` effect disposer is async and awaits every open `RemoteStream.dispose()`, because Cordis awaits async disposers and a fiber that reported unloaded while an old iterator was still closing could overlap the next plugin instance under HMR. - **The roster flags a record, it does not count bytes.** `SessionJob.record: true` replaced `outputTotal`: `append` commits no roster change (only lifecycle commits fire `onJobsChanged`), so a mirrored count went stale the moment output arrived, and broadcasting the roster per append was rejected as traffic for a number no row needed. The live offsets ride the observation stream's `opened` anchor. - **The record is a best-effort live preview.** Producers copy stdout and stderr per poll round, so writes inside one window land stdout first; pipe capture cannot recover the true interleaving (only a PTY or `2>&1` can), and the client concatenates chunks regardless of `channel`. `channel` stays on the wire because it is what makes that limit visible and what a distinct stderr rendering would need. +- **The declaration types the face.** `JobStart` is a union discriminated by `record`: `RecordingJobStart.run` receives `RecordingJob`, `PlainJobStart.run` receives `RunningJob` without `append`, and the registry builds the plain face without the method — output the registry has nowhere to keep is unrepresentable instead of warned about and dropped. - **Web e2e keep-alive is a barrier, not a clock.** The background command holds on a file the test owns in the job's cwd and the scenario kills it explicitly, so no CI stall can settle the job first; each scenario is one test, never a chain of tests sharing a job id. ## Consequences diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md index a23f3cda4c..ed62a04e8f 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md @@ -14,7 +14,7 @@ Status: implemented `ctx.jobs` 拥有观测 record;`packages/activity/`、`packages/api/activity-controller` 与 correlation 词表被移除。 -- **`JobStart.record?: true`** 声明可观测输出 record。`run(job)` 现在收到 job 的生产者面——`RunningJob { id, append(text, {channel?, gapBefore?}), updateDetail(detail) }`——因此 id 在 starter 运行前签发(starter 抛出仍然不登记任何东西;序号被跳过)。starter 内暂存的写入在登记提交时可见。`updateDetail` 对所有 job 可用,让 `job_list` 也能看到实时进度行;未声明 record 的 `append` 记日志并丢弃。 +- **`JobStart.record?: true`** 声明可观测输出 record。`run(job)` 现在收到 job 的生产者面——`record: true` 的 start 收到 `RecordingJob { id, append(text, {channel?, gapBefore?}), updateDetail(detail) }`,其余收到普通的 `RunningJob { id, updateDetail(detail) }`——因此 id 在 starter 运行前签发(starter 抛出仍然不登记任何东西;序号被跳过)。starter 内暂存的写入在登记提交时可见。`updateDetail` 对所有 job 可用,让 `job_list` 也能看到实时进度行;未声明 record 的 `append` 记日志并丢弃。 - **没有 `end`。** job 结算——生产者 outcome、kill 或 teardown——是 record 唯一的关闭:裁剪到结算保留量并发出最后一个 `onOutput` 信号。双结算配对(`ActivityHandle.end` 与 teardown 强结的 first-wins 对账)被删除,而非重新实现。 - **`readRecord(id, from, caller)`** 是非消耗多读者视图(绝对 UTF-8 偏移,低于保留窗口为 `lossy`),围栏与其他 job 读取一致;永不置 `reported`。模型面的 `readOutput` 游标原样保留——两个投影服务不同读者,刻意保持分离。 - **`jobs-local`** 吸收块环(`retainBytes` 运行期 256 KiB,`settledRetainBytes` 结算后 16 KiB),`pumpJobOutput` 在 seam 旁替换 `pumpActivityOutput`。生产者把 pump 的末次排空折进 `hooks.done`,让 record 在结算关闭前握有最后的字节。 @@ -38,6 +38,7 @@ Status: implemented - **客户端卸载等待载体静止。** `ctx.jobOutput` 的 effect disposer 是异步的,await 每条打开的 `RemoteStream.dispose()`:Cordis 会 await 异步 disposer,而一个在旧 iterator 仍在关闭时就宣告卸载完成的 fiber,在 HMR 下可能与下一个插件实例重叠。 - **名册标记 record,不计字节。** `SessionJob.record: true` 取代了 `outputTotal`:`append` 不提交名册变更(只有生命周期提交触发 `onJobsChanged`),镜像的计数在输出到达的瞬间就陈旧了;而为一个没有任何行需要的数字按 append 广播整份名册被否决。实时偏移随观测流的 `opened` 锚帧到达。 - **record 是尽力而为的实时预览。** 生产者按轮询轮次复制 stdout 与 stderr,同一窗口内的写入先 stdout 落地;pipe 捕获无法还原真实交错(只有 PTY 或 `2>&1` 可以),客户端拼接 chunk 时也不区分 `channel`。`channel` 留在 wire 上,因为它正是让这一限制可见、也是将来区分渲染 stderr 所需要的东西。 +- **声明决定生产者面的类型。** `JobStart` 是按 `record` 判别的联合类型:`RecordingJobStart.run` 收到 `RecordingJob`,`PlainJobStart.run` 收到没有 `append` 的 `RunningJob`,注册表给普通 job 构造的面根本没有这个方法——注册表无处存放的输出成为不可表达,而不是警告后丢弃。 - **Web e2e 的保活是 barrier 而非时钟。** 后台命令守在测试拥有的、位于 job cwd 的文件上,由场景显式 kill,因此 CI 卡顿不可能先把任务结算掉;每个场景是一个测试,绝不是共享 job id 的测试链。 ## 后果 diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml index 444bbac0ad..ee733d059e 100644 --- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.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 .agents/notes/implemented/feature/2026-08-08-web-background-job-display.md -2026-08-08-web-background-job-display.md: 3dd003c0e972ec7a5857e84980520eee93b53955 -2026-08-08-web-background-job-display.zh.md: 5d1ee4bada9c1966e4329d35f5a4db64300ca3b4 +2026-08-08-web-background-job-display.md: 7787466154d65ba0970010c3fdaf964ae6d8507f +2026-08-08-web-background-job-display.zh.md: 478acdf00936baed1700d18db2f63b1da1749e37 diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md index 3dd003c0e9..7787466154 100644 --- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md +++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md @@ -66,7 +66,7 @@ The listener is owner-granular rather than task-granular. The only consumer push `onJobDone` is not a subset of this. It delivers the terminal record with the exact owner `Agent` under first-wins semantics that `dsh-tool-jobs` couples to `reported`; `onJobsChanged` is pure observation with no delivery meaning and marks nothing reported. Listener throws are contained and never awaited, matching `onJobDone`, and each registration is an effect on the calling fiber. -Service disposal deliberately announces nothing. Every `onJobsChanged` registration is an effect on the registry's own fiber, so the listeners are already gone by the time teardown clears the store; an observer learns the registry left through its own disposal, not through a final empty set. +Service disposal commits one final emptying and announces it: after the registry has cancelled and awaited its jobs, `onJobsChanged` fires once per owner whose visible set the teardown emptied, so a listener registered on a longer-lived fiber sees the final empty set instead of a stale roster (a listener registered on the registry's own fiber is already gone by then). ### The Session Controller carrier @@ -89,7 +89,7 @@ Two replacement points keep it honest. Each control-stream generation clears the ### The header action -`@deepseek-ai/dsh-client-ui-jobs` (since merged into `dsh-client-ui-activity`) registers one entry in `conversation.session.header.actions`, ordered after the subagent catalog. Its own README owns the presentation contract; the decisions worth recording here are that the control does not render at all until the session has a task, that the live badge is omitted at zero so a history-only session keeps a quiet entry point, and that settled rows stay visible because a failed task's `detail` is the only place its failure is legible. +`@deepseek-ai/dsh-client-ui-jobs` registers one entry in `conversation.session.header.actions`, ordered between the preset label and the subagent catalog (`order: 20` against the catalog's 30). Its own README owns the presentation contract; the decisions worth recording here are that the control does not render at all until the session has a task, that the live badge is omitted at zero so a history-only session keeps a quiet entry point, and that settled rows stay visible because a failed task's `detail` is the only place its failure is legible. A running one-shot background subagent therefore appears both there and in the subagent catalog. The two answer different questions — the catalog navigates into the child's transcript, this list is the only handle a cancellation can ever attach to — and suppressing `kind: 'subagent'` here would leave the cancellation phase with no entry point for exactly those tasks. diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md index 5d1ee4bada..478acdf009 100644 --- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md +++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md @@ -66,7 +66,7 @@ abstract onJobsChanged(listener: JobsChangedListener): () => void `onJobDone` 不是它的子集。后者按 first-wins 语义投递终态记录和确切的 owner `Agent`,`dsh-tool-jobs` 把这套语义与 `reported` 绑在一起;`onJobsChanged` 是纯观察,不含任何投递含义,也不把任何东西标为已上报。监听器抛错被包住且从不 await,与 `onJobDone` 一致,每次注册都是调用方 fiber 上的 effect。 -服务销毁刻意什么都不通告。每个 `onJobsChanged` 注册都是注册表自身 fiber 上的 effect,等到 teardown 清空 store 时监听器早已消失;观察者通过自己的销毁而不是一份最终空集来得知注册表离开了。 +服务销毁会提交最后一次清空并通告它:注册表取消并等完自己的 job 之后,`onJobsChanged` 对每个可见集被 teardown 清空的 owner 触发一次,因此注册在更长命 fiber 上的监听器看到的是最终空集而不是陈旧名册(注册在注册表自身 fiber 上的监听器此时早已消失)。 ### Session Controller 载体 @@ -89,7 +89,7 @@ abstract onJobsChanged(listener: JobsChangedListener): () => void ### header 入口 -`@deepseek-ai/dsh-client-ui-jobs`(后并入 `dsh-client-ui-activity`) 在 `conversation.session.header.actions` 注册一个条目,排在 subagent 目录之后。呈现契约归它自己的 README;值得记在这里的决策是:会话没有任务时控件根本不渲染;活跃角标为零时省略,让只剩历史的会话保留一个安静的入口;终态行保持可见,因为失败任务的 `detail` 是其失败唯一可读之处。 +`@deepseek-ai/dsh-client-ui-jobs` 在 `conversation.session.header.actions` 注册一个条目,排在 preset 标签与 subagent 目录之间(`order: 20`,目录为 30)。呈现契约归它自己的 README;值得记在这里的决策是:会话没有任务时控件根本不渲染;活跃角标为零时省略,让只剩历史的会话保留一个安静的入口;终态行保持可见,因为失败任务的 `detail` 是其失败唯一可读之处。 因此一个运行中的一次性后台 subagent 会同时出现在那里和 subagent 目录里。两者回答不同的问题——目录负责进入子会话的 transcript,而这个列表是中断能力唯一可能附着的句柄——在这里屏蔽 `kind: 'subagent'` 会让中断那一期恰好对这批任务没有入口。 diff --git a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.i18n.yaml index 651ef99e3c..548e9f5b36 100644 --- a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-24-activity-observation-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 .agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md -2026-08-24-activity-observation-seam.md: 29ee08b1bb7f72a63d2f84278af62587060de3fe -2026-08-24-activity-observation-seam.zh.md: 97ac4f195c83cdd4f16d2f0a108abd2b3338d95d +2026-08-24-activity-observation-seam.md: 21fe08fd21ad95eec7a83f6f29b9b94514358bb9 +2026-08-24-activity-observation-seam.zh.md: ffb6766b3e5d226d324ea2894a6e3f758cf1932a diff --git a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md index 29ee08b1bb..21fe08fd21 100644 --- a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md +++ b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.md @@ -19,7 +19,7 @@ A new capability seam, `packages/activity/`, is the non-consuming observation pl - **`@deepseek-ai/dsh-activity` (Service Definition)** — abstract `ActivityRegistry` on `ctx.activities`: `open(spec) → ActivityHandle { append, updateDetail, end }`, fenced `get`/`list`, non-consuming `read(id, from)` over absolute UTF-8 byte offsets, owner-relative `onActivitiesChanged` (roster) and `onOutput` (advancement signal, id only). `ActivityCorrelation { callId?, jobId? }` links a row to its tool call and job. `pumpActivityOutput` is the shared pull-substrate pump. - **`@deepseek-ai/dsh-activity-local` (Service Provider)** — in-memory chunk ring per activity. Offsets stay absolute across eviction (`outputEarliest` marks the oldest retained byte; a read below it is `lossy`, never an error); a single over-cap chunk keeps its UTF-8-safe tail with `gapBefore`. Config `retainBytes` (256 KiB) live, trimmed to `settledRetainBytes` (16 KiB) at settlement. Records outlive producer fibers; owner disposal force-ends and removes; `end` is first-wins and post-end writes log-and-drop so a producer's trailing flush cannot break its own teardown. - **`@deepseek-ai/dsh-api-activity-controller`** — the wire, in the workspace-controller shape: `activity.control` streams one roster baseline then whole-bucket replacement frames per owner session (the jobs-frame self-healing semantics), and `activity.observe({ activityId, from? })` streams one `opened` anchor, coalesced `output` frames (`flushMs` window, `maxFrameBytes` soft budget), then the terminal `status` on the same stream before closing — so settlement can never race a still-open output channel. Reconnects resume from the last frame's `next`. The client half installs `ctx.activityFeed` (roster mirror plus reference-counted observation streams with a bounded render tail). -- **`@deepseek-ai/dsh-client-ui-activity`** — the session-header task list ([unified with the job rows](2026-08-25-unified-task-list.md)); expanding a row opens its observation stream into a `TerminalBlock` panel, collapsing closes it, so output only flows while someone is watching. `TerminalBlock` itself gained live rendering: a running block with supplied `output` shows the text under the running state instead of the historical prompt-only frame. +- **`@deepseek-ai/dsh-client-ui-activity`** — the session-header task list ([unified with the job rows](../../archived/feature/2026-08-25-unified-task-list.md)); expanding a row opens its observation stream into a `TerminalBlock` panel, collapsing closes it, so output only flows while someone is watching. `TerminalBlock` itself gained live rendering: a running block with supplied `output` shows the text under the running state instead of the historical prompt-only frame. Producers mirror best-effort behind `ctx.get('activities')`, never a declared inject, and every observation failure is logged and swallowed — the seam is strictly optional and can never break the work it observes: @@ -50,4 +50,4 @@ Unit suites pin the registry (offsets, eviction, UTF-8-safe tail trims, lossy re ## Consequences -The Web client now shows live output for background bash/pwsh and workflow narration with zero model-facing change, and any plugin can join with three calls (`open`/`append`/`end`) against an optional service. Bought at the cost of one more seam family and a per-producer tap; the initial two-header-list duplication was folded into [one task list](2026-08-25-unified-task-list.md). Deferred, recorded on the package READMEs: foreground streaming (needs a shell-seam run/observe variant), terminal `pty-send` observation (needs a non-consuming face on terminal buffers), a human kill control (blocked on the jobs `reported` contract), SDK/ACP consumers, and durable replay after restart. +The Web client now shows live output for background bash/pwsh and workflow narration with zero model-facing change, and any plugin can join with three calls (`open`/`append`/`end`) against an optional service. Bought at the cost of one more seam family and a per-producer tap; the initial two-header-list duplication was folded into [one task list](../../archived/feature/2026-08-25-unified-task-list.md). Deferred, recorded on the package READMEs: foreground streaming (needs a shell-seam run/observe variant), terminal `pty-send` observation (needs a non-consuming face on terminal buffers), a human kill control (blocked on the jobs `reported` contract), SDK/ACP consumers, and durable replay after restart. diff --git a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md index 97ac4f195c..ffb6766b3e 100644 --- a/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md +++ b/.agents/notes/implemented/feature/2026-08-24-activity-observation-seam.zh.md @@ -19,7 +19,7 @@ bash 之下的底座其实早有正确形态:`SubprocessOutputReader.readFrom( - **`@deepseek-ai/dsh-activity`(Service Definition)**——`ctx.activities` 上的抽象 `ActivityRegistry`:`open(spec) → ActivityHandle { append, updateDetail, end }`、有栅栏的 `get`/`list`、按绝对 UTF-8 字节 offset 的非消费 `read(id, from)`、owner 相对投递的 `onActivitiesChanged`(roster)与 `onOutput`(推进信号,只带 id)。`ActivityCorrelation { callId?, jobId? }` 把行关联到工具调用与 job。`pumpActivityOutput` 是 pull 型底座的共享泵。 - **`@deepseek-ai/dsh-activity-local`(Service Provider)**——每个 activity 一个内存 chunk 环。offset 跨淘汰稳定(`outputEarliest` 指明最老保留字节;低于它的读取是 `lossy` 而非错误);单个超上限 chunk 保留 UTF-8 安全尾部并带 `gapBefore`。配置 `retainBytes`(256 KiB)存活,结算时裁到 `settledRetainBytes`(16 KiB)。记录存续期长于生产者 fiber;owner 销毁强制终结并移除;`end` first-wins,end 后写入记日志后丢弃,生产者的收尾 flush 砸不掉自己的 teardown。 - **`@deepseek-ai/dsh-api-activity-controller`**——wire 层,取 workspace-controller 的形态:`activity.control` 流出一份 roster baseline 加按 owner 会话的整桶替换帧(jobs 帧的自愈语义);`activity.observe({ activityId, from? })` 流出一帧 `opened` 锚点、合并的 `output` 帧(`flushMs` 窗口、`maxFrameBytes` 软预算)、再在同一条流上发终态 `status` 后关闭——结算永远不会与仍开着的输出通道竞态。重连以上一帧的 `next` 续传。客户端半区安装 `ctx.activityFeed`(roster 镜像 + 按引用计数的观察流与有界渲染尾巴)。 -- **`@deepseek-ai/dsh-client-ui-activity`**——会话头部任务列表([与 job 行合并](2026-08-25-unified-task-list.zh.md));展开某行即把其观察流打开进 `TerminalBlock` 面板,收起即关——只有有人在看时输出才流动。`TerminalBlock` 本身获得实时渲染能力:running 且提供了 `output` 的块在 running 状态下显示文本,而非历史上的仅提示行画面。 +- **`@deepseek-ai/dsh-client-ui-activity`**——会话头部任务列表([与 job 行合并](../../archived/feature/2026-08-25-unified-task-list.md));展开某行即把其观察流打开进 `TerminalBlock` 面板,收起即关——只有有人在看时输出才流动。`TerminalBlock` 本身获得实时渲染能力:running 且提供了 `output` 的块在 running 状态下显示文本,而非历史上的仅提示行画面。 生产者一律经 `ctx.get('activities')` 尽力镜像,绝不声明 inject,一切观察失败只记日志并吞掉——该 seam 严格可选,永远不能破坏它所观察的工作: @@ -50,4 +50,4 @@ bash 之下的底座其实早有正确形态:`SubprocessOutputReader.readFrom( ## 后果 -Web 客户端在零模型面改动下获得后台 bash/pwsh 实时输出与 workflow 叙述;任何插件对着一个可选服务用三个调用(`open`/`append`/`end`)即可接入。代价是多一个 seam 家族与每生产者一个接入点;最初的双头部列表重复已折并为[单一任务列表](2026-08-25-unified-task-list.zh.md)。暂缓项记录在各包 README:前台流式(需 shell seam 的 run/observe 变体)、terminal `pty-send` 观察(需给 terminal 缓冲加非消费面)、人工 kill 控件(被 jobs `reported` 契约阻塞)、SDK/ACP 消费端、重启后的持久回放。 +Web 客户端在零模型面改动下获得后台 bash/pwsh 实时输出与 workflow 叙述;任何插件对着一个可选服务用三个调用(`open`/`append`/`end`)即可接入。代价是多一个 seam 家族与每生产者一个接入点;最初的双头部列表重复已折并为[单一任务列表](../../archived/feature/2026-08-25-unified-task-list.md)。暂缓项记录在各包 README:前台流式(需 shell seam 的 run/observe 变体)、terminal `pty-send` 观察(需给 terminal 缓冲加非消费面)、人工 kill 控件(被 jobs `reported` 契约阻塞)、SDK/ACP 消费端、重启后的持久回放。 diff --git a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.i18n.yaml b/.agents/notes/implemented/feature/2026-08-25-unified-task-list.i18n.yaml deleted file mode 100644 index eab6f6fa1b..0000000000 --- a/.agents/notes/implemented/feature/2026-08-25-unified-task-list.i18n.yaml +++ /dev/null @@ -1,6 +0,0 @@ -# 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 .agents/notes/implemented/feature/2026-08-25-unified-task-list.md -2026-08-25-unified-task-list.md: daf6582bf2c9e4b4a5ce26d6ae632fb78b30dbcb -2026-08-25-unified-task-list.zh.md: 624747396e175a216047239333575322ec4b1808 diff --git a/docs/subsystems/jobs.i18n.yaml b/docs/subsystems/jobs.i18n.yaml index 022befcbd2..8e4c26b4bb 100644 --- a/docs/subsystems/jobs.i18n.yaml +++ b/docs/subsystems/jobs.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 docs/subsystems/jobs.md -jobs.md: 0610d99892da22a25590ab7efe8ff71d9a004f01 -jobs.zh.md: 4c35fd7c879ddf7133c0db55df24948b40118b9d +jobs.md: 639faa8da3836cb3efc865c494cd8ca8c60f49fb +jobs.zh.md: 3d008671657847520eccd41b8a3bd75014777680 diff --git a/docs/subsystems/jobs.md b/docs/subsystems/jobs.md index 0610d99892..639faa8da3 100644 --- a/docs/subsystems/jobs.md +++ b/docs/subsystems/jobs.md @@ -23,42 +23,37 @@ interface JobKindMap { ## Producer contract -`JobStart` declares identity and a starter. The runtime finishes preflight before calling `run()` with the job's producer face and commits without a later failable step. Producers own execution resources; the runtime owns identity, access, and lifecycle state. +`JobStart` declares identity and a starter, discriminated by `record`: a `RecordingJobStart` receives the `RecordingJob` face, a `PlainJobStart` the `RunningJob` face without `append`. The runtime finishes preflight before calling `run()` with that face and commits without a later failable step. Producers own execution resources; the runtime owns identity, access, and lifecycle state. ```ts type-equiv /** - * Producer declaration passed to {@link JobRegistry.start}. The runtime - * preflights access and cleanup before invoking {@link run}; the producer owns - * execution resources while the runtime owns identity and lifecycle state. + * A start with the model-facing surfaces only. Its producer face carries no + * `append`, so output the registry would have nowhere to keep is + * unrepresentable rather than dropped. */ -interface JobStart { - /** Producer kind — also the id prefix (`bash`, `subagent`, …). */ - kind: JobKind - /** One-line model-facing label (the command; the delegation description). */ - label: string +interface PlainJobStart extends JobStartBase { + record?: undefined /** - * Optional UTF-8 byte cap for each complete model-facing completion notice or - * output read, including controller status metadata. Independent of record - * retention: it bounds the consuming model surface, never - * {@link JobRegistry.readRecord}. + * Start the work after preflight and synchronously return its hooks. Called + * once with the job's producer face; a throw leaves nothing registered (the + * spent ordinal is skipped), and the producer must clean up any partially + * started resources. + * @param job - the issued id plus the live-detail writer. */ - outputLimitBytes?: number - /** - * Owning live agent. Access is fenced by its session id, and agent disposal - * cancels and awaits the job. The instance must be the one currently - * registered under its agent id. Omitting the owner creates an unowned job, - * open to any caller until service disposal. - */ - owner?: Agent - /** - * Declares an observable output record beside the model-facing surfaces: - * {@link RunningJob.append} retains chunks in a bounded ring that any number - * of observers read at absolute byte offsets through - * {@link JobRegistry.readRecord}, and snapshots carry - * {@link JobSnapshot.outputTotal} and {@link JobSnapshot.outputEarliest}. - * Without the declaration `append` logs and drops. - */ - record?: true + run(job: RunningJob): JobHooks +} +``` + +```ts type-equiv +/** + * A start that declares an observable output record beside the model-facing + * surfaces: {@link RecordingJob.append} retains chunks in a bounded ring that + * any number of observers read at absolute byte offsets through + * {@link JobRegistry.readRecord}, and snapshots carry + * {@link JobSnapshot.outputTotal} and {@link JobSnapshot.outputEarliest}. + */ +interface RecordingJobStart extends JobStartBase { + record: true /** * Start the work after preflight and synchronously return its hooks. Called * once with the job's producer face; a throw leaves nothing registered (the @@ -66,10 +61,20 @@ interface JobStart { * started resources. * @param job - the issued id plus the record append and live-detail writers. */ - run(job: RunningJob): JobHooks + run(job: RecordingJob): JobHooks } ``` +```ts type-equiv +/** + * Producer declaration passed to {@link JobRegistry.start}, discriminated by + * `record`. The runtime preflights access and cleanup before invoking `run`; + * the producer owns execution resources while the runtime owns identity and + * lifecycle state. + */ +type JobStart = PlainJobStart | RecordingJobStart +``` + `JobHooks.done` resolves after the producer releases its resources, not merely when work finishes. Optional `readOutput` distinguishes consuming stream jobs from final-output-only jobs. ```ts type-equiv @@ -113,34 +118,38 @@ interface JobOutcome { ## Observation record -A producer that declares `record: true` streams raw output into a bounded per-job ring through the `RunningJob` face its starter receives; any number of observers read retained chunks at absolute byte offsets through `readRecord` without touching the consuming model cursor or notice state. Job settlement ends the stream and trims retention to the settled cap — the record has no separate lifecycle. `pumpJobOutput` copies producer offset-readers (the subprocess `readFrom` family) into the record at a bounded cadence. Browsers reach the record through `job.observe`, the Remote stream of [`dsh-api-job-controller`](../../packages/api/job-controller/README.md), whose frames are listed under its Cordis API section below. +A producer that declares `record: true` streams raw output into a bounded per-job ring through the `RecordingJob` face its starter receives; any number of observers read retained chunks at absolute byte offsets through `readRecord` without touching the consuming model cursor or notice state. Job settlement ends the stream and trims retention to the settled cap — the record has no separate lifecycle. `pumpJobOutput` copies producer offset-readers (the subprocess `readFrom` family) into the record at a bounded cadence. Browsers reach the record through `job.observe`, the Remote stream of [`dsh-api-job-controller`](../../packages/api/job-controller/README.md), whose frames are listed under its Cordis API section below. ```ts type-equiv /** - * Producer face of one registered job, handed to {@link JobStart.run} and - * valid for the job's whole life. All methods are synchronous. Writes staged - * inside the starter call are retained and become visible with the - * registration commit; after settlement — the producer's own outcome, a kill, - * or a registry-forced teardown end — both methods log and drop instead of - * throwing, so a producer's trailing flush cannot break its own teardown path. + * Producer face of one registered job, handed to `run` and valid for the + * job's whole life. All methods are synchronous. Writes staged inside the + * starter call are retained and become visible with the registration commit; + * after settlement — the producer's own outcome, a kill, or a registry-forced + * teardown end — writes log and drop instead of throwing, so a producer's + * trailing flush cannot break its own teardown path. */ interface RunningJob { /** The registry-issued id (`-N`). */ readonly id: JobId + /** + * Replace the snapshot's status detail with a live progress line (`3/10`). + * @param detail - the new detail line. + */ + updateDetail(detail: string): void +} +``` + +```ts type-equiv +/** Producer face of a {@link RecordingJobStart}: {@link RunningJob} plus the record append. */ +interface RecordingJob extends RunningJob { /** * Append one record chunk. Offsets advance by the chunk's UTF-8 byte - * length; an empty chunk is dropped without waking observers. Without a - * {@link JobStart.record} declaration the chunk is logged and dropped. + * length; an empty chunk is dropped without waking observers. * @param text - the chunk text, exactly as produced. * @param options - stream label and gap marker. */ append(text: string, options?: JobAppendOptions): void - /** - * Replace the snapshot's status detail with a live progress line (`3/10`). - * Works for every job, with or without a record. - * @param detail - the new detail line. - */ - updateDetail(detail: string): void } ``` @@ -368,7 +377,6 @@ abstract wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal */ abstract onJobDone(listener: JobDoneListener): () => void -/** /** * Register an effect-scoped observer of visible-set changes. It fires after * every commit that changes what {@link list} returns for that owner — diff --git a/docs/subsystems/jobs.zh.md b/docs/subsystems/jobs.zh.md index 4c35fd7c87..3d00867165 100644 --- a/docs/subsystems/jobs.zh.md +++ b/docs/subsystems/jobs.zh.md @@ -23,42 +23,37 @@ interface JobKindMap { ## 生产方约定 -`JobStart` 声明身份和启动器。运行时会在完成预检后携带该 job 的生产者面调用 `run()`,随后提交注册,不再执行可能失败的步骤。生产方拥有执行资源;运行时拥有身份、访问权限和生命周期状态。 +`JobStart` 声明身份和启动器,并按 `record` 判别:`RecordingJobStart` 收到 `RecordingJob` 面,`PlainJobStart` 收到没有 `append` 的 `RunningJob` 面。运行时会在完成预检后携带该面调用 `run()`,随后提交注册,不再执行可能失败的步骤。生产方拥有执行资源;运行时拥有身份、访问权限和生命周期状态。 ```ts type-equiv /** - * Producer declaration passed to {@link JobRegistry.start}. The runtime - * preflights access and cleanup before invoking {@link run}; the producer owns - * execution resources while the runtime owns identity and lifecycle state. + * A start with the model-facing surfaces only. Its producer face carries no + * `append`, so output the registry would have nowhere to keep is + * unrepresentable rather than dropped. */ -interface JobStart { - /** Producer kind — also the id prefix (`bash`, `subagent`, …). */ - kind: JobKind - /** One-line model-facing label (the command; the delegation description). */ - label: string +interface PlainJobStart extends JobStartBase { + record?: undefined /** - * Optional UTF-8 byte cap for each complete model-facing completion notice or - * output read, including controller status metadata. Independent of record - * retention: it bounds the consuming model surface, never - * {@link JobRegistry.readRecord}. + * Start the work after preflight and synchronously return its hooks. Called + * once with the job's producer face; a throw leaves nothing registered (the + * spent ordinal is skipped), and the producer must clean up any partially + * started resources. + * @param job - the issued id plus the live-detail writer. */ - outputLimitBytes?: number - /** - * Owning live agent. Access is fenced by its session id, and agent disposal - * cancels and awaits the job. The instance must be the one currently - * registered under its agent id. Omitting the owner creates an unowned job, - * open to any caller until service disposal. - */ - owner?: Agent - /** - * Declares an observable output record beside the model-facing surfaces: - * {@link RunningJob.append} retains chunks in a bounded ring that any number - * of observers read at absolute byte offsets through - * {@link JobRegistry.readRecord}, and snapshots carry - * {@link JobSnapshot.outputTotal} and {@link JobSnapshot.outputEarliest}. - * Without the declaration `append` logs and drops. - */ - record?: true + run(job: RunningJob): JobHooks +} +``` + +```ts type-equiv +/** + * A start that declares an observable output record beside the model-facing + * surfaces: {@link RecordingJob.append} retains chunks in a bounded ring that + * any number of observers read at absolute byte offsets through + * {@link JobRegistry.readRecord}, and snapshots carry + * {@link JobSnapshot.outputTotal} and {@link JobSnapshot.outputEarliest}. + */ +interface RecordingJobStart extends JobStartBase { + record: true /** * Start the work after preflight and synchronously return its hooks. Called * once with the job's producer face; a throw leaves nothing registered (the @@ -66,10 +61,20 @@ interface JobStart { * started resources. * @param job - the issued id plus the record append and live-detail writers. */ - run(job: RunningJob): JobHooks + run(job: RecordingJob): JobHooks } ``` +```ts type-equiv +/** + * Producer declaration passed to {@link JobRegistry.start}, discriminated by + * `record`. The runtime preflights access and cleanup before invoking `run`; + * the producer owns execution resources while the runtime owns identity and + * lifecycle state. + */ +type JobStart = PlainJobStart | RecordingJobStart +``` + `JobHooks.done` 会在生产方释放其资源后 resolve,而不是仅在工作完成时 resolve。可选的 `readOutput` 用来区分会消费输出的流式任务和仅有最终输出的任务。 ```ts type-equiv @@ -113,34 +118,38 @@ interface JobOutcome { ## 观测 record -声明 `record: true` 的生产方通过 starter 收到的 `RunningJob` 面把原始输出流入按 job 划分的有界环形缓冲;任意数量的观察者通过 `readRecord` 按绝对字节偏移读取保留块,不触碰消耗型的模型游标与通知状态。job 结算即封流并把保留量裁剪到结算上限——record 没有独立生命周期。`pumpJobOutput` 以有界节奏把生产方的偏移读取器(subprocess 的 `readFrom` 家族)复制进 record。浏览器经 [`dsh-api-job-controller`](../../packages/api/job-controller/README.zh.md) 的 Remote 流 `job.observe` 读取 record,其帧类型列在下方该控制器的 Cordis API 一节。 +声明 `record: true` 的生产方通过 starter 收到的 `RecordingJob` 面把原始输出流入按 job 划分的有界环形缓冲;任意数量的观察者通过 `readRecord` 按绝对字节偏移读取保留块,不触碰消耗型的模型游标与通知状态。job 结算即封流并把保留量裁剪到结算上限——record 没有独立生命周期。`pumpJobOutput` 以有界节奏把生产方的偏移读取器(subprocess 的 `readFrom` 家族)复制进 record。浏览器经 [`dsh-api-job-controller`](../../packages/api/job-controller/README.zh.md) 的 Remote 流 `job.observe` 读取 record,其帧类型列在下方该控制器的 Cordis API 一节。 ```ts type-equiv /** - * Producer face of one registered job, handed to {@link JobStart.run} and - * valid for the job's whole life. All methods are synchronous. Writes staged - * inside the starter call are retained and become visible with the - * registration commit; after settlement — the producer's own outcome, a kill, - * or a registry-forced teardown end — both methods log and drop instead of - * throwing, so a producer's trailing flush cannot break its own teardown path. + * Producer face of one registered job, handed to `run` and valid for the + * job's whole life. All methods are synchronous. Writes staged inside the + * starter call are retained and become visible with the registration commit; + * after settlement — the producer's own outcome, a kill, or a registry-forced + * teardown end — writes log and drop instead of throwing, so a producer's + * trailing flush cannot break its own teardown path. */ interface RunningJob { /** The registry-issued id (`-N`). */ readonly id: JobId + /** + * Replace the snapshot's status detail with a live progress line (`3/10`). + * @param detail - the new detail line. + */ + updateDetail(detail: string): void +} +``` + +```ts type-equiv +/** Producer face of a {@link RecordingJobStart}: {@link RunningJob} plus the record append. */ +interface RecordingJob extends RunningJob { /** * Append one record chunk. Offsets advance by the chunk's UTF-8 byte - * length; an empty chunk is dropped without waking observers. Without a - * {@link JobStart.record} declaration the chunk is logged and dropped. + * length; an empty chunk is dropped without waking observers. * @param text - the chunk text, exactly as produced. * @param options - stream label and gap marker. */ append(text: string, options?: JobAppendOptions): void - /** - * Replace the snapshot's status detail with a live progress line (`3/10`). - * Works for every job, with or without a record. - * @param detail - the new detail line. - */ - updateDetail(detail: string): void } ``` @@ -368,7 +377,6 @@ abstract wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal */ abstract onJobDone(listener: JobDoneListener): () => void -/** /** * Register an effect-scoped observer of visible-set changes. It fires after * every commit that changes what {@link list} returns for that owner — diff --git a/packages/api/job-controller/tests/observe.host.spec.ts b/packages/api/job-controller/tests/observe.host.spec.ts index 5bbb5a8c66..bc6827fdc2 100644 --- a/packages/api/job-controller/tests/observe.host.spec.ts +++ b/packages/api/job-controller/tests/observe.host.spec.ts @@ -3,7 +3,7 @@ import { Context } from '@deepseek-ai/cordis' import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import { JobId } from '@deepseek-ai/dsh-jobs' -import type { JobOutcome, RunningJob } from '@deepseek-ai/dsh-jobs' +import type { JobOutcome, RecordingJob } from '@deepseek-ai/dsh-jobs' import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session' import TypertRegistry from '@deepseek-ai/dsh-typert-registry' @@ -38,13 +38,13 @@ function registerAgent(ctx: Context, rawId: string): Agent { /** Start one record job whose done settles on demand; expose the producer face. */ function startRecordJob(ctx: Context, options: { label?: string; owner?: Agent; record?: boolean } = {}) { let settle!: (outcome: JobOutcome) => void - let face!: RunningJob + let face!: RecordingJob const id = ctx.jobs.start({ kind: 'bash', label: options.label ?? 'echo', ...options.owner !== undefined ? { owner: options.owner } : {}, ...options.record === false ? {} : { record: true }, - run: (job) => { + run: (job: RecordingJob) => { face = job return { cancel() {}, @@ -54,7 +54,7 @@ function startRecordJob(ctx: Context, options: { label?: string; owner?: Agent; }) return { id, - append: (text: string, opts?: Parameters[1]) => { face.append(text, opts) }, + append: (text: string, opts?: Parameters[1]) => { face.append(text, opts) }, updateDetail: (detail: string) => { face.updateDetail(detail) }, settle: async (outcome: JobOutcome) => { settle(outcome) diff --git a/packages/client/ui-jobs/src/client/index.ts b/packages/client/ui-jobs/src/client/index.ts index 209cec1f23..3edaf89efb 100644 --- a/packages/client/ui-jobs/src/client/index.ts +++ b/packages/client/ui-jobs/src/client/index.ts @@ -38,7 +38,8 @@ export function apply(ctx: ClientContext): void { () => ctx.slots.register({ name: 'conversation.session.header.actions', id: 'job-list', - // After the subagent catalog: session lineage reads before running work. + // Between the preset label and the subagent catalog (order 30): running + // work reads before the session lineage. order: 20, locale: NS, inject: (): JobListInjected => ({ diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 3002c82a56..ff56058008 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -1095,7 +1095,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ }, { signature: 'abstract onJobsChanged(listener: JobsChangedListener): () => void', - description: '/** Register an effect-scoped observer of visible-set changes. It fires after every commit that changes what list returns for that owner — registration, every stopping transition (including the one teardown performs before it awaits a slow producer), settlement, owner-disposal removal, and the emptying that service disposal commits — so an observer re-reads rather than accumulating deltas.\n\nDelivery is owner-relative on the same terms as onJobDone: an observer registered from an unscoped context — a host composition\'s own carrier — sees every owner, while one registered under an agent composition\'s scope sees exactly the agents composed under it.\n\nThis is not a superset of onJobDone: that one delivers the terminal record under first-wins semantics a job controller couples to notice delivery, while this one carries no delivery meaning and marks nothing reported. Listeners are contained and never awaited.', + description: 'Register an effect-scoped observer of visible-set changes. It fires after every commit that changes what list returns for that owner — registration, every stopping transition (including the one teardown performs before it awaits a slow producer), settlement, owner-disposal removal, and the emptying that service disposal commits — so an observer re-reads rather than accumulating deltas.\n\nDelivery is owner-relative on the same terms as onJobDone: an observer registered from an unscoped context — a host composition\'s own carrier — sees every owner, while one registered under an agent composition\'s scope sees exactly the agents composed under it.\n\nThis is not a superset of onJobDone: that one delivers the terminal record under first-wins semantics a job controller couples to notice delivery, while this one carries no delivery meaning and marks nothing reported. Listeners are contained and never awaited.', parameters: [{ name: 'listener', description: 'receives the owner whose visible set changed, or `undefined` when an unowned job changed and every caller\'s set did.' }], returns: 'disposer that unregisters the listener.', }, @@ -4239,7 +4239,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'JobStart', - declaration: 'export interface JobStart {\n kind: JobKind;\n label: string;\n outputLimitBytes?: number;\n owner?: Agent;\n record?: true;\n run(job: RunningJob): JobHooks;\n}', + declaration: 'export type JobStart = PlainJobStart | RecordingJobStart;', }, { name: 'JobStatus', @@ -4537,6 +4537,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'PermissionSelect', declaration: 'export interface PermissionSelect {\n options: PresetOption[];\n currentValue: string;\n}', }, + { + name: 'PlainJobStart', + declaration: 'export interface PlainJobStart extends JobStartBase {\n record?: undefined;\n run(job: RunningJob): JobHooks;\n}', + }, { name: 'PostToolDecision', declaration: 'export type PostToolDecision = {\n kind: \'accept\';\n content?: ContentBlock[];\n value?: never;\n additionalContexts?: UserMessage[];\n} | {\n kind: \'accept\';\n value: JsonValue;\n content?: never;\n additionalContexts?: UserMessage[];\n} | {\n kind: \'block\';\n feedback: ContentBlock[];\n additionalContexts?: UserMessage[];\n};', @@ -4657,6 +4661,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'ReasoningEffortId', declaration: 'export type ReasoningEffortId = Branded<\'ReasoningEffortId\'>;', }, + { + name: 'RecordingJob', + declaration: 'export interface RecordingJob extends RunningJob {\n append(text: string, options?: JobAppendOptions): void;\n}', + }, + { + name: 'RecordingJobStart', + declaration: 'export interface RecordingJobStart extends JobStartBase {\n record: true;\n run(job: RecordingJob): JobHooks;\n}', + }, { name: 'RedactedSecret', declaration: 'export interface RedactedSecret {\n path: string[];\n set: boolean;\n}', @@ -4739,7 +4751,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'RunningJob', - declaration: 'export interface RunningJob {\n readonly id: JobId;\n append(text: string, options?: JobAppendOptions): void;\n updateDetail(detail: string): void;\n}', + declaration: 'export interface RunningJob {\n readonly id: JobId;\n updateDetail(detail: string): void;\n}', }, { name: 'SandboxEnforcement', diff --git a/packages/jobs/jobs-local/src/index.ts b/packages/jobs/jobs-local/src/index.ts index 15cb5336b0..e5415aee15 100644 --- a/packages/jobs/jobs-local/src/index.ts +++ b/packages/jobs/jobs-local/src/index.ts @@ -19,7 +19,7 @@ import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout' import { JobRegistry, JobId } from '@deepseek-ai/dsh-jobs' import type { JobAppendOptions, JobChannel, JobDoneListener, JobKind, JobOutcome, JobOutputListener, JobRead, - JobRecordChunk, JobRecordRead, JobSnapshot, JobStart, JobStatus, JobsChangedListener, RunningJob, + JobRecordChunk, JobRecordRead, JobSnapshot, JobStart, JobStatus, JobsChangedListener, RecordingJob, RunningJob, } from '@deepseek-ai/dsh-jobs' /** Timeout code that distinguishes a bounded wait from caller cancellation. */ @@ -236,17 +236,13 @@ export class LocalJobRegistry extends JobRegistry { const count = (this.counters.get(spec.kind) ?? 0) + 1 this.counters.set(spec.kind, count) const id = JobId(`${spec.kind}-${count}`) - const state: ProducerState = { - record: spec.record === true ? { chunks: [], retainedBytes: 0, total: 0, earliest: 0 } : undefined, - detail: undefined, - job: undefined, - } - const handle: RunningJob = { + const state: ProducerState = { record: undefined, detail: undefined, job: undefined } + const face: RunningJob = { id, - append: (text, options) => { this.appendRecord(id, state, text, options) }, updateDetail: (detail) => { this.updateDetail(state, detail) }, } - const hooks = spec.run(handle) + // The declaration decides the face: a plain start never receives `append`. + const hooks = spec.record === true ? spec.run(this.recordingFace(face, state)) : spec.run(face) let markSettled!: () => void const settled = new Promise((resolve) => { markSettled = resolve }) @@ -556,23 +552,28 @@ export class LocalJobRegistry extends JobRegistry { } } + /** Install the job's record and extend the producer face with its append. */ + private recordingFace(face: RunningJob, state: ProducerState): RecordingJob { + const record: RecordState = { chunks: [], retainedBytes: 0, total: 0, earliest: 0 } + state.record = record + return { + ...face, + append: (text, options) => { this.appendRecord(state, record, text, options) }, + } + } + /** - * Append one chunk through a producer face. A chunk against a settled job or - * without a record declaration is logged and dropped; an empty chunk is - * dropped silently. A chunk staged inside the starter call is retained and - * signals no observer — the registration commit publishes it. + * Append one chunk through a recording producer face. A chunk against a + * settled job is logged and dropped; an empty chunk is dropped silently. A + * chunk staged inside the starter call is retained and signals no observer — + * the registration commit publishes it. */ - private appendRecord(id: JobId, state: ProducerState, text: string, options?: JobAppendOptions): void { + private appendRecord(state: ProducerState, record: RecordState, text: string, options?: JobAppendOptions): void { const job = state.job if (job !== undefined && isTerminal(job.status)) { this.selfCtx.logger.warn(`jobs: append to settled job ${job.id} dropped`) return } - const record = state.record - if (record === undefined) { - this.selfCtx.logger.warn(`jobs: append to job ${id} without a record declaration dropped`) - return - } if (text.length === 0) return const bytes = Buffer.byteLength(text, 'utf8') record.chunks.push({ diff --git a/packages/jobs/jobs-local/tests/jobs.spec.ts b/packages/jobs/jobs-local/tests/jobs.spec.ts index 9771023057..5bcb9b156e 100644 --- a/packages/jobs/jobs-local/tests/jobs.spec.ts +++ b/packages/jobs/jobs-local/tests/jobs.spec.ts @@ -6,7 +6,7 @@ import type { Agent } from '@deepseek-ai/dsh-agent' import { bindScopeParent, createScope, scopeOf } from '@deepseek-ai/dsh-scope' import type { ScopeKey } from '@deepseek-ai/dsh-scope' import { JobId } from '@deepseek-ai/dsh-jobs' -import type { JobHooks, JobKind, JobOutcome, JobSnapshot, JobStart, RunningJob } from '@deepseek-ai/dsh-jobs' +import type { JobHooks, JobKind, JobOutcome, JobSnapshot, JobStart, RecordingJob } from '@deepseek-ai/dsh-jobs' import LocalJobRegistry, { type Config as JobsConfig } from '@deepseek-ai/dsh-jobs-local' declare module '@deepseek-ai/dsh-jobs' { @@ -66,14 +66,14 @@ function producer(overrides: Partial & JobHooks> = {}) { done: new Promise((res, rej) => { settle = res; reject = rej }), ...hookOverrides, } - let started: RunningJob | undefined + let started: RecordingJob | undefined const spec: JobStart = { kind, label, ...owner !== undefined ? { owner } : {}, ...outputLimitBytes !== undefined ? { outputLimitBytes } : {}, ...record !== undefined ? { record } : {}, - run: (job) => { + run: (job: RecordingJob) => { started = job return hooks }, @@ -83,7 +83,7 @@ function producer(overrides: Partial & JobHooks> = {}) { settle, reject, cancels, - job(): RunningJob { + job(): RecordingJob { if (started === undefined) throw new Error('producer not started') return started }, @@ -200,7 +200,7 @@ describe('LocalJobRegistry.start', () => { for (const job of live) ctx.jobs.start(job.spec) const blocked = producer() - const run = vi.fn((job: RunningJob) => blocked.spec.run(job)) + const run = vi.fn((job: RecordingJob) => blocked.spec.run(job)) expect(() => ctx.jobs.start({ ...blocked.spec, run })) .toThrow('background job limit reached for this owner (limit: 10)') expect(run).not.toHaveBeenCalled() @@ -213,7 +213,7 @@ describe('LocalJobRegistry.start', () => { expect(ctx.jobs.start(first.spec)).toBe('bash-1') const blocked = producer() - const run = vi.fn((job: RunningJob) => blocked.spec.run(job)) + const run = vi.fn((job: RecordingJob) => blocked.spec.run(job)) expect(() => ctx.jobs.start({ ...blocked.spec, run })) .toThrow('use job_kill to stop an unneeded job, wait for it to finish, then retry') expect(run).not.toHaveBeenCalled() @@ -658,7 +658,7 @@ describe('LocalJobRegistry owner isolation', () => { ctx.jobs.start(current.spec) // Attach the current owner's cleanup first. const stale = producer({ owner: staleOwner }) - const staleRun = vi.fn((job: RunningJob) => stale.spec.run(job)) + const staleRun = vi.fn((job: RecordingJob) => stale.spec.run(job)) expect(() => ctx.jobs.start({ ...stale.spec, run: staleRun })) .toThrow('is not the registered agent instance') expect(staleRun).not.toHaveBeenCalled() @@ -1223,14 +1223,12 @@ describe('LocalJobRegistry record', () => { expect(ctx.jobs.get(id).outputTotal).toBe(0) }) - it('logs and drops an append without a record declaration; updateDetail still works', async () => { + it('hands a start without a record declaration no append; updateDetail still works', async () => { const ctx = await harness() - const warn = vi.fn() - ctx.logger.warn = warn as never const p = producer() const id = ctx.jobs.start(p.spec) - p.job().append('nowhere to land') - expect(warn).toHaveBeenCalledWith(expect.stringContaining(`append to job ${id} without a record declaration dropped`)) + // The plain face is built without the method, not with a dropping stub. + expect(p.job()).not.toHaveProperty('append') expect(() => ctx.jobs.readRecord(id, 0)).toThrow(`job ${id} declared no output record`) const snapshot = ctx.jobs.get(id) expect(snapshot.outputTotal).toBeUndefined() diff --git a/packages/jobs/jobs/README.i18n.yaml b/packages/jobs/jobs/README.i18n.yaml index 662a521a55..54d4ecc8e9 100644 --- a/packages/jobs/jobs/README.i18n.yaml +++ b/packages/jobs/jobs/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/jobs/jobs/README.md -README.md: 10c74af908f64c18616e3c1eb71f19a3cbbf4eb3 -README.zh.md: 1fc500311c58a538ebfc7fbd89886d9c12b96acd +README.md: 5d4e10de9fa852dc4a38c521321bae53c744909b +README.zh.md: b584191a6b94e79ba8908875e7a0706a525edf4f diff --git a/packages/jobs/jobs/README.md b/packages/jobs/jobs/README.md index 10c74af908..5d4e10de9f 100644 --- a/packages/jobs/jobs/README.md +++ b/packages/jobs/jobs/README.md @@ -31,7 +31,7 @@ Use this package when you are composing a background-job capability or writing a A producer registers work with a kind and a one-line label; the registry returns a `-N` id such as `bash-1`. Anyone who owns the job can read output, list jobs, wait up to a timeout for settlement, and request cancellation — each call returns a fresh snapshot of the job's status, from `running` and `stopping` to the terminal `completed`, `killed`, or `failed`. When a job settles, the owning agent is notified through the completion listener that `dsh-tool-jobs` turns into an in-session notice, so no polling is needed. A producer may attach an optional byte cap so each complete model-facing output read or completion notice stays bounded. -A producer that declares `record: true` additionally streams raw output into the job's bounded record through the `RunningJob` face its starter receives: observers read retained chunks at absolute byte offsets and get signaled on advancement, the settlement that ends the job also ends the stream, and `updateDetail` publishes a live progress line into every snapshot. The record is invisible to the model: reads consume nothing and never touch notice state. +A producer that declares `record: true` additionally streams raw output into the job's bounded record through the `RecordingJob` face its starter receives — a start without the declaration receives the plain `RunningJob` face, which has no `append`: observers read retained chunks at absolute byte offsets and get signaled on advancement, the settlement that ends the job also ends the stream, and `updateDetail` publishes a live progress line into every snapshot. The record is invisible to the model: reads consume nothing and never touch notice state. ### The ownership boundary @@ -77,7 +77,7 @@ This section explains the design decisions behind the contract and points at the | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | Plugin entry: the abstract `JobRegistry` service and its contract | -| [`src/types.ts`](src/types.ts) | Shared vocabulary: `JobKindMap`, `JobStart`, `JobHooks`, `RunningJob`, `JobSnapshot`, listener types | +| [`src/types.ts`](src/types.ts) | Shared vocabulary: `JobKindMap`, `JobStart`, `JobHooks`, `RunningJob`, `RecordingJob`, `JobSnapshot`, listener types | | [`src/brand.ts`](src/brand.ts) | `JobId` branded identifier, importable without the agent dependency | | [`src/pump.ts`](src/pump.ts) | `pumpJobOutput`: poll pump copying producer offset-readers into a job record | | [`src/invariant.ts`](src/invariant.ts) | Invariant companion: validates snapshot identity, status, timestamps, owner, and record-offset fields | diff --git a/packages/jobs/jobs/README.zh.md b/packages/jobs/jobs/README.zh.md index 1fc500311c..b584191a6b 100644 --- a/packages/jobs/jobs/README.zh.md +++ b/packages/jobs/jobs/README.zh.md @@ -31,7 +31,7 @@ kind: "package-reference" 生产方以 kind 和一行标签注册工作;注册表返回 `-N` id,例如 `bash-1`。拥有任务的任何一方都可以读取输出、列出任务、带超时等待结算或请求取消——每次调用都返回任务状态的全新快照,从 `running`、`stopping` 到终止态的 `completed`、`killed` 或 `failed`。任务结算时,拥有它的 agent 会通过 `dsh-tool-jobs` 转成会话内通知的完成监听器得到通知,因此无需轮询。生产方还可以附加可选的字节上限,让每次完整的模型侧输出读取或完成通知保持有界。 -声明 `record: true` 的生产方还会通过 starter 收到的 `RunningJob` 面把原始输出流入该 job 的有界 record:观察者按绝对字节偏移读取保留块并在推进时收到信号,结束 job 的结算同时封流,`updateDetail` 把实时进度行发布进每个快照。record 对模型不可见:读取不消耗任何东西,也永不触碰通知状态。 +声明 `record: true` 的生产方还会通过 starter 收到的 `RecordingJob` 面(未声明的 start 收到的是没有 `append` 的普通 `RunningJob` 面)把原始输出流入该 job 的有界 record:观察者按绝对字节偏移读取保留块并在推进时收到信号,结束 job 的结算同时封流,`updateDetail` 把实时进度行发布进每个快照。record 对模型不可见:读取不消耗任何东西,也永不触碰通知状态。 ### 归属边界 @@ -77,7 +77,7 @@ kind: "package-reference" | 文件 | 职责 | |---|---| | [`src/index.ts`](src/index.ts) | 插件入口:抽象 `JobRegistry` 服务及其约定 | -| [`src/types.ts`](src/types.ts) | 共享词汇:`JobKindMap`、`JobStart`、`JobHooks`、`RunningJob`、`JobSnapshot`、监听器类型 | +| [`src/types.ts`](src/types.ts) | 共享词汇:`JobKindMap`、`JobStart`、`JobHooks`、`RunningJob`、`RecordingJob`、`JobSnapshot`、监听器类型 | | [`src/brand.ts`](src/brand.ts) | `JobId` 带类型标记的标识符,无需 agent 依赖即可导入 | | [`src/pump.ts`](src/pump.ts) | `pumpJobOutput`:把生产方偏移读取器复制进 job record 的轮询泵 | | [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件:校验快照标识、状态、时间戳、所有者与 record 偏移字段 | diff --git a/packages/jobs/jobs/src/index.ts b/packages/jobs/jobs/src/index.ts index 796afc0882..4b6d6d9d43 100644 --- a/packages/jobs/jobs/src/index.ts +++ b/packages/jobs/jobs/src/index.ts @@ -33,6 +33,9 @@ export type { JobStart, JobStatus, JobsChangedListener, + PlainJobStart, + RecordingJob, + RecordingJobStart, RunningJob, } from './types.ts' export { pumpJobOutput } from './pump.ts' @@ -163,7 +166,6 @@ export abstract class JobRegistry extends Service { */ abstract onJobDone(listener: JobDoneListener): () => void - /** /** * Register an effect-scoped observer of visible-set changes. It fires after * every commit that changes what {@link list} returns for that owner — diff --git a/packages/jobs/jobs/src/pump.ts b/packages/jobs/jobs/src/pump.ts index 5203157a9f..a3c1956019 100644 --- a/packages/jobs/jobs/src/pump.ts +++ b/packages/jobs/jobs/src/pump.ts @@ -5,7 +5,7 @@ * @module */ -import type { JobChannel, RunningJob } from './types.ts' +import type { JobChannel, RecordingJob } from './types.ts' /** One non-consuming offset read from a producer-owned stream. */ export interface JobPumpRead { @@ -74,7 +74,7 @@ export interface JobPumpOptions { * @returns resolves after the final post-settlement drain. */ export async function pumpJobOutput( - job: RunningJob, + job: RecordingJob, sources: readonly JobPumpSource[], options: JobPumpOptions, ): Promise { diff --git a/packages/jobs/jobs/src/types.ts b/packages/jobs/jobs/src/types.ts index b42d7815e4..3ec3f87357 100644 --- a/packages/jobs/jobs/src/types.ts +++ b/packages/jobs/jobs/src/types.ts @@ -56,12 +56,8 @@ export interface JobAppendOptions { gapBefore?: true } -/** - * Producer declaration passed to {@link JobRegistry.start}. The runtime - * preflights access and cleanup before invoking {@link run}; the producer owns - * execution resources while the runtime owns identity and lifecycle state. - */ -export interface JobStart { +/** Fields shared by every producer declaration passed to {@link JobRegistry.start}. */ +interface JobStartBase { /** Producer kind — also the id prefix (`bash`, `subagent`, …). */ kind: JobKind /** One-line model-facing label (the command; the delegation description). */ @@ -80,15 +76,34 @@ export interface JobStart { * open to any caller until service disposal. */ owner?: Agent +} + +/** + * A start with the model-facing surfaces only. Its producer face carries no + * `append`, so output the registry would have nowhere to keep is + * unrepresentable rather than dropped. + */ +export interface PlainJobStart extends JobStartBase { + record?: undefined /** - * Declares an observable output record beside the model-facing surfaces: - * {@link RunningJob.append} retains chunks in a bounded ring that any number - * of observers read at absolute byte offsets through - * {@link JobRegistry.readRecord}, and snapshots carry - * {@link JobSnapshot.outputTotal} and {@link JobSnapshot.outputEarliest}. - * Without the declaration `append` logs and drops. + * Start the work after preflight and synchronously return its hooks. Called + * once with the job's producer face; a throw leaves nothing registered (the + * spent ordinal is skipped), and the producer must clean up any partially + * started resources. + * @param job - the issued id plus the live-detail writer. */ - record?: true + run(job: RunningJob): JobHooks +} + +/** + * A start that declares an observable output record beside the model-facing + * surfaces: {@link RecordingJob.append} retains chunks in a bounded ring that + * any number of observers read at absolute byte offsets through + * {@link JobRegistry.readRecord}, and snapshots carry + * {@link JobSnapshot.outputTotal} and {@link JobSnapshot.outputEarliest}. + */ +export interface RecordingJobStart extends JobStartBase { + record: true /** * Start the work after preflight and synchronously return its hooks. Called * once with the job's producer face; a throw leaves nothing registered (the @@ -96,34 +111,44 @@ export interface JobStart { * started resources. * @param job - the issued id plus the record append and live-detail writers. */ - run(job: RunningJob): JobHooks + run(job: RecordingJob): JobHooks } /** - * Producer face of one registered job, handed to {@link JobStart.run} and - * valid for the job's whole life. All methods are synchronous. Writes staged - * inside the starter call are retained and become visible with the - * registration commit; after settlement — the producer's own outcome, a kill, - * or a registry-forced teardown end — both methods log and drop instead of - * throwing, so a producer's trailing flush cannot break its own teardown path. + * Producer declaration passed to {@link JobRegistry.start}, discriminated by + * `record`. The runtime preflights access and cleanup before invoking `run`; + * the producer owns execution resources while the runtime owns identity and + * lifecycle state. + */ +export type JobStart = PlainJobStart | RecordingJobStart + +/** + * Producer face of one registered job, handed to `run` and valid for the + * job's whole life. All methods are synchronous. Writes staged inside the + * starter call are retained and become visible with the registration commit; + * after settlement — the producer's own outcome, a kill, or a registry-forced + * teardown end — writes log and drop instead of throwing, so a producer's + * trailing flush cannot break its own teardown path. */ export interface RunningJob { /** The registry-issued id (`-N`). */ readonly id: JobId + /** + * Replace the snapshot's status detail with a live progress line (`3/10`). + * @param detail - the new detail line. + */ + updateDetail(detail: string): void +} + +/** Producer face of a {@link RecordingJobStart}: {@link RunningJob} plus the record append. */ +export interface RecordingJob extends RunningJob { /** * Append one record chunk. Offsets advance by the chunk's UTF-8 byte - * length; an empty chunk is dropped without waking observers. Without a - * {@link JobStart.record} declaration the chunk is logged and dropped. + * length; an empty chunk is dropped without waking observers. * @param text - the chunk text, exactly as produced. * @param options - stream label and gap marker. */ append(text: string, options?: JobAppendOptions): void - /** - * Replace the snapshot's status detail with a live progress line (`3/10`). - * Works for every job, with or without a record. - * @param detail - the new detail line. - */ - updateDetail(detail: string): void } /** Hooks through which the runtime controls and observes producer work. */ diff --git a/packages/jobs/jobs/tests/service.spec.ts b/packages/jobs/jobs/tests/service.spec.ts index 3938328478..331bf6596b 100644 --- a/packages/jobs/jobs/tests/service.spec.ts +++ b/packages/jobs/jobs/tests/service.spec.ts @@ -3,8 +3,8 @@ import { Context } from '@deepseek-ai/cordis' import type { Agent } from '@deepseek-ai/dsh-agent' import { JobId, JobRegistry, pumpJobOutput } from '@deepseek-ai/dsh-jobs' import type { - JobAppendOptions, JobDoneListener, JobOutputListener, JobPumpSource, JobRead, JobRecordRead, - JobSnapshot, JobStart, JobsChangedListener, RunningJob, + JobAppendOptions, JobDoneListener, JobHooks, JobOutputListener, JobPumpSource, JobRead, JobRecordRead, + JobSnapshot, JobStart, JobsChangedListener, PlainJobStart, RecordingJob, RecordingJobStart, } from '@deepseek-ai/dsh-jobs' /** @@ -71,6 +71,40 @@ class StubJobRegistry extends JobRegistry { } } +/** Compile-time probe: does the producer face `Face` carry `append`? */ +type HasAppend = 'append' extends keyof Face ? true : false + +describe('JobStart producer faces', () => { + it('hands append only to a start that declares a record', () => { + const hooks: JobHooks = { cancel() {}, done: new Promise(() => {}) } + // The literal's `record` discriminant selects the face `run` receives. + const plain: JobStart = { + kind: 'bash', + label: 'no record', + run: (job) => { + job.updateDetail('works for every job') + return hooks + }, + } + const recording: JobStart = { + kind: 'bash', + label: 'record', + record: true, + run: (job) => { + job.append('lands in the record') + return hooks + }, + } + // Negative proof: a plain start's face has no `append` at the type level. + const plainFace: HasAppend[0]> = false + const recordingFace: HasAppend[0]> = true + expect(plainFace).toBe(false) + expect(recordingFace).toBe(true) + expect(plain.record).toBeUndefined() + expect(recording.record).toBe(true) + }) +}) + describe('JobRegistry seam', () => { it('a concrete subclass registers as ctx.jobs and serves the abstract API', async () => { const ctx = new Context() @@ -109,9 +143,9 @@ describe('JobRegistry seam', () => { }) /** Record every append so pump behavior is observable without a registry. */ -function recordingJob(): { job: RunningJob; appends: { text: string; options?: JobAppendOptions }[] } { +function recordingJob(): { job: RecordingJob; appends: { text: string; options?: JobAppendOptions }[] } { const appends: { text: string; options?: JobAppendOptions }[] = [] - const job: RunningJob = { + const job: RecordingJob = { id: JobId('bash-1'), append(text, options) { appends.push({ text, ...options !== undefined ? { options } : {} }) }, updateDetail() {}, diff --git a/packages/shell/tool-bash/src/observe.ts b/packages/shell/tool-bash/src/observe.ts index 0758be7b7b..89a28817bc 100644 --- a/packages/shell/tool-bash/src/observe.ts +++ b/packages/shell/tool-bash/src/observe.ts @@ -15,7 +15,7 @@ import type { Context } from '@deepseek-ai/cordis' import type { ShellProcess } from '@deepseek-ai/dsh-shell' import { pumpJobOutput } from '@deepseek-ai/dsh-jobs' -import type { JobPumpSource, RunningJob } from '@deepseek-ai/dsh-jobs' +import type { JobPumpSource, RecordingJob } from '@deepseek-ai/dsh-jobs' /** * Pump the process's non-consuming offset readers into the job record until @@ -31,7 +31,7 @@ import type { JobPumpSource, RunningJob } from '@deepseek-ai/dsh-jobs' */ export function observeProcessRecord( ctx: Context, - job: RunningJob, + job: RecordingJob, proc: ShellProcess, pollMs: number, ): Promise { diff --git a/packages/shell/tool-bash/tests/observe.spec.ts b/packages/shell/tool-bash/tests/observe.spec.ts index 8a4ac6ae2a..4586ada7a5 100644 --- a/packages/shell/tool-bash/tests/observe.spec.ts +++ b/packages/shell/tool-bash/tests/observe.spec.ts @@ -10,7 +10,7 @@ import ToolRuntime from '@deepseek-ai/dsh-tools' import AgentRegistry from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' -import type { JobId, RunningJob } from '@deepseek-ai/dsh-jobs' +import type { JobId, RecordingJob } from '@deepseek-ai/dsh-jobs' import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs' import type { ShellProcess } from '@deepseek-ai/dsh-shell' import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local' @@ -121,8 +121,8 @@ describe('background bash record', () => { }) describe('observeProcessRecord', () => { - /** A RunningJob face recording appends for pump assertions. */ - function recordingJob(): { job: RunningJob; appends: string[] } { + /** A RecordingJob face recording appends for pump assertions. */ + function recordingJob(): { job: RecordingJob; appends: string[] } { const appends: string[] = [] return { job: { diff --git a/packages/shell/tool-pwsh/src/observe.ts b/packages/shell/tool-pwsh/src/observe.ts index 911145bd93..357567e31e 100644 --- a/packages/shell/tool-pwsh/src/observe.ts +++ b/packages/shell/tool-pwsh/src/observe.ts @@ -16,7 +16,7 @@ import type { Context } from '@deepseek-ai/cordis' import type { ShellProcess } from '@deepseek-ai/dsh-shell' import { pumpJobOutput } from '@deepseek-ai/dsh-jobs' -import type { JobPumpSource, RunningJob } from '@deepseek-ai/dsh-jobs' +import type { JobPumpSource, RecordingJob } from '@deepseek-ai/dsh-jobs' /** * Pump the process's non-consuming offset readers into the job record until @@ -32,7 +32,7 @@ import type { JobPumpSource, RunningJob } from '@deepseek-ai/dsh-jobs' */ export function observeProcessRecord( ctx: Context, - job: RunningJob, + job: RecordingJob, proc: ShellProcess, pollMs: number, ): Promise { diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index ac52455c6d..b78e1dcf07 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -513,6 +513,9 @@ export const LINK_MAP: Readonly> = { JobWireChunk: 'jobs.md', JobSnapshot: 'jobs.md', JobStart: 'jobs.md', + PlainJobStart: 'jobs.md', + RecordingJob: 'jobs.md', + RecordingJobStart: 'jobs.md', JobsChangedListener: 'jobs.md', JobAppendOptions: 'jobs.md', JobChannel: 'jobs.md', diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 2c24e9b407..327f58f9e3 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -1006,6 +1006,16 @@ "symbol": "JobKindMap", "source": "packages/jobs/jobs/src/types.ts" }, + { + "doc": "docs/subsystems/jobs.md", + "symbol": "PlainJobStart", + "source": "packages/jobs/jobs/src/types.ts" + }, + { + "doc": "docs/subsystems/jobs.md", + "symbol": "RecordingJobStart", + "source": "packages/jobs/jobs/src/types.ts" + }, { "doc": "docs/subsystems/jobs.md", "symbol": "JobStart", @@ -1036,6 +1046,11 @@ "symbol": "RunningJob", "source": "packages/jobs/jobs/src/types.ts" }, + { + "doc": "docs/subsystems/jobs.md", + "symbol": "RecordingJob", + "source": "packages/jobs/jobs/src/types.ts" + }, { "doc": "docs/subsystems/jobs.md", "symbol": "JobRecordChunk", diff --git a/snapshots/web/cordis-tool-round/session.jsonl b/snapshots/web/cordis-tool-round/session.jsonl index e69dbc7f2a..354033a43e 100644 --- a/snapshots/web/cordis-tool-round/session.jsonl +++ b/snapshots/web/cordis-tool-round/session.jsonl @@ -1,4 +1,4 @@ -{"type":"session","version":0,"id":"{{session:1}}","createdAt":1788357779640,"cwd":"{{cwd}}","agentPreset":"standard"} +{"type":"session","version":0,"id":"{{session:1}}","createdAt":1787736473857,"cwd":"{{cwd}}","agentPreset":"standard"} {"type":"permission/preset","data":{"preset":"workspace-write"}} {"type":"sandbox/mode","data":{"mode":"workspace-write"}} {"type":"approval/policy","data":{"policy":"ask"}} From 09bd6bcf54a1dbc792fb8b79bac9d20515dd59cc Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 13:45:09 +0800 Subject: [PATCH 026/100] chore(http-proxy): align the package version with the 0.1.2-rc.1 bump --- packages/util/http-proxy/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/util/http-proxy/package.json b/packages/util/http-proxy/package.json index b626e431e3..d75ba94f36 100644 --- a/packages/util/http-proxy/package.json +++ b/packages/util/http-proxy/package.json @@ -1,7 +1,7 @@ { "name": "@deepseek-ai/dsh-http-proxy", "description": "Process-wide outbound HTTP proxy policy for DeepSeek Harness: resolve it from the launch environment and install it as undici's global dispatcher", - "version": "0.1.2-alpha.5", + "version": "0.1.2-rc.1", "publishConfig": { "access": "public" }, From 07941fe5e2a18abd89faa1a09f395dad164a8b66 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 15:51:39 +0800 Subject: [PATCH 027/100] refactor(jobs): consolidate the seam into JobSpec, VisibleJobs, and one event stream The registry seam keeps three members plus the controller handshake: `start(spec)`, `visibleTo(caller)` (one authorization, then list / get / read / readAt / kill / wait without a caller argument), and `events` (one typed stream with an explicit filter instead of three listeners). Every job owns an output ring: `JobSpec.output` names pull sources the registry pumps, `JobHandle.append` pushes, and the model's consuming `read` and observers' `readAt` read the same bytes through separate cursors. `reported`, the `record` declaration, the producer `readOutput` hook, and the `JobStart`/`RunningJob` split are gone; `JobView` is the one projection, split into `progress` and terminal `detail`. The client-safe `./view` leaf carries the projection vocabulary. --- packages/jobs/jobs/package.json | 4 + packages/jobs/jobs/src/index.ts | 207 +++------- packages/jobs/jobs/src/invariant.ts | 53 ++- packages/jobs/jobs/src/pump.ts | 122 ------ packages/jobs/jobs/src/types.ts | 430 +++++++++++---------- packages/jobs/jobs/src/view.ts | 81 ++++ packages/jobs/jobs/tests/invariant.spec.ts | 91 +++-- packages/jobs/jobs/tests/service.spec.ts | 286 ++++---------- tsconfig.base.json | 1 + 9 files changed, 513 insertions(+), 762 deletions(-) delete mode 100644 packages/jobs/jobs/src/pump.ts create mode 100644 packages/jobs/jobs/src/view.ts diff --git a/packages/jobs/jobs/package.json b/packages/jobs/jobs/package.json index 34b32d40e7..dfaba10771 100644 --- a/packages/jobs/jobs/package.json +++ b/packages/jobs/jobs/package.json @@ -26,6 +26,10 @@ "types": "./lib/types/brand.d.ts", "default": "./lib/types/brand.js" }, + "./view": { + "types": "./lib/types/view.d.ts", + "default": "./lib/types/view.js" + }, "./src/*": "./src/*", "./package.json": "./package.json" }, diff --git a/packages/jobs/jobs/src/index.ts b/packages/jobs/jobs/src/index.ts index 4b6d6d9d43..a1c60cbeef 100644 --- a/packages/jobs/jobs/src/index.ts +++ b/packages/jobs/jobs/src/index.ts @@ -1,45 +1,43 @@ /** * The background-job Service Definition (`ctx.jobs`). It owns the contract for - * job ids, session-scoped access, lifecycle state, completion listeners, - * owner cleanup, and the optional per-job observation record — an append-only - * bounded output stream any number of independent observers read at absolute - * byte offsets, invisible to the model-facing consuming cursor — while - * producers retain their execution resources. The process-local registry - * lives in `@deepseek-ai/dsh-jobs-local`. + * job ids, session-scoped access, lifecycle state, the per-job output ring — + * one bounded stream that the model consumes through a registry-kept cursor + * and that any number of observers read at absolute byte offsets — and the + * event stream announcing every commit, while producers retain their + * execution resources. The process-local registry lives in + * `@deepseek-ai/dsh-jobs-local`. * @module @deepseek-ai/dsh-jobs */ import { Context, Service } from '@deepseek-ai/cordis' -import type { Agent } from '@deepseek-ai/dsh-agent' -import type { - JobDoneListener, JobId, JobOutputListener, JobRead, JobRecordRead, JobSnapshot, JobStart, - JobsChangedListener, -} from './types.ts' +import type { SessionId } from '@deepseek-ai/dsh-session' +import type { JobEvents, JobId, JobSpec, VisibleJobs } from './types.ts' export { JobId } from './types.ts' export type { JobAppendOptions, JobChannel, - JobDoneListener, + JobChunk, + JobEvent, + JobEventFilter, + JobEventListener, + JobEvents, + JobHandle, JobHooks, + JobKillOptions, JobKind, JobKindMap, JobOutcome, - JobOutputListener, + JobOutputRead, + JobOutputSource, JobRead, - JobRecordChunk, - JobRecordRead, - JobSnapshot, - JobStart, + JobSettleCause, + JobSourceRead, + JobSpec, JobStatus, - JobsChangedListener, - PlainJobStart, - RecordingJob, - RecordingJobStart, - RunningJob, + JobView, + VisibleJobs, } from './types.ts' -export { pumpJobOutput } from './pump.ts' -export type { JobPumpOptions, JobPumpRead, JobPumpSource } from './pump.ts' declare module '@deepseek-ai/cordis' { interface Context { @@ -48,7 +46,7 @@ declare module '@deepseek-ai/cordis' { } /** - * Abstract background job registry. Subclass, implement the abstract methods, + * Abstract background job registry. Subclass, implement the abstract members, * and load the subclass as a plugin — it registers as `ctx.jobs` (one * implementation per context; loading a second throws, which is cordis' * standard duplicate-service behavior). @@ -56,32 +54,30 @@ declare module '@deepseek-ai/cordis' { * Implementations must honor these semantics: * - Registrations outlive producer and controller fibers. Owner and * service disposal cancel live work and await compliant producers; a - * throwing teardown cancel force-fails only the record. Teardown - * cancellation also marks the record reported, because a record its owner - * is being destroyed for has no reader left. + * throwing teardown cancel force-fails only the record. Such settlements + * announce `cause: 'teardown'`, because a job whose owner is being destroyed + * has no reader left. * - Owned-job access is fenced by the owner's session id. Ids are * predictable, so authorization — not secrecy — is the boundary. - * - Settlement is first-wins: one terminal record, released waiters, and one - * round of contained listener notification, even against a late producer - * outcome. Completion is announced last, after the record is committed and - * every other observer of the settlement has seen it, because a reporter - * may open a model turn synchronously. + * - Settlement is first-wins: one terminal record, released waiters, then one + * round of contained event delivery, even against a late producer outcome. + * The `settled` event follows every released waiter, so a consumer that + * claims a settlement while waiting always claims before the event. * - {@link start} refuses work while no attached job controller serves the * spec's owner, so a producer cannot start work that owner cannot collect * or stop. One registry serves every composition in the process, so this - * question — and completion-listener delivery — is owner-relative rather - * than process-wide: registrations made from an unscoped context serve - * every owner, and registrations made under an agent composition's scope - * serve exactly the agents composed under it. - * - Record observation never consumes. Any number of {@link readRecord} - * readers hold their own absolute byte offsets; a record read changes no - * cursor and no notice state, so the model-facing surfaces (the consuming - * {@link read}, completion notices) are unaffected. - * - Record retention is bounded. Appends past the live cap drop the oldest + * question — and event delivery under `{ owners: 'scope' }` — is + * owner-relative rather than process-wide: registrations made from an + * unscoped context serve every owner, and registrations made under an agent + * composition's scope serve exactly the agents composed under it. + * - Every job owns one output ring. Pull sources named by the spec are pumped + * by the registry and drained once more before settlement; pushed appends + * land whole. The model's consuming cursor and observers' absolute offsets + * read the same bytes and never disturb each other. + * - Ring retention is bounded. Appends past the live cap drop the oldest * retained bytes; a reader below the retained window gets a lossy read, - * never an error. Settlement — the producer outcome, a kill, or teardown — - * trims retention to the settled cap and ends the stream; the record has no - * separate lifecycle. + * never an error. Settlement trims retention to the settled cap and ends + * the stream; the ring has no separate lifecycle. */ export abstract class JobRegistry extends Service { constructor(ctx: Context) { @@ -94,125 +90,28 @@ export abstract class JobRegistry extends Service { super(ctx, 'jobs') } + /** Lifecycle and output events, filtered per subscription. */ + abstract readonly events: JobEvents + /** * Preflight access, validation, owner cleanup, and implementation-owned * admission before starting and atomically registering work. Any preflight * rejection leaves no job id or execution resource. A throwing starter * leaves nothing registered; after it returns, registration cannot fail. - * Settlement records the outcome, notifies listeners, and releases waiters. - * @param spec - job identity, owner, and synchronous starter. + * @param spec - job identity, owner, output sources, and synchronous starter. * @returns the registry-issued `-N` id. */ - abstract start(spec: JobStart): JobId + abstract start(spec: JobSpec): JobId /** - * List caller-owned and unowned jobs in registration order without exposing - * another session's labels. - * @param caller - reading agent; a non-agent caller sees only unowned jobs. - * @returns fresh snapshots. + * Bind the caller's identity once and return its operations. A caller sees + * its own jobs and every unowned job; a caller-less view sees unowned jobs + * only. The view resolves visibility on every call, so it stays valid as + * jobs come and go. + * @param caller - the reading session, or undefined for an anonymous caller. + * @returns the operations available to that caller. */ - abstract list(caller?: Agent): JobSnapshot[] - - /** - * Return a non-consuming snapshot without changing its read cursor or notice - * state. Throws for an unknown or foreign job. - * @param id - job to look up. - * @param caller - reading agent checked against the owner. - * @returns a fresh snapshot. - */ - abstract get(id: JobId, caller?: Agent): JobSnapshot - - /** - * Read the next stream delta, or the idempotent final output after settlement. - * A terminal read marks the job reported. Throws for an unknown or foreign - * job. - * @param id - job to read. - * @param caller - reading agent checked against the owner. - * @returns output text and the post-read snapshot. - */ - abstract read(id: JobId, caller?: Agent): JobRead - - /** - * Request cancellation, then mark the job stopping and reported. A producer - * throw propagates without changing job state. Throws for an unknown or - * foreign job. - * @param id - job to cancel. - * @param caller - killing agent checked against the owner. - * @param reason - logged reason forwarded to the producer. - * @returns `requested` for live work, otherwise `already-finished`. - */ - abstract kill(id: JobId, caller?: Agent, reason?: string): 'requested' | 'already-finished' - - /** - * Wait for settlement or timeout without cancelling the job. Caller abort - * rejects only while the job is live; after settlement the terminal - * snapshot wins so a notice suppressed for this waiter is still delivered. - * Throws for invalid, unknown, or foreign input. - * @param id - job to wait for. - * @param timeoutMs - positive finite wait bound in milliseconds. - * @param caller - waiting agent checked against the owner. - * @param signal - optional cancellation of the wait itself. - * @returns snapshot at settlement or timeout. - */ - abstract wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise - - /** - * Register an effect-scoped completion listener. It receives the settlements - * of the owners its registering context's scope covers; each listener is - * contained; returned promises are observed but not awaited. No listener runs - * after service disposal. - * @param listener - receives each terminal snapshot and its exact owner. - * @returns disposer that unregisters the listener. - */ - abstract onJobDone(listener: JobDoneListener): () => void - - /** - * Register an effect-scoped observer of visible-set changes. It fires after - * every commit that changes what {@link list} returns for that owner — - * registration, every stopping transition (including the one teardown - * performs before it awaits a slow producer), settlement, owner-disposal - * removal, and the emptying that service disposal commits — so an observer - * re-reads rather than accumulating deltas. - * - * Delivery is owner-relative on the same terms as {@link onJobDone}: an - * observer registered from an unscoped context — a host composition's own - * carrier — sees every owner, while one registered under an agent - * composition's scope sees exactly the agents composed under it. - * - * This is not a superset of {@link onJobDone}: that one delivers the terminal - * record under first-wins semantics a job controller couples to notice - * delivery, while this one carries no delivery meaning and marks nothing - * reported. Listeners are contained and never awaited. - * @param listener - receives the owner whose visible set changed, or - * `undefined` when an unowned job changed and every caller's set did. - * @returns disposer that unregisters the listener. - */ - abstract onJobsChanged(listener: JobsChangedListener): () => void - - /** - * Read retained record output from an absolute byte offset without consuming - * it. Resume by passing a previous read's `next`; a foreign offset inside a - * retained chunk returns that whole chunk (its `at` may precede `from`). - * Never marks the job reported. Throws for an unknown or foreign job, a job - * without a {@link JobStart.record} declaration, or a negative or - * non-integer offset. - * @param id - job to read. - * @param from - absolute byte offset to read from (0 for the retained head). - * @param caller - reading agent checked against the owner. - * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. - */ - abstract readRecord(id: JobId, from: number, caller?: Agent): JobRecordRead - - /** - * Register an effect-scoped observer of record advancement — one signal per - * committed append and one at settlement, carrying only the job id. A - * consumer schedules a {@link readRecord} from its own cursor; the registry - * never pushes payloads. Delivery is owner-relative on the same terms as - * {@link onJobsChanged}. Listeners are contained and never awaited. - * @param listener - receives the id whose record advanced. - * @returns disposer that unregisters the listener. - */ - abstract onOutput(listener: JobOutputListener): () => void + abstract visibleTo(caller?: SessionId): VisibleJobs /** * Attach an effect-scoped controller that can read and stop jobs. It serves the diff --git a/packages/jobs/jobs/src/invariant.ts b/packages/jobs/jobs/src/invariant.ts index 36aca11fd8..84e3a22fe2 100644 --- a/packages/jobs/jobs/src/invariant.ts +++ b/packages/jobs/jobs/src/invariant.ts @@ -1,9 +1,8 @@ -/** Package-owned background-job snapshot invariants. @module @deepseek-ai/dsh-jobs/invariant */ +/** Package-owned background-job projection invariants. @module @deepseek-ai/dsh-jobs/invariant */ import type { Context } from '@deepseek-ai/cordis' -import type { Agent } from '@deepseek-ai/dsh-agent' import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants' -import type { JobSnapshot } from './types.ts' +import type { JobView } from './types.ts' const PACKAGE_NAME = '@deepseek-ai/dsh-jobs' const TERMINAL_STATUSES = new Set(['completed', 'killed', 'failed']) @@ -13,48 +12,44 @@ export const name = 'jobs-invariant' /** Service required before the companion can reserve package ownership. */ export const inject = ['invariants'] -/** Validate the cross-field relationships in one registry snapshot. */ -function validateSnapshot(snapshot: JobSnapshot, owner: Agent | undefined, fail: InvariantFailure): void { - const id = String(snapshot.id) - const prefix = `${snapshot.kind}-` +/** Validate the cross-field relationships in one registry projection. */ +function validateView(job: JobView, fail: InvariantFailure): void { + const id = String(job.id) + const prefix = `${job.kind}-` const ordinal = Number(id.slice(prefix.length)) - if (snapshot.kind.length === 0 || !id.startsWith(prefix) + if (job.kind.length === 0 || !id.startsWith(prefix) || !Number.isSafeInteger(ordinal) || ordinal < 1) { - fail(`job snapshot id ${JSON.stringify(id)} must be ${JSON.stringify(prefix)} followed by a positive ordinal`) + fail(`job view id ${JSON.stringify(id)} must be ${JSON.stringify(prefix)} followed by a positive ordinal`) } - if (snapshot.label.length === 0) fail(`job ${JSON.stringify(id)} label must be non-empty`) - if (!Number.isSafeInteger(snapshot.startedAt) || snapshot.startedAt < 0) { + if (job.label.length === 0) fail(`job ${JSON.stringify(id)} label must be non-empty`) + if (!Number.isSafeInteger(job.startedAt) || job.startedAt < 0) { fail(`job ${JSON.stringify(id)} startedAt must be a non-negative epoch integer`) } - const terminal = TERMINAL_STATUSES.has(snapshot.status) - if (terminal !== (snapshot.finishedAt !== undefined)) { + const terminal = TERMINAL_STATUSES.has(job.status) + if (terminal !== (job.finishedAt !== undefined)) { fail(`job ${JSON.stringify(id)} finishedAt must be present exactly for a terminal status`) } - if (snapshot.finishedAt !== undefined - && (!Number.isSafeInteger(snapshot.finishedAt) || snapshot.finishedAt < snapshot.startedAt)) { + if (job.finishedAt !== undefined + && (!Number.isSafeInteger(job.finishedAt) || job.finishedAt < job.startedAt)) { fail(`job ${JSON.stringify(id)} finishedAt must be an epoch integer no earlier than startedAt`) } - - const expectedOwner = owner?.id - if (snapshot.ownerSession !== expectedOwner) { - fail(`job ${JSON.stringify(id)} ownerSession does not match its completion owner`) + if (terminal && job.progress !== undefined) { + fail(`job ${JSON.stringify(id)} progress must be cleared once settled`) } - const { outputTotal, outputEarliest } = snapshot - if ((outputTotal !== undefined) !== (outputEarliest !== undefined)) { - fail(`job ${JSON.stringify(id)} record offsets must be present together`) - } else if (outputTotal !== undefined && outputEarliest !== undefined - && (!Number.isSafeInteger(outputTotal) || !Number.isSafeInteger(outputEarliest) - || outputEarliest < 0 || outputEarliest > outputTotal)) { - fail(`job ${JSON.stringify(id)} record offsets must satisfy 0 <= outputEarliest <= outputTotal`) + const { total, earliest } = job.output + if (!Number.isSafeInteger(total) || !Number.isSafeInteger(earliest) || earliest < 0 || earliest > total) { + fail(`job ${JSON.stringify(id)} output offsets must satisfy 0 <= earliest <= total`) } } -/** Install checks over current unowned records and every terminal snapshot. */ +/** Install checks over the current unowned projections and every settlement. */ const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => { - for (const snapshot of ctx.jobs.list()) validateSnapshot(snapshot, undefined, fail) - ctx.jobs.onJobDone((snapshot, owner) => { validateSnapshot(snapshot, owner, fail) }) + for (const job of ctx.jobs.visibleTo().list()) validateView(job, fail) + ctx.jobs.events.subscribe({ owners: 'all' }, (event) => { + if (event.type === 'settled') validateView(event.job, fail) + }) }, { inject: ['jobs'] }) /** diff --git a/packages/jobs/jobs/src/pump.ts b/packages/jobs/jobs/src/pump.ts deleted file mode 100644 index a3c1956019..0000000000 --- a/packages/jobs/jobs/src/pump.ts +++ /dev/null @@ -1,122 +0,0 @@ -/** - * Shared poll pump for producers whose output substrate is a non-consuming - * offset reader (the subprocess `readFrom(fromByte)` family). Pure utility — - * no cordis, no timers retained past settlement. - * @module - */ - -import type { JobChannel, RecordingJob } from './types.ts' - -/** One non-consuming offset read from a producer-owned stream. */ -export interface JobPumpRead { - /** Text captured since the requested offset (the whole retained tail when lossy). */ - text: string - /** Whole-stream offset to resume from on the next read. */ - nextOffset: number - /** True when the requested offset slid out of the source's retained window. */ - lossy: boolean -} - -/** - * One producer-owned stream the pump copies into a job record. - * - * The source is a pull-by-offset snapshot reader, not a Node.js `Readable`, - * because the substrate it reads (the subprocess `readFrom` family) is a - * retained ring that several readers share: the model-facing consuming - * cursor, the foreground result collector, and this record pump each hold - * their own absolute offset and read without disturbing the others. A - * `Readable` is single-consumer and consuming, so wrapping the ring in one - * would need a tee per reader and could not express `lossy` — the reader's - * offset having slid out of the retained window — which the record turns - * into a visible `gapBefore` instead of a silent splice. - */ -export interface JobPumpSource { - /** Stream label attached to every chunk this source yields. */ - channel?: JobChannel - /** - * Read everything captured since `fromByte` without consuming it. - * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 first). - * @returns the delta text, the next offset, and the lossy flag. - */ - read(fromByte: number): JobPumpRead -} - -/** Cadence and settlement for one {@link pumpJobOutput} run. */ -export interface JobPumpOptions { - /** Poll interval in milliseconds; a positive finite number. */ - pollMs: number - /** - * Settles when the producer's work finished and its sources hold their - * final bytes. The pump drains once more after settlement and returns; - * a rejection is treated as settlement. - */ - done: Promise -} - -/** - * Copy producer streams into a job record at a bounded cadence: drain every - * source, sleep `pollMs` or until `done` settles, repeat, then drain one - * final time. A lossy source read appends its surviving tail with - * `gapBefore`, so the discontinuity stays visible to observers. Fold the - * returned promise into the producer's `JobHooks.done` chain so the final - * drain lands before settlement trims and closes the record. - * - * Each round drains the sources in array order, so bytes two sources - * produced inside one poll window land in that order, not in the order they - * were written; the record is a best-effort live view whose cross-source - * reordering is bounded by `pollMs`, not a terminal transcript. - * - * The wait holds constant resources however long the job runs: one - * subscription on `done` for the whole run and one pending timer at a time. - * @param job - the running job's producer face receiving the copied chunks. - * @param sources - producer streams, each pumped at its own offset. - * @param options - poll cadence and the producer's settlement promise. - * @returns resolves after the final post-settlement drain. - */ -export async function pumpJobOutput( - job: RecordingJob, - sources: readonly JobPumpSource[], - options: JobPumpOptions, -): Promise { - if (!Number.isFinite(options.pollMs) || options.pollMs <= 0) { - throw new Error(`invalid pump pollMs: expected a positive finite number of milliseconds, got ${JSON.stringify(options.pollMs)}`) - } - const states = sources.map(source => ({ source, cursor: 0 })) - const drain = (): void => { - for (const state of states) { - const { source } = state - const read = source.read(state.cursor) - state.cursor = read.nextOffset - if (read.text.length === 0) continue - if (source.channel === undefined && !read.lossy) { - job.append(read.text) - } else { - job.append(read.text, { - ...source.channel !== undefined ? { channel: source.channel } : {}, - ...read.lossy ? { gapBefore: true as const } : {}, - }) - } - } - } - let settled = false - let timer: ReturnType | undefined - let wake: (() => void) | undefined - const finish = (): void => { - settled = true - // Clear the pending poll so a finished pump holds no timer for up to one - // interval, and release the current wait so the final drain runs at once. - if (timer !== undefined) clearTimeout(timer) - wake?.() - } - void options.done.then(finish, finish) - while (!settled) { - drain() - await new Promise((resolve) => { - wake = resolve - timer = setTimeout(resolve, options.pollMs) - }) - wake = undefined - timer = undefined - } - drain() -} diff --git a/packages/jobs/jobs/src/types.ts b/packages/jobs/jobs/src/types.ts index 3ec3f87357..0f46ff1715 100644 --- a/packages/jobs/jobs/src/types.ts +++ b/packages/jobs/jobs/src/types.ts @@ -1,154 +1,98 @@ /** - * Types shared by job producers, the registry, and controllers. The - * service implementation lives in `./index.ts`. + * Types shared by job producers, the registry, and its consumers. The + * client-safe projection vocabulary lives in `./view.ts`; the service + * implementation lives in `./index.ts`. * @module @deepseek-ai/dsh-jobs/types */ -import type { Agent } from '@deepseek-ai/dsh-agent' import type { SessionId } from '@deepseek-ai/dsh-session' import type { JobId } from './brand.ts' +import type { JobChannel, JobChunk, JobKind, JobView } from './view.ts' export { JobId } from './brand.ts' - -/** - * Task lifecycle: `running`, optionally `stopping`, then exactly one terminal - * status. Producer-specific facts belong in {@link JobSnapshot.detail}. - */ -export type JobStatus = 'running' | 'stopping' | 'completed' | 'killed' | 'failed' - -/** - * Producer-defined job kinds. Plugins extend this map by declaration merging; - * the registry treats every value as an opaque id namespace. - */ -export interface JobKindMap { - bash: 'bash' - subagent: 'subagent' -} - -/** The merge-extensible union of registered producer kind names. */ -export type JobKind = JobKindMap[keyof JobKindMap] +export type { JobChannel, JobChunk, JobKind, JobKindMap, JobStatus, JobView } from './view.ts' /** Terminal result supplied by a producer through {@link JobHooks.done}. */ export interface JobOutcome { /** How the job ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */ status: 'completed' | 'killed' | 'failed' - /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */ + /** + * Terminal reason rendered into status lines (`exit code: 3`, `max-tokens`). + * When the job settles `killed` after a {@link VisibleJobs.kill} with a + * reason, the registry appends that reason. + */ detail?: string - /** Final output for jobs without `readOutput`; stream jobs leave it unset. */ - output?: string + /** + * Return value for jobs whose result is a value rather than a stream (a + * workflow's rendered result, a subagent's report). The output ring carries + * the stream; this is handed out once by the model's next {@link VisibleJobs.read}. + */ + result?: string +} + +/** One incremental read from a {@link JobOutputSource}. */ +export interface JobSourceRead { + /** Text captured since the requested offset (the whole retained tail when lossy). */ + text: string + /** Whole-stream offset to resume from on the next read. */ + nextOffset: number + /** True when the requested offset slid out of the source's retained window. */ + lossy: boolean } /** - * Record-stream label. Producers without distinct streams omit it; consumers - * treat an unrecognized label like an absent one. + * A pull source the registry pumps into the job's output ring — the subprocess + * `readFrom` family. The registry owns the cadence and drains every source one + * last time before settlement closes the ring, so a producer folds nothing + * into its `done`. */ -export type JobChannel = 'stdout' | 'stderr' +export interface JobOutputSource { + /** Stream label attached to every chunk this source yields. */ + channel?: JobChannel + /** + * Read everything captured since `fromByte` without consuming it. + * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 first). + * @returns the delta text, the next offset, and the lossy flag. + */ + read(fromByte: number): JobSourceRead +} -/** Options for one {@link RunningJob.append}. */ +/** Options for one {@link JobHandle.append}. */ export interface JobAppendOptions { /** Stream label for the chunk; omitted for producers without distinct streams. */ channel?: JobChannel /** * Marks that producer-side bytes between the previous chunk and this one - * were lost (a source window slid before the producer could copy it), so an - * observer can render the discontinuity instead of a silent splice. + * were lost, so an observer can render the discontinuity instead of a + * silent splice. */ gapBefore?: true } -/** Fields shared by every producer declaration passed to {@link JobRegistry.start}. */ -interface JobStartBase { - /** Producer kind — also the id prefix (`bash`, `subagent`, …). */ - kind: JobKind - /** One-line model-facing label (the command; the delegation description). */ - label: string - /** - * Optional UTF-8 byte cap for each complete model-facing completion notice or - * output read, including controller status metadata. Independent of record - * retention: it bounds the consuming model surface, never - * {@link JobRegistry.readRecord}. - */ - outputLimitBytes?: number - /** - * Owning live agent. Access is fenced by its session id, and agent disposal - * cancels and awaits the job. The instance must be the one currently - * registered under its agent id. Omitting the owner creates an unowned job, - * open to any caller until service disposal. - */ - owner?: Agent -} - /** - * A start with the model-facing surfaces only. Its producer face carries no - * `append`, so output the registry would have nowhere to keep is - * unrepresentable rather than dropped. + * Producer face of one registered job, handed to {@link JobSpec.run} and + * valid for the job's whole life. All methods are synchronous. Writes staged + * inside the starter call are retained and become visible with the + * registration commit; after settlement — the producer's own outcome, a kill, + * or a registry-forced teardown end — writes log and drop instead of + * throwing, so a producer's trailing flush cannot break its own teardown path. */ -export interface PlainJobStart extends JobStartBase { - record?: undefined - /** - * Start the work after preflight and synchronously return its hooks. Called - * once with the job's producer face; a throw leaves nothing registered (the - * spent ordinal is skipped), and the producer must clean up any partially - * started resources. - * @param job - the issued id plus the live-detail writer. - */ - run(job: RunningJob): JobHooks -} - -/** - * A start that declares an observable output record beside the model-facing - * surfaces: {@link RecordingJob.append} retains chunks in a bounded ring that - * any number of observers read at absolute byte offsets through - * {@link JobRegistry.readRecord}, and snapshots carry - * {@link JobSnapshot.outputTotal} and {@link JobSnapshot.outputEarliest}. - */ -export interface RecordingJobStart extends JobStartBase { - record: true - /** - * Start the work after preflight and synchronously return its hooks. Called - * once with the job's producer face; a throw leaves nothing registered (the - * spent ordinal is skipped), and the producer must clean up any partially - * started resources. - * @param job - the issued id plus the record append and live-detail writers. - */ - run(job: RecordingJob): JobHooks -} - -/** - * Producer declaration passed to {@link JobRegistry.start}, discriminated by - * `record`. The runtime preflights access and cleanup before invoking `run`; - * the producer owns execution resources while the runtime owns identity and - * lifecycle state. - */ -export type JobStart = PlainJobStart | RecordingJobStart - -/** - * Producer face of one registered job, handed to `run` and valid for the - * job's whole life. All methods are synchronous. Writes staged inside the - * starter call are retained and become visible with the registration commit; - * after settlement — the producer's own outcome, a kill, or a registry-forced - * teardown end — writes log and drop instead of throwing, so a producer's - * trailing flush cannot break its own teardown path. - */ -export interface RunningJob { +export interface JobHandle { /** The registry-issued id (`-N`). */ readonly id: JobId /** - * Replace the snapshot's status detail with a live progress line (`3/10`). - * @param detail - the new detail line. - */ - updateDetail(detail: string): void -} - -/** Producer face of a {@link RecordingJobStart}: {@link RunningJob} plus the record append. */ -export interface RecordingJob extends RunningJob { - /** - * Append one record chunk. Offsets advance by the chunk's UTF-8 byte - * length; an empty chunk is dropped without waking observers. + * Append one chunk to the output ring. Offsets advance by the chunk's UTF-8 + * byte length; an empty chunk is dropped without waking observers. * @param text - the chunk text, exactly as produced. * @param options - stream label and gap marker. */ append(text: string, options?: JobAppendOptions): void + /** + * Replace the live progress line (`3/10`, the current phase). Settlement + * clears it; the terminal reason travels in {@link JobOutcome.detail}. + * @param line - the new progress line. + */ + updateProgress(line: string): void } /** Hooks through which the runtime controls and observes producer work. */ @@ -162,104 +106,82 @@ export interface JobHooks { * Resolves after the producer releases its resources, not merely when work * finishes. Must not reject; the runtime converts a rejection to `failed`. * If teardown cancellation throws, the runtime may force-fail only the - * registry record without claiming that the work stopped. Settlement also - * ends the record: fold any record-filling pump into this promise so the - * final drain lands before the registry trims and closes the stream. + * registry record without claiming that the work stopped. */ done: Promise - /** - * Consume output produced since the previous call. The producer formats - * truncation and spill notices. Absence marks a final-output-only job; each - * job has one consuming cursor. Independent of the record: this is the - * model-facing projection, {@link JobRegistry.readRecord} the observer one. - */ - readOutput?(): string } /** - * A read-only projection of one job, safe to hand to listeners and tools — - * a fresh object per call, never live registry state. + * Producer declaration passed to {@link JobRegistry.start}. The runtime + * preflights access and cleanup before invoking {@link run}; the producer owns + * execution resources while the runtime owns identity, lifecycle state, and + * the output ring. */ -export interface JobSnapshot { - /** The registry-issued id (`-N`). */ - id: JobId - /** The producer kind the job was registered with. */ +export interface JobSpec { + /** Producer kind — also the id prefix (`bash`, `subagent`, …). */ kind: JobKind - /** The producer-supplied one-line label. */ + /** One-line model-facing label (the command; the delegation description). */ label: string - /** Producer-owned cap for complete model-facing notices and output reads. */ + /** + * Owning session. Access is fenced by it, and the owner's live Agent must be + * the one currently registered under that id: its disposal cancels and + * awaits the job. Omitting the owner creates an unowned job, open to any + * caller until service disposal. + */ + owner?: SessionId + /** + * Optional UTF-8 byte cap for each complete model-facing completion notice or + * output read, including controller status metadata. Independent of ring + * retention: it bounds the consuming model surface, never observers. + */ outputLimitBytes?: number /** - * Owner session id used for authorization and correlation; absent for - * unowned jobs. Completion listeners receive the exact {@link Agent} - * separately through {@link JobDoneListener}. + * Pull sources the registry pumps into the ring at its own cadence. + * Producers that narrate their own progress use {@link JobHandle.append} + * instead; a job may use both. */ - ownerSession?: SessionId - /** Current lifecycle state. */ - status: JobStatus + output?: readonly JobOutputSource[] /** - * Kind-specific status detail: live progress while the producer updates it - * through {@link RunningJob.updateDetail}, the terminal detail once settled. + * Start the work after preflight and synchronously return its hooks. Called + * once with the job's producer face; a throw leaves nothing registered (the + * spent ordinal is skipped), and the producer must clean up any partially + * started resources. + * @param job - the issued id plus the ring append and progress writers. */ - detail?: string - /** Epoch ms when the job was registered. */ - startedAt: number - /** Epoch ms when the job settled; absent while `running`/`stopping`. */ - finishedAt?: number - /** - * True when a kill, read, wait, or teardown cancel has reported or committed - * to report the terminal state. Completion reporters suppress redundant - * notices when set. Teardown claims it because the owner or service being - * destroyed leaves no reader: a reporter that opens a turn on notice would - * otherwise spend a model request per teardown layer. - */ - reported: boolean - /** - * Total UTF-8 bytes ever appended to the record — the offset the next chunk - * starts at. Present exactly when the job declared {@link JobStart.record}. - */ - outputTotal?: number - /** - * Offset of the oldest retained record byte. Greater than zero exactly when - * retention dropped the head; a reader starting below it gets a lossy read. - * Present exactly when the job declared {@link JobStart.record}. - */ - outputEarliest?: number + run(job: JobHandle): JobHooks } -/** Output and post-read state returned by {@link JobRegistry.read}. */ +/** Options for {@link VisibleJobs.kill}. */ +export interface JobKillOptions { + /** + * Cancellation reason: forwarded verbatim to the producer's cancel hook, and + * merged into the terminal `detail` when the job settles `killed`, so both + * the model and observers can see why the work stopped. + */ + reason?: string +} + +/** Output and post-read state returned by the consuming {@link VisibleJobs.read}. */ export interface JobRead { - /** - * Stream kinds: the consuming delta since the previous read. Final-output - * kinds: empty while live, the terminal {@link JobOutcome.output} (or - * empty) once settled — idempotent, never consumed. - */ - text: string + /** Ring chunks appended since the model cursor, in offset order; every channel included. */ + chunks: readonly JobChunk[] + /** True when the cursor fell below the oldest retained byte, so bytes are missing before `chunks`. */ + lossy: boolean + /** The producer's {@link JobOutcome.result}, handed out by the first read after settlement only. */ + result?: string /** The job's state at read time. */ - snapshot: JobSnapshot + job: JobView } -/** One retained record chunk returned by {@link JobRegistry.readRecord}. */ -export interface JobRecordChunk { - /** Absolute offset of the chunk's first byte. */ - at: number - /** Chunk text exactly as appended (possibly tail-trimmed by retention). */ - text: string - /** Stream label, when the producer supplied one. */ - channel?: JobChannel - /** Producer-reported loss immediately before this chunk. */ - gapBefore?: true -} - -/** Result of one non-consuming {@link JobRegistry.readRecord}. */ -export interface JobRecordRead { +/** Result of one non-consuming {@link VisibleJobs.readAt}. */ +export interface JobOutputRead { /** Retained chunks overlapping `[from, total)`, in offset order. */ - chunks: readonly JobRecordChunk[] + chunks: readonly JobChunk[] /** - * Offset to resume from — the record's current `outputTotal`. Always a - * chunk boundary: appends land whole and trimming only advances chunk - * starts, and consumers concatenate `chunks` under that assumption, so a - * provider serving partial chunks would silently duplicate text. + * Offset to resume from — the ring's current `total`. Always a chunk + * boundary: appends land whole and trimming only advances chunk starts, and + * consumers concatenate `chunks` under that assumption, so a provider + * serving partial chunks would silently duplicate text. */ next: number /** True when `from` fell below the oldest retained byte, so bytes are missing before `chunks`. */ @@ -267,28 +189,118 @@ export interface JobRecordRead { } /** - * Completion callback with the exact owner supplied at start, or `undefined` - * for an unowned job. Returned promises are observed but not awaited. + * The operations one caller may perform, bound by {@link JobRegistry.visibleTo}. + * A caller sees its own jobs and every unowned job; every method throws for + * an id outside that set, without distinguishing unknown from foreign. */ -export type JobDoneListener = ( - snapshot: JobSnapshot, - owner: Agent | undefined, -) => void | PromiseLike +export interface VisibleJobs { + /** + * List the visible jobs in registration order. + * @returns fresh projections. + */ + list(): JobView[] + /** + * Project one job without touching its cursor. + * @param id - job to look up. + * @returns a fresh projection. + */ + get(id: JobId): JobView + /** + * Consume the ring from the model cursor and advance it to the current + * total. After settlement the first read also carries the producer's + * result; later reads return only what was appended since. + * @param id - job to read. + * @returns the chunks since the cursor, the lossy flag, the result once, and the post-read projection. + */ + read(id: JobId): JobRead + /** + * Read retained ring output from an absolute byte offset without consuming + * it. Resume by passing a previous read's `next`; an offset inside a + * retained chunk returns that whole chunk (its `at` may precede `from`). + * Never moves the model cursor. Throws for a negative or non-integer offset. + * @param id - job to read. + * @param from - absolute byte offset to read from (0 for the retained head). + * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. + */ + readAt(id: JobId, from: number): JobOutputRead + /** + * Request cancellation, then mark the job stopping. A recorded + * {@link JobKillOptions.reason} merges into the terminal `detail` when the + * job settles `killed`. A producer throw propagates without changing job + * state. + * @param id - job to cancel. + * @param options - cancellation reason. + * @returns `requested` for live work, otherwise `already-finished`. + */ + kill(id: JobId, options?: JobKillOptions): 'requested' | 'already-finished' + /** + * Wait for settlement or timeout without cancelling the job. Caller abort + * rejects only while the job is live; after settlement the terminal + * projection wins. Throws for an invalid timeout. + * @param id - job to wait for. + * @param timeoutMs - positive finite wait bound in milliseconds. + * @param signal - optional cancellation of the wait itself. + * @returns projection at settlement or timeout. + */ + wait(id: JobId, timeoutMs: number, signal?: AbortSignal): Promise +} /** - * Observation callback for a change to what one owner's {@link JobRegistry.list} - * would return. It is owner-granular rather than job-granular because the - * change may be a removal, which no per-job record can express, and because - * its consumers re-read the whole visible set anyway. - * - * An `undefined` owner means an unowned job changed, so every caller's visible - * set changed with it. + * Why a job settled: its producer finished (`producer`), a + * {@link VisibleJobs.kill} ran first (`kill`), or owner or service teardown + * cancelled it (`teardown`) — a settlement whose owner has no reader left. */ -export type JobsChangedListener = (owner: Agent | undefined) => void +export type JobSettleCause = 'producer' | 'kill' | 'teardown' /** - * Observer of record advancement for one job: new appended output, or the - * settlement that ends the stream. Carries no payload — a consumer schedules a - * {@link JobRegistry.readRecord} from its own cursor. + * One lifecycle or output event. Lifecycle events carry the job's projection + * after the commit they announce; `output` carries only the id and the new + * total, so an observer schedules a {@link VisibleJobs.readAt} from its own + * cursor and the registry never pushes payloads. */ -export type JobOutputListener = (id: JobId) => void +export type JobEvent = + | { + /** Registration commit, progress line change, stopping transition, or removal from the visible set. */ + readonly type: 'registered' | 'progress' | 'stopping' | 'removed' + readonly job: JobView + } + | { + readonly type: 'settled' + readonly job: JobView + readonly cause: JobSettleCause + } + | { + readonly type: 'output' + readonly id: JobId + /** Owning session, absent for an unowned job. */ + readonly owner?: SessionId + /** The ring's total after the append (or at settlement, which ends the stream). */ + readonly total: number + } + +/** + * Who a subscription hears about. `{ owner }` delivers that session's jobs + * plus every unowned job (the set that session can see). `{ owners: 'scope' }` + * delivers the owners composed under the subscribing context — one registry + * serves every composition in the process, and a mount under one preset must + * not hear another preset's agents. `{ owners: 'all' }` delivers everything. + */ +export type JobEventFilter = + | { readonly owner: SessionId } + | { readonly owners: 'all' | 'scope' } + +/** Event callback; contained by the registry, never awaited. */ +export type JobEventListener = (event: JobEvent) => void + +/** The registry's event stream. */ +export interface JobEvents { + /** + * Register an effect-scoped listener. Events are dispatched synchronously + * after the commit they announce; a `settled` event follows the release of + * every waiter. No listener runs after service disposal. + * @param filter - which owners' events to deliver. + * @param listener - receives each matching event. + * @returns disposer that unregisters the listener. + */ + subscribe(filter: JobEventFilter, listener: JobEventListener): () => void +} diff --git a/packages/jobs/jobs/src/view.ts b/packages/jobs/jobs/src/view.ts new file mode 100644 index 0000000000..033fcfbe76 --- /dev/null +++ b/packages/jobs/jobs/src/view.ts @@ -0,0 +1,81 @@ +/** + * Client-safe job vocabulary: the read-only projection of one job and the + * chunks its output ring hands out. This leaf reaches no Host package, so + * browser programs and Remote wire types import it without pulling the + * registry's Host declaration merges. + * @module @deepseek-ai/dsh-jobs/view + */ + +import type { SessionId } from '@deepseek-ai/dsh-session/types' +import type { JobId } from './brand.ts' + +/** + * Job lifecycle: `running`, optionally `stopping`, then exactly one terminal + * status. Producer-specific facts belong in {@link JobView.progress} and + * {@link JobView.detail}. + */ +export type JobStatus = 'running' | 'stopping' | 'completed' | 'killed' | 'failed' + +/** + * Producer-defined job kinds. Plugins extend this map by declaration merging; + * the registry treats every value as an opaque id namespace. + */ +export interface JobKindMap { + bash: 'bash' + subagent: 'subagent' +} + +/** The merge-extensible union of registered producer kind names. */ +export type JobKind = JobKindMap[keyof JobKindMap] + +/** + * Stream label of one output chunk. `stdout` and `stderr` reach the model's + * consuming read; `log` marks producer narration (a workflow's phase lines) + * that only observers see. Consumers treat an unrecognized label like an + * absent one. + */ +export type JobChannel = 'stdout' | 'stderr' | 'log' + +/** One chunk of a job's output ring: absolute offset, text, and its provenance. */ +export interface JobChunk { + /** Absolute offset of the chunk's first byte; offsets never move once assigned. */ + readonly at: number + /** Chunk text exactly as appended (possibly tail-trimmed by retention). */ + readonly text: string + /** Stream label, when the producer supplied one. */ + readonly channel?: JobChannel + /** Bytes immediately before this chunk were lost, at the producer or to retention. */ + readonly gapBefore?: true +} + +/** + * Read-only projection of one job — a fresh object per call, never live + * registry state. The model tools, the browser roster, and the observation + * stream all consume this one shape. + */ +export interface JobView { + /** The registry-issued id (`-N`). */ + readonly id: JobId + /** The producer kind the job was registered with. */ + readonly kind: JobKind + /** The producer-supplied one-line label. */ + readonly label: string + /** Owning session; absent for an unowned job, which every caller can see. */ + readonly owner?: SessionId + /** Current lifecycle state. */ + readonly status: JobStatus + /** The producer's live progress line (`3/10`, the current phase); cleared at settlement. */ + readonly progress?: string + /** Terminal reason (`exit code: 3`); a recorded kill reason is merged in. */ + readonly detail?: string + /** Epoch ms when the job was registered. */ + readonly startedAt: number + /** Epoch ms when the job settled; absent while live. */ + readonly finishedAt?: number + /** + * The output ring's absolute coordinates. `total` is the offset the next + * chunk starts at (0 while nothing was written); `earliest` is the oldest + * retained byte, greater than zero exactly when retention dropped the head. + */ + readonly output: { readonly total: number; readonly earliest: number } +} diff --git a/packages/jobs/jobs/tests/invariant.spec.ts b/packages/jobs/jobs/tests/invariant.spec.ts index fa42eb6c74..12a6d48bee 100644 --- a/packages/jobs/jobs/tests/invariant.spec.ts +++ b/packages/jobs/jobs/tests/invariant.spec.ts @@ -1,48 +1,49 @@ import { describe, expect, it } from 'vitest' import { Context } from '@deepseek-ai/cordis' -import type { Agent } from '@deepseek-ai/dsh-agent' import { SessionId } from '@deepseek-ai/dsh-session' import JobRegistry, { JobId } from '@deepseek-ai/dsh-jobs' -import type { JobDoneListener, JobSnapshot } from '@deepseek-ai/dsh-jobs' +import type { JobEventListener, JobView } from '@deepseek-ai/dsh-jobs' import * as JobsInvariant from '@deepseek-ai/dsh-jobs/invariant' import InvariantRegistry from '@deepseek-ai/dsh-invariants' -const BASE: JobSnapshot = { +const BASE: JobView = { id: JobId('bash-1'), kind: 'bash', label: 'compile', status: 'completed', startedAt: 10, finishedAt: 20, - reported: false, + output: { total: 0, earliest: 0 }, } -const RUNNING: JobSnapshot = { +const RUNNING: JobView = { id: JobId('bash-1'), kind: 'bash', label: 'compile', status: 'running', startedAt: 10, - reported: false, + output: { total: 0, earliest: 0 }, } -const TERMINAL_WITHOUT_FINISH: JobSnapshot = { +const TERMINAL_WITHOUT_FINISH: JobView = { id: JobId('bash-1'), kind: 'bash', label: 'compile', status: 'completed', startedAt: 10, - reported: false, + output: { total: 0, earliest: 0 }, } -async function setup(seed: JobSnapshot[] = []): Promise<(snapshot: unknown, owner?: Agent) => void> { +async function setup(seed: JobView[] = []): Promise<(job: unknown) => void> { const ctx = new Context() - let listener: JobDoneListener | undefined + let listener: JobEventListener | undefined const probe = { - list: () => seed, - onJobDone(value: JobDoneListener) { - listener = value - return () => { listener = undefined } + visibleTo: () => ({ list: () => seed }), + events: { + subscribe(_filter: unknown, value: JobEventListener) { + listener = value + return () => { listener = undefined } + }, }, } as unknown as JobRegistry await ctx.plugin(InvariantRegistry) @@ -51,44 +52,54 @@ async function setup(seed: JobSnapshot[] = []): Promise<(snapshot: unknown, owne apply(child: Context) { child.provide('jobs', probe) }, }) await ctx.plugin(JobsInvariant) - if (listener === undefined) throw new Error('job invariant did not subscribe to terminal snapshots') - return (snapshot, owner) => { listener!(snapshot as JobSnapshot, owner) } + if (listener === undefined) throw new Error('job invariant did not subscribe to settlements') + return (job) => { listener!({ type: 'settled', job: job as JobView, cause: 'producer' }) } } describe('job-registry invariants', () => { - it('accepts coherent current and terminal snapshots', async () => { + it('accepts coherent current and terminal projections', async () => { const notify = await setup([RUNNING]) expect(() => { notify(BASE) }).not.toThrow() - const owner = { id: SessionId('owner') } as Agent - expect(() => { notify({ ...BASE, id: JobId('subagent-2'), kind: 'subagent', ownerSession: owner.id }, owner) }) + expect(() => { notify({ ...BASE, id: JobId('subagent-2'), kind: 'subagent', owner: SessionId('owner') }) }) .not.toThrow() - expect(() => { notify({ ...BASE, outputTotal: 8, outputEarliest: 4 }) }).not.toThrow() + expect(() => { notify({ ...BASE, output: { total: 8, earliest: 4 } }) }).not.toThrow() + }) + + it('ignores non-settlement events', async () => { + const ctx = new Context() + let listener: JobEventListener | undefined + const probe = { + visibleTo: () => ({ list: () => [] }), + events: { subscribe(_filter: unknown, value: JobEventListener) { listener = value; return () => {} } }, + } as unknown as JobRegistry + await ctx.plugin(InvariantRegistry) + await ctx.plugin({ name: 'job-invariant-probe', apply(child: Context) { child.provide('jobs', probe) } }) + await ctx.plugin(JobsInvariant) + expect(() => { listener!({ type: 'registered', job: { ...BASE, label: '' } }) }).not.toThrow() }) it.each([ - [{ ...BASE, id: JobId('-1'), kind: '' }, undefined, /positive ordinal/], - [{ ...BASE, id: JobId('other-1') }, undefined, /must be "bash-" followed by a positive ordinal/], - [{ ...BASE, id: JobId('bash-x') }, undefined, /positive ordinal/], - [{ ...BASE, id: JobId('bash-0') }, undefined, /positive ordinal/], - [{ ...BASE, startedAt: -1 }, undefined, /startedAt must be a non-negative epoch integer/], - [{ ...BASE, startedAt: 0.5 }, undefined, /startedAt must be a non-negative epoch integer/], - [{ ...BASE, status: 'running' }, undefined, /finishedAt must be present exactly for a terminal status/], - [TERMINAL_WITHOUT_FINISH, undefined, /finishedAt must be present exactly for a terminal status/], - [{ ...BASE, finishedAt: 9 }, undefined, /no earlier than startedAt/], - [{ ...BASE, finishedAt: 20.5 }, undefined, /no earlier than startedAt/], - [{ ...BASE, ownerSession: SessionId('recorded') }, { id: SessionId('actual') } as Agent, /does not match its completion owner/], - [{ ...BASE, outputTotal: 8 }, undefined, /record offsets must be present together/], - [{ ...BASE, outputEarliest: 0 }, undefined, /record offsets must be present together/], - [{ ...BASE, outputTotal: 8, outputEarliest: 9 }, undefined, /0 <= outputEarliest <= outputTotal/], - [{ ...BASE, outputTotal: 8.5, outputEarliest: 0 }, undefined, /0 <= outputEarliest <= outputTotal/], - [{ ...BASE, outputTotal: 8, outputEarliest: 0.5 }, undefined, /0 <= outputEarliest <= outputTotal/], - [{ ...BASE, outputTotal: 8, outputEarliest: -1 }, undefined, /0 <= outputEarliest <= outputTotal/], - ] as const)('rejects an incoherent registry snapshot', async (snapshot, owner, message) => { + [{ ...BASE, id: JobId('-1'), kind: '' }, /positive ordinal/], + [{ ...BASE, id: JobId('other-1') }, /must be "bash-" followed by a positive ordinal/], + [{ ...BASE, id: JobId('bash-x') }, /positive ordinal/], + [{ ...BASE, id: JobId('bash-0') }, /positive ordinal/], + [{ ...BASE, startedAt: -1 }, /startedAt must be a non-negative epoch integer/], + [{ ...BASE, startedAt: 0.5 }, /startedAt must be a non-negative epoch integer/], + [{ ...BASE, status: 'running' }, /finishedAt must be present exactly for a terminal status/], + [TERMINAL_WITHOUT_FINISH, /finishedAt must be present exactly for a terminal status/], + [{ ...BASE, finishedAt: 9 }, /no earlier than startedAt/], + [{ ...BASE, finishedAt: 20.5 }, /no earlier than startedAt/], + [{ ...BASE, progress: '3/10' }, /progress must be cleared once settled/], + [{ ...BASE, output: { total: 8, earliest: 9 } }, /0 <= earliest <= total/], + [{ ...BASE, output: { total: 8.5, earliest: 0 } }, /0 <= earliest <= total/], + [{ ...BASE, output: { total: 8, earliest: 0.5 } }, /0 <= earliest <= total/], + [{ ...BASE, output: { total: 8, earliest: -1 } }, /0 <= earliest <= total/], + ] as const)('rejects an incoherent registry projection', async (job, message) => { const notify = await setup() - expect(() => { notify(snapshot, owner) }).toThrow(message) + expect(() => { notify(job) }).toThrow(message) }) - it('rejects an incoherent record already present at installation', async () => { + it('rejects an incoherent projection already present at installation', async () => { await expect(setup([{ ...BASE, label: '' }])).rejects.toThrow(/label must be non-empty/) }) }) diff --git a/packages/jobs/jobs/tests/service.spec.ts b/packages/jobs/jobs/tests/service.spec.ts index 331bf6596b..f3b456acbc 100644 --- a/packages/jobs/jobs/tests/service.spec.ts +++ b/packages/jobs/jobs/tests/service.spec.ts @@ -1,69 +1,60 @@ -import { describe, expect, it, vi } from 'vitest' +import { describe, expect, it } from 'vitest' import { Context } from '@deepseek-ai/cordis' -import type { Agent } from '@deepseek-ai/dsh-agent' -import { JobId, JobRegistry, pumpJobOutput } from '@deepseek-ai/dsh-jobs' +import { SessionId } from '@deepseek-ai/dsh-session' +import { JobId, JobRegistry } from '@deepseek-ai/dsh-jobs' import type { - JobAppendOptions, JobDoneListener, JobHooks, JobOutputListener, JobPumpSource, JobRead, JobRecordRead, - JobSnapshot, JobStart, JobsChangedListener, PlainJobStart, RecordingJob, RecordingJobStart, + JobEvent, JobEventFilter, JobEventListener, JobHooks, JobOutputSource, JobRead, JobSpec, JobView, VisibleJobs, } from '@deepseek-ai/dsh-jobs' +/** Compile-time probe: does `Shape` carry a `Key` member? */ +type HasKey = Key extends keyof Shape ? true : false + /** - * Minimal concrete registry: one canned record. The Service Definition owns the contract - * only (ids, snapshots, authorization-shaped signatures); the registry + * Minimal concrete registry: one canned row. The Service Definition owns the + * contract only (ids, the caller-bound view, the event stream); the registry * behavior suite lives with `@deepseek-ai/dsh-jobs-local`. */ class StubJobRegistry extends JobRegistry { - snapshotOf(id: JobId): JobSnapshot { + readonly subscriptions: { filter: JobEventFilter; listener: JobEventListener }[] = [] + readonly started: JobSpec[] = [] + + readonly events = { + subscribe: (filter: JobEventFilter, listener: JobEventListener): (() => void) => { + const entry = { filter, listener } + this.subscriptions.push(entry) + return () => { this.subscriptions.splice(this.subscriptions.indexOf(entry), 1) } + }, + } + + private view(id: JobId, owner: SessionId | undefined): JobView { return { id, kind: 'bash', label: 'sleep 60', + ...owner !== undefined ? { owner } : {}, status: 'running', startedAt: 0, - reported: false, + output: { total: 0, earliest: 0 }, } } - start(spec: JobStart): JobId { + start(spec: JobSpec): JobId { + this.started.push(spec) const id = JobId(`${spec.kind}-1`) - spec.run({ id, append() {}, updateDetail() {} }) + spec.run({ id, append() {}, updateProgress() {} }) return id } - list(): JobSnapshot[] { - return [this.snapshotOf(JobId('bash-1'))] - } - - get(id: JobId): JobSnapshot { - return this.snapshotOf(id) - } - - read(id: JobId): JobRead { - return { text: '', snapshot: this.snapshotOf(id) } - } - - kill(): 'requested' | 'already-finished' { - return 'requested' - } - - wait(id: JobId, _timeoutMs: number, _caller?: Agent, _signal?: AbortSignal): Promise { - return Promise.resolve(this.snapshotOf(id)) - } - - onJobDone(_listener: JobDoneListener): () => void { - return () => {} - } - - onJobsChanged(_listener: JobsChangedListener): () => void { - return () => {} - } - - readRecord(_id: JobId, from: number): JobRecordRead { - return { chunks: [], next: from, lossy: false } - } - - onOutput(_listener: JobOutputListener): () => void { - return () => {} + visibleTo(caller?: SessionId): VisibleJobs { + const view = (id: JobId): JobView => this.view(id, caller) + return { + list: () => [view(JobId('bash-1'))], + get: id => view(id), + read: (id): JobRead => ({ chunks: [], lossy: false, job: view(id) }), + readAt: (_id, from) => ({ chunks: [], next: from, lossy: false }), + kill: () => 'requested', + wait: id => Promise.resolve(view(id)), + } } attachController(_name: string): () => void { @@ -71,63 +62,58 @@ class StubJobRegistry extends JobRegistry { } } -/** Compile-time probe: does the producer face `Face` carry `append`? */ -type HasAppend = 'append' extends keyof Face ? true : false - -describe('JobStart producer faces', () => { - it('hands append only to a start that declares a record', () => { - const hooks: JobHooks = { cancel() {}, done: new Promise(() => {}) } - // The literal's `record` discriminant selects the face `run` receives. - const plain: JobStart = { - kind: 'bash', - label: 'no record', - run: (job) => { - job.updateDetail('works for every job') - return hooks - }, - } - const recording: JobStart = { - kind: 'bash', - label: 'record', - record: true, - run: (job) => { - job.append('lands in the record') - return hooks - }, - } - // Negative proof: a plain start's face has no `append` at the type level. - const plainFace: HasAppend[0]> = false - const recordingFace: HasAppend[0]> = true - expect(plainFace).toBe(false) - expect(recordingFace).toBe(true) - expect(plain.record).toBeUndefined() - expect(recording.record).toBe(true) - }) -}) - describe('JobRegistry seam', () => { it('a concrete subclass registers as ctx.jobs and serves the abstract API', async () => { const ctx = new Context() await ctx.plugin(StubJobRegistry) + const caller = SessionId('session-1') + const hooks: JobHooks = { cancel() {}, done: new Promise(() => {}) } const detachController = ctx.jobs.attachController('seam-test') - const id = ctx.jobs.start({ kind: 'bash', label: 'sleep 60', run: () => ({ cancel() {}, done: new Promise(() => {}) }) }) + const id = ctx.jobs.start({ kind: 'bash', label: 'sleep 60', owner: caller, run: () => hooks }) expect(id).toBe('bash-1') - expect(ctx.jobs.list()).toHaveLength(1) - expect(ctx.jobs.get(id).status).toBe('running') - expect(ctx.jobs.read(id).text).toBe('') - expect(ctx.jobs.kill(id)).toBe('requested') - await expect(ctx.jobs.wait(id, 5)).resolves.toMatchObject({ id }) - expect(ctx.jobs.readRecord(id, 0)).toEqual({ chunks: [], next: 0, lossy: false }) - const detachListener = ctx.jobs.onJobDone(() => {}) - detachListener() - const detachChanges = ctx.jobs.onJobsChanged(() => {}) - detachChanges() - const detachOutput = ctx.jobs.onOutput(() => {}) - detachOutput() + + const jobs = ctx.jobs.visibleTo(caller) + expect(jobs.list()).toHaveLength(1) + expect(jobs.get(id).status).toBe('running') + expect(jobs.get(id).owner).toBe(caller) + expect(jobs.read(id)).toEqual({ chunks: [], lossy: false, job: expect.objectContaining({ id }) }) + expect(jobs.readAt(id, 7)).toEqual({ chunks: [], next: 7, lossy: false }) + expect(jobs.kill(id, { reason: 'seam test' })).toBe('requested') + await expect(jobs.wait(id, 5)).resolves.toMatchObject({ id }) + // A caller-less view is the unowned-only view. + expect(ctx.jobs.visibleTo().get(id).owner).toBeUndefined() + + const events: JobEvent[] = [] + const unsubscribe = ctx.jobs.events.subscribe({ owners: 'all' }, (event) => { events.push(event) }) + unsubscribe() detachController() }) + it('types every start the same way: one handle, pull sources optional', () => { + const hooks: JobHooks = { cancel() {}, done: new Promise(() => {}) } + const source: JobOutputSource = { + channel: 'stdout', + read: fromByte => ({ text: '', nextOffset: fromByte, lossy: false }), + } + const spec: JobSpec = { + kind: 'bash', + label: 'x', + output: [source], + run: (job) => { + job.append('lands in the ring', { channel: 'log' }) + job.updateProgress('1/2') + return hooks + }, + } + expect(spec.output).toHaveLength(1) + // Bookkeeping never reaches the public view, and the record declaration is gone. + const viewHasReported: HasKey = false + const specHasRecord: HasKey = false + const hooksHaveReadOutput: HasKey = false + expect([viewHasReported, specHasRecord, hooksHaveReadOutput]).toEqual([false, false, false]) + }) + it('loading a second implementation throws (one jobs service per context — cordis standard)', async () => { const ctx = new Context() await ctx.plugin(StubJobRegistry) @@ -141,119 +127,3 @@ describe('JobRegistry seam', () => { .rejects.toThrow(/abstract job registry seam; load an implementation such as @deepseek-ai\/dsh-jobs-local/) }) }) - -/** Record every append so pump behavior is observable without a registry. */ -function recordingJob(): { job: RecordingJob; appends: { text: string; options?: JobAppendOptions }[] } { - const appends: { text: string; options?: JobAppendOptions }[] = [] - const job: RecordingJob = { - id: JobId('bash-1'), - append(text, options) { appends.push({ text, ...options !== undefined ? { options } : {} }) }, - updateDetail() {}, - } - return { job, appends } -} - -/** A scripted source: each read() shifts the next scripted result. */ -function scriptedSource( - reads: { text: string; lossy?: boolean }[], - channel?: 'stdout' | 'stderr', -): { source: JobPumpSource; offsets: number[] } { - const offsets: number[] = [] - let offset = 0 - const source: JobPumpSource = { - ...channel !== undefined ? { channel } : {}, - read(fromByte) { - offsets.push(fromByte) - const next = reads.shift() ?? { text: '' } - offset += Buffer.byteLength(next.text, 'utf8') - return { text: next.text, nextOffset: offset, lossy: next.lossy ?? false } - }, - } - return { source, offsets } -} - -describe('pumpJobOutput', () => { - it('rejects a non-positive poll interval before touching any source', async () => { - const { job } = recordingJob() - await expect(pumpJobOutput(job, [], { pollMs: 0, done: Promise.resolve() })) - .rejects.toThrow(/invalid pump pollMs/) - }) - - it('copies labeled deltas at the poll cadence and resumes each source at its own offset', async () => { - vi.useFakeTimers() - try { - const { job, appends } = recordingJob() - let settle!: () => void - const done = new Promise((resolve) => { settle = resolve }) - const out = scriptedSource([{ text: 'a' }, { text: 'bc' }], 'stdout') - const err = scriptedSource([{ text: '' }, { text: 'E' }], 'stderr') - const pump = pumpJobOutput(job, [out.source, err.source], { pollMs: 50, done }) - - await vi.advanceTimersByTimeAsync(50) - settle() - await pump - expect(appends).toEqual([ - { text: 'a', options: { channel: 'stdout' } }, - { text: 'bc', options: { channel: 'stdout' } }, - { text: 'E', options: { channel: 'stderr' } }, - ]) - // Every read resumed from the previous nextOffset, never from a shared cursor. - expect(out.offsets).toEqual([0, 1, 3]) - expect(err.offsets).toEqual([0, 0, 1]) - // Settlement cleared the raced poll timer instead of leaving it pending. - expect(vi.getTimerCount()).toBe(0) - } finally { - vi.useRealTimers() - } - }) - - it('subscribes to done once and holds one poll timer however long the job runs', async () => { - vi.useFakeTimers() - try { - const { job } = recordingJob() - // A thenable stands in for the producer's done promise, and whatever the - // pump derives from it counts its own reactions too: a pending promise - // retains every reaction until it settles, so a day-long job must not - // gain one per poll round. - let subscriptions = 0 - let settle!: () => void - const settled = new Promise((resolve) => { settle = resolve }) - const counting = (promise: Promise): Promise => ({ - then(onFulfilled?: (value: unknown) => unknown, onRejected?: (reason: unknown) => unknown) { - subscriptions += 1 - return counting(promise.then(onFulfilled, onRejected)) - }, - }) as unknown as Promise - const done = counting(settled) - const { source, offsets } = scriptedSource([]) - const pump = pumpJobOutput(job, [source], { pollMs: 50, done }) - - const rounds = 10_000 - await vi.advanceTimersByTimeAsync(50 * rounds) - expect(offsets).toHaveLength(rounds + 1) - expect(subscriptions).toBeLessThanOrEqual(2) - expect(vi.getTimerCount()).toBe(1) - - settle() - await pump - expect(offsets).toHaveLength(rounds + 2) - expect(vi.getTimerCount()).toBe(0) - } finally { - vi.useRealTimers() - } - }) - - it('marks a lossy source read as a gap so observers see the discontinuity', async () => { - const { job, appends } = recordingJob() - const { source } = scriptedSource([{ text: 'tail', lossy: true }]) - await pumpJobOutput(job, [source], { pollMs: 1, done: Promise.resolve() }) - expect(appends).toEqual([{ text: 'tail', options: { gapBefore: true } }]) - }) - - it('treats a rejected done as settlement and still drains the final bytes', async () => { - const { job, appends } = recordingJob() - const { source } = scriptedSource([{ text: 'last' }]) - await pumpJobOutput(job, [source], { pollMs: 1, done: Promise.reject(new Error('producer broke')) }) - expect(appends).toEqual([{ text: 'last' }]) - }) -}) diff --git a/tsconfig.base.json b/tsconfig.base.json index bfdee3acfb..97ea6bcf0c 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -102,6 +102,7 @@ "@deepseek-ai/dsh-commands/brand": ["./packages/interaction/commands/src/brand.ts"], "@deepseek-ai/dsh-commands/types": ["./packages/interaction/commands/src/types.ts"], "@deepseek-ai/dsh-jobs/brand": ["./packages/jobs/jobs/src/brand.ts"], + "@deepseek-ai/dsh-jobs/view": ["./packages/jobs/jobs/src/view.ts"], "@deepseek-ai/dsh-credentials/types": ["./packages/credentials/credentials/src/types.ts"], "@deepseek-ai/dsh-authorization/types": ["./packages/credentials/authorization/src/types.ts"], "@deepseek-ai/dsh-settings/types": ["./packages/settings/settings/src/types.ts"], From 1b97207150ca8dc36cf6814aba8edeaec4f9f7ca Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 15:53:59 +0800 Subject: [PATCH 028/100] refactor(jobs-local): extract the output ring and the registry-owned pump --- packages/jobs/jobs-local/src/pump.ts | 85 +++++++++++++++ packages/jobs/jobs-local/src/ring.ts | 113 ++++++++++++++++++++ packages/jobs/jobs-local/tests/pump.spec.ts | 111 +++++++++++++++++++ packages/jobs/jobs-local/tests/ring.spec.ts | 65 +++++++++++ 4 files changed, 374 insertions(+) create mode 100644 packages/jobs/jobs-local/src/pump.ts create mode 100644 packages/jobs/jobs-local/src/ring.ts create mode 100644 packages/jobs/jobs-local/tests/pump.spec.ts create mode 100644 packages/jobs/jobs-local/tests/ring.spec.ts diff --git a/packages/jobs/jobs-local/src/pump.ts b/packages/jobs/jobs-local/src/pump.ts new file mode 100644 index 0000000000..e57cb02a09 --- /dev/null +++ b/packages/jobs/jobs-local/src/pump.ts @@ -0,0 +1,85 @@ +/** + * The registry-owned pull pump: copies a job's {@link JobOutputSource}s into + * its ring at a bounded cadence and drains them once more after the + * producer settles, so the ring holds every byte before settlement trims and + * closes it. Pure utility — no cordis, no timers retained past settlement. + * @module @deepseek-ai/dsh-jobs-local/pump + */ + +import type { JobAppendOptions, JobOutputSource } from '@deepseek-ai/dsh-jobs' + +/** One pump run; `done` resolves after the final post-settlement drain. */ +export interface PumpHandle { + done: Promise +} + +/** + * Drain every source in array order, sleep `pollMs` or until `until` + * settles, repeat, then drain one final time. A lossy source read appends + * its surviving tail with `gapBefore`, so the discontinuity stays visible to + * observers. Sources drain in array order each round, so bytes two sources + * produced inside one poll window land in that order, not in the order they + * were written: the ring is a best-effort live view whose cross-source + * reordering is bounded by `pollMs`. + * + * The wait holds constant resources however long the job runs: one + * subscription on `until` for the whole run and one pending timer at a time. + * @param sources - producer streams, each pumped at its own offset. + * @param append - the ring append; receives each copied chunk. + * @param pollMs - poll interval in milliseconds; a positive finite number. + * @param until - settles (or rejects, which counts as settlement) when the producer finished. + * @returns the handle whose `done` resolves after the final drain. + */ +export function startPump( + sources: readonly JobOutputSource[], + append: (text: string, options?: JobAppendOptions) => void, + pollMs: number, + until: Promise, +): PumpHandle { + if (!Number.isFinite(pollMs) || pollMs <= 0) { + throw new Error(`invalid pump pollMs: expected a positive finite number of milliseconds, got ${JSON.stringify(pollMs)}`) + } + const states = sources.map(source => ({ source, cursor: 0 })) + const drain = (): void => { + for (const state of states) { + const { source } = state + const read = source.read(state.cursor) + state.cursor = read.nextOffset + if (read.text.length === 0) continue + if (source.channel === undefined && !read.lossy) { + append(read.text) + } else { + append(read.text, { + ...source.channel !== undefined ? { channel: source.channel } : {}, + ...read.lossy ? { gapBefore: true as const } : {}, + }) + } + } + } + const done = (async (): Promise => { + let settled = false + let timer: ReturnType | undefined + let wake: (() => void) | undefined + const finish = (): void => { + settled = true + // Clear the pending poll so a finished pump holds no timer for up to one + // interval, and release the current wait so the final drain runs at once. + // `finish` always runs from a microtask, after the loop parked on its + // first timer, so the timer is never absent here. + clearTimeout(timer) + wake?.() + } + void until.then(finish, finish) + while (!settled) { + drain() + await new Promise((resolve) => { + wake = resolve + timer = setTimeout(resolve, pollMs) + }) + wake = undefined + timer = undefined + } + drain() + })() + return { done } +} diff --git a/packages/jobs/jobs-local/src/ring.ts b/packages/jobs/jobs-local/src/ring.ts new file mode 100644 index 0000000000..fb4bcb3c5b --- /dev/null +++ b/packages/jobs/jobs-local/src/ring.ts @@ -0,0 +1,113 @@ +/** + * The bounded output ring behind one job: chunks at absolute byte offsets, + * head eviction that never moves an assigned offset, and non-consuming reads + * from any offset. + * @module @deepseek-ai/dsh-jobs-local/ring + */ + +import type { JobAppendOptions, JobChannel, JobOutputRead } from '@deepseek-ai/dsh-jobs' + +/** One retained ring entry; `bytes` caches the chunk's UTF-8 length. */ +interface RingChunk { + at: number + text: string + bytes: number + channel?: JobChannel + gapBefore?: true +} + +/** + * The UTF-8-safe tail of `text` no longer than `maxBytes`: the byte cut + * advances past continuation bytes so the surviving text never starts inside + * a code point. + * @param text - the oversized chunk text. + * @param maxBytes - positive byte budget for the surviving tail. + * @returns the surviving tail and its exact byte length. + */ +function utf8Tail(text: string, maxBytes: number): { text: string; bytes: number } { + const raw = Buffer.from(text, 'utf8') + let start = raw.length - maxBytes + // The loop bound proves the index is in range; the assertion only + // discharges noUncheckedIndexedAccess. + while (start < raw.length && ((raw[start] as number) & 0xC0) === 0x80) start += 1 + const tail = raw.subarray(start) + return { text: tail.toString('utf8'), bytes: tail.length } +} + +/** Offsets stay absolute across eviction: `earliest` only ever advances. */ +export class OutputRing { + /** Retained chunks in offset order. */ + private readonly chunks: RingChunk[] = [] + /** Sum of the retained chunks' byte lengths. */ + retainedBytes = 0 + /** Total UTF-8 bytes ever appended — the offset the next chunk starts at. */ + total = 0 + /** Offset of the oldest retained byte (equals {@link total} when nothing is retained). */ + earliest = 0 + + /** + * Append one chunk and trim the head to `cap`. + * @param text - the chunk text, exactly as produced. + * @param options - stream label and gap marker. + * @param cap - retention cap in UTF-8 bytes after this append. + * @returns false when the chunk was empty and nothing changed. + */ + append(text: string, options: JobAppendOptions | undefined, cap: number): boolean { + if (text.length === 0) return false + const bytes = Buffer.byteLength(text, 'utf8') + this.chunks.push({ + at: this.total, + text, + bytes, + ...options?.channel !== undefined ? { channel: options.channel } : {}, + ...options?.gapBefore !== undefined ? { gapBefore: options.gapBefore } : {}, + }) + this.total += bytes + this.retainedBytes += bytes + this.trim(cap) + return true + } + + /** + * Drop retained head chunks until the ring fits `cap`; a single oversized + * chunk keeps only its UTF-8-safe tail with a `gapBefore` marker. + * @param cap - retention cap in UTF-8 bytes. + */ + trim(cap: number): void { + while (this.retainedBytes > cap && this.chunks.length > 1) { + const dropped = this.chunks.shift() + /* v8 ignore next -- the length guard proves shift() returns a chunk; the check only satisfies noUncheckedIndexedAccess. */ + if (dropped === undefined) break + this.retainedBytes -= dropped.bytes + } + const single = this.chunks.length === 1 ? this.chunks[0] : undefined + if (single !== undefined && single.bytes > cap) { + const tail = utf8Tail(single.text, cap) + single.at += single.bytes - tail.bytes + single.text = tail.text + single.bytes = tail.bytes + single.gapBefore = true + this.retainedBytes = tail.bytes + } + this.earliest = this.chunks[0]?.at ?? this.total + } + + /** + * Retained chunks overlapping `[from, total)` as fresh wire chunks. + * @param from - absolute byte offset to read from. + * @returns the chunks, the resume offset, and whether bytes before them were evicted. + */ + readFrom(from: number): JobOutputRead { + const chunks = [] + for (const chunk of this.chunks) { + if (chunk.at + chunk.bytes <= from) continue + chunks.push({ + at: chunk.at, + text: chunk.text, + ...chunk.channel !== undefined ? { channel: chunk.channel } : {}, + ...chunk.gapBefore !== undefined ? { gapBefore: chunk.gapBefore } : {}, + }) + } + return { chunks, next: this.total, lossy: from < this.earliest } + } +} diff --git a/packages/jobs/jobs-local/tests/pump.spec.ts b/packages/jobs/jobs-local/tests/pump.spec.ts new file mode 100644 index 0000000000..31ee5d4d3f --- /dev/null +++ b/packages/jobs/jobs-local/tests/pump.spec.ts @@ -0,0 +1,111 @@ +import { describe, expect, it, vi } from 'vitest' +import type { JobAppendOptions, JobOutputSource } from '@deepseek-ai/dsh-jobs' +import { startPump } from '../src/pump.ts' + +/** Record every append so pump behavior is observable without a registry. */ +function sink() { + const appends: { text: string; options?: JobAppendOptions }[] = [] + return { + appends, + append: (text: string, options?: JobAppendOptions) => { appends.push({ text, ...options !== undefined ? { options } : {} }) }, + } +} + +/** A scripted source: each read() shifts the next scripted result. */ +function scriptedSource( + reads: { text: string; lossy?: boolean }[], + channel?: 'stdout' | 'stderr', +): { source: JobOutputSource; offsets: number[] } { + const offsets: number[] = [] + let offset = 0 + const source: JobOutputSource = { + ...channel !== undefined ? { channel } : {}, + read(fromByte) { + offsets.push(fromByte) + const next = reads.shift() ?? { text: '' } + offset += Buffer.byteLength(next.text, 'utf8') + return { text: next.text, nextOffset: offset, lossy: next.lossy ?? false } + }, + } + return { source, offsets } +} + +describe('startPump', () => { + it('copies labeled deltas at the poll cadence and resumes each source at its own offset', async () => { + vi.useFakeTimers() + try { + const { appends, append } = sink() + let settle!: () => void + const until = new Promise((resolve) => { settle = resolve }) + const out = scriptedSource([{ text: 'a' }, { text: 'bc' }], 'stdout') + const err = scriptedSource([{ text: '' }, { text: 'E' }], 'stderr') + const pump = startPump([out.source, err.source], append, 50, until) + + await vi.advanceTimersByTimeAsync(50) + settle() + await pump.done + expect(appends).toEqual([ + { text: 'a', options: { channel: 'stdout' } }, + { text: 'bc', options: { channel: 'stdout' } }, + { text: 'E', options: { channel: 'stderr' } }, + ]) + // Every read resumed from the previous nextOffset, never from a shared cursor. + expect(out.offsets).toEqual([0, 1, 3]) + expect(err.offsets).toEqual([0, 0, 1]) + // Settlement cleared the pending poll timer instead of leaving it pending. + expect(vi.getTimerCount()).toBe(0) + } finally { + vi.useRealTimers() + } + }) + + it('marks a lossy source read as a gap so observers see the discontinuity', async () => { + const { appends, append } = sink() + const { source } = scriptedSource([{ text: 'tail', lossy: true }]) + await startPump([source], append, 1, Promise.resolve()).done + expect(appends).toEqual([{ text: 'tail', options: { gapBefore: true } }]) + }) + + it('treats a rejected settlement as settlement and still drains the final bytes', async () => { + const { appends, append } = sink() + const { source } = scriptedSource([{ text: 'last' }]) + await startPump([source], append, 1, Promise.reject(new Error('producer broke'))).done + expect(appends).toEqual([{ text: 'last' }]) + }) + + it('subscribes to the settlement once and holds one poll timer however long the job runs', async () => { + vi.useFakeTimers() + try { + const { append } = sink() + let subscriptions = 0 + let settle!: () => void + const settled = new Promise((resolve) => { settle = resolve }) + const counting = (promise: Promise): Promise => ({ + then(onFulfilled?: (value: unknown) => unknown, onRejected?: (reason: unknown) => unknown) { + subscriptions += 1 + return counting(promise.then(onFulfilled, onRejected)) + }, + }) as unknown as Promise + const { source, offsets } = scriptedSource([]) + const pump = startPump([source], append, 50, counting(settled)) + + const rounds = 10_000 + await vi.advanceTimersByTimeAsync(50 * rounds) + expect(offsets).toHaveLength(rounds + 1) + expect(subscriptions).toBeLessThanOrEqual(2) + expect(vi.getTimerCount()).toBe(1) + + settle() + await pump.done + expect(offsets).toHaveLength(rounds + 2) + expect(vi.getTimerCount()).toBe(0) + } finally { + vi.useRealTimers() + } + }) + + it('rejects a non-positive poll interval before touching any source', () => { + const { append } = sink() + expect(() => startPump([], append, 0, Promise.resolve())).toThrow(/invalid pump pollMs/) + }) +}) diff --git a/packages/jobs/jobs-local/tests/ring.spec.ts b/packages/jobs/jobs-local/tests/ring.spec.ts new file mode 100644 index 0000000000..670e121d0b --- /dev/null +++ b/packages/jobs/jobs-local/tests/ring.spec.ts @@ -0,0 +1,65 @@ +import { describe, expect, it } from 'vitest' +import { OutputRing } from '../src/ring.ts' + +describe('OutputRing', () => { + it('assigns absolute offsets by UTF-8 byte length and drops empty chunks silently', () => { + const ring = new OutputRing() + expect(ring.append('', undefined, 1024)).toBe(false) + expect(ring.append('héllo', { channel: 'stdout' }, 1024)).toBe(true) + expect(ring.append('wörld', { channel: 'stderr', gapBefore: true }, 1024)).toBe(true) + expect(ring.total).toBe(12) + expect(ring.earliest).toBe(0) + expect(ring.retainedBytes).toBe(12) + expect(ring.readFrom(0)).toEqual({ + chunks: [ + { at: 0, text: 'héllo', channel: 'stdout' }, + { at: 6, text: 'wörld', channel: 'stderr', gapBefore: true }, + ], + next: 12, + lossy: false, + }) + }) + + it('reads from a foreign offset by returning the whole overlapping chunk', () => { + const ring = new OutputRing() + ring.append('abc', undefined, 1024) + ring.append('def', undefined, 1024) + expect(ring.readFrom(4).chunks).toEqual([{ at: 3, text: 'def' }]) + expect(ring.readFrom(6)).toEqual({ chunks: [], next: 6, lossy: false }) + }) + + it('trims whole head chunks past the cap and reports the evicted span as lossy', () => { + const ring = new OutputRing() + ring.append('aaaa', undefined, 8) + ring.append('bbbb', undefined, 8) + ring.append('cc', undefined, 8) + // 10 bytes retained > cap 8: the oldest whole chunk goes. + expect(ring.earliest).toBe(4) + expect(ring.retainedBytes).toBe(6) + expect(ring.readFrom(0)).toEqual({ chunks: [{ at: 4, text: 'bbbb' }, { at: 8, text: 'cc' }], next: 10, lossy: true }) + expect(ring.readFrom(4).lossy).toBe(false) + }) + + it('keeps a lone oversized chunk as a UTF-8-safe tail marked gapBefore', () => { + const ring = new OutputRing() + // 3 two-byte code points = 6 bytes; a 3-byte cap must not start inside a code point. + ring.append('ééé', undefined, 3) + expect(ring.retainedBytes).toBe(2) + expect(ring.earliest).toBe(4) + expect(ring.readFrom(0)).toEqual({ chunks: [{ at: 4, text: 'é', gapBefore: true }], next: 6, lossy: true }) + }) + + it('re-trims to a smaller cap on demand and leaves total untouched', () => { + const ring = new OutputRing() + ring.append('12345678', undefined, 64) + ring.append('abcdefgh', undefined, 64) + ring.trim(8) + expect(ring.total).toBe(16) + expect(ring.earliest).toBe(8) + expect(ring.readFrom(8)).toEqual({ chunks: [{ at: 8, text: 'abcdefgh' }], next: 16, lossy: false }) + // Trimming an empty ring is a no-op that keeps earliest at total. + const empty = new OutputRing() + empty.trim(1) + expect(empty.earliest).toBe(0) + }) +}) From f55e9805c753af225dc80fcc9b0d4159dc860d36 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 16:03:16 +0800 Subject: [PATCH 029/100] refactor(jobs-local): one ring, two cursors, and event routing Every job owns an `OutputRing`; the model's `read` consumes from a registry-kept cursor while `readAt` reads at absolute offsets. Pull sources named by the spec are pumped by the registry and drained once more before settlement. `visibleTo(caller)` binds the session fence once; the three listener families become one event hub with explicit filters; `reported` is gone and settlements announce their cause. --- packages/jobs/jobs-local/src/events.ts | 98 ++ packages/jobs/jobs-local/src/index.ts | 741 ++++++------- packages/jobs/jobs-local/tests/events.spec.ts | 138 +++ packages/jobs/jobs-local/tests/jobs.spec.ts | 983 ++++++++---------- 4 files changed, 967 insertions(+), 993 deletions(-) create mode 100644 packages/jobs/jobs-local/src/events.ts create mode 100644 packages/jobs/jobs-local/tests/events.spec.ts diff --git a/packages/jobs/jobs-local/src/events.ts b/packages/jobs/jobs-local/src/events.ts new file mode 100644 index 0000000000..2e39f7089f --- /dev/null +++ b/packages/jobs/jobs-local/src/events.ts @@ -0,0 +1,98 @@ +/** + * Event routing for the local registry: subscriptions file by filter, and + * every commit dispatches once to each matching listener with containment. + * @module @deepseek-ai/dsh-jobs-local/events + */ + +import type { Context } from '@deepseek-ai/cordis' +import type { Agent } from '@deepseek-ai/dsh-agent' +import { AnonymousEntries, ScopedLayers, scopeOf } from '@deepseek-ai/dsh-scope' +import type { ScopeLayer } from '@deepseek-ai/dsh-scope' +import type { JobEvent, JobEventFilter, JobEventListener } from '@deepseek-ai/dsh-jobs' + +/** One registered listener and the filter it declared. */ +interface Subscription { + filter: JobEventFilter + listener: JobEventListener +} + +/** + * One scope's contributions: the job controllers attached from it and the + * `{ owners: 'scope' }` subscriptions registered there. Both tables are + * anonymous because a contribution is identified by its own disposer, never + * by a name a second registrant could shadow. + */ +export class JobLayer implements ScopeLayer { + readonly controllers = new AnonymousEntries() + readonly scoped = new AnonymousEntries() + + isEmpty(): boolean { + return this.controllers.isEmpty() && this.scoped.isEmpty() + } +} + +/** + * Routes events to subscriptions. `{ owner }` and `{ owners: 'all' }` + * subscriptions are evaluated against every event regardless of where they + * were registered; `{ owners: 'scope' }` subscriptions file into the + * registering context's scope layer and receive the owners composed under it + * — the global layer, reached from an unscoped context, receives every owner. + */ +export class JobEventHub { + private readonly unscoped = new Set() + + /** + * @param layers - the scope-layer table shared with the controller handshake. + * @param warn - sink for a listener's contained failure. + */ + constructor( + private readonly layers: ScopedLayers, + private readonly warn: (message: string) => void, + ) {} + + /** + * Register one listener as an effect of `ctx`. + * @param ctx - the subscribing context; owns the effect and, for `'scope'`, names the scope. + * @param filter - which owners' events to deliver. + * @param listener - receives each matching event. + * @returns disposer that unregisters the listener. + */ + subscribe(ctx: Context, filter: JobEventFilter, listener: JobEventListener): () => void { + const subscription: Subscription = { filter, listener } + if ('owners' in filter && filter.owners === 'scope') { + return this.layers.effect(ctx, layer => layer.scoped.append(subscription), { label: 'jobs.events.subscribe()' }) + } + return ctx.effect(() => { + this.unscoped.add(subscription) + return () => { this.unscoped.delete(subscription) } + }, 'jobs.events.subscribe()') + } + + /** + * Deliver one event to every matching subscription, containing each + * listener so an observer cannot break the commit already made. + * @param event - the event to deliver. + * @param owner - the job's exact owner, or undefined for unowned work. + */ + emit(event: JobEvent, owner: Agent | undefined): void { + const ownerId = owner?.id + for (const subscription of this.unscoped) { + const { filter } = subscription + if ('owner' in filter && ownerId !== undefined && ownerId !== filter.owner) continue + this.deliver(subscription, event) + } + for (const subscription of this.layers.global.scoped.values()) this.deliver(subscription, event) + const scope = owner === undefined ? undefined : scopeOf(owner.ctx) + for (const layer of this.layers.chainLayers(scope)) { + for (const subscription of layer.scoped.values()) this.deliver(subscription, event) + } + } + + private deliver(subscription: Subscription, event: JobEvent): void { + try { + subscription.listener(event) + } catch (error: unknown) { + this.warn(`jobs: event listener threw on ${event.type}: ${String(error)}`) + } + } +} diff --git a/packages/jobs/jobs-local/src/index.ts b/packages/jobs/jobs-local/src/index.ts index e5415aee15..965de7a124 100644 --- a/packages/jobs/jobs-local/src/index.ts +++ b/packages/jobs/jobs-local/src/index.ts @@ -1,8 +1,8 @@ /** * Process-local provider for the background-job capability seam - * (`ctx.jobs`). It keeps every record — lifecycle state plus the optional - * bounded output ring — in memory and hands out fresh snapshots and chunk - * copies, never live state. + * (`ctx.jobs`). It keeps every job — lifecycle state, the bounded output + * ring, and the model cursor — in memory and hands out fresh projections and + * chunk copies, never live state. * * Registrations outlive producer and controller fibers. Agent or service * disposal cancels live work and awaits compliant producers; a throwing @@ -13,14 +13,18 @@ import { Context } from '@deepseek-ai/cordis' import z from '@deepseek-ai/schemastery' import type { Agent } from '@deepseek-ai/dsh-agent' -import { AnonymousEntries, ScopedLayers, scopeOf } from '@deepseek-ai/dsh-scope' -import type { ScopeLayer } from '@deepseek-ai/dsh-scope' +import { ScopedLayers, scopeOf } from '@deepseek-ai/dsh-scope' +import type { SessionId } from '@deepseek-ai/dsh-session' import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout' import { JobRegistry, JobId } from '@deepseek-ai/dsh-jobs' import type { - JobAppendOptions, JobChannel, JobDoneListener, JobKind, JobOutcome, JobOutputListener, JobRead, - JobRecordChunk, JobRecordRead, JobSnapshot, JobStart, JobStatus, JobsChangedListener, RecordingJob, RunningJob, + JobAppendOptions, JobEvent, JobEvents, JobHandle, JobKillOptions, JobKind, JobOutcome, JobOutputRead, JobRead, + JobSettleCause, JobSpec, JobStatus, JobView, VisibleJobs, } from '@deepseek-ai/dsh-jobs' +import { JobEventHub, JobLayer } from './events.ts' +import { startPump } from './pump.ts' +import type { PumpHandle } from './pump.ts' +import { OutputRing } from './ring.ts' /** Timeout code that distinguishes a bounded wait from caller cancellation. */ export const TASK_WAIT_TIMEOUT = 'TASK_WAIT_TIMEOUT' @@ -28,12 +32,15 @@ export const TASK_WAIT_TIMEOUT = 'TASK_WAIT_TIMEOUT' /** Default maximum number of active jobs in one exact-owner bucket. */ const DEFAULT_MAX_CONCURRENT_TASKS_PER_OWNER = 10 -/** Default live record retention per job, in UTF-8 bytes. */ +/** Default live ring retention per job, in UTF-8 bytes. */ const DEFAULT_RETAIN_BYTES = 256 * 1024 -/** Default record retention kept after settlement, in UTF-8 bytes. */ +/** Default ring retention kept after settlement, in UTF-8 bytes. */ const DEFAULT_SETTLED_RETAIN_BYTES = 16 * 1024 +/** Default poll interval for pull sources, in milliseconds. */ +const DEFAULT_PUMP_POLL_MS = 150 + /** Configuration for the process-local job registry. */ export interface Config { /** @@ -41,49 +48,28 @@ export interface Config { * omission defaults to 10. */ maxConcurrentJobsPerOwner?: number - /** Live record retention per job in UTF-8 bytes; omission defaults to 262144. */ + /** Live ring retention per job in UTF-8 bytes; omission defaults to 262144. */ retainBytes?: number - /** Record retention kept after a job settles, in UTF-8 bytes; omission defaults to 16384. */ + /** Ring retention kept after a job settles, in UTF-8 bytes; omission defaults to 16384. */ settledRetainBytes?: number -} - -/** One retained record ring entry; `bytes` caches the chunk's UTF-8 length. */ -interface RingChunk { - at: number - text: string - bytes: number - channel?: JobChannel - gapBefore?: true -} - -/** The bounded output ring behind one job's declared record. */ -interface RecordState { - /** Retained chunks in offset order; offsets stay absolute across eviction. */ - chunks: RingChunk[] - /** Sum of the retained chunks' byte lengths. */ - retainedBytes: number - /** Total UTF-8 bytes ever appended. */ - total: number - /** Offset of the oldest retained byte (equals {@link total} when nothing is retained). */ - earliest: number + /** Poll interval for a job's pull sources, in milliseconds; omission defaults to 150. */ + pumpPollMs?: number } /** - * Producer-written state shared between the {@link RunningJob} face and the + * Producer-written state shared between the {@link JobHandle} and the * registered record: the starter call writes through it before the commit, * the same object serves the job for its whole life afterwards. */ interface ProducerState { - /** Bounded output ring; undefined when the spec declared no record. */ - record: RecordState | undefined - /** Live progress detail until settlement replaces it with the terminal one. */ - detail: string | undefined + /** Live progress line until settlement clears it. */ + progress: string | undefined /** The committed registry record; undefined exactly during the starter call. */ - job: TrackedTask | undefined + job: TrackedJob | undefined } -/** The registry's mutable per-job record (never handed out — see {@link LocalJobRegistry.snapshot}). */ -interface TrackedTask { +/** The registry's mutable per-job record (never handed out — see {@link LocalJobRegistry.view}). */ +interface TrackedJob { id: JobId kind: JobKind label: string @@ -91,22 +77,31 @@ interface TrackedTask { /** Exact lifecycle owner; session-id authorization is derived from it. */ owner: Agent | undefined cancel: (reason?: string) => void - readOutput: (() => string) | undefined status: JobStatus - /** Producer-shared record ring and detail line. */ + ring: OutputRing + /** The model's consuming cursor; {@link VisibleJobs.readAt} never moves it. */ + modelCursor: number + /** Whether the first post-settlement read already handed out `result`. */ + resultDelivered: boolean + /** Producer-shared progress line and commit binding. */ state: ProducerState - output: string | undefined + /** Terminal reason; a recorded kill reason is merged in at settlement. */ + detail: string | undefined + result: string | undefined startedAt: number finishedAt: number | undefined - reported: boolean - /** Resolves once the terminal snapshot is recorded and listeners notified. */ + /** Reason recorded by {@link VisibleJobs.kill}, merged into a `killed` settlement's detail. */ + killReason: string | undefined + /** Set once a kill or teardown cancel ran; settlement reports it as the cause. */ + settleCause: JobSettleCause | undefined + /** Resolves once the terminal record is committed and announced. */ settled: Promise /** Resolver for {@link settled}, called by the first effective settlement. */ markSettled: () => void - /** Live waits; settlement with a waiter marks the job reported. */ - waiters: number /** Removable resolvers for live waits; timeout/abort unregister before the job settles. */ waitResolvers: Set<() => void> + /** The registry-owned pump over the spec's pull sources, when it named any. */ + pump: PumpHandle | undefined } /** True for the three terminal {@link JobStatus} values. */ @@ -114,42 +109,6 @@ function isTerminal(status: JobStatus): boolean { return status === 'completed' || status === 'killed' || status === 'failed' } -/** - * The UTF-8-safe tail of `text` no longer than `maxBytes`: the byte cut - * advances past continuation bytes so the surviving text never starts inside - * a code point. - * @param text - the oversized chunk text. - * @param maxBytes - positive byte budget for the surviving tail. - * @returns the surviving tail and its exact byte length. - */ -function utf8Tail(text: string, maxBytes: number): { text: string; bytes: number } { - const raw = Buffer.from(text, 'utf8') - let start = raw.length - maxBytes - // The loop bound proves the index is in range; the assertion only - // discharges noUncheckedIndexedAccess. - while (start < raw.length && ((raw[start] as number) & 0xC0) === 0x80) start += 1 - const tail = raw.subarray(start) - return { text: tail.toString('utf8'), bytes: tail.length } -} - -/** - * One scope's contributions: the job controllers attached from it and the - * completion, change, and record-output listeners registered there. All - * tables are anonymous because a contribution is identified by its own - * disposer, never by a name a second registrant could shadow. - */ -class JobLayer implements ScopeLayer { - readonly controllers = new AnonymousEntries() - readonly listeners = new AnonymousEntries() - readonly changed = new AnonymousEntries() - readonly output = new AnonymousEntries() - - isEmpty(): boolean { - return this.controllers.isEmpty() && this.listeners.isEmpty() && this.changed.isEmpty() - && this.output.isEmpty() - } -} - /** * The in-memory `jobs` registry. See the Service Definition contract in * `@deepseek-ai/dsh-jobs` for the ownership, isolation, and lifecycle @@ -172,20 +131,28 @@ export class LocalJobRegistry extends JobRegistry { .min(1) .max(Number.MAX_SAFE_INTEGER) .default(DEFAULT_SETTLED_RETAIN_BYTES), + pumpPollMs: z.number() + .step(1) + .min(1) + .max(Number.MAX_SAFE_INTEGER) + .default(DEFAULT_PUMP_POLL_MS), }) /** Schemastery-defaulted active-job limit. */ private readonly maxConcurrentJobsPerOwner: number - /** Schemastery-defaulted live record retention cap. */ + /** Schemastery-defaulted live ring retention cap. */ private readonly retainBytes: number - /** Schemastery-defaulted settled record retention cap. */ + /** Schemastery-defaulted settled ring retention cap. */ private readonly settledRetainBytes: number - private store = new Map() + /** Schemastery-defaulted pull-source poll interval. */ + private readonly pumpPollMs: number + private store = new Map() private counters = new Map() /** - * Surfaces and listeners layered by the scope that registered them, in the - * tools-registry shape: a contribution files into its registering context's - * scope, and a read unions the global layer with the reader's scope chain. + * Controllers and scoped subscriptions layered by the scope that registered + * them, in the tools-registry shape: a contribution files into its + * registering context's scope, and a read unions the global layer with the + * owner's scope chain. * * The registry is one process-wide instance serving every composition, so a * flat table would answer a per-owner question process-wide: one preset's @@ -195,7 +162,7 @@ export class LocalJobRegistry extends JobRegistry { * layer, so change notification is a no-op. */ private readonly layers = new ScopedLayers(() => new JobLayer(), () => {}) - private listenersClosed = false + private readonly hub: JobEventHub /** Owner agents with attached scope cleanup, mapped to the exact disposer. */ private ownerCleanups = new Map Promise | void>() /** Service context used by detached settlement continuations and teardown. */ @@ -204,15 +171,30 @@ export class LocalJobRegistry extends JobRegistry { constructor(ctx: Context, config: Config) { super(ctx) // Schemastery validates and fills the defaults before constructing the service. - this.maxConcurrentJobsPerOwner = (config as Required).maxConcurrentJobsPerOwner - this.retainBytes = (config as Required).retainBytes - this.settledRetainBytes = (config as Required).settledRetainBytes + const resolved = config as Required + this.maxConcurrentJobsPerOwner = resolved.maxConcurrentJobsPerOwner + this.retainBytes = resolved.retainBytes + this.settledRetainBytes = resolved.settledRetainBytes + this.pumpPollMs = resolved.pumpPollMs this.selfCtx = ctx + this.hub = new JobEventHub(this.layers, message => ctx.logger.warn(message)) ctx.effect(() => () => this.disposeAll(), 'jobs teardown') } - start(spec: JobStart): JobId { - if (!this.servesOwner(spec.owner)) { + /** + * The event stream bound to the accessing context: a subscription is an + * effect of that context, and `{ owners: 'scope' }` names its scope. + */ + get events(): JobEvents { + const registrar = this.ctx + return { + subscribe: (filter, listener) => this.hub.subscribe(registrar, filter, listener), + } + } + + start(spec: JobSpec): JobId { + const owner = this.resolveOwner(spec.owner) + if (!this.servesOwner(owner)) { throw new Error('background jobs unavailable: no job controller serves this agent (load @deepseek-ai/dsh-tool-jobs in its composition)') } if (spec.kind.length === 0) throw new Error('invalid job kind: expected a non-empty string') @@ -221,9 +203,9 @@ export class LocalJobRegistry extends JobRegistry { && (!Number.isSafeInteger(spec.outputLimitBytes) || spec.outputLimitBytes <= 0)) { throw new Error(`invalid outputLimitBytes: expected a positive safe integer, got ${JSON.stringify(spec.outputLimitBytes)}`) } - if (spec.owner !== undefined) this.ensureOwnerCleanup(spec.owner) + if (owner !== undefined) this.ensureOwnerCleanup(owner) - const active = this.activeTaskCount(spec.owner) + const active = this.activeTaskCount(owner) if (active >= this.maxConcurrentJobsPerOwner) { throw new Error( `background job limit reached for this owner (limit: ${this.maxConcurrentJobsPerOwner}); use job_kill to stop an unneeded job, wait for it to finish, then retry`, @@ -236,189 +218,90 @@ export class LocalJobRegistry extends JobRegistry { const count = (this.counters.get(spec.kind) ?? 0) + 1 this.counters.set(spec.kind, count) const id = JobId(`${spec.kind}-${count}`) - const state: ProducerState = { record: undefined, detail: undefined, job: undefined } - const face: RunningJob = { + const ring = new OutputRing() + const state: ProducerState = { progress: undefined, job: undefined } + const handle: JobHandle = { id, - updateDetail: (detail) => { this.updateDetail(state, detail) }, + append: (text, options) => { this.appendRing(state, ring, text, options, 'producer') }, + updateProgress: (line) => { this.updateProgress(state, line) }, } - // The declaration decides the face: a plain start never receives `append`. - const hooks = spec.record === true ? spec.run(this.recordingFace(face, state)) : spec.run(face) + const hooks = spec.run(handle) let markSettled!: () => void const settled = new Promise((resolve) => { markSettled = resolve }) - const job: TrackedTask = { + const job: TrackedJob = { id, kind: spec.kind, label: spec.label, outputLimitBytes: spec.outputLimitBytes, - owner: spec.owner, + owner, cancel: hooks.cancel.bind(hooks), - readOutput: hooks.readOutput?.bind(hooks), status: 'running', + ring, + modelCursor: 0, + resultDelivered: false, state, - output: undefined, + detail: undefined, + result: undefined, startedAt: Date.now(), finishedAt: undefined, - reported: false, + killReason: undefined, + settleCause: undefined, settled, markSettled, - waiters: 0, waitResolvers: new Set(), + pump: undefined, } // Binding the shared producer state is the commit: writes staged inside - // the starter are already in `state`, and every later handle call reaches - // the registered record for its terminal checks and observer signals. + // the starter are already in the ring and `state`, and every later handle + // call reaches the registered record for its terminal checks and signals. state.job = job this.store.set(id, job) - void hooks.done.then( - (outcome) => { this.settle(job, outcome) }, - (error: unknown) => { + // The producer's settlement or a registry-forced one ends the pump; the + // pump's final drain then lands before this registry trims the ring. + const producerDone = hooks.done.then( + outcome => outcome, + (error: unknown): JobOutcome => { // Contain a producer contract violation (`done` rejected) so cleanup and waiters cannot hang. this.selfCtx.logger.warn(`jobs: job ${job.id} producer done promise rejected (producer contract violation): ${String(error)}`) - this.settle(job, { status: 'failed', detail: String(error) }) + return { status: 'failed', detail: String(error) } }, ) + if (spec.output !== undefined && spec.output.length > 0) { + job.pump = startPump( + spec.output, + (text, options) => { this.appendRing(state, ring, text, options, 'pump') }, + this.pumpPollMs, + Promise.race([producerDone, settled]), + ) + } + void producerDone.then(async (outcome) => { + if (job.pump !== undefined) await job.pump.done + this.settle(job, outcome, job.settleCause ?? 'producer') + }) // Registration is complete and cannot fail from here, so the visible set // has genuinely changed. - this.notifyChanged(job.owner) + this.emit({ type: 'registered', job: this.view(job) }, owner) return id } - list(caller?: Agent): JobSnapshot[] { - const session = caller?.id - return [...this.store.values()] - .filter(job => job.owner === undefined || job.owner.id === session) - .map(job => this.snapshot(job)) - } - - get(id: JobId, caller?: Agent): JobSnapshot { - const job = this.expect(id) - this.assertAccess(job, caller) - return this.snapshot(job) - } - - read(id: JobId, caller?: Agent): JobRead { - const job = this.expect(id) - this.assertAccess(job, caller) - const text = job.readOutput !== undefined - ? job.readOutput() - : isTerminal(job.status) ? job.output ?? '' : '' - if (isTerminal(job.status)) job.reported = true - return { text, snapshot: this.snapshot(job) } - } - - kill(id: JobId, caller?: Agent, reason?: string): 'requested' | 'already-finished' { - const job = this.expect(id) - this.assertAccess(job, caller) - if (isTerminal(job.status)) { - job.reported = true - return 'already-finished' + visibleTo(caller?: SessionId): VisibleJobs { + const reach = (id: JobId): TrackedJob => { + const job = this.expect(id) + this.assertAccess(job, caller) + return job } - // Cancel first so a throw leaves both lifecycle and notice state unchanged. - job.cancel(reason) - job.status = 'stopping' - job.reported = true - this.notifyChanged(job.owner) - return 'requested' - } - - async wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise { - const job = this.expect(id) - this.assertAccess(job, caller) - if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) { - throw new Error(`invalid wait timeout: expected a positive number of milliseconds, got ${JSON.stringify(timeoutMs)}`) + return { + list: () => [...this.store.values()] + .filter(job => job.owner === undefined || job.owner.id === caller) + .map(job => this.view(job)), + get: id => this.view(reach(id)), + read: id => this.readJob(reach(id)), + readAt: (id, from) => this.readAt(reach(id), from), + kill: (id, options) => this.killJob(reach(id), options), + wait: async (id, timeoutMs, signal) => this.waitJob(reach(id), timeoutMs, signal), } - if (!isTerminal(job.status)) { - if (signal?.aborted) throw new Error('wait aborted') - // Abort removes the waiter synchronously so same-tick settlement cannot - // suppress a notice for a wait that will reject. - job.waiters += 1 - let counted = true - const uncount = (): void => { - if (!counted) return - counted = false - job.waiters -= 1 - } - try { - // The scoped deadline distinguishes a successful wait timeout from - // caller cancellation and clears its timer on every exit. - using d = deadline(signal, timeoutMs, TASK_WAIT_TIMEOUT) - await new Promise((resolve, reject) => { - const onSettled = (): void => { - job.waitResolvers.delete(onSettled) - d.signal.removeEventListener('abort', onAbort) - resolve() - } - const onAbort = (): void => { - job.waitResolvers.delete(onSettled) - // A settled job cannot reach here: settlement releases every waiter - // before it announces completion, and each released waiter detaches - // this listener in the same synchronous span, so nothing that reacts - // to a settlement can abort a wait the settlement already owed. - if (timeoutOf(d.signal, TASK_WAIT_TIMEOUT) !== undefined) { - resolve() - } else { - uncount() - reject(new Error('wait aborted')) - } - } - job.waitResolvers.add(onSettled) - d.signal.addEventListener('abort', onAbort, { once: true }) - }) - } finally { - uncount() - } - } - if (isTerminal(job.status)) job.reported = true - return this.snapshot(job) - } - - onJobDone(listener: JobDoneListener): () => void { - return this.layers.effect( - this.ctx, - layer => layer.listeners.append(listener), - { label: 'jobs.onJobDone()' }, - ) - } - - onJobsChanged(listener: JobsChangedListener): () => void { - return this.layers.effect( - this.ctx, - layer => layer.changed.append(listener), - { label: 'jobs.onJobsChanged()' }, - ) - } - - readRecord(id: JobId, from: number, caller?: Agent): JobRecordRead { - const job = this.expect(id) - this.assertAccess(job, caller) - if (!Number.isSafeInteger(from) || from < 0) { - throw new Error(`invalid record read offset: expected a non-negative safe integer, got ${JSON.stringify(from)}`) - } - const record = job.state.record - if (record === undefined) { - throw new Error(`job ${job.id} declared no output record`) - } - const chunks: JobRecordChunk[] = [] - for (const chunk of record.chunks) { - if (chunk.at + chunk.bytes <= from) continue - chunks.push({ - at: chunk.at, - text: chunk.text, - ...chunk.channel !== undefined ? { channel: chunk.channel } : {}, - ...chunk.gapBefore !== undefined ? { gapBefore: chunk.gapBefore } : {}, - }) - } - return { chunks, next: record.total, lossy: from < record.earliest } - } - - onOutput(listener: JobOutputListener): () => void { - return this.layers.effect( - this.ctx, - layer => layer.output.append(listener), - { label: 'jobs.onOutput()' }, - ) } attachController(name: string): () => void { @@ -431,6 +314,24 @@ export class LocalJobRegistry extends JobRegistry { ) } + /** + * Resolve a spec's owner session to its live Agent. An owned registration + * needs the agent registry, and the session must currently have a live + * instance: that instance's disposal is what cancels and drops the job. + */ + private resolveOwner(session: SessionId | undefined): Agent | undefined { + if (session === undefined) return undefined + const agents = this.selfCtx.get('agents') + if (agents === undefined) { + throw new Error('background job ownership requires the agent registry (load @deepseek-ai/dsh-agent)') + } + const owner = agents.get(session) + if (owner === undefined) { + throw new Error(`session "${session}" has no live agent (background job owner must be live)`) + } + return owner + } + /** * Whether an attached job controller can collect and stop work owned by * `owner`. The global layer holds every controller attached from an unscoped @@ -454,22 +355,8 @@ export class LocalJobRegistry extends JobRegistry { return count } - /** - * The completion listeners that own `owner`'s notices: the global layer's - * first, then each scoped layer along the owner's chain. A listener outside - * that chain belongs to another composition and must not deliver, or the - * owner reads one notice per mounted preset. - * @param owner - the settled job's owner, or undefined for unowned work. - * @returns the listeners to notify, in registration order per layer. - */ - private *listenersFor(owner?: Agent): IterableIterator { - yield* this.layers.global.listeners.values() - const scope = owner === undefined ? undefined : scopeOf(owner.ctx) - for (const layer of this.layers.chainLayers(scope)) yield* layer.listeners.values() - } - /** Look up a job or fail loud. */ - private expect(id: JobId): TrackedTask { + private expect(id: JobId): TrackedJob { const job = this.store.get(id) if (job === undefined) throw new Error(`unknown job ${id}`) return job @@ -478,214 +365,189 @@ export class LocalJobRegistry extends JobRegistry { /** * The isolation fence: a job with an owner is reachable only by callers * whose session id matches (`!== undefined` semantics — an unowned job is - * open, and a no-agent caller can never match an owned one). + * open, and a caller-less view can never match an owned one). */ - private assertAccess(job: TrackedTask, caller?: Agent): void { - if (job.owner !== undefined && job.owner.id !== caller?.id) { + private assertAccess(job: TrackedJob, caller: SessionId | undefined): void { + if (job.owner !== undefined && job.owner.id !== caller) { throw new Error(`job ${job.id} belongs to another session`) } } - /** Project a fresh read-only snapshot from the mutable record. */ - private snapshot(job: TrackedTask): JobSnapshot { - const ownerSession = job.owner?.id - const record = job.state.record + /** Project a fresh read-only view from the mutable record. */ + private view(job: TrackedJob): JobView { + const owner = job.owner?.id return { id: job.id, kind: job.kind, label: job.label, + ...owner !== undefined ? { owner } : {}, ...job.outputLimitBytes !== undefined ? { outputLimitBytes: job.outputLimitBytes } : {}, - ...ownerSession !== undefined ? { ownerSession } : {}, status: job.status, - ...job.state.detail !== undefined ? { detail: job.state.detail } : {}, + ...job.state.progress !== undefined ? { progress: job.state.progress } : {}, + ...job.detail !== undefined ? { detail: job.detail } : {}, startedAt: job.startedAt, ...job.finishedAt !== undefined ? { finishedAt: job.finishedAt } : {}, - reported: job.reported, - ...record !== undefined ? { outputTotal: record.total, outputEarliest: record.earliest } : {}, + output: { total: job.ring.total, earliest: job.ring.earliest }, } } - /** - * The change observers that own `owner`'s updates, resolved exactly like - * {@link listenersFor}: the global layer — a host composition's own carrier, - * which serves every owner — then each scoped layer along the owner's chain. - * An observer outside that chain belongs to another composition and would - * otherwise be told about agents it does not compose. - * @param owner - the owner whose visible set moved, or undefined for unowned work. - * @returns the observers to notify, in registration order per layer. - */ - private *changedFor(owner?: Agent): IterableIterator { - yield* this.layers.global.changed.values() - const scope = owner === undefined ? undefined : scopeOf(owner.ctx) - for (const layer of this.layers.chainLayers(scope)) yield* layer.changed.values() + private emit(event: JobEvent, owner: Agent | undefined): void { + this.hub.emit(event, owner) } - /** - * Announce that one owner's visible set changed. Each listener is contained - * so an observer cannot break a lifecycle commit that already happened. - */ - private notifyChanged(owner: Agent | undefined): void { - for (const listener of this.changedFor(owner)) { - try { - listener(owner) - } catch (error: unknown) { - this.selfCtx.logger.warn(`jobs: onJobsChanged listener threw: ${String(error)}`) - } - } - } - - /** The record-output observers that own `owner`'s stream signals, resolved like {@link changedFor}. */ - private *outputFor(owner?: Agent): IterableIterator { - yield* this.layers.global.output.values() - const scope = owner === undefined ? undefined : scopeOf(owner.ctx) - for (const layer of this.layers.chainLayers(scope)) yield* layer.output.values() - } - - /** Announce that one job's record advanced (append or settlement), with per-listener containment. */ - private notifyOutput(job: TrackedTask): void { - for (const listener of this.outputFor(job.owner)) { - try { - listener(job.id) - } catch (error: unknown) { - this.selfCtx.logger.warn(`jobs: onOutput listener threw: ${String(error)}`) - } - } - } - - /** Install the job's record and extend the producer face with its append. */ - private recordingFace(face: RunningJob, state: ProducerState): RecordingJob { - const record: RecordState = { chunks: [], retainedBytes: 0, total: 0, earliest: 0 } - state.record = record + /** Consume the ring from the model cursor; the result rides the first read after settlement. */ + private readJob(job: TrackedJob): JobRead { + const read = job.ring.readFrom(job.modelCursor) + job.modelCursor = job.ring.total + const result = isTerminal(job.status) && !job.resultDelivered ? job.result : undefined + if (result !== undefined) job.resultDelivered = true return { - ...face, - append: (text, options) => { this.appendRecord(state, record, text, options) }, + chunks: read.chunks, + lossy: read.lossy, + ...result !== undefined ? { result } : {}, + job: this.view(job), } } + private readAt(job: TrackedJob, from: number): JobOutputRead { + if (!Number.isSafeInteger(from) || from < 0) { + throw new Error(`invalid output read offset: expected a non-negative safe integer, got ${JSON.stringify(from)}`) + } + return job.ring.readFrom(from) + } + + private killJob(job: TrackedJob, options?: JobKillOptions): 'requested' | 'already-finished' { + if (isTerminal(job.status)) return 'already-finished' + // Cancel first so a throw leaves lifecycle state unchanged. + job.cancel(options?.reason) + job.status = 'stopping' + // Last writer wins on purpose: the detail reports the latest kill intent. + if (options?.reason !== undefined) job.killReason = options.reason + job.settleCause = 'kill' + this.emit({ type: 'stopping', job: this.view(job) }, job.owner) + return 'requested' + } + + private async waitJob(job: TrackedJob, timeoutMs: number, signal?: AbortSignal): Promise { + if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) { + throw new Error(`invalid wait timeout: expected a positive number of milliseconds, got ${JSON.stringify(timeoutMs)}`) + } + if (!isTerminal(job.status)) { + if (signal?.aborted) throw new Error('wait aborted') + // The scoped deadline distinguishes a successful wait timeout from + // caller cancellation and clears its timer on every exit. + using d = deadline(signal, timeoutMs, TASK_WAIT_TIMEOUT) + await new Promise((resolve, reject) => { + const onSettled = (): void => { + job.waitResolvers.delete(onSettled) + d.signal.removeEventListener('abort', onAbort) + resolve() + } + const onAbort = (): void => { + job.waitResolvers.delete(onSettled) + // A settled job cannot reach here: settlement releases every waiter + // before it announces, and each released waiter detaches this + // listener in the same synchronous span, so nothing that reacts to a + // settlement can abort a wait the settlement already owed. + if (timeoutOf(d.signal, TASK_WAIT_TIMEOUT) !== undefined) { + resolve() + } else { + reject(new Error('wait aborted')) + } + } + job.waitResolvers.add(onSettled) + d.signal.addEventListener('abort', onAbort, { once: true }) + }) + } + return this.view(job) + } + /** - * Append one chunk through a recording producer face. A chunk against a - * settled job is logged and dropped; an empty chunk is dropped silently. A - * chunk staged inside the starter call is retained and signals no observer — - * the registration commit publishes it. + * Append one chunk to the ring. A producer chunk against a settled job is + * logged and dropped; the registry's own pump drains silently after + * settlement (a forced settlement may precede the producer's). A chunk + * staged inside the starter call is retained and signals no observer — the + * registration commit publishes it. */ - private appendRecord(state: ProducerState, record: RecordState, text: string, options?: JobAppendOptions): void { + private appendRing( + state: ProducerState, + ring: OutputRing, + text: string, + options: JobAppendOptions | undefined, + writer: 'producer' | 'pump', + ): void { const job = state.job if (job !== undefined && isTerminal(job.status)) { - this.selfCtx.logger.warn(`jobs: append to settled job ${job.id} dropped`) + if (writer === 'producer') this.selfCtx.logger.warn(`jobs: append to settled job ${job.id} dropped`) return } - if (text.length === 0) return - const bytes = Buffer.byteLength(text, 'utf8') - record.chunks.push({ - at: record.total, - text, - bytes, - ...options?.channel !== undefined ? { channel: options.channel } : {}, - ...options?.gapBefore !== undefined ? { gapBefore: options.gapBefore } : {}, - }) - record.total += bytes - record.retainedBytes += bytes - this.trimRecord(record, this.retainBytes) - if (job !== undefined) this.notifyOutput(job) + if (!ring.append(text, options, this.retainBytes)) return + if (job !== undefined) this.emitOutput(job) + } + + /** Announce that one job's ring advanced (append or settlement). */ + private emitOutput(job: TrackedJob): void { + const owner = job.owner?.id + this.emit({ type: 'output', id: job.id, ...owner !== undefined ? { owner } : {}, total: job.ring.total }, job.owner) } /** - * Replace the live detail line through a producer face; a write against a + * Replace the live progress line through a producer face; a write against a * settled job is logged and dropped. A write staged inside the starter call - * seeds the registered snapshot and signals no observer. + * seeds the registered projection and signals no observer. */ - private updateDetail(state: ProducerState, detail: string): void { + private updateProgress(state: ProducerState, line: string): void { const job = state.job if (job !== undefined && isTerminal(job.status)) { - this.selfCtx.logger.warn(`jobs: detail update on settled job ${job.id} dropped`) + this.selfCtx.logger.warn(`jobs: progress update on settled job ${job.id} dropped`) return } - state.detail = detail - if (job !== undefined) this.notifyChanged(job.owner) + state.progress = line + if (job !== undefined) this.emit({ type: 'progress', job: this.view(job) }, job.owner) } /** - * Drop retained head chunks until the ring fits `cap`; a single oversized - * chunk keeps only its UTF-8-safe tail with a `gapBefore` marker. Offsets - * stay absolute: `earliest` advances over everything dropped. + * Record the first terminal outcome, release waiters, then announce the + * settlement. First-wins preserves a teardown force-failure against late + * producer settlement. The settled event follows every released waiter, so + * a consumer that claims while waiting always claims before the event. */ - private trimRecord(record: RecordState, cap: number): void { - while (record.retainedBytes > cap && record.chunks.length > 1) { - const dropped = record.chunks.shift() - /* v8 ignore next -- the length guard proves shift() returns a chunk; the check only satisfies noUncheckedIndexedAccess. */ - if (dropped === undefined) break - record.retainedBytes -= dropped.bytes - } - const single = record.chunks.length === 1 ? record.chunks[0] : undefined - if (single !== undefined && single.bytes > cap) { - const tail = utf8Tail(single.text, cap) - single.at += single.bytes - tail.bytes - single.text = tail.text - single.bytes = tail.bytes - single.gapBefore = true - record.retainedBytes = tail.bytes - } - record.earliest = record.chunks[0]?.at ?? record.total - } - - /** - * Record the first terminal outcome, release waiters, then announce - * completion. First-wins preserves a teardown force-failure against late - * producer settlement. Pending waits mark the job reported before listeners - * run. Completion is announced last because a reporter may open a model turn - * synchronously: every other observer of this settlement must already have - * seen the committed record. - */ - private settle(job: TrackedTask, outcome: JobOutcome): void { + private settle(job: TrackedJob, outcome: JobOutcome, cause: JobSettleCause): void { if (isTerminal(job.status)) return job.status = outcome.status - // A terminal detail replaces the live progress line; without one the last - // progress line stays, still describing what the job was doing. - if (outcome.detail !== undefined) job.state.detail = outcome.detail - job.output = outcome.output + // A killed settlement carries the recorded kill reason in its detail: + // producer facts first (`signal: SIGTERM; cancelled by the user`). A job + // that outran its kill request (settled `completed`/`failed`) keeps the + // producer detail alone — the reason describes a kill that never landed. + if (outcome.status === 'killed' && job.killReason !== undefined) { + job.detail = outcome.detail !== undefined + ? `${outcome.detail}; ${job.killReason}` + : job.killReason + } else if (outcome.detail !== undefined) { + job.detail = outcome.detail + } + job.state.progress = undefined + job.result = outcome.result job.finishedAt = Date.now() - if (job.waiters > 0) job.reported = true - // Settlement ends the record: trim to the settled cap before any observer - // reads the terminal snapshot. - const record = job.state.record - if (record !== undefined) this.trimRecord(record, this.settledRetainBytes) - const snapshot = this.snapshot(job) + // Settlement ends the stream: trim to the settled cap before any observer + // reads the terminal projection. + job.ring.trim(this.settledRetainBytes) const waitResolvers = [...job.waitResolvers] job.waitResolvers.clear() for (const resolveWait of waitResolvers) resolveWait() job.markSettled() - this.notifyChanged(job.owner) - // The record stream ends with settlement; the signal follows the committed - // visible-set change and precedes completion listeners, which stay last. - if (record !== undefined) this.notifyOutput(job) - if (this.listenersClosed) return - for (const listener of this.listenersFor(job.owner)) { - try { - const returned = listener(snapshot, job.owner) - void Promise.resolve(returned).catch((error: unknown) => { - this.selfCtx.logger.warn(`jobs: onJobDone listener rejected for ${job.id}: ${String(error)}`) - }) - } catch (error: unknown) { - this.selfCtx.logger.warn(`jobs: onJobDone listener threw for ${job.id}: ${String(error)}`) - } - } + this.emit({ type: 'settled', job: this.view(job), cause }, job.owner) + // The ring's stream ends with settlement; the signal follows the committed + // settlement so an observer that wakes on it reads the terminal state. + this.emitOutput(job) } /** * Attach one awaited cleanup through the exact owner's scope. This survives * producer reloads and joins agent quiescence; the retained disposer lets - * service teardown detach the cross-fiber effect. Fails when the registry is - * absent or the owner is not its currently registered instance. + * service teardown detach the cross-fiber effect. */ private ensureOwnerCleanup(owner: Agent): void { - const ownerId = owner.id - const agents = this.selfCtx.get('agents') - if (agents === undefined) { - throw new Error('background job ownership requires the agent registry (load @deepseek-ai/dsh-agent)') - } - if (agents.get(ownerId) !== owner) { - throw new Error(`agent "${ownerId}" is not the registered agent instance (background job owner must be live)`) - } if (this.ownerCleanups.has(owner)) return // Record only after attach succeeds; a disposing scope rejects new effects. const detach = owner.ctx.effect(() => async () => { @@ -700,31 +562,30 @@ export class LocalJobRegistry extends JobRegistry { const owned = [...this.store.values()].filter(job => job.owner === owner) this.cancelForTeardown(owned, 'owner disposed') await Promise.all(owned.map(job => job.settled)) - for (const job of owned) this.store.delete(job.id) - // Removal is the one visible-set change no per-job record carries, so it - // must be announced here or an observer keeps the dropped rows forever. - if (owned.length > 0) this.notifyChanged(owner) + this.remove(owned) + } + + /** Drop settled records and announce each removal, the one visible-set change no per-job record carries. */ + private remove(jobs: readonly TrackedJob[]): void { + for (const job of jobs) { + this.store.delete(job.id) + this.emit({ type: 'removed', job: this.view(job) }, job.owner) + } } /** - * Close listeners, cancel live jobs, await settlement, and detach owner + * Cancel live jobs, await settlement, drop every record, and detach owner * effects. Throwing cancels are force-failed to avoid teardown deadlock. */ private async disposeAll(): Promise { - // The flag is the whole guard: each layer entry's undo belongs to the fiber - // that registered it, so this service may not drop them on its own way out. - this.listenersClosed = true const all = [...this.store.values()] this.cancelForTeardown(all, 'jobs service disposed') await Promise.all(all.map(job => job.settled)) - // Distinct owners whose records just disappeared. A change observer files - // into the layer of the context that registered it, so a consumer mounted - // outside this service — the api-proxy carrier registers from the mux - // stream — is still reachable here. Without this it keeps the rows it last - // received after a registry reload. - const emptied = new Set(all.map(job => job.owner)) - this.store.clear() - for (const owner of emptied) this.notifyChanged(owner) + // A subscriber mounted outside this service — the job controller's rows + // stream registers from its own context — is still reachable here. + // Without the removals it keeps the rows it last received after a + // registry reload. + this.remove(all) // Detach cross-fiber owner effects after the shared store is quiescent. const ownerCleanups = [...this.ownerCleanups.values()] this.ownerCleanups.clear() @@ -736,28 +597,24 @@ export class LocalJobRegistry extends JobRegistry { * force-fails the record and reports a possible orphan; a cancel that returns * without settling remains indistinguishable from a slow stop and may stall. */ - private cancelForTeardown(jobs: TrackedTask[], reason: string): void { + private cancelForTeardown(jobs: TrackedJob[], reason: string): void { for (const job of jobs) { if (isTerminal(job.status)) continue - // Teardown cancellation is a kill without a caller, so it claims the - // terminal report the same way `kill()` does. Nothing will read a notice - // for a job whose owner or service is being destroyed, and a waking - // reporter would spend a model request per teardown layer. This is - // decided before the producer runs: the force-failure below settles the - // record too, so a throwing cancel must not be the one path that - // announces an unreported completion into a disposing owner. - job.reported = true + // Whatever settles this job from here on, its owner or the service is + // being destroyed: the settlement announces `teardown` so a completion + // reporter does not address a reader that no longer exists. + job.settleCause = 'teardown' try { job.cancel(reason) job.status = 'stopping' // Teardown reaches settlement only after the producer releases, which a // slow stop can defer; announcing the transition here is what keeps an // observer from showing `running` for that whole window. - this.notifyChanged(job.owner) + this.emit({ type: 'stopping', job: this.view(job) }, job.owner) } catch (error: unknown) { const detail = `cancel threw during teardown; work may be orphaned: ${String(error)}` this.selfCtx.logger.warn(`jobs: cancel of ${job.id} threw during teardown; job record forced failed and work may be orphaned: ${String(error)}`) - this.settle(job, { status: 'failed', detail }) + this.settle(job, { status: 'failed', detail }, 'teardown') } } } diff --git a/packages/jobs/jobs-local/tests/events.spec.ts b/packages/jobs/jobs-local/tests/events.spec.ts new file mode 100644 index 0000000000..b77a4e5c8c --- /dev/null +++ b/packages/jobs/jobs-local/tests/events.spec.ts @@ -0,0 +1,138 @@ +import { describe, expect, it, vi } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import { Session, SessionId } from '@deepseek-ai/dsh-session' +import { Inbox } from '@deepseek-ai/dsh-agent' +import type { Agent } from '@deepseek-ai/dsh-agent' +import { ScopedLayers, bindScopeParent, createScope, scopeOf } from '@deepseek-ai/dsh-scope' +import type { ScopeKey } from '@deepseek-ai/dsh-scope' +import { JobId } from '@deepseek-ai/dsh-jobs' +import type { JobEvent, JobView } from '@deepseek-ai/dsh-jobs' +import { JobEventHub, JobLayer } from '../src/events.ts' + +function agentIn(ctx: Context, rawId: string, presetScope?: ScopeKey): Agent { + const id = SessionId(rawId) + let agentCtx = ctx.plugin(() => {}).ctx + if (presetScope !== undefined) { + const key = {} + bindScopeParent(key, presetScope) + agentCtx = createScope(agentCtx, key).ctx + } + const session = Session.create(id) + return { + id, + session, + inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }), + status: 'idle', + ctx: agentCtx, + } as unknown as Agent +} + +function view(owner: Agent | undefined): JobView { + return { + id: JobId('bash-1'), + kind: 'bash', + label: 'x', + ...owner !== undefined ? { owner: owner.id } : {}, + status: 'running', + startedAt: 0, + output: { total: 0, earliest: 0 }, + } +} + +function bench() { + const ctx = new Context() + const warnings: string[] = [] + const layers = new ScopedLayers(() => new JobLayer(), () => {}) + const hub = new JobEventHub(layers, message => warnings.push(message)) + return { ctx, hub, warnings } +} + +describe('JobEventHub', () => { + it('delivers by owner: that session plus every unowned job, never another session', () => { + const { ctx, hub } = bench() + const alice = agentIn(ctx, 'alice') + const bob = agentIn(ctx, 'bob') + const seen: (string | undefined)[] = [] + hub.subscribe(ctx, { owner: alice.id }, (event) => { seen.push(event.type === 'output' ? event.owner : event.job.owner) }) + + hub.emit({ type: 'registered', job: view(alice) }, alice) + hub.emit({ type: 'registered', job: view(bob) }, bob) + hub.emit({ type: 'registered', job: view(undefined) }, undefined) + hub.emit({ type: 'output', id: JobId('bash-1'), owner: bob.id, total: 1 }, bob) + hub.emit({ type: 'output', id: JobId('bash-1'), total: 1 }, undefined) + expect(seen).toEqual(['alice', undefined, undefined]) + }) + + it("delivers 'all' everything and 'scope' only the owners composed under the subscriber", async () => { + const { ctx, hub } = bench() + const mount = createScope(ctx, {}) + const otherMount = createScope(ctx, {}) + const alice = agentIn(ctx, 'alice', scopeOf(mount.ctx)) + const bob = agentIn(ctx, 'bob', scopeOf(otherMount.ctx)) + + const all: string[] = [] + hub.subscribe(ctx, { owners: 'all' }, (event) => { all.push(event.type === 'output' ? String(event.owner) : String(event.job.owner)) }) + const scoped: string[] = [] + await mount.ctx.plugin((pluginCtx: Context) => { + hub.subscribe(pluginCtx, { owners: 'scope' }, (event) => { scoped.push(event.type === 'output' ? String(event.owner) : String(event.job.owner)) }) + }) + const unscoped: string[] = [] + hub.subscribe(ctx, { owners: 'scope' }, (event) => { unscoped.push(event.type === 'output' ? String(event.owner) : String(event.job.owner)) }) + + hub.emit({ type: 'registered', job: view(alice) }, alice) + hub.emit({ type: 'registered', job: view(bob) }, bob) + hub.emit({ type: 'registered', job: view(undefined) }, undefined) + expect(all).toEqual(['alice', 'bob', 'undefined']) + // A preset-scoped subscription hears its own agents only; an unowned job + // has no chain to walk, so only unscoped subscriptions hear it. + expect(scoped).toEqual(['alice']) + expect(unscoped).toEqual(['alice', 'bob', 'undefined']) + }) + + it('contains a throwing listener and keeps delivering to later ones', () => { + const { ctx, hub, warnings } = bench() + const seen: JobEvent[] = [] + hub.subscribe(ctx, { owners: 'all' }, () => { throw new Error('listener boom') }) + hub.subscribe(ctx, { owners: 'all' }, (event) => { seen.push(event) }) + hub.emit({ type: 'registered', job: view(undefined) }, undefined) + expect(seen).toHaveLength(1) + expect(warnings).toEqual([expect.stringContaining('event listener threw on registered: Error: listener boom')]) + }) + + it('unregisters through the disposer and with the subscribing fiber', async () => { + const { ctx, hub } = bench() + const seen: number[] = [] + const detach = hub.subscribe(ctx, { owners: 'all' }, () => { seen.push(1) }) + const fiber = await ctx.plugin((pluginCtx: Context) => { + hub.subscribe(pluginCtx, { owners: 'scope' }, () => { seen.push(2) }) + hub.subscribe(pluginCtx, { owner: SessionId('nobody') }, () => { seen.push(3) }) + }) + + // Filter-kind order is not a contract; the assertion only fixes it for determinism. + hub.emit({ type: 'registered', job: view(undefined) }, undefined) + expect(seen).toEqual([1, 3, 2]) + detach() + detach() + hub.emit({ type: 'registered', job: view(undefined) }, undefined) + expect(seen).toEqual([1, 3, 2, 3, 2]) + await fiber.dispose() + hub.emit({ type: 'registered', job: view(undefined) }, undefined) + expect(seen).toEqual([1, 3, 2, 3, 2]) + }) + + it('keeps a scoped layer alive only while a subscription or controller remains in it', async () => { + const { ctx, hub } = bench() + const mount = createScope(ctx, {}) + const spy = vi.fn() + const fiber = await mount.ctx.plugin((pluginCtx: Context) => { + hub.subscribe(pluginCtx, { owners: 'scope' }, spy) + }) + const alice = agentIn(ctx, 'alice', scopeOf(mount.ctx)) + hub.emit({ type: 'registered', job: view(alice) }, alice) + expect(spy).toHaveBeenCalledTimes(1) + await fiber.dispose() + hub.emit({ type: 'registered', job: view(alice) }, alice) + expect(spy).toHaveBeenCalledTimes(1) + expect(new JobLayer().isEmpty()).toBe(true) + }) +}) diff --git a/packages/jobs/jobs-local/tests/jobs.spec.ts b/packages/jobs/jobs-local/tests/jobs.spec.ts index 5bcb9b156e..550a713f6b 100644 --- a/packages/jobs/jobs-local/tests/jobs.spec.ts +++ b/packages/jobs/jobs-local/tests/jobs.spec.ts @@ -6,7 +6,9 @@ import type { Agent } from '@deepseek-ai/dsh-agent' import { bindScopeParent, createScope, scopeOf } from '@deepseek-ai/dsh-scope' import type { ScopeKey } from '@deepseek-ai/dsh-scope' import { JobId } from '@deepseek-ai/dsh-jobs' -import type { JobHooks, JobKind, JobOutcome, JobSnapshot, JobStart, RecordingJob } from '@deepseek-ai/dsh-jobs' +import type { + JobEvent, JobEventFilter, JobHandle, JobHooks, JobKind, JobOutcome, JobOutputSource, JobSpec, JobView, VisibleJobs, +} from '@deepseek-ai/dsh-jobs' import LocalJobRegistry, { type Config as JobsConfig } from '@deepseek-ai/dsh-jobs-local' declare module '@deepseek-ai/dsh-jobs' { @@ -55,25 +57,36 @@ async function disposeAgentScope(agent: Agent): Promise { await dispose() } -/** A controllable producer start-spec: settle its `done` on demand, record cancels, expose the job face. */ -function producer(overrides: Partial & JobHooks> = {}) { +/** Register a stub agent so the registry can resolve it as a live owner. */ +function liveAgent(ctx: Context, rawId: string, presetScope?: ScopeKey): Agent { + const agent = stubAgent(ctx, rawId, presetScope) + ctx.agents.register(agent) + return agent +} + +type ProducerOverrides = Partial & JobHooks> & { + owner?: Agent +} + +/** A controllable producer spec: settle its `done` on demand, record cancels, expose the handle. */ +function producer(overrides: ProducerOverrides = {}) { let settle!: (outcome: JobOutcome) => void let reject!: (error: unknown) => void const cancels: (string | undefined)[] = [] - const { kind = 'bash', label = 'sleep 60', owner, outputLimitBytes, record, ...hookOverrides } = overrides + const { kind = 'bash', label = 'sleep 60', owner, outputLimitBytes, output, ...hookOverrides } = overrides const hooks: JobHooks = { cancel(reason) { cancels.push(reason) }, done: new Promise((res, rej) => { settle = res; reject = rej }), ...hookOverrides, } - let started: RecordingJob | undefined - const spec: JobStart = { + let started: JobHandle | undefined + const spec: JobSpec = { kind, label, - ...owner !== undefined ? { owner } : {}, + ...owner !== undefined ? { owner: owner.id } : {}, ...outputLimitBytes !== undefined ? { outputLimitBytes } : {}, - ...record !== undefined ? { record } : {}, - run: (job: RecordingJob) => { + ...output !== undefined ? { output } : {}, + run: (job) => { started = job return hooks }, @@ -83,7 +96,7 @@ function producer(overrides: Partial & JobHooks> = {}) { settle, reject, cancels, - job(): RecordingJob { + job(): JobHandle { if (started === undefined) throw new Error('producer not started') return started }, @@ -98,12 +111,24 @@ async function harness(config: JobsConfig = {}) { return ctx } +/** The caller-bound view for an agent, or the anonymous view. */ +function jobsOf(ctx: Context, agent?: Agent): VisibleJobs { + return ctx.jobs.visibleTo(agent?.id) +} + +/** Collect events matching `filter`; `types` narrows what is recorded. */ +function collect(ctx: Context, filter: JobEventFilter = { owners: 'all' }, types?: JobEvent['type'][]): JobEvent[] { + const seen: JobEvent[] = [] + ctx.jobs.events.subscribe(filter, (event) => { + if (types === undefined || types.includes(event.type)) seen.push(event) + }) + return seen +} + /** * Attach a job controller the way `tool-jobs` does: from a plugin whose own * `inject` resolves `ctx.jobs`, so the service method binds to the REGISTERING - * context and the controller files into that context's scope layer. Reading the - * service off a bare scoped context instead throws `cannot get property "jobs" - * without inject`, which is the same rule the shipped plugin obeys. + * context and the controller files into that context's scope layer. * @param ctx - the context whose scope should own the controller. */ async function attachControllerIn(ctx: Context): Promise { @@ -124,9 +149,22 @@ function waitResolverCount(ctx: Context, id: JobId): number { return job.waitResolvers.size } +/** A scripted pull source: each read shifts the next scripted result. */ +function scriptedSource(reads: { text: string; lossy?: boolean }[], channel?: 'stdout' | 'stderr'): JobOutputSource { + let offset = 0 + return { + ...channel !== undefined ? { channel } : {}, + read() { + const next = reads.shift() ?? { text: '' } + offset += Buffer.byteLength(next.text, 'utf8') + return { text: next.text, nextOffset: offset, lossy: next.lossy ?? false } + }, + } +} + describe('LocalJobRegistry.start', () => { - it('preserves the SessionId brand on public owner snapshots', () => { - expectTypeOf().toEqualTypeOf() + it('preserves the SessionId brand on public owner projections', () => { + expectTypeOf().toEqualTypeOf() }) it('refuses to register while no job controller serves the owner', async () => { @@ -146,10 +184,8 @@ describe('LocalJobRegistry.start', () => { const withoutControls = createScope(ctx, {}) await attachControllerIn(withControls.ctx) - const served = stubAgent(ctx, 'served', scopeOf(withControls.ctx)) - const unserved = stubAgent(ctx, 'unserved', scopeOf(withoutControls.ctx)) - ctx.agents.register(served) - ctx.agents.register(unserved) + const served = liveAgent(ctx, 'served', scopeOf(withControls.ctx)) + const unserved = liveAgent(ctx, 'unserved', scopeOf(withoutControls.ctx)) expect(() => ctx.jobs.start(producer({ owner: served }).spec)).not.toThrow() expect(() => ctx.jobs.start(producer({ owner: unserved }).spec)) @@ -166,8 +202,7 @@ describe('LocalJobRegistry.start', () => { // The host-plane composition's own controls: no scope, so the global layer // holds them and every owner's read includes it. await attachControllerIn(ctx) - const scoped = stubAgent(ctx, 'scoped', scopeOf(createScope(ctx, {}).ctx)) - ctx.agents.register(scoped) + const scoped = liveAgent(ctx, 'scoped', scopeOf(createScope(ctx, {}).ctx)) expect(() => ctx.jobs.start(producer({ owner: scoped }).spec)).not.toThrow() expect(() => ctx.jobs.start(producer().spec)).not.toThrow() @@ -189,6 +224,11 @@ describe('LocalJobRegistry.start', () => { }, ) + it('rejects a non-positive pump interval', async () => { + const ctx = new Context() + await expect(ctx.plugin(LocalJobRegistry, { pumpPollMs: 0 })).rejects.toThrow() + }) + it('accepts the largest safe integer limit', async () => { const ctx = await harness({ maxConcurrentJobsPerOwner: Number.MAX_SAFE_INTEGER }) expect(ctx.jobs).toBeInstanceOf(LocalJobRegistry) @@ -200,7 +240,7 @@ describe('LocalJobRegistry.start', () => { for (const job of live) ctx.jobs.start(job.spec) const blocked = producer() - const run = vi.fn((job: RecordingJob) => blocked.spec.run(job)) + const run = vi.fn((job: JobHandle) => blocked.spec.run(job)) expect(() => ctx.jobs.start({ ...blocked.spec, run })) .toThrow('background job limit reached for this owner (limit: 10)') expect(run).not.toHaveBeenCalled() @@ -213,7 +253,7 @@ describe('LocalJobRegistry.start', () => { expect(ctx.jobs.start(first.spec)).toBe('bash-1') const blocked = producer() - const run = vi.fn((job: RecordingJob) => blocked.spec.run(job)) + const run = vi.fn((job: JobHandle) => blocked.spec.run(job)) expect(() => ctx.jobs.start({ ...blocked.spec, run })) .toThrow('use job_kill to stop an unneeded job, wait for it to finish, then retry') expect(run).not.toHaveBeenCalled() @@ -227,7 +267,7 @@ describe('LocalJobRegistry.start', () => { const ctx = await harness({ maxConcurrentJobsPerOwner: 1 }) const first = producer() const id = ctx.jobs.start(first.spec) - expect(ctx.jobs.kill(id)).toBe('requested') + expect(jobsOf(ctx).kill(id)).toBe('requested') const replacement = producer() expect(() => ctx.jobs.start(replacement.spec)).toThrow('(limit: 1)') @@ -249,17 +289,18 @@ describe('LocalJobRegistry.start', () => { }, ) - it('isolates exact owners, replacement objects with the same session id, and the unowned bucket', async () => { + it('buckets by exact owner: a same-session replacement and the unowned bucket count separately', async () => { const ctx = await harness({ maxConcurrentJobsPerOwner: 1 }) const oldOwner = stubAgent(ctx, 'shared-session') const detachOld = ctx.agents.register(oldOwner) const oldTask = producer({ owner: oldOwner }) ctx.jobs.start(oldTask.spec) - const otherOwner = stubAgent(ctx, 'other-session') - ctx.agents.register(otherOwner) - expect(() => ctx.jobs.start(producer({ owner: otherOwner }).spec)).not.toThrow() + liveAgent(ctx, 'other-session') + expect(() => ctx.jobs.start({ ...producer().spec, owner: SessionId('other-session') })).not.toThrow() + // The session id resolves to whichever agent is live now; a replacement + // instance starts with its own bucket even while the old job runs on. detachOld() const replacement = stubAgent(ctx, 'shared-session') ctx.agents.register(replacement) @@ -267,8 +308,6 @@ describe('LocalJobRegistry.start', () => { ctx.jobs.start(producer().spec) expect(() => ctx.jobs.start(producer().spec)).toThrow('(limit: 1)') - expect(() => ctx.jobs.start(producer({ owner: oldOwner }).spec)) - .toThrow('is not the registered agent instance') oldTask.settle({ status: 'completed' }) await tick() @@ -285,94 +324,81 @@ describe('LocalJobRegistry.start', () => { }) describe('LocalJobRegistry reads and settlement', () => { - it('stream kinds read a consuming delta; terminal reads mark reported', async () => { + it('read consumes the ring from the model cursor and advances it; readAt never moves it', async () => { const ctx = await harness() - const chunks = ['first', '', 'rest'] - const p = producer({ readOutput: () => chunks.shift() ?? '' }) + const p = producer() const id = ctx.jobs.start(p.spec) + const jobs = jobsOf(ctx) + p.job().append('first', { channel: 'stdout' }) + p.job().append('err', { channel: 'stderr' }) - expect(ctx.jobs.read(id)).toMatchObject({ text: 'first', snapshot: { status: 'running', reported: false } }) - expect(ctx.jobs.read(id).text).toBe('') + const first = jobs.read(id) + expect(first.chunks).toEqual([{ at: 0, text: 'first', channel: 'stdout' }, { at: 5, text: 'err', channel: 'stderr' }]) + expect(first.lossy).toBe(false) + expect(first.result).toBeUndefined() + expect(first.job).toMatchObject({ status: 'running', output: { total: 8, earliest: 0 } }) + expect(jobs.read(id).chunks).toEqual([]) - p.settle({ status: 'completed', detail: 'exit code: 0' }) - await tick() - const read = ctx.jobs.read(id) - expect(read.text).toBe('rest') - expect(read.snapshot).toMatchObject({ status: 'completed', detail: 'exit code: 0', reported: true }) - expect(read.snapshot.finishedAt).toBeTypeOf('number') + // A non-consuming read from the head sees everything again, and leaves the cursor alone. + expect(jobs.readAt(id, 0).chunks).toHaveLength(2) + p.job().append('rest') + expect(jobs.read(id).chunks).toEqual([{ at: 8, text: 'rest' }]) }) - it('projects a producer-owned model output limit into reads and snapshots', async () => { - const ctx = await harness() - const p = producer({ outputLimitBytes: 64, readOutput: () => 'delta' }) - const id = ctx.jobs.start(p.spec) - expect(ctx.jobs.read(id)).toMatchObject({ - text: 'delta', snapshot: { outputLimitBytes: 64 }, - }) - expect(ctx.jobs.get(id)).toMatchObject({ outputLimitBytes: 64 }) - }) - - it('final-output kinds read empty while live, the outcome output idempotently once settled', async () => { + it('hands the producer result out once, on the first read after settlement', async () => { const ctx = await harness() const p = producer({ kind: 'subagent', label: 'research job' }) const id = ctx.jobs.start(p.spec) + const jobs = jobsOf(ctx) + expect(jobs.read(id)).toMatchObject({ chunks: [], job: { status: 'running' } }) - expect(ctx.jobs.read(id)).toMatchObject({ text: '', snapshot: { status: 'running' } }) - - p.settle({ status: 'completed', output: 'final answer' }) + p.settle({ status: 'completed', result: 'final answer' }) await tick() - expect(ctx.jobs.read(id).text).toBe('final answer') - expect(ctx.jobs.read(id).text).toBe('final answer') // idempotent, not consumed + const read = jobs.read(id) + expect(read.result).toBe('final answer') + expect(read.job).toMatchObject({ status: 'completed' }) + expect(read.job.finishedAt).toBeTypeOf('number') + expect(jobs.read(id).result).toBeUndefined() }) - it('a settled job without output reads as empty text', async () => { + it('a settled job without a result reads as empty', async () => { const ctx = await harness() const p = producer({ kind: 'subagent' }) const id = ctx.jobs.start(p.spec) p.settle({ status: 'failed', detail: 'max-tokens' }) await tick() - expect(ctx.jobs.read(id)).toMatchObject({ text: '', snapshot: { status: 'failed', detail: 'max-tokens' } }) + expect(jobsOf(ctx).read(id)).toMatchObject({ chunks: [], job: { status: 'failed', detail: 'max-tokens' } }) + }) + + it('projects a producer-owned model output limit into views', async () => { + const ctx = await harness() + const p = producer({ outputLimitBytes: 64 }) + const id = ctx.jobs.start(p.spec) + expect(jobsOf(ctx).get(id)).toMatchObject({ outputLimitBytes: 64 }) + expect(jobsOf(ctx).read(id).job).toMatchObject({ outputLimitBytes: 64 }) }) it('throws for unknown job ids', async () => { const ctx = await harness() - expect(() => ctx.jobs.read(JobId('bash-99'))).toThrow('unknown job bash-99') + expect(() => jobsOf(ctx).read(JobId('bash-99'))).toThrow('unknown job bash-99') + expect(() => jobsOf(ctx).get(JobId('bash-99'))).toThrow('unknown job bash-99') }) - it('notifies onJobDone once per job with containment across listeners', async () => { + it('announces settlement once with containment across listeners', async () => { const ctx = await harness() const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {}) - const seen: JobSnapshot[] = [] - ctx.jobs.onJobDone(() => { throw new Error('listener boom') }) - ctx.jobs.onJobDone(snapshot => void seen.push(snapshot)) + ctx.jobs.events.subscribe({ owners: 'all' }, () => { throw new Error('listener boom') }) + const seen = collect(ctx, { owners: 'all' }, ['settled']) const p = producer() const id = ctx.jobs.start(p.spec) p.settle({ status: 'completed', detail: 'exit code: 0' }) await tick() - expect(seen).toHaveLength(1) - expect(seen[0]).toMatchObject({ id, status: 'completed', reported: false }) + expect(seen).toEqual([{ type: 'settled', cause: 'producer', job: expect.objectContaining({ id, status: 'completed', detail: 'exit code: 0' }) }]) expect(warn).toHaveBeenCalledWith(expect.stringContaining('listener boom')) }) - it('contains a rejecting onJobDone listener without starving later listeners', async () => { - const ctx = await harness() - const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {}) - const seen: JobId[] = [] - ctx.jobs.onJobDone(async () => { throw new Error('async listener boom') }) - ctx.jobs.onJobDone(snapshot => void seen.push(snapshot.id)) - - const p = producer() - const id = ctx.jobs.start(p.spec) - p.settle({ status: 'completed' }) - await tick() - - expect(seen).toEqual([id]) - expect(warn).toHaveBeenCalledWith(expect.stringContaining('onJobDone listener rejected')) - expect(warn).toHaveBeenCalledWith(expect.stringContaining('async listener boom')) - }) - it("contains rejection from the producer's done promise as a failed outcome (producer contract violation)", async () => { const ctx = await harness() const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {}) @@ -381,19 +407,19 @@ describe('LocalJobRegistry reads and settlement', () => { p.reject(new Error('transport exploded')) await tick() - expect(ctx.jobs.read(id).snapshot).toMatchObject({ status: 'failed', detail: 'Error: transport exploded' }) + expect(jobsOf(ctx).get(id)).toMatchObject({ status: 'failed', detail: 'Error: transport exploded' }) expect(warn).toHaveBeenCalledWith(expect.stringContaining('producer contract violation')) }) - it('unregisters onJobDone listeners with the contributing fiber (HMR safety)', async () => { + it('unregisters event listeners with the contributing fiber (HMR safety)', async () => { const ctx = await harness() const seen: string[] = [] const fiber = await ctx.plugin(Object.assign((inner: Context) => { - inner.jobs.onJobDone(snapshot => void seen.push(snapshot.id)) + inner.jobs.events.subscribe({ owners: 'all' }, event => void seen.push(event.type)) }, { inject: ['jobs'] })) await fiber.dispose() // The returned disposer detaches too (the non-fiber path). - const detach = ctx.jobs.onJobDone(snapshot => void seen.push(snapshot.id)) + const detach = ctx.jobs.events.subscribe({ owners: 'all' }, event => void seen.push(event.type)) detach() const p = producer() @@ -405,22 +431,39 @@ describe('LocalJobRegistry reads and settlement', () => { }) describe('LocalJobRegistry.kill', () => { - it('cancels a live job with the forwarded reason and suppresses the notice', async () => { + it('cancels a live job with the forwarded reason and settles with cause kill', async () => { const ctx = await harness() - const seen: JobSnapshot[] = [] - ctx.jobs.onJobDone(snapshot => void seen.push(snapshot)) + const seen = collect(ctx, { owners: 'all' }, ['stopping', 'settled']) const p = producer() const id = ctx.jobs.start(p.spec) - expect(ctx.jobs.kill(id, undefined, 'no longer needed')).toBe('requested') + expect(jobsOf(ctx).kill(id, { reason: 'no longer needed' })).toBe('requested') expect(p.cancels).toEqual(['no longer needed']) - expect(ctx.jobs.list()[0]).toMatchObject({ status: 'stopping', reported: true }) + expect(jobsOf(ctx).list()[0]).toMatchObject({ status: 'stopping' }) + expect(seen).toEqual([{ type: 'stopping', job: expect.objectContaining({ id, status: 'stopping' }) }]) - p.settle({ status: 'killed' }) + p.settle({ status: 'killed', detail: 'signal: SIGTERM' }) await tick() - // The listener still fires (telemetry may care), but carries reported: true - // so the notice path suppresses its redundant "finished". - expect(seen[0]).toMatchObject({ id, status: 'killed', reported: true }) + expect(seen[1]).toEqual({ + type: 'settled', + cause: 'kill', + job: expect.objectContaining({ id, status: 'killed', detail: 'signal: SIGTERM; no longer needed' }), + }) + }) + + it('merges a reason without producer detail and keeps producer detail alone when the job outran the kill', async () => { + const ctx = await harness() + const killed = producer() + const killedId = ctx.jobs.start(killed.spec) + jobsOf(ctx).kill(killedId, { reason: 'cancelled by the user' }) + killed.settle({ status: 'killed' }) + const outran = producer() + const outranId = ctx.jobs.start(outran.spec) + jobsOf(ctx).kill(outranId, { reason: 'too late' }) + outran.settle({ status: 'completed', detail: 'exit code: 0' }) + await tick() + expect(jobsOf(ctx).get(killedId).detail).toBe('cancelled by the user') + expect(jobsOf(ctx).get(outranId).detail).toBe('exit code: 0') }) it('reports an already-finished job instead of failing', async () => { @@ -429,13 +472,12 @@ describe('LocalJobRegistry.kill', () => { const id = ctx.jobs.start(p.spec) p.settle({ status: 'completed' }) await tick() - expect(ctx.jobs.kill(id)).toBe('already-finished') + expect(jobsOf(ctx).kill(id)).toBe('already-finished') }) it('propagates a throwing producer cancel and leaves the job untouched', async () => { const ctx = await harness() - const seen: JobSnapshot[] = [] - ctx.jobs.onJobDone(snapshot => void seen.push(snapshot)) + const seen = collect(ctx, { owners: 'all' }, ['stopping', 'settled']) let broken = true let settle!: (outcome: JobOutcome) => void const id = ctx.jobs.start({ @@ -446,38 +488,41 @@ describe('LocalJobRegistry.kill', () => { done: new Promise((res) => { settle = res }), }), }) - expect(() => ctx.jobs.kill(id)).toThrow('cancel boom') - // The failed kill mutated NOTHING: still running, notice not suppressed, - // and a later (successful) kill still works. - expect(ctx.jobs.get(id)).toMatchObject({ status: 'running', reported: false }) + expect(() => jobsOf(ctx).kill(id)).toThrow('cancel boom') + // The failed kill mutated NOTHING: still running, and the settlement + // still reports the producer as its cause. + expect(jobsOf(ctx).get(id)).toMatchObject({ status: 'running' }) + expect(seen).toEqual([]) settle({ status: 'completed' }) await tick() - expect(seen[0]).toMatchObject({ id, reported: false }) // notice would still fire + expect(seen).toEqual([{ type: 'settled', cause: 'producer', job: expect.objectContaining({ id }) }]) broken = false - expect(ctx.jobs.kill(id)).toBe('already-finished') + expect(jobsOf(ctx).kill(id)).toBe('already-finished') }) }) describe('LocalJobRegistry.wait', () => { - it('resolves with the terminal snapshot when the job settles, marked reported', async () => { + it('resolves with the terminal projection when the job settles, before the settled event', async () => { const ctx = await harness() - const seen: JobSnapshot[] = [] - ctx.jobs.onJobDone(snapshot => void seen.push(snapshot)) + const order: string[] = [] + ctx.jobs.events.subscribe({ owners: 'all' }, (event) => { if (event.type === 'settled') order.push('event') }) const p = producer() const id = ctx.jobs.start(p.spec) - const wait = ctx.jobs.wait(id, 5_000) + const wait = jobsOf(ctx).wait(id, 5_000).then((view) => { order.push('wait'); return view }) p.settle({ status: 'completed', detail: 'exit code: 0' }) - expect(await wait).toMatchObject({ status: 'completed', reported: true }) - // A waiting reader claims delivery before completion listeners inspect the snapshot. - expect(seen[0]).toMatchObject({ id, reported: true }) + expect(await wait).toMatchObject({ status: 'completed' }) + // Waiters are released synchronously inside the settlement, ahead of the + // event; their continuations run afterwards, which is why a claim made + // when the wait starts (not when it returns) is what stays ordered. + expect(order).toEqual(['event', 'wait']) }) - it('returns the live snapshot on timeout without marking reported', async () => { + it('returns the live projection on timeout', async () => { const ctx = await harness() const id = ctx.jobs.start(producer().spec) - expect(await ctx.jobs.wait(id, 5)).toMatchObject({ status: 'running', reported: false }) + expect(await jobsOf(ctx).wait(id, 5)).toMatchObject({ status: 'running' }) }) it('unregisters timed-out and aborted wait resolvers while the job remains live', async () => { @@ -485,19 +530,19 @@ describe('LocalJobRegistry.wait', () => { const id = ctx.jobs.start(producer().spec) for (let index = 0; index < 3; index += 1) { - const wait = ctx.jobs.wait(id, 5) + const wait = jobsOf(ctx).wait(id, 5) expect(waitResolverCount(ctx, id)).toBe(1) await expect(wait).resolves.toMatchObject({ status: 'running' }) expect(waitResolverCount(ctx, id)).toBe(0) } const controller = new AbortController() - const wait = ctx.jobs.wait(id, 5_000, undefined, controller.signal) + const wait = jobsOf(ctx).wait(id, 5_000, controller.signal) expect(waitResolverCount(ctx, id)).toBe(1) controller.abort() await expect(wait).rejects.toThrow('wait aborted') expect(waitResolverCount(ctx, id)).toBe(0) - expect(ctx.jobs.get(id).status).toBe('running') + expect(jobsOf(ctx).get(id).status).toBe('running') }) it('returns immediately for an already-finished job', async () => { @@ -506,14 +551,14 @@ describe('LocalJobRegistry.wait', () => { const id = ctx.jobs.start(p.spec) p.settle({ status: 'completed' }) await tick() - expect(await ctx.jobs.wait(id, 5_000)).toMatchObject({ status: 'completed', reported: true }) + expect(await jobsOf(ctx).wait(id, 5_000)).toMatchObject({ status: 'completed' }) }) it('rejects a non-positive or non-finite timeout', async () => { const ctx = await harness() const id = ctx.jobs.start(producer().spec) - await expect(ctx.jobs.wait(id, 0)).rejects.toThrow('invalid wait timeout') - await expect(ctx.jobs.wait(id, Number.NaN)).rejects.toThrow('invalid wait timeout') + await expect(jobsOf(ctx).wait(id, 0)).rejects.toThrow('invalid wait timeout') + await expect(jobsOf(ctx).wait(id, Number.NaN)).rejects.toThrow('invalid wait timeout') }) it('an aborted signal rejects the wait only — the job stays alive', async () => { @@ -521,120 +566,111 @@ describe('LocalJobRegistry.wait', () => { const id = ctx.jobs.start(producer().spec) const controller = new AbortController() - const wait = ctx.jobs.wait(id, 5_000, undefined, controller.signal) + const wait = jobsOf(ctx).wait(id, 5_000, controller.signal) controller.abort() await expect(wait).rejects.toThrow('wait aborted') - expect(ctx.jobs.list()[0]).toMatchObject({ status: 'running' }) + expect(jobsOf(ctx).list()[0]).toMatchObject({ status: 'running' }) const preAborted = new AbortController() preAborted.abort() - await expect(ctx.jobs.wait(id, 5_000, undefined, preAborted.signal)).rejects.toThrow('wait aborted') + await expect(jobsOf(ctx).wait(id, 5_000, preAborted.signal)).rejects.toThrow('wait aborted') }) - it('an abort racing settlement in the same tick does not swallow the notice', async () => { + it('an abort racing settlement in the same tick rejects the wait and leaves the settlement intact', async () => { const ctx = await harness() - const seen: JobSnapshot[] = [] - ctx.jobs.onJobDone(snapshot => void seen.push(snapshot)) + const seen = collect(ctx, { owners: 'all' }, ['settled']) const p = producer() const id = ctx.jobs.start(p.spec) const controller = new AbortController() - const wait = ctx.jobs.wait(id, 5_000, undefined, controller.signal) - // Settlement is queued first, so abort must remove the waiter synchronously; - // otherwise settlement suppresses the notice for a reader that receives nothing. + const wait = jobsOf(ctx).wait(id, 5_000, controller.signal) p.settle({ status: 'completed', detail: 'exit code: 0' }) controller.abort() await expect(wait).rejects.toThrow('wait aborted') - expect(seen).toHaveLength(1) - expect(seen[0]).toMatchObject({ id, status: 'completed', reported: false }) + expect(seen).toEqual([{ type: 'settled', cause: 'producer', job: expect.objectContaining({ id, status: 'completed' }) }]) }) - it('an abort landing after settlement still delivers the terminal snapshot it owes', async () => { + it('an abort landing after settlement still delivers the terminal projection it owes', async () => { const ctx = await harness() const controller = new AbortController() - const seen: JobSnapshot[] = [] // The listener aborts after settlement released this waiter but before its // resolve microtask runs. Releasing waiters ahead of the announcement is // what makes that abort harmless; this is the guard on that ordering. - ctx.jobs.onJobDone((snapshot) => { - seen.push(snapshot) - controller.abort() - }) + ctx.jobs.events.subscribe({ owners: 'all' }, (event) => { if (event.type === 'settled') controller.abort() }) const p = producer() const id = ctx.jobs.start(p.spec) - const wait = ctx.jobs.wait(id, 5_000, undefined, controller.signal) + const wait = jobsOf(ctx).wait(id, 5_000, controller.signal) p.settle({ status: 'completed', detail: 'exit code: 0' }) - await expect(wait).resolves.toMatchObject({ status: 'completed', reported: true }) - expect(seen[0]).toMatchObject({ id, reported: true }) // suppression stays honest: the wait delivered + await expect(wait).resolves.toMatchObject({ status: 'completed' }) }) }) describe('LocalJobRegistry owner isolation', () => { - it('fences read/kill/wait to the owning session and keeps unowned jobs open', async () => { + it('fences every view operation to the owning session and keeps unowned jobs open', async () => { const ctx = await harness() - const owner = stubAgent(ctx, 'owner') - ctx.agents.register(owner) + const owner = liveAgent(ctx, 'owner') const other = stubAgent(ctx, 'other') const owned = ctx.jobs.start(producer({ owner }).spec) const open = ctx.jobs.start(producer().spec) // The owner and the unowned job are reachable. - expect(ctx.jobs.read(owned, owner).snapshot.id).toBe(owned) - expect(ctx.jobs.read(open, other).snapshot.id).toBe(open) + expect(jobsOf(ctx, owner).read(owned).job.id).toBe(owned) + expect(jobsOf(ctx, other).read(open).job.id).toBe(open) - // A different session and a no-agent caller are rejected. - expect(() => ctx.jobs.read(owned, other)).toThrow(`job ${owned} belongs to another session`) - expect(() => ctx.jobs.kill(owned, other)).toThrow('belongs to another session') - await expect(ctx.jobs.wait(owned, 10, other)).rejects.toThrow('belongs to another session') - expect(() => ctx.jobs.read(owned)).toThrow('belongs to another session') + // A different session and an anonymous caller are rejected. + const foreign = jobsOf(ctx, other) + expect(() => foreign.read(owned)).toThrow(`job ${owned} belongs to another session`) + expect(() => foreign.get(owned)).toThrow('belongs to another session') + expect(() => foreign.readAt(owned, 0)).toThrow('belongs to another session') + expect(() => foreign.kill(owned)).toThrow('belongs to another session') + await expect(foreign.wait(owned, 10)).rejects.toThrow('belongs to another session') + expect(() => jobsOf(ctx).read(owned)).toThrow('belongs to another session') }) it('list() shows only caller-owned plus unowned jobs', async () => { const ctx = await harness() - const alice = stubAgent(ctx, 'alice') - const bob = stubAgent(ctx, 'bob') - ctx.agents.register(alice) - ctx.agents.register(bob) + const alice = liveAgent(ctx, 'alice') + const bob = liveAgent(ctx, 'bob') const aliceTask = ctx.jobs.start(producer({ owner: alice }).spec) const bobTask = ctx.jobs.start(producer({ owner: bob }).spec) const openTask = ctx.jobs.start(producer({ kind: 'subagent' }).spec) - expect(ctx.jobs.list(alice).map(t => t.id)).toEqual([aliceTask, openTask]) - expect(ctx.jobs.list(bob).map(t => t.id)).toEqual([bobTask, openTask]) - expect(ctx.jobs.list().map(t => t.id)).toEqual([openTask]) + expect(jobsOf(ctx, alice).list().map(t => t.id)).toEqual([aliceTask, openTask]) + expect(jobsOf(ctx, bob).list().map(t => t.id)).toEqual([bobTask, openTask]) + expect(jobsOf(ctx).list().map(t => t.id)).toEqual([openTask]) }) it('rejects an owned registration when no agent registry is mounted', async () => { const ctx = new Context() await ctx.plugin(LocalJobRegistry) ctx.jobs.attachController('test-controller') - expect(() => ctx.jobs.start(producer({ owner: stubAgent(ctx, 'a') }).spec)) + expect(() => ctx.jobs.start({ ...producer().spec, owner: SessionId('a') })) .toThrow('background job ownership requires the agent registry') // The failed registration mutated nothing: no stored job, counter untouched. - expect(ctx.jobs.list()).toEqual([]) + expect(jobsOf(ctx).list()).toEqual([]) expect(ctx.jobs.start(producer().spec)).toBe('bash-1') }) - it('a failed owner-cleanup attach leaves the registry unchanged and does not poison the owner', async () => { + it('rejects a session without a live agent and attaches cleanup once it has one', async () => { const ctx = await harness() const ghost = stubAgent(ctx, 'ghost') // never registered in ctx.agents - // Exact-instance validation precedes registry mutation and cleanup attachment. + // Owner resolution precedes registry mutation and cleanup attachment. expect(() => ctx.jobs.start(producer({ owner: ghost }).spec)) - .toThrow('is not the registered agent instance') - expect(ctx.jobs.list(ghost)).toEqual([]) + .toThrow('has no live agent') + expect(jobsOf(ctx, ghost).list()).toEqual([]) - // A later valid registration must still attach cleanup for the same object. + // A later valid registration must still attach cleanup for the live instance. ctx.agents.register(ghost) const cancels: (string | undefined)[] = [] let settle!: (outcome: JobOutcome) => void const id = ctx.jobs.start({ kind: 'bash', label: 'after retry', - owner: ghost, + owner: ghost.id, run: () => ({ cancel(reason) { cancels.push(reason); settle({ status: 'killed' }) }, done: new Promise((res) => { settle = res }), @@ -643,42 +679,37 @@ describe('LocalJobRegistry owner isolation', () => { expect(id).toBe('bash-1') // the failed attempt burned no counter await disposeAgentScope(ghost) expect(cancels).toEqual(['owner disposed']) - expect(ctx.jobs.list(ghost)).toEqual([]) + expect(jobsOf(ctx, ghost).list()).toEqual([]) }) - it('rejects a stale owner instance after another agent reuses its id', async () => { + it('binds a session id to the agent that is live now, and reads stay keyed by that id', async () => { const ctx = await harness() const staleOwner = stubAgent(ctx, 'owner') const unregisterStale = ctx.agents.register(staleOwner) unregisterStale() - const currentOwner = stubAgent(ctx, 'owner') ctx.agents.register(currentOwner) - const current = producer({ owner: currentOwner }) - ctx.jobs.start(current.spec) // Attach the current owner's cleanup first. - const stale = producer({ owner: staleOwner }) - const staleRun = vi.fn((job: RecordingJob) => stale.spec.run(job)) - expect(() => ctx.jobs.start({ ...stale.spec, run: staleRun })) - .toThrow('is not the registered agent instance') - expect(staleRun).not.toHaveBeenCalled() - // Access is keyed by the unified session id, so a reconnect carrying the - // same identity can observe the current job even though stale ownership - // registration is rejected by exact-instance validation. - expect(ctx.jobs.list(staleOwner)).toHaveLength(1) - expect(ctx.jobs.list(currentOwner)).toHaveLength(1) + const current = producer({ owner: currentOwner }) + const id = ctx.jobs.start(current.spec) + // The stale instance shares the id, so the fence lets it read; ownership + // (and therefore teardown) belongs to the live instance. + expect(jobsOf(ctx, staleOwner).get(id).owner).toBe(currentOwner.id) + await disposeAgentScope(staleOwner) + expect(jobsOf(ctx, currentOwner).list()).toHaveLength(1) current.settle({ status: 'completed' }) await tick() await disposeAgentScope(currentOwner) + expect(jobsOf(ctx, currentOwner).list()).toEqual([]) }) }) describe('LocalJobRegistry owner cleanup', () => { - it('drains the owner: cancels live jobs, awaits settlement, drops snapshots', async () => { + it('drains the owner: cancels live jobs, awaits settlement, removes the rows', async () => { const ctx = await harness() - const owner = stubAgent(ctx, 'owner') - ctx.agents.register(owner) + const owner = liveAgent(ctx, 'owner') + const seen = collect(ctx, { owner: owner.id }, ['removed']) // The producer settles only when cancelled — models a child that stops on request. let settle!: (outcome: JobOutcome) => void @@ -686,7 +717,7 @@ describe('LocalJobRegistry owner cleanup', () => { ctx.jobs.start({ kind: 'subagent', label: 'long research', - owner, + owner: owner.id, run: () => ({ cancel(reason) { cancels.push(reason); settle({ status: 'killed' }) }, done: new Promise((res) => { settle = res }), @@ -699,59 +730,33 @@ describe('LocalJobRegistry owner cleanup', () => { await disposeAgentScope(owner) expect(cancels).toEqual(['owner disposed']) - // Snapshots dropped: nothing of the owner's remains, listing is empty. - expect(ctx.jobs.list(owner)).toEqual([]) + expect(jobsOf(ctx, owner).list()).toEqual([]) + expect(seen.map(event => event.type === 'removed' ? event.job.id : undefined)).toEqual(['subagent-1', 'bash-1']) }) - it('publishes the settled visible set before announcing completion', async () => { + it('announces teardown settlements with cause teardown', async () => { const ctx = await harness() - const owner = stubAgent(ctx, 'owner') - ctx.agents.register(owner) - const p = producer({ owner }) - ctx.jobs.start(p.spec) - // Registered after start so only the settlement's notifications are ordered. - const order: string[] = [] - ctx.jobs.onJobsChanged(() => void order.push('changed')) - ctx.jobs.onJobDone(() => void order.push('done')) - - p.settle({ status: 'completed' }) - await tick() - - // A completion reporter may open a turn synchronously. Announcing before - // the visible set is published would let a client render that turn while - // its job row still reads `running`. - expect(order).toEqual(['changed', 'done']) - }) - - it('reports a teardown-cancelled record so completion reporters stay quiet', async () => { - const ctx = await harness() - const owner = stubAgent(ctx, 'owner') - ctx.agents.register(owner) - const seen: JobSnapshot[] = [] - ctx.jobs.onJobDone(snapshot => void seen.push(snapshot)) + const owner = liveAgent(ctx, 'owner') + const seen = collect(ctx, { owners: 'all' }, ['settled']) let settle!: (outcome: JobOutcome) => void ctx.jobs.start({ kind: 'subagent', label: 'long research', - owner, + owner: owner.id, run: () => ({ cancel() { settle({ status: 'killed' }) }, done: new Promise((res) => { settle = res }), }), }) - // Observers still receive the terminal record; the report bit is what - // keeps a notice reporter from addressing an owner being destroyed. await disposeAgentScope(owner) - expect(seen).toHaveLength(1) - expect(seen[0]?.reported).toBe(true) + expect(seen).toEqual([{ type: 'settled', cause: 'teardown', job: expect.objectContaining({ status: 'killed' }) }]) }) it('attaches one cleanup per owner and drains all owned jobs with the scope', async () => { const ctx = await harness() - const owner = stubAgent(ctx, 'owner') - ctx.agents.register(owner) + const owner = liveAgent(ctx, 'owner') const first = producer({ owner }) const second = producer({ owner }) @@ -762,21 +767,21 @@ describe('LocalJobRegistry owner cleanup', () => { await tick() expect(owner.ctx.fiber.getEffects().filter(effect => effect.label === 'jobs.ownerCleanup()')).toHaveLength(1) await disposeAgentScope(owner) - expect(ctx.jobs.list(owner)).toEqual([]) + expect(jobsOf(ctx, owner).list()).toEqual([]) }) - it('does not let an old scope cleanup cancel a same-id/session replacement job', async () => { + it('does not let an old scope cleanup cancel a same-session replacement job', async () => { const ctx = await harness() const oldOwner = stubAgent(ctx, 'owner') const detachOld = ctx.agents.register(oldOwner) const cancels: string[] = [] - function start(owner: Agent, label: string): JobId { + function start(label: string): JobId { let settle!: (outcome: JobOutcome) => void return ctx.jobs.start({ kind: 'bash', label, - owner, + owner: SessionId('owner'), run: () => ({ cancel() { cancels.push(label); settle({ status: 'killed' }) }, done: new Promise((resolve) => { settle = resolve }), @@ -784,15 +789,15 @@ describe('LocalJobRegistry owner cleanup', () => { }) } - start(oldOwner, 'old job') + start('old job') detachOld() const replacement = stubAgent(ctx, 'owner') ctx.agents.register(replacement) - const replacementId = start(replacement, 'replacement job') + const replacementId = start('replacement job') await disposeAgentScope(oldOwner) expect(cancels).toEqual(['old job']) - expect(ctx.jobs.list(replacement).map(job => job.id)).toEqual([replacementId]) + expect(jobsOf(ctx, replacement).list().map(job => job.id)).toEqual([replacementId]) await disposeAgentScope(replacement) expect(cancels).toEqual(['old job', 'replacement job']) @@ -803,8 +808,7 @@ describe('LocalJobRegistry owner cleanup', () => { await ctx.plugin(AgentRegistry) const tasksFiber = await ctx.plugin(LocalJobRegistry) ctx.jobs.attachController('test-controller') - const owner = stubAgent(ctx, 'owner') - ctx.agents.register(owner) + const owner = liveAgent(ctx, 'owner') const ownerCleanupEffects = () => owner.ctx.fiber.getEffects() .filter(effect => effect.label === 'jobs.ownerCleanup()') @@ -821,22 +825,19 @@ describe('LocalJobRegistry owner cleanup', () => { expect(ownerCleanupEffects()).toHaveLength(0) expect(ctx.get('jobs')).toBeDefined() expect(tasksFiber.getEffects().some(effect => effect.label === 'jobs teardown')).toBe(true) - }) it('force-fails a throwing teardown cancel without awaiting producer done, first outcome wins', async () => { const ctx = await harness() const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {}) - const owner = stubAgent(ctx, 'owner') - ctx.agents.register(owner) - const seen: JobSnapshot[] = [] - ctx.jobs.onJobDone(snapshot => void seen.push(snapshot)) + const owner = liveAgent(ctx, 'owner') + const seen = collect(ctx, { owners: 'all' }, ['settled']) let settle!: (outcome: JobOutcome) => void ctx.jobs.start({ kind: 'bash', label: 'broken producer', - owner, + owner: owner.id, run: () => ({ cancel() { throw new Error('cancel boom') }, done: new Promise((res) => { settle = res }), @@ -861,24 +862,27 @@ describe('LocalJobRegistry owner cleanup', () => { expect(drainedWithoutProducerDone).toBe(true) expect(warn).toHaveBeenCalledWith(expect.stringContaining('work may be orphaned')) expect(seen).toHaveLength(1) - expect(seen[0]?.status).toBe('failed') - expect(seen[0]?.detail).toContain('cancel threw during teardown') - expect(ctx.jobs.list(owner)).toEqual([]) + expect(seen[0]).toMatchObject({ cause: 'teardown', job: { status: 'failed' } }) + expect((seen[0] as { job: JobView }).job.detail).toContain('cancel threw during teardown') + expect(jobsOf(ctx, owner).list()).toEqual([]) }) }) describe('LocalJobRegistry disposal', () => { - it('cancels live jobs, awaits settlement, and silences listeners', async () => { + it('cancels live jobs, awaits settlement, and announces the teardown to outside subscribers', async () => { const ctx = new Context() await ctx.plugin(AgentRegistry) const fiber = await ctx.plugin(LocalJobRegistry) - const controller = await ctx.plugin(Object.assign((inner: Context) => { + await ctx.plugin(Object.assign((inner: Context) => { inner.jobs.attachController('test-controller') }, { inject: ['jobs'] })) - void controller + // A subscriber outside the registry's fiber is still listening when the + // registry unloads: it must see the rows leave, not keep them forever. const seen: string[] = [] - ctx.jobs.onJobDone(snapshot => void seen.push(snapshot.id)) + ctx.jobs.events.subscribe({ owners: 'all' }, (event) => { + seen.push(event.type === 'settled' ? `settled:${event.cause}` : event.type) + }) let settle!: (outcome: JobOutcome) => void const cancels: (string | undefined)[] = [] ctx.jobs.start({ @@ -892,8 +896,7 @@ describe('LocalJobRegistry disposal', () => { await fiber.dispose() expect(cancels).toEqual(['jobs service disposed']) - // The teardown kill settles AFTER the listener registry closed: silent. - expect(seen).toEqual([]) + expect(seen).toEqual(['registered', 'stopping', 'settled:teardown', 'output', 'removed']) }) it('force-fails a throwing cancel so service disposal does not await producer done', async () => { @@ -902,8 +905,7 @@ describe('LocalJobRegistry disposal', () => { const fiber = await ctx.plugin(LocalJobRegistry) ctx.jobs.attachController('test-controller') const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {}) - const seen: JobSnapshot[] = [] - ctx.jobs.onJobDone(snapshot => void seen.push(snapshot)) + const seen = collect(ctx, { owners: 'all' }, ['settled']) let settle!: (outcome: JobOutcome) => void ctx.jobs.start({ @@ -931,7 +933,7 @@ describe('LocalJobRegistry disposal', () => { expect(disposedWithoutProducerDone).toBe(true) expect(warn).toHaveBeenCalledWith(expect.stringContaining('work may be orphaned')) - expect(seen).toEqual([]) + expect(seen).toEqual([{ type: 'settled', cause: 'teardown', job: expect.objectContaining({ status: 'failed' }) }]) }) it('detaches owner effects from still-live agent scopes when the service unloads', async () => { @@ -939,13 +941,12 @@ describe('LocalJobRegistry disposal', () => { await ctx.plugin(AgentRegistry) const tasksFiber = await ctx.plugin(LocalJobRegistry) ctx.jobs.attachController('test-controller') - const owner = stubAgent(ctx, 'owner') - ctx.agents.register(owner) + const owner = liveAgent(ctx, 'owner') let settle!: (outcome: JobOutcome) => void ctx.jobs.start({ kind: 'bash', label: 'owned work', - owner, + owner: owner.id, run: () => ({ cancel() { settle({ status: 'killed' }) }, done: new Promise((resolve) => { settle = resolve }), @@ -971,11 +972,10 @@ describe('LocalJobRegistry disposal', () => { inject: ['jobs'], apply(pluginCtx: Context) { pluginCtx.jobs.attachController('tool-jobs') - pluginCtx.jobs.onJobDone(() => {}) + pluginCtx.jobs.events.subscribe({ owners: 'scope' }, () => {}) }, }) - const owner = stubAgent(ctx, 'joined', scopeOf(standing.ctx)) - ctx.agents.register(owner) + const owner = liveAgent(ctx, 'joined', scopeOf(standing.ctx)) expect(() => ctx.jobs.start(producer({ owner }).spec)).not.toThrow() await mount.dispose() @@ -1003,198 +1003,162 @@ describe('LocalJobRegistry disposal', () => { }) }) -describe('LocalJobRegistry.onJobsChanged', () => { - it('fires after registration, the stopping transition, and settlement', async () => { +describe('LocalJobRegistry events', () => { + it('announces registration, progress, stopping, and settlement with the committed projection', async () => { const ctx = await harness() - const owner = stubAgent(ctx, 'alice') - ctx.agents.register(owner) - const seen: (string | undefined)[] = [] - ctx.jobs.onJobsChanged(changed => void seen.push(changed?.id)) + const owner = liveAgent(ctx, 'alice') + const seen = collect(ctx, { owner: owner.id }, ['registered', 'progress', 'stopping', 'settled']) const p = producer({ owner }) const id = ctx.jobs.start(p.spec) // Registration is announced only once the record is readable. - expect(seen).toEqual(['alice']) - expect(ctx.jobs.list(owner)).toHaveLength(1) + expect(seen).toEqual([{ type: 'registered', job: expect.objectContaining({ id, owner: 'alice', status: 'running' }) }]) + expect(jobsOf(ctx, owner).list()).toHaveLength(1) - expect(ctx.jobs.kill(id, owner)).toBe('requested') - expect(seen).toEqual(['alice', 'alice']) - expect(ctx.jobs.get(id, owner).status).toBe('stopping') + p.job().updateProgress('3/10') + expect(seen[1]).toEqual({ type: 'progress', job: expect.objectContaining({ id, progress: '3/10' }) }) + + expect(jobsOf(ctx, owner).kill(id)).toBe('requested') + expect(seen[2]).toEqual({ type: 'stopping', job: expect.objectContaining({ id, status: 'stopping', progress: '3/10' }) }) p.settle({ status: 'killed' }) await tick() - expect(seen).toEqual(['alice', 'alice', 'alice']) - expect(ctx.jobs.get(id, owner).status).toBe('killed') + const settled = seen[3] as { job: JobView } + expect(seen[3]).toMatchObject({ type: 'settled', cause: 'kill', job: { id, status: 'killed' } }) + expect(settled.job.progress).toBeUndefined() await disposeAgentScope(owner) }) - it('reports an unowned change as undefined, since every caller can see it', async () => { + it('announces an unowned job to every session filter, since every caller can see it', async () => { const ctx = await harness() - const seen: (string | undefined)[] = [] - ctx.jobs.onJobsChanged(changed => void seen.push(changed?.id)) - + const seen = collect(ctx, { owner: SessionId('anyone') }, ['registered']) ctx.jobs.start(producer().spec) - expect(seen).toEqual([undefined]) + expect(seen).toEqual([{ type: 'registered', job: expect.objectContaining({ id: 'bash-1' }) }]) + expect((seen[0] as { job: JobView }).job.owner).toBeUndefined() }) it('announces the owner-disposal removal, and stays silent when that owner had none', async () => { const ctx = await harness() - const owner = stubAgent(ctx, 'alice') - const bystander = stubAgent(ctx, 'bob') - ctx.agents.register(owner) - ctx.agents.register(bystander) + const owner = liveAgent(ctx, 'alice') + const bystander = liveAgent(ctx, 'bob') const p = producer({ owner }) ctx.jobs.start(p.spec) - const seen: (string | undefined)[] = [] - ctx.jobs.onJobsChanged(changed => void seen.push(changed?.id)) + const seen = collect(ctx, { owners: 'all' }, ['settled', 'removed']) p.settle({ status: 'completed' }) await tick() - expect(seen).toEqual(['alice']) + expect(seen.map(event => event.type)).toEqual(['settled']) // Disposing an owner with no records changes no visible set. await disposeAgentScope(bystander) - expect(seen).toEqual(['alice']) + expect(seen.map(event => event.type)).toEqual(['settled']) await disposeAgentScope(owner) - expect(seen).toEqual(['alice', 'alice']) - expect(ctx.jobs.list(owner)).toEqual([]) + expect(seen.map(event => event.type)).toEqual(['settled', 'removed']) + expect(jobsOf(ctx, owner).list()).toEqual([]) }) it('contains a throwing listener so the lifecycle commit still stands', async () => { const ctx = await harness() const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {}) - const seen: (string | undefined)[] = [] - ctx.jobs.onJobsChanged(() => { throw new Error('observer boom') }) - ctx.jobs.onJobsChanged(changed => void seen.push(changed?.id)) + ctx.jobs.events.subscribe({ owners: 'all' }, () => { throw new Error('observer boom') }) + const seen = collect(ctx, { owners: 'all' }, ['registered']) const id = ctx.jobs.start(producer().spec) expect(id).toBe('bash-1') - expect(seen).toEqual([undefined]) - expect(warn).toHaveBeenCalledWith(expect.stringContaining('onJobsChanged listener threw')) + expect(seen).toHaveLength(1) + expect(warn).toHaveBeenCalledWith(expect.stringContaining('event listener threw on registered')) }) - it('unregisters through its disposer and with its fiber (HMR safety)', async () => { - const ctx = await harness() - const seen: number[] = [] - const detach = ctx.jobs.onJobsChanged(() => void seen.push(1)) - const fiber = await ctx.plugin(Object.assign((inner: Context) => { - inner.jobs.onJobsChanged(() => void seen.push(2)) - }, { inject: ['jobs'] })) - - ctx.jobs.start(producer().spec) - expect(seen).toEqual([1, 2]) - - detach() - detach() // second call of the same disposer is a no-op - ctx.jobs.start(producer().spec) - expect(seen).toEqual([1, 2, 2]) - - await fiber.dispose() - ctx.jobs.start(producer().spec) - expect(seen).toEqual([1, 2, 2]) - }) -}) - -describe('LocalJobRegistry teardown change notifications', () => { it('announces the stopping transition during owner teardown, before settlement', async () => { const ctx = await harness() - const owner = stubAgent(ctx, 'alice') - ctx.agents.register(owner) + const owner = liveAgent(ctx, 'alice') const p = producer({ owner }) - const id = ctx.jobs.start(p.spec) + ctx.jobs.start(p.spec) - const statuses: (string | undefined)[] = [] - ctx.jobs.onJobsChanged((changed) => { - statuses.push(changed === undefined ? undefined : ctx.jobs.list(changed)[0]?.status) + const statuses: string[] = [] + ctx.jobs.events.subscribe({ owner: owner.id }, (event) => { + if (event.type !== 'output') statuses.push(`${event.type}:${event.job.status}`) }) // A slow producer keeps teardown parked between cancel and settlement; // an observer must not be left showing `running` for that whole window. const disposal = disposeAgentScope(owner) await tick() - expect(statuses).toEqual(['stopping']) + expect(statuses).toEqual(['stopping:stopping']) p.settle({ status: 'killed' }) await disposal // Settlement, then the removal that empties the visible set. - expect(statuses).toEqual(['stopping', 'killed', undefined]) - expect(ctx.jobs.list(owner)).toEqual([]) - void id + expect(statuses).toEqual(['stopping:stopping', 'settled:killed', 'removed:killed']) + expect(jobsOf(ctx, owner).list()).toEqual([]) }) - it('announces the emptied set to a listener registered outside this service (reload safety)', async () => { - const ctx = new Context() - await ctx.plugin(AgentRegistry) - const fiber = await ctx.plugin(LocalJobRegistry) - ctx.jobs.attachController('test-controller') - - // The api-proxy carrier registers from its own stream context, not the - // registry's fiber, so it is still listening when the registry unloads. - const seen: (string | undefined)[] = [] - ctx.jobs.onJobsChanged(changed => void seen.push(changed?.id)) - let settle!: (outcome: JobOutcome) => void - ctx.jobs.start({ - kind: 'bash', - label: 'sleep 600', - run: () => ({ - cancel() { settle({ status: 'killed' }) }, - done: new Promise((resolve) => { settle = resolve }), - }), + it('delivers scoped subscriptions to the owning composition only', async () => { + const ctx = await harness() + const mount = createScope(ctx, {}) + const otherMount = createScope(ctx, {}) + const alice = liveAgent(ctx, 'alice', scopeOf(mount.ctx)) + const bob = liveAgent(ctx, 'bob', scopeOf(otherMount.ctx)) + const everyone = collect(ctx, { owners: 'all' }, ['output']) + const scoped: string[] = [] + await mount.ctx.plugin({ + inject: ['jobs'], + apply(scopedCtx: Context) { + scopedCtx.jobs.events.subscribe({ owners: 'scope' }, (event) => { + if (event.type === 'output') scoped.push(String(event.id)) + }) + }, }) - seen.length = 0 - - await fiber.dispose() - // stopping (teardown cancel), settlement, then the final empty set. - expect(seen).toEqual([undefined, undefined, undefined]) + const pa = producer({ owner: alice }) + const aliceId = ctx.jobs.start(pa.spec) + const pb = producer({ owner: bob }) + ctx.jobs.start(pb.spec) + pa.job().append('for alice observers') + pb.job().append('for bob observers') + expect(everyone).toHaveLength(2) + expect(scoped).toEqual([String(aliceId)]) }) }) -describe('LocalJobRegistry record', () => { - it('appends advance absolute offsets; record reads are non-consuming and never mark reported', async () => { +describe('LocalJobRegistry output ring', () => { + it('appends advance absolute offsets and reach observers as output events', async () => { const ctx = await harness() - const p = producer({ record: true }) + const outputs = collect(ctx, { owners: 'all' }, ['output']) + const p = producer() const id = ctx.jobs.start(p.spec) p.job().append('hello ') p.job().append('world', { channel: 'stderr' }) - const first = ctx.jobs.readRecord(id, 0) - expect(first.lossy).toBe(false) - expect(first.next).toBe(11) - expect(first.chunks).toEqual([ - { at: 0, text: 'hello ' }, - { at: 6, text: 'world', channel: 'stderr' }, - ]) + const first = jobsOf(ctx).readAt(id, 0) + expect(first).toEqual({ + chunks: [{ at: 0, text: 'hello ' }, { at: 6, text: 'world', channel: 'stderr' }], + next: 11, + lossy: false, + }) // A second identical read proves nothing was consumed. - expect(ctx.jobs.readRecord(id, 0)).toEqual(first) + expect(jobsOf(ctx).readAt(id, 0)).toEqual(first) // Resuming from `next` yields nothing until more output arrives. - expect(ctx.jobs.readRecord(id, first.next).chunks).toEqual([]) + expect(jobsOf(ctx).readAt(id, first.next).chunks).toEqual([]) p.job().append('!') - expect(ctx.jobs.readRecord(id, first.next).chunks).toEqual([{ at: 11, text: '!' }]) - const snapshot = ctx.jobs.get(id) - expect(snapshot.outputTotal).toBe(12) - expect(snapshot.outputEarliest).toBe(0) - // The observer surface owns no notice state: even a terminal record read - // leaves the completion notice due. - p.settle({ status: 'completed' }) - await tick() - ctx.jobs.readRecord(id, 0) - expect(ctx.jobs.get(id).reported).toBe(false) + expect(jobsOf(ctx).readAt(id, first.next).chunks).toEqual([{ at: 11, text: '!' }]) + expect(jobsOf(ctx).get(id).output).toEqual({ total: 12, earliest: 0 }) + expect(outputs).toEqual([ + { type: 'output', id, total: 6 }, + { type: 'output', id, total: 11 }, + { type: 'output', id, total: 12 }, + ]) }) it('staged starter writes surface at the registration commit without observer signals', async () => { const ctx = await harness() - const outputSignals: string[] = [] - ctx.jobs.onOutput((id) => { outputSignals.push(String(id)) }) - const changes: number[] = [] - ctx.jobs.onJobsChanged(() => { changes.push(1) }) + const seen = collect(ctx) let settle!: (outcome: JobOutcome) => void const id = ctx.jobs.start({ kind: 'bash', label: 'staged writes', - record: true, run: (job) => { job.append('early ', { channel: 'stdout' }) - job.updateDetail('booting') + job.updateProgress('booting') return { cancel() {}, done: new Promise((resolve) => { settle = resolve }), @@ -1202,253 +1166,170 @@ describe('LocalJobRegistry record', () => { }, }) // Only the registration commit announced anything. - expect(outputSignals).toEqual([]) - expect(changes).toEqual([1]) - const snapshot = ctx.jobs.get(id) - expect(snapshot.detail).toBe('booting') - expect(snapshot.outputTotal).toBe(6) - expect(ctx.jobs.readRecord(id, 0).chunks).toEqual([{ at: 0, text: 'early ', channel: 'stdout' }]) + expect(seen.map(event => event.type)).toEqual(['registered']) + const view = jobsOf(ctx).get(id) + expect(view.progress).toBe('booting') + expect(view.output.total).toBe(6) + expect(jobsOf(ctx).readAt(id, 0).chunks).toEqual([{ at: 0, text: 'early ', channel: 'stdout' }]) settle({ status: 'completed' }) await tick() }) it('drops an empty append without waking observers', async () => { const ctx = await harness() - const signals: string[] = [] - ctx.jobs.onOutput((id) => { signals.push(String(id)) }) - const p = producer({ record: true }) + const outputs = collect(ctx, { owners: 'all' }, ['output']) + const p = producer() const id = ctx.jobs.start(p.spec) p.job().append('') - expect(signals).toEqual([]) - expect(ctx.jobs.get(id).outputTotal).toBe(0) + expect(outputs).toEqual([]) + expect(jobsOf(ctx).get(id).output.total).toBe(0) }) - it('hands a start without a record declaration no append; updateDetail still works', async () => { + it('rejects a negative or fractional read offset', async () => { const ctx = await harness() const p = producer() const id = ctx.jobs.start(p.spec) - // The plain face is built without the method, not with a dropping stub. - expect(p.job()).not.toHaveProperty('append') - expect(() => ctx.jobs.readRecord(id, 0)).toThrow(`job ${id} declared no output record`) - const snapshot = ctx.jobs.get(id) - expect(snapshot.outputTotal).toBeUndefined() - expect(snapshot.outputEarliest).toBeUndefined() - p.job().updateDetail('7/10 items') - expect(ctx.jobs.get(id).detail).toBe('7/10 items') - }) - - it('rejects a negative or fractional record read offset', async () => { - const ctx = await harness() - const p = producer({ record: true }) - const id = ctx.jobs.start(p.spec) - expect(() => ctx.jobs.readRecord(id, -1)).toThrow(/invalid record read offset/) - expect(() => ctx.jobs.readRecord(id, 0.5)).toThrow(/invalid record read offset/) - expect(() => ctx.jobs.readRecord(JobId('bash-99'), 0)).toThrow(/unknown job/) - }) - - it('fences record reads to the owning session', async () => { - const ctx = await harness() - const alice = stubAgent(ctx, 'alice') - const bob = stubAgent(ctx, 'bob') - ctx.agents.register(alice) - ctx.agents.register(bob) - const p = producer({ owner: alice, record: true }) - const id = ctx.jobs.start(p.spec) - p.job().append('secret') - expect(() => ctx.jobs.readRecord(id, 0, bob)).toThrow(/belongs to another session/) - expect(() => ctx.jobs.readRecord(id, 0)).toThrow(/belongs to another session/) - expect(ctx.jobs.readRecord(id, 0, alice).chunks[0]?.text).toBe('secret') + expect(() => jobsOf(ctx).readAt(id, -1)).toThrow(/invalid output read offset/) + expect(() => jobsOf(ctx).readAt(id, 0.5)).toThrow(/invalid output read offset/) + expect(() => jobsOf(ctx).readAt(JobId('bash-99'), 0)).toThrow(/unknown job/) }) it('evicts whole head chunks past the live cap and flags stale readers lossy', async () => { const ctx = await harness({ retainBytes: 8 }) - const p = producer({ record: true }) + const p = producer() const id = ctx.jobs.start(p.spec) p.job().append('aaaa') p.job().append('bbbb') p.job().append('cccc') - const read = ctx.jobs.readRecord(id, 0) + const read = jobsOf(ctx).readAt(id, 0) expect(read.lossy).toBe(true) expect(read.chunks).toEqual([{ at: 4, text: 'bbbb' }, { at: 8, text: 'cccc' }]) expect(read.next).toBe(12) - const snapshot = ctx.jobs.get(id) - expect(snapshot.outputEarliest).toBe(4) - expect(snapshot.outputTotal).toBe(12) + expect(jobsOf(ctx).get(id).output).toEqual({ total: 12, earliest: 4 }) // A reader at the retained boundary is not lossy. - expect(ctx.jobs.readRecord(id, 4).lossy).toBe(false) + expect(jobsOf(ctx).readAt(id, 4).lossy).toBe(false) + // The model cursor is subject to the same eviction. + expect(jobsOf(ctx).read(id).lossy).toBe(true) }) - it('keeps only the UTF-8-safe tail of a single oversized chunk', async () => { - const ctx = await harness({ retainBytes: 5 }) - const p = producer({ record: true }) - const id = ctx.jobs.start(p.spec) - // '你好' is six UTF-8 bytes; a five-byte budget must not split the second code point. - p.job().append('你好') - const read = ctx.jobs.readRecord(id, 0) - expect(read.lossy).toBe(true) - expect(read.chunks).toEqual([{ at: 3, text: '好', gapBefore: true }]) - const snapshot = ctx.jobs.get(id) - expect(snapshot.outputEarliest).toBe(3) - expect(snapshot.outputTotal).toBe(6) - }) - - it('an exhausted byte budget leaves an empty gap-marked tail at the total offset', async () => { - const ctx = await harness({ retainBytes: 1 }) - const p = producer({ record: true }) - const id = ctx.jobs.start(p.spec) - // Every byte of '好' from the cut is a continuation byte, so no code point survives. - p.job().append('好') - const read = ctx.jobs.readRecord(id, 0) - expect(read.lossy).toBe(true) - expect(read.chunks).toEqual([{ at: 3, text: '', gapBefore: true }]) - expect(ctx.jobs.get(id).outputEarliest).toBe(3) - }) - - it('returns the whole overlapped chunk for a foreign mid-chunk offset', async () => { - const ctx = await harness() - const p = producer({ record: true }) - const id = ctx.jobs.start(p.spec) - p.job().append('abcdef') - const read = ctx.jobs.readRecord(id, 3) - expect(read.chunks).toEqual([{ at: 0, text: 'abcdef' }]) - expect(read.lossy).toBe(false) - }) - - it('preserves a producer-reported gap marker through reads', async () => { - const ctx = await harness() - const p = producer({ record: true }) - const id = ctx.jobs.start(p.spec) - p.job().append('tail after drop', { gapBefore: true, channel: 'stdout' }) - expect(ctx.jobs.readRecord(id, 0).chunks).toEqual([ - { at: 0, text: 'tail after drop', channel: 'stdout', gapBefore: true }, - ]) - }) - - it('settlement trims to the settled cap, signals once more, and drops later writes', async () => { + it('settlement trims to the settled cap, ends the stream, and drops later writes', async () => { const ctx = await harness({ retainBytes: 1024, settledRetainBytes: 4 }) const warn = vi.fn() ctx.logger.warn = warn as never - const signals: string[] = [] - ctx.jobs.onOutput((id) => { signals.push(String(id)) }) - const p = producer({ record: true }) + const outputs = collect(ctx, { owners: 'all' }, ['output']) + const p = producer() const id = ctx.jobs.start(p.spec) p.job().append('abcdefgh') p.settle({ status: 'completed', detail: 'exit code: 0' }) await tick() - expect(signals).toEqual([String(id), String(id)]) - const snapshot = ctx.jobs.get(id) - expect(snapshot).toMatchObject({ status: 'completed', detail: 'exit code: 0', outputTotal: 8, outputEarliest: 4 }) - const read = ctx.jobs.readRecord(id, 0) + expect(outputs.map(event => event.type === 'output' ? event.total : -1)).toEqual([8, 8]) + expect(jobsOf(ctx).get(id)).toMatchObject({ status: 'completed', detail: 'exit code: 0', output: { total: 8, earliest: 4 } }) + const read = jobsOf(ctx).readAt(id, 0) expect(read.lossy).toBe(true) expect(read.chunks).toEqual([{ at: 4, text: 'efgh', gapBefore: true }]) // The stream ended with the settlement: a trailing flush cannot break teardown. p.job().append('late') - p.job().updateDetail('late detail') + p.job().updateProgress('late progress') expect(warn.mock.calls.map(call => String(call[0]))).toEqual([ expect.stringContaining('append to settled job'), - expect.stringContaining('detail update on settled job'), + expect.stringContaining('progress update on settled job'), ]) - expect(signals).toHaveLength(2) - expect(ctx.jobs.get(id).detail).toBe('exit code: 0') + expect(outputs).toHaveLength(2) + expect(jobsOf(ctx).get(id).progress).toBeUndefined() }) - it('a terminal outcome without detail keeps the last progress line', async () => { + it('settlement clears the progress line; the terminal detail is the outcome alone', async () => { const ctx = await harness() - const changes: number[] = [] - const p = producer({ record: true }) + const p = producer() const id = ctx.jobs.start(p.spec) - ctx.jobs.onJobsChanged(() => { changes.push(1) }) - p.job().updateDetail('3/10 agents done') - expect(changes).toHaveLength(1) - expect(ctx.jobs.get(id).detail).toBe('3/10 agents done') + p.job().updateProgress('3/10 agents done') + expect(jobsOf(ctx).get(id)).toMatchObject({ progress: '3/10 agents done' }) p.settle({ status: 'completed' }) await tick() - expect(ctx.jobs.get(id)).toMatchObject({ status: 'completed', detail: '3/10 agents done' }) + const view = jobsOf(ctx).get(id) + expect(view.status).toBe('completed') + expect(view.progress).toBeUndefined() + expect(view.detail).toBeUndefined() }) - it('a teardown-forced settlement also ends the record', async () => { + it('a teardown-forced settlement also ends the ring', async () => { const ctx = await harness() const warn = vi.fn() ctx.logger.warn = warn as never - const owner = stubAgent(ctx, 'owner') - ctx.agents.register(owner) - const p = producer({ owner, record: true }) + const owner = liveAgent(ctx, 'owner') + const p = producer({ owner }) const id = ctx.jobs.start(p.spec) p.job().append('partial') const disposal = disposeAgentScope(owner) p.settle({ status: 'killed' }) await disposal - expect(() => ctx.jobs.readRecord(id, 0, owner)).toThrow(/unknown job/) + expect(() => jobsOf(ctx, owner).readAt(id, 0)).toThrow(/unknown job/) // The producer face outlives the row; its trailing flush is dropped, not thrown. p.job().append('late') expect(warn).toHaveBeenCalledWith(expect.stringContaining('append to settled job')) }) - it('delivers onOutput to the global layer and to the owning scope only', async () => { + it('hands out fresh projections, never live registry state', async () => { const ctx = await harness() - const mount = createScope(ctx, {}) - const otherMount = createScope(ctx, {}) - const alice = stubAgent(ctx, 'alice', scopeOf(mount.ctx)) - const bob = stubAgent(ctx, 'bob', scopeOf(otherMount.ctx)) - ctx.agents.register(alice) - ctx.agents.register(bob) - const globalSignals: string[] = [] - ctx.jobs.onOutput((id) => { globalSignals.push(String(id)) }) - const scopedSignals: string[] = [] - await mount.ctx.plugin({ - inject: ['jobs'], - apply(scopedCtx: Context) { - scopedCtx.jobs.onOutput((id) => { scopedSignals.push(String(id)) }) - }, - }) - const pa = producer({ owner: alice, record: true }) - const aliceId = ctx.jobs.start(pa.spec) - const pb = producer({ owner: bob, record: true }) - ctx.jobs.start(pb.spec) - pa.job().append('for alice observers') - pb.job().append('for bob observers') - expect(globalSignals).toHaveLength(2) - expect(scopedSignals).toEqual([String(aliceId)]) - }) - - it('contains a throwing onOutput listener without breaking the append commit', async () => { - const ctx = await harness() - const warn = vi.fn() - ctx.logger.warn = warn as never - ctx.jobs.onOutput(() => { throw new Error('output boom') }) - const p = producer({ record: true }) + const p = producer() const id = ctx.jobs.start(p.spec) - p.job().append('x') - expect(ctx.jobs.get(id).outputTotal).toBe(1) - expect(warn).toHaveBeenCalledWith(expect.stringContaining('onOutput listener threw')) - }) - - it('unregisters onOutput listeners with their registering fiber (HMR safety)', async () => { - const ctx = await harness() - const signals: string[] = [] - const fiber = ctx.plugin({ - inject: ['jobs'], - apply(pluginCtx: Context) { - pluginCtx.jobs.onOutput((id) => { signals.push(String(id)) }) - }, - }) - await fiber - const p = producer({ record: true }) - ctx.jobs.start(p.spec) - p.job().append('a') - expect(signals).toHaveLength(1) - await fiber.dispose() - p.job().append('b') - expect(signals).toHaveLength(1) - }) - - it('hands out fresh record snapshots, never live registry state', async () => { - const ctx = await harness() - const p = producer({ record: true }) - const id = ctx.jobs.start(p.spec) - const before = ctx.jobs.get(id) + const before = jobsOf(ctx).get(id) p.job().append('grow') - expect(before.outputTotal).toBe(0) - expect(ctx.jobs.get(id).outputTotal).toBe(4) + expect(before.output.total).toBe(0) + expect(jobsOf(ctx).get(id).output.total).toBe(4) + }) +}) + +describe('LocalJobRegistry pull sources', () => { + it('pumps the spec sources into the ring and drains them once more before settlement', async () => { + const ctx = await harness({ pumpPollMs: 1 }) + const out = scriptedSource([{ text: 'a' }, { text: 'bc' }], 'stdout') + // stderr only becomes readable once the producer has settled: the pump's + // final drain is the only read that can collect it. + let finishing = false + let errOffset = 0 + const err: JobOutputSource = { + channel: 'stderr', + read() { + const text = finishing && errOffset === 0 ? 'E' : '' + errOffset += text.length + return { text, nextOffset: errOffset, lossy: false } + }, + } + const p = producer({ output: [out, err] }) + const id = ctx.jobs.start(p.spec) + await new Promise(resolve => setTimeout(resolve, 10)) + expect(jobsOf(ctx).readAt(id, 0).chunks.map(chunk => chunk.text)).toEqual(['a', 'bc']) + + const settled = collect(ctx, { owners: 'all' }, ['settled']) + finishing = true + p.settle({ status: 'completed', detail: 'exit code: 0' }) + await new Promise(resolve => setTimeout(resolve, 10)) + // The final drain landed before the settlement announced itself. + expect(settled).toHaveLength(1) + expect(jobsOf(ctx).readAt(id, 0).chunks.map(chunk => chunk.text)).toEqual(['a', 'bc', 'E']) + expect(jobsOf(ctx).get(id)).toMatchObject({ status: 'completed', output: { total: 4 } }) + }) + + it('stops pumping silently after a forced settlement', async () => { + const ctx = await harness({ pumpPollMs: 1 }) + const warn = vi.fn() + ctx.logger.warn = warn as never + const owner = liveAgent(ctx, 'owner') + const source: JobOutputSource = { + read: fromByte => ({ text: 'x', nextOffset: fromByte + 1, lossy: false }), + } + ctx.jobs.start({ + kind: 'bash', + label: 'endless', + owner: owner.id, + output: [source], + run: () => ({ cancel() { throw new Error('cancel boom') }, done: new Promise(() => {}) }), + }) + await new Promise(resolve => setTimeout(resolve, 5)) + await disposeAgentScope(owner) + await new Promise(resolve => setTimeout(resolve, 5)) + // The forced failure is the only warning: the pump's later drains are silent. + expect(warn.mock.calls.map(call => String(call[0]))).toEqual([expect.stringContaining('work may be orphaned')]) }) }) From 6626c74dbc66b292061cbde6063c12654a30bde8 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 16:09:07 +0800 Subject: [PATCH 030/100] refactor(jobs-local): contain a throwing pull source instead of freezing the job --- packages/jobs/jobs-local/src/index.ts | 28 ++++++++++++++++++--- packages/jobs/jobs-local/tests/jobs.spec.ts | 17 +++++++++++++ 2 files changed, 42 insertions(+), 3 deletions(-) diff --git a/packages/jobs/jobs-local/src/index.ts b/packages/jobs/jobs-local/src/index.ts index 965de7a124..165cf83aff 100644 --- a/packages/jobs/jobs-local/src/index.ts +++ b/packages/jobs/jobs-local/src/index.ts @@ -18,8 +18,8 @@ import type { SessionId } from '@deepseek-ai/dsh-session' import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout' import { JobRegistry, JobId } from '@deepseek-ai/dsh-jobs' import type { - JobAppendOptions, JobEvent, JobEvents, JobHandle, JobKillOptions, JobKind, JobOutcome, JobOutputRead, JobRead, - JobSettleCause, JobSpec, JobStatus, JobView, VisibleJobs, + JobAppendOptions, JobEvent, JobEvents, JobHandle, JobKillOptions, JobKind, JobOutcome, JobOutputRead, JobOutputSource, + JobRead, JobSettleCause, JobSpec, JobStatus, JobView, VisibleJobs, } from '@deepseek-ai/dsh-jobs' import { JobEventHub, JobLayer } from './events.ts' import { startPump } from './pump.ts' @@ -270,7 +270,7 @@ export class LocalJobRegistry extends JobRegistry { ) if (spec.output !== undefined && spec.output.length > 0) { job.pump = startPump( - spec.output, + spec.output.map(source => this.guardSource(job, source)), (text, options) => { this.appendRing(state, ring, text, options, 'pump') }, this.pumpPollMs, Promise.race([producerDone, settled]), @@ -485,6 +485,28 @@ export class LocalJobRegistry extends JobRegistry { if (job !== undefined) this.emitOutput(job) } + /** + * Contain a failing pull source: the first throw is logged, and the source + * reads as exhausted from then on, so the job runs to its own settlement + * with whatever the ring holds instead of freezing on a pump failure. + */ + private guardSource(job: TrackedJob, source: JobOutputSource): JobOutputSource { + let failed = false + return { + ...source.channel !== undefined ? { channel: source.channel } : {}, + read: (fromByte) => { + if (failed) return { text: '', nextOffset: fromByte, lossy: false } + try { + return source.read(fromByte) + } catch (error: unknown) { + failed = true + this.selfCtx.logger.warn(`jobs: output source for ${job.id} failed; its stream stops here: ${String(error)}`) + return { text: '', nextOffset: fromByte, lossy: false } + } + }, + } + } + /** Announce that one job's ring advanced (append or settlement). */ private emitOutput(job: TrackedJob): void { const owner = job.owner?.id diff --git a/packages/jobs/jobs-local/tests/jobs.spec.ts b/packages/jobs/jobs-local/tests/jobs.spec.ts index 550a713f6b..6f65916157 100644 --- a/packages/jobs/jobs-local/tests/jobs.spec.ts +++ b/packages/jobs/jobs-local/tests/jobs.spec.ts @@ -1311,6 +1311,23 @@ describe('LocalJobRegistry pull sources', () => { expect(jobsOf(ctx).get(id)).toMatchObject({ status: 'completed', output: { total: 4 } }) }) + it('contains a throwing source: warns once, keeps the job live, and settles on the producer', async () => { + const ctx = await harness({ pumpPollMs: 1 }) + const warn = vi.fn() + ctx.logger.warn = warn as never + const broken: JobOutputSource = { channel: 'stdout', read() { throw new Error('reader boom') } } + const healthy = scriptedSource([{ text: 'ok' }], 'stderr') + const p = producer({ output: [broken, healthy] }) + const id = ctx.jobs.start(p.spec) + await new Promise(resolve => setTimeout(resolve, 10)) + expect(jobsOf(ctx).get(id).status).toBe('running') + expect(jobsOf(ctx).readAt(id, 0).chunks).toEqual([{ at: 0, text: 'ok', channel: 'stderr' }]) + expect(warn.mock.calls.map(call => String(call[0]))).toEqual([expect.stringContaining(`output source for ${id} failed`)]) + p.settle({ status: 'completed', detail: 'exit code: 0' }) + await new Promise(resolve => setTimeout(resolve, 10)) + expect(jobsOf(ctx).get(id)).toMatchObject({ status: 'completed', detail: 'exit code: 0' }) + }) + it('stops pumping silently after a forced settlement', async () => { const ctx = await harness({ pumpPollMs: 1 }) const warn = vi.fn() From 0e35952802da6648f09fe5e824fd48c928983349 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 16:30:57 +0800 Subject: [PATCH 031/100] refactor(tool-jobs): render model reads from the ring and own the notice ledger - job_output reads the per-job ring through visibleTo(): stdout, then one [stderr] section, log narration excluded, a dropped-output notice on a lossy read, and the result exactly once after settlement - completion notices come from the registry event stream subscribed with { owners: 'scope' }; a wait claims its job when it starts and withdraws on timeout or abort, job_kill claims on 'requested', teardown settlements and unowned jobs are skipped, and a removal drops the ledger entry - the notice destination is the agent registered for the owner session at settlement, so tool-jobs now injects the agent registry - JobView exposes the producer's outputLimitBytes for the tool-result bound - lint: hub disposer identity comment, unknown-typed matchers in seam tests --- packages/jobs/jobs-local/src/events.ts | 4 +- packages/jobs/jobs-local/src/index.ts | 2 +- packages/jobs/jobs-local/tests/jobs.spec.ts | 22 +- packages/jobs/jobs/src/view.ts | 2 + packages/jobs/jobs/tests/service.spec.ts | 2 +- packages/jobs/tool-jobs/src/index.ts | 153 ++++---- packages/jobs/tool-jobs/src/render.ts | 80 ++++ .../jobs/tool-jobs/tests/tool-jobs.spec.ts | 354 ++++++++++++------ 8 files changed, 433 insertions(+), 186 deletions(-) create mode 100644 packages/jobs/tool-jobs/src/render.ts diff --git a/packages/jobs/jobs-local/src/events.ts b/packages/jobs/jobs-local/src/events.ts index 2e39f7089f..333d5db5fc 100644 --- a/packages/jobs/jobs-local/src/events.ts +++ b/packages/jobs/jobs-local/src/events.ts @@ -62,10 +62,12 @@ export class JobEventHub { if ('owners' in filter && filter.owners === 'scope') { return this.layers.effect(ctx, layer => layer.scoped.append(subscription), { label: 'jobs.events.subscribe()' }) } - return ctx.effect(() => { + const dispose = ctx.effect(() => { this.unscoped.add(subscription) return () => { this.unscoped.delete(subscription) } }, 'jobs.events.subscribe()') + // oxlint-disable-next-line typescript/no-misused-promises -- exact synchronous disposer preserves Cordis effect identity + return dispose } /** diff --git a/packages/jobs/jobs-local/src/index.ts b/packages/jobs/jobs-local/src/index.ts index 165cf83aff..990c03209c 100644 --- a/packages/jobs/jobs-local/src/index.ts +++ b/packages/jobs/jobs-local/src/index.ts @@ -177,7 +177,7 @@ export class LocalJobRegistry extends JobRegistry { this.settledRetainBytes = resolved.settledRetainBytes this.pumpPollMs = resolved.pumpPollMs this.selfCtx = ctx - this.hub = new JobEventHub(this.layers, message => ctx.logger.warn(message)) + this.hub = new JobEventHub(this.layers, (message) => { ctx.logger.warn(message) }) ctx.effect(() => () => this.disposeAll(), 'jobs teardown') } diff --git a/packages/jobs/jobs-local/tests/jobs.spec.ts b/packages/jobs/jobs-local/tests/jobs.spec.ts index 6f65916157..55e5615a58 100644 --- a/packages/jobs/jobs-local/tests/jobs.spec.ts +++ b/packages/jobs/jobs-local/tests/jobs.spec.ts @@ -395,7 +395,7 @@ describe('LocalJobRegistry reads and settlement', () => { p.settle({ status: 'completed', detail: 'exit code: 0' }) await tick() - expect(seen).toEqual([{ type: 'settled', cause: 'producer', job: expect.objectContaining({ id, status: 'completed', detail: 'exit code: 0' }) }]) + expect(seen).toEqual([{ type: 'settled', cause: 'producer', job: expect.objectContaining({ id, status: 'completed', detail: 'exit code: 0' }) as unknown }]) expect(warn).toHaveBeenCalledWith(expect.stringContaining('listener boom')) }) @@ -440,14 +440,14 @@ describe('LocalJobRegistry.kill', () => { expect(jobsOf(ctx).kill(id, { reason: 'no longer needed' })).toBe('requested') expect(p.cancels).toEqual(['no longer needed']) expect(jobsOf(ctx).list()[0]).toMatchObject({ status: 'stopping' }) - expect(seen).toEqual([{ type: 'stopping', job: expect.objectContaining({ id, status: 'stopping' }) }]) + expect(seen).toEqual([{ type: 'stopping', job: expect.objectContaining({ id, status: 'stopping' }) as unknown }]) p.settle({ status: 'killed', detail: 'signal: SIGTERM' }) await tick() expect(seen[1]).toEqual({ type: 'settled', cause: 'kill', - job: expect.objectContaining({ id, status: 'killed', detail: 'signal: SIGTERM; no longer needed' }), + job: expect.objectContaining({ id, status: 'killed', detail: 'signal: SIGTERM; no longer needed' }) as unknown, }) }) @@ -495,7 +495,7 @@ describe('LocalJobRegistry.kill', () => { expect(seen).toEqual([]) settle({ status: 'completed' }) await tick() - expect(seen).toEqual([{ type: 'settled', cause: 'producer', job: expect.objectContaining({ id }) }]) + expect(seen).toEqual([{ type: 'settled', cause: 'producer', job: expect.objectContaining({ id }) as unknown }]) broken = false expect(jobsOf(ctx).kill(id)).toBe('already-finished') @@ -587,7 +587,7 @@ describe('LocalJobRegistry.wait', () => { p.settle({ status: 'completed', detail: 'exit code: 0' }) controller.abort() await expect(wait).rejects.toThrow('wait aborted') - expect(seen).toEqual([{ type: 'settled', cause: 'producer', job: expect.objectContaining({ id, status: 'completed' }) }]) + expect(seen).toEqual([{ type: 'settled', cause: 'producer', job: expect.objectContaining({ id, status: 'completed' }) as unknown }]) }) it('an abort landing after settlement still delivers the terminal projection it owes', async () => { @@ -751,7 +751,7 @@ describe('LocalJobRegistry owner cleanup', () => { }) await disposeAgentScope(owner) - expect(seen).toEqual([{ type: 'settled', cause: 'teardown', job: expect.objectContaining({ status: 'killed' }) }]) + expect(seen).toEqual([{ type: 'settled', cause: 'teardown', job: expect.objectContaining({ status: 'killed' }) as unknown }]) }) it('attaches one cleanup per owner and drains all owned jobs with the scope', async () => { @@ -933,7 +933,7 @@ describe('LocalJobRegistry disposal', () => { expect(disposedWithoutProducerDone).toBe(true) expect(warn).toHaveBeenCalledWith(expect.stringContaining('work may be orphaned')) - expect(seen).toEqual([{ type: 'settled', cause: 'teardown', job: expect.objectContaining({ status: 'failed' }) }]) + expect(seen).toEqual([{ type: 'settled', cause: 'teardown', job: expect.objectContaining({ status: 'failed' }) as unknown }]) }) it('detaches owner effects from still-live agent scopes when the service unloads', async () => { @@ -1012,14 +1012,14 @@ describe('LocalJobRegistry events', () => { const p = producer({ owner }) const id = ctx.jobs.start(p.spec) // Registration is announced only once the record is readable. - expect(seen).toEqual([{ type: 'registered', job: expect.objectContaining({ id, owner: 'alice', status: 'running' }) }]) + expect(seen).toEqual([{ type: 'registered', job: expect.objectContaining({ id, owner: 'alice', status: 'running' }) as unknown }]) expect(jobsOf(ctx, owner).list()).toHaveLength(1) p.job().updateProgress('3/10') - expect(seen[1]).toEqual({ type: 'progress', job: expect.objectContaining({ id, progress: '3/10' }) }) + expect(seen[1]).toEqual({ type: 'progress', job: expect.objectContaining({ id, progress: '3/10' }) as unknown }) expect(jobsOf(ctx, owner).kill(id)).toBe('requested') - expect(seen[2]).toEqual({ type: 'stopping', job: expect.objectContaining({ id, status: 'stopping', progress: '3/10' }) }) + expect(seen[2]).toEqual({ type: 'stopping', job: expect.objectContaining({ id, status: 'stopping', progress: '3/10' }) as unknown }) p.settle({ status: 'killed' }) await tick() @@ -1033,7 +1033,7 @@ describe('LocalJobRegistry events', () => { const ctx = await harness() const seen = collect(ctx, { owner: SessionId('anyone') }, ['registered']) ctx.jobs.start(producer().spec) - expect(seen).toEqual([{ type: 'registered', job: expect.objectContaining({ id: 'bash-1' }) }]) + expect(seen).toEqual([{ type: 'registered', job: expect.objectContaining({ id: 'bash-1' }) as unknown }]) expect((seen[0] as { job: JobView }).job.owner).toBeUndefined() }) diff --git a/packages/jobs/jobs/src/view.ts b/packages/jobs/jobs/src/view.ts index 033fcfbe76..d3c73ae018 100644 --- a/packages/jobs/jobs/src/view.ts +++ b/packages/jobs/jobs/src/view.ts @@ -62,6 +62,8 @@ export interface JobView { readonly label: string /** Owning session; absent for an unowned job, which every caller can see. */ readonly owner?: SessionId + /** Producer-owned cap for complete model-facing notices and reads, in UTF-8 bytes. */ + readonly outputLimitBytes?: number /** Current lifecycle state. */ readonly status: JobStatus /** The producer's live progress line (`3/10`, the current phase); cleared at settlement. */ diff --git a/packages/jobs/jobs/tests/service.spec.ts b/packages/jobs/jobs/tests/service.spec.ts index f3b456acbc..5bcde91862 100644 --- a/packages/jobs/jobs/tests/service.spec.ts +++ b/packages/jobs/jobs/tests/service.spec.ts @@ -77,7 +77,7 @@ describe('JobRegistry seam', () => { expect(jobs.list()).toHaveLength(1) expect(jobs.get(id).status).toBe('running') expect(jobs.get(id).owner).toBe(caller) - expect(jobs.read(id)).toEqual({ chunks: [], lossy: false, job: expect.objectContaining({ id }) }) + expect(jobs.read(id)).toEqual({ chunks: [], lossy: false, job: expect.objectContaining({ id }) as unknown }) expect(jobs.readAt(id, 7)).toEqual({ chunks: [], next: 7, lossy: false }) expect(jobs.kill(id, { reason: 'seam test' })).toBe('requested') await expect(jobs.wait(id, 5)).resolves.toMatchObject({ id }) diff --git a/packages/jobs/tool-jobs/src/index.ts b/packages/jobs/tool-jobs/src/index.ts index 325766ee2b..d189182b72 100644 --- a/packages/jobs/tool-jobs/src/index.ts +++ b/packages/jobs/tool-jobs/src/index.ts @@ -1,9 +1,10 @@ /** * Model-facing `job_output`, `job_list`, and `job_kill` tools over * `ctx.jobs`. Loading the plugin attaches the controller required by - * producers. It also delivers unreported completions to the owning agent: - * injected into a busy owner's next step, or opening a turn on an idle one - * under the default `wakeup` delivery, bounded per owner. + * producers. It also delivers completions the model has not already + * collected to the owning agent: injected into a busy owner's next step, or + * opening a turn on an idle one under the default `wakeup` delivery, bounded + * per owner. * @module @deepseek-ai/dsh-tool-jobs */ @@ -14,14 +15,19 @@ import { TextRetainer } from '@deepseek-ai/dsh-output-retention' import { defineTool } from '@deepseek-ai/dsh-tools' import type { GenericCallView, ToolDefinition, ToolExecution } from '@deepseek-ai/dsh-tools' import { JobId } from '@deepseek-ai/dsh-jobs' -import type { JobSnapshot } from '@deepseek-ai/dsh-jobs' +import type { JobView, VisibleJobs } from '@deepseek-ai/dsh-jobs' import type { Agent } from '@deepseek-ai/dsh-agent' +import { jobDetail, publicJob, renderModelDelta, statusLine } from './render.ts' +import type { PublicJobSnapshot } from './render.ts' + +export { publicJob, renderModelDelta, statusLine } from './render.ts' +export type { PublicJobSnapshot } from './render.ts' export const name = 'tool-jobs' -export const inject = ['tools', 'jobs', 'systemPrompt'] +export const inject = ['tools', 'jobs', 'agents', 'systemPrompt'] /** - * How an unreported completion reaches an owner that is already idle: `wakeup` + * How an uncollected completion reaches an owner that is already idle: `wakeup` * opens a turn for it, `quiet` leaves it pending until something else wakes the * owner. A busy owner is injected either way. */ @@ -51,17 +57,6 @@ export const Config: z = z.object({ maxConsecutiveWakes: z.number().min(1).default(3), }) -/** Task state safe for model-authored programs; ownership/bookkeeping fields are omitted. */ -export interface PublicJobSnapshot { - id: string - kind: string - label: string - status: JobSnapshot['status'] - detail?: string - startedAt: number - finishedAt?: number -} - /** Shared schema for job-control outputs. */ const PUBLIC_TASK_SCHEMA = { type: 'object', @@ -81,30 +76,6 @@ const PUBLIC_TASK_SCHEMA = { }, } as const -/** Remove job ownership and notification bookkeeping from a registry snapshot. */ -function publicJob(snapshot: JobSnapshot): PublicJobSnapshot { - return { - id: snapshot.id, - kind: snapshot.kind, - label: snapshot.label, - status: snapshot.status, - ...snapshot.detail !== undefined ? { detail: snapshot.detail } : {}, - startedAt: snapshot.startedAt, - ...snapshot.finishedAt !== undefined ? { finishedAt: snapshot.finishedAt } : {}, - } -} - -/** - * Render generic status with optional producer detail. - * @param snapshot - job state to render. - * @returns a bracketed status line. - */ -export function statusLine(snapshot: Pick): string { - return snapshot.detail !== undefined - ? `[status: ${snapshot.status}, ${snapshot.detail}]` - : `[status: ${snapshot.status}]` -} - const encoder = new TextEncoder() function retainTail(text: string, maxBytes: number): string { @@ -135,19 +106,19 @@ function fitWithSuffix( /** * One-line account of a settled job for the `notice` form's collapsed row. - * @param snapshot - the settled job. + * @param job - the settled job. * @returns its kind, label, and status, bounded like every notice summary. */ -function completionSummary(snapshot: JobSnapshot): string { - return boundContextSummary(`${snapshot.kind} ${snapshot.label} ${statusLine(snapshot)}`) +function completionSummary(job: JobView): string { + return boundContextSummary(`${job.kind} ${job.label} ${statusLine({ status: job.status, detail: jobDetail(job) })}`) } -function fitCompletionNotice(snapshot: JobSnapshot): string { - const prefix = `background job ${snapshot.id}` - const detail = ` (${snapshot.kind}: ${snapshot.label}) finished ${statusLine(snapshot)}` +function fitCompletionNotice(job: JobView): string { + const prefix = `background job ${job.id}` + const detail = ` (${job.kind}: ${job.label}) finished ${statusLine({ status: job.status, detail: jobDetail(job) })}` const action = '\nDone; job_output.' const complete = `${prefix}${detail}. Read its output with job_output.` - const maxBytes = snapshot.outputLimitBytes + const maxBytes = job.outputLimitBytes if (maxBytes === undefined || encoder.encode(complete).byteLength <= maxBytes) return complete const omitted = '\n[notice truncated]' const fixed = `${prefix}${omitted}${action}` @@ -181,11 +152,12 @@ function boundSingleText(content: readonly ContentBlock[], maxBytes: number): Co }] } +/** The producer's cap for the job a `job_output` or `job_kill` call names, when it is visible to the caller. */ function visibleOutputLimit(ctx: Context, exec: ToolExecution): number | undefined { if (exec.name !== 'job_output' && exec.name !== 'job_kill') return undefined const jobId = (exec.arguments as { job_id?: unknown } | null | undefined)?.job_id if (typeof jobId !== 'string' || jobId.length === 0) return undefined - return ctx.jobs.list(exec.agent).find(snapshot => snapshot.id === jobId)?.outputLimitBytes + return ctx.jobs.visibleTo(exec.agent?.id).list().find(job => job.id === jobId)?.outputLimitBytes } /** Validate the non-empty constraint that ParameterSchemaSpec cannot express. */ @@ -201,6 +173,21 @@ function presentTaskCall(title: string, kind: 'read' | 'execute', rawInput?: str return { card: 'generic', title, kind, ...rawInput !== undefined ? { rawInput } : {} } } +/** True for the three terminal statuses. */ +function isTerminal(job: JobView): boolean { + return job.status === 'completed' || job.status === 'killed' || job.status === 'failed' +} + +/** The consuming read as the model sees it: the delta, then the result once, then the status line. */ +function readBody(jobs: VisibleJobs, id: JobId): { text: string; job: PublicJobSnapshot } { + const read = jobs.read(id) + const delta = renderModelDelta(read.chunks, read.lossy) + const text = read.result === undefined + ? delta + : `${delta}${delta.length > 0 && !delta.endsWith('\n') ? '\n' : ''}${read.result}` + return { text, job: publicJob(read.job) } +} + export function apply(ctx: Context, config: Config): void { const waitDefault = config.waitTimeoutMs ?? 30_000 const waitCap = config.maxWaitTimeoutMs ?? 600_000 @@ -262,31 +249,52 @@ export function apply(ctx: Context, config: Config): void { ctx.systemPrompt.section({ name: 'tool:jobs', order: ctx.systemPrompt.getSectionOrder('TOOL_JOBS'), - text: 'Track every background job id you start. You are notified in-session when a job finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running job\'s work. Before giving a final answer, collect every still-relevant job with job_output (set wait: true only when you are genuinely blocked on it), and job_kill jobs that stopped mattering.', + text: 'Track every background job id you start. You are notified in-session when a job finishes — do not busy-poll or sleep on one; keep working on independent steps and do not stop your turn just to wait. Use job_output when you need its output now. Use job_kill to stop a job you no longer need.', }) - // Use the exact lifecycle owner; reusable ids could resolve to a replacement. + // Jobs whose terminal state this plugin already handed to the model through + // a tool result: a terminal `job_output`, a wait that returned it, or a + // `job_kill` it requested. A wait claims when it starts, not when it + // returns — settlement releases waiters before it announces, but their + // continuations run after the event — and withdraws the claim if the job + // outlives the wait. The settlement event drops the entry, so the ledger + // holds only live jobs the model already touched. + const delivered = new Set() + const claim = (id: JobId): (() => void) => { + delivered.add(id) + return () => { delivered.delete(id) } + } + // A busy owner is injected: the notice waits in its next-step inbox, which // the turn cannot close over, so jobs settling together cost one step. An // idle owner is woken instead, because an unclaimed notice is a completion // the model never learns about. Either way, disposal before the claim - // discards it with the owner, and teardown settlements arrive `reported`. + // discards it with the owner, and a teardown settlement has no reader left. // - // The registry routes each settlement to the listeners its owner's scope - // chain reaches, so a mount under one preset never sees another preset's - // agents; this listener owns delivery, not the choice of whom to deliver to. - ctx.jobs.onJobDone((snapshot, owner) => { - if (snapshot.reported || owner === undefined) return + // The registry routes each settlement to the scope this plugin was mounted + // under, so a mount under one preset never sees another preset's agents; + // this listener owns delivery, not the choice of whom to deliver to. + ctx.jobs.events.subscribe({ owners: 'scope' }, (event) => { + if (event.type === 'removed') { + delivered.delete(event.job.id) + return + } + if (event.type !== 'settled') return + const claimed = delivered.delete(event.job.id) + if (claimed || event.cause === 'teardown' || event.job.owner === undefined) return + // Use the exact lifecycle owner; a session whose agent left has no inbox. + const owner = ctx.agents.get(event.job.owner) + if (owner === undefined) return const message = createUserMessage({ content: [{ type: 'text', - text: fitCompletionNotice(snapshot), + text: fitCompletionNotice(event.job), }], source: { kind: 'plugin', plugin: 'tool-jobs', form: 'notice', - summary: completionSummary(snapshot), + summary: completionSummary(event.job), }, }) const spent = spentWakes.get(owner) ?? 0 @@ -328,12 +336,19 @@ export function apply(ctx: Context, config: Config): void { }, async execute(args, exec) { const id = validateJobId(args.job_id) + const jobs = ctx.jobs.visibleTo(exec.agent?.id) if (args.wait === true) { const timeout = Math.min(args.timeout_ms ?? waitDefault, waitCap) - await ctx.jobs.wait(id, timeout, exec.agent, exec.signal) + const withdraw = claim(id) + try { + const view = await jobs.wait(id, timeout, exec.signal) + if (!isTerminal(view)) withdraw() + } catch (error: unknown) { + withdraw() + throw error + } } - const read = ctx.jobs.read(id, exec.agent) - return { text: read.text, job: publicJob(read.snapshot) } + return readBody(jobs, id) }, presentCall: args => presentTaskCall(`Read output from background job ${args.job_id}`, 'read', args.job_id), })) @@ -352,7 +367,7 @@ export function apply(ctx: Context, config: Config): void { }], }, execute(_args, exec) { - const jobs = ctx.jobs.list(exec.agent) + const jobs = ctx.jobs.visibleTo(exec.agent?.id).list() return Promise.resolve(jobs.map(publicJob)) }, presentCall: () => presentTaskCall('List background jobs', 'read'), @@ -388,12 +403,16 @@ export function apply(ctx: Context, config: Config): void { }, execute(args, exec) { const id = validateJobId(args.job_id) - const result = ctx.jobs.kill(id, exec.agent, args.reason) - // A snapshot describes current state without consuming pending output. - const snapshot = publicJob(ctx.jobs.get(id, exec.agent)) + const jobs = ctx.jobs.visibleTo(exec.agent?.id) + const result = jobs.kill(id, args.reason === undefined ? {} : { reason: args.reason }) + // The model's own kill is its delivery: the settlement notice would only + // repeat what this tool result already said. + if (result === 'requested') claim(id) + // A projection describes current state without consuming pending output. + const job = publicJob(jobs.get(id)) return Promise.resolve({ outcome: result === 'already-finished' ? 'already-finished' as const : 'cancellation-requested' as const, - job: snapshot, + job, }) }, presentCall: args => presentTaskCall(`Kill background job ${args.job_id}`, 'execute', args.job_id), diff --git a/packages/jobs/tool-jobs/src/render.ts b/packages/jobs/tool-jobs/src/render.ts new file mode 100644 index 0000000000..74b0255cbd --- /dev/null +++ b/packages/jobs/tool-jobs/src/render.ts @@ -0,0 +1,80 @@ +/** + * Model-facing rendering of registry reads: the consuming delta as the + * shell tools have always shown it (stdout, then one marked stderr section), + * the `[status: …]` line, and the public job projection the tool schemas + * expose. + * @module @deepseek-ai/dsh-tool-jobs/render + */ + +import type { JobChunk, JobView } from '@deepseek-ai/dsh-jobs' + +/** Job state safe for model-authored programs; ownership and offsets are omitted. */ +export interface PublicJobSnapshot { + id: string + kind: string + label: string + status: JobView['status'] + /** The live progress line while running, the terminal reason once settled. */ + detail?: string + startedAt: number + finishedAt?: number +} + +/** + * The one-line qualifier the model reads beside a status: live progress while + * the job runs, the terminal reason once it settled. + * @param job - the job projection. + * @returns the qualifier, or undefined when the job carries neither. + */ +export function jobDetail(job: Pick): string | undefined { + return job.progress ?? job.detail +} + +/** + * Remove ownership, offsets, and limits from a registry projection. + * @param job - the registry projection. + * @returns the model-safe projection. + */ +export function publicJob(job: JobView): PublicJobSnapshot { + const detail = jobDetail(job) + return { + id: job.id, + kind: job.kind, + label: job.label, + status: job.status, + ...detail !== undefined ? { detail } : {}, + startedAt: job.startedAt, + ...job.finishedAt !== undefined ? { finishedAt: job.finishedAt } : {}, + } +} + +/** + * Render generic status with optional detail. + * @param snapshot - job state to render. + * @returns a bracketed status line. + */ +export function statusLine(snapshot: Pick): string { + return snapshot.detail !== undefined + ? `[status: ${snapshot.status}, ${snapshot.detail}]` + : `[status: ${snapshot.status}]` +} + +/** + * Render one consuming read for the model: stdout and unlabeled chunks in + * order, then every stderr chunk in one `[stderr]` section, exactly as the + * shell tools render a foreground result. `log` chunks are producer + * narration for observers and never reach the model. A lossy read — the + * cursor fell behind the ring's retention — ends with a dropped-output + * notice. + * @param chunks - the chunks since the model cursor, in offset order. + * @param lossy - whether bytes before `chunks` were evicted unread. + * @returns the delta text, possibly empty. + */ +export function renderModelDelta(chunks: readonly JobChunk[], lossy: boolean): string { + const out = chunks.filter(chunk => chunk.channel === undefined || chunk.channel === 'stdout').map(chunk => chunk.text).join('') + const err = chunks.filter(chunk => chunk.channel === 'stderr').map(chunk => chunk.text).join('') + const separator = out.length > 0 && !out.endsWith('\n') ? '\n' : '' + const body = out + (err.length > 0 ? `${separator}[stderr]\n${err}` : '') + if (!lossy) return body + return `${body}${body.length > 0 && !body.endsWith('\n') ? '\n' : ''}[some output was dropped from memory before this read]` +} diff --git a/packages/jobs/tool-jobs/tests/tool-jobs.spec.ts b/packages/jobs/tool-jobs/tests/tool-jobs.spec.ts index 4c6a81e48a..6c792226d4 100644 --- a/packages/jobs/tool-jobs/tests/tool-jobs.spec.ts +++ b/packages/jobs/tool-jobs/tests/tool-jobs.spec.ts @@ -10,21 +10,26 @@ import { SessionId } from '@deepseek-ai/dsh-session' import { bindScopeParent, createScope, scopeOf } from '@deepseek-ai/dsh-scope' import { JobId } from '@deepseek-ai/dsh-jobs' import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' -import type { JobHooks, JobOutcome, JobSnapshot, JobStart } from '@deepseek-ai/dsh-jobs' +import type { JobAppendOptions, JobHandle, JobHooks, JobOutcome, JobSpec, JobView } from '@deepseek-ai/dsh-jobs' import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs' -import { statusLine } from '@deepseek-ai/dsh-tool-jobs' +import { publicJob, renderModelDelta, statusLine } from '@deepseek-ai/dsh-tool-jobs' const testToolSignal = new AbortController().signal const agentRegistryDisposers = new WeakMap void>() const agentScopeFibers = new WeakMap Promise }>() -async function setup(config: ToolTasks.Config = {}) { +/** Registry knobs a test may narrow; every producer here pushes, so the pump stays idle. */ +interface RegistryConfig { + retainBytes?: number +} + +async function setup(config: ToolTasks.Config = {}, registry: RegistryConfig = {}) { const ctx = new Context() await ctx.plugin(SystemPrompt) await ctx.plugin(ToolRuntime) const agentsFiber = await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalJobRegistry) + await ctx.plugin(LocalJobRegistry, registry) const toolsFiber = await ctx.plugin(ToolTasks, config) return { ctx, agentsFiber, toolsFiber } } @@ -70,9 +75,13 @@ async function disposeAgentScope(agent: Agent): Promise { await fiber.dispose() } -/** A controllable producer start-spec (settle `done` on demand, record cancels). */ -function producer(overrides: Partial & JobHooks> = {}) { +/** + * A controllable producer spec: pushes output and progress through the handle + * the registry hands its starter, settles `done` on demand, records cancels. + */ +function producer(overrides: Partial & JobHooks> = {}) { let settle!: (outcome: JobOutcome) => void + let handle: JobHandle | undefined const cancels: (string | undefined)[] = [] const { kind = 'bash', label = 'sleep 60', owner, outputLimitBytes, ...hookOverrides } = overrides const hooks: JobHooks = { @@ -80,14 +89,24 @@ function producer(overrides: Partial & JobHooks> = {}) { done: new Promise((res) => { settle = res }), ...hookOverrides, } - const spec: JobStart = { + const spec: JobSpec = { kind, label, ...owner !== undefined ? { owner } : {}, ...outputLimitBytes !== undefined ? { outputLimitBytes } : {}, - run: () => hooks, + run: (job) => { handle = job; return hooks }, + } + const started = (): JobHandle => { + if (handle === undefined) throw new Error('producer not started') + return handle + } + return { + spec, + settle, + cancels, + append: (text: string, options?: JobAppendOptions) => { started().append(text, options) }, + progress: (line: string) => { started().updateProgress(line) }, } - return { spec, settle, cancels } } let callCounter = 0 @@ -104,7 +123,7 @@ const tick = () => new Promise(r => setTimeout(r, 0)) /** Start and settle `count` owned jobs one at a time, letting each notice land. */ async function settleTasks(ctx: Context, owner: Agent, count: number): Promise { for (let i = 0; i < count; i += 1) { - const p = producer({ owner }) + const p = producer({ owner: owner.id }) ctx.jobs.start(p.spec) p.settle({ status: 'completed' }) await tick() @@ -119,10 +138,18 @@ describe('tool-jobs setup', () => { expect(() => ctx.jobs.start(producer().spec)).toThrow('no job controller serves this agent') }) + it('leaves with the agent registry it resolves owners through', async () => { + const { ctx, agentsFiber } = await setup() + await agentsFiber.dispose() + expect(ctx.tools.get('job_output')).toBeUndefined() + expect(() => ctx.jobs.start(producer().spec)).toThrow('no job controller serves this agent') + }) + it('rejects a config whose default wait exceeds the cap', async () => { const ctx = new Context() await ctx.plugin(SystemPrompt) await ctx.plugin(ToolRuntime) + await ctx.plugin(AgentRegistry) await ctx.plugin(LocalJobRegistry) await expect(ctx.plugin(ToolTasks, { waitTimeoutMs: 100, maxWaitTimeoutMs: 50 })) .rejects.toThrow('waitTimeoutMs (100) exceeds maxWaitTimeoutMs (50)') @@ -141,6 +168,7 @@ describe('tool-jobs setup', () => { const ctx = new Context() await ctx.plugin(SystemPrompt) await ctx.plugin(ToolRuntime) + await ctx.plugin(AgentRegistry) await ctx.plugin(LocalJobRegistry) try { await ctx.plugin(ToolTasks, { maxConsecutiveWakes }) @@ -158,9 +186,35 @@ describe('tool-jobs setup', () => { }) it('renders status lines with and without producer detail', () => { - const base = { id: 'bash-1', kind: 'bash', label: 'x', startedAt: 0, reported: false } as unknown as JobSnapshot - expect(statusLine({ ...base, status: 'running' })).toBe('[status: running]') - expect(statusLine({ ...base, status: 'completed', detail: 'exit code: 0' })).toBe('[status: completed, exit code: 0]') + expect(statusLine({ status: 'running' })).toBe('[status: running]') + expect(statusLine({ status: 'completed', detail: 'exit code: 0' })).toBe('[status: completed, exit code: 0]') + }) + + it('projects the public job: live progress or terminal detail, never ownership or offsets', () => { + const live: JobView = { + id: JobId('bash-1'), kind: 'bash', label: 'x', owner: SessionId('sess-1'), outputLimitBytes: 8, + status: 'running', progress: '3/10 files', startedAt: 5, output: { total: 12, earliest: 0 }, + } + expect(publicJob(live)).toEqual({ id: 'bash-1', kind: 'bash', label: 'x', status: 'running', detail: '3/10 files', startedAt: 5 }) + const settled: JobView = { + id: JobId('bash-1'), kind: 'bash', label: 'x', status: 'completed', detail: 'exit code: 0', + startedAt: 5, finishedAt: 9, output: { total: 12, earliest: 0 }, + } + expect(publicJob(settled)).toEqual({ id: 'bash-1', kind: 'bash', label: 'x', status: 'completed', detail: 'exit code: 0', startedAt: 5, finishedAt: 9 }) + }) + + it('renders a model delta as stdout, one stderr section, and a dropped-output notice', () => { + expect(renderModelDelta([], false)).toBe('') + expect(renderModelDelta([], true)).toBe('[some output was dropped from memory before this read]') + expect(renderModelDelta([ + { at: 0, text: 'a' }, + { at: 1, text: 'e1\n', channel: 'stderr' }, + { at: 4, text: 'narration', channel: 'log' }, + { at: 13, text: 'b', channel: 'stdout' }, + { at: 14, text: 'e2', channel: 'stderr' }, + ], false)).toBe('ab\n[stderr]\ne1\ne2') + expect(renderModelDelta([{ at: 0, text: 'tail' }], true)).toBe('tail\n[some output was dropped from memory before this read]') + expect(renderModelDelta([{ at: 0, text: 'line\n' }], true)).toBe('line\n[some output was dropped from memory before this read]') }) it('applies the built-in wait bounds when apply() receives a bare config', async () => { @@ -169,6 +223,7 @@ describe('tool-jobs setup', () => { const ctx = new Context() await ctx.plugin(SystemPrompt) await ctx.plugin(ToolRuntime) + await ctx.plugin(AgentRegistry) await ctx.plugin(LocalJobRegistry) ToolTasks.apply(ctx, {}) expect(ctx.tools.get('job_output')).toBeDefined() @@ -179,8 +234,9 @@ describe('tool-jobs setup', () => { describe('job_output', () => { it('reads a consuming delta with a trailing status line', async () => { const { ctx } = await setup() - const chunks = ['line one\n', ''] - ctx.jobs.start(producer({ readOutput: () => chunks.shift() ?? '' }).spec) + const p = producer() + ctx.jobs.start(p.spec) + p.append('line one\n') // A body already ending in a newline gets no doubled separator. const first = await call(ctx, 'job_output', { job_id: 'bash-1' }) @@ -190,29 +246,75 @@ describe('job_output', () => { text: 'line one\n', job: { id: 'bash-1', kind: 'bash', label: 'sleep 60', status: 'running' }, }) - expect(firstValue.job).not.toHaveProperty('ownerSession') - expect(firstValue.job).not.toHaveProperty('reported') + expect(firstValue.job).not.toHaveProperty('owner') + expect(firstValue.job).not.toHaveProperty('output') expect(text(first)).toBe('line one\n[status: running]') expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('(no new output)\n[status: running]') }) - it('returns the final output of a settled final-output job', async () => { + it('renders stderr in a trailing section and never shows log narration', async () => { + const { ctx } = await setup() + const p = producer() + ctx.jobs.start(p.spec) + p.append('out\n') + p.append('warn\n', { channel: 'stderr' }) + p.append('observer-only narration', { channel: 'log' }) + expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('out\n[stderr]\nwarn\n[status: running]') + expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('(no new output)\n[status: running]') + }) + + it('shows live progress beside the status until settlement replaces it with the terminal detail', async () => { + const { ctx } = await setup() + const p = producer() + ctx.jobs.start(p.spec) + p.progress('3/10 files') + expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('(no new output)\n[status: running, 3/10 files]') + p.settle({ status: 'completed', detail: 'exit code: 0' }) + await tick() + expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('(no new output)\n[status: completed, exit code: 0]') + }) + + it('flags a read whose cursor fell behind the ring', async () => { + const { ctx } = await setup({}, { retainBytes: 16 }) + const p = producer() + ctx.jobs.start(p.spec) + p.append('x'.repeat(40)) + const first = text(await call(ctx, 'job_output', { job_id: 'bash-1' })) + expect(first).toContain('[some output was dropped from memory before this read]') + expect(first).toContain('[status: running]') + expect(first).not.toContain('x'.repeat(17)) + // The cursor now sits at the ring's end: the next read is clean. + expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('(no new output)\n[status: running]') + }) + + it('returns the result of a settled job exactly once, after the pending delta', async () => { const { ctx } = await setup() const p = producer({ kind: 'subagent', label: 'research' }) ctx.jobs.start(p.spec) expect(text(await call(ctx, 'job_output', { job_id: 'subagent-1' }))).toBe('(no new output)\n[status: running]') - p.settle({ status: 'completed', detail: 'completed', output: 'the answer' }) + p.append('partial') + p.settle({ status: 'completed', detail: 'completed', result: 'the answer' }) await tick() - expect(text(await call(ctx, 'job_output', { job_id: 'subagent-1' }))).toBe('the answer\n[status: completed, completed]') + expect(text(await call(ctx, 'job_output', { job_id: 'subagent-1' }))).toBe('partial\nthe answer\n[status: completed, completed]') + expect(text(await call(ctx, 'job_output', { job_id: 'subagent-1' }))).toBe('(no new output)\n[status: completed, completed]') + }) + + it('keeps a newline-terminated delta and the result on separate lines', async () => { + const { ctx } = await setup() + const p = producer({ kind: 'subagent', label: 'research' }) + ctx.jobs.start(p.spec) + p.append('progress log\n') + p.settle({ status: 'completed', result: 'the answer' }) + await tick() + expect(text(await call(ctx, 'job_output', { job_id: 'subagent-1' }))).toBe('progress log\nthe answer\n[status: completed]') }) it('applies a producer limit to the complete body and status result', async () => { const { ctx } = await setup() - ctx.jobs.start(producer({ - outputLimitBytes: 48, - readOutput: () => '界'.repeat(100), - }).spec) + const p = producer({ outputLimitBytes: 48 }) + ctx.jobs.start(p.spec) + p.append('界'.repeat(100)) const output = text(await call(ctx, 'job_output', { job_id: 'bash-1' })) expect(Buffer.byteLength(output)).toBeLessThanOrEqual(48) @@ -221,24 +323,21 @@ describe('job_output', () => { it('preserves empty and newline-terminated output under a producer limit', async () => { const { ctx } = await setup() - const chunks = ['', 'line\n'] - ctx.jobs.start(producer({ - outputLimitBytes: 64, - readOutput: () => chunks.shift() ?? '', - }).spec) + const p = producer({ outputLimitBytes: 64 }) + ctx.jobs.start(p.spec) expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))) .toBe('(no new output)\n[status: running]') + p.append('line\n') expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))) .toBe('line\n[status: running]') }) it('bounds post-policy output without restoring the canonical status rendering', async () => { const { ctx } = await setup() - ctx.jobs.start(producer({ - outputLimitBytes: 64, - readOutput: () => 'canonical output', - }).spec) + const p = producer({ outputLimitBytes: 64 }) + ctx.jobs.start(p.spec) + p.append('canonical output') ctx.on('tools/post-execute', (exec, _result, next) => { if (exec.name !== 'job_output') return next() return Promise.resolve({ kind: 'accept', content: [{ type: 'text', text: 'p'.repeat(1_000) }] }) @@ -250,17 +349,30 @@ describe('job_output', () => { expect(text(result)).not.toContain('[status: running]') }) - it('applies a producer limit to a normalized read failure', async () => { + it('does not double a truncation marker a policy already appended', async () => { const { ctx } = await setup() - ctx.jobs.start(producer({ - outputLimitBytes: 64, - readOutput: () => { throw new Error('read failed: '.repeat(100)) }, - }).spec) + ctx.jobs.start(producer({ outputLimitBytes: 64 }).spec) + ctx.on('tools/post-execute', (exec, _result, next) => { + if (exec.name !== 'job_output') return next() + return Promise.resolve({ kind: 'accept', content: [{ type: 'text', text: `${'z'.repeat(1_000)}\n[result truncated]` }] }) + }) const result = await call(ctx, 'job_output', { job_id: 'bash-1' }) - expect(result.isError).toBe(true) expect(Buffer.byteLength(text(result))).toBeLessThanOrEqual(64) - expect(text(result)).toContain('[result truncated]') + expect(text(result).match(/\[result truncated\]/g)).toHaveLength(1) + }) + + it('refuses a job owned by another session as an errored result', async () => { + const { ctx } = await setup() + const alice = fakeAgent(ctx, 'sess-alice') + ctx.jobs.start(producer({ owner: alice.id }).spec) + const bob = fakeAgent(ctx, 'sess-bob') + + const result = await call(ctx, 'job_output', { job_id: 'bash-1' }, bob) + expect(result.isError).toBe(true) + expect(text(result)).toContain('belongs to another session') + expect((await call(ctx, 'job_output', { job_id: 'bash-1' })).isError).toBe(true) + expect((await call(ctx, 'job_output', { job_id: 'bash-1' }, alice)).isError).toBe(false) }) it('bounds pre-, around-, and post-execute policy outcomes and failures', async () => { @@ -325,7 +437,7 @@ describe('job_output', () => { ctx.jobs.start(p.spec) const pending = call(ctx, 'job_output', { job_id: 'subagent-1', wait: true }) - p.settle({ status: 'completed', output: 'done deal' }) + p.settle({ status: 'completed', result: 'done deal' }) expect(text(await pending)).toBe('done deal\n[status: completed]') }) @@ -354,9 +466,9 @@ describe('job_list', () => { expect(text(await call(ctx, 'job_list', {}))).toBe('(no background jobs)') const alice = fakeAgent(ctx, 'sess-alice') - ctx.jobs.start(producer({ owner: alice, label: 'pnpm test' }).spec) + ctx.jobs.start(producer({ owner: alice.id, label: 'pnpm test' }).spec) ctx.jobs.start(producer({ kind: 'subagent', label: 'open research' }).spec) - const p = producer({ owner: alice, label: 'build' }) + const p = producer({ owner: alice.id, label: 'build' }) ctx.jobs.start(p.spec) p.settle({ status: 'completed', detail: 'exit code: 0' }) await tick() @@ -368,8 +480,8 @@ describe('job_list', () => { expect(listedValue[0]).toMatchObject({ id: 'bash-1', kind: 'bash', label: 'pnpm test', status: 'running' }) expect(listedValue[2]).toMatchObject({ id: 'bash-2', kind: 'bash', label: 'build', status: 'completed', detail: 'exit code: 0' }) for (const job of listedValue) { - expect(job).not.toHaveProperty('ownerSession') - expect(job).not.toHaveProperty('reported') + expect(job).not.toHaveProperty('owner') + expect(job).not.toHaveProperty('output') } expect(text(listed)).toBe([ 'bash-1 [bash] running — pnpm test', @@ -395,8 +507,8 @@ describe('job_kill', () => { outcome: 'cancellation-requested', job: { id: 'bash-1', kind: 'bash', label: 'sleep 60', status: 'stopping' }, }) - expect(killValue.job).not.toHaveProperty('ownerSession') - expect(killValue.job).not.toHaveProperty('reported') + expect(killValue.job).not.toHaveProperty('owner') + expect(killValue.job).not.toHaveProperty('output') expect(text(result)).toBe('requested cancellation of job bash-1') expect(p.cancels).toEqual(['superseded']) }) @@ -422,7 +534,7 @@ describe('job_kill', () => { expect(result.isError).toBe(true) expect(Buffer.byteLength(text(result))).toBeLessThanOrEqual(64) expect(text(result)).toContain('[result truncated]') - expect(ctx.jobs.get(JobId('bash-1'))).toMatchObject({ status: 'running', reported: false }) + expect(ctx.jobs.visibleTo().get(JobId('bash-1')).status).toBe('running') }) it('bounds single-text post policy while preserving structured policy results', async () => { @@ -470,9 +582,9 @@ describe('job_kill', () => { it('reports an already-finished job without consuming its pending delta', async () => { const { ctx } = await setup() - let delta = 'unread tail' - const p = producer({ readOutput: () => { const d = delta; delta = ''; return d } }) + const p = producer() ctx.jobs.start(p.spec) + p.append('unread tail') p.settle({ status: 'completed', detail: 'exit code: 0' }) await tick() @@ -483,7 +595,7 @@ describe('job_kill', () => { job: { id: 'bash-1', kind: 'bash', label: 'sleep 60', status: 'completed', detail: 'exit code: 0' }, }) expect(text(killed)).toBe('job bash-1 had already finished [status: completed, exit code: 0]') - // The kill described the job via a non-consuming snapshot: the delta is intact. + // The kill described the job via a non-consuming projection: the delta is intact. expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }))).toBe('unread tail\n[status: completed, exit code: 0]') }) @@ -508,9 +620,9 @@ describe('tool-owned UI presentation (presentCall)', () => { describe('completion notices across scoped mounts', () => { /** * Two agent presets mounting `tool-jobs` over ONE host registry: each mount - * registers its own `onJobDone` listener on the shared service, and - * `settle()` broadcasts one snapshot to every listener with no scope filter. - * Only the mount whose scope the owner belongs to may deliver the notice. + * subscribes with `{ owners: 'scope' }`, which the registry files into the + * mount's own scope layer and reaches along the owner's scope chain. Only + * the mount whose scope the owner belongs to sees the settlement. */ it('delivers one notice from the owning scope when two mounts share the registry', async () => { const ctx = new Context() @@ -539,9 +651,7 @@ describe('completion notices across scoped mounts', () => { const dispose = ctx.agents.register(owner) try { - // No waiter: `settle()` leaves `reported` false, which is the only path - // that reaches the notice listeners at all. - const p = producer({ owner, label: 'pnpm test' }) + const p = producer({ owner: owner.id, label: 'pnpm test' }) ctx.jobs.start(p.spec) p.settle({ status: 'completed', detail: 'exit code: 0' }) await tick() @@ -559,7 +669,7 @@ describe('completion notice delivery', () => { const inject = vi.fn() const followup = vi.fn() const owner = fakeAgent(ctx, 'sess-1', { inject, followup, status: 'idle' }) - const p = producer({ owner, label: 'pnpm test' }) + const p = producer({ owner: owner.id, label: 'pnpm test' }) ctx.jobs.start(p.spec) p.settle({ status: 'completed', detail: 'exit code: 0' }) @@ -573,7 +683,7 @@ describe('completion notice delivery', () => { const inject = vi.fn() const followup = vi.fn() const owner = fakeAgent(ctx, 'sess-1', { inject, followup, status: 'idle' }) - const p = producer({ owner }) + const p = producer({ owner: owner.id }) ctx.jobs.start(p.spec) p.settle({ status: 'completed' }) @@ -621,15 +731,15 @@ describe('completion notice delivery', () => { ctx.jobs.start({ kind: 'bash', label: 'sleep 60', - owner, + owner: owner.id, run: () => ({ cancel() { settle({ status: 'killed' }) }, done: new Promise((res) => { settle = res }), }), }) - // Disposal cancels and settles the owned job. Waking here would spend a - // model request on an agent the host is destroying, once per tree layer. + // Disposal cancels and settles the owned job with a teardown cause. Waking + // here would spend a model request on an agent the host is destroying. await disposeAgentScope(owner) await tick() expect(followup).not.toHaveBeenCalled() @@ -645,17 +755,16 @@ describe('completion notice delivery', () => { ctx.jobs.start({ kind: 'bash', label: 'broken producer', - owner, + owner: owner.id, run: () => ({ cancel() { throw new Error('cancel boom') }, done: new Promise(() => {}), }), }) - // The registry force-fails the record instead of deadlocking. That path - // settles the job too, so it must claim the report as the ordinary - // teardown cancel does — otherwise a throwing producer is all it takes to - // spend a model request on an owner being destroyed. + // The registry force-fails the record instead of deadlocking. That + // settlement also announces a teardown cause, so a throwing producer is + // not enough to spend a model request on an owner being destroyed. await disposeAgentScope(owner) await tick() expect(warn).toHaveBeenCalledWith(expect.stringContaining('work may be orphaned')) @@ -682,11 +791,11 @@ describe('completion notice delivery', () => { }) describe('completion notices', () => { - it('injects a notice into the owning agent when an unreported job settles', async () => { + it('injects a notice into the owning agent when an uncollected job settles', async () => { const { ctx } = await setup() const inject = vi.fn() const owner = fakeAgent(ctx, 'sess-1', { inject }) - const p = producer({ owner, label: 'pnpm test' }) + const p = producer({ owner: owner.id, label: 'pnpm test' }) ctx.jobs.start(p.spec) p.settle({ status: 'completed', detail: 'exit code: 0' }) @@ -710,7 +819,7 @@ describe('completion notices', () => { const inject = vi.fn() const owner = fakeAgent(ctx, 'sess-1', { inject }) const first = producer({ - owner, + owner: owner.id, kind: 'subagent', label: 'x'.repeat(1_000), outputLimitBytes: 61, @@ -737,7 +846,7 @@ describe('completion notices', () => { ) const second = producer({ - owner, + owner: owner.id, kind: 'subagent', label: 'x'.repeat(1_000), outputLimitBytes: 80, @@ -764,7 +873,7 @@ describe('completion notices', () => { const inject = vi.fn() const owner = fakeAgent(ctx, 'sess-1', { inject }) const target = producer({ - owner, + owner: owner.id, kind: 'pty-send', label: 'x'.repeat(1_000), outputLimitBytes: 64, @@ -784,8 +893,8 @@ describe('completion notices', () => { const { ctx } = await setup() const inject = vi.fn() const owner = fakeAgent(ctx, 'sess-1', { inject }) - const tiny = producer({ owner, kind: 'pty-send', label: 'x'.repeat(100), outputLimitBytes: 8 }) - const short = producer({ owner, kind: 'pty-send', label: 'x'.repeat(100), outputLimitBytes: 32 }) + const tiny = producer({ owner: owner.id, kind: 'pty-send', label: 'x'.repeat(100), outputLimitBytes: 8 }) + const short = producer({ owner: owner.id, kind: 'pty-send', label: 'x'.repeat(100), outputLimitBytes: 32 }) ctx.jobs.start(tiny.spec) ctx.jobs.start(short.spec) @@ -805,7 +914,7 @@ describe('completion notices', () => { const { ctx } = await setup() const inject = vi.fn() const owner = fakeAgent(ctx, 'sess-1', { inject }) - const p = producer({ owner }) + const p = producer({ owner: owner.id }) ctx.jobs.start(p.spec) await call(ctx, 'job_kill', { job_id: 'bash-1' }, owner) @@ -818,15 +927,55 @@ describe('completion notices', () => { const { ctx } = await setup() const inject = vi.fn() const owner = fakeAgent(ctx, 'sess-1', { inject }) - const p = producer({ owner, kind: 'subagent' }) + const p = producer({ owner: owner.id, kind: 'subagent' }) ctx.jobs.start(p.spec) const pending = call(ctx, 'job_output', { job_id: 'subagent-1', wait: true }, owner) - p.settle({ status: 'completed', output: 'answer' }) + p.settle({ status: 'completed', result: 'answer' }) expect(text(await pending)).toContain('answer') + await tick() expect(inject).not.toHaveBeenCalled() }) + it('withdraws the wait claim when the wait times out, so the later settlement still notifies', async () => { + const { ctx } = await setup({ waitTimeoutMs: 10, maxWaitTimeoutMs: 20 }) + const inject = vi.fn() + const owner = fakeAgent(ctx, 'sess-1', { inject }) + const p = producer({ owner: owner.id }) + ctx.jobs.start(p.spec) + + expect(text(await call(ctx, 'job_output', { job_id: 'bash-1', wait: true }, owner))).toBe('(no new output)\n[status: running]') + p.settle({ status: 'completed' }) + await tick() + expect(inject).toHaveBeenCalledTimes(1) + }) + + it('withdraws the wait claim when the caller aborts the wait', async () => { + const { ctx } = await setup() + const inject = vi.fn() + const owner = fakeAgent(ctx, 'sess-1', { inject }) + const p = producer({ owner: owner.id }) + ctx.jobs.start(p.spec) + + const aborter = new AbortController() + const pending = ctx.tools.execute({ + signal: aborter.signal, + callId: ToolCallId('call-aborted-wait'), + name: 'job_output', + arguments: { job_id: 'bash-1', wait: true }, + agent: owner, + }) + await tick() + aborter.abort() + const result = await pending + expect(result.isError).toBe(true) + expect(text(result)).toContain('wait aborted') + + p.settle({ status: 'completed' }) + await tick() + expect(inject).toHaveBeenCalledTimes(1) + }) + it('drops the notice for unowned jobs without throwing', async () => { const { ctx } = await setup() // Unowned: settles with nobody to notify — nothing throws. @@ -836,31 +985,45 @@ describe('completion notices', () => { await tick() }) - it('does not route an old owner completion notice to a same-session replacement', async () => { + it('delivers to the agent currently registered for the owner session', async () => { const { ctx } = await setup() - // Delivery into a tearing-down owner is a plain inject: the loop has no - // terminal state, so the notice lands in the old owner's (detached) - // session instead of throwing or re-routing. + // The settlement names the owner session; the notice goes to whichever + // agent holds that session when the job settles, which can read the job + // through the same session id. const oldInject = vi.fn() const oldOwner = fakeAgent(ctx, 'shared', { inject: oldInject }) - const p = producer({ owner: oldOwner }) + const p = producer({ owner: oldOwner.id }) ctx.jobs.start(p.spec) detachAgent(oldOwner) const replacementInject = vi.fn() - fakeAgent(ctx, 'shared', { inject: replacementInject }) + const replacement = fakeAgent(ctx, 'shared', { inject: replacementInject }) p.settle({ status: 'completed' }) await tick() - expect(oldInject).toHaveBeenCalledTimes(1) - expect(replacementInject).not.toHaveBeenCalled() + expect(oldInject).not.toHaveBeenCalled() + expect(replacementInject).toHaveBeenCalledTimes(1) + expect(text(await call(ctx, 'job_output', { job_id: 'bash-1' }, replacement))).toBe('(no new output)\n[status: completed]') + }) + + it('drops the notice when the owner session has no live agent at settlement', async () => { + const { ctx } = await setup() + const inject = vi.fn() + const owner = fakeAgent(ctx, 'sess-1', { inject }) + const p = producer({ owner: owner.id }) + ctx.jobs.start(p.spec) + + detachAgent(owner) + p.settle({ status: 'completed' }) + await tick() + expect(inject).not.toHaveBeenCalled() }) it('surfaces an inject failure through listener containment (a real bug must be visible)', async () => { const { ctx } = await setup() const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {}) const owner = fakeAgent(ctx, 'sess-1', { inject: () => { throw new Error('unexpected inject bug') } }) - const p = producer({ owner }) + const p = producer({ owner: owner.id }) ctx.jobs.start(p.spec) p.settle({ status: 'completed' }) await tick() @@ -868,23 +1031,4 @@ describe('completion notices', () => { // registry's per-listener containment — visible, not swallowed. expect(warn).toHaveBeenCalledWith(expect.stringContaining('unexpected inject bug')) }) - - it('keeps using the exact owner after the agent registry is gone', async () => { - const { ctx, agentsFiber } = await setup() - const inject = vi.fn() - const owner = fakeAgent(ctx, 'sess-1', { inject }) - - // Settlement must not depend on a later registry lookup: the exact owner - // supplied at start remains the destination while its own scope is live. - const p1 = producer({ owner }) - ctx.jobs.start(p1.spec) - const p2 = producer({ owner }) - ctx.jobs.start(p2.spec) - - await agentsFiber.dispose() - p1.settle({ status: 'completed' }) - p2.settle({ status: 'failed' }) - await tick() - expect(inject).toHaveBeenCalledTimes(2) - }) }) From 053d302210a2e1d9c30c6efa0ae9530e8c8c313e Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 16:30:57 +0800 Subject: [PATCH 032/100] refactor(shell tools): hand the job registry pull sources and terminal outcomes tool-bash and tool-pwsh no longer render their own background reads. processSources() wraps the process's observed offset readers as registry pull sources, pumped at dsh-jobs-local's pumpPollMs, and processOutcome() folds the settled sandbox facts into the terminal detail. observe.ts and the recordPollMs config field are gone; READMEs and pairings follow. --- packages/shell/tool-bash/README.i18n.yaml | 4 +- packages/shell/tool-bash/README.md | 2 +- packages/shell/tool-bash/README.zh.md | 2 +- packages/shell/tool-bash/src/background.ts | 67 +++++++-- packages/shell/tool-bash/src/index.ts | 36 ++--- packages/shell/tool-bash/src/observe.ts | 47 ------- packages/shell/tool-bash/src/render.ts | 34 +---- .../{observe.spec.ts => background.spec.ts} | 127 ++++++++---------- packages/shell/tool-bash/tests/tools.spec.ts | 62 ++------- packages/shell/tool-pwsh/README.i18n.yaml | 4 +- packages/shell/tool-pwsh/README.md | 2 +- packages/shell/tool-pwsh/README.zh.md | 2 +- packages/shell/tool-pwsh/src/background.ts | 69 ++++++++-- packages/shell/tool-pwsh/src/index.ts | 36 ++--- packages/shell/tool-pwsh/src/observe.ts | 49 ------- packages/shell/tool-pwsh/src/render.ts | 32 +---- .../{observe.spec.ts => background.spec.ts} | 71 +++++----- packages/shell/tool-pwsh/tests/tools.spec.ts | 79 +++-------- 18 files changed, 280 insertions(+), 445 deletions(-) delete mode 100644 packages/shell/tool-bash/src/observe.ts rename packages/shell/tool-bash/tests/{observe.spec.ts => background.spec.ts} (51%) delete mode 100644 packages/shell/tool-pwsh/src/observe.ts rename packages/shell/tool-pwsh/tests/{observe.spec.ts => background.spec.ts} (73%) diff --git a/packages/shell/tool-bash/README.i18n.yaml b/packages/shell/tool-bash/README.i18n.yaml index 57f2951bfa..8832f9e8ee 100644 --- a/packages/shell/tool-bash/README.i18n.yaml +++ b/packages/shell/tool-bash/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/shell/tool-bash/README.md -README.md: 50047a5fe0d69da1feb38f75ada27595b88fa5c5 -README.zh.md: c74a45561298defb4baa5b34be7cebc1cdfbc744 +README.md: c824ee897162e8ca1b1e616f3dcace43e58f8c9a +README.zh.md: f6240153855edd2ab4eb12e8038e2108f0842b3b diff --git a/packages/shell/tool-bash/README.md b/packages/shell/tool-bash/README.md index 50047a5fe0..c824ee8971 100644 --- a/packages/shell/tool-bash/README.md +++ b/packages/shell/tool-bash/README.md @@ -55,7 +55,7 @@ The tool executes `bash -c ` and returns the combined output. Commands ### Running long commands in the background -Passing `run_in_background: true` returns a job id immediately and no timeout applies; the command keeps running while the agent works on something else. The agent reads its output with `job_output` (non-blocking unless `wait: true`), lists jobs with `job_list`, and stops it with `job_kill`; a finished job notifies the owning agent in-session. Background support needs the generic job runtime (`dsh-jobs-local`) and its control tools (`dsh-tool-jobs`) mounted. The background job declares an observation record: the run's non-consuming `observed` readers are pumped into it at `recordPollMs` (default 150), so the Web client streams live output without touching the job's consuming cursor; a pump failure is logged and swallowed while the job runs on. The record is a best-effort live preview: stdout and stderr are copied per poll round, so writes the two streams made inside one `recordPollMs` window appear stdout first rather than in write order. +Passing `run_in_background: true` returns a job id immediately and no timeout applies; the command keeps running while the agent works on something else. The agent reads its output with `job_output` (non-blocking unless `wait: true`), lists jobs with `job_list`, and stops it with `job_kill`; a finished job notifies the owning agent in-session. Background support needs the generic job runtime (`dsh-jobs-local`) and its control tools (`dsh-tool-jobs`) mounted. The background job hands the run's non-consuming `observed` readers to the job registry as pull sources; the registry pumps them into the job's output ring at its own cadence (`pumpPollMs` on `dsh-jobs-local`), so the Web client streams live output and the model's `job_output` reads consume the same bytes through a separate cursor. A reader that throws is logged once and its stream stops; the job runs on to its own settlement. The ring is a best-effort live preview: stdout and stderr are copied per poll round, so writes the two streams made inside one poll window appear stdout first rather than in write order. ### Sandboxed execution and escalation diff --git a/packages/shell/tool-bash/README.zh.md b/packages/shell/tool-bash/README.zh.md index c74a455612..f624015385 100644 --- a/packages/shell/tool-bash/README.zh.md +++ b/packages/shell/tool-bash/README.zh.md @@ -55,7 +55,7 @@ kind: "package-reference" ### 后台运行长时间命令 -传入 `run_in_background: true` 会立即返回 job id,不应用超时;命令继续运行,agent 同时处理其他事情。agent 用 `job_output` 读取输出(除非 `wait: true`,否则非阻塞)、用 `job_list` 列出任务、用 `job_kill` 停止任务;完成的任务会在会话内通知拥有它的 agent。后台支持需要挂载通用任务运行时(`dsh-jobs-local`)及其控制工具(`dsh-tool-jobs`)。后台 job 声明观测 record:运行的非消费 `observed` 读取器以 `recordPollMs`(默认 150)的节奏泵入其中,使 Web 客户端在不触碰 job 消耗游标的情况下流式看到实时输出;泵失败会被记录并吞掉,job 继续运行。record 是尽力而为的实时预览:stdout 与 stderr 按轮询轮次复制,同一个 `recordPollMs` 窗口内两条流的写入会先 stdout 后 stderr 出现,而不是按写入顺序。 +传入 `run_in_background: true` 会立即返回 job id,不应用超时;命令继续运行,agent 同时处理其他事情。agent 用 `job_output` 读取输出(除非 `wait: true`,否则非阻塞)、用 `job_list` 列出任务、用 `job_kill` 停止任务;完成的任务会在会话内通知拥有它的 agent。后台支持需要挂载通用任务运行时(`dsh-jobs-local`)及其控制工具(`dsh-tool-jobs`)。后台 job 把运行的非消费 `observed` 读取器交给 job 注册表作为拉式源;注册表按自己的节奏(`dsh-jobs-local` 的 `pumpPollMs`)把它们泵入 job 的输出环,Web 客户端由此流式看到实时输出,模型的 `job_output` 读取则经另一个游标消费同一份字节。读取器抛错只记录一次,该流就此停止,job 继续跑到自己的结算。输出环是尽力而为的实时预览:stdout 与 stderr 按轮询轮次复制,同一个轮询窗口内两条流的写入会先 stdout 后 stderr 出现,而不是按写入顺序。 ### 沙箱执行与升权 diff --git a/packages/shell/tool-bash/src/background.ts b/packages/shell/tool-bash/src/background.ts index c01f91a586..dbe6d08c5e 100644 --- a/packages/shell/tool-bash/src/background.ts +++ b/packages/shell/tool-bash/src/background.ts @@ -1,27 +1,74 @@ /** - * Generic-task adaptation for background bash process handles. + * Generic-job adaptation for background bash process handles: the terminal + * outcome the registry records and the pull sources it pumps. * * @module @deepseek-ai/dsh-tool-bash/background */ -import type { ShellProcess } from '@deepseek-ai/dsh-shell' +import type { SandboxMode } from '@deepseek-ai/dsh-sandbox' +import { escalationHintMarker, sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox' +import type { ShellProcess, ShellSandboxInfo } from '@deepseek-ai/dsh-shell' +import type { JobOutcome, JobOutputSource } from '@deepseek-ai/dsh-jobs' /** - * Map a settled background process onto the generic task-outcome vocabulary: + * Sandbox facts worth the terminal detail: a runner that never ran the + * command, or a denial (with the escalation hint this composition offers). + * @param sandbox - settled sandbox facts, when this was a confined process. + * @param escalationModes - escalation targets advertised by this composition. + * @returns the markers to append, oldest first. + */ +function sandboxNotes(sandbox: ShellSandboxInfo | undefined, escalationModes: readonly SandboxMode[]): string[] { + if (sandbox?.runnerFailed) { + return [`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`] + } + if (sandbox?.denied) { + const notes = [sandboxDenialMarker(sandbox.mode)] + if (escalationModes.length > 0) notes.push(escalationHintMarker('command')) + return notes + } + return [] +} + +/** + * Map a settled background process onto the generic job-outcome vocabulary: * `killed` stays `killed` (detail: the signal when one is known), everything * else is `completed` with the exit code as detail. A nonzero command exit is - * reported, not failed, exactly like the foreground rendering. + * reported, not failed, exactly like the foreground rendering. Sandbox facts + * join the detail, since a job's terminal reason is the one line every + * reader — the model's status line, the roster row — shows. * @param proc - the settled process handle. + * @param escalationModes - escalation targets advertised by this composition. * @returns the outcome for the `ctx.jobs` registration. */ -export function processOutcome(proc: ShellProcess): { status: 'completed' | 'killed'; detail: string } { +export function processOutcome(proc: ShellProcess, escalationModes: readonly SandboxMode[] = []): JobOutcome { // TODO(background-infrastructure-outcome): widen ShellProcess with an explicit - // infrastructure-failure outcome, then map it to task `failed`. Restricted + // infrastructure-failure outcome, then map it to job `failed`. Restricted // runner failures expose sandbox.runnerFailed, but unconfined spawn failures // still alias a signal-less kill; real nonzero command exits must remain // `completed`. - if (proc.status === 'killed') { - return { status: 'killed', detail: proc.signal !== null ? `signal: ${proc.signal}` : 'killed before exit' } - } - return { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` } + const base: JobOutcome = proc.status === 'killed' + ? { status: 'killed', detail: proc.signal !== null ? `signal: ${proc.signal}` : 'killed before exit' } + : { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` } + const notes = sandboxNotes(proc.sandbox, escalationModes) + return notes.length === 0 ? base : { ...base, detail: `${base.detail}; ${notes.join(' ')}` } +} + +/** + * The process's non-consuming stream readers as registry pull sources. They + * bind lazily because the process is spawned inside the starter, after the + * registry admitted the job; a backend without offset readers degrades to no + * observation rather than an error, and the pump keeps the model's consuming + * cursor untouched. + * @param proc - the started process, once the starter has spawned it. + * @returns one source per stream, stdout first. + */ +export function processSources(proc: () => ShellProcess | undefined): JobOutputSource[] { + const source = (channel: 'stdout' | 'stderr'): JobOutputSource => ({ + channel, + read: (fromByte) => { + const reader = proc()?.observed?.[channel] + return reader === undefined ? { text: '', nextOffset: fromByte, lossy: false } : reader.readFrom(fromByte) + }, + }) + return [source('stdout'), source('stderr')] } diff --git a/packages/shell/tool-bash/src/index.ts b/packages/shell/tool-bash/src/index.ts index c4586d0b10..8abc59a2c7 100644 --- a/packages/shell/tool-bash/src/index.ts +++ b/packages/shell/tool-bash/src/index.ts @@ -22,10 +22,9 @@ import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandb import { ESCALATION_TARGETS, approveEscalation, canonicalPath, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox' import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy' import { DSH_ENV_PREFIX } from '@deepseek-ai/dsh-shell' -import type { ShellRunResult } from '@deepseek-ai/dsh-shell' -import { processOutcome } from './background.ts' -import { observeProcessRecord } from './observe.ts' -import { parseExitStatus, renderProcessRead, renderResult } from './render.ts' +import type { ShellRunResult, ShellProcess } from '@deepseek-ai/dsh-shell' +import { processOutcome, processSources } from './background.ts' +import { parseExitStatus, renderResult } from './render.ts' export const name = 'tool-bash' export const inject = ['tools', 'shell', 'systemPrompt', 'shellEnv'] @@ -34,18 +33,11 @@ export const inject = ['tools', 'shell', 'systemPrompt', 'shellEnv'] export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean - /** Poll cadence for copying background output into the job record, in milliseconds (default 150). */ - recordPollMs?: number } /** Runtime configuration schema for the bash tool plugin. */ export const Config: z = z.object({ enableRunInBackground: z.boolean().default(true), - recordPollMs: z.number() - .step(1) - .min(1) - .max(Number.MAX_SAFE_INTEGER) - .default(150), }) /** Parsed tool args; execute validates value constraints absent from ParameterSchemaSpec. */ @@ -196,7 +188,6 @@ const BACKGROUND_OUTPUT_PROPERTIES = { export function apply(ctx: Context, config: Config = {}): void { const backgroundEnabled = config.enableRunInBackground ?? true - const recordPollMs = config.recordPollMs ?? 150 const defaultMode = ctx.shell.sandboxMode const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS const sandboxPolicy: SandboxPolicyService | undefined = defaultMode === undefined ? undefined : ctx.get('sandboxPolicy') @@ -369,20 +360,21 @@ export function apply(ctx: Context, config: Config = {}): void { error.name = 'AbortError' throw error } + // The registry pumps the process's non-consuming readers into the + // job's ring; the sources bind lazily because the process is spawned + // only once admission has passed. + let proc: ShellProcess | undefined const id = jobs.start({ kind: 'bash', label: args.command, - ...exec.agent ? { owner: exec.agent } : {}, - record: true, - run: (job) => { - const proc = ctx.shell.start(ctx.shell.resolve(request)) - // The pump's final drain is folded into `done` so the record holds - // its last bytes before settlement trims and closes it. - const observed = observeProcessRecord(ctx, job, proc, recordPollMs) + ...exec.agent ? { owner: exec.agent.id } : {}, + output: processSources(() => proc), + run: () => { + const started = ctx.shell.start(ctx.shell.resolve(request)) + proc = started return { - cancel: () => void proc.kill(), - done: observed.then(() => proc.done).then(() => processOutcome(proc)), - readOutput: () => renderProcessRead(proc.readOutput(), proc.sandbox, escalationModes), + cancel: () => void started.kill(), + done: started.done.then(() => processOutcome(started, escalationModes)), } }, }) diff --git a/packages/shell/tool-bash/src/observe.ts b/packages/shell/tool-bash/src/observe.ts deleted file mode 100644 index 89a28817bc..0000000000 --- a/packages/shell/tool-bash/src/observe.ts +++ /dev/null @@ -1,47 +0,0 @@ -/** - * Record tap for background bash runs: copies the spawned process's captured - * streams into the job's observation record, so non-consuming observers (the - * Web client) see live output without touching the job's consuming - * `readOutput` cursor. Observation is strictly best-effort: absent backend - * offset readers degrade to no observation, and a pump failure is logged and - * swallowed — the job path is unaffected either way. - * The record interleaves stdout and stderr per poll round, not per write: - * output the two streams produced inside one `pollMs` window lands stdout - * first, so the panel is a live preview, not a terminal-exact transcript. - * - * @module @deepseek-ai/dsh-tool-bash/observe - */ - -import type { Context } from '@deepseek-ai/cordis' -import type { ShellProcess } from '@deepseek-ai/dsh-shell' -import { pumpJobOutput } from '@deepseek-ai/dsh-jobs' -import type { JobPumpSource, RecordingJob } from '@deepseek-ai/dsh-jobs' - -/** - * Pump the process's non-consuming offset readers into the job record until - * the run settles, then drain once more. The returned promise never rejects: - * a pump failure is logged and the record simply stops advancing, while the - * process and its job continue untouched. - * @param ctx - plugin context used for the warning log. - * @param job - the running job's producer face receiving the copied chunks. - * @param proc - the started background process handle. - * @param pollMs - producer-configured pump cadence in milliseconds. - * @returns resolves after the final drain; fold into the job's `done` chain so - * the record holds its final bytes before settlement closes it. - */ -export function observeProcessRecord( - ctx: Context, - job: RecordingJob, - proc: ShellProcess, - pollMs: number, -): Promise { - const sources: JobPumpSource[] = [] - const stdout = proc.observed?.stdout - if (stdout !== undefined) sources.push({ channel: 'stdout', read: from => stdout.readFrom(from) }) - const stderr = proc.observed?.stderr - if (stderr !== undefined) sources.push({ channel: 'stderr', read: from => stderr.readFrom(from) }) - return pumpJobOutput(job, sources, { pollMs, done: proc.done }) - .catch((error: unknown) => { - ctx.logger.warn(`record observation pump for ${job.id} failed: ${String(error)}`) - }) -} diff --git a/packages/shell/tool-bash/src/render.ts b/packages/shell/tool-bash/src/render.ts index 82403cca44..a13b8348f1 100644 --- a/packages/shell/tool-bash/src/render.ts +++ b/packages/shell/tool-bash/src/render.ts @@ -4,7 +4,7 @@ * @module @deepseek-ai/dsh-tool-bash/render */ -import type { ShellProcessRead, ShellRunResult, ShellSandboxInfo, CollectedOutput } from '@deepseek-ai/dsh-shell' +import type { ShellRunResult, CollectedOutput } from '@deepseek-ai/dsh-shell' import type { SandboxMode } from '@deepseek-ai/dsh-sandbox' import { escalationHintMarker, sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox' @@ -62,38 +62,6 @@ export function renderResult( return body + markers.join('\n') } -/** - * Shape one background-process read into the `job_output` delta the model - * sees: the incremental delta, plus the lossy-read notice (with full-stream - * spill paths) when in-memory truncation dropped unread bytes. Empty-delta - * rendering (`(no new output)`) is the generic job controller's job. - * @param read - one incremental read from the process handle. - * @param sandbox - settled sandbox facts, when this was a confined process. - * @param escalationModes - escalation targets advertised by this composition. - * @returns the delta text with any loss or sandbox notice appended. - */ -export function renderProcessRead( - read: ShellProcessRead, - sandbox?: ShellSandboxInfo, - escalationModes: readonly SandboxMode[] = [], -): string { - const notices: string[] = [] - if (read.lossy) { - const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((path): path is string => path !== undefined) - notices.push(`[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(', ') : '(unavailable)'}]`) - } - if (sandbox?.runnerFailed) { - notices.push(`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`) - } else if (sandbox?.denied) { - notices.push(sandboxDenialMarker(sandbox.mode)) - if (escalationModes.length > 0) { - notices.push(escalationHintMarker('command')) - } - } - if (notices.length === 0) return read.delta - return `${read.delta}${read.delta.length > 0 && !read.delta.endsWith('\n') ? '\n' : ''}${notices.join('\n')}` -} - /** * The exit-status parse is the shared marker-contract half of the shell-tool * rendering story, owned by `@deepseek-ai/dsh-shell` so `dsh-tool-pwsh` reuses diff --git a/packages/shell/tool-bash/tests/observe.spec.ts b/packages/shell/tool-bash/tests/background.spec.ts similarity index 51% rename from packages/shell/tool-bash/tests/observe.spec.ts rename to packages/shell/tool-bash/tests/background.spec.ts index 4586ada7a5..5862887118 100644 --- a/packages/shell/tool-bash/tests/observe.spec.ts +++ b/packages/shell/tool-bash/tests/background.spec.ts @@ -1,7 +1,7 @@ import { mkdtempSync } from 'node:fs' import { tmpdir } from 'node:os' import { join } from 'node:path' -import { describe, expect, it, vi } from 'vitest' +import { describe, expect, it } from 'vitest' import { Context } from '@deepseek-ai/cordis' import { ToolCallId } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' @@ -10,31 +10,31 @@ import ToolRuntime from '@deepseek-ai/dsh-tools' import AgentRegistry from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' -import type { JobId, RecordingJob } from '@deepseek-ai/dsh-jobs' +import type { JobId } from '@deepseek-ai/dsh-jobs' import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs' import type { ShellProcess } from '@deepseek-ai/dsh-shell' import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local' import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local' import * as ToolBash from '@deepseek-ai/dsh-tool-bash' -import { observeProcessRecord } from '../src/observe.ts' +import { processSources } from '../src/background.ts' import * as BashEnvPlugin from '@deepseek-ai/dsh-shell-env' const testToolSignal = new AbortController().signal -const spillDir = mkdtempSync(join(tmpdir(), 'dsh-tool-bash-observe-spec-')) +const spillDir = mkdtempSync(join(tmpdir(), 'dsh-tool-bash-background-spec-')) -/** Job harness with a fast record pump for tests. */ +/** Job harness with a fast registry pump for tests. */ async function setup() { const ctx = new Context() await ctx.plugin(SystemPrompt) await ctx.plugin(ToolRuntime) await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalJobRegistry) + await ctx.plugin(LocalJobRegistry, { pumpPollMs: 25 }) await ctx.plugin(ToolTasks) await ctx.plugin(LocalSubprocessRuntime) ;(ctx.subprocess as LocalSubprocessRuntime).internals = { spillDir } await ctx.plugin(BashEnvPlugin) await ctx.plugin(LocalBashExecutor, { timeoutMs: 10_000, graceMs: 200 }) - await ctx.plugin(ToolBash, { recordPollMs: 25 }) + await ctx.plugin(ToolBash) return ctx } @@ -42,7 +42,7 @@ let callCounter = 0 function call(ctx: Context, args: Record) { return ctx.tools.execute({ signal: testToolSignal, - callId: ToolCallId(`observe-call-${++callCounter}`), + callId: ToolCallId(`background-call-${++callCounter}`), name: 'bash', arguments: args, }) @@ -63,11 +63,11 @@ async function until(read: () => T | undefined, timeoutMs = 5_000): Promise chunk.text).join('') + return ctx.jobs.visibleTo(caller?.id).readAt(id, 0).chunks.map(chunk => chunk.text).join('') } -describe('background bash record', () => { - it('streams a background run into the job record with live output and settlement', async () => { +describe('background bash output', () => { + it('streams a background run into the job ring with live output and settlement', async () => { const ctx = await setup() const ack = await call(ctx, { command: 'printf "line-1\\n"; sleep 0.4; printf "line-2\\n"', @@ -75,34 +75,33 @@ describe('background bash record', () => { run_in_background: true, }) expect(text(ack)).toContain('started background job') - const job = ctx.jobs.list()[0] + const jobs = ctx.jobs.visibleTo() + const job = jobs.list()[0] expect(job).toBeDefined() - expect(job!.outputTotal).toBeDefined() - // Live output appears in the record while the command is still running. + // Live output appears in the ring while the command is still running. await until(() => retainedText(ctx, job!.id).includes('line-1') ? true : undefined) - expect(ctx.jobs.get(job!.id).status).toBe('running') + expect(jobs.get(job!.id).status).toBe('running') - // Settlement ends the record with the job; the trailing bytes are drained first. - await until(() => ctx.jobs.get(job!.id).status === 'completed' ? true : undefined) - expect(ctx.jobs.get(job!.id).detail).toBe('exit code: 0') + // Settlement ends the ring with the job; the trailing bytes are drained first. + await until(() => jobs.get(job!.id).status === 'completed' ? true : undefined) + expect(jobs.get(job!.id).detail).toBe('exit code: 0') expect(retainedText(ctx, job!.id)).toContain('line-2') - // The model-facing consuming cursor still delivers everything: observation stole nothing. - const collected = await until(() => { - const read = ctx.jobs.read(job!.id) - return read.text.includes('line-1') ? read.text : undefined - }) - expect(collected).toContain('line-2') + // The model-facing consuming cursor reads the same bytes: observation stole nothing. + const consumed = jobs.read(job!.id).chunks.map(chunk => chunk.text).join('') + expect(consumed).toContain('line-1') + expect(consumed).toContain('line-2') }) - it('a killed background job ends its record with the killed settlement', async () => { + it('a killed background job settles killed with the kill reason merged into its detail', async () => { const ctx = await setup() await call(ctx, { command: 'sleep 60', description: 'test command', run_in_background: true }) - const job = ctx.jobs.list()[0] - ctx.jobs.kill(job!.id, undefined, 'test cleanup') - await until(() => ctx.jobs.get(job!.id).status === 'killed' ? true : undefined) - expect(ctx.jobs.get(job!.id).detail).toMatch(/signal|killed before exit/) + const jobs = ctx.jobs.visibleTo() + const job = jobs.list()[0] + jobs.kill(job!.id, { reason: 'test cleanup' }) + await until(() => jobs.get(job!.id).status === 'killed' ? true : undefined) + expect(jobs.get(job!.id).detail).toMatch(/(signal|killed before exit).*; test cleanup$/) }) it('labels stderr chunks with their channel', async () => { @@ -112,73 +111,63 @@ describe('background bash record', () => { description: 'test command', run_in_background: true, }) - const job = ctx.jobs.list()[0] - await until(() => ctx.jobs.get(job!.id).status === 'completed' ? true : undefined) - const chunks = ctx.jobs.readRecord(job!.id, 0).chunks + const jobs = ctx.jobs.visibleTo() + const job = jobs.list()[0] + await until(() => jobs.get(job!.id).status === 'completed' ? true : undefined) + const chunks = jobs.readAt(job!.id, 0).chunks expect(chunks.find(chunk => chunk.text.includes('out-line'))?.channel).toBe('stdout') expect(chunks.find(chunk => chunk.text.includes('err-line'))?.channel).toBe('stderr') }) }) -describe('observeProcessRecord', () => { - /** A RecordingJob face recording appends for pump assertions. */ - function recordingJob(): { job: RecordingJob; appends: string[] } { - const appends: string[] = [] - return { - job: { - id: 'bash-1' as JobId, - append(chunk) { appends.push(chunk) }, - updateDetail() {}, - }, - appends, - } - } - - it('degrades to no observation when the backend exposes no offset readers', async () => { - const ctx = new Context() - const { job, appends } = recordingJob() - const proc = { done: Promise.resolve() } as unknown as ShellProcess - await observeProcessRecord(ctx, job, proc, 25) - expect(appends).toEqual([]) +describe('processSources', () => { + it('reads nothing while the process is not spawned yet and when the backend exposes no readers', () => { + const spawned: { proc?: ShellProcess } = {} + const [stdout, stderr] = processSources(() => spawned.proc) + expect(stdout!.channel).toBe('stdout') + expect(stderr!.channel).toBe('stderr') + expect(stdout!.read(0)).toEqual({ text: '', nextOffset: 0, lossy: false }) + spawned.proc = { done: Promise.resolve() } as unknown as ShellProcess + expect(stderr!.read(3)).toEqual({ text: '', nextOffset: 3, lossy: false }) }) - it('contains a pump failure with a warning; the job path is unaffected', async () => { - const ctx = new Context() - const warn = vi.fn() - ctx.logger.warn = warn as never - const { job } = recordingJob() + it('forwards each read to the matching stream reader once the process exists', () => { + const reads: number[] = [] const proc = { - done: new Promise((resolve) => { setTimeout(resolve, 10) }), observed: { - stdout: { readFrom() { throw new Error('reader boom') } }, + stdout: { readFrom: (from: number) => { reads.push(from); return { text: 'out', nextOffset: from + 3, lossy: false } } }, }, } as unknown as ShellProcess - await observeProcessRecord(ctx, job, proc, 5) - expect(warn).toHaveBeenCalledWith(expect.stringContaining('record observation pump for bash-1 failed')) + const [stdout, stderr] = processSources(() => proc) + expect(stdout!.read(2)).toEqual({ text: 'out', nextOffset: 5, lossy: false }) + expect(reads).toEqual([2]) + // A missing stderr reader is an absent stream, not an error. + expect(stderr!.read(0)).toEqual({ text: '', nextOffset: 0, lossy: false }) }) }) -describe('owned background record', () => { - it('fences an owned background run record under the owning session', async () => { +describe('owned background output', () => { + it('fences an owned background run under the owning session', async () => { const ctx = await setup() const owner = { - id: SessionId('observe-owner'), - session: { id: SessionId('observe-owner'), header: { cwd: process.cwd() } }, + id: SessionId('background-owner'), + session: { id: SessionId('background-owner'), header: { cwd: process.cwd() } }, status: 'idle', ctx, } as unknown as Agent ctx.agents.register(owner) await ctx.tools.execute({ signal: testToolSignal, - callId: ToolCallId('observe-owned-1'), + callId: ToolCallId('background-owned-1'), name: 'bash', arguments: { command: 'echo owned', description: 'test command', run_in_background: true }, agent: owner, }) - const job = ctx.jobs.list(owner)[0] + const owned = ctx.jobs.visibleTo(owner.id) + const job = owned.list()[0] expect(job).toBeDefined() - expect(job!.ownerSession).toBe(owner.id) - await until(() => ctx.jobs.get(job!.id, owner).status === 'completed' ? true : undefined) + expect(job!.owner).toBe(owner.id) + await until(() => owned.get(job!.id).status === 'completed' ? true : undefined) expect(() => retainedText(ctx, job!.id)).toThrow(/belongs to another session/) await until(() => retainedText(ctx, job!.id, owner).includes('owned') ? true : undefined) }) diff --git a/packages/shell/tool-bash/tests/tools.spec.ts b/packages/shell/tool-bash/tests/tools.spec.ts index 747d98b48d..8a4d7a41b4 100644 --- a/packages/shell/tool-bash/tests/tools.spec.ts +++ b/packages/shell/tool-bash/tests/tools.spec.ts @@ -5,7 +5,7 @@ import { describe, expect, it, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' import { ToolCallId } from '@deepseek-ai/dsh-llm' import { ShellExecutor } from '@deepseek-ai/dsh-shell' -import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellProcessRead, ShellRunResult } from '@deepseek-ai/dsh-shell' +import type { ShellExecRequest, ShellExecSpec, ShellProcess, ShellRunResult } from '@deepseek-ai/dsh-shell' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRuntime, { TOOL_ABORTED, TOOL_ABORTED_BEFORE_DISPATCH } from '@deepseek-ai/dsh-tools' import AgentRegistry from '@deepseek-ai/dsh-agent' @@ -22,8 +22,9 @@ import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy' import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection' import * as ToolBash from '@deepseek-ai/dsh-tool-bash' import * as BashEnvPlugin from '@deepseek-ai/dsh-shell-env' +import { escalationHintMarker, sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox' import { processOutcome } from '../src/background.ts' -import { renderProcessRead, renderResult } from '../src/render.ts' +import { renderResult } from '../src/render.ts' const testToolSignal = new AbortController().signal @@ -731,53 +732,6 @@ describe('sandbox escalation through the generic task producer', () => { }) }) -describe('renderProcessRead', () => { - const base: ShellProcessRead = { delta: 'out\n', lossy: false } - - it('returns the delta verbatim for a lossless read', () => { - expect(renderProcessRead(base)).toBe('out\n') - expect(renderProcessRead({ delta: '', lossy: false })).toBe('') - }) - - it('appends the loss notice with the available spill paths', () => { - expect(renderProcessRead({ ...base, lossy: true, stdoutSpillPath: '/spill/out.log' })) - .toBe('out\n[some output was dropped from memory; full output: /spill/out.log]') - expect(renderProcessRead({ ...base, lossy: true, stdoutSpillPath: '/spill/out.log', stderrSpillPath: '/spill/err.log' })) - .toBe('out\n[some output was dropped from memory; full output: /spill/out.log, /spill/err.log]') - }) - - it('reports (unavailable) when a lossy read has no safe spill path', () => { - expect(renderProcessRead({ ...base, lossy: true })) - .toBe('out\n[some output was dropped from memory; full output: (unavailable)]') - }) - - it('an empty lossy delta is the notice alone', () => { - expect(renderProcessRead({ delta: '', lossy: true, stderrSpillPath: '/spill/err.log' })) - .toBe('[some output was dropped from memory; full output: /spill/err.log]') - }) - - it('inserts the separating newline only when the delta lacks one', () => { - expect(renderProcessRead({ delta: 'tail', lossy: true })) - .toBe('tail\n[some output was dropped from memory; full output: (unavailable)]') - expect(renderProcessRead({ delta: 'tail\n', lossy: true })) - .toBe('tail\n[some output was dropped from memory; full output: (unavailable)]') - }) - - it('appends settled sandbox denial and runner-failure facts', () => { - expect(renderProcessRead(base, { mode: 'read-only', denied: true }, ['workspace-write'])) - .toContain('[sandbox: escalation available') - expect(renderProcessRead({ delta: 'tail', lossy: false }, { mode: 'read-only', denied: true })) - .toBe('tail\n[sandbox: file access denied under read-only mode]') - const runner = renderProcessRead( - { delta: '', lossy: false }, - { mode: 'workspace-write', denied: true, runnerFailed: true }, - ['danger-full-access'], - ) - expect(runner).toContain('sandbox runner itself failed under workspace-write mode') - expect(runner).not.toContain('file access denied') - }) -}) - describe('processOutcome', () => { function settled(over: Partial): ShellProcess { return { @@ -810,6 +764,16 @@ describe('processOutcome', () => { expect(processOutcome(settled({ exitCode: null }))) .toEqual({ status: 'completed', detail: 'exit code: 0' }) }) + + it('appends sandbox facts to the terminal detail', () => { + const denied = processOutcome(settled({ exitCode: 1, sandbox: { mode: 'read-only', denied: true } }), ['workspace-write']) + expect(denied.detail).toBe(`exit code: 1; ${sandboxDenialMarker('read-only')} ${escalationHintMarker('command')}`) + const deniedWithoutEscalation = processOutcome(settled({ exitCode: 1, sandbox: { mode: 'read-only', denied: true } })) + expect(deniedWithoutEscalation.detail).toBe(`exit code: 1; ${sandboxDenialMarker('read-only')}`) + const runnerFailed = processOutcome(settled({ exitCode: 1, sandbox: { mode: 'read-only', denied: false, runnerFailed: true } })) + expect(runnerFailed.detail).toContain('the sandbox runner itself failed under read-only mode') + expect(processOutcome(settled({ sandbox: { mode: 'read-only', denied: false } })).detail).toBe('exit code: 0') + }) }) describe('session-cwd routing (per-session workdir)', () => { diff --git a/packages/shell/tool-pwsh/README.i18n.yaml b/packages/shell/tool-pwsh/README.i18n.yaml index fbf8f4b9ae..ff3bcb8f9b 100644 --- a/packages/shell/tool-pwsh/README.i18n.yaml +++ b/packages/shell/tool-pwsh/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/shell/tool-pwsh/README.md -README.md: 6ce58c103e0e11c5011632e6c4a7024deeaa79cd -README.zh.md: b583cf3f9198ed9dd01a239405a6ada1094ecb9f +README.md: ead65fb453dfbcf36307ebda00d79e2e08c58744 +README.zh.md: 8b92fffe3797a096c6c292c3f277812a31020048 diff --git a/packages/shell/tool-pwsh/README.md b/packages/shell/tool-pwsh/README.md index 6ce58c103e..ead65fb453 100644 --- a/packages/shell/tool-pwsh/README.md +++ b/packages/shell/tool-pwsh/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -`dsh-tool-pwsh` gives the agent a `pwsh` tool that runs PowerShell commands through the mounted shell executor — the Windows counterpart of `dsh-tool-bash`, mirroring it call-for-call. Each call runs in a fresh pwsh process, so no state survives; `run_in_background` turns long-running commands into background jobs. Commands are PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables, with no dialect translation. Every call runs with the managed `DSH_*` environment, and under a sandboxing executor the tool teaches and enforces the Windows-specific language-mode and named-pipe contracts. Mount it with a PowerShell executor such as `dsh-pwsh-local` and the `dsh-shell-env` plugin. A background run's job declares an observation record pumped at `recordPollMs` (default 150), exactly like `dsh-tool-bash`. +`dsh-tool-pwsh` gives the agent a `pwsh` tool that runs PowerShell commands through the mounted shell executor — the Windows counterpart of `dsh-tool-bash`, mirroring it call-for-call. Each call runs in a fresh pwsh process, so no state survives; `run_in_background` turns long-running commands into background jobs. Commands are PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables, with no dialect translation. Every call runs with the managed `DSH_*` environment, and under a sandboxing executor the tool teaches and enforces the Windows-specific language-mode and named-pipe contracts. Mount it with a PowerShell executor such as `dsh-pwsh-local` and the `dsh-shell-env` plugin. A background run hands the process's offset readers to the job registry as pull sources, pumped at `pumpPollMs` on `dsh-jobs-local`, exactly like `dsh-tool-bash`. ## Table of Contents diff --git a/packages/shell/tool-pwsh/README.zh.md b/packages/shell/tool-pwsh/README.zh.md index b583cf3f91..8b92fffe37 100644 --- a/packages/shell/tool-pwsh/README.zh.md +++ b/packages/shell/tool-pwsh/README.zh.md @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -`dsh-tool-pwsh` 为 agent 提供 `pwsh` 工具,通过已挂载的 shell 执行器运行 PowerShell 命令——它是 `dsh-tool-bash` 的 Windows 对应物,逐调用镜像。每次调用都运行在全新 pwsh 进程中,因此状态不会保留;`run_in_background` 把长时间运行的命令变成后台任务。命令是 PowerShell 方言:原生 `C:\...` 路径与 `$env:NAME` 变量,不做方言翻译。每次调用都运行在受管 `DSH_*` 环境中;在沙箱执行器下,工具会教授并执行 Windows 特有的语言模式与命名管道约定。请与 `dsh-pwsh-local` 等 PowerShell 执行器以及 `dsh-shell-env` 插件一起挂载。后台运行的 job 声明按 `recordPollMs`(默认 150)泵送的观测 record,与 `dsh-tool-bash` 完全一致。 +`dsh-tool-pwsh` 为 agent 提供 `pwsh` 工具,通过已挂载的 shell 执行器运行 PowerShell 命令——它是 `dsh-tool-bash` 的 Windows 对应物,逐调用镜像。每次调用都运行在全新 pwsh 进程中,因此状态不会保留;`run_in_background` 把长时间运行的命令变成后台任务。命令是 PowerShell 方言:原生 `C:\...` 路径与 `$env:NAME` 变量,不做方言翻译。每次调用都运行在受管 `DSH_*` 环境中;在沙箱执行器下,工具会教授并执行 Windows 特有的语言模式与命名管道约定。请与 `dsh-pwsh-local` 等 PowerShell 执行器以及 `dsh-shell-env` 插件一起挂载。后台运行把进程的偏移读取器作为拉取源交给 job 注册表,由 `dsh-jobs-local` 按其 `pumpPollMs` 泵送,与 `dsh-tool-bash` 完全一致。 ## 目录 diff --git a/packages/shell/tool-pwsh/src/background.ts b/packages/shell/tool-pwsh/src/background.ts index dc0f53ffab..81066ecb0b 100644 --- a/packages/shell/tool-pwsh/src/background.ts +++ b/packages/shell/tool-pwsh/src/background.ts @@ -1,31 +1,78 @@ /** - * Generic-task adaptation for background pwsh process handles — the shell-agnostic - * twin of `dsh-tool-bash`'s background adaptation. + * Generic-job adaptation for background pwsh process handles — the + * shell-agnostic twin of `dsh-tool-bash`'s background adaptation: the terminal + * outcome the registry records and the pull sources it pumps. * * @module @deepseek-ai/dsh-tool-pwsh/background */ -import type { ShellProcess } from '@deepseek-ai/dsh-shell' +import type { SandboxMode } from '@deepseek-ai/dsh-sandbox' +import { escalationHintMarker, sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox' +import type { ShellProcess, ShellSandboxInfo } from '@deepseek-ai/dsh-shell' +import type { JobOutcome, JobOutputSource } from '@deepseek-ai/dsh-jobs' /* jscpd:ignore-start -- deliberate twin of dsh-tool-bash/background.ts (Agent Note). */ /** - * Map a settled background process onto the generic task-outcome vocabulary: + * Sandbox facts worth the terminal detail: a runner that never ran the + * command, or a denial (with the escalation hint this composition offers). + * @param sandbox - settled sandbox facts, when this was a confined process. + * @param escalationModes - escalation targets advertised by this composition. + * @returns the markers to append, oldest first. + */ +function sandboxNotes(sandbox: ShellSandboxInfo | undefined, escalationModes: readonly SandboxMode[]): string[] { + if (sandbox?.runnerFailed) { + return [`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`] + } + if (sandbox?.denied) { + const notes = [sandboxDenialMarker(sandbox.mode)] + if (escalationModes.length > 0) notes.push(escalationHintMarker('command')) + return notes + } + return [] +} + +/** + * Map a settled background process onto the generic job-outcome vocabulary: * `killed` stays `killed` (detail: the signal when one is known), everything * else is `completed` with the exit code as detail. A nonzero command exit is - * reported, not failed, exactly like the foreground rendering. + * reported, not failed, exactly like the foreground rendering. Sandbox facts + * join the detail, since a job's terminal reason is the one line every + * reader — the model's status line, the roster row — shows. * @param proc - the settled process handle. + * @param escalationModes - escalation targets advertised by this composition. * @returns the outcome for the `ctx.jobs` registration. */ -export function processOutcome(proc: ShellProcess): { status: 'completed' | 'killed'; detail: string } { +export function processOutcome(proc: ShellProcess, escalationModes: readonly SandboxMode[] = []): JobOutcome { // TODO(background-infrastructure-outcome): widen ShellProcess with an explicit // infrastructure-failure outcome, then map spawn failures and - // sandbox.runnerFailed to task `failed`. The current contract aliases a spawn + // sandbox.runnerFailed to job `failed`. The current contract aliases a spawn // failure with a signal-less kill and a runner failure with an ordinary // wrapper exit; real nonzero command exits must remain `completed`. - if (proc.status === 'killed') { - return { status: 'killed', detail: proc.signal !== null ? `signal: ${proc.signal}` : 'killed before exit' } - } - return { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` } + const base: JobOutcome = proc.status === 'killed' + ? { status: 'killed', detail: proc.signal !== null ? `signal: ${proc.signal}` : 'killed before exit' } + : { status: 'completed', detail: `exit code: ${proc.exitCode ?? 0}` } + const notes = sandboxNotes(proc.sandbox, escalationModes) + return notes.length === 0 ? base : { ...base, detail: `${base.detail}; ${notes.join(' ')}` } +} + +/** + * The process's non-consuming stream readers as registry pull sources. They + * bind lazily because the process is spawned inside the starter, after the + * registry admitted the job; a backend without offset readers degrades to no + * observation rather than an error, and the pump keeps the model's consuming + * cursor untouched. + * @param proc - the started process, once the starter has spawned it. + * @returns one source per stream, stdout first. + */ +export function processSources(proc: () => ShellProcess | undefined): JobOutputSource[] { + const source = (channel: 'stdout' | 'stderr'): JobOutputSource => ({ + channel, + read: (fromByte) => { + const reader = proc()?.observed?.[channel] + return reader === undefined ? { text: '', nextOffset: fromByte, lossy: false } : reader.readFrom(fromByte) + }, + }) + return [source('stdout'), source('stderr')] } /* jscpd:ignore-end */ diff --git a/packages/shell/tool-pwsh/src/index.ts b/packages/shell/tool-pwsh/src/index.ts index a7926e1b34..b84f618a33 100644 --- a/packages/shell/tool-pwsh/src/index.ts +++ b/packages/shell/tool-pwsh/src/index.ts @@ -32,11 +32,10 @@ import type {} from '@deepseek-ai/dsh-user-approval' import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox' import { ESCALATION_TARGETS, approveEscalation, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox' import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy' -import type { ShellRunResult } from '@deepseek-ai/dsh-shell' +import type { ShellRunResult, ShellProcess } from '@deepseek-ai/dsh-shell' import { parseExitStatus } from '@deepseek-ai/dsh-shell' -import { processOutcome } from './background.ts' -import { observeProcessRecord } from './observe.ts' -import { renderPwshProcessRead, renderPwshResult } from './render.ts' +import { processOutcome, processSources } from './background.ts' +import { renderPwshResult } from './render.ts' import type { RenderablePwshResult } from './render.ts' declare module '@deepseek-ai/dsh-jobs' { @@ -53,18 +52,11 @@ export const inject = ['tools', 'shell', 'systemPrompt', 'shellEnv'] export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean - /** Poll cadence for copying background output into the job record, in milliseconds (default 150). */ - recordPollMs?: number } /** Runtime configuration schema for the pwsh tool plugin. */ export const Config: z = z.object({ enableRunInBackground: z.boolean().default(true), - recordPollMs: z.number() - .step(1) - .min(1) - .max(Number.MAX_SAFE_INTEGER) - .default(150), }) /* jscpd:ignore-end */ @@ -203,7 +195,6 @@ const BACKGROUND_OUTPUT_PROPERTIES = { /* jscpd:ignore-start -- deliberate mirror of dsh-tool-bash's apply() preamble (pwsh-tool-and-executor Agent Note). */ export function apply(ctx: Context, config: Config = {}): void { const backgroundEnabled = config.enableRunInBackground ?? true - const recordPollMs = config.recordPollMs ?? 150 const defaultMode = ctx.shell.sandboxMode const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS const sandboxPolicy: SandboxPolicyService | undefined = defaultMode === undefined ? undefined : ctx.get('sandboxPolicy') @@ -387,20 +378,21 @@ export function apply(ctx: Context, config: Config = {}): void { error.name = 'AbortError' throw error } + // The registry pumps the process's non-consuming readers into the + // job's ring; the sources bind lazily because the process is spawned + // only once admission has passed. + let proc: ShellProcess | undefined const id = jobs.start({ kind: 'pwsh', label: args.command, - ...exec.agent ? { owner: exec.agent } : {}, - record: true, - run: (job) => { - const proc = ctx.shell.start(ctx.shell.resolve(request)) - // The pump's final drain is folded into `done` so the record holds - // its last bytes before settlement trims and closes it. - const observed = observeProcessRecord(ctx, job, proc, recordPollMs) + ...exec.agent ? { owner: exec.agent.id } : {}, + output: processSources(() => proc), + run: () => { + const started = ctx.shell.start(ctx.shell.resolve(request)) + proc = started return { - cancel: () => void proc.kill(), - done: observed.then(() => proc.done).then(() => processOutcome(proc)), - readOutput: () => renderPwshProcessRead(proc.readOutput(), proc.sandbox, escalationModes), + cancel: () => void started.kill(), + done: started.done.then(() => processOutcome(started, escalationModes)), } }, }) diff --git a/packages/shell/tool-pwsh/src/observe.ts b/packages/shell/tool-pwsh/src/observe.ts deleted file mode 100644 index 357567e31e..0000000000 --- a/packages/shell/tool-pwsh/src/observe.ts +++ /dev/null @@ -1,49 +0,0 @@ -/** - * Record tap for background pwsh runs: copies the spawned process's captured - * streams into the job's observation record, so non-consuming observers (the - * Web client) see live output without touching the job's consuming - * `readOutput` cursor. Observation is strictly best-effort: absent backend - * offset readers degrade to no observation, and a pump failure is logged and - * swallowed — the job path is unaffected either way. - * The record interleaves stdout and stderr per poll round, not per write: - * output the two streams produced inside one `pollMs` window lands stdout - * first, so the panel is a live preview, not a terminal-exact transcript. - * - * @module @deepseek-ai/dsh-tool-pwsh/observe - */ - -/* jscpd:ignore-start -- mirrors tool-bash's observe tap by design, like render/background. */ -import type { Context } from '@deepseek-ai/cordis' -import type { ShellProcess } from '@deepseek-ai/dsh-shell' -import { pumpJobOutput } from '@deepseek-ai/dsh-jobs' -import type { JobPumpSource, RecordingJob } from '@deepseek-ai/dsh-jobs' - -/** - * Pump the process's non-consuming offset readers into the job record until - * the run settles, then drain once more. The returned promise never rejects: - * a pump failure is logged and the record simply stops advancing, while the - * process and its job continue untouched. - * @param ctx - plugin context used for the warning log. - * @param job - the running job's producer face receiving the copied chunks. - * @param proc - the started background process handle. - * @param pollMs - producer-configured pump cadence in milliseconds. - * @returns resolves after the final drain; fold into the job's `done` chain so - * the record holds its final bytes before settlement closes it. - */ -export function observeProcessRecord( - ctx: Context, - job: RecordingJob, - proc: ShellProcess, - pollMs: number, -): Promise { - const sources: JobPumpSource[] = [] - const stdout = proc.observed?.stdout - if (stdout !== undefined) sources.push({ channel: 'stdout', read: from => stdout.readFrom(from) }) - const stderr = proc.observed?.stderr - if (stderr !== undefined) sources.push({ channel: 'stderr', read: from => stderr.readFrom(from) }) - return pumpJobOutput(job, sources, { pollMs, done: proc.done }) - .catch((error: unknown) => { - ctx.logger.warn(`record observation pump for ${job.id} failed: ${String(error)}`) - }) -} -/* jscpd:ignore-end */ diff --git a/packages/shell/tool-pwsh/src/render.ts b/packages/shell/tool-pwsh/src/render.ts index cc7b8a661d..01e0a51e2e 100644 --- a/packages/shell/tool-pwsh/src/render.ts +++ b/packages/shell/tool-pwsh/src/render.ts @@ -10,7 +10,7 @@ * @module @deepseek-ai/dsh-tool-pwsh/render */ -import type { ShellProcessRead, ShellSandboxInfo, CollectedOutput } from '@deepseek-ai/dsh-shell' +import type { ShellSandboxInfo, CollectedOutput } from '@deepseek-ai/dsh-shell' import type { SandboxMode } from '@deepseek-ai/dsh-sandbox' import { escalationHintMarker, sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox' @@ -80,34 +80,4 @@ export function renderPwshResult( return body + markers.join('\n') } -/** - * Shape one background-process read into the `job_output` delta the model - * sees: the incremental delta, plus the lossy-read notice (with full-stream - * spill paths) when in-memory truncation dropped unread bytes. - * @param read - one incremental read from the process handle. - * @param sandbox - settled sandbox facts, when this was a confined process. - * @param escalationModes - escalation targets advertised by this composition. - * @returns the delta text with any loss or sandbox notice appended. - */ -export function renderPwshProcessRead( - read: ShellProcessRead, - sandbox?: ShellSandboxInfo, - escalationModes: readonly SandboxMode[] = [], -): string { - const notices: string[] = [] - if (read.lossy) { - const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((path): path is string => path !== undefined) - notices.push(`[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(', ') : '(unavailable)'}]`) - } - if (sandbox?.runnerFailed) { - notices.push(`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`) - } else if (sandbox?.denied) { - notices.push(sandboxDenialMarker(sandbox.mode)) - if (escalationModes.length > 0) { - notices.push(escalationHintMarker('command')) - } - } - if (notices.length === 0) return read.delta - return `${read.delta}${read.delta.length > 0 && !read.delta.endsWith('\n') ? '\n' : ''}${notices.join('\n')}` -} /* jscpd:ignore-end */ diff --git a/packages/shell/tool-pwsh/tests/observe.spec.ts b/packages/shell/tool-pwsh/tests/background.spec.ts similarity index 73% rename from packages/shell/tool-pwsh/tests/observe.spec.ts rename to packages/shell/tool-pwsh/tests/background.spec.ts index 0fbdcb80de..6c12ff8611 100644 --- a/packages/shell/tool-pwsh/tests/observe.spec.ts +++ b/packages/shell/tool-pwsh/tests/background.spec.ts @@ -78,11 +78,11 @@ async function setup() { await ctx.plugin(SystemPrompt) await ctx.plugin(ToolRuntime) await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalJobRegistry) + await ctx.plugin(LocalJobRegistry, { pumpPollMs: 5 }) await ctx.plugin(ToolTasks) await ctx.plugin(BashEnvPlugin) await ctx.plugin(FakePwsh) - await ctx.plugin(ToolPwsh, { recordPollMs: 5 }) + await ctx.plugin(ToolPwsh) return { ctx, pwsh: ctx.shell as FakePwsh } } @@ -90,7 +90,7 @@ let callCounter = 0 function call(ctx: Context, args: Record) { return ctx.tools.execute({ signal: testToolSignal, - callId: ToolCallId(`pwsh-observe-${++callCounter}`), + callId: ToolCallId(`pwsh-background-${++callCounter}`), name: 'pwsh', arguments: args, }) @@ -106,8 +106,8 @@ async function until(read: () => T | undefined, timeoutMs = 5_000): Promise { - it('streams observed channels into the job record and settles with the mapped outcome', async () => { +describe('background pwsh output', () => { + it('streams observed channels into the job ring and settles with the mapped outcome', async () => { const { ctx, pwsh } = await setup() const stdout = { text: '' } const stderr = { text: '' } @@ -115,30 +115,31 @@ describe('background pwsh record', () => { pwsh.backgroundHandler = () => scripted.proc await call(ctx, { command: 'Get-Progress', description: 'test command', run_in_background: true }) - const job = ctx.jobs.list()[0] + const jobs = ctx.jobs.visibleTo() + const job = jobs.list()[0] expect(job).toBeDefined() expect(job!.kind).toBe('pwsh') - expect(job!.outputTotal).toBe(0) + expect(job!.output).toEqual({ total: 0, earliest: 0 }) stdout.text = 'progress-line\n' stderr.text = 'warn-line\n' await until(() => { - const chunks = ctx.jobs.readRecord(job!.id, 0).chunks + const chunks = jobs.readAt(job!.id, 0).chunks return chunks.some(chunk => chunk.text.includes('progress-line')) && chunks.some(chunk => chunk.text.includes('warn-line')) ? true : undefined }) - const chunks = ctx.jobs.readRecord(job!.id, 0).chunks + const chunks = jobs.readAt(job!.id, 0).chunks expect(chunks.find(chunk => chunk.text.includes('progress-line'))?.channel).toBe('stdout') expect(chunks.find(chunk => chunk.text.includes('warn-line'))?.channel).toBe('stderr') scripted.finish() - await until(() => ctx.jobs.get(job!.id).status === 'completed' ? true : undefined) - expect(ctx.jobs.get(job!.id).detail).toBe('exit code: 0') + await until(() => jobs.get(job!.id).status === 'completed' ? true : undefined) + expect(jobs.get(job!.id).detail).toBe('exit code: 0') }) - it('a pump failure warns and never fakes a terminal state onto the running job', async () => { + it('a failing reader warns once and never fakes a terminal state onto the running job', async () => { const { ctx, pwsh } = await setup() const warn = vi.fn() ctx.logger.warn = warn as never @@ -158,40 +159,43 @@ describe('background pwsh record', () => { } pwsh.backgroundHandler = () => proc await call(ctx, { command: 'Get-Broken', description: 'test command', run_in_background: true }) - const job = ctx.jobs.list()[0] - await until(() => warn.mock.calls.some(args => String(args[0]).includes('record observation pump')) ? true : undefined) - // The pump already failed; the job must wait for real settlement rather + const jobs = ctx.jobs.visibleTo() + const job = jobs.list()[0] + await until(() => warn.mock.calls.some(args => String(args[0]).includes('output source for')) ? true : undefined) + // The reader already failed; the job must wait for real settlement rather // than freezing a fake terminal state onto the running process. await new Promise(resolve => setTimeout(resolve, 50)) - expect(ctx.jobs.get(job!.id).status).toBe('running') + expect(jobs.get(job!.id).status).toBe('running') + expect(warn).toHaveBeenCalledTimes(1) proc.status = 'completed' proc.exitCode = 0 resolveDone() - await until(() => ctx.jobs.get(job!.id).status !== 'running' ? true : undefined) - expect(ctx.jobs.get(job!.id)).toMatchObject({ status: 'completed', detail: 'exit code: 0' }) + await until(() => jobs.get(job!.id).status !== 'running' ? true : undefined) + expect(jobs.get(job!.id)).toMatchObject({ status: 'completed', detail: 'exit code: 0' }) }) - it('a backend without observed readers still yields a status-only record', async () => { + it('a backend without observed readers still settles with an empty ring', async () => { const { ctx, pwsh } = await setup() const scripted = observableProcess() pwsh.backgroundHandler = () => scripted.proc await call(ctx, { command: 'Start-Job', description: 'test command', run_in_background: true }) - const job = ctx.jobs.list()[0] - expect(ctx.jobs.readRecord(job!.id, 0).chunks).toEqual([]) + const jobs = ctx.jobs.visibleTo() + const job = jobs.list()[0] + expect(jobs.readAt(job!.id, 0).chunks).toEqual([]) scripted.finish() - await until(() => ctx.jobs.get(job!.id).status === 'completed' ? true : undefined) - expect(ctx.jobs.get(job!.id).outputTotal).toBe(0) + await until(() => jobs.get(job!.id).status === 'completed' ? true : undefined) + expect(jobs.get(job!.id).output).toEqual({ total: 0, earliest: 0 }) }) }) -describe('owned background record (pwsh)', () => { - it('keeps an owned background run record under the owning session', async () => { +describe('owned background output (pwsh)', () => { + it('keeps an owned background run under the owning session', async () => { const { ctx, pwsh } = await setup() const owner = { - id: SessionId('pwsh-observe-owner'), - session: { id: SessionId('pwsh-observe-owner'), header: { cwd: process.cwd() } }, + id: SessionId('pwsh-background-owner'), + session: { id: SessionId('pwsh-background-owner'), header: { cwd: process.cwd() } }, status: 'idle', ctx, } as unknown as Agent @@ -200,17 +204,18 @@ describe('owned background record (pwsh)', () => { pwsh.backgroundHandler = () => scripted.proc await ctx.tools.execute({ signal: testToolSignal, - callId: ToolCallId('pwsh-observe-owned'), + callId: ToolCallId('pwsh-background-owned'), name: 'pwsh', arguments: { command: 'Get-Slow', description: 'test command', run_in_background: true }, agent: owner, }) - const job = ctx.jobs.list(owner)[0] + const owned = ctx.jobs.visibleTo(owner.id) + const job = owned.list()[0] expect(job).toBeDefined() - expect(job!.ownerSession).toBe(owner.id) - expect(() => ctx.jobs.readRecord(job!.id, 0)).toThrow(/belongs to another session/) - expect(ctx.jobs.readRecord(job!.id, 0, owner).chunks).toEqual([]) + expect(job!.owner).toBe(owner.id) + expect(() => ctx.jobs.visibleTo().readAt(job!.id, 0)).toThrow(/belongs to another session/) + expect(owned.readAt(job!.id, 0).chunks).toEqual([]) scripted.finish() - await until(() => ctx.jobs.get(job!.id, owner).status === 'completed' ? true : undefined) + await until(() => owned.get(job!.id).status === 'completed' ? true : undefined) }) }) diff --git a/packages/shell/tool-pwsh/tests/tools.spec.ts b/packages/shell/tool-pwsh/tests/tools.spec.ts index 5e27e3c8e0..0995697129 100644 --- a/packages/shell/tool-pwsh/tests/tools.spec.ts +++ b/packages/shell/tool-pwsh/tests/tools.spec.ts @@ -32,9 +32,9 @@ import { turnBoundaryProjectionDefinition } from '@deepseek-ai/dsh-agent-loop' import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy' import * as ToolPwsh from '@deepseek-ai/dsh-tool-pwsh' import * as BashEnvPlugin from '@deepseek-ai/dsh-shell-env' -import type { ShellProcessRead } from '@deepseek-ai/dsh-shell' +import { escalationHintMarker, sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox' import { processOutcome } from '../src/background.ts' -import { renderPwshProcessRead, renderPwshResult } from '../src/render.ts' +import { renderPwshResult } from '../src/render.ts' const testToolSignal = new AbortController().signal @@ -91,20 +91,19 @@ function runResult(stdout: string, overrides?: Partial): ShellRu } } -/** A settled successful background handle; overrides script failure shapes. */ +/** A settled successful background handle whose stdout the registry pump reads by offset (ASCII: offsets are string indexes). */ function fakeProcess(delta = 'bg-ok\n'): ShellProcess { - let consumed = false return { status: 'completed', exitCode: 0, signal: null, done: Promise.resolve(), - readOutput: () => { - if (consumed) return { delta: '', lossy: false } - consumed = true - return { delta, lossy: false } - }, + readOutput: () => ({ delta: '', lossy: false }), kill: () => false, + observed: { + stdout: { readFrom: (fromByte: number) => ({ text: delta.slice(fromByte), nextOffset: delta.length, lossy: false }) }, + stderr: { readFrom: (fromByte: number) => ({ text: '', nextOffset: fromByte, lossy: false }) }, + }, } } @@ -1005,58 +1004,6 @@ describe('renderPwshResult sandbox markers', () => { }) }) -describe('renderPwshProcessRead', () => { - const base: ShellProcessRead = { delta: 'out\n', lossy: false } - - it('returns the delta verbatim for a lossless read', () => { - expect(renderPwshProcessRead(base)).toBe('out\n') - expect(renderPwshProcessRead({ delta: '', lossy: false })).toBe('') - }) - - it('appends the loss notice with the available spill paths', () => { - expect(renderPwshProcessRead({ ...base, lossy: true, stdoutSpillPath: 'C:\\spill\\out.log' })) - .toBe('out\n[some output was dropped from memory; full output: C:\\spill\\out.log]') - expect(renderPwshProcessRead({ - ...base, - lossy: true, - stdoutSpillPath: 'C:\\spill\\out.log', - stderrSpillPath: 'C:\\spill\\err.log', - })) - .toBe('out\n[some output was dropped from memory; full output: C:\\spill\\out.log, C:\\spill\\err.log]') - }) - - it('reports (unavailable) when a lossy read has no safe spill path', () => { - expect(renderPwshProcessRead({ ...base, lossy: true })) - .toBe('out\n[some output was dropped from memory; full output: (unavailable)]') - }) - - it('an empty lossy delta is the notice alone', () => { - expect(renderPwshProcessRead({ delta: '', lossy: true, stderrSpillPath: 'C:\\spill\\err.log' })) - .toBe('[some output was dropped from memory; full output: C:\\spill\\err.log]') - }) - - it('inserts the separating newline only when the delta lacks one', () => { - expect(renderPwshProcessRead({ delta: 'tail', lossy: true })) - .toBe('tail\n[some output was dropped from memory; full output: (unavailable)]') - expect(renderPwshProcessRead({ delta: 'tail\n', lossy: true })) - .toBe('tail\n[some output was dropped from memory; full output: (unavailable)]') - }) - - it('appends the runner-failed notice (denial outranked)', () => { - expect(renderPwshProcessRead({ delta: 'x', lossy: false }, { mode: 'read-only', denied: true, runnerFailed: true })) - .toBe('x\n[sandbox: the sandbox runner itself failed under read-only mode — the command did not run; this is a sandbox problem, not a command failure]') - }) - - it('appends the denial marker and hints only when escalation is advertised', () => { - expect(renderPwshProcessRead({ delta: 'x', lossy: false }, { mode: 'read-only', denied: true })) - .toBe('x\n[sandbox: file access denied under read-only mode]') - expect(renderPwshProcessRead({ delta: 'x', lossy: false }, { mode: 'read-only', denied: true }, ['workspace-write'])) - .toBe('x\n[sandbox: file access denied under read-only mode]\n' - + '[sandbox: escalation available — retry this exact command once with sandbox_permissions ' - + '(the narrowest wider mode that suffices) + justification; the approval prompt asks the user]') - }) -}) - describe('processOutcome', () => { function settled(over: Partial): ShellProcess { return { @@ -1089,4 +1036,14 @@ describe('processOutcome', () => { expect(processOutcome(settled({ exitCode: null }))) .toEqual({ status: 'completed', detail: 'exit code: 0' }) }) + + it('appends sandbox facts to the terminal detail', () => { + const denied = processOutcome(settled({ exitCode: 1, sandbox: { mode: 'read-only', denied: true } }), ['workspace-write']) + expect(denied.detail).toBe(`exit code: 1; ${sandboxDenialMarker('read-only')} ${escalationHintMarker('command')}`) + const deniedWithoutEscalation = processOutcome(settled({ exitCode: 1, sandbox: { mode: 'read-only', denied: true } })) + expect(deniedWithoutEscalation.detail).toBe(`exit code: 1; ${sandboxDenialMarker('read-only')}`) + const runnerFailed = processOutcome(settled({ exitCode: 1, sandbox: { mode: 'read-only', denied: false, runnerFailed: true } })) + expect(runnerFailed.detail).toContain('the sandbox runner itself failed under read-only mode') + expect(processOutcome(settled({ sandbox: { mode: 'read-only', denied: false } })).detail).toBe('exit code: 0') + }) }) From 10d76fbd03ee00cd478ef86fbcc3c75c2686ab0a Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 16:37:35 +0800 Subject: [PATCH 033/100] refactor(producers): subagent and terminal jobs use session owners, results, and pull sources - tool-subagent registers the parent session id as the owner and settleRun reports the child's final text as the job result, which the first read after settlement carries once - tool-terminal hands the registry one pull source over the backend's consuming send reader (sendSource in background.ts) instead of a readOutput hook; the truncation marker stays in the delivered text - the model's kill reason now shows in a killed job's status line, as the registry records it as the terminal detail - test call sites move from jobs.list(owner) to visibleTo(owner).list() --- .../tests/profiles/headless/tests/ptc.e2e.ts | 10 +++--- .../subagent/subagent/src/run-settlement.ts | 2 +- .../subagent/tests/run-settlement.spec.ts | 4 +-- packages/subagent/tool-subagent/src/index.ts | 4 +-- .../tool-subagent/tests/tool-subagent.spec.ts | 15 ++++----- .../terminal/tool-terminal/src/background.ts | 31 +++++++++++++++++++ packages/terminal/tool-terminal/src/index.ts | 17 +++++----- .../tool-terminal/tests/tools.spec.ts | 22 +++++++++++-- 8 files changed, 79 insertions(+), 26 deletions(-) create mode 100644 packages/terminal/tool-terminal/src/background.ts diff --git a/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts b/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts index 8ee3affb8a..25a7292e45 100644 --- a/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts +++ b/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts @@ -222,7 +222,7 @@ describe('PTC mode typed values: keyless real-worker contracts', () => { return await tools.bash({ command: 'sleep 10', description: 'Must never start', run_in_background: true }); `, pre.signal) expect(preResult.isError).toBe(true) - expect(ctx.jobs.list()).toEqual([]) + expect(ctx.jobs.visibleTo().list()).toEqual([]) const afterPublication = new AbortController() const running = runCode(ctx, ` @@ -230,14 +230,14 @@ describe('PTC mode typed values: keyless real-worker contracts', () => { console.log(started.jobId); await new Promise(() => {}); `, afterPublication.signal) - for (let attempt = 0; attempt < 100 && ctx.jobs.list().length === 0; attempt++) { + for (let attempt = 0; attempt < 100 && ctx.jobs.visibleTo().list().length === 0; attempt++) { await new Promise(resolve => setTimeout(resolve, 10)) } - const job = ctx.jobs.list()[0] + const job = ctx.jobs.visibleTo().list()[0] expect(job).toMatchObject({ id: 'bash-1', status: 'running' }) afterPublication.abort('outer-call-cancelled') expect((await running).isError).toBe(true) - expect(ctx.jobs.list()[0]).toMatchObject({ id: job!.id, status: 'running' }) + expect(ctx.jobs.visibleTo().list()[0]).toMatchObject({ id: job!.id, status: 'running' }) const killed = completion(await runCode(ctx, ` return await tools.job_kill({ job_id: ${JSON.stringify(job!.id)}, reason: 'test owns cancellation' }); @@ -261,7 +261,7 @@ describe('PTC mode typed values: keyless real-worker contracts', () => { const result = await pending expect(result.isError).toBe(true) expect(Date.now() - startedAt).toBeLessThan(5_000) - expect(ctx.jobs.list()).toEqual([]) + expect(ctx.jobs.visibleTo().list()).toEqual([]) }, 15_000) it('uses versioned Cordis DTO ids directly for running and pending Plugins, then confirms removal', async () => { diff --git a/packages/subagent/subagent/src/run-settlement.ts b/packages/subagent/subagent/src/run-settlement.ts index 02f61a7baf..34baacbcd4 100644 --- a/packages/subagent/subagent/src/run-settlement.ts +++ b/packages/subagent/subagent/src/run-settlement.ts @@ -37,7 +37,7 @@ function failureDetail(result: SubagentResult): string { function runOutcome(result: SubagentResult): JobOutcome { switch (result.stopReason) { case 'completed': - return { status: 'completed', output: finalText(result.output) } + return { status: 'completed', result: finalText(result.output) } case 'aborted': return result.diagnostic === undefined ? { status: 'killed' } diff --git a/packages/subagent/subagent/tests/run-settlement.spec.ts b/packages/subagent/subagent/tests/run-settlement.spec.ts index 146181d43a..20fc514504 100644 --- a/packages/subagent/subagent/tests/run-settlement.spec.ts +++ b/packages/subagent/subagent/tests/run-settlement.spec.ts @@ -9,7 +9,7 @@ const MAX_SUBAGENT_DIAGNOSTIC_BYTES = 4_096 describe('outcome mapping helpers', () => { it.each([ - ['completed', { status: 'completed', output: 'partial' }], + ['completed', { status: 'completed', result: 'partial' }], ['aborted', { status: 'killed' }], ['error', { status: 'failed', detail: 'error' }], ['max-tokens', { status: 'failed', detail: 'max-tokens' }], @@ -34,7 +34,7 @@ describe('outcome mapping helpers', () => { dispose() { order.push('dispose'); return Promise.resolve() }, }) order.push('reported') - expect(completed).toEqual({ status: 'completed', output: 'ok' }) + expect(completed).toEqual({ status: 'completed', result: 'ok' }) expect(order).toEqual(['dispose', 'reported']) // An infrastructure rejection still disposes and reports failed. diff --git a/packages/subagent/tool-subagent/src/index.ts b/packages/subagent/tool-subagent/src/index.ts index 03b56a3c9d..2c87bbf213 100644 --- a/packages/subagent/tool-subagent/src/index.ts +++ b/packages/subagent/tool-subagent/src/index.ts @@ -537,7 +537,7 @@ export function apply(ctx: Context, config: Config): void { const id = jobs.start({ kind: 'subagent', label: args.description, - owner: parent, + owner: parent.id, run: () => { const controller = new AbortController() const start = runtimeCtx.subagents.start(config.provider, { ...request, signal: controller.signal }) @@ -546,7 +546,7 @@ export function apply(ctx: Context, config: Config): void { controller.abort(reason ?? 'background subagent task killed') }, done: settleStart(start, controller.signal), - // No readOutput: the child session owns intermediate detail. + // No output sources: the child session owns intermediate detail. } }, }) diff --git a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts index e5f9502a43..c1b2046182 100644 --- a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts +++ b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts @@ -883,7 +883,7 @@ describe('dsh-tool-subagent background mode', () => { }) expect(text(collected)).toBe('background answer\n[status: completed]') - // Final-output reads are idempotent (not consumed). + // The result rides the first read after settlement; a later read carries only the status. const again = await ctx.tools.execute({ signal: testToolSignal, callId: ToolCallId('collect-2'), @@ -891,7 +891,7 @@ describe('dsh-tool-subagent background mode', () => { arguments: { job_id: 'subagent-1' }, agent: parent, }) - expect(text(again)).toBe('background answer\n[status: completed]') + expect(text(again)).toBe('(no new output)\n[status: completed]') }) it('preserves provider diagnostics in one-shot background failure detail', async () => { @@ -972,7 +972,7 @@ describe('dsh-tool-subagent background mode', () => { const result = await resultPromise expect(result.isError).toBe(true) - expect(ctx.jobs.list(parent)).toEqual([]) + expect(ctx.jobs.visibleTo(parent.id).list()).toEqual([]) }) it('rejects startup when the provider changes during asynchronous route preflight', async () => { @@ -1082,7 +1082,8 @@ describe('dsh-tool-subagent background mode', () => { arguments: { job_id: 'subagent-1', wait: true }, agent: parent, }) - expect(text(output)).toBe('(no new output)\n[status: killed]') + // The registry records the model's kill reason as the terminal detail. + expect(text(output)).toBe('(no new output)\n[status: killed, no longer needed]') }) it('reports startup rollback failure after cancellation as a failed job', async () => { @@ -1169,7 +1170,7 @@ describe('dsh-tool-subagent background mode', () => { // The aborted children settle as killed tasks. const killed = await ctx.tools.execute({ signal: testToolSignal, callId: ToolCallId('w1'), name: 'job_output', arguments: { job_id: 'subagent-1', wait: true }, agent: parent }) - expect(text(killed)).toBe('(no new output)\n[status: killed]') + expect(text(killed)).toBe('(no new output)\n[status: killed, superseded]') }) }) @@ -1240,7 +1241,7 @@ describe('dsh-tool-subagent continuable background mode', () => { expect(match).not.toBeNull() const [, childId] = match! // No Task was created for the continuable child. - expect(ctx.jobs.list(parent)).toEqual([]) + expect(ctx.jobs.visibleTo(parent.id).list()).toEqual([]) await vi.waitFor(() => { expect(ctx.agents.get(SessionId(childId!))).toBeUndefined() @@ -1271,7 +1272,7 @@ describe('dsh-tool-subagent continuable background mode', () => { if (result.isError) throw new Error('expected foreground subagent success') expect(result.value).toMatchObject({ kind: 'foreground' }) expect(text(result)).toBe('continuable answer') - expect(ctx.jobs.list(parent)).toEqual([]) + expect(ctx.jobs.visibleTo(parent.id).list()).toEqual([]) }) it('isolates a cancelled continuable preparation from a concurrent sibling', async () => { diff --git a/packages/terminal/tool-terminal/src/background.ts b/packages/terminal/tool-terminal/src/background.ts new file mode 100644 index 0000000000..47494f7cff --- /dev/null +++ b/packages/terminal/tool-terminal/src/background.ts @@ -0,0 +1,31 @@ +/** + * Generic-job adaptation for background terminal sends: the registry pull + * source over the backend's consuming send reader. + * + * @module @deepseek-ai/dsh-tool-terminal/background + */ + +import type { JobOutputSource } from '@deepseek-ai/dsh-jobs' +import type { TerminalSendOperation } from '@deepseek-ai/dsh-terminal' +import { renderSendRead } from './render.ts' + +/** + * Adapt the backend's consuming send reader to a registry pull source. The + * reader has no offsets of its own — each call hands over what arrived since + * the previous one — so the source counts the bytes it delivered to keep the + * registry's cursor monotonic. It binds lazily because the send starts inside + * the job starter, after the registry admitted the job; a read before that + * point delivers nothing. + * @param operation - the live send, once the starter has begun it. + * @returns one unlabeled source over the send's bounded delta. + */ +export function sendSource(operation: () => TerminalSendOperation | undefined): JobOutputSource { + return { + read: (fromByte) => { + const live = operation() + if (live === undefined) return { text: '', nextOffset: fromByte, lossy: false } + const text = renderSendRead(live.readOutput()) + return { text, nextOffset: fromByte + Buffer.byteLength(text), lossy: false } + }, + } +} diff --git a/packages/terminal/tool-terminal/src/index.ts b/packages/terminal/tool-terminal/src/index.ts index 880cfcd31f..417c1537c4 100644 --- a/packages/terminal/tool-terminal/src/index.ts +++ b/packages/terminal/tool-terminal/src/index.ts @@ -9,11 +9,12 @@ import z from '@deepseek-ai/schemastery' import type { Agent } from '@deepseek-ai/dsh-agent' import type { ContentBlock } from '@deepseek-ai/dsh-llm' import { TerminalSessionId } from '@deepseek-ai/dsh-terminal' -import type { TerminalSendResult, TerminalSessionId as TerminalSessionIdType, TerminalSignal } from '@deepseek-ai/dsh-terminal' +import type { TerminalSendOperation, TerminalSendResult, TerminalSessionId as TerminalSessionIdType, TerminalSignal } from '@deepseek-ai/dsh-terminal' import type {} from '@deepseek-ai/dsh-jobs' import { defineTool } from '@deepseek-ai/dsh-tools' import type { ToolDefinition } from '@deepseek-ai/dsh-tools' -import { boundTerminalText, renderList, renderRead, renderSend, renderSendRead, renderSpawn } from './render.ts' +import { sendSource } from './background.ts' +import { boundTerminalText, renderList, renderRead, renderSend, renderSpawn } from './render.ts' declare module '@deepseek-ai/dsh-jobs' { interface JobKindMap { @@ -252,23 +253,25 @@ export function apply(ctx: Context, config: Config = {}): void { const jobs = ctx.get('jobs') if (jobs === undefined) throw new Error('background terminal sends require @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs') let cancelRequested = false + let operation: TerminalSendOperation | undefined const jobId = jobs.start({ kind: 'pty-send', label: `${id}: ${args.text || '(input)'}`, - owner, + owner: owner.id, outputLimitBytes: maxResultBytes, + output: [sendSource(() => operation)], run: () => { - const operation = ctx.terminals.startSend(owner, id, request) + const started = ctx.terminals.startSend(owner, id, request) + operation = started return { cancel: () => { cancelRequested = true - operation.cancel() + started.cancel() }, - done: operation.done.then( + done: started.done.then( result => ({ status: cancelRequested ? 'killed' as const : 'completed' as const, detail: sendDetail(result) }), (error: unknown) => ({ status: 'failed' as const, detail: String(error) }), ), - readOutput: () => renderSendRead(operation.readOutput()), } }, }) diff --git a/packages/terminal/tool-terminal/tests/tools.spec.ts b/packages/terminal/tool-terminal/tests/tools.spec.ts index 15151f7bd2..eb80741bf8 100644 --- a/packages/terminal/tool-terminal/tests/tools.spec.ts +++ b/packages/terminal/tool-terminal/tests/tools.spec.ts @@ -8,10 +8,11 @@ import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRuntime, { renderToolsSdk } from '@deepseek-ai/dsh-tools' import type { ToolSdkSchema } from '@deepseek-ai/dsh-tools/src/ts-types.ts' import TerminalSessionService, { TerminalSessionId } from '@deepseek-ai/dsh-terminal' -import type { TerminalBackend, TerminalBackendSession, TerminalSendOperation, TerminalSendRequest, TerminalSessionStatus, TerminalSignal } from '@deepseek-ai/dsh-terminal' +import type { TerminalBackend, TerminalBackendSession, TerminalSendOperation, TerminalSendRead, TerminalSendRequest, TerminalSessionStatus, TerminalSignal } from '@deepseek-ai/dsh-terminal' import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' import * as ToolTasks from '@deepseek-ai/dsh-tool-jobs' import * as ToolPty from '@deepseek-ai/dsh-tool-terminal' +import { sendSource } from '../src/background.ts' function fakeAgent(ctx: Context, rawId: string): Agent { const scope = ctx.plugin(() => {}) @@ -54,7 +55,11 @@ class StubSession implements TerminalBackendSession { })) const operation: TerminalSendOperation = { done, - readOutput: () => ({ delta: this.delta, truncated: this.deltaTruncated }), + readOutput: () => { + const delta = this.delta + this.delta = '' + return { delta, truncated: this.deltaTruncated } + }, cancel: () => { if (cancelled) return false cancelled = true @@ -402,6 +407,19 @@ describe('tool-terminal foreground API', () => { }) }) +describe('sendSource', () => { + it('reads nothing before the send starts and counts delivered bytes afterwards', () => { + const reads: TerminalSendRead[] = [{ delta: '界', truncated: false }, { delta: '', truncated: true }] + const send: { operation?: TerminalSendOperation } = {} + const source = sendSource(() => send.operation) + expect(source.read(0)).toEqual({ text: '', nextOffset: 0, lossy: false }) + send.operation = { readOutput: () => reads.shift()!, cancel: () => false, done: new Promise(() => {}) } + expect(source.read(0)).toEqual({ text: '界', nextOffset: 3, lossy: false }) + // A truncated delta carries the same marker the foreground read shows. + expect(source.read(3)).toEqual({ text: '[output truncated]', nextOffset: 21, lossy: false }) + }) +}) + describe('tool-terminal task integration', () => { it('registers a generic task and exposes incremental output', async () => { const { ctx, agent } = await setup(true) From 2132b7beebc141a371afb2cedcac7020f8393108 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 16:43:15 +0800 Subject: [PATCH 034/100] refactor(session-controller): drop the job roster from the control stream The control baseline and frames carry queues and projections only; the SessionJob row type, the jobs frame, the registry subscription, and the client jobsBySession mirror are gone, and every client fixture drops the empty mirror. The roster moves to dsh-api-job-controller's job.rows stream in the next change. --- packages/api/remotes/src/client/index.ts | 1 - .../api/session-controller/README.i18n.yaml | 4 +- packages/api/session-controller/README.md | 3 +- packages/api/session-controller/README.zh.md | 3 +- packages/api/session-controller/package.json | 5 - .../src/client/sessions/manager.ts | 22 -- .../src/client/sessions/service.ts | 13 +- .../api/session-controller/src/control.ts | 48 +--- packages/api/session-controller/src/types.ts | 21 -- .../tests/control-jobs.host.spec.ts | 248 ------------------ .../tests/manager.client.spec.ts | 65 +---- .../tests/transport.client.spec.ts | 4 +- .../locale/tests/language-row.client.spec.tsx | 2 +- .../ui-chat/tests/chat-view.client.spec.tsx | 2 +- .../tests/gate-branch-tails.client.spec.tsx | 4 +- .../tests/transcript-view-row.client.spec.tsx | 2 +- .../conversation-registry.client.spec.ts | 2 +- .../tests/enter-behavior-row.client.spec.tsx | 2 +- .../tests/input-bar.client.spec.tsx | 2 +- .../tests/input-matrix.client.spec.tsx | 2 +- .../tests/input-scenarios.client.spec.tsx | 2 +- .../tests/skeleton.client.spec.tsx | 2 +- .../tests/ui-session.client.spec.ts | 2 +- .../tests/conversation-ui.client.spec.tsx | 2 +- .../tests/appearance-row.client.spec.tsx | 2 +- .../tests/font-size-row.client.spec.tsx | 2 +- .../tests/coverage-tails.client.spec.tsx | 2 +- .../ui-tool/tests/diff-card.client.spec.tsx | 6 +- .../ui-tool/tests/image-card.client.spec.tsx | 2 +- .../ui-tool/tests/read-card.client.spec.tsx | 6 +- .../ui-tool/tests/search-card.client.spec.tsx | 2 +- .../tests/terminal-card.client.spec.tsx | 8 +- .../ui-tool/tests/web-card.client.spec.tsx | 2 +- .../ui-trajectory/tests/views.client.spec.tsx | 2 +- .../tests/plan-review-panel.client.spec.tsx | 2 +- .../user-questions-composer.client.spec.tsx | 2 +- .../tests/workflow-run.client.spec.tsx | 2 +- .../ui-workspace/tests/apply.client.spec.ts | 2 +- .../ui-workspace/tests/tree.client.spec.ts | 2 +- .../tests/workspace-browser.client.spec.tsx | 2 +- .../tests/workspace-picker.client.spec.tsx | 2 +- .../tests/workspaces-service.client.spec.ts | 2 +- .../client-runtime/src/sessions.ts | 2 +- pnpm-lock.yaml | 3 - 44 files changed, 52 insertions(+), 466 deletions(-) delete mode 100644 packages/api/session-controller/tests/control-jobs.host.spec.ts diff --git a/packages/api/remotes/src/client/index.ts b/packages/api/remotes/src/client/index.ts index ce08f3dbe3..e0185c5176 100644 --- a/packages/api/remotes/src/client/index.ts +++ b/packages/api/remotes/src/client/index.ts @@ -34,7 +34,6 @@ export type {} from '@deepseek-ai/dsh-api-job-controller/remote' export type * from '@deepseek-ai/dsh-api-job-controller/types' export type {} from '@deepseek-ai/dsh-api-workspace-controller/remote' export type * from '@deepseek-ai/dsh-api-workspace-controller/types' -export type { SessionJob as JobView } from '@deepseek-ai/dsh-api-session-controller/types' // The forwarded-event allowlist's selection seat: without it in the consumer's // compilation face `TypertRemoteEvent` is `never` and every `$on` call fails. export type { ApiRemoteForwardedEvent } from '../types.ts' diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml index 9f55558821..ad6ea9d524 100644 --- a/packages/api/session-controller/README.i18n.yaml +++ b/packages/api/session-controller/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/api/session-controller/README.md -README.md: 4414cd7221b40cc880122415e83b6dc3818df481 -README.zh.md: 8f457d4a94f57c802f67624d9c84ba15c78b1ada +README.md: 941c255d3923b4b51635381b2f45f83780bb60c8 +README.zh.md: 3dfe2a206fa7657e57e9c3b43e40fcd75e8c1bc0 diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md index 4414cd7221..941c255d39 100644 --- a/packages/api/session-controller/README.md +++ b/packages/api/session-controller/README.md @@ -29,7 +29,7 @@ Each endpoint states its activation policy. List, search, attachment, history pa The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, and `append` changes, and repairs reconnect or sequence gaps through a tail page. Backwards paging has two verbs: `loadOlder()` pulls one 50-message page, and `loadThrough(seq)` — the turn-jump loader — loops 200-message pages until the window covers the target seq, lowering a shared target on repeated calls, stopping on a page that makes no progress, and reporting busy through the same `loadingOlder` snapshot bit. Ordinary records cover `[event.seq, event.seq]`; packed rows cover `[event.seq, event.seq + memberCount - 1]`. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces queue, jobs, and projection state instead of treating transient values as durable events. -A `SessionJob` row carries `record: true` exactly when the job declared an observation record; streaming that record is the job controller's `job.observe` (see [`dsh-api-job-controller`](../job-controller/README.md)), while this package keeps the roster on the control stream. +Background-job rows and observation streams belong to [`dsh-api-job-controller`](../job-controller/README.md); the control stream carries queues and projections only. The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. Session derives each echo's `transcript`, `queued`, or `steering` placement from its current running state and the requested delivery mode, then retains that placement while serialization is in flight. The prompt's `requestId` is the correlation identity: the Host echoes it as the durable user source's `rpcId`, and queue occurrences project it as `SessionQueuedItem.rpcId`. An echo retires one animation frame after its durable event or queue occurrence is observed (the delay keeps it renderable until the replacement is ready), immediately when its identified prompt fails or is abandoned, and as failed on disposal; each retirement fires the registered `onRetire` callback exactly once. Echoes are Client memory only; reload and reconnect rebuild the conversation from durable events alone. @@ -61,7 +61,6 @@ No direct effect; model requests remain owned by the Agent and LLM packages. -- Control baselines represent process-local state and therefore cannot reconstruct jobs after a Host restart. - A failed follow resumption remains visible to the caller instead of retrying indefinitely. - File-reference completion uses the shared Agent lookup and can resume a cold Session; the `skills/list` catalog is the non-activating alternative for skill metadata. diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md index 8f457d4a94..3dfe2a206f 100644 --- a/packages/api/session-controller/README.zh.md +++ b/packages/api/session-controller/README.zh.md @@ -29,7 +29,7 @@ kind: "package-reference" Client adapter 提供 `SessionEventStream`,即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow,只发布连续的 `replace`、`prepend` 和 `append` 变更,并通过 tail page 修复重连或 seq 缺口。向后分页有两个动词:`loadOlder()` 拉一页 50 条 message,而 `loadThrough(seq)`——轮次跳转加载器——按 200 条 message 一页循环拉取直到窗口覆盖目标 seq,重复调用会下调共享目标,遇到无进展的页即停止,忙碌状态复用同一个 `loadingOlder` 快照位。普通 record 覆盖 `[event.seq, event.seq]`,packed row 覆盖 `[event.seq, event.seq + memberCount - 1]`。业务、persistence 或无法恢复的连续性错误会终止 stream,只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`;每代都以完整的进程本地 baseline 开始,因此重连会替换 queue、jobs 和 projection 状态,而不会把瞬态值当作 durable event。 -`SessionJob` 行恰在该 job 声明了观测 record 时携带 `record: true`;流式发送该 record 的是 job 控制器的 `job.observe`(见 [`dsh-api-job-controller`](../job-controller/README.zh.md)),本包只在控制流上保留名册。 +后台 job 的名册行与观测流属于 [`dsh-api-job-controller`](../job-controller/README.zh.md);控制流只承载队列与投影。 Session 对象还承载本地提交回显:`session.beginSubmission` 在调用方序列化与 prompt 之前,同步把一条回显写入 `SessionSnapshot.pendingSubmissions`,会话 UI 因此能在点击提交的当帧显示消息。Session 根据当前运行状态与请求的投递模式推导每条回显的 `transcript`、`queued` 或 `steering` 位置,并在序列化期间保留该位置。prompt 的 `requestId` 是关联标识:Host 把它回显为 durable user source 的 `rpcId`,queue occurrence 也把它投影为 `SessionQueuedItem.rpcId`。回显在观察到其 durable event 或 queue occurrence 后延迟一个动画帧退休,该延迟保证替代内容就绪前回显仍可渲染;带标识的 prompt 失败或被放弃时立即退休,销毁时按 failed 退休;每次退休恰好触发一次注册的 `onRetire` 回调。回显只存在于 Client 内存;刷新与重连只从 durable event 重建会话。 @@ -61,7 +61,6 @@ Session 对象还承载本地提交回显:`session.beginSubmission` 在调用 -- Control baseline 表示进程本地状态,因此 Host 重启后无法重建 jobs。 - follow 恢复失败会对调用方可见,而不会无限重试。 - 文件引用补全使用共享 Agent lookup,因此可能恢复冷 Session;`skills/list` 目录是不激活 Agent 的 skill 元数据读取路径。 diff --git a/packages/api/session-controller/package.json b/packages/api/session-controller/package.json index e60bfd4517..e836e921ae 100644 --- a/packages/api/session-controller/package.json +++ b/packages/api/session-controller/package.json @@ -82,7 +82,6 @@ "@deepseek-ai/dsh-attachment": "workspace:^", "@deepseek-ai/dsh-client-connection": "workspace:^", "@deepseek-ai/dsh-file-reference": "workspace:^", - "@deepseek-ai/dsh-jobs": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-native-command": "workspace:^", "@deepseek-ai/dsh-scope": "workspace:^", @@ -101,9 +100,6 @@ "@deepseek-ai/dsh-workspace": "workspace:^" }, "peerDependenciesMeta": { - "@deepseek-ai/dsh-jobs": { - "optional": true - }, "@deepseek-ai/dsh-session-persistence": { "optional": true }, @@ -121,7 +117,6 @@ "@deepseek-ai/dsh-client-connection": "workspace:^", "@deepseek-ai/dsh-client-store": "workspace:^", "@deepseek-ai/dsh-file-reference": "workspace:^", - "@deepseek-ai/dsh-jobs": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-native-command": "workspace:^", "@deepseek-ai/dsh-permission-presets": "workspace:^", diff --git a/packages/api/session-controller/src/client/sessions/manager.ts b/packages/api/session-controller/src/client/sessions/manager.ts index fd39fefedf..0c143d7b6d 100644 --- a/packages/api/session-controller/src/client/sessions/manager.ts +++ b/packages/api/session-controller/src/client/sessions/manager.ts @@ -10,7 +10,6 @@ import type { SessionControlFrame, SessionQueuedItem, SessionSummary, - SessionJob as JobView, } from '../../types.ts' import { mergeOrderedBaseline } from '../ordered-baseline.ts' import { isRemoteFailure } from '@deepseek-ai/dsh-api-gateway/client' @@ -56,8 +55,6 @@ export interface SessionListSnapshot { phase: SessionListPhase error: RemoteFailure | null subagentsByParent: Readonly> - /** Background jobs per session; an absent key is an empty set. */ - jobsBySession: Readonly> currentAddress: SubagentAddress | undefined } @@ -126,12 +123,6 @@ export class SessionManager { private readonly catalogStale = new Set() private readonly openCatalogs = new Set() private readonly catalogDebounce = new Map>() - /** - * Background jobs per session, last-wins from Session Controller's control - * stream. An empty set is stored as an absent key, so absence and `[]` are - * one representation. - */ - private readonly jobsBySession = new Map() private selected: SessionId | undefined @@ -669,12 +660,6 @@ export class SessionManager { this.notifier.markDirty() return } - if (frame.type === 'jobs') { - if (frame.jobs.length === 0) this.jobsBySession.delete(frame.sessionId) - else this.jobsBySession.set(frame.sessionId, frame.jobs) - this.notifier.markDirty() - return - } this.queues.set(frame.sessionId, frame.items) this.sessions.get(frame.sessionId)?.handleControlFrame(frame) } @@ -685,11 +670,6 @@ export class SessionManager { this.queues.set(sessionId as SessionId, items) } - this.jobsBySession.clear() - for (const [sessionId, jobs] of Object.entries(baseline.jobs)) { - if (jobs.length > 0) this.jobsBySession.set(sessionId as SessionId, jobs) - } - for (const [sessionId, block] of Object.entries(baseline.projections)) { const store = this.projectionStore(sessionId as SessionId) const asOfSeq = sessionSeqCursor(block.asOfSeq) @@ -739,7 +719,6 @@ export class SessionManager { if (durableSubagent) this.sessions.get(sessionId)?.handleRunning(false) else this.sessions.get(sessionId)?.handleRemoved() this.queues.delete(sessionId) - this.jobsBySession.delete(sessionId) if (!durableSubagent) this.projectionStores.delete(sessionId) const inflightCatalog = this.catalogInflight.get(sessionId) if (inflightCatalog !== undefined) { @@ -951,7 +930,6 @@ export class SessionManager { phase: this.listPhase, error: this.listError, subagentsByParent: Object.fromEntries(this.catalogs), - jobsBySession: Object.fromEntries(this.jobsBySession), currentAddress: current === undefined ? undefined : this.addresses.get(current), } } diff --git a/packages/api/session-controller/src/client/sessions/service.ts b/packages/api/session-controller/src/client/sessions/service.ts index d1d840c513..521752da39 100644 --- a/packages/api/session-controller/src/client/sessions/service.ts +++ b/packages/api/session-controller/src/client/sessions/service.ts @@ -20,7 +20,6 @@ import { SessionSeq, type SessionId } from '@deepseek-ai/dsh-session/types' import { workspaceTitleOf } from '@deepseek-ai/dsh-util-workspace-path' import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types' import { SESSION_SEARCH_RESULT_LIMIT } from '../../types.ts' -import type { SessionJob as JobView } from '../../types.ts' import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types' import { createSnapshotStore, type SnapshotStore, @@ -76,12 +75,6 @@ export interface SessionListState { phase: SessionListPhase /** Direct durable catalogs keyed by their selected parent address. */ subagentsByParent: Readonly> - /** - * Background jobs each session can see, mirrored last-wins from Session - * Controller's control baseline and `jobs` frames. A missing key is an empty - * set, so consumers read absence rather than a sentinel. - */ - jobsBySession: Readonly> /** Current session's catalog-derived address, absent on ordinary navigation. */ currentAddress: SubagentAddress | undefined } @@ -233,7 +226,7 @@ export class ClientSessions implements ISessions { ) this.list = createSnapshotStore({ ids: [], byId: {}, current: undefined, phase: 'pending', - subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined, + subagentsByParent: {}, currentAddress: undefined, }) // The manager owns wire truth; the store is its projection. Manager // notifications are already microtask-batched. @@ -576,7 +569,7 @@ export class ClientSessions implements ISessions { /** Project the manager's list snapshot into the store (title derivation is display-only). */ private projectList(): void { const { - items, current, phase, subagentsByParent, jobsBySession, currentAddress, + items, current, phase, subagentsByParent, currentAddress, } = this.manager.getListSnapshot() const ids: SessionId[] = [] const byId: Record = {} @@ -642,7 +635,7 @@ export class ClientSessions implements ISessions { ...(currentAddress === undefined ? {} : { subagentAddress: currentAddress }), }) } - this.list.set({ ids, byId, current, phase, subagentsByParent, jobsBySession, currentAddress }) + this.list.set({ ids, byId, current, phase, subagentsByParent, currentAddress }) this.pruneScopes() } diff --git a/packages/api/session-controller/src/control.ts b/packages/api/session-controller/src/control.ts index b96cbb7f9d..ad64f36ec0 100644 --- a/packages/api/session-controller/src/control.ts +++ b/packages/api/session-controller/src/control.ts @@ -1,9 +1,8 @@ -/** Live Session queue, jobs, and projection state with reconnect baselines. */ +/** Live Session queue and projection state with reconnect baselines. */ import type { Context } from '@deepseek-ai/cordis' import type { Agent } from '@deepseek-ai/dsh-agent' import { Deque } from '@deepseek-ai/dsh-deque' -import type { JobSnapshot } from '@deepseek-ai/dsh-jobs' import type { Session, SessionEvent, SessionEventMap, SessionId, UserMessage, } from '@deepseek-ai/dsh-session' @@ -11,7 +10,6 @@ import type { JsonValue } from '@deepseek-ai/dsh-util-values' import type { SessionControlBaseline, SessionControlFrame, - SessionJob, SessionProjectionBaseline, SessionProjectionValues, SessionQueuedItem, @@ -21,7 +19,7 @@ import type { export class SessionControlController { private readonly streams = new Set() - /** @param ctx - Host context carrying live Agent, projection, and jobs services. */ + /** @param ctx - Host context carrying live Agent and projection services. */ constructor(private readonly ctx: Context) { ctx.on('session/event', (session, event) => { this.onSessionEvent(session, event) }) ctx.sessionProjections.onChanged((session, key, value, seq) => { @@ -33,13 +31,6 @@ export class SessionControlController { seq, }) }) - ctx.inject(['jobs'], (jobsCtx) => { - jobsCtx.jobs.onJobsChanged((owner) => { this.onJobsChanged(owner) }) - }) - ctx.on('session/created', (session) => { - const jobs = this.jobsFor(this.ctx.agents.get(session.id)) - if (jobs.length > 0) this.broadcast({ type: 'jobs', sessionId: session.id, jobs }) - }) ctx.effect(() => () => { for (const stream of this.streams) stream.end() this.streams.clear() @@ -67,15 +58,12 @@ export class SessionControlController { private baseline(): SessionControlBaseline { const sessions = this.ctx.sessions.list() const queues = Object.create(null) as Record - const jobs = Object.create(null) as Record for (const session of sessions) { const agent = this.ctx.agents.get(session.id) queues[session.id] = agent?.session === session ? queueItems(agent) : [] - jobs[session.id] = this.jobsFor(agent) } return { queues, - jobs, projections: this.projectionBaseline(sessions), } } @@ -106,25 +94,6 @@ export class SessionControlController { }) } - private onJobsChanged(owner: Agent | undefined): void { - if (owner !== undefined) { - this.broadcast({ type: 'jobs', sessionId: owner.id, jobs: this.jobsFor(owner) }) - return - } - for (const session of this.ctx.sessions.list()) { - this.broadcast({ - type: 'jobs', - sessionId: session.id, - jobs: this.jobsFor(this.ctx.agents.get(session.id)), - }) - } - } - - private jobsFor(agent: Agent | undefined): SessionJob[] { - const jobs = this.ctx.get('jobs') - return jobs === undefined ? [] : jobs.list(agent).map(jobView) - } - private broadcast(frame: SessionControlFrame): void { for (const stream of this.streams) stream.push(frame) } @@ -202,16 +171,3 @@ function promptRpcId(message: UserMessage): Pick { const source = message.source return source.kind === 'user' && 'rpcId' in source ? { rpcId: source.rpcId } : {} } - -function jobView(job: JobSnapshot): SessionJob { - return { - id: job.id, - kind: job.kind, - label: job.label, - status: job.status, - ...(job.detail === undefined ? {} : { detail: job.detail }), - startedAt: job.startedAt, - ...(job.finishedAt === undefined ? {} : { finishedAt: job.finishedAt }), - ...(job.outputTotal === undefined ? {} : { record: true as const }), - } -} diff --git a/packages/api/session-controller/src/types.ts b/packages/api/session-controller/src/types.ts index d3ab795ecb..d65d977e9a 100644 --- a/packages/api/session-controller/src/types.ts +++ b/packages/api/session-controller/src/types.ts @@ -9,7 +9,6 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm/types' import type { ChunkRow } from '@deepseek-ai/dsh-session/chunk-rows' import type { SessionId } from '@deepseek-ai/dsh-session/types' import type { SessionProjectionMap } from '@deepseek-ai/dsh-session-projection/types' -import type { JobId } from '@deepseek-ai/dsh-jobs/brand' import type { JsonValue } from '@deepseek-ai/dsh-util-values' import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types' @@ -479,28 +478,9 @@ export interface SessionQueuedItem { } } -/** Browser-safe background-job row. */ -export interface SessionJob { - readonly id: JobId - readonly kind: string - readonly label: string - readonly status: 'running' | 'stopping' | 'completed' | 'killed' | 'failed' - readonly detail?: string - readonly startedAt: number - readonly finishedAt?: number - /** - * Present exactly when the job declared an observation record: the row is - * observable through the job controller's `job.observe` stream, whose - * `opened` anchor carries the live byte offsets. The roster refreshes on - * lifecycle commits only, so it mirrors no byte count. - */ - readonly record?: true -} - /** Complete live control baseline emitted once per control stream generation. */ export interface SessionControlBaseline { readonly queues: Readonly> - readonly jobs: Readonly> readonly projections: Readonly> } @@ -516,7 +496,6 @@ export interface SessionProjectionUpdate { export type SessionControlFrame = | { readonly type: 'baseline'; readonly value: SessionControlBaseline } | { readonly type: 'queue'; readonly sessionId: SessionId; readonly items: readonly SessionQueuedItem[] } - | { readonly type: 'jobs'; readonly sessionId: SessionId; readonly jobs: readonly SessionJob[] } | ({ readonly type: 'projection' } & SessionProjectionUpdate) diff --git a/packages/api/session-controller/tests/control-jobs.host.spec.ts b/packages/api/session-controller/tests/control-jobs.host.spec.ts deleted file mode 100644 index 9d80501966..0000000000 --- a/packages/api/session-controller/tests/control-jobs.host.spec.ts +++ /dev/null @@ -1,248 +0,0 @@ -import { Context } from '@deepseek-ai/cordis' -import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' -import type { Agent } from '@deepseek-ai/dsh-agent' -import type { JobOutcome } from '@deepseek-ai/dsh-jobs' -import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' -import SessionStore, { SessionId } from '@deepseek-ai/dsh-session' -import type { Session } from '@deepseek-ai/dsh-session' -import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection' -import { describe, expect, it } from 'vitest' -import { SessionControlController } from '../src/control.ts' -import type { SessionControlFrame } from '../src/types.ts' - -type BaselineFrame = Extract -type JobFrame = Extract - -function producer(label = 'sleep 60') { - let settle!: (outcome: JobOutcome) => void - const reads = { count: 0 } - const spec = { - kind: 'bash' as const, - label, - run: () => ({ - cancel: () => {}, - done: new Promise((resolve) => { settle = resolve }), - readOutput: () => { reads.count += 1; return 'stolen output' }, - }), - } - return { spec, reads, settle: (outcome: JobOutcome) => { settle(outcome) } } -} - -async function harness(withJobs: boolean): Promise<{ - ctx: Context - session: Session - agent: Agent - control: SessionControlController -}> { - const ctx = new Context() - await ctx.plugin(SessionStore) - await ctx.plugin(AgentRegistry) - await ctx.plugin(SessionProjectionRegistry) - if (withJobs) { - await ctx.plugin(LocalJobRegistry) - ctx.jobs.attachController('session-controller-test') - } - const session = ctx.sessions.create() - const agent = { - id: session.id, - session, - inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }), - status: 'idle', - ctx, - } as Agent - ctx.agents.register(agent) - const control = new SessionControlController(ctx) - await new Promise(resolve => setTimeout(resolve, 0)) - return { ctx, session, agent, control } -} - -async function baseline(control: SessionControlController): Promise { - const abort = new AbortController() - const iterator = control.control(abort.signal)[Symbol.asyncIterator]() - const first = await iterator.next() - abort.abort() - await iterator.next() - if (first.done || first.value.type !== 'baseline') throw new Error('missing control baseline') - return first.value -} - -async function collectJobs( - iterable: AsyncIterable, - count: number, - abort: AbortController, -): Promise { - const jobs: JobFrame[] = [] - for await (const frame of iterable) { - if (frame.type !== 'jobs') continue - jobs.push(frame) - if (jobs.length >= count) abort.abort() - } - return jobs -} - -describe('Session control jobs baseline', () => { - it('represents an attached session with no jobs as an empty set', async () => { - const { session, control } = await harness(true) - const frame = await baseline(control) - expect(frame.value.jobs[session.id]).toEqual([]) - }) - - it('carries the visible set when the stream opens', async () => { - const { ctx, session, agent, control } = await harness(true) - ctx.jobs.start({ ...producer('pnpm run build').spec, owner: agent }) - const frame = await baseline(control) - const jobs = frame.value.jobs[session.id] - expect(jobs).toHaveLength(1) - const [job] = jobs ?? [] - expect(job?.startedAt).toBeTypeOf('number') - expect({ ...job, startedAt: 0 }).toEqual({ - id: 'bash-1', - kind: 'bash', - label: 'pnpm run build', - status: 'running', - startedAt: 0, - }) - }) -}) - -describe('Session control jobs updates', () => { - it('publishes existing unowned jobs when a Session attaches after the stream opens', async () => { - const { ctx, control } = await harness(true) - const abort = new AbortController() - const iterator = control.control(abort.signal)[Symbol.asyncIterator]() - await expect(iterator.next()).resolves.toMatchObject({ value: { type: 'baseline' } }) - const task = producer('already running') - const id = ctx.jobs.start(task.spec) - await expect(iterator.next()).resolves.toMatchObject({ value: { type: 'jobs' } }) - - const created = ctx.sessions.create(SessionId('late-session')) - await expect(iterator.next()).resolves.toMatchObject({ - value: { - type: 'jobs', - sessionId: created.id, - jobs: [expect.objectContaining({ id, label: 'already running' })], - }, - }) - - task.settle({ status: 'completed' }) - abort.abort() - await iterator.return?.() - }) - - it('pushes the owner whole set on registration, stopping, and settlement', async () => { - const { ctx, session, agent, control } = await harness(true) - const abort = new AbortController() - const collected = collectJobs(control.control(abort.signal), 3, abort) - - const task = producer() - const id = ctx.jobs.start({ ...task.spec, owner: agent }) - ctx.jobs.kill(id, agent, 'test') - task.settle({ status: 'killed', detail: 'signal: SIGTERM' }) - - const frames = await collected - expect(frames.map(frame => frame.sessionId)).toEqual([session.id, session.id, session.id]) - expect(frames.map(frame => frame.jobs[0]?.status)).toEqual(['running', 'stopping', 'killed']) - expect(frames[2]?.jobs[0]?.detail).toBe('signal: SIGTERM') - expect(frames[2]?.jobs[0]?.finishedAt).toBeTypeOf('number') - }) - - it('drops internal registry fields from the browser view', async () => { - const { ctx, agent, control } = await harness(true) - const abort = new AbortController() - const collected = collectJobs(control.control(abort.signal), 1, abort) - ctx.jobs.start({ ...producer().spec, owner: agent, outputLimitBytes: 1_024 }) - - const [frame] = await collected - expect(Object.keys(frame?.jobs[0] ?? {}).sort()).toEqual([ - 'id', - 'kind', - 'label', - 'startedAt', - 'status', - ]) - }) - - it('flags record-declaring jobs instead of mirroring a byte count the roster never refreshes', async () => { - const { ctx, agent, control } = await harness(true) - const abort = new AbortController() - const collected = collectJobs(control.control(abort.signal), 1, abort) - ctx.jobs.start({ - kind: 'bash', - label: 'observable run', - owner: agent, - record: true, - run: (job) => { - job.append('hi') - return { cancel: () => {}, done: new Promise(() => {}) } - }, - }) - - const [frame] = await collected - expect(frame?.jobs[0]).toMatchObject({ record: true }) - expect(frame?.jobs[0]).not.toHaveProperty('outputTotal') - }) - - it('fans an unowned change out to every attached session', async () => { - const { ctx, control } = await harness(true) - const second = ctx.sessions.create() - const abort = new AbortController() - const collected = collectJobs(control.control(abort.signal), 2, abort) - - ctx.jobs.start(producer('open to every caller').spec) - - const frames = await collected - expect(new Set(frames.map(frame => frame.sessionId)).size).toBe(2) - expect(frames.some(frame => frame.sessionId === second.id)).toBe(true) - for (const frame of frames) expect(frame.jobs[0]?.label).toBe('open to every caller') - }) - - it('does not resume persisted sessions while projecting an unowned change', async () => { - const { ctx, control } = await harness(true) - const coldId = SessionId('session-cold-tasks') - let loaded = false - ctx.provide('sessionPersistence', { - list: async () => [{ version: 0, id: coldId, createdAt: 5, cwd: '/tmp' }], - locate: () => undefined, - load: () => { loaded = true; throw new Error('job projection must not load a cold log') }, - } as never) - const abort = new AbortController() - const collected = collectJobs(control.control(abort.signal), 1, abort) - - ctx.jobs.start(producer().spec) - await collected - expect(loaded).toBe(false) - expect(ctx.agents.get(coldId)).toBeUndefined() - }) - - it('reports empty sets when no jobs registry is composed', async () => { - const { session, control } = await harness(false) - const frame = await baseline(control) - expect(frame.value.jobs[session.id]).toEqual([]) - }) - - it('never consumes model output while projecting a lifecycle', async () => { - const { ctx, agent, control } = await harness(true) - const abort = new AbortController() - const collected = collectJobs(control.control(abort.signal), 3, abort) - - const task = producer() - const id = ctx.jobs.start({ ...task.spec, owner: agent }) - ctx.jobs.kill(id, agent, 'test') - task.settle({ status: 'killed', detail: 'signal: SIGTERM' }) - await collected - - expect(task.reads.count).toBe(0) - }) - - it('never consumes model output while producing a baseline', async () => { - const { ctx, agent, control } = await harness(true) - const task = producer() - ctx.jobs.start({ ...task.spec, owner: agent }) - - const frame = await baseline(control) - - expect(frame.value.jobs[agent.id]).toHaveLength(1) - expect(task.reads.count).toBe(0) - }) - -}) diff --git a/packages/api/session-controller/tests/manager.client.spec.ts b/packages/api/session-controller/tests/manager.client.spec.ts index 14f7c25fca..f59d1a782d 100644 --- a/packages/api/session-controller/tests/manager.client.spec.ts +++ b/packages/api/session-controller/tests/manager.client.spec.ts @@ -187,7 +187,7 @@ describe('list lifecycle', () => { frame({ type: 'baseline', value: { - queues: {}, jobs: {}, + queues: {}, projections: { [S1]: { asOfSeq: 2, values: {} } }, }, }) @@ -200,7 +200,7 @@ describe('list lifecycle', () => { frame({ type: 'baseline', value: { - queues: {}, jobs: {}, + queues: {}, projections: { [S1]: { asOfSeq: 2, values: { title: 'Durable' } } }, }, }) @@ -919,64 +919,3 @@ describe('completed reminder', () => { expect(entry(manager, S2)?.completed).toBe(true) }) }) - -describe('background-job mirror', () => { - const view = (over: Partial<{ id: string; status: string; label: string }> = {}) => ({ - id: 'bash-1', kind: 'bash', label: 'pnpm run build', status: 'running', startedAt: 5, ...over, - }) - const tasksFrame = ( - sessionId: SessionId, - jobs: unknown[], - ): Extract => ({ - type: 'jobs', sessionId, jobs: jobs as never, - }) - - it('mirrors the whole set last-wins, keyed per session, with no Session instance needed', () => { - const manager = makeManager() - manager.handleControlFrame(tasksFrame(S1, [view()])) - manager.handleControlFrame(tasksFrame(S2, [view({ id: 'pwsh-1', label: 'other' })])) - const first = manager.getListSnapshot().jobsBySession - expect(first[S1]).toEqual([view()]) - expect(first[S2]?.[0]?.label).toBe('other') - - // Last-wins: the newer whole set replaces, it does not merge. - manager.handleControlFrame(tasksFrame(S1, [view({ status: 'completed' })])) - expect(manager.getListSnapshot().jobsBySession[S1]).toEqual([view({ status: 'completed' })]) - }) - - it('stores an emptied set as an absent key so absence and [] read alike', () => { - const manager = makeManager() - manager.handleControlFrame(tasksFrame(S1, [view()])) - expect(S1 in manager.getListSnapshot().jobsBySession).toBe(true) - manager.handleControlFrame(tasksFrame(S1, [])) - expect(S1 in manager.getListSnapshot().jobsBySession).toBe(false) - }) - - it('clears the mirror when the next control baseline has no jobs', () => { - const manager = makeManager() - manager.handleControlFrame(tasksFrame(S1, [view()])) - manager.handleControlFrame({ - type: 'baseline', - value: { queues: {}, jobs: {}, projections: {} }, - }) - expect(S1 in manager.getListSnapshot().jobsBySession).toBe(false) - }) - - it('drops the rows when the session is removed, whichever stream lands first', () => { - const manager = makeManager() - manager.handleSessionAdded(summary(S1, { blank: true })) - manager.handleControlFrame(tasksFrame(S1, [view()])) - manager.handleSessionRemoved(S1) - expect(S1 in manager.getListSnapshot().jobsBySession).toBe(false) - }) - - it('notifies list subscribers so an open header re-renders without a poll', async () => { - const manager = makeManager() - const seen = vi.fn() - manager.subscribe(seen) - manager.handleControlFrame(tasksFrame(S1, [view()])) - // The notifier batches on a microtask; the frame itself is already applied. - await Promise.resolve() - expect(seen).toHaveBeenCalled() - }) -}) diff --git a/packages/api/session-controller/tests/transport.client.spec.ts b/packages/api/session-controller/tests/transport.client.spec.ts index c5f50ad7de..560874d8d0 100644 --- a/packages/api/session-controller/tests/transport.client.spec.ts +++ b/packages/api/session-controller/tests/transport.client.spec.ts @@ -327,7 +327,7 @@ describe('Session Client stream adapters', () => { it('maps the Host-wide control baseline and deltas into one snapshot stream', async () => { const baseline: SessionControlFrame = { type: 'baseline', - value: { queues: {}, jobs: {}, projections: {} }, + value: { queues: {}, projections: {} }, } const update: SessionControlFrame = { type: 'queue', sessionId: 'session-1' as never, items: [], @@ -362,7 +362,7 @@ describe('Session Client stream adapters', () => { const baseline: SessionControlFrame = { type: 'baseline', - value: { queues: {}, jobs: {}, projections: {} }, + value: { queues: {}, projections: {} }, } const carrierFailed = vi.fn() const failed = vi.fn() diff --git a/packages/client/locale/tests/language-row.client.spec.tsx b/packages/client/locale/tests/language-row.client.spec.tsx index 44ddb31e7b..198127a703 100644 --- a/packages/client/locale/tests/language-row.client.spec.tsx +++ b/packages/client/locale/tests/language-row.client.spec.tsx @@ -15,7 +15,7 @@ const OPTIONS = [{ id: 'zh', label: '中文' }, { id: 'en', label: 'English' }] function emptySessions() { const store = createSnapshotStore( - { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined }) + { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined }) return bindSnapshotSelector(store) } function emptyWorkspaces() { diff --git a/packages/client/ui-chat/tests/chat-view.client.spec.tsx b/packages/client/ui-chat/tests/chat-view.client.spec.tsx index 9e0818f37c..f1029a50b8 100644 --- a/packages/client/ui-chat/tests/chat-view.client.spec.tsx +++ b/packages/client/ui-chat/tests/chat-view.client.spec.tsx @@ -194,7 +194,7 @@ const compaction = (over: Partial = {}): CompactionSummar /** Empty sessions-list hook for the global standard-kit seat. */ function emptySessions() { const store = createSnapshotStore( - { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined }) + { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined }) return bindSnapshotSelector(store) } diff --git a/packages/client/ui-chat/tests/gate-branch-tails.client.spec.tsx b/packages/client/ui-chat/tests/gate-branch-tails.client.spec.tsx index 57afd2abd8..7d42abb682 100644 --- a/packages/client/ui-chat/tests/gate-branch-tails.client.spec.tsx +++ b/packages/client/ui-chat/tests/gate-branch-tails.client.spec.tsx @@ -133,7 +133,7 @@ describe('render branch tails', () => { const chat = createChatStore().create() chat.actions.select({ turnSeq: 1, callId: 'ghost' } satisfies SelectionTarget) const emptyList = createSnapshotStore( - { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined }) + { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined }) const workspaces = emptyWorkspaces() const view = render( { const chat = createChatStore().create() chat.actions.select({ turnSeq: 9, callId: 'p1:code:1:code:1', toolName: 'read' } satisfies SelectionTarget) const emptyList = createSnapshotStore( - { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined }) + { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined }) const workspaces = emptyWorkspaces() const owners: DetailsToolOwnerProps[] = [] const view = render( diff --git a/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx b/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx index f946a28f1a..a22c273552 100644 --- a/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx +++ b/packages/client/ui-chat/tests/transcript-view-row.client.spec.tsx @@ -13,7 +13,7 @@ afterEach(cleanup) function emptySessions() { return bindSnapshotSelector(createSnapshotStore({ - ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined, + ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined, })) } diff --git a/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts b/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts index 9805bf189f..dc8f342c90 100644 --- a/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts +++ b/packages/client/ui-conversation/tests/conversation-registry.client.spec.ts @@ -73,7 +73,7 @@ function fakeSessions(ctx: Context): { sessions: ISessions; binding: SessionBind current: undefined, phase: 'ready', subagentsByParent: {}, - jobsBySession: {}, + currentAddress: undefined, }) const sessions = { diff --git a/packages/client/ui-conversation/tests/enter-behavior-row.client.spec.tsx b/packages/client/ui-conversation/tests/enter-behavior-row.client.spec.tsx index 44022cb553..ff8649695a 100644 --- a/packages/client/ui-conversation/tests/enter-behavior-row.client.spec.tsx +++ b/packages/client/ui-conversation/tests/enter-behavior-row.client.spec.tsx @@ -18,7 +18,7 @@ afterEach(() => { function emptySessions() { return bindSnapshotSelector(createSnapshotStore({ - ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined, + ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined, })) } diff --git a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx index 0edc8b9ef6..72e41bb829 100644 --- a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx +++ b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx @@ -162,7 +162,7 @@ function bench(over?: BenchOptions) { useSessionPendingInteraction: bindSnapshotSelector(createSnapshotStore(new Map())), useSessions: bindSnapshotSelector(createSnapshotStore({ ids: [], byId: {}, current: undefined, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined, + subagentsByParent: {}, currentAddress: undefined, })), useWorkspaces: bindSnapshotSelector(createSnapshotStore({ items: [], archivedSessionIds: [], state: 'idle', phase: 'ready', error: null, diff --git a/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx b/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx index bdb878672b..a5367c6304 100644 --- a/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx +++ b/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx @@ -49,7 +49,7 @@ function mountBar(shell: SessionInputShell, over?: { running?: boolean; disabled useSession: bindSnapshotSelector(session), useSessions: bindSnapshotSelector(createSnapshotStore({ ids: [], byId: {}, current: undefined, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined, + subagentsByParent: {}, currentAddress: undefined, })), useSessionPendingInteraction: bindSnapshotSelector( createSnapshotStore(new Map()), diff --git a/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx index ec7f586683..0babbf8dc1 100644 --- a/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx +++ b/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx @@ -138,7 +138,7 @@ async function scopedBench(register?: (inputTriggers: InputTriggerService) => vo useSession: bindSnapshotSelector(sessionStore), useSessions: bindSnapshotSelector(createSnapshotStore({ ids: [], byId: {}, current: undefined, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined, + subagentsByParent: {}, currentAddress: undefined, })), useSessionPendingInteraction: bindSnapshotSelector( createSnapshotStore(new Map()), diff --git a/packages/client/ui-conversation/tests/skeleton.client.spec.tsx b/packages/client/ui-conversation/tests/skeleton.client.spec.tsx index b431a51ff8..2e9dacdc12 100644 --- a/packages/client/ui-conversation/tests/skeleton.client.spec.tsx +++ b/packages/client/ui-conversation/tests/skeleton.client.spec.tsx @@ -146,7 +146,7 @@ function mount( ...listed && { [SID]: childRow }, }, current: SID, - phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined, + phase: 'ready', subagentsByParent: {}, currentAddress: undefined, }) const workspaces = createSnapshotStore(workspaceState(workspaceRows)) const session = createSnapshotStore(snapshot) diff --git a/packages/client/ui-session/tests/ui-session.client.spec.ts b/packages/client/ui-session/tests/ui-session.client.spec.ts index 3eca1b7a47..f44320b36d 100644 --- a/packages/client/ui-session/tests/ui-session.client.spec.ts +++ b/packages/client/ui-session/tests/ui-session.client.spec.ts @@ -40,7 +40,7 @@ function createSessionsBench(_ctx: Context): SessionsBench { current: undefined, phase: 'ready', subagentsByParent: {}, - jobsBySession: {}, + currentAddress: undefined, }) const bindings = new Map() diff --git a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx index 6839df928c..13ef3391fc 100644 --- a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx +++ b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx @@ -63,7 +63,7 @@ function props( }, current: PARENT, phase: 'ready', subagentsByParent: value === undefined ? nested : { [PARENT]: value, ...nested }, - jobsBySession: {}, + currentAddress: undefined, } satisfies SessionListState function useSessions(select: (snapshot: SessionListState) => T): T { diff --git a/packages/client/ui-theme/tests/appearance-row.client.spec.tsx b/packages/client/ui-theme/tests/appearance-row.client.spec.tsx index c42d6aa3b6..6d1f40366b 100644 --- a/packages/client/ui-theme/tests/appearance-row.client.spec.tsx +++ b/packages/client/ui-theme/tests/appearance-row.client.spec.tsx @@ -21,7 +21,7 @@ const COPY: Record = { function emptySessions() { const store = createSnapshotStore( - { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined }) + { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined }) return bindSnapshotSelector(store) } function emptyWorkspaces() { diff --git a/packages/client/ui-theme/tests/font-size-row.client.spec.tsx b/packages/client/ui-theme/tests/font-size-row.client.spec.tsx index 314576d572..eb33802368 100644 --- a/packages/client/ui-theme/tests/font-size-row.client.spec.tsx +++ b/packages/client/ui-theme/tests/font-size-row.client.spec.tsx @@ -23,7 +23,7 @@ const COPY: Record = { /** Empty global standard-kit hooks (the row reads neither). */ function emptySessions() { const store = createSnapshotStore( - { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined }) + { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined }) return bindSnapshotSelector(store) } function emptyWorkspaces() { diff --git a/packages/client/ui-tool/tests/coverage-tails.client.spec.tsx b/packages/client/ui-tool/tests/coverage-tails.client.spec.tsx index 04e464d968..062a4222bc 100644 --- a/packages/client/ui-tool/tests/coverage-tails.client.spec.tsx +++ b/packages/client/ui-tool/tests/coverage-tails.client.spec.tsx @@ -29,7 +29,7 @@ function listStore() { }, current: undefined, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, + subagentsByParent: {}, currentAddress: undefined, }) } diff --git a/packages/client/ui-tool/tests/diff-card.client.spec.tsx b/packages/client/ui-tool/tests/diff-card.client.spec.tsx index ed386b8321..d2906e6ccf 100644 --- a/packages/client/ui-tool/tests/diff-card.client.spec.tsx +++ b/packages/client/ui-tool/tests/diff-card.client.spec.tsx @@ -212,7 +212,7 @@ describe('FileMutationRow diff card', () => { byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, updatedAt: 0, cwd: '/w/app' } }, current: SID, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, + subagentsByParent: {}, currentAddress: undefined, }) @@ -363,13 +363,13 @@ describe('DetailsPanel diff Output section', () => { const chat = createChatStore().create() if (selection !== null) chat.actions.select(selection) const sessions = createSnapshotStore(cwd === undefined - ? { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined } + ? { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined } : { ids: [SID], byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, updatedAt: 0, cwd } }, current: SID, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, + subagentsByParent: {}, currentAddress: undefined, }) const session = createSnapshotStore(sessionSnapshot(SID)) diff --git a/packages/client/ui-tool/tests/image-card.client.spec.tsx b/packages/client/ui-tool/tests/image-card.client.spec.tsx index 53578e25d9..c5ccf03c9e 100644 --- a/packages/client/ui-tool/tests/image-card.client.spec.tsx +++ b/packages/client/ui-tool/tests/image-card.client.spec.tsx @@ -269,7 +269,7 @@ describe('ReadImageRow keyed toolview', () => { byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, updatedAt: 0, cwd: '/w/app' } }, current: SID, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, + subagentsByParent: {}, currentAddress: undefined, } as unknown as SessionListState) diff --git a/packages/client/ui-tool/tests/read-card.client.spec.tsx b/packages/client/ui-tool/tests/read-card.client.spec.tsx index 092a7ce506..9e3f547b3f 100644 --- a/packages/client/ui-tool/tests/read-card.client.spec.tsx +++ b/packages/client/ui-tool/tests/read-card.client.spec.tsx @@ -194,7 +194,7 @@ describe('ReadRow keyed toolview', () => { byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, updatedAt: 0, cwd: '/w/app' } }, current: SID, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, + subagentsByParent: {}, currentAddress: undefined, }) @@ -283,13 +283,13 @@ describe('DetailsPanel Output section (read)', () => { const chat = createChatStore().create() if (selection !== null) chat.actions.select(selection) const sessions = createSnapshotStore(cwd === undefined - ? { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined } + ? { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined } : { ids: [SID], byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, updatedAt: 0, cwd } }, current: SID, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, + subagentsByParent: {}, currentAddress: undefined, }) const session = createSnapshotStore(sessionSnapshot(SID)) diff --git a/packages/client/ui-tool/tests/search-card.client.spec.tsx b/packages/client/ui-tool/tests/search-card.client.spec.tsx index bc5213d02e..6e62152851 100644 --- a/packages/client/ui-tool/tests/search-card.client.spec.tsx +++ b/packages/client/ui-tool/tests/search-card.client.spec.tsx @@ -375,7 +375,7 @@ describe('DetailsPanel Output section (search)', () => { if (selection !== null) chat.actions.select(selection) const sessions = createSnapshotStore({ ids: [], byId: {}, current: undefined, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined, + subagentsByParent: {}, currentAddress: undefined, }) const session = createSnapshotStore(sessionSnapshot(SID)) const conversation = createSnapshotStore(conversationSnapshot()) diff --git a/packages/client/ui-tool/tests/terminal-card.client.spec.tsx b/packages/client/ui-tool/tests/terminal-card.client.spec.tsx index 064c25d4ec..7e036fce66 100644 --- a/packages/client/ui-tool/tests/terminal-card.client.spec.tsx +++ b/packages/client/ui-tool/tests/terminal-card.client.spec.tsx @@ -390,7 +390,7 @@ describe('BashRow terminal card', () => { byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, updatedAt: 0 } }, current: undefined, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, + subagentsByParent: {}, currentAddress: undefined, }) @@ -499,13 +499,13 @@ describe('DetailsPanel Output section', () => { const chat = createChatStore().create() if (selection !== null) chat.actions.select(selection) const sessions = createSnapshotStore(cwd === undefined - ? { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined } + ? { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined } : { ids: [SID], byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, updatedAt: 0, cwd } }, current: SID, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, + subagentsByParent: {}, currentAddress: undefined, }) const session = createSnapshotStore(sessionSnapshot(SID)) @@ -705,7 +705,7 @@ describe('DetailsPanel Output section', () => { useSessions={bindSnapshotSelector(createSnapshotStore( { ids: [], byId: {}, current: undefined, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined, + subagentsByParent: {}, currentAddress: undefined, }))} useSessionPendingInteraction={bindSnapshotSelector(attention)} useWorkspaces={bindSnapshotSelector(workspaces)} diff --git a/packages/client/ui-tool/tests/web-card.client.spec.tsx b/packages/client/ui-tool/tests/web-card.client.spec.tsx index f510ae050f..70a7ea5f8b 100644 --- a/packages/client/ui-tool/tests/web-card.client.spec.tsx +++ b/packages/client/ui-tool/tests/web-card.client.spec.tsx @@ -222,7 +222,7 @@ describe('DetailsPanel web Output section', () => { if (selection !== null) chat.actions.select(selection) const sessions = createSnapshotStore({ ids: [], byId: {}, current: undefined, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined, + subagentsByParent: {}, currentAddress: undefined, }) const session = createSnapshotStore(sessionSnapshot(SID)) const conversation = createSnapshotStore(conversationSnapshot()) diff --git a/packages/client/ui-trajectory/tests/views.client.spec.tsx b/packages/client/ui-trajectory/tests/views.client.spec.tsx index fba1a7b77e..0626f7dc0e 100644 --- a/packages/client/ui-trajectory/tests/views.client.spec.tsx +++ b/packages/client/ui-trajectory/tests/views.client.spec.tsx @@ -167,7 +167,7 @@ function standaloneDuration(): Pick< /** Empty sessions-list hook; breadcrumbs therefore fall back to the raw id. */ function emptySessions() { const store = createSnapshotStore( - { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined }) + { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined }) return bindSnapshotSelector(store) } diff --git a/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx b/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx index 35575aeb4d..4bb2181469 100644 --- a/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx +++ b/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx @@ -48,7 +48,7 @@ const sessionList = { current: SID, phase: 'ready' as const, subagentsByParent: {}, - jobsBySession: {}, + currentAddress: undefined, } const attentionState: AttentionState = new Map() diff --git a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx index e44f492b10..97cd206508 100644 --- a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx +++ b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx @@ -47,7 +47,7 @@ const sessionList = { current: SID, phase: 'ready' as const, subagentsByParent: {}, - jobsBySession: {}, + currentAddress: undefined, } const attentionState: AttentionState = new Map() diff --git a/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx b/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx index 772c90a571..4e01c5c61c 100644 --- a/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx +++ b/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx @@ -299,7 +299,7 @@ const listState = (overrides: Partial = {}): SessionListState current: PARENT_ID, phase: 'ready', subagentsByParent: {}, - jobsBySession: {}, + currentAddress: undefined, ...overrides, }) diff --git a/packages/client/ui-workspace/tests/apply.client.spec.ts b/packages/client/ui-workspace/tests/apply.client.spec.ts index be05aae9df..660396aace 100644 --- a/packages/client/ui-workspace/tests/apply.client.spec.ts +++ b/packages/client/ui-workspace/tests/apply.client.spec.ts @@ -47,7 +47,7 @@ async function bench() { list: { getSnapshot: () => ({ ids: [], byId: {}, current: undefined, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined, + subagentsByParent: {}, currentAddress: undefined, }), subscribe, }, diff --git a/packages/client/ui-workspace/tests/tree.client.spec.ts b/packages/client/ui-workspace/tests/tree.client.spec.ts index 1451b1450d..1f7dcf2a47 100644 --- a/packages/client/ui-workspace/tests/tree.client.spec.ts +++ b/packages/client/ui-workspace/tests/tree.client.spec.ts @@ -20,7 +20,7 @@ const list = (...items: SessionSummary[]): SessionListState => ({ ids: items.map(item => item.id), byId: Object.fromEntries(items.map(item => [item.id, item])), current: undefined, - phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined, + phase: 'ready', subagentsByParent: {}, currentAddress: undefined, }) const workspace = (id: string, sessionIds: string[], title = id): WorkspaceView => ({ workspaceId: wid(id), path: `/projects/${id}`, title, diff --git a/packages/client/ui-workspace/tests/workspace-browser.client.spec.tsx b/packages/client/ui-workspace/tests/workspace-browser.client.spec.tsx index 8ee31d37c9..0349223796 100644 --- a/packages/client/ui-workspace/tests/workspace-browser.client.spec.tsx +++ b/packages/client/ui-workspace/tests/workspace-browser.client.spec.tsx @@ -32,7 +32,7 @@ const sessionState = (items: readonly SessionSummary[], overrides: Partial [item.id, item])), current: undefined, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, + subagentsByParent: {}, currentAddress: undefined, ...overrides, }) diff --git a/packages/client/ui-workspace/tests/workspace-picker.client.spec.tsx b/packages/client/ui-workspace/tests/workspace-picker.client.spec.tsx index 1c76b8b25f..746c6b3259 100644 --- a/packages/client/ui-workspace/tests/workspace-picker.client.spec.tsx +++ b/packages/client/ui-workspace/tests/workspace-picker.client.spec.tsx @@ -30,7 +30,7 @@ function hook(snapshot: T) { return function select(selector: (state: T) => S): S { return selector(snapshot) } } const sessions: SessionListState = { - ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined, + ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, currentAddress: undefined, } const noPendingInteraction: SessionPendingInteractionSnapshot = new Map() const workspaceState = (items: readonly WorkspaceView[]): WorkspaceSnapshot => ({ diff --git a/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts b/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts index 393619bbb7..7d746b7fa1 100644 --- a/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts +++ b/packages/client/ui-workspace/tests/workspaces-service.client.spec.ts @@ -56,7 +56,7 @@ function sessionState( current, phase, subagentsByParent: {}, - jobsBySession: {}, + currentAddress: undefined, } } diff --git a/packages/test-support/client-runtime/src/sessions.ts b/packages/test-support/client-runtime/src/sessions.ts index 419e155af7..32db7c5eac 100644 --- a/packages/test-support/client-runtime/src/sessions.ts +++ b/packages/test-support/client-runtime/src/sessions.ts @@ -216,7 +216,7 @@ export class TestSessions implements ISessions { constructor(private readonly stabilize: Stabilizer, private readonly rootCtx: Context) { this.list = createSnapshotStore({ ids: [], byId: {}, current: undefined, phase: 'ready', - subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined, + subagentsByParent: {}, currentAddress: undefined, }) } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b01a46c7f0..51447df391 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -836,9 +836,6 @@ importers: '@deepseek-ai/dsh-file-reference': specifier: workspace:^ version: link:../../context/file-reference - '@deepseek-ai/dsh-jobs': - specifier: workspace:^ - version: link:../../jobs/jobs '@deepseek-ai/dsh-llm': specifier: workspace:^ version: link:../../llm/llm From b7ce934b29c4aa9e5d5ac8c9e1b2f176008374b2 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 17:00:49 +0800 Subject: [PATCH 035/100] refactor(job-controller): own the roster stream and the browser jobs service - job.rows({ sessionId }) streams the jobs one session can see as whole-set frames: once on open, then after each coalesced burst of lifecycle commits; output appends never refresh it - job.observe reads through visibleTo(sessionId) and carries JobView in its opened and status frames; the wire chunk is the registry's JobChunk - the client installs ctx.jobs (ClientJobs over ClientJobsModel): watchRows and observe are reference-counted streams, rows drop with the last watcher or a terminal failure, observations keep their render tail - the controller no longer needs the agent registry --- packages/api/job-controller/README.i18n.yaml | 4 +- packages/api/job-controller/README.md | 18 +- packages/api/job-controller/README.zh.md | 18 +- .../api/job-controller/src/client/index.ts | 36 +- .../api/job-controller/src/client/model.ts | 86 +++-- .../api/job-controller/src/client/service.ts | 172 ++++++--- packages/api/job-controller/src/index.ts | 47 ++- packages/api/job-controller/src/observe.ts | 128 ++----- packages/api/job-controller/src/rows.ts | 54 +++ packages/api/job-controller/src/types.ts | 63 ++-- packages/api/job-controller/src/wake.ts | 60 +++ .../tests/client-apply.client.spec.ts | 28 +- .../api/job-controller/tests/host-harness.ts | 92 +++++ .../job-controller/tests/model.client.spec.ts | 344 ++++++++++++------ .../job-controller/tests/observe.host.spec.ts | 224 +++++------- .../job-controller/tests/rows.host.spec.ts | 89 +++++ .../api/job-controller/tsconfig.host.json | 5 +- 17 files changed, 937 insertions(+), 531 deletions(-) create mode 100644 packages/api/job-controller/src/rows.ts create mode 100644 packages/api/job-controller/src/wake.ts create mode 100644 packages/api/job-controller/tests/host-harness.ts create mode 100644 packages/api/job-controller/tests/rows.host.spec.ts diff --git a/packages/api/job-controller/README.i18n.yaml b/packages/api/job-controller/README.i18n.yaml index 49a565d20f..8ad9d12dc8 100644 --- a/packages/api/job-controller/README.i18n.yaml +++ b/packages/api/job-controller/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/api/job-controller/README.md -README.md: 6aaab1bff1f13cc21672a039170f811b570230db -README.zh.md: 47e68802346fbc5e41e74171a42afa17289ee156 +README.md: b21327eeea33d84d9218f6869fbe9f9b3d8c6052 +README.zh.md: 32e67646d10f49e2626f0dc2a094e1eb303cc211 diff --git a/packages/api/job-controller/README.md b/packages/api/job-controller/README.md index 6aaab1bff1..b21327eeea 100644 --- a/packages/api/job-controller/README.md +++ b/packages/api/job-controller/README.md @@ -1,5 +1,5 @@ --- -description: "Host and Client job observation: stream one background job's output record to the browser without touching the model's consuming cursor." +description: "Host and Client job streams: the roster one session can see and one job's retained output, mirrored to the browser without touching the model's consuming cursor." kind: "package-reference" --- # Job Controller @@ -8,7 +8,7 @@ English | [中文](README.zh.md) ## Summary -`@deepseek-ai/dsh-api-job-controller` owns the Host `ctx.jobController` service and the generated Client `ctx.remote.job` namespace. Its one Remote stream, `job.observe`, delivers a record-declaring job's retained output from an absolute byte offset; the Client half installs `ctx.jobOutput`, the reference-counted per-job observation service whose accumulated views the session-header job list renders. The roster itself is not here: `SessionJob` rows still ride the session control stream owned by [`dsh-api-session-controller`](../session-controller/README.md), and a row's `record` says whether this controller has anything to stream for it. +`@deepseek-ai/dsh-api-job-controller` owns the Host `ctx.jobController` service and the generated Client `ctx.remote.job` namespace. Its two Remote streams are projections of `ctx.jobs`: `job.rows` mirrors the jobs one session can see as whole-set frames, and `job.observe` delivers one job's retained output from an absolute byte offset. The Client half installs `ctx.jobs`, the reference-counted service whose rosters and accumulated views the session-header job list renders. Neither stream touches the model's consuming cursor or the completion-notice ledger. ## Table of Contents @@ -22,15 +22,15 @@ English | [中文](README.zh.md) ## Use this package -The Host controller requires the live Agent registry and the job registry (`dsh-jobs-local` in the shipped compositions) and fails to load without them. `job.observe({ sessionId?, jobId, from? })` resolves the fenced-read caller from the request's session — an unowned job needs no session — and yields one `opened` anchor, coalesced `output` frames, then one terminal `status` once the job has settled and its record is drained, after which the stream closes normally. Record reads are non-consuming: the model-facing `job_output` cursor and completion-notice state never observe them. A job the session does not own, a job without a record, or an unknown job rejects the stream. Reconnecting callers resume by passing the last frame's `next` as `from`; a `from` below the oldest retained byte gets a `lossy` first frame instead of an error. +The Host controller requires the job registry (`dsh-jobs-local` in the shipped compositions) and fails to load without it. `job.rows({ sessionId })` yields the session's visible set — its own jobs plus every unowned job — once on open and again after each coalesced burst of lifecycle commits (registration, progress, stopping, settlement, removal); output appends never refresh the roster, since a settled projection already carries the final byte count. `job.observe({ sessionId?, jobId, from? })` reads through `visibleTo(sessionId)` — an unowned job needs no session — and yields one `opened` anchor carrying the job projection, coalesced `output` frames, then one terminal `status` once the job has settled and its ring is drained, after which the stream closes normally. Both reads are non-consuming: the model's `job_output` cursor and notice state never observe them. -The Client entry provides `ClientJobOutput` (`ctx.jobOutput`) over `ClientJobOutputModel`. `observe(sessionId, jobId)` opens one Gateway stream per job however many viewers expand it, keeps a bounded render tail per job with `gapBefore` marking eviction or resume gaps, records the terminal status or a stream failure on the view, and drops the view after the last viewer releases. The plugin resolves the Gateway stream factory and the `job` namespace while its own context is current, because observation (re)opens run on caller stacks that have not declared `remote.job`. +The Client entry provides `ClientJobs` (`ctx.jobs`) over `ClientJobsModel`. `watchRows(sessionId)` keeps one roster stream open per watched session however many viewers hold it and drops the rows after the last release; a reconnect's first frame is already the whole truth. `observe(sessionId, jobId)` opens one Gateway stream per job however many viewers expand it, keeps a bounded render tail per job with `gapBefore` marking eviction or resume gaps, closes the view on the terminal frame or records a stream failure on it, and drops the view after the last viewer releases. The plugin resolves the Gateway stream factory and the `job` namespace while its own context is current, because stream (re)opens run on caller stacks whose dynamic context has not declared `remote.job`. ### Config | Field | Default | Meaning | |---|---:|---| -| `observeFlushMs` | `100` | Coalescing window after new record output before an observation read, in milliseconds | +| `observeFlushMs` | `100` | Coalescing window after a registry commit before the next rows or output read, in milliseconds | | `observeMaxFrameBytes` | `65,536` | Soft byte budget per observation output frame; one larger chunk ships whole | The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-api-job-controller) is the exhaustive source for accepted fields and their JSDoc. @@ -50,9 +50,9 @@ No direct effect; observation reads never touch model requests. -- The record is a best-effort live preview, not a terminal transcript: producers copy stdout and stderr per poll round, so the two streams' writes inside one poll window reach the record stdout first, and the client concatenates chunks regardless of `channel`. -- The stream is process-local: a Host restart loses every record, and a resumed observation then anchors on an empty registry. -- Per-session fencing is enforced by the registry read; the Remote layer itself serves any connected browser, matching the session control stream's `jobsBySession` broadcast. +- The ring is a best-effort live preview, not a terminal transcript: producers' pull sources are copied per poll round, so two streams' writes inside one poll window land stdout first, and the client concatenates chunks regardless of `channel`. +- Both streams are process-local: a Host restart loses every ring and roster; a resumed observation then anchors on an empty registry, and a re-opened roster starts empty. +- Per-session fencing is enforced by the registry's `visibleTo` read; the Remote layer itself serves any connected browser. ### Dev Note @@ -64,4 +64,4 @@ None. -**Runtime invariant:** No companion is published. The controller is a stateless projection of `ctx.jobs` reads; the registry's own `@deepseek-ai/dsh-jobs/invariant` owns the offset relations this stream forwards. +**Runtime invariant:** No companion is published. The controller is a stateless projection of `ctx.jobs` reads; the registry's own `@deepseek-ai/dsh-jobs/invariant` owns the offset relations these streams forward. diff --git a/packages/api/job-controller/README.zh.md b/packages/api/job-controller/README.zh.md index 47e6880234..32e67646d1 100644 --- a/packages/api/job-controller/README.zh.md +++ b/packages/api/job-controller/README.zh.md @@ -1,5 +1,5 @@ --- -description: "Host 与 Client 的 job 观测:把一个后台任务的输出 record 流式送到浏览器,不触碰模型的消耗型游标。" +description: "Host 与 Client 的 job 流:把一个会话看得到的名册与一个 job 的保留输出镜像到浏览器,不触碰模型的消耗型游标。" kind: "package-reference" --- # Job Controller @@ -8,7 +8,7 @@ kind: "package-reference" ## 概述 -`@deepseek-ai/dsh-api-job-controller` 拥有 Host 的 `ctx.jobController` 服务与生成的 Client `ctx.remote.job` namespace。它唯一的 Remote 流 `job.observe` 从绝对字节偏移发送声明了 record 的 job 的保留输出;Client 半侧安装 `ctx.jobOutput`——按 job 引用计数的观测服务,会话头部任务列表渲染其累积视图。名册不在这里:`SessionJob` 行仍随 [`dsh-api-session-controller`](../session-controller/README.zh.md) 拥有的会话控制流到达,行上的 `record` 说明本控制器是否有东西可流。 +`@deepseek-ai/dsh-api-job-controller` 拥有 Host 的 `ctx.jobController` 服务与生成的 Client `ctx.remote.job` namespace。它的两条 Remote 流都是 `ctx.jobs` 的投影:`job.rows` 以整集帧镜像一个会话看得到的 job;`job.observe` 从绝对字节偏移发送一个 job 的保留输出。Client 半侧安装 `ctx.jobs`——按引用计数的服务,会话头部任务列表渲染其名册与累积视图。两条流都不触碰模型的消耗型游标与完成播报台账。 ## 目录 @@ -22,15 +22,15 @@ kind: "package-reference" ## 使用本包 -Host 控制器要求活体 Agent 注册表与 job 注册表(已发布组合里是 `dsh-jobs-local`),缺少任一则不加载。`job.observe({ sessionId?, jobId, from? })` 由请求的 session 解析围栏读取者——无主 job 不需要 session——先产出一个 `opened` 锚帧,再是聚合的 `output` 帧,job 结算且 record 排干后产出一个终态 `status`,随后流正常关闭。record 读取是非消耗的:模型侧 `job_output` 游标与完成播报状态永远观察不到它们。session 不拥有的 job、没有 record 的 job 或未知 job 会拒绝该流。重连方把上一帧的 `next` 作为 `from` 续读;低于最老保留字节的 `from` 得到带 `lossy` 的首帧而非错误。 +Host 控制器要求 job 注册表(已发布组合里是 `dsh-jobs-local`),缺少则不加载。`job.rows({ sessionId })` 产出该会话可见的集合——自己的 job 加上所有无主 job——打开时一次,之后每一轮聚合过的生命周期提交(注册、进度、停止中、结算、移除)后再一次;输出追加从不刷新名册,因为结算后的投影已经带着最终字节数。`job.observe({ sessionId?, jobId, from? })` 经 `visibleTo(sessionId)` 读取——无主 job 不需要 session——先产出一个携带 job 投影的 `opened` 锚帧,再是聚合的 `output` 帧,job 结算且环排干后产出一个终态 `status`,随后流正常关闭。两种读取都是非消耗的:模型侧 `job_output` 游标与完成播报状态永远观察不到它们。 -Client 入口在 `ClientJobOutputModel` 之上提供 `ClientJobOutput`(`ctx.jobOutput`)。`observe(sessionId, jobId)` 不论多少查看器展开同一 job 都只开一条 Gateway 流,按 job 保留有界的渲染尾部并用 `gapBefore` 标记淘汰或续读缺口,把终态或流失败记到视图上,最后一个查看器释放后丢弃视图。插件在自己的上下文仍是当前上下文时解析 Gateway 流工厂与 `job` namespace,因为观测的(重)开启跑在未声明 `remote.job` 的调用栈上。 +Client 入口在 `ClientJobsModel` 之上提供 `ClientJobs`(`ctx.jobs`)。`watchRows(sessionId)` 不论多少查看器持有都只为每个被关注的会话开一条名册流,最后一个释放后丢弃行;重连后的首帧已经是完整事实。`observe(sessionId, jobId)` 不论多少查看器展开同一 job 都只开一条 Gateway 流,按 job 保留有界的渲染尾部并用 `gapBefore` 标记淘汰或续读缺口,在终态帧上关闭视图或把流失败记到视图上,最后一个查看器释放后丢弃视图。插件在自己的上下文仍是当前上下文时解析 Gateway 流工厂与 `job` namespace,因为流的(重)开启跑在未声明 `remote.job` 的调用栈上。 ### 配置 | 字段 | 默认值 | 含义 | |---|---:|---| -| `observeFlushMs` | `100` | 新 record 输出到一次观测读取之间的聚合窗口,毫秒 | +| `observeFlushMs` | `100` | 注册表提交到下一次名册或输出读取之间的聚合窗口,毫秒 | | `observeMaxFrameBytes` | `65,536` | 每个观测输出帧的软字节预算;更大的单块整块发送 | 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-api-job-controller)是所有受支持字段及其 JSDoc 的完整来源。 @@ -50,9 +50,9 @@ Client 入口在 `ClientJobOutputModel` 之上提供 `ClientJobOutput`(`ctx.jo -- record 是尽力而为的实时预览,不是终端转录:生产者按轮询轮次复制 stdout 与 stderr,同一轮询窗口内两条流的写入先 stdout 后到达 record,客户端拼接 chunk 时也不区分 `channel`。 -- 流是进程本地的:Host 重启丢失全部 record,续读的观测随后锚定在空注册表上。 -- 按 session 的围栏由注册表读取强制;Remote 层本身服务任何已连接浏览器,与会话控制流对 `jobsBySession` 的广播一致。 +- 环是尽力而为的实时预览,不是终端转录:生产者的拉取源按轮询轮次复制,同一轮询窗口内两条流的写入先 stdout 落地,客户端拼接 chunk 时也不区分 `channel`。 +- 两条流都是进程本地的:Host 重启丢失全部环与名册,续读的观测随后锚定在空注册表上,重开的名册从空开始。 +- 按 session 的围栏由注册表的 `visibleTo` 读取强制;Remote 层本身服务任何已连接浏览器。 ### 开发备注 @@ -64,4 +64,4 @@ Client 入口在 `ClientJobOutputModel` 之上提供 `ClientJobOutput`(`ctx.jo -**运行时不变式:** 不发布伴生入口。控制器是 `ctx.jobs` 读取的无状态投影;本流转发的偏移关系由注册表自己的 `@deepseek-ai/dsh-jobs/invariant` 拥有。 +**运行时不变式:** 不发布伴生入口。控制器是 `ctx.jobs` 读取的无状态投影;这些流转发的偏移关系由注册表自己的 `@deepseek-ai/dsh-jobs/invariant` 拥有。 diff --git a/packages/api/job-controller/src/client/index.ts b/packages/api/job-controller/src/client/index.ts index a76d507332..61c59ce52b 100644 --- a/packages/api/job-controller/src/client/index.ts +++ b/packages/api/job-controller/src/client/index.ts @@ -1,34 +1,36 @@ /** - * Job Controller client half: installs `ctx.jobOutput` over the generated - * `job` Remote namespace. The plugin resolves both Remote faces it drives - * while its own context is current, because observation (re)opens run on - * caller stacks — a React event, a carrier retry — whose dynamic context has - * not declared `remote.job`. + * Job Controller client half: installs `ctx.jobs` over the generated `job` + * Remote namespace. The plugin resolves both Remote faces it drives while its + * own context is current, because stream (re)opens run on caller stacks — a + * React event, a carrier retry — whose dynamic context has not declared + * `remote.job`. * @module @deepseek-ai/dsh-api-job-controller/client */ import type { Context } from '@deepseek-ai/cordis' -import { ClientJobOutputModel } from './model.ts' -import { ClientJobOutput } from './service.ts' -import type { JobObserveRemote } from './service.ts' +import { ClientJobsModel } from './model.ts' +import { ClientJobs } from './service.ts' +import type { JobsRemote } from './service.ts' -export { ClientJobOutputModel } from './model.ts' -export type { JobOutputSnapshot, JobOutputSource, ObservedJob } from './model.ts' -export { ClientJobOutput } from './service.ts' -export type { IJobOutput, JobObserveRemote, JobRemote } from './service.ts' -export type { JobObserveFrame, JobObserveRequest, JobObserveStatus, JobWireChunk } from '../types.ts' +export { ClientJobsModel } from './model.ts' +export type { JobsSnapshot, JobsSource, ObservedJob } from './model.ts' +export { ClientJobs } from './service.ts' +export type { IJobs, JobRemote, JobsRemote } from './service.ts' +export type { + JobChunk, JobObserveFrame, JobObserveRequest, JobRowsFrame, JobRowsRequest, JobView, +} from '../types.ts' /** Required Client Remote services. */ export const inject = ['remote', 'remote.job'] /** - * Install the client job-output service. + * Install the client jobs service. * @param ctx - Client root Context. */ export function apply(ctx: Context): void { - const remotes = ctx.remote as unknown as JobObserveRemote - new ClientJobOutput(ctx, { + const remotes = ctx.remote as unknown as JobsRemote + new ClientJobs(ctx, { $stream: options => remotes.$stream(options), job: remotes.job, - }, new ClientJobOutputModel()) + }, new ClientJobsModel()) } diff --git a/packages/api/job-controller/src/client/model.ts b/packages/api/job-controller/src/client/model.ts index 1c44aa039a..2b58208bb0 100644 --- a/packages/api/job-controller/src/client/model.ts +++ b/packages/api/job-controller/src/client/model.ts @@ -1,13 +1,15 @@ /** - * React-free client job-record observation state: per-job accumulated output - * views fed by `job.observe` frames. Pure data plus subscriptions — transport - * wiring stays in the client service, UI stays in slot components. + * React-free client job state: the roster each watched session can see, fed + * by `job.rows` frames, and per-job accumulated output views fed by + * `job.observe` frames. Pure data plus subscriptions — transport wiring stays + * in the client service, UI stays in slot components. * @module @deepseek-ai/dsh-api-job-controller/client/model */ import { notifySubscribers } from '@deepseek-ai/dsh-client-store' import type { JobId } from '@deepseek-ai/dsh-jobs/brand' -import type { JobObserveFrame, JobObserveStatus } from '../types.ts' +import type { SessionId } from '@deepseek-ai/dsh-session/types' +import type { JobObserveFrame, JobView } from '../types.ts' /** Bounded per-job render tail, in UTF-16 code units. */ const RENDER_TAIL_LIMIT = 128 * 1024 @@ -19,25 +21,28 @@ export interface ObservedJob { readonly text: string /** True when bytes before {@link text} were dropped (eviction, resume gap, or the render bound). */ readonly gapBefore: boolean - /** Latest status delivered on the observation stream. */ - readonly status: JobObserveStatus - readonly detail?: string /** True while the observation stream is open and the job has not settled. */ readonly streaming: boolean /** Terminal observation failure, when the stream ended abnormally. */ readonly error?: string } -/** Immutable client job-output state. */ -export interface JobOutputSnapshot { +/** Immutable client job state. */ +export interface JobsSnapshot { + /** + * The jobs each watched session can see, keyed by session id. A session + * nobody watches, or one that sees no job, has no key, so consumers read + * absence rather than a sentinel. + */ + readonly rows: Readonly> /** Live observation state keyed by job id. */ readonly observed: Readonly> } -/** Bare observable source for the client job-output snapshot. */ -export interface JobOutputSource { +/** Bare observable source for the client job snapshot. */ +export interface JobsSource { /** Read the identity-stable current snapshot. */ - getSnapshot(): JobOutputSnapshot + getSnapshot(): JobsSnapshot /** * Subscribe to snapshot changes. * @param listener - invalidation callback. @@ -53,18 +58,21 @@ interface ObservedState { cursor: number | undefined } -/** Owns per-job observation state. */ -export class ClientJobOutputModel implements JobOutputSource { +/** Owns the per-session rosters and per-job observation state. */ +export class ClientJobsModel implements JobsSource { + private readonly rowsBySession = new Map() private readonly observedStates = new Map() private readonly listeners = new Set<() => void>() - private snapshotCache: JobOutputSnapshot = { observed: {} } + private snapshotCache: JobsSnapshot = { rows: {}, observed: {} } private snapshotDirty = false - getSnapshot(): JobOutputSnapshot { + getSnapshot(): JobsSnapshot { if (this.snapshotDirty) { + const rows: Record = {} + for (const [id, jobs] of this.rowsBySession) rows[id] = jobs const observed: Record = {} for (const [id, state] of this.observedStates) observed[id] = state.view - this.snapshotCache = { observed } + this.snapshotCache = { rows, observed } this.snapshotDirty = false } return this.snapshotCache @@ -75,6 +83,31 @@ export class ClientJobOutputModel implements JobOutputSource { return () => { this.listeners.delete(listener) } } + /** + * Replace one session's roster with a `rows` frame's whole set. An empty + * set is stored as an absent key. + * @param sessionId - the watched session. + * @param jobs - the complete visible set. + */ + rowsReplaced(sessionId: SessionId, jobs: readonly JobView[]): void { + const key = String(sessionId) + if (jobs.length === 0) { + if (!this.rowsBySession.delete(key)) return + } else { + this.rowsBySession.set(key, jobs) + } + this.changed() + } + + /** + * Drop one session's roster after its last watcher stops or its stream fails. + * @param sessionId - the no-longer-watched session. + */ + rowsDropped(sessionId: SessionId): void { + if (!this.rowsBySession.delete(String(sessionId))) return + this.changed() + } + /** * The resume offset for one job's next observation generation. * @param id - observed job. @@ -99,9 +132,7 @@ export class ClientJobOutputModel implements JobOutputSource { const view: ObservedJob = { jobId: id, text: existing?.view.text ?? '', - gapBefore: (existing?.view.gapBefore ?? false) || frame.from < frame.earliest || freshPastHead, - status: frame.status, - ...frame.detail !== undefined ? { detail: frame.detail } : {}, + gapBefore: (existing?.view.gapBefore ?? false) || frame.from < frame.job.output.earliest || freshPastHead, streaming: true, } this.observedStates.set(String(id), { view, cursor: frame.from }) @@ -134,20 +165,15 @@ export class ClientJobOutputModel implements JobOutputSource { } /** - * Record the terminal status delivered at the end of the observation stream. + * Close the live view once the terminal `status` frame arrived: the ring is + * drained and the roster row carries the settled projection. * @param id - observed job. - * @param frame - the terminal `status` frame. */ - observeStatus(id: JobId, frame: Extract): void { + observeSettled(id: JobId): void { const state = this.observedStates.get(String(id)) /* v8 ignore next -- frames arrive only between opened and stop for a tracked id. */ if (state === undefined) return - state.view = { - ...state.view, - status: frame.status, - ...frame.detail !== undefined ? { detail: frame.detail } : {}, - streaming: false, - } + state.view = { ...state.view, streaming: false } this.changed() } @@ -174,6 +200,6 @@ export class ClientJobOutputModel implements JobOutputSource { private changed(): void { this.snapshotDirty = true - notifySubscribers(this.listeners, 'job output') + notifySubscribers(this.listeners, 'jobs') } } diff --git a/packages/api/job-controller/src/client/service.ts b/packages/api/job-controller/src/client/service.ts index 07f3a00ec2..b339871180 100644 --- a/packages/api/job-controller/src/client/service.ts +++ b/packages/api/job-controller/src/client/service.ts @@ -1,7 +1,9 @@ /** - * The `ctx.jobOutput` client service: reference-counted per-job observation - * streams over `job.observe`, so overlapping viewers of one job share one - * stream and resume from the model's cursor across reconnects. + * The `ctx.jobs` client service: reference-counted streams over the `job` + * namespace — one `job.rows` roster stream per watched session and one + * `job.observe` stream per observed job — so overlapping viewers share a + * stream, rosters resume whole after a reconnect, and observations resume + * from the model's cursor. * @module @deepseek-ai/dsh-api-job-controller/client/service */ @@ -9,11 +11,18 @@ import { Service, type Context } from '@deepseek-ai/cordis' import { RemoteStreamCarrierError, type ClientRemote } from '@deepseek-ai/dsh-api-gateway/client' import type { JobId } from '@deepseek-ai/dsh-jobs/brand' import type { SessionId } from '@deepseek-ai/dsh-session/types' -import type { JobObserveFrame, JobObserveRequest } from '../types.ts' -import type { ClientJobOutputModel, JobOutputSource } from './model.ts' +import type { JobObserveFrame, JobObserveRequest, JobRowsFrame, JobRowsRequest } from '../types.ts' +import type { ClientJobsModel, JobsSource } from './model.ts' -/** The generated `job` namespace face the observation runner drives. */ +/** The generated `job` namespace face the stream runners drive. */ export interface JobRemote { + /** + * Open one roster generation. + * @param request - the session whose visible set to mirror. + * @param signal - generation cancellation. + * @returns the whole-set frame sequence of one generation. + */ + rows(request: JobRowsRequest, signal?: AbortSignal): AsyncIterable /** * Open one observation generation. * @param request - target job, owning session, and optional resume offset. @@ -23,18 +32,25 @@ export interface JobRemote { observe(request: JobObserveRequest, signal?: AbortSignal): AsyncIterable } -/** Remote faces the observation runner drives: the Gateway stream factory and the `job` namespace. */ -export interface JobObserveRemote { +/** Remote faces the runners drive: the Gateway stream factory and the `job` namespace. */ +export interface JobsRemote { readonly $stream: ClientRemote['$stream'] readonly job: JobRemote } -/** The job-output client service face. */ -export interface IJobOutput { - /** Per-job observation state. */ - readonly state: JobOutputSource +/** The client jobs service face. */ +export interface IJobs { + /** Rosters and per-job observation state. */ + readonly state: JobsSource /** - * Start observing one job's live record; reference-counted, so two viewers + * Keep one session's roster current; reference-counted, so two watchers of + * the same session share one stream and the rows leave with the last. + * @param sessionId - the session whose visible jobs to mirror. + * @returns stop function releasing this watcher's reference. + */ + watchRows(sessionId: SessionId): () => void + /** + * Start observing one job's live output; reference-counted, so two viewers * of the same job share one stream. * @param sessionId - owning session used for the fenced read; undefined for an unowned job. * @param id - job to observe. @@ -43,8 +59,8 @@ export interface IJobOutput { observe(sessionId: SessionId | undefined, id: JobId): () => void } -/** One reference-counted observation stream. */ -interface ObservationEntry { +/** One reference-counted stream. */ +interface StreamEntry { refs: number stopped: boolean dispose: () => Promise @@ -52,79 +68,139 @@ interface ObservationEntry { declare module '@deepseek-ai/cordis' { interface Context { - /** React-free client job-record observation control. */ - jobOutput: IJobOutput + /** React-free client job rosters and observation control. */ + jobs: IJobs } } -/** Owns the bare job-output snapshot and per-job observation streams. */ -export class ClientJobOutput extends Service implements IJobOutput { - readonly state: JobOutputSource - private readonly entries = new Map() +/** Owns the bare jobs snapshot and the per-session and per-job streams. */ +export class ClientJobs extends Service implements IJobs { + readonly state: JobsSource + private readonly rowsEntries = new Map() + private readonly observations = new Map() /** * @param ctx - client root Context. * @param remote - the Gateway stream factory plus the generated `job` namespace, both resolved by the caller. - * @param model - shared client job-output model. + * @param model - shared client jobs model. */ constructor( ctx: Context, - private readonly remote: JobObserveRemote, - private readonly model: ClientJobOutputModel, + private readonly remote: JobsRemote, + private readonly model: ClientJobsModel, ) { - super(ctx, 'jobOutput') + super(ctx, 'jobs') this.state = model ctx.effect(() => async () => { - const open = [...this.entries.values()] - this.entries.clear() + const open = [...this.rowsEntries.values(), ...this.observations.values()] + this.rowsEntries.clear() + this.observations.clear() for (const entry of open) entry.stopped = true // Cordis awaits an async disposer, so the fiber stays unloading until // every carrier iterator has closed and a successor plugin instance // cannot overlap one. A carrier whose teardown fails is stopped all the // same; its failure has no consumer here. await Promise.allSettled(open.map(entry => entry.dispose())) - }, 'job-controller.client.observations') + }, 'job-controller.client.streams') + } + + watchRows(sessionId: SessionId): () => void { + return this.acquire( + this.rowsEntries, + String(sessionId), + () => this.startRows(sessionId), + () => { this.model.rowsDropped(sessionId) }, + ) } observe(sessionId: SessionId | undefined, id: JobId): () => void { - const key = String(id) - const existing = this.entries.get(key) + return this.acquire( + this.observations, + String(id), + () => this.startObservation(sessionId, id), + () => { this.model.observeStopped(id) }, + ) + } + + /** Share the live entry under `key` or start one, and hand back its release. */ + private acquire( + entries: Map, + key: string, + start: () => StreamEntry, + cleared: () => void, + ): () => void { + const existing = entries.get(key) if (existing !== undefined && !existing.stopped) { existing.refs += 1 - return this.releaser(key, existing) + return this.releaser(entries, key, existing, cleared) } - const entry = this.startObservation(sessionId, id) - this.entries.set(key, entry) - return this.releaser(key, entry) + const entry = start() + entries.set(key, entry) + return this.releaser(entries, key, entry, cleared) } /** * Release closures bind the exact entry they were minted for, never the - * map's current occupant: a later `observe()` on the same id may have - * replaced a stopped entry, and decrementing or disposing through the key - * alone would tear down that newer stream's references. + * map's current occupant: a later acquire on the same key may have replaced + * a stopped entry, and decrementing or disposing through the key alone + * would tear down that newer stream's references. */ - private releaser(key: string, entry: ObservationEntry): () => void { + private releaser(entries: Map, key: string, entry: StreamEntry, cleared: () => void): () => void { let released = false return () => { if (released) return released = true entry.refs -= 1 if (entry.refs > 0) return - if (this.entries.get(key) === entry) this.entries.delete(key) + if (entries.get(key) === entry) entries.delete(key) entry.stopped = true void entry.dispose().then(() => { - // Clear the view only while no successor observation holds the key: - // a re-expand inside the dispose round-trip already re-anchored the - // model, and a stale clear would blank its panel for good. - if (this.entries.has(key)) return - // The key is the stringified branded id this releaser was minted for. - this.model.observeStopped(key as JobId) + // Clear the state only while no successor holds the key: a re-acquire + // inside the dispose round-trip already refilled the model, and a + // stale clear would blank it for good. + if (entries.has(key)) return + cleared() }) } } - private startObservation(sessionId: SessionId | undefined, id: JobId): ObservationEntry { + private startRows(sessionId: SessionId): StreamEntry { + const name = `job rows ${String(sessionId)}` + const stream = this.remote.$stream({ + name, + open: signal => this.remote.job.rows({ sessionId }, signal), + // The roster has no natural end while it is watched: an end after the + // first frame is a carrier interruption (a Host reload closes the + // generation) and the next generation's whole set loses nothing. An end + // before the first frame is terminal. + ended: accepted => accepted + ? new RemoteStreamCarrierError(`${name} ended before release`) + : new Error(`${name} ended before its first frame`), + }) + const entry: StreamEntry = { + refs: 1, + stopped: false, + dispose: () => stream.dispose(), + } + void (async () => { + try { + for await (const item of stream) { + this.model.rowsReplaced(sessionId, item.value.jobs) + item.accept() + } + } catch { + // A terminal stream failure leaves nothing current to show; the model + // drops the roster rather than keeping a stale set on screen. + if (!entry.stopped) this.model.rowsDropped(sessionId) + } finally { + entry.stopped = true + void entry.dispose() + } + })() + return entry + } + + private startObservation(sessionId: SessionId | undefined, id: JobId): StreamEntry { const name = `job observation ${String(id)}` const stream = this.remote.$stream({ name, @@ -146,7 +222,7 @@ export class ClientJobOutput extends Service implements IJobOutput { ? new RemoteStreamCarrierError(`${name} ended before settlement`) : new Error(`${name} ended before its anchor`), }) - const entry: ObservationEntry = { + const entry: StreamEntry = { refs: 1, stopped: false, dispose: () => stream.dispose(), @@ -166,7 +242,7 @@ export class ClientJobOutput extends Service implements IJobOutput { } // Terminal status: leave the loop before the generation end is // classified, then close the stream for good. - this.model.observeStatus(id, frame) + this.model.observeSettled(id) break } } catch (error) { diff --git a/packages/api/job-controller/src/index.ts b/packages/api/job-controller/src/index.ts index 27e85a0ed0..431c7ce1d2 100644 --- a/packages/api/job-controller/src/index.ts +++ b/packages/api/job-controller/src/index.ts @@ -1,18 +1,18 @@ /** - * Host job Remote owner: streams one background job's observation record to - * browsers over the generated `job` namespace. The roster itself rides the - * session control stream (`jobsBySession`, owned by `dsh-api-session-controller`); - * this controller carries only the non-consuming record output. + * Host job Remote owner: streams the background-job roster one session can + * see and one job's retained output to browsers over the generated `job` + * namespace. Both streams are projections of `ctx.jobs`; the model's + * consuming cursor and notice state never observe them. * @module @deepseek-ai/dsh-api-job-controller */ import { Context } from '@deepseek-ai/cordis' import z from '@deepseek-ai/schemastery' -import type {} from '@deepseek-ai/dsh-agent' import type {} from '@deepseek-ai/dsh-jobs' import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol' -import { observeJobRecord } from './observe.ts' -import type { JobObserveFrame, JobObserveRequest } from './types.ts' +import { observeJobOutput } from './observe.ts' +import { streamJobRows } from './rows.ts' +import type { JobObserveFrame, JobObserveRequest, JobRowsFrame, JobRowsRequest } from './types.ts' export type * from './types.ts' @@ -23,7 +23,7 @@ declare module '@deepseek-ai/cordis' { } } -/** Default coalescing window between record reads, in milliseconds. */ +/** Default coalescing window between reads, in milliseconds. */ const DEFAULT_OBSERVE_FLUSH_MS = 100 /** Default soft byte budget per output frame. */ @@ -31,7 +31,7 @@ const DEFAULT_OBSERVE_MAX_FRAME_BYTES = 64 * 1024 /** Job Controller deployment policy. */ export interface Config { - /** Coalescing window after new record output before an observation read, in milliseconds (default 100). */ + /** Coalescing window after a registry commit before the next rows or output read, in milliseconds (default 100). */ readonly observeFlushMs?: number /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */ readonly observeMaxFrameBytes?: number @@ -39,7 +39,7 @@ export interface Config { /** Host service backing the generated `ctx.remote.job` namespace. */ export class JobController extends TypertRemoteService { - static inject = ['agents', 'jobs', 'typert'] + static inject = ['jobs', 'typert'] static Config: z = z.object({ observeFlushMs: z.natural().min(1).default(DEFAULT_OBSERVE_FLUSH_MS), @@ -50,7 +50,7 @@ export class JobController extends TypertRemoteService { private readonly observeMaxFrameBytes: number /** - * @param ctx - Host context carrying the live Agent registry and the job registry. + * @param ctx - Host context carrying the job registry. * @param config - observation cadence and framing policy. */ constructor(ctx: Context, config: Config) { @@ -63,22 +63,33 @@ export class JobController extends TypertRemoteService { } /** - * Stream one job's retained record output from an absolute byte offset, - * then its terminal status once settled and drained. Non-consuming: the + * Stream the jobs one session can see — its own plus every unowned job — + * as whole-set frames: one on open, then one after each coalesced burst of + * lifecycle commits. The stream has no natural end; the carrier closes it. + * @param request - the session whose visible set to mirror. + * @param signal - cancellation owned by the Remote stream carrier. + * @returns the roster frames. + */ + @Remote({ mode: 'stream' }) + rows(request: JobRowsRequest, signal: AbortSignal): AsyncIterable { + return streamJobRows(this.ctx.jobs, request, { flushMs: this.observeFlushMs }, signal) + } + + /** + * Stream one job's retained output from an absolute byte offset, then its + * terminal projection once settled and drained. Non-consuming: the * model-facing cursor and notice state never observe these reads. The - * request's session resolves the fenced-read caller; the registry rejects a - * job the session does not own, a job without a record, or an unknown job. + * request's session is the fenced read's caller; the registry rejects a + * job the session cannot see and an unknown job. * @param request - target job, owning session, and optional resume offset. * @param signal - cancellation owned by the Remote stream carrier. * @returns anchor, coalesced output frames, and the terminal status. */ @Remote({ mode: 'stream' }) observe(request: JobObserveRequest, signal: AbortSignal): AsyncIterable { - const caller = request.sessionId === undefined ? undefined : this.ctx.agents.get(request.sessionId) - return observeJobRecord(this.ctx.jobs, request, { + return observeJobOutput(this.ctx.jobs, request, { flushMs: this.observeFlushMs, maxFrameBytes: this.observeMaxFrameBytes, - caller, }, signal) } } diff --git a/packages/api/job-controller/src/observe.ts b/packages/api/job-controller/src/observe.ts index 731f40b2e2..8590a704f7 100644 --- a/packages/api/job-controller/src/observe.ts +++ b/packages/api/job-controller/src/observe.ts @@ -1,9 +1,9 @@ -/** Per-job record observation generations: anchor, coalesced output, terminal status. */ +/** Per-job observation generations: anchor, coalesced output, terminal status. */ -import type { Agent } from '@deepseek-ai/dsh-agent' import type { JobId } from '@deepseek-ai/dsh-jobs/brand' -import type { JobRegistry, JobSnapshot } from '@deepseek-ai/dsh-jobs' -import type { JobObserveFrame, JobObserveRequest, JobWireChunk } from './types.ts' +import type { JobChunk, JobRegistry, JobStatus } from '@deepseek-ai/dsh-jobs' +import type { JobObserveFrame, JobObserveRequest } from './types.ts' +import { OutputWaiter, sleep } from './wake.ts' /** Cadence and framing bounds for one observation generation. */ export interface ObserveJobOptions { @@ -15,81 +15,28 @@ export interface ObserveJobOptions { * registry's retention cap is the hard bound on any single chunk). */ readonly maxFrameBytes: number - /** The live owning agent for fenced reads, resolved from the request's session. */ - readonly caller: Agent | undefined } -function isTerminal(status: JobSnapshot['status']): boolean { +function isTerminal(status: JobStatus): boolean { return status !== 'running' && status !== 'stopping' } -/** A record job's total offset; the anchor check proved the declaration and it never leaves. */ -function recordTotal(snapshot: JobSnapshot): number { - /* v8 ignore next -- a declared record never loses its offsets. */ - return snapshot.outputTotal ?? 0 -} - -/** Wake-flag waiter: a wake between waits is never lost. */ -class OutputWaiter { - private dirty = false - private resolve: (() => void) | undefined - - wake(): void { - this.dirty = true - this.resolve?.() - } - - /** - * Resolve on the next wake, immediately when one already arrived, or on abort. - * @param signal - generation cancellation. - */ - wait(signal: AbortSignal): Promise { - if (this.dirty || signal.aborted) { - this.dirty = false - return Promise.resolve() - } - return new Promise((resolve) => { - const finish = (): void => { - signal.removeEventListener('abort', finish) - /* v8 ignore next -- one wait owns the sole installed resolver. */ - if (this.resolve === finish) this.resolve = undefined - this.dirty = false - resolve() - } - this.resolve = finish - signal.addEventListener('abort', finish, { once: true }) - }) - } -} - -function sleep(ms: number, signal: AbortSignal): Promise { - if (signal.aborted) return Promise.resolve() - return new Promise((resolve) => { - const timer = setTimeout(done, ms) - function done(): void { - clearTimeout(timer) - signal.removeEventListener('abort', done) - resolve() - } - signal.addEventListener('abort', done, { once: true }) - }) -} - /** - * Stream one job's retained record output from an absolute offset: one - * `opened` anchor, coalesced `output` frames as the record advances, then one - * terminal `status` after the settled job is drained, after which the - * generation closes normally. Reads are non-consuming — the model-facing - * cursor and notice state never observe them; reconnecting callers resume by - * passing the last frame's `next` as `from`. Throws for a job that declared - * no record. + * Stream one job's retained output from an absolute offset: one `opened` + * anchor, coalesced `output` frames as the ring advances, then one terminal + * `status` after the settled job is drained, after which the generation + * closes normally. Reads are non-consuming — the model-facing cursor and + * notice state never observe them; reconnecting callers resume by passing + * the last frame's `next` as `from`. The request's session is the fenced + * read's caller: the registry rejects a job the session cannot see and an + * unknown job. * @param registry - the live job registry. - * @param request - target job and optional resume offset. - * @param options - cadence, framing bounds, and the fenced-read caller. + * @param request - target job, owning session, and optional resume offset. + * @param options - cadence and framing bounds. * @param signal - generation cancellation owned by the Remote stream carrier. * @returns the observation frame sequence for one generation. */ -export async function* observeJobRecord( +export async function* observeJobOutput( registry: JobRegistry, request: JobObserveRequest, options: ObserveJobOptions, @@ -105,41 +52,24 @@ export async function* observeJobRecord( const waiter = new OutputWaiter() // Subscribe before the first read so an append between the anchor read and // the wait cannot be missed. - const unsubscribe = registry.onOutput((changed) => { + const unsubscribe = registry.events.subscribe({ owners: 'all' }, (event) => { + const changed = event.type === 'output' ? event.id : event.job.id if (changed === id) waiter.wake() }) try { - const caller = options.caller - let snapshot = registry.get(id, caller) - if (snapshot.outputTotal === undefined || snapshot.outputEarliest === undefined) { - throw new Error(`job ${id} declared no output record`) - } - let cursor = request.from ?? snapshot.outputEarliest - yield { - type: 'opened', - jobId: id, - from: cursor, - earliest: snapshot.outputEarliest, - total: snapshot.outputTotal, - status: snapshot.status, - ...snapshot.detail !== undefined ? { detail: snapshot.detail } : {}, - } + const visible = registry.visibleTo(request.sessionId) + let job = visible.get(id) + let cursor = request.from ?? job.output.earliest + yield { type: 'opened', job, from: cursor } while (!signal.aborted) { - const read = registry.readRecord(id, cursor, caller) - if (read.chunks.length > 0) { + const read = visible.readAt(id, cursor) + if (read.chunks.length > 0 || read.lossy) { yield* outputFrames(read.chunks, read.next, read.lossy, options.maxFrameBytes) } cursor = read.next - snapshot = registry.get(id, caller) - if (isTerminal(snapshot.status) && cursor >= recordTotal(snapshot)) { - yield { - type: 'status', - status: snapshot.status, - ...snapshot.detail !== undefined ? { detail: snapshot.detail } : {}, - // Settlement always stamps finishedAt; the guard only discharges the optional field type. - /* v8 ignore next */ - ...snapshot.finishedAt !== undefined ? { finishedAt: snapshot.finishedAt } : {}, - } + job = visible.get(id) + if (isTerminal(job.status) && cursor >= job.output.total) { + yield { type: 'status', job } return } await waiter.wait(signal) @@ -153,12 +83,12 @@ export async function* observeJobRecord( /** Split one read into frames along the soft per-frame byte budget. */ function* outputFrames( - chunks: readonly JobWireChunk[], + chunks: readonly JobChunk[], next: number, lossy: boolean, maxFrameBytes: number, ): Iterable { - let batch: JobWireChunk[] = [] + let batch: JobChunk[] = [] let batchBytes = 0 let flaggedLossy = lossy for (const chunk of chunks) { diff --git a/packages/api/job-controller/src/rows.ts b/packages/api/job-controller/src/rows.ts new file mode 100644 index 0000000000..9076f12424 --- /dev/null +++ b/packages/api/job-controller/src/rows.ts @@ -0,0 +1,54 @@ +/** Per-session roster generations: the caller-visible job set, replaced whole after every lifecycle change. */ + +import type { JobRegistry } from '@deepseek-ai/dsh-jobs' +import type { JobRowsFrame, JobRowsRequest } from './types.ts' +import { OutputWaiter, sleep } from './wake.ts' + +/** Cadence bound for one roster generation. */ +export interface RowsOptions { + /** Coalescing window after a lifecycle event before the next rows read, in milliseconds. */ + readonly flushMs: number +} + +/** + * Stream the jobs one session can see: one frame on open, then one after + * every lifecycle commit that touches a visible job (registration, progress, + * stopping, settlement, removal), coalesced over `flushMs`. Output appends + * never refresh the roster — a settled projection already carries the final + * byte count — so the stream is quiet while a job merely writes. Reads are + * projections; the model's cursor and notice state never observe them. + * @param registry - the live job registry. + * @param request - the session whose visible set to mirror. + * @param options - the coalescing window. + * @param signal - generation cancellation owned by the Remote stream carrier. + * @returns the roster frame sequence for one generation. + */ +export async function* streamJobRows( + registry: JobRegistry, + request: JobRowsRequest, + options: RowsOptions, + signal: AbortSignal, +): AsyncIterable { + signal.throwIfAborted() + const waiter = new OutputWaiter() + // Subscribe before the first read so a commit between the read and the + // wait cannot be missed. + const unsubscribe = registry.events.subscribe({ owners: 'all' }, (event) => { + if (event.type === 'output') return + const owner = event.job.owner + if (owner === undefined || owner === request.sessionId) waiter.wake() + }) + try { + const visible = registry.visibleTo(request.sessionId) + yield { type: 'rows', jobs: visible.list() } + while (true) { + await waiter.wait(signal) + // Let a burst of commits settle into one frame. + await sleep(options.flushMs, signal) + if (signal.aborted) return + yield { type: 'rows', jobs: visible.list() } + } + } finally { + unsubscribe() + } +} diff --git a/packages/api/job-controller/src/types.ts b/packages/api/job-controller/src/types.ts index 98df4d8f65..0afa3ba1e9 100644 --- a/packages/api/job-controller/src/types.ts +++ b/packages/api/job-controller/src/types.ts @@ -1,24 +1,35 @@ /** - * Wire types of the generated `job` Remote namespace: the observation request - * and the frames its stream yields. Client-safe: no Host imports. + * Wire types of the generated `job` Remote namespace: the per-session roster + * stream and the per-job observation stream. Client-safe: no Host imports. * @module @deepseek-ai/dsh-api-job-controller/types */ import type { JobId } from '@deepseek-ai/dsh-jobs/brand' +import type { JobChunk, JobView } from '@deepseek-ai/dsh-jobs/view' import type { SessionId } from '@deepseek-ai/dsh-session/types' +export type { JobChunk, JobView } from '@deepseek-ai/dsh-jobs/view' + +/** Target of one `job.rows` stream: the session whose visible jobs the stream mirrors. */ +export interface JobRowsRequest { + readonly sessionId: SessionId +} + /** - * A job's lifecycle state on the wire. Spelled out rather than imported from - * the registry package so this client-safe face pulls no Host declaration - * merges into browser programs; it is the registry's `JobStatus` union. + * One `job.rows` frame: the complete set the session can see — its own jobs + * plus every unowned job — after a lifecycle change. Whole-set replacement, + * so a reconnect's first frame is already the truth. */ -export type JobObserveStatus = 'running' | 'stopping' | 'completed' | 'killed' | 'failed' +export interface JobRowsFrame { + readonly type: 'rows' + readonly jobs: readonly JobView[] +} /** Target of one `job.observe` stream: the job, its owning session, and an optional resume offset. */ export interface JobObserveRequest { /** - * Owning session, resolved to the live agent for the fenced record read. - * Omitted for an unowned job, which any caller may observe. + * Owning session for the fenced read. Omitted for an unowned job, which any + * caller may observe. */ readonly sessionId?: SessionId readonly jobId: JobId @@ -29,39 +40,25 @@ export interface JobObserveRequest { readonly from?: number } -/** One retained record chunk on the wire. `channel` widens to string like a job's `kind`. */ -export interface JobWireChunk { - /** Absolute offset of the chunk's first byte. */ - readonly at: number - readonly text: string - readonly channel?: string - /** Bytes immediately before this chunk were lost at the producer or to retention. */ - readonly gapBefore?: true -} - /** - * Job observation stream frames: one `opened` anchor, then coalesced `output` - * batches, then — once the job has settled and its retained record is - * drained — one terminal `status`, after which the stream closes normally. - * Status rides the same stream as output so settlement can never race a - * still-open output channel. + * Job observation stream frames: one `opened` anchor carrying the job's + * projection (its `output.earliest` and `output.total` at open time) and the + * offset the first `output` frame continues from, then coalesced `output` + * batches, then — once the job has settled and its ring is drained — one + * terminal `status` carrying the settled projection, after which the stream + * closes normally. Status rides the same stream as output so settlement can + * never race a still-open output channel. */ export type JobObserveFrame = | { readonly type: 'opened' - readonly jobId: JobId + readonly job: JobView /** Offset the first `output` frame continues from. */ readonly from: number - /** Oldest retained byte at open time; `from < earliest` means the head is gone. */ - readonly earliest: number - /** Total bytes produced at open time. */ - readonly total: number - readonly status: JobObserveStatus - readonly detail?: string } | { readonly type: 'output' - readonly chunks: readonly JobWireChunk[] + readonly chunks: readonly JobChunk[] /** Offset to resume from after this frame. */ readonly next: number /** Bytes between the requested offset and `chunks` were already evicted. */ @@ -69,7 +66,5 @@ export type JobObserveFrame = } | { readonly type: 'status' - readonly status: JobObserveStatus - readonly detail?: string - readonly finishedAt?: number + readonly job: JobView } diff --git a/packages/api/job-controller/src/wake.ts b/packages/api/job-controller/src/wake.ts new file mode 100644 index 0000000000..489699cb3c --- /dev/null +++ b/packages/api/job-controller/src/wake.ts @@ -0,0 +1,60 @@ +/** + * Wake bookkeeping shared by the two observation generators: a wake-flag + * waiter that never loses a wake between waits, and an abortable sleep that + * coalesces bursts into bounded frames. + * @module @deepseek-ai/dsh-api-job-controller/wake + */ + +/** Wake-flag waiter: a wake between waits is never lost. */ +export class OutputWaiter { + private dirty = false + private resolve: (() => void) | undefined + + /** Record one wake; releases a pending wait or arms the next one. */ + wake(): void { + this.dirty = true + this.resolve?.() + } + + /** + * Resolve on the next wake, immediately when one already arrived, or on abort. + * @param signal - generation cancellation. + * @returns settles when woken or aborted. + */ + wait(signal: AbortSignal): Promise { + if (this.dirty || signal.aborted) { + this.dirty = false + return Promise.resolve() + } + return new Promise((resolve) => { + const finish = (): void => { + signal.removeEventListener('abort', finish) + /* v8 ignore next -- one wait owns the sole installed resolver. */ + if (this.resolve === finish) this.resolve = undefined + this.dirty = false + resolve() + } + this.resolve = finish + signal.addEventListener('abort', finish, { once: true }) + }) + } +} + +/** + * Sleep for the coalescing window, or return at once when aborted. + * @param ms - window in milliseconds. + * @param signal - generation cancellation. + * @returns settles after the window or on abort. + */ +export function sleep(ms: number, signal: AbortSignal): Promise { + if (signal.aborted) return Promise.resolve() + return new Promise((resolve) => { + const timer = setTimeout(done, ms) + function done(): void { + clearTimeout(timer) + signal.removeEventListener('abort', done) + resolve() + } + signal.addEventListener('abort', done, { once: true }) + }) +} diff --git a/packages/api/job-controller/tests/client-apply.client.spec.ts b/packages/api/job-controller/tests/client-apply.client.spec.ts index ebbe67e98e..37fb4c3048 100644 --- a/packages/api/job-controller/tests/client-apply.client.spec.ts +++ b/packages/api/job-controller/tests/client-apply.client.spec.ts @@ -4,7 +4,7 @@ import { RemoteStream, type RemoteStreamOptions } from '@deepseek-ai/dsh-api-gat import type { SessionId } from '@deepseek-ai/dsh-session/types' import { afterEach, describe, expect, it } from 'vitest' import * as JobClient from '../src/client/index.ts' -import type { JobObserveFrame } from '../src/types.ts' +import type { JobObserveFrame, JobRowsFrame } from '../src/types.ts' const contexts = new Set() @@ -14,10 +14,11 @@ afterEach(async () => { }) /** Mount the client half over a captured `remote.job` namespace and a real Gateway stream carrier. */ -async function mount(): Promise<{ ctx: Context; observeCalls: unknown[] }> { +async function mount(): Promise<{ ctx: Context; observeCalls: unknown[]; rowsCalls: unknown[] }> { const ctx = new Context() contexts.add(ctx) const observeCalls: unknown[] = [] + const rowsCalls: unknown[] = [] const connection: ConnectionHandle = { isLoopback: true, generation: { getSnapshot: () => ({ id: 1, host: { home: '/home/fixture' } }), subscribe: () => () => {} }, @@ -28,7 +29,11 @@ async function mount(): Promise<{ ctx: Context; observeCalls: unknown[] }> { start: () => ({ stop: () => {} }), } const job = { - // The fake stream never yields; opening and releasing must leave no view behind. + // The fake streams never yield; opening and releasing must leave no state behind. + rows: (request: unknown) => { + rowsCalls.push(request) + return (async function* (): AsyncGenerator {})() + }, observe: (request: unknown) => { observeCalls.push(request) return (async function* (): AsyncGenerator {})() @@ -40,7 +45,7 @@ async function mount(): Promise<{ ctx: Context; observeCalls: unknown[] }> { }) ctx.reflect.provide('remote.job', job) await ctx.plugin(JobClient) - return { ctx, observeCalls } + return { ctx, observeCalls, rowsCalls } } async function flush(): Promise { @@ -52,14 +57,17 @@ describe('Job Controller Client apply', () => { expect(JobClient.inject).toEqual(['remote', 'remote.job']) }) - it('installs ctx.jobOutput over the captured job namespace', async () => { - const { ctx, observeCalls } = await mount() - expect(ctx.jobOutput).toBeDefined() - const stop = ctx.jobOutput.observe('session-1' as SessionId, 'bash-1' as never) + it('installs ctx.jobs over the captured job namespace', async () => { + const { ctx, observeCalls, rowsCalls } = await mount() + expect(ctx.jobs).toBeDefined() + const stopRows = ctx.jobs.watchRows('session-1' as SessionId) + const stopObserve = ctx.jobs.observe('session-1' as SessionId, 'bash-1' as never) await flush() + expect(rowsCalls).toEqual([{ sessionId: 'session-1' }]) expect(observeCalls).toEqual([{ sessionId: 'session-1', jobId: 'bash-1' }]) - stop() + stopRows() + stopObserve() await flush() - expect(ctx.jobOutput.state.getSnapshot().observed).toEqual({}) + expect(ctx.jobs.state.getSnapshot()).toEqual({ rows: {}, observed: {} }) }) }) diff --git a/packages/api/job-controller/tests/host-harness.ts b/packages/api/job-controller/tests/host-harness.ts new file mode 100644 index 0000000000..0ffb1fd2b8 --- /dev/null +++ b/packages/api/job-controller/tests/host-harness.ts @@ -0,0 +1,92 @@ +import { Context } from '@deepseek-ai/cordis' +import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' +import type { Agent } from '@deepseek-ai/dsh-agent' +import type { JobAppendOptions, JobHandle, JobOutcome } from '@deepseek-ai/dsh-jobs' +import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' +import { Session, SessionId } from '@deepseek-ai/dsh-session' + +/** A registry with a tiny ring so eviction is cheap to reach. */ +export async function harness(): Promise { + const ctx = new Context() + await ctx.plugin(AgentRegistry) + await ctx.plugin(LocalJobRegistry, { retainBytes: 64, settledRetainBytes: 64 }) + ctx.jobs.attachController('job-controller-test') + return ctx +} + +/** Register a live agent for `rawId` under its own lifecycle scope. */ +export function registerAgent(ctx: Context, rawId: string): Agent & { disposeScope: () => Promise } { + const scopeFiber = ctx.plugin(() => {}) + const id = SessionId(rawId) + const session = Session.create(id) + const agent = { + id, + session, + inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }), + status: 'idle', + ctx: scopeFiber.ctx, + disposeScope: () => scopeFiber.dispose(), + } as unknown as Agent & { disposeScope: () => Promise } + ctx.agents.register(agent) + return agent +} + +/** + * Start one push-producer job whose `done` settles on demand; expose the + * handle's writers. A cancel settles the job as killed unless `slowStop` + * keeps it stopping until the test settles it. + */ +export function startJob(ctx: Context, options: { label?: string; owner?: SessionId; slowStop?: boolean } = {}) { + let settle!: (outcome: JobOutcome) => void + let handle!: JobHandle + const id = ctx.jobs.start({ + kind: 'bash', + label: options.label ?? 'echo', + ...options.owner !== undefined ? { owner: options.owner } : {}, + run: (job) => { + handle = job + return { + cancel() { if (options.slowStop !== true) settle({ status: 'killed' }) }, + done: new Promise((resolve) => { settle = resolve }), + } + }, + }) + return { + id, + append: (text: string, opts?: JobAppendOptions) => { handle.append(text, opts) }, + progress: (line: string) => { handle.updateProgress(line) }, + settle: async (outcome: JobOutcome) => { + settle(outcome) + await new Promise(resolve => setTimeout(resolve, 0)) + }, + } +} + +/** Read frames until `count` arrive or the generator finishes, then abort. */ +export async function collect( + iterable: AsyncIterable, + count: number, + abort: AbortController, +): Promise { + const frames: Frame[] = [] + const iterator = iterable[Symbol.asyncIterator]() + try { + while (frames.length < count) { + const step = await iterator.next() + if (step.done) return frames + frames.push(step.value) + } + } finally { + abort.abort() + await iterator.next().catch(() => undefined) + } + return frames +} + +export const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms)) + +/** The next yielded frame, or undefined once the generator finished. */ +export async function next(iterator: AsyncIterator): Promise { + const step = await iterator.next() + return step.done === true ? undefined : step.value +} diff --git a/packages/api/job-controller/tests/model.client.spec.ts b/packages/api/job-controller/tests/model.client.spec.ts index 5e49771318..a170f1b98f 100644 --- a/packages/api/job-controller/tests/model.client.spec.ts +++ b/packages/api/job-controller/tests/model.client.spec.ts @@ -2,44 +2,75 @@ import { describe, expect, it, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' import type { JobId } from '@deepseek-ai/dsh-jobs/brand' import type { SessionId } from '@deepseek-ai/dsh-session/types' -import { ClientJobOutputModel } from '../src/client/model.ts' -import { ClientJobOutput } from '../src/client/service.ts' -import type { JobObserveFrame } from '../src/types.ts' +import { ClientJobsModel } from '../src/client/model.ts' +import { ClientJobs } from '../src/client/service.ts' +import type { JobObserveFrame, JobRowsFrame, JobView } from '../src/types.ts' const ID = 'bash-1' as JobId +const S1 = 'alice' as SessionId +const S2 = 'bob' as SessionId -function opened(model: ClientJobOutputModel, over: Partial<{ from: number; earliest: number; total: number }> = {}): void { +function view(over: Partial = {}): JobView { + return { + id: ID, kind: 'bash', label: 'pnpm run build', status: 'running', startedAt: 5, + output: { total: 0, earliest: 0 }, + ...over, + } +} + +function opened(model: ClientJobsModel, over: Partial<{ from: number; earliest: number; total: number }> = {}): void { model.observeOpened(ID, { type: 'opened', - jobId: ID, - from: 0, - earliest: 0, - total: 0, - status: 'running', - ...over, + job: view({ output: { total: over.total ?? 0, earliest: over.earliest ?? 0 } }), + from: over.from ?? 0, }) } -describe('ClientJobOutputModel observation', () => { - it('accumulates output, advances the resume cursor, and settles on status', () => { - const model = new ClientJobOutputModel() +describe('ClientJobsModel rows', () => { + it('replaces a session roster whole, stores an empty set as absence, and drops on release', () => { + const model = new ClientJobsModel() + let notified = 0 + model.subscribe(() => { notified += 1 }) + model.rowsReplaced(S1, [view()]) + model.rowsReplaced(S2, [view({ id: 'pwsh-1' as JobId, label: 'other' })]) + expect(model.getSnapshot().rows[S1]).toEqual([view()]) + expect(model.getSnapshot().rows[S2]?.[0]?.label).toBe('other') + + // Last-wins: the newer whole set replaces, it does not merge. + model.rowsReplaced(S1, [view({ status: 'completed' })]) + expect(model.getSnapshot().rows[S1]).toEqual([view({ status: 'completed' })]) + expect(notified).toBe(3) + + model.rowsReplaced(S1, []) + expect(S1 in model.getSnapshot().rows).toBe(false) + // An empty set over an absent key changes nothing. + model.rowsReplaced(S1, []) + expect(notified).toBe(4) + + model.rowsDropped(S2) + expect(model.getSnapshot().rows).toEqual({}) + model.rowsDropped(S2) + expect(notified).toBe(5) + }) +}) + +describe('ClientJobsModel observation', () => { + it('accumulates output, advances the resume cursor, and closes on settlement', () => { + const model = new ClientJobsModel() opened(model) expect(model.cursorOf(ID)).toBe(0) model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'a' }, { at: 1, text: 'b' }], next: 2 }) model.observeOutput(ID, { type: 'output', chunks: [{ at: 2, text: 'c' }], next: 3 }) expect(model.cursorOf(ID)).toBe(3) - const view = model.getSnapshot().observed[String(ID)] - expect(view?.text).toBe('abc') - expect(view?.streaming).toBe(true) - model.observeStatus(ID, { type: 'status', status: 'completed', detail: 'exit code: 0' }) - const settled = model.getSnapshot().observed[String(ID)] - expect(settled?.streaming).toBe(false) - expect(settled?.status).toBe('completed') - expect(settled?.detail).toBe('exit code: 0') + const live = model.getSnapshot().observed[String(ID)] + expect(live?.text).toBe('abc') + expect(live?.streaming).toBe(true) + model.observeSettled(ID) + expect(model.getSnapshot().observed[String(ID)]?.streaming).toBe(false) }) it('keeps snapshot identity stable between changes and notifies subscribers', () => { - const model = new ClientJobOutputModel() + const model = new ClientJobsModel() let notified = 0 const unsubscribe = model.subscribe(() => { notified += 1 }) const before = model.getSnapshot() @@ -53,16 +84,16 @@ describe('ClientJobOutputModel observation', () => { }) it('marks gaps from lossy frames, gap chunks, and a resume behind the retained head', () => { - const model = new ClientJobOutputModel() + const model = new ClientJobsModel() opened(model, { from: 4, earliest: 8, total: 10 }) expect(model.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) - const clean = new ClientJobOutputModel() + const clean = new ClientJobsModel() opened(clean) clean.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'x', gapBefore: true }], next: 1 }) expect(clean.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) - const lossy = new ClientJobOutputModel() + const lossy = new ClientJobsModel() opened(lossy) lossy.observeOutput(ID, { type: 'output', chunks: [], next: 5, lossy: true }) expect(lossy.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) @@ -71,12 +102,12 @@ describe('ClientJobOutputModel observation', () => { it('marks a fresh observation anchored past the evicted head', () => { // Fresh observations anchor at the registry's earliest retained byte, so // from === earliest > 0 means the head was already discarded. - const fresh = new ClientJobOutputModel() + const fresh = new ClientJobsModel() opened(fresh, { from: 60_240, earliest: 60_240, total: 321_328 }) expect(fresh.getSnapshot().observed[String(ID)]?.gapBefore).toBe(true) // A retry that accumulated no text yet earns the mark the same way. - const retried = new ClientJobOutputModel() + const retried = new ClientJobsModel() opened(retried) expect(retried.getSnapshot().observed[String(ID)]?.gapBefore).toBe(false) opened(retried, { from: 6, earliest: 6, total: 6 }) @@ -84,43 +115,40 @@ describe('ClientJobOutputModel observation', () => { }) it('bounds the render tail without splitting a surrogate pair', () => { - const model = new ClientJobOutputModel() + const model = new ClientJobsModel() opened(model) const emoji = '😀'.repeat((64 * 1024) + 8) model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: emoji }], next: emoji.length * 2 }) - const view = model.getSnapshot().observed[String(ID)] - expect(view?.gapBefore).toBe(true) - expect(view!.text.length).toBeLessThanOrEqual(128 * 1024) + const live = model.getSnapshot().observed[String(ID)] + expect(live?.gapBefore).toBe(true) + expect(live!.text.length).toBeLessThanOrEqual(128 * 1024) // The bound landed between pairs: the surviving text still round-trips. - expect(/^(?:😀)+$/u.test(view!.text)).toBe(true) + expect(/^(?:😀)+$/u.test(live!.text)).toBe(true) }) - it('carries the anchor detail and trims a plain-ASCII tail without a boundary shift', () => { - const model = new ClientJobOutputModel() - model.observeOpened(ID, { - type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running', detail: 'exit soon', - }) - expect(model.getSnapshot().observed[String(ID)]?.detail).toBe('exit soon') + it('trims a plain-ASCII tail without a boundary shift', () => { + const model = new ClientJobsModel() + opened(model) const long = 'x'.repeat((128 * 1024) + 5) model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: long }], next: long.length }) - const view = model.getSnapshot().observed[String(ID)] - expect(view?.text.length).toBe(128 * 1024) - expect(view?.gapBefore).toBe(true) + const live = model.getSnapshot().observed[String(ID)] + expect(live?.text.length).toBe(128 * 1024) + expect(live?.gapBefore).toBe(true) }) it('advances the cut past a low surrogate landing exactly on the bound', () => { - const model = new ClientJobOutputModel() + const model = new ClientJobsModel() opened(model) // 'z' + one emoji + odd ASCII tail puts a low surrogate exactly at the cut index. const text = 'z😀' + 'a'.repeat((128 * 1024) - 1) model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text }], next: text.length }) - const view = model.getSnapshot().observed[String(ID)] - expect(view?.text.length).toBe((128 * 1024) - 1) - expect(view?.text.startsWith('a')).toBe(true) + const live = model.getSnapshot().observed[String(ID)] + expect(live?.text.length).toBe((128 * 1024) - 1) + expect(live?.text.startsWith('a')).toBe(true) }) it('preserves accumulated text across a reconnect anchor and clears on stop', () => { - const model = new ClientJobOutputModel() + const model = new ClientJobsModel() opened(model) model.observeOutput(ID, { type: 'output', chunks: [{ at: 0, text: 'kept' }], next: 4 }) opened(model, { from: 4, earliest: 0, total: 4 }) @@ -133,19 +161,19 @@ describe('ClientJobOutputModel observation', () => { }) it('records a terminal stream failure on the live view', () => { - const model = new ClientJobOutputModel() + const model = new ClientJobsModel() opened(model) model.observeFailed(ID, new Error('carrier gone')) - const view = model.getSnapshot().observed[String(ID)] - expect(view?.streaming).toBe(false) - expect(view?.error).toContain('carrier gone') + const live = model.getSnapshot().observed[String(ID)] + expect(live?.streaming).toBe(false) + expect(live?.error).toContain('carrier gone') // A failure for an untracked id is inert. model.observeFailed('bash-9' as JobId, new Error('ignored')) }) }) /** One scripted logical stream: frames are pushed by the test, never reopened. */ -class FakeStream { +class FakeStream { disposed = false /** Model a carrier whose disposal surfaces as an iterator throw. */ throwOnDispose = false @@ -153,12 +181,12 @@ class FakeStream { deferDispose = false private disposeRelease: (() => void) | undefined private disposePending: Promise | undefined - private readonly frames: JobObserveFrame[] = [] + private readonly frames: Frame[] = [] private waiter: (() => void) | undefined private failure: Error | undefined readonly accepts: number[] = [] - push(frame: JobObserveFrame): void { + push(frame: Frame): void { this.frames.push(frame) this.waiter?.() } @@ -208,14 +236,21 @@ class FakeStream { } } +interface StreamOptions { + name: string + open: (signal: AbortSignal) => unknown + ended: (accepted: boolean) => Error +} + function bench() { const ctx = new Context() - const model = new ClientJobOutputModel() - const streams: { options: { open: (signal: AbortSignal) => unknown }; stream: FakeStream }[] = [] + const model = new ClientJobsModel() + const streams: { options: StreamOptions; stream: FakeStream & FakeStream }[] = [] const observeCalls: unknown[] = [] + const rowsCalls: unknown[] = [] const remote = { - $stream: (options: { open: (signal: AbortSignal) => unknown }) => { - const stream = new FakeStream() + $stream: (options: StreamOptions) => { + const stream = new FakeStream() streams.push({ options, stream }) return stream }, @@ -224,37 +259,129 @@ function bench() { observeCalls.push(request) return { [Symbol.asyncIterator]: async function* () { /* never yields */ } } }, + rows: (request: unknown) => { + rowsCalls.push(request) + return { [Symbol.asyncIterator]: async function* () { /* never yields */ } } + }, }, } - const output = new ClientJobOutput(ctx, remote as never, model) - return { ctx, model, output, streams, observeCalls } + const jobs = new ClientJobs(ctx, remote as never, model) + return { ctx, model, jobs, streams, observeCalls, rowsCalls } } const tick = () => new Promise(resolve => setTimeout(resolve, 0)) +const anchor = (): JobObserveFrame => ({ type: 'opened', job: view(), from: 0 }) + +describe('ClientJobs roster streams', () => { + it('shares one roster stream per session and drops the rows after the last release', async () => { + const { model, jobs, streams, rowsCalls } = bench() + const first = jobs.watchRows(S1) + const second = jobs.watchRows(S1) + jobs.watchRows(S2) + expect(streams.map(entry => entry.options.name)).toEqual(['job rows alice', 'job rows bob']) + streams[0]!.options.open(new AbortController().signal) + expect(rowsCalls.at(-1)).toEqual({ sessionId: 'alice' }) -describe('ClientJobOutput observation streams', () => { - it('feeds anchor, output, and terminal frames into the model, then closes', async () => { - const { model, output, streams } = bench() - output.observe(undefined, ID) const { stream } = streams[0]! - stream.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + stream.push({ type: 'rows', jobs: [view()] }) + await tick() + expect(model.getSnapshot().rows[S1]).toEqual([view()]) + expect(stream.accepts).toHaveLength(1) + stream.push({ type: 'rows', jobs: [view({ status: 'completed' })] }) + await tick() + expect(model.getSnapshot().rows[S1]?.[0]?.status).toBe('completed') + + first() + first() + expect(stream.disposed).toBe(false) + second() + await tick() + expect(stream.disposed).toBe(true) + expect(S1 in model.getSnapshot().rows).toBe(false) + expect(streams[1]!.stream.disposed).toBe(false) + }) + + it('classifies a roster end as retryable only after the first frame', () => { + const { jobs, streams } = bench() + jobs.watchRows(S1) + const { options } = streams[0]! + expect(options.ended(true).name).toBe('RemoteStreamCarrierError') + expect(options.ended(false).name).toBe('Error') + }) + + it('drops the roster on a terminal stream failure', async () => { + const { model, jobs, streams } = bench() + jobs.watchRows(S1) + const { stream } = streams[0]! + stream.push({ type: 'rows', jobs: [view()] }) + await tick() + expect(model.getSnapshot().rows[S1]).toBeDefined() + stream.poison(new Error('frame decode broke')) + await tick() + expect(S1 in model.getSnapshot().rows).toBe(false) + }) + + it('stays silent when the carrier teardown itself throws after the last release', async () => { + const { model, jobs, streams } = bench() + const stop = jobs.watchRows(S1) + const { stream } = streams[0]! + stream.throwOnDispose = true + stream.push({ type: 'rows', jobs: [view()] }) + await tick() + // The releaser drops the rows and marks the entry stopped, then its + // dispose surfaces as an iterator throw — which the consumer swallows for + // a stopped entry instead of dropping twice or failing loud. + stop() + await tick() + expect(model.getSnapshot().rows).toEqual({}) + }) + + it('a re-watch inside the dispose round-trip keeps its fresh rows', async () => { + const { model, jobs, streams } = bench() + const stop = jobs.watchRows(S1) + const first = streams[0]!.stream + first.deferDispose = true + first.push({ type: 'rows', jobs: [view()] }) + await tick() + + stop() + // Re-watch while the previous generation's dispose is still in flight. + jobs.watchRows(S1) + const second = streams[1]!.stream + second.push({ type: 'rows', jobs: [view({ label: 'fresh' })] }) + await tick() + + first.releaseDispose() + await tick() + // The stale post-dispose clear must not blank the successor's rows. + expect(model.getSnapshot().rows[S1]?.[0]?.label).toBe('fresh') + }) +}) + +describe('ClientJobs observation streams', () => { + it('feeds anchor, output, and terminal frames into the model, then closes', async () => { + const { model, jobs, streams } = bench() + jobs.observe(undefined, ID) + const { stream } = streams[0]! + expect(streams[0]!.options.name).toBe('job observation bash-1') + stream.push(anchor()) stream.push({ type: 'output', chunks: [{ at: 0, text: 'hi' }], next: 2 }) await tick() expect(model.getSnapshot().observed[String(ID)]?.text).toBe('hi') expect(stream.accepts).toHaveLength(1) - stream.push({ type: 'status', status: 'completed' }) + stream.push({ type: 'status', job: view({ status: 'completed' }) }) await tick() expect(model.getSnapshot().observed[String(ID)]?.streaming).toBe(false) expect(stream.disposed).toBe(true) }) it('shares one stream across observers and stops after the last release', async () => { - const { model, output, streams } = bench() - const first = output.observe(undefined, ID) - const second = output.observe(undefined, ID) + const { model, jobs, streams } = bench() + const first = jobs.observe(undefined, ID) + const second = jobs.observe(undefined, ID) expect(streams).toHaveLength(1) - streams[0]!.stream.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + streams[0]!.stream.push(anchor()) await tick() first() @@ -267,17 +394,17 @@ describe('ClientJobOutput observation streams', () => { }) it('a late release of a superseded observation neither tears down nor clears its successor', async () => { - const { model, output, streams } = bench() - const firstStop = output.observe(undefined, ID) + const { model, jobs, streams } = bench() + const firstStop = jobs.observe(undefined, ID) const first = streams[0]!.stream - first.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) - first.push({ type: 'status', status: 'completed' }) + first.push(anchor()) + first.push({ type: 'status', job: view({ status: 'completed' }) }) await tick() // A successor observation replaces the settled entry while the first // observer still holds its releaser. - const secondStop = output.observe(undefined, ID) + const secondStop = jobs.observe(undefined, ID) const second = streams[1]!.stream - second.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + second.push(anchor()) await tick() firstStop() @@ -292,18 +419,18 @@ describe('ClientJobOutput observation streams', () => { }) it('a re-observation inside the dispose round-trip keeps its fresh view', async () => { - const { model, output, streams } = bench() - const stop = output.observe(undefined, ID) + const { model, jobs, streams } = bench() + const stop = jobs.observe(undefined, ID) const first = streams[0]!.stream first.deferDispose = true - first.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + first.push(anchor()) await tick() stop() // Re-expand while the previous generation's dispose is still in flight. - output.observe(undefined, ID) + jobs.observe(undefined, ID) const second = streams[1]!.stream - second.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + second.push(anchor()) await tick() first.releaseDispose() @@ -316,9 +443,9 @@ describe('ClientJobOutput observation streams', () => { }) it('opens a fresh stream for a re-observed job and resumes from the model cursor', async () => { - const { output, streams, observeCalls, model } = bench() - const stop = output.observe('alice' as SessionId, ID) - streams[0]!.stream.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + const { jobs, streams, observeCalls, model } = bench() + const stop = jobs.observe(S1, ID) + streams[0]!.stream.push(anchor()) streams[0]!.stream.push({ type: 'output', chunks: [{ at: 0, text: 'abc' }], next: 3 }) await tick() // The generation opener reads the live cursor at open time and carries the @@ -328,7 +455,7 @@ describe('ClientJobOutput observation streams', () => { stop() await tick() - output.observe(undefined, ID) + jobs.observe(undefined, ID) expect(streams).toHaveLength(2) streams[1]!.options.open(new AbortController().signal) // Stopped observation dropped the cursor: the fresh stream starts unanchored. @@ -337,31 +464,31 @@ describe('ClientJobOutput observation streams', () => { }) it('classifies a premature end as retryable only after the anchor', () => { - const { output, streams } = bench() - output.observe(undefined, ID) - const options = streams[0]!.options as unknown as { ended: (accepted: boolean) => Error } + const { jobs, streams } = bench() + jobs.observe(undefined, ID) + const { options } = streams[0]! expect(options.ended(true).name).toBe('RemoteStreamCarrierError') expect(options.ended(false).name).toBe('Error') }) it('records a consumer failure on the live view', async () => { - const { model, output, streams } = bench() - output.observe(undefined, ID) + const { model, jobs, streams } = bench() + jobs.observe(undefined, ID) const { stream } = streams[0]! - stream.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + stream.push(anchor()) await tick() stream.poison(new Error('frame decode broke')) await tick() - const view = model.getSnapshot().observed[String(ID)] - expect(view?.error).toContain('frame decode broke') - expect(view?.streaming).toBe(false) + const live = model.getSnapshot().observed[String(ID)] + expect(live?.error).toContain('frame decode broke') + expect(live?.streaming).toBe(false) }) it('treats a release after service disposal as inert and stays silent for post-stop failures', async () => { - const { ctx, model, output, streams } = bench() - const stop = output.observe(undefined, ID) + const { ctx, model, jobs, streams } = bench() + const stop = jobs.observe(undefined, ID) const { stream } = streams[0]! - stream.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + stream.push(anchor()) await tick() // Poison wakes the consumer, but the synchronous stop lands first, so the // failure arrives on an already-stopped entry and stays silent. @@ -370,7 +497,7 @@ describe('ClientJobOutput observation streams', () => { await tick() expect(model.getSnapshot().observed[String(ID)]).toBeUndefined() - const second = output.observe(undefined, ID) + const second = jobs.observe(undefined, ID) await ctx.fiber.dispose() // The disposal path already removed every entry; a live releaser whose // entry is gone is inert. @@ -378,11 +505,11 @@ describe('ClientJobOutput observation streams', () => { }) it('stays silent when the carrier teardown itself throws after a stop', async () => { - const { model, output, streams } = bench() - const stop = output.observe(undefined, ID) + const { model, jobs, streams } = bench() + const stop = jobs.observe(undefined, ID) const { stream } = streams[0]! stream.throwOnDispose = true - stream.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + stream.push(anchor()) await tick() // The releaser marks the entry stopped, then its dispose surfaces as an // iterator throw — which the consumer swallows for a stopped entry. @@ -392,9 +519,9 @@ describe('ClientJobOutput observation streams', () => { }) it('holds service disposal until every open stream reports quiescence', async () => { - const { ctx, output, streams } = bench() - output.observe(undefined, ID) - output.observe(undefined, 'bash-2' as JobId) + const { ctx, jobs, streams } = bench() + jobs.watchRows(S1) + jobs.observe(undefined, ID) for (const { stream } of streams) stream.deferDispose = true await tick() @@ -416,21 +543,18 @@ describe('ClientJobOutput observation streams', () => { }) it('records a terminal stream failure and service disposal closes live streams', async () => { - const { ctx, model, output, streams } = bench() - output.observe(undefined, ID) + const { ctx, model, jobs, streams } = bench() + jobs.observe(undefined, ID) const failing = streams[0]!.stream - failing.push({ type: 'opened', jobId: ID, from: 0, earliest: 0, total: 0, status: 'running' }) + failing.push(anchor()) await tick() - const iterator = failing[Symbol.asyncIterator]() - void iterator // Simulate a terminal consumer failure by disposing the underlying stream: // the consumer loop ends without a status frame and cleans up. const spy = vi.spyOn(model, 'observeFailed') await failing.dispose() await tick() - const other = 'bash-2' as JobId - output.observe(undefined, other) + jobs.observe(undefined, 'bash-2' as JobId) await ctx.fiber.dispose() expect(streams.every(entry => entry.stream.disposed)).toBe(true) expect(spy).not.toHaveBeenCalled() diff --git a/packages/api/job-controller/tests/observe.host.spec.ts b/packages/api/job-controller/tests/observe.host.spec.ts index bc6827fdc2..7f36b8df1e 100644 --- a/packages/api/job-controller/tests/observe.host.spec.ts +++ b/packages/api/job-controller/tests/observe.host.spec.ts @@ -3,123 +3,58 @@ import { Context } from '@deepseek-ai/cordis' import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import { JobId } from '@deepseek-ai/dsh-jobs' -import type { JobOutcome, RecordingJob } from '@deepseek-ai/dsh-jobs' import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' -import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session' +import SessionStore, { SessionId } from '@deepseek-ai/dsh-session' import TypertRegistry from '@deepseek-ai/dsh-typert-registry' import { JobController } from '../src/index.ts' -import { observeJobRecord } from '../src/observe.ts' +import { observeJobOutput } from '../src/observe.ts' import type { ObserveJobOptions } from '../src/observe.ts' import type { JobObserveFrame } from '../src/types.ts' +import { collect, harness, next, registerAgent, startJob, wait } from './host-harness.ts' -async function harness() { - const ctx = new Context() - await ctx.plugin(AgentRegistry) - await ctx.plugin(LocalJobRegistry, { retainBytes: 64, settledRetainBytes: 64 }) - ctx.jobs.attachController('observe-job-test') - return ctx -} +const OBSERVE: ObserveJobOptions = { flushMs: 5, maxFrameBytes: 1024 } -function registerAgent(ctx: Context, rawId: string): Agent { - const scopeFiber = ctx.plugin(() => {}) - const id = SessionId(rawId) - const session = Session.create(id) - const agent = { - id, - session, - inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }), - status: 'idle', - ctx: scopeFiber.ctx, - } as unknown as Agent - ctx.agents.register(agent) - return agent -} - -/** Start one record job whose done settles on demand; expose the producer face. */ -function startRecordJob(ctx: Context, options: { label?: string; owner?: Agent; record?: boolean } = {}) { - let settle!: (outcome: JobOutcome) => void - let face!: RecordingJob - const id = ctx.jobs.start({ - kind: 'bash', - label: options.label ?? 'echo', - ...options.owner !== undefined ? { owner: options.owner } : {}, - ...options.record === false ? {} : { record: true }, - run: (job: RecordingJob) => { - face = job - return { - cancel() {}, - done: new Promise((resolve) => { settle = resolve }), - } - }, - }) - return { - id, - append: (text: string, opts?: Parameters[1]) => { face.append(text, opts) }, - updateDetail: (detail: string) => { face.updateDetail(detail) }, - settle: async (outcome: JobOutcome) => { - settle(outcome) - await new Promise(resolve => setTimeout(resolve, 0)) - }, - } -} - -/** Read frames until `count` arrive or the generator finishes, then abort. */ -async function collect( - iterable: AsyncIterable, - count: number, - abort: AbortController, -): Promise { - const frames: Frame[] = [] - const iterator = iterable[Symbol.asyncIterator]() - try { - while (frames.length < count) { - const step = await iterator.next() - if (step.done) return frames - frames.push(step.value) - } - } finally { - abort.abort() - await iterator.next().catch(() => undefined) - } - return frames -} - -const OBSERVE: Omit = { flushMs: 5, maxFrameBytes: 1024 } - -describe('observeJobRecord', () => { - function observed(ctx: Context, request: { jobId: JobId; from?: number }, caller?: Agent) { +describe('observeJobOutput', () => { + function observed(ctx: Context, request: { jobId: JobId; sessionId?: SessionId; from?: number }) { const abort = new AbortController() const frames: JobObserveFrame[] = [] - const stream = observeJobRecord(ctx.jobs, request, { ...OBSERVE, caller }, abort.signal) + const stream = observeJobOutput(ctx.jobs, request, OBSERVE, abort.signal) const done = (async () => { for await (const frame of stream) frames.push(frame) })() return { abort, frames, done } } - it('anchors, streams coalesced output, and closes with the terminal status', async () => { + it('anchors, streams coalesced output, and closes with the terminal projection', async () => { const ctx = await harness() - const job = startRecordJob(ctx) + const job = startJob(ctx) job.append('early ') const { frames, done } = observed(ctx, { jobId: job.id }) - await new Promise(resolve => setTimeout(resolve, 20)) + await wait(20) job.append('live', { channel: 'stderr' }) - await new Promise(resolve => setTimeout(resolve, 20)) + await wait(20) await job.settle({ status: 'completed', detail: 'exit code: 0' }) await done - expect(frames[0]).toMatchObject({ type: 'opened', from: 0, earliest: 0, total: 6, status: 'running' }) + expect(frames[0]).toMatchObject({ + type: 'opened', + from: 0, + job: { id: job.id, status: 'running', output: { earliest: 0, total: 6 } }, + }) const outputs = frames.filter(frame => frame.type === 'output') const text = outputs.flatMap(frame => frame.chunks.map(chunk => chunk.text)).join('') expect(text).toBe('early live') expect(outputs.at(-1)?.next).toBe(10) expect(outputs.flatMap(frame => frame.chunks).find(chunk => chunk.text === 'live')?.channel).toBe('stderr') - expect(frames.at(-1)).toMatchObject({ type: 'status', status: 'completed', detail: 'exit code: 0' }) + expect(frames.at(-1)).toMatchObject({ + type: 'status', + job: { status: 'completed', detail: 'exit code: 0', output: { total: 10 } }, + }) }) it('resumes from an explicit offset and flags an evicted resume lossy', async () => { const ctx = await harness() - const job = startRecordJob(ctx, { label: 'spam' }) + const job = startJob(ctx, { label: 'spam' }) job.append('a'.repeat(60)) job.append('b'.repeat(60)) await job.settle({ status: 'completed' }) @@ -138,17 +73,13 @@ describe('observeJobRecord', () => { it('splits oversized reads along the frame budget', async () => { const ctx = await harness() - const job = startRecordJob(ctx, { label: 'wide' }) + const job = startJob(ctx, { label: 'wide' }) job.append('x'.repeat(30)) job.append('y'.repeat(30)) await job.settle({ status: 'completed' }) const abort = new AbortController() const frames = await collect( - observeJobRecord(ctx.jobs, { jobId: job.id }, { - flushMs: 5, - maxFrameBytes: 30, - caller: undefined, - }, abort.signal), + observeJobOutput(ctx.jobs, { jobId: job.id }, { flushMs: 5, maxFrameBytes: 30 }, abort.signal), 5, abort, ) @@ -160,18 +91,14 @@ describe('observeJobRecord', () => { it('carries the lossy flag on the first frame of a split evicted read', async () => { const ctx = await harness() - const job = startRecordJob(ctx, { label: 'evicted split' }) + const job = startJob(ctx, { label: 'evicted split' }) job.append('a'.repeat(40)) job.append('b'.repeat(40)) job.append('c'.repeat(40)) await job.settle({ status: 'completed' }) const abort = new AbortController() const frames = await collect( - observeJobRecord(ctx.jobs, { jobId: job.id, from: 0 }, { - flushMs: 5, - maxFrameBytes: 40, - caller: undefined, - }, abort.signal), + observeJobOutput(ctx.jobs, { jobId: job.id, from: 0 }, { flushMs: 5, maxFrameBytes: 40 }, abort.signal), 5, abort, ) @@ -180,61 +107,49 @@ describe('observeJobRecord', () => { expect(outputs[1]?.lossy).toBeUndefined() }) - it('reads owned records through the resolved caller and rejects foreign, bad, and unknown input', async () => { + it('reads owned output through the request session and rejects foreign, bad, and unknown input', async () => { const ctx = await harness() const owner = registerAgent(ctx, 'alice') - const job = startRecordJob(ctx, { label: 'secret', owner }) + const job = startJob(ctx, { label: 'secret', owner: owner.id }) job.append('classified') await job.settle({ status: 'completed' }) - const { frames, done } = observed(ctx, { jobId: job.id }, owner) + const { frames, done } = observed(ctx, { jobId: job.id, sessionId: owner.id }) await done expect(frames.some(frame => frame.type === 'output' && frame.chunks.some(chunk => chunk.text === 'classified'))).toBe(true) const foreign = new AbortController() await expect(collect( - observeJobRecord(ctx.jobs, { jobId: job.id }, { ...OBSERVE, caller: undefined }, foreign.signal), + observeJobOutput(ctx.jobs, { jobId: job.id }, OBSERVE, foreign.signal), 1, foreign, )).rejects.toThrow(/belongs to another session/) const abort = new AbortController() await expect(collect( - observeJobRecord(ctx.jobs, { jobId: job.id, from: -1 }, { ...OBSERVE, caller: owner }, abort.signal), + observeJobOutput(ctx.jobs, { jobId: job.id, sessionId: owner.id, from: -1 }, OBSERVE, abort.signal), 1, abort, )).rejects.toThrow(/invalid observe offset/) const abortUnknown = new AbortController() await expect(collect( - observeJobRecord(ctx.jobs, { jobId: JobId('bash-999') }, { ...OBSERVE, caller: undefined }, abortUnknown.signal), + observeJobOutput(ctx.jobs, { jobId: JobId('bash-999') }, OBSERVE, abortUnknown.signal), 1, abortUnknown, )).rejects.toThrow(/unknown job/) }) - it('refuses a job that declared no record', async () => { + it('anchors with the live progress and takes the fast wait path for a wake that lands mid-yield', async () => { const ctx = await harness() - const job = startRecordJob(ctx, { record: false }) + const job = startJob(ctx) + job.progress('3/10') const abort = new AbortController() - await expect(collect( - observeJobRecord(ctx.jobs, { jobId: job.id }, { ...OBSERVE, caller: undefined }, abort.signal), - 1, - abort, - )).rejects.toThrow(/declared no output record/) - await job.settle({ status: 'completed' }) - }) - - it('anchors with the live detail and takes the fast wait path for a wake that lands mid-yield', async () => { - const ctx = await harness() - const job = startRecordJob(ctx) - job.updateDetail('3/10') - const abort = new AbortController() - const iterator = observeJobRecord(ctx.jobs, { jobId: job.id }, { ...OBSERVE, caller: undefined }, abort.signal)[Symbol.asyncIterator]() + const iterator = observeJobOutput(ctx.jobs, { jobId: job.id }, OBSERVE, abort.signal)[Symbol.asyncIterator]() const anchor = await iterator.next() - expect(anchor.value).toMatchObject({ type: 'opened', detail: '3/10' }) + expect(anchor.value).toMatchObject({ type: 'opened', job: { progress: '3/10' } }) // Both chunks land while the generator is suspended on a yield, so each // wake precedes the loop's wait(): draining the first chunk must pass // through the already-woken fast path to read the second. @@ -247,18 +162,18 @@ describe('observeJobRecord', () => { const pending = iterator.next() await job.settle({ status: 'completed' }) const status = await pending - expect(status.value).toMatchObject({ type: 'status', status: 'completed' }) + expect(status.value).toMatchObject({ type: 'status', job: { status: 'completed' } }) expect((await iterator.next()).done).toBe(true) }) it('ignores output signals for other jobs while waiting', async () => { const ctx = await harness() - const watched = startRecordJob(ctx, { label: 'watched' }) - const noisy = startRecordJob(ctx, { label: 'noisy' }) + const watched = startJob(ctx, { label: 'watched' }) + const noisy = startJob(ctx, { label: 'noisy' }) const { abort, frames, done } = observed(ctx, { jobId: watched.id }) - await new Promise(resolve => setTimeout(resolve, 15)) + await wait(15) noisy.append('unrelated') - await new Promise(resolve => setTimeout(resolve, 15)) + await wait(15) await watched.settle({ status: 'completed' }) await done abort.abort() @@ -268,9 +183,9 @@ describe('observeJobRecord', () => { it('stops cleanly on abort while waiting for output', async () => { const ctx = await harness() - const job = startRecordJob(ctx, { label: 'idle' }) + const job = startJob(ctx, { label: 'idle' }) const { abort, frames, done } = observed(ctx, { jobId: job.id }) - await new Promise(resolve => setTimeout(resolve, 20)) + await wait(20) abort.abort() await done expect(frames[0]?.type).toBe('opened') @@ -279,18 +194,31 @@ describe('observeJobRecord', () => { }) }) -describe('JobController.observe', () => { +describe('JobController', () => { async function controllerHarness() { const ctx = new Context() await ctx.plugin(SessionStore) await ctx.plugin(AgentRegistry) await ctx.plugin(LocalJobRegistry) await ctx.plugin(TypertRegistry) - ctx.jobs.attachController('observe-job-test') + ctx.jobs.attachController('job-controller-test') await ctx.plugin(JobController, {}) return ctx } + function liveOwner(ctx: Context, rawId: string): Agent { + const session = ctx.sessions.create(SessionId(rawId)) + const owner = { + id: session.id, + session, + inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }), + status: 'idle', + ctx, + } as unknown as Agent + ctx.agents.register(owner) + return owner + } + it('waits for the job registry instead of serving without one', async () => { const ctx = new Context() await ctx.plugin(SessionStore) @@ -301,24 +229,16 @@ describe('JobController.observe', () => { expect(ctx.get('jobController')).toBeUndefined() }) - it('resolves the fenced-read caller from the request session', async () => { + it('observe reads an owned job through the request session', async () => { const ctx = await controllerHarness() - const session = ctx.sessions.create(SessionId('observing-session')) - const owner = { - id: session.id, - session, - inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }), - status: 'idle', - ctx, - } as unknown as Agent - ctx.agents.register(owner) - const job = startRecordJob(ctx, { label: 'owned run', owner }) + const owner = liveOwner(ctx, 'observing-session') + const job = startJob(ctx, { label: 'owned run', owner: owner.id }) job.append('hi') await job.settle({ status: 'completed' }) const abort = new AbortController() const frames = await collect( - ctx.jobController.observe({ sessionId: session.id, jobId: job.id }, abort.signal), + ctx.jobController.observe({ sessionId: owner.id, jobId: job.id }, abort.signal), 3, abort, ) @@ -327,7 +247,7 @@ describe('JobController.observe', () => { it('observes an unowned job without a request session', async () => { const ctx = await controllerHarness() - const job = startRecordJob(ctx, { label: 'unowned run' }) + const job = startJob(ctx, { label: 'unowned run' }) job.append('open access') await job.settle({ status: 'completed' }) @@ -339,4 +259,22 @@ describe('JobController.observe', () => { ) expect(frames.map(frame => frame.type)).toEqual(['opened', 'output', 'status']) }) + + it('rows mirrors the session-visible set and follows a settlement', async () => { + const ctx = await controllerHarness() + const owner = liveOwner(ctx, 'listing-session') + const owned = startJob(ctx, { label: 'owned', owner: owner.id }) + startJob(ctx, { label: 'shared' }) + + const abort = new AbortController() + const iterator = ctx.jobController.rows({ sessionId: owner.id }, abort.signal)[Symbol.asyncIterator]() + const first = await next(iterator) + expect(first?.jobs.map(job => job.label)).toEqual(['owned', 'shared']) + const pending = next(iterator) + await owned.settle({ status: 'completed', detail: 'exit code: 0' }) + const second = await pending + expect(second?.jobs.find(job => job.id === owned.id)).toMatchObject({ status: 'completed', detail: 'exit code: 0' }) + abort.abort() + expect(await next(iterator)).toBeUndefined() + }) }) diff --git a/packages/api/job-controller/tests/rows.host.spec.ts b/packages/api/job-controller/tests/rows.host.spec.ts new file mode 100644 index 0000000000..f246425605 --- /dev/null +++ b/packages/api/job-controller/tests/rows.host.spec.ts @@ -0,0 +1,89 @@ +import { describe, expect, it } from 'vitest' +import { streamJobRows } from '../src/rows.ts' +import { harness, next, registerAgent, startJob, wait } from './host-harness.ts' + +const ROWS = { flushMs: 5 } + +describe('streamJobRows', () => { + it('opens with the visible set and re-sends it after each coalesced lifecycle burst', async () => { + const ctx = await harness() + const alice = registerAgent(ctx, 'alice') + const bob = registerAgent(ctx, 'bob') + startJob(ctx, { label: 'shared' }) + const mine = startJob(ctx, { label: 'mine', owner: alice.id }) + startJob(ctx, { label: 'theirs', owner: bob.id }) + + const abort = new AbortController() + const iterator = streamJobRows(ctx.jobs, { sessionId: alice.id }, ROWS, abort.signal)[Symbol.asyncIterator]() + const first = await next(iterator) + expect(first?.jobs.map(job => job.label)).toEqual(['shared', 'mine']) + + // Another owner's lifecycle and this job's own output never wake the roster; + // the next frame is the one the settlement earns, and it carries the final + // byte count without a frame per append. + startJob(ctx, { label: 'theirs too', owner: bob.id }) + mine.append('progress bytes') + await wait(20) + const pending = next(iterator) + await mine.settle({ status: 'completed', detail: 'exit code: 0' }) + const second = await pending + expect(second?.jobs.map(job => job.label)).toEqual(['shared', 'mine']) + expect(second?.jobs[1]).toMatchObject({ status: 'completed', detail: 'exit code: 0', output: { total: 14 } }) + abort.abort() + expect(await next(iterator)).toBeUndefined() + }) + + it('follows progress, stopping, and registration commits', async () => { + const ctx = await harness() + const alice = registerAgent(ctx, 'alice') + const job = startJob(ctx, { label: 'first', owner: alice.id, slowStop: true }) + const abort = new AbortController() + const iterator = streamJobRows(ctx.jobs, { sessionId: alice.id }, ROWS, abort.signal)[Symbol.asyncIterator]() + await next(iterator) + + job.progress('3/10') + expect((await next(iterator))?.jobs[0]).toMatchObject({ progress: '3/10' }) + ctx.jobs.visibleTo(alice.id).kill(job.id, { reason: 'enough' }) + expect((await next(iterator))?.jobs[0]).toMatchObject({ status: 'stopping', progress: '3/10' }) + startJob(ctx, { label: 'second', owner: alice.id }) + expect((await next(iterator))?.jobs.map(entry => entry.label)).toEqual(['first', 'second']) + abort.abort() + expect(await next(iterator)).toBeUndefined() + await job.settle({ status: 'killed' }) + }) + + it('drops an owner\'s rows when its lifecycle ends, keeping the unowned set', async () => { + const ctx = await harness() + const alice = registerAgent(ctx, 'alice') + startJob(ctx, { label: 'shared' }) + startJob(ctx, { label: 'mine', owner: alice.id }) + const abort = new AbortController() + const iterator = streamJobRows(ctx.jobs, { sessionId: alice.id }, ROWS, abort.signal)[Symbol.asyncIterator]() + expect((await next(iterator))?.jobs).toHaveLength(2) + + await alice.disposeScope() + // Teardown cancels, settles, and removes the owned job; the frames land in + // that order, and the last one holds the unowned job alone. + let frame = await next(iterator) + while (frame !== undefined && frame.jobs.length !== 1) frame = await next(iterator) + expect(frame?.jobs.map(job => job.label)).toEqual(['shared']) + abort.abort() + expect(await next(iterator)).toBeUndefined() + }) + + it('stops cleanly on abort while idle and refuses an already-aborted signal', async () => { + const ctx = await harness() + startJob(ctx, { label: 'idle' }) + const abort = new AbortController() + const iterator = streamJobRows(ctx.jobs, { sessionId: 'nobody' as never }, ROWS, abort.signal)[Symbol.asyncIterator]() + expect((await next(iterator))?.jobs.map(job => job.label)).toEqual(['idle']) + await wait(10) + abort.abort() + expect(await next(iterator)).toBeUndefined() + + const aborted = new AbortController() + aborted.abort() + const refused = streamJobRows(ctx.jobs, { sessionId: 'nobody' as never }, ROWS, aborted.signal)[Symbol.asyncIterator]() + await expect(refused.next()).rejects.toThrow() + }) +}) diff --git a/packages/api/job-controller/tsconfig.host.json b/packages/api/job-controller/tsconfig.host.json index 96de4dede2..4e5c8c3f01 100644 --- a/packages/api/job-controller/tsconfig.host.json +++ b/packages/api/job-controller/tsconfig.host.json @@ -8,12 +8,13 @@ "files": [ "src/index.ts", "src/observe.ts", - "src/types.ts" + "src/rows.ts", + "src/types.ts", + "src/wake.ts" ], "references": [ { "path": "../../../vendor/cordis" }, { "path": "../../../vendor/schemastery" }, - { "path": "../../core/agent" }, { "path": "../../core/session" }, { "path": "../../jobs/jobs" }, { "path": "../../typert/protocol" } From 84efac2c4297b84b00768eca3973787ed7146d75 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 17:00:51 +0800 Subject: [PATCH 036/100] refactor(ui-jobs): read rows and observations from ctx.jobs The header list watches its session's roster through ctx.jobs.watchRows while mounted and reads rows and observed views from one jobs snapshot. A row is expandable while the job is live or once it left retained output behind; it shows the live progress line or the terminal detail. The web e2e drivers kill through visibleTo(), and the client fixtures the roster removal missed drop their jobs baselines. --- apps/web/tests/background-job-list.e2e.ts | 2 +- apps/web/tests/live-job-stream.e2e.ts | 8 +- .../tests/client-apply.client.spec.ts | 2 +- .../tests/fake-api.client.ts | 1 - .../tests/projection-store.client.spec.ts | 2 +- .../tests/queue-store.client.spec.ts | 1 - .../tests/sessions-service.client.spec.ts | 2 +- packages/client/ui-jobs/README.i18n.yaml | 4 +- packages/client/ui-jobs/README.md | 19 ++- packages/client/ui-jobs/README.zh.md | 19 ++- packages/client/ui-jobs/package.json | 2 - .../ui-jobs/src/client/JobListAction.tsx | 81 +++++++----- packages/client/ui-jobs/src/client/index.ts | 17 ++- .../tests/browser-plugin.client.spec.ts | 25 ++-- .../tests/job-list-action.client.spec.tsx | 125 +++++++++++------- 15 files changed, 178 insertions(+), 132 deletions(-) diff --git a/apps/web/tests/background-job-list.e2e.ts b/apps/web/tests/background-job-list.e2e.ts index 96a7f4f833..5d881f59b4 100644 --- a/apps/web/tests/background-job-list.e2e.ts +++ b/apps/web/tests/background-job-list.e2e.ts @@ -111,7 +111,7 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => { expect(tripwire.warnings).toEqual([]) phase = 'settled' - expect(scaffold.ctx.jobs.kill(jobId, agent, 'web e2e cancellation')).toBe('requested') + expect(scaffold.ctx.jobs.visibleTo(agent.id).kill(jobId, { reason: 'web e2e cancellation' })).toBe('requested') const idle = page.getByRole('button', { name: '1 background job', exact: true }) await idle.waitFor({ timeout: 20_000 }) diff --git a/apps/web/tests/live-job-stream.e2e.ts b/apps/web/tests/live-job-stream.e2e.ts index 83736763c6..ccddae0ee2 100644 --- a/apps/web/tests/live-job-stream.e2e.ts +++ b/apps/web/tests/live-job-stream.e2e.ts @@ -1,5 +1,5 @@ // Session-header job list driven by a real background bash run: the job row -// arrives over the session control stream, expanding it opens the record +// arrives over the job roster stream, expanding it opens the output // observation stream, and the panel shows the process's real output while it // is still running. No model call is involved. import { readFile, writeFile } from 'node:fs/promises' @@ -99,11 +99,11 @@ describe.skipIf(MODE === 'record')('web e2e: live job stream', () => { if (matched === null) throw new Error(`background bash reported no job id: ${reported}`) const jobId = JobId(matched[0]) - // The job row reaches the header over the session control stream. + // The job row reaches the header over the job roster stream. await trigger.waitFor({ timeout: 15_000 }) await trigger.click() - // Expanding the row opens the record observation stream; the panel then renders + // Expanding the row opens the output observation stream; the panel then renders // the command's real stdout while the process is still running. const expand = page.getByRole('button', { name: /Show live output/ }) await expand.waitFor({ timeout: 10_000 }) @@ -116,7 +116,7 @@ describe.skipIf(MODE === 'record')('web e2e: live job stream', () => { expect(tripwire.warnings).toEqual([]) phase = 'settled' - expect(scaffold.ctx.jobs.kill(jobId, agent, 'web e2e cancellation')).toBe('requested') + expect(scaffold.ctx.jobs.visibleTo(agent.id).kill(jobId, { reason: 'web e2e cancellation' })).toBe('requested') // Settlement arrives on the observation stream itself, so the open panel // flips without any further interaction; the roster trigger follows. diff --git a/packages/api/session-controller/tests/client-apply.client.spec.ts b/packages/api/session-controller/tests/client-apply.client.spec.ts index 07f88b1a4f..29b435e3f9 100644 --- a/packages/api/session-controller/tests/client-apply.client.spec.ts +++ b/packages/api/session-controller/tests/client-apply.client.spec.ts @@ -150,7 +150,7 @@ describe('Session Controller Client apply', () => { expect(accept).toHaveBeenCalledWith({ type: 'baseline', - value: { queues: {}, jobs: {}, projections: {} }, + value: { queues: {}, projections: {} }, }) bench.api.failStreams(new RemoteStreamCarrierError('generation lost')) diff --git a/packages/api/session-controller/tests/fake-api.client.ts b/packages/api/session-controller/tests/fake-api.client.ts index e3ea48f783..14db19d4ce 100644 --- a/packages/api/session-controller/tests/fake-api.client.ts +++ b/packages/api/session-controller/tests/fake-api.client.ts @@ -155,7 +155,6 @@ export class FakeApiClient { followCursor: number | undefined controlBaseline: SessionControlBaseline = { queues: {}, - jobs: {}, projections: {}, } workspaceBaseline: Extract['value'] = { diff --git a/packages/api/session-controller/tests/projection-store.client.spec.ts b/packages/api/session-controller/tests/projection-store.client.spec.ts index 74f37c57cd..2dc1b98998 100644 --- a/packages/api/session-controller/tests/projection-store.client.spec.ts +++ b/packages/api/session-controller/tests/projection-store.client.spec.ts @@ -172,7 +172,7 @@ describe('manager frame routing', () => { manager.handleControlFrame({ type: 'baseline', value: { - queues: {}, jobs: {}, + queues: {}, projections: { [sid('s1')]: { asOfSeq: 2, values: {} } }, }, }) diff --git a/packages/api/session-controller/tests/queue-store.client.spec.ts b/packages/api/session-controller/tests/queue-store.client.spec.ts index 722a06b090..fd0f261c21 100644 --- a/packages/api/session-controller/tests/queue-store.client.spec.ts +++ b/packages/api/session-controller/tests/queue-store.client.spec.ts @@ -279,7 +279,6 @@ describe('manager buffering of queue snapshots', () => { type: 'baseline', value: { queues: { [SID]: nextQueue }, - jobs: {}, projections: {}, }, }) diff --git a/packages/api/session-controller/tests/sessions-service.client.spec.ts b/packages/api/session-controller/tests/sessions-service.client.spec.ts index c98ff399fb..5d3d040612 100644 --- a/packages/api/session-controller/tests/sessions-service.client.spec.ts +++ b/packages/api/session-controller/tests/sessions-service.client.spec.ts @@ -139,7 +139,7 @@ describe('scope tree', () => { b.svc.handleControlFrame({ type: 'baseline', - value: { queues: {}, jobs: {}, projections: {} }, + value: { queues: {}, projections: {} }, }) await Promise.resolve() expect(b.svc.resolveAgentScope(sid('s-early'))).toBe(scoped) diff --git a/packages/client/ui-jobs/README.i18n.yaml b/packages/client/ui-jobs/README.i18n.yaml index 7a5e54a34f..acc54648f7 100644 --- a/packages/client/ui-jobs/README.i18n.yaml +++ b/packages/client/ui-jobs/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-jobs/README.md -README.md: fe357b5555cdc2f7a94ea0a44e97c499652695d3 -README.zh.md: d23b96becc5b2598197f7720a355a37e5c8bf7cb +README.md: 697bb2dc488e11d3c92c061cc83fabeebeb366dc +README.zh.md: 3b05b5796fe366ce6e2f4cb389b758e8855483b7 diff --git a/packages/client/ui-jobs/README.md b/packages/client/ui-jobs/README.md index fe357b5555..697bb2dc48 100644 --- a/packages/client/ui-jobs/README.md +++ b/packages/client/ui-jobs/README.md @@ -1,5 +1,5 @@ --- -description: "The session-header background-job list: expandable streaming record panels, running/finished sections, and static rows for jobs without a record." +description: "The session-header background-job list: expandable streaming output panels, running/finished sections, and static rows for settled jobs without retained output." kind: "package-reference" --- @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -`dsh-client-ui-jobs` puts this session's background jobs in one header control. Every row carries the job's lifecycle, ticking duration, and model-visible `detail` from the `jobsBySession` mirror; a job that declared an observation record additionally offers an expandable panel that streams its real output while it runs. Collapsing stops the stream, so output only flows while someone is watching. Live rows lead with a ticking duration over a kind-and-status second line; settled rows compact behind a section heading; jobs without a record (subagent delegations, PTY sends) render as static rows with no expansion affordance. +`dsh-client-ui-jobs` puts this session's background jobs in one header control. Every row carries the job's lifecycle, ticking duration, and the model-visible progress line or terminal detail from the roster `ctx.jobs` keeps current; a live job, or a settled one that left retained output behind, additionally offers an expandable panel that streams its real output. Collapsing stops the stream, so output only flows while someone is watching. Live rows lead with the ticking duration and carry kind and status on a second line; settled rows fold after a section heading; a settled job that retained no output (a subagent, whose answer went to the model) renders as a static row. ## Table of Contents @@ -29,11 +29,11 @@ Load the plugin through the web-app manifest; it renders nothing until the sessi ### One row per job -The session control stream's `jobsBySession` mirror is the single roster: each `SessionJob` row carries lifecycle, duration, and the model-visible `detail`, and its `record` flag is present exactly when the job declared a record — that flag is what makes a row expandable. There is no second roster to join. +The `job.rows` stream `ctx.jobs` mirrors is the single roster: each `JobView` row carries lifecycle, duration, the live `progress` line or the terminal `detail`, and its retained byte count — a live job, or a settled one with retained output, is what makes a row expandable. There is no second roster to join. ### The expanded panel -Expanding an observable row opens that job's record observation stream from `ctx.jobOutput` (installed by `dsh-api-job-controller`) into an embedded terminal panel. The panel copies the command (not the output), wraps commands and output lines in full, scrolls its output inside a fixed height instead of folding, and draws no run-state dot of its own — the row above carries the state. Retention gaps and stream failures render as notices above the panel. +Expanding an observable row opens that job's output observation stream from `ctx.jobs` (installed by `dsh-api-job-controller`) into an embedded terminal panel. The panel copies the command (not the output), wraps commands and output lines in full, scrolls its output inside a fixed height instead of folding, and draws no run-state dot of its own — the row above carries the state. Retention gaps and stream interruptions render as notices above the panel. ----- @@ -43,7 +43,7 @@ Expanding an observable row opens that job's record observation stream from `ctx
        Implementation internals — click to expand -One slot entry in the header actions band (after the preset label, before the subagent catalog) renders the trigger and popover; the popover fits itself to the viewport by measuring its anchor. All data arrives through `ctx.jobOutput` and the standard `useSessions` hook — the component holds no transport state. Observation follows visibility: one `useEffect` opens the stream for the expanded row's job and closes it on collapse, unmount, or popover dismissal. +One slot entry in the header actions band (after the preset label, before the subagent catalog) renders the trigger and popover; the popover fits itself to the viewport by measuring its anchor. All data arrives through `ctx.jobs` — the component holds no transport state. The roster follows the mount: one `useEffect` keeps the session's `job.rows` stream open while the control lives. Observation follows visibility: another `useEffect` opens the stream for the expanded row's job and closes it on collapse, unmount, or popover close. | File | Role | |---|---| @@ -58,9 +58,8 @@ One slot entry in the header actions band (after the preset label, before the su ## Further Exploration -- [`dsh-api-job-controller`](../../api/job-controller/README.md) — the `job.observe` stream and the `ctx.jobOutput` service behind the panel. -- [`dsh-api-session-controller`](../../api/session-controller/README.md) — the `jobsBySession` roster mirror the rows come from. -- [`dsh-jobs`](../../jobs/jobs/README.md) — the registry contract that owns the record semantics. +- [`dsh-api-job-controller`](../../api/job-controller/README.md) — the `job.rows` and `job.observe` streams and the `ctx.jobs` service behind the rows and the panel. +- [`dsh-jobs`](../../jobs/jobs/README.md) — the registry contract that owns the ring and projection semantics. - [`dsh-client-ui-primitives`](../ui-primitives/README.md) — the `TerminalBlock` surface the panel configures. ----- @@ -80,7 +79,7 @@ None; the package never assembles or sends provider requests. These limits define current package constraints, not a task backlog. -- **No kill control** — cancellation stays with the model's `job_kill`; a human kill is blocked on the jobs `reported` contract question recorded in the [web job display Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md). +- **No kill control** — cancellation stays with the model's `job_kill`. - **Channel labels are not rendered** — stdout and stderr chunks concatenate into one stream; per-channel tinting is a presentation follow-up. @@ -93,4 +92,4 @@ None.
        -**Runtime invariant:** No companion is published. This package is a read-only projection of the `jobsBySession` mirror onto one header slot entry. It emits no cordis events, owns no cross-plugin mutable state, and its single slot registration proves disposal through the HMR-safety spec. +**Runtime invariant:** No companion is published. This package is a read-only projection of the `ctx.jobs` rosters and views onto one header slot entry. It emits no cordis events, owns no cross-plugin mutable state, and its single slot registration proves disposal through the HMR-safety spec. diff --git a/packages/client/ui-jobs/README.zh.md b/packages/client/ui-jobs/README.zh.md index d23b96becc..3b05b5796f 100644 --- a/packages/client/ui-jobs/README.zh.md +++ b/packages/client/ui-jobs/README.zh.md @@ -1,5 +1,5 @@ --- -description: "会话头部后台任务列表:可展开的流式 record 面板、进行中/已结束分组,以及无 record 任务的静态行。" +description: "会话头部后台任务列表:可展开的流式输出面板、进行中/已结束分组,以及无保留输出的已结束任务的静态行。" kind: "package-reference" --- @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -`dsh-client-ui-jobs` 把本会话的后台任务放进一个头部控件。每一行都携带 `jobsBySession` 镜像里该 job 的生命周期、跳动时长与模型可见的 `detail`;声明了观测 record 的 job 额外提供可展开的面板,在运行期间流式呈现其真实输出。收起即停流——只有有人在看时输出才流动。进行中的行以跳动时长为主行、kind 与状态为副行;已结束的行折叠在分组标题之后;没有 record 的 job(subagent 委托、PTY 发送)渲染为无展开操作的静态行。 +`dsh-client-ui-jobs` 把本会话的后台任务放进一个头部控件。每一行都携带 `ctx.jobs` 保持最新的名册里该 job 的生命周期、跳动时长与模型可见的进度行或终态 detail;进行中的 job,或结算后仍留有保留输出的 job,额外提供可展开的面板,流式呈现其真实输出。收起即停流——只有有人在看时输出才流动。进行中的行以跳动时长为主行、kind 与状态为副行;已结束的行折叠在分组标题之后;没有保留输出的已结束 job(subagent,其回答已交给模型)渲染为静态行。 ## 目录 @@ -29,11 +29,11 @@ kind: "package-reference" ### 一 job 一行 -session control 流的 `jobsBySession` 镜像是唯一名册:每个 `SessionJob` 行携带生命周期、时长与模型可见的 `detail`,其 `record` 标志恰在 job 声明了 record 时存在——这个标志就是行可展开的依据。不存在需要 join 的第二份名册。 +`ctx.jobs` 镜像的 `job.rows` 流是唯一名册:每个 `JobView` 行携带生命周期、时长、实时 `progress` 行或终态 `detail`,以及其保留字节数——进行中的 job,或留有保留输出的已结束 job,就是行可展开的依据。不存在需要 join 的第二份名册。 ### 展开的面板 -展开可观察的行会从 `ctx.jobOutput`(由 `dsh-api-job-controller` 安装)打开该 job 的 record 观测流,注入内嵌终端面板。面板复制的是命令(不是输出),命令与输出行完整换行,输出在固定高度内滚动而非折叠,且不绘制自己的运行状态点——上方的行承载状态。保留缺口与流中断在面板上方渲染为提示。 +展开可观察的行会从 `ctx.jobs`(由 `dsh-api-job-controller` 安装)打开该 job 的输出观测流,注入内嵌终端面板。面板复制的是命令(不是输出),命令与输出行完整换行,输出在固定高度内滚动而非折叠,且不绘制自己的运行状态点——上方的行承载状态。保留缺口与流中断在面板上方渲染为提示。 ----- @@ -43,7 +43,7 @@ session control 流的 `jobsBySession` 镜像是唯一名册:每个 `SessionJo
        实现内幕——点击展开 -头部操作带里的一个 slot 条目(preset 标签之后、subagent 目录之前)渲染触发器与弹出层;弹出层通过测量锚点把自己收进视口。所有数据经 `ctx.jobOutput` 与标准 `useSessions` hook 到达——组件不持有任何传输状态。观测跟随可见性:一个 `useEffect` 为展开行的 job 打开流,并在收起、卸载或弹出层关闭时关闭它。 +头部操作带里的一个 slot 条目(preset 标签之后、subagent 目录之前)渲染触发器与弹出层;弹出层通过测量锚点把自己收进视口。所有数据经 `ctx.jobs` 到达——组件不持有任何传输状态。名册跟随挂载:一个 `useEffect` 在控件存活期间保持会话的 `job.rows` 流打开。观测跟随可见性:另一个 `useEffect` 为展开行的 job 打开流,并在收起、卸载或弹出层关闭时关闭它。 | 文件 | 角色 | |---|---| @@ -58,9 +58,8 @@ session control 流的 `jobsBySession` 镜像是唯一名册:每个 `SessionJo ## 进一步探索 -- [`dsh-api-job-controller`](../../api/job-controller/README.zh.md) —— 面板背后的 `job.observe` 流与 `ctx.jobOutput` 服务。 -- [`dsh-api-session-controller`](../../api/session-controller/README.zh.md) —— 行所来自的 `jobsBySession` 名册镜像。 -- [`dsh-jobs`](../../jobs/jobs/README.zh.md) —— 拥有 record 语义的注册表契约。 +- [`dsh-api-job-controller`](../../api/job-controller/README.zh.md) —— 行与面板背后的 `job.rows`、`job.observe` 流与 `ctx.jobs` 服务。 +- [`dsh-jobs`](../../jobs/jobs/README.zh.md) —— 拥有环与投影语义的注册表契约。 - [`dsh-client-ui-primitives`](../ui-primitives/README.zh.md) —— 面板所配置的 `TerminalBlock` 表面。 ----- @@ -80,7 +79,7 @@ session control 流的 `jobsBySession` 镜像是唯一名册:每个 `SessionJo 这些限制界定当前包约束,不是任务清单。 -- **没有 kill 控件**——取消仍归模型的 `job_kill`;人工 kill 卡在 [web 任务显示 Agent Note](../../../.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md) 记录的 jobs `reported` 契约问题上。 +- **没有 kill 控件**——取消仍归模型的 `job_kill`。 - **不渲染 channel 标签**——stdout 与 stderr 块拼接为一条流;按 channel 着色是展示层的后续工作。 @@ -93,4 +92,4 @@ session control 流的 `jobsBySession` 镜像是唯一名册:每个 `SessionJo
        -**运行时不变式:** 不发布伴生入口。本包只把 `jobsBySession` mirror 只读投影到一个 header slot,不发出 Cordis 事件,也不持有跨插件可变状态。 +**运行时不变式:** 不发布伴生入口。本包只把 `ctx.jobs` 的名册与视图只读投影到一个 header slot,不发出 Cordis 事件,也不持有跨插件可变状态。 diff --git a/packages/client/ui-jobs/package.json b/packages/client/ui-jobs/package.json index 27ab997467..92f29f2db1 100644 --- a/packages/client/ui-jobs/package.json +++ b/packages/client/ui-jobs/package.json @@ -36,7 +36,6 @@ "devDependencies": { "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-api-job-controller": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", "@deepseek-ai/dsh-client-locale": "workspace:^", "@deepseek-ai/dsh-client-test-runtime": "workspace:^", "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", @@ -57,7 +56,6 @@ "client": { "inject": [ "@deepseek-ai/dsh-api-job-controller", - "@deepseek-ai/dsh-api-session-controller", "@deepseek-ai/dsh-client-locale", "@deepseek-ai/dsh-client-ui-conversation", "@deepseek-ai/dsh-client-ui-primitives" diff --git a/packages/client/ui-jobs/src/client/JobListAction.tsx b/packages/client/ui-jobs/src/client/JobListAction.tsx index bf369c9949..c7af7fe160 100644 --- a/packages/client/ui-jobs/src/client/JobListAction.tsx +++ b/packages/client/ui-jobs/src/client/JobListAction.tsx @@ -1,6 +1,5 @@ import { useEffect, useLayoutEffect, useMemo, useRef, useState, type KeyboardEvent } from 'react' -import type { JobOutputSnapshot, ObservedJob } from '@deepseek-ai/dsh-api-job-controller/client' -import type { SessionJob } from '@deepseek-ai/dsh-api-session-controller/types' +import type { JobsSnapshot, JobView, ObservedJob } from '@deepseek-ai/dsh-api-job-controller/client' import type { SessionId } from '@deepseek-ai/dsh-session/types' import { IconChevronDownOutline14, StateDot, TerminalBlock, useDismissOnOutsidePointer, @@ -14,17 +13,22 @@ import css from './JobListAction.module.css' /** Registration-side business face for the job list. */ export interface JobListInjected { hooks: { - /** Client job-output snapshot bound by the renderer as useJobOutput. */ - jobOutput: { - getSnapshot(): JobOutputSnapshot + /** Client jobs snapshot (rosters and observations) bound by the renderer as useJobs. */ + jobs: { + getSnapshot(): JobsSnapshot subscribe(listener: () => void): () => void } } /** - * Start observing one job's live record; returns the stop function. + * Keep one session's roster current while the list is mounted; returns the + * stop function. Reference-counted by the client service. + */ + watchRows: (sessionId: SessionId) => () => void + /** + * Start observing one job's live output; returns the stop function. * Reference-counted by the client service, so panels can overlap safely. */ - observe: (sessionId: SessionId | undefined, id: SessionJob['id']) => () => void + observe: (sessionId: SessionId | undefined, id: JobView['id']) => () => void } /** Full props for the session-header job-list action. */ @@ -34,19 +38,27 @@ export type JobListActionProps = & InjectFace /** Stable empty list so a session with no jobs keeps one array identity. */ -const NO_JOBS: readonly SessionJob[] = [] +const NO_JOBS: readonly JobView[] = [] /** Minimum gap kept between the popover and the viewport edges (the Menu primitive's portal margin). */ const VIEWPORT_MARGIN = 12 -function isLive(job: SessionJob): boolean { +function isLive(job: JobView): boolean { return job.status === 'running' || job.status === 'stopping' } -/** True exactly when the job declared an observation record. */ -function isObservable(job: SessionJob): boolean { - return job.record === true +/** + * Whether the row offers an output panel: every live job (its output may + * still arrive) and a settled one that left retained output behind. + */ +function isObservable(job: JobView): boolean { + return isLive(job) || job.output.total > 0 +} + +/** The one-line qualifier beside the status: live progress while running, the terminal reason once settled. */ +function jobDetail(job: JobView): string | undefined { + return job.progress ?? job.detail } /** Closed-union exhaustiveness fence for the wire status set. */ @@ -59,7 +71,7 @@ function assertNever(value: never): never { * Status marker semantics. `stopping` and `killed` share the attention color: * both mean the work ended (or is ending) on request rather than on its own. */ -function dotState(status: SessionJob['status']): StateDotState { +function dotState(status: JobView['status']): StateDotState { switch (status) { case 'running': return 'ongoing' case 'stopping': return 'warning' @@ -71,7 +83,7 @@ function dotState(status: SessionJob['status']): StateDotState { } } -function statusLabel(status: SessionJob['status'], t: TranslateNS): string { +function statusLabel(status: JobView['status'], t: TranslateNS): string { switch (status) { case 'running': return t('status.running') case 'stopping': return t('status.stopping') @@ -130,7 +142,7 @@ function terminalLabels(t: TranslateNS): TerminalBlockLabels { * that settled in the same millisecond fall back to start order, so the sort * never depends on the host's map iteration. */ -function ordered(jobs: readonly SessionJob[]): SessionJob[] { +function ordered(jobs: readonly JobView[]): JobView[] { return [...jobs].sort((left, right) => { const liveLeft = isLive(left) if (liveLeft !== isLive(right)) return liveLeft ? -1 : 1 @@ -142,7 +154,7 @@ function ordered(jobs: readonly SessionJob[]): SessionJob[] { /** One job row plus, when observable and expanded, its live output panel. */ function JobItem({ job, view, expanded, now, onToggle, t }: { - job: SessionJob + job: JobView view: ObservedJob | undefined expanded: boolean /** Clock sample live rows derive their running duration from. */ @@ -152,6 +164,7 @@ function JobItem({ job, view, expanded, now, onToggle, t }: { }) { const live = isLive(job) const status = statusLabel(job.status, t) + const detail = jobDetail(job) const observable = isObservable(job) const labels = useMemo(() => terminalLabels(t), [t]) const elapsed = live ? now - job.startedAt : (job.finishedAt ?? job.startedAt) - job.startedAt @@ -175,10 +188,11 @@ function JobItem({ job, view, expanded, now, onToggle, t }: {
        {job.kind} - {job.detail ?? status} + {detail ?? status} - {observable ? : null} + {/* A live row is always observable: its output may still arrive. */} + ) : ( @@ -186,7 +200,7 @@ function JobItem({ job, view, expanded, now, onToggle, t }: { {job.kind} {job.label} - {job.detail ?? status} + {detail ?? status} {durationCell} {observable ? : null} @@ -206,7 +220,7 @@ function JobItem({ job, view, expanded, now, onToggle, t }: { ) : ( - + {body} )} @@ -237,18 +251,19 @@ function JobItem({ job, view, expanded, now, onToggle, t }: { } /** - * Session-header entry point for this session's background jobs. It renders - * nothing at all until the session can see at least one job; expanding an - * observable row (a job that declared a record) starts its observation - * stream, and collapsing (or closing the popover) stops it — output only - * flows while someone is watching. - * @param props - runtime slot currency, the session and job-output snapshot - * hooks, the observation control, and the namespace translator. + * Session-header entry point for this session's background jobs. Mounting it + * keeps the session's roster stream open; it renders nothing at all until the + * session can see at least one job. Expanding an observable row (a live job, + * or a settled one with retained output) starts its observation stream, and + * collapsing (or closing the popover) stops it — output only flows while + * someone is watching. + * @param props - runtime slot currency, the jobs snapshot hook, the roster + * and observation controls, and the namespace translator. * @returns the trigger and its popover list, or null when there is nothing to show. */ -export function JobListAction({ sessionId, useSessions, useJobOutput, observe, t }: JobListActionProps) { - const jobs = useSessions(state => state.jobsBySession[sessionId]) ?? NO_JOBS - const observedViews = useJobOutput(state => state.observed) +export function JobListAction({ sessionId, useJobs, watchRows, observe, t }: JobListActionProps) { + const jobs = useJobs(state => state.rows[sessionId]) ?? NO_JOBS + const observedViews = useJobs(state => state.observed) const [open, setOpen] = useState(false) const [expandedKey, setExpandedKey] = useState(undefined) const [now, setNow] = useState(() => Date.now()) @@ -265,6 +280,10 @@ export function JobListAction({ sessionId, useSessions, useJobOutput, observe, t useDismissOnOutsidePointer(rootRef, open, setOpen) + // The roster follows the mounted session: one stream while this control + // lives, released with it. + useEffect(() => watchRows(sessionId), [sessionId, watchRows]) + // The clock only runs while an open list is showing something that moves. useEffect(() => { if (!open || liveRows.length === 0) return @@ -337,7 +356,7 @@ export function JobListAction({ sessionId, useSessions, useJobOutput, observe, t triggerRef.current?.focus() } - const item = (job: SessionJob) => ( + const item = (job: JobView) => ( ({ - hooks: { jobOutput: ctx.jobOutput.state }, - observe: (sessionId, id) => ctx.jobOutput.observe(sessionId, id), + hooks: { jobs: ctx.jobs.state }, + watchRows: sessionId => ctx.jobs.watchRows(sessionId), + observe: (sessionId, id) => ctx.jobs.observe(sessionId, id), }), }, JobListAction), ) diff --git a/packages/client/ui-jobs/tests/browser-plugin.client.spec.ts b/packages/client/ui-jobs/tests/browser-plugin.client.spec.ts index 91a9521ca7..2c70dfe40f 100644 --- a/packages/client/ui-jobs/tests/browser-plugin.client.spec.ts +++ b/packages/client/ui-jobs/tests/browser-plugin.client.spec.ts @@ -19,8 +19,10 @@ function headerEntryIds(ctx: Context): (string | undefined)[] { .map(entry => entry.options.id) } -/** Observation requests handed to the stubbed job-output control. */ +/** Observation requests handed to the stubbed jobs service. */ const observed: [string | undefined, string][] = [] +/** Roster watches handed to the stubbed jobs service. */ +const watched: string[] = [] /** Boot the browser half over a real slot tree that declares the header list. */ async function bench(): Promise<{ ctx: Context; fiber: ReturnType }> { @@ -32,9 +34,12 @@ async function bench(): Promise<{ ctx: Context; fiber: ReturnType null) - ctx.provide('sessions', {} as never) - ctx.provide('jobOutput', { - state: { getSnapshot: () => ({ observed: {} }), subscribe: () => () => {} }, + ctx.provide('jobs', { + state: { getSnapshot: () => ({ rows: {}, observed: {} }), subscribe: () => () => {} }, + watchRows: (sessionId: string) => { + watched.push(sessionId) + return () => {} + }, observe: (sessionId: string | undefined, id: string) => { observed.push([sessionId, id]) return () => {} @@ -57,21 +62,25 @@ async function bench(): Promise<{ ctx: Context; fiber: ReturnType { it('declares the services it binds', () => { - expect(inject).toEqual(['sessions', 'jobOutput', 'slots', 'locale']) + expect(inject).toEqual(['jobs', 'slots', 'locale']) }) - it('exposes the output source and observation control through the inject face', async () => { + it('exposes the jobs source and the roster and observation controls through the inject face', async () => { const { ctx } = await bench() const entry = ctx.slots .entries('conversation.session.header.actions') .find(candidate => candidate.options.id === 'job-list') const face = (entry as unknown as { inject: () => { - hooks: { jobOutput: unknown } + hooks: { jobs: unknown } + watchRows: (sessionId: string) => () => void observe: (sessionId: string | undefined, id: string) => () => void } }).inject() - expect(face.hooks.jobOutput).toBeDefined() + expect(face.hooks.jobs).toBeDefined() + const release = face.watchRows('session') + expect(watched).toEqual(['session']) + release() const stopper = face.observe('session', 'bash-1') expect(observed).toEqual([['session', 'bash-1']]) stopper() diff --git a/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx b/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx index 9a8b9a1edc..a16a00c76f 100644 --- a/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx +++ b/packages/client/ui-jobs/tests/job-list-action.client.spec.tsx @@ -2,8 +2,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest' import { act, cleanup, fireEvent, render, screen, within } from '@testing-library/react' import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime' -import type { JobOutputSnapshot, ObservedJob } from '@deepseek-ai/dsh-api-job-controller/client' -import type { SessionJob } from '@deepseek-ai/dsh-api-session-controller/types' +import type { JobsSnapshot, JobView, ObservedJob } from '@deepseek-ai/dsh-api-job-controller/client' import type { SessionId } from '@deepseek-ai/dsh-session/types' import { JobListAction, type JobListActionProps } from '../src/client/JobListAction.tsx' import { zh } from '../src/client/locales.ts' @@ -17,36 +16,35 @@ afterEach(() => { const SESSION = 'session' as SessionId const t: JobListActionProps['t'] = makeTranslate(zh) -function job(over: Partial = {}): SessionJob { +/** A running job with nothing retained yet. */ +function job(over: Partial = {}): JobView { return { - id: 'bash-1' as SessionJob['id'], + id: 'bash-1' as JobView['id'], kind: 'bash', label: 'pnpm run build', status: 'running', startedAt: 1_700_000_000_000, + output: { total: 0, earliest: 0 }, ...over, } } -/** A job that declared an observation record, so its row offers a panel. */ -function recordJob(over: Partial = {}): SessionJob { - return job({ record: true, ...over }) +/** A job that left retained output behind, so its row offers a panel even once settled. */ +function outputJob(over: Partial = {}): JobView { + return job({ output: { total: 12, earliest: 0 }, ...over }) } function props( - jobs: readonly SessionJob[], + jobs: readonly JobView[], observe: JobListActionProps['observe'] = () => () => {}, observed: Readonly> = {}, + watchRows: JobListActionProps['watchRows'] = () => () => {}, ): JobListActionProps { - const outputState: JobOutputSnapshot = { observed } - function useJobOutput(select: (value: JobOutputSnapshot) => T): T { - return select(outputState) + const jobsState: JobsSnapshot = { rows: jobs.length > 0 ? { [SESSION]: jobs } : {}, observed } + function useJobs(select: (value: JobsSnapshot) => T): T { + return select(jobsState) } - const sessionsState = { jobsBySession: jobs.length > 0 ? { [SESSION]: jobs } : {} } - function useSessions(select: (value: typeof sessionsState) => T): T { - return select(sessionsState) - } - return { sessionId: SESSION, useSessions, useJobOutput, observe, t } as unknown as JobListActionProps + return { sessionId: SESSION, useJobs, watchRows, observe, t } as unknown as JobListActionProps } function openList(): void { @@ -59,10 +57,20 @@ describe('JobListAction visibility', () => { expect(container.innerHTML).toBe('') }) + it('watches the session roster while mounted and releases it on unmount', () => { + const stop = vi.fn() + const watchRows = vi.fn(() => stop) + const { unmount } = render() + expect(watchRows).toHaveBeenCalledWith(SESSION) + expect(stop).not.toHaveBeenCalled() + unmount() + expect(stop).toHaveBeenCalledTimes(1) + }) + it('counts live jobs on the trigger', () => { render() expect(screen.getByRole('button', { name: '2 个后台任务运行中' })).toBeDefined() }) @@ -76,18 +84,24 @@ describe('JobListAction visibility', () => { }) describe('JobListAction rows', () => { - it('renders a record-less job row without expansion affordances', () => { + it('renders a settled job without retained output as a static row', () => { render() - expect(screen.getByRole('button', { name: '1 个后台任务运行中' })).toBeDefined() + expect(screen.getByRole('button', { name: '1 个后台任务' })).toBeDefined() openList() expect(screen.getByText('explore the repo')).toBeDefined() expect(screen.queryByRole('button', { name: zh['row.expandAria'].replace('{label}', 'explore the repo') })).toBeNull() }) - it('shows the live detail line in place of the status word', () => { - render() + it('offers a panel on a live row before any output arrived', () => { + render() + openList() + expect(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'warming up') })).toBeDefined() + }) + + it('shows the live progress line in place of the status word', () => { + render() openList() const list = screen.getByRole('list', { name: zh['list.aria'] }) expect(within(list).getAllByRole('listitem')).toHaveLength(1) @@ -96,7 +110,7 @@ describe('JobListAction rows', () => { }) it('labels each non-empty section and drops the heading of an empty one', () => { - const settled = [job({ id: 'bash-2' as SessionJob['id'], status: 'completed', finishedAt: 1_700_000_012_000 })] + const settled = [job({ id: 'bash-2' as JobView['id'], status: 'completed', finishedAt: 1_700_000_012_000 })] const { rerender } = render() openList() expect(screen.getByText(zh['section.live'])).toBeDefined() @@ -111,9 +125,9 @@ describe('JobListAction rows', () => { vi.useFakeTimers({ now: 1_700_000_020_000 }) render() openList() expect(screen.getByText('5秒')).toBeDefined() @@ -124,10 +138,10 @@ describe('JobListAction rows', () => { expect(screen.getByText('6秒')).toBeDefined() }) - it('lists rows with kind, label, and detail-or-status', () => { + it('lists rows with kind, label, and progress, terminal detail, or status', () => { render() openList() const list = screen.getByRole('list', { name: zh['list.aria'] }) @@ -139,9 +153,9 @@ describe('JobListAction rows', () => { }) it('orders live rows first by start and settled rows newest-first with tie-breaks', () => { - const settled = (id: string, label: string, startedAt: number, finishedAt?: number): SessionJob => + const settled = (id: string, label: string, startedAt: number, finishedAt?: number): JobView => job({ - id: id as SessionJob['id'], + id: id as JobView['id'], label, status: 'completed', startedAt, @@ -153,8 +167,8 @@ describe('JobListAction rows', () => { settled('bash-b', 'settled-b', 90), settled('bash-e', 'settled-e', 95, 50), settled('bash-d', 'settled-d', 10, 200), - job({ id: 'bash-l1' as SessionJob['id'], label: 'live-1', startedAt: 5 }), - job({ id: 'bash-l2' as SessionJob['id'], label: 'live-2', startedAt: 3 }), + job({ id: 'bash-l1' as JobView['id'], label: 'live-1', startedAt: 5 }), + job({ id: 'bash-l2' as JobView['id'], label: 'live-2', startedAt: 3 }), ])} />) openList() const labels = within(screen.getByRole('list', { name: zh['list.aria'] })) @@ -173,14 +187,13 @@ describe('JobListAction observation', () => { Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } }) const lines = Array.from({ length: 24 }, (_value, index) => `line ${index + 1}`).join('\n') const view: ObservedJob = { - jobId: 'bash-1' as SessionJob['id'], + jobId: 'bash-1' as JobView['id'], text: lines, gapBefore: false, - status: 'killed', streaming: false, } render() @@ -204,7 +217,7 @@ describe('JobListAction observation', () => { const originalWidth = window.innerWidth Object.defineProperty(window, 'innerWidth', { value: 700, configurable: true, writable: true }) try { - render() + render() openList() const menu = screen.getByRole('list', { name: zh['list.aria'] }) // 700 - 12 - 440 - 344 = -96: the popover moves left to keep the margin. @@ -225,7 +238,7 @@ describe('JobListAction observation', () => { const originalWidth = window.innerWidth Object.defineProperty(window, 'innerWidth', { value: 700, configurable: true, writable: true }) try { - render() + render() openList() const menu = screen.getByRole('list', { name: zh['list.aria'] }) // max(12 - 4, min(0, 700 - 12 - 800 - 4)) = 8: clamped at the left margin. @@ -237,8 +250,8 @@ describe('JobListAction observation', () => { it('ignores other keys while open and closes once the roster empties', () => { const settledPair = [ - recordJob({ id: 'bash-1' as SessionJob['id'], status: 'completed', finishedAt: 2 }), - recordJob({ id: 'bash-2' as SessionJob['id'], status: 'completed', finishedAt: 3 }), + outputJob({ id: 'bash-1' as JobView['id'], status: 'completed', finishedAt: 2 }), + outputJob({ id: 'bash-2' as JobView['id'], status: 'completed', finishedAt: 3 }), ] const { rerender } = render() expect(screen.getByRole('button', { name: '2 个后台任务' })).toBeDefined() @@ -255,13 +268,12 @@ describe('JobListAction observation', () => { const stop = vi.fn() const observe = vi.fn(() => stop) const view: ObservedJob = { - jobId: 'bash-1' as SessionJob['id'], + jobId: 'bash-1' as JobView['id'], text: 'compiling…\n', gapBefore: false, - status: 'running', streaming: true, } - render() + render() openList() fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) expect(observe).toHaveBeenCalledWith(SESSION, 'bash-1') @@ -271,16 +283,29 @@ describe('JobListAction observation', () => { expect(stop).toHaveBeenCalledTimes(1) }) + it('renders a running panel with the prompt alone for a live row whose output has not arrived', () => { + const view: ObservedJob = { + jobId: 'bash-1' as JobView['id'], + text: '', + gapBefore: false, + streaming: true, + } + const { container } = render() + openList() + fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) + expect(container.querySelector('[data-running]')).not.toBeNull() + expect(screen.queryByText(zh['terminal.noOutput'])).toBeNull() + }) + it('surfaces retention gaps and stream failures above the panel', () => { const view: ObservedJob = { - jobId: 'bash-1' as SessionJob['id'], + jobId: 'bash-1' as JobView['id'], text: 'tail only', gapBefore: true, - status: 'running', streaming: false, error: 'connection lost', } - render() + render() openList() fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) expect(screen.getByText(zh['output.gap'])).toBeDefined() @@ -289,7 +314,7 @@ describe('JobListAction observation', () => { it('stops observation when the popover closes via Escape', () => { const stop = vi.fn() - render( stop)} />) + render( stop)} />) openList() fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) fireEvent.keyDown(screen.getByRole('list', { name: zh['list.aria'] }), { key: 'Escape' }) @@ -301,10 +326,10 @@ describe('JobListAction observation', () => { const stop = vi.fn() // One stable observe identity across renders, as the inject face provides. const observe = () => stop - const { rerender } = render() + const { rerender } = render() openList() fireEvent.click(screen.getByRole('button', { name: zh['row.expandAria'].replace('{label}', 'pnpm run build') })) - rerender() + rerender() expect(stop).toHaveBeenCalledTimes(1) expect(screen.queryByRole('button', { name: zh['row.collapseAria'].replace('{label}', 'other') })).toBeNull() }) From cbb0ec0296a0b6597aef81b5e8de8a846d4e144a Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Thu, 3 Sep 2026 17:15:07 +0800 Subject: [PATCH 037/100] docs(jobs): describe the consolidated seam - docs/subsystems/jobs.md (+zh) records JobSpec, JobHandle, JobHooks, JobOutcome, the pull-source types, JobChunk, JobOutputRead, JobView, JobRead, VisibleJobs, and the event types as type-equivalence blocks; the manifest and the cordis catalog link map follow - the jobs, jobs-local, and tool-jobs READMEs (+zh) describe the ring, the caller-bound view, the event stream, and the notice ledger; the architecture table and the adding-a-tool cookbook drop record: true and readOutput - Agent Note 2026-09-03-jobs-seam-consolidation owns the decision; the 2026-09-01 record note and the 2026-08-08 web display note carry Superseded pointers and the display note links the rows spec - regenerated catalogs (cordis, api, inspect, client, tool, config, persistence, doc graphs, module graph) with their Chinese mirrors; the cordis catalog drops the jobOutput exemption and the tool catalog mounts the agent registry for tool-jobs; the client model imports JobView from its leaf so the typert analyzer resolves it --- ...9-01-jobs-absorb-activity-record.i18n.yaml | 4 +- .../2026-09-01-jobs-absorb-activity-record.md | 2 + ...26-09-01-jobs-absorb-activity-record.zh.md | 2 + ...26-09-03-jobs-seam-consolidation.i18n.yaml | 6 + .../2026-09-03-jobs-seam-consolidation.md | 33 ++ .../2026-09-03-jobs-seam-consolidation.zh.md | 33 ++ ...08-08-web-background-job-display.i18n.yaml | 4 +- .../2026-08-08-web-background-job-display.md | 4 +- ...026-08-08-web-background-job-display.zh.md | 4 +- docs/architecture.i18n.yaml | 4 +- docs/architecture.md | 2 +- docs/architecture.zh.md | 2 +- docs/config-catalog.i18n.yaml | 4 +- docs/config-catalog.md | 28 +- docs/config-catalog.zh.md | 28 +- docs/cookbook/adding-a-tool.i18n.yaml | 4 +- docs/cookbook/adding-a-tool.md | 2 +- docs/cookbook/adding-a-tool.zh.md | 2 +- docs/event-producer-consumer.i18n.yaml | 4 +- docs/event-producer-consumer.md | 10 +- docs/event-producer-consumer.zh.md | 10 +- docs/module-graph.i18n.yaml | 4 +- docs/module-graph.md | 3 +- docs/module-graph.zh.md | 3 +- docs/persistence-catalog.i18n.yaml | 4 +- docs/persistence-catalog.md | 2 +- docs/persistence-catalog.zh.md | 2 +- docs/subsystems/jobs.i18n.yaml | 4 +- docs/subsystems/jobs.md | 552 +++++++++--------- docs/subsystems/jobs.zh.md | 552 +++++++++--------- docs/tool-catalog.i18n.yaml | 4 +- docs/tool-catalog.md | 2 +- docs/tool-catalog.zh.md | 2 +- .../api/job-controller/src/client/model.ts | 3 +- .../extensions/tool-cordis/src/api-catalog.ts | 179 +++--- packages/jobs/jobs-local/README.i18n.yaml | 4 +- packages/jobs/jobs-local/README.md | 28 +- packages/jobs/jobs-local/README.zh.md | 28 +- packages/jobs/jobs-local/src/events.ts | 2 + packages/jobs/jobs/README.i18n.yaml | 4 +- packages/jobs/jobs/README.md | 25 +- packages/jobs/jobs/README.zh.md | 25 +- packages/jobs/tool-jobs/README.i18n.yaml | 4 +- packages/jobs/tool-jobs/README.md | 17 +- packages/jobs/tool-jobs/README.zh.md | 17 +- pnpm-lock.yaml | 3 - scripts/gen-cordis-catalog.ts | 31 +- scripts/gen-tool-catalog.ts | 3 +- scripts/type-equiv.manifest.json | 50 +- 49 files changed, 929 insertions(+), 820 deletions(-) create mode 100644 .agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.i18n.yaml create mode 100644 .agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.md create mode 100644 .agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.zh.md diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml index e895f7c65b..491a988b1f 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.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 .agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md -2026-09-01-jobs-absorb-activity-record.md: 2f2bf7a65b5c26c80ec7ddc307c0f31a87f4de54 -2026-09-01-jobs-absorb-activity-record.zh.md: ed62a04e8f9da9de35bd721cceee3a2e56644cdb +2026-09-01-jobs-absorb-activity-record.md: a1da1ba6f47dd0f5d557542d6b9668d6723fd683 +2026-09-01-jobs-absorb-activity-record.zh.md: fd735f1d9764dc83c0469209e241d47176584f5a diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md index 2f2bf7a65b..a1da1ba6f4 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.md @@ -2,6 +2,8 @@ Status: implemented +Superseded: the record declaration (`JobStart.record`, `RecordingJob`, `readRecord`, `pumpJobOutput`) and the split wire (`SessionJob.record` on the session control stream, `ctx.jobOutput`) described below were consolidated into one output ring, `VisibleJobs`, and `ctx.jobs` — see [the jobs seam consolidation](2026-09-03-jobs-seam-consolidation.md). The argument for absorbing the standalone activity seam into `ctx.jobs` still holds. + English | [中文](2026-09-01-jobs-absorb-activity-record.zh.md) ## Problem diff --git a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md index ed62a04e8f..fd735f1d97 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-01-jobs-absorb-activity-record.zh.md @@ -2,6 +2,8 @@ Status: implemented +Superseded:下文描述的 record 声明(`JobStart.record`、`RecordingJob`、`readRecord`、`pumpJobOutput`)与拆分的线路(会话控制流上的 `SessionJob.record`、`ctx.jobOutput`)已收敛为一个输出环、`VisibleJobs` 与 `ctx.jobs`——见 [jobs seam 收敛](2026-09-03-jobs-seam-consolidation.zh.md)。把独立 activity seam 吸收进 `ctx.jobs` 的论证仍然成立。 + [English](2026-09-01-jobs-absorb-activity-record.md) | 中文 ## 问题 diff --git a/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.i18n.yaml new file mode 100644 index 0000000000..c8e9b6a942 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.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 .agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.md +2026-09-03-jobs-seam-consolidation.md: cae6463cee7a2e2a07f66baf759247aaef2afef9 +2026-09-03-jobs-seam-consolidation.zh.md: e87cf61d32e49f74b33e53bf246ccbc64b403baa diff --git a/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.md b/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.md new file mode 100644 index 0000000000..cae6463cee --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.md @@ -0,0 +1,33 @@ +# Agent Note: One output ring, one projection, one event stream for background jobs + +Status: implemented + +English | [中文](2026-09-03-jobs-seam-consolidation.zh.md) + +## Problem + +The job seam had grown by accretion. Producers declared their output twice — a consuming `readOutput` hook the model read and an optional `record: true` ring observers read — and the registry kept two vocabularies for one job (`JobSnapshot` for the model, `SessionJob` on the session control stream, `JobWireChunk` on the observation wire). Three listener families (`onJobDone`, `onJobsChanged`, `onOutput`) delivered overlapping facts with different owner filters, and the registry itself tracked `reported`, a bit that only the model-facing tool could interpret. Review of the merged design called the interface layer the weakest part: a reader could not tell which of `read`, `readRecord`, `JobStart`, `RecordingJob`, and `updateDetail` was the contract and which was an accident of history. + +## Decision + +- **One ring per job.** `JobSpec` replaces `JobStart`: a spec names optional pull `output` sources (`JobOutputSource`, the subprocess `readFrom` family) that the registry pumps at its own cadence (`pumpPollMs` on `dsh-jobs-local`), and every producer receives a `JobHandle` whose `append` pushes chunks into the same ring. The model's consuming read and every observer's absolute-offset read serve the same bytes; `readOutput` and the `record` discriminator are gone. Shell producers hand the registry their `observed` offset readers and fold sandbox facts into the terminal `detail`; the terminal producer adapts its consuming send reader through a byte-counting source; the subagent returns its answer as `JobOutcome.result`, which the first read after settlement carries once. +- **Two cursors, one storage.** `VisibleJobs.read(id)` is the stateful model cursor; `VisibleJobs.readAt(id, from)` is the stateless observer read. Model reads exclude `log` chunks (producer narration for observers) and render stdout, then one `[stderr]` section, exactly as the shell tools always did. +- **`updateProgress` replaces `updateDetail`.** `JobView.progress` is the live line and is cleared at settlement; `JobView.detail` is the terminal reason, with the model's `job_kill` reason merged in. +- **One projection.** `JobView` (client-safe leaf `@deepseek-ai/dsh-jobs/view`) is what the model tools, the browser roster, and the observation frames consume; `owner` is the session id, never the `Agent`. +- **One caller-bound view.** `JobRegistry.visibleTo(caller?)` binds a session once and returns `list`, `get`, `read`, `readAt`, `kill`, and `wait`; every method throws for an id outside the caller's set without distinguishing unknown from foreign. +- **One event stream.** `events.subscribe(filter, listener)` with `{ owner }`, `{ owners: 'scope' }`, or `{ owners: 'all' }` replaces the three listener families. `settled` names its cause (`producer`, `kill`, `teardown`); `output` carries only the id and the new total. +- **The notice ledger moves to `dsh-tool-jobs`.** The registry no longer tracks `reported`. The tool claims a job when a wait starts (and withdraws on timeout or abort) and when `job_kill` is accepted; the settlement event drops the entry, teardown settlements and unowned jobs are skipped, and the destination is the agent registered for the owner session at settlement. +- **The roster leaves the session control stream.** `dsh-api-job-controller` owns `job.rows({ sessionId })` — whole-set frames after each coalesced burst of lifecycle commits, never per append — beside `job.observe`, and its client installs `ctx.jobs` (`watchRows`, `observe`, one snapshot). `dsh-api-session-controller` carries queues and projections only; `ui-jobs` watches its session's roster while mounted, and a row is expandable while live or once it left retained output behind. + +`attachController` and the owner-relative `servesOwner` gate stay as they were; whether a producer may offer `run_in_background` without a mounted controller is deferred, since the gap predates this change. + +## Alternatives considered + +- **Keep three listeners with a shared owner filter.** It preserves the accreted names but not the property reviewers asked for — one place to learn what the registry announces — and `onJobDone`'s exact-owner delivery is what forced the registry to keep an `Agent` in every projection. +- **Keep `reported` in the registry.** Only the tool knows which deliveries reach the model (a wait's tool result, a kill's acknowledgement); the registry could only approximate it, and the approximation was the source of the double-notice and missed-notice bugs the review listed. +- **Keep the roster on the session control stream.** It saved one Remote stream but coupled the session controller to the job registry and mirrored a `record` flag the ring's byte count now answers directly (`output.total`). +- **Serve `log` chunks to the model too.** Producer narration is for observers; the model already receives the same facts through `progress` and the terminal `detail`. + +## Consequences + +The model-visible text is unchanged: status lines, tool descriptions and schemas, and notice wording are byte-identical, and the only new model-visible fact is the kill reason a `killed` status line now carries. A producer that needs to stream output picks pull sources or `append`; it never formats a consuming delta. The Web client renders every live job as expandable, so a job that never writes shows an empty running panel instead of a static row. `JobKindMap` merges are host-side, so a browser program types `JobView.kind` as the kinds it knows and treats the rest as opaque strings, which is all the roster does with it. diff --git a/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.zh.md b/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.zh.md new file mode 100644 index 0000000000..e87cf61d32 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.zh.md @@ -0,0 +1,33 @@ +# Agent Note:后台 job 的一个输出环、一个投影、一条事件流 + +Status: implemented + +[English](2026-09-03-jobs-seam-consolidation.md) | 中文 + +## 问题 + +job seam 是逐步堆出来的。生产者要把输出声明两次——模型读取的消耗式 `readOutput` 钩子,以及观察者读取的可选 `record: true` 环——注册表也为同一个 job 保留了两套词汇(模型侧的 `JobSnapshot`、会话控制流上的 `SessionJob`、观测线路上的 `JobWireChunk`)。三个监听器家族(`onJobDone`、`onJobsChanged`、`onOutput`)用不同的拥有者过滤投递彼此重叠的事实,注册表自己还跟踪着只有模型侧工具才解释得了的 `reported` 位。合并后设计的评审把接口层称作最薄弱的部分:读者分不清 `read`、`readRecord`、`JobStart`、`RecordingJob` 与 `updateDetail` 里哪些是约定、哪些是历史遗留。 + +## 决策 + +- **每个 job 一个环。** `JobSpec` 取代 `JobStart`:spec 声明可选的拉取式 `output` 源(`JobOutputSource`,子进程的 `readFrom` 家族),由注册表按自己的节奏(`dsh-jobs-local` 的 `pumpPollMs`)泵送;每个生产者都收到一个 `JobHandle`,其 `append` 把块推进同一个环。模型的消耗式读取与每个观察者的绝对偏移读取服务同一批字节;`readOutput` 与 `record` 判别字段被移除。shell 生产者把它们的 `observed` 偏移读取器交给注册表,并把沙箱事实折进终态 `detail`;terminal 生产者通过一个计字节的源适配其消耗式发送读取器;subagent 把回答作为 `JobOutcome.result` 返回,结算后的第一次读取携带它一次。 +- **两个游标,一份存储。** `VisibleJobs.read(id)` 是有状态的模型游标;`VisibleJobs.readAt(id, from)` 是无状态的观察者读取。模型读取排除 `log` 块(给观察者的生产者叙述),并渲染 stdout,再接一段 `[stderr]`,与 shell 工具一贯的做法完全一致。 +- **`updateProgress` 取代 `updateDetail`。** `JobView.progress` 是实时行,结算时清除;`JobView.detail` 是终态原因,合并了模型 `job_kill` 给出的原因。 +- **一个投影。** `JobView`(客户端安全叶子 `@deepseek-ai/dsh-jobs/view`)是模型工具、浏览器名册与观测帧共同消费的形状;`owner` 是会话 id,从不是 `Agent`。 +- **一个绑定调用方的视图。** `JobRegistry.visibleTo(caller?)` 绑定一次会话并返回 `list`、`get`、`read`、`readAt`、`kill` 与 `wait`;每个方法对调用方集合之外的 id 抛出,不区分未知与他人。 +- **一条事件流。** 带 `{ owner }`、`{ owners: 'scope' }` 或 `{ owners: 'all' }` 过滤的 `events.subscribe(filter, listener)` 取代三个监听器家族。`settled` 标出原因(`producer`、`kill`、`teardown`);`output` 只携带 id 与新的 total。 +- **播报台账移到 `dsh-tool-jobs`。** 注册表不再跟踪 `reported`。工具在等待开始时认领 job(超时或中止则撤回),在 `job_kill` 被接受时也认领;结算事件删除条目,teardown 结算与无主 job 被跳过,投递目标是结算时登记在拥有者会话下的 agent。 +- **名册离开会话控制流。** `dsh-api-job-controller` 在 `job.observe` 旁拥有 `job.rows({ sessionId })`——每轮聚合过的生命周期提交之后发一次整集帧,从不按追加发——其客户端安装 `ctx.jobs`(`watchRows`、`observe`、一份快照)。`dsh-api-session-controller` 只承载队列与投影;`ui-jobs` 在挂载期间关注其会话的名册,行在 job 进行中或留有保留输出时可展开。 + +`attachController` 与相对拥有者的 `servesOwner` 门保持原样;没有挂载控制器的生产者是否可以提供 `run_in_background`,因为这个缺口早于本次变更,暂不处理。 + +## 考虑过的替代方案 + +- **保留三个监听器并共享一个拥有者过滤。** 它保住了堆出来的名字,却保不住评审要的性质——一个地方就能学会注册表宣布什么——而且 `onJobDone` 的精确拥有者投递正是迫使注册表在每个投影里保留 `Agent` 的原因。 +- **把 `reported`留在注册表。** 只有工具知道哪些投递到达了模型(等待的工具结果、kill 的确认);注册表只能近似,而这个近似正是评审列出的重复播报与漏播报 bug 的来源。 +- **把名册留在会话控制流上。** 省了一条 Remote 流,却把会话控制器耦合到 job 注册表,还镜像了一个环的字节数如今直接回答的 `record` 标志(`output.total`)。 +- **也把 `log` 块交给模型。** 生产者叙述是给观察者的;模型已经通过 `progress` 与终态 `detail` 收到同样的事实。 + +## 后果 + +模型可见文本保持不变:状态行、工具描述与 schema、播报措辞逐字节相同,唯一新增的模型可见事实是 `killed` 状态行现在携带的 kill 原因。需要流式输出的生产者选择拉取源或 `append`,从不格式化消耗式增量。Web 客户端把每个进行中的 job 渲染为可展开,因此从不写输出的 job 显示为空的运行中面板而非静态行。`JobKindMap` 的合并发生在宿主侧,浏览器程序把 `JobView.kind` 视为它认识的 kind 集合,其余当作不透明字符串——名册对它也只做这些。 diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml index ee733d059e..8e24662bc9 100644 --- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.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 .agents/notes/implemented/feature/2026-08-08-web-background-job-display.md -2026-08-08-web-background-job-display.md: 7787466154d65ba0970010c3fdaf964ae6d8507f -2026-08-08-web-background-job-display.zh.md: 478acdf00936baed1700d18db2f63b1da1749e37 +2026-08-08-web-background-job-display.md: d2440ea63fc1d9c7f1829fa18b3054a8ea3768a5 +2026-08-08-web-background-job-display.zh.md: e5e55c95ce94f211ee6d1ac7f3391ab9a453c1a6 diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md index 7787466154..d2440ea63f 100644 --- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md +++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.md @@ -2,6 +2,8 @@ Status: implemented +Superseded: the roster this note put on the session control stream (`jobsBySession`, `onJobsChanged`) now streams from the job controller's `job.rows` into `ctx.jobs` — see [the jobs seam consolidation](../architecture/2026-09-03-jobs-seam-consolidation.md). The display decisions below (one roster, sections, durations, no kill control) still hold. + Update: the output phase this note deferred now ships as the per-job observation record on `ctx.jobs` — see [jobs absorb the record](../architecture/2026-09-01-jobs-absorb-activity-record.md). English | [中文](2026-08-08-web-background-job-display.zh.md) @@ -119,7 +121,7 @@ A running one-shot background subagent therefore appears both there and in the s The [web e2e scenario](../../../../apps/web/tests/background-job-list.e2e.ts) is the end-to-end proof and runs keyless: a real `run_in_background` bash call registers with `ctx.jobs`, the header count and row appear with no user interaction, and killing the task through the registry flips the open list to its producer detail. It asserts the whole delivery path rather than any single layer. -Below it, [`jobs-local`](../../../../packages/jobs/jobs-local/tests/jobs.spec.ts) pins the change feed at all four commit points, its containment of a throwing observer, and its removal on both explicit disposal and fiber teardown; [`control-jobs`](../../../../packages/api/session-controller/tests/control-jobs.host.spec.ts) pins the complete baseline, three change pushes, dropped internal fields, unowned fan-out, no-resume guarantee, registry-absent composition, and the prohibition on consuming model output; and the client suites pin baseline replacement, the last-wins fold, the absent-key representation, removal cleanup, and the component's ordering, duration, and dismissal behavior. +Below it, [`jobs-local`](../../../../packages/jobs/jobs-local/tests/jobs.spec.ts) pins the change feed at all four commit points, its containment of a throwing observer, and its removal on both explicit disposal and fiber teardown; [`rows`](../../../../packages/api/job-controller/tests/rows.host.spec.ts) pins the roster stream that replaced the control-stream fan-out: the complete visible set on open, a refresh after each lifecycle commit and none per append, owner removal, and a clean abort; and the client suites pin baseline replacement, the last-wins fold, the absent-key representation, removal cleanup, and the component's ordering, duration, and dismissal behavior. ## Consequences diff --git a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md index 478acdf009..e5e55c95ce 100644 --- a/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md +++ b/.agents/notes/implemented/feature/2026-08-08-web-background-job-display.zh.md @@ -2,6 +2,8 @@ Status: implemented +Superseded:本文放在会话控制流上的名册(`jobsBySession`、`onJobsChanged`)现在从 job 控制器的 `job.rows` 流入 `ctx.jobs`——见 [jobs seam 收敛](../architecture/2026-09-03-jobs-seam-consolidation.zh.md)。下文的展示决策(单一名册、分组、时长、没有 kill 控件)仍然成立。 + Update:本文推迟的输出阶段现已作为 `ctx.jobs` 上的逐 job 观测 record 交付——见 [jobs 吸收 record](../architecture/2026-09-01-jobs-absorb-activity-record.zh.md)。 [English](2026-08-08-web-background-job-display.md) | 中文 @@ -119,7 +121,7 @@ abstract onJobsChanged(listener: JobsChangedListener): () => void [web e2e 场景](../../../../apps/web/tests/background-job-list.e2e.ts)是端到端的证据,且无需密钥:一次真实的 `run_in_background` bash 调用注册进 `ctx.jobs`,header 的计数与行在没有任何用户操作的情况下出现,通过注册表杀掉该任务后打开着的列表翻到生产者给出的 detail。它断言的是整条投递链路,而不是其中某一层。 -在它之下,[`jobs-local`](../../../../packages/jobs/jobs-local/tests/jobs.spec.ts) 钉住变更订阅的全部四个提交点、对抛错观察者的包容,以及显式销毁与 fiber 拆除两条路径上的注销;[`control-jobs`](../../../../packages/api/session-controller/tests/control-jobs.host.spec.ts) 钉住完整 baseline、三次变更推送、被丢弃的内部字段、无主扇出、不 resume 的保证、没有注册表的组合,以及不得消费模型输出;客户端各套件钉住 baseline 替换、last-wins 折叠、缺失键表示、移除清理,以及组件的排序、时长与关闭行为。 +在它之下,[`jobs-local`](../../../../packages/jobs/jobs-local/tests/jobs.spec.ts) 钉住变更订阅的全部四个提交点、对抛错观察者的包容,以及显式销毁与 fiber 拆除两条路径上的注销;[`rows`](../../../../packages/api/job-controller/tests/rows.host.spec.ts) 钉住取代控制流扇出的名册流:打开时的完整可见集、每次生命周期提交后刷新一次且追加不刷新、拥有者移除,以及干净的中止;客户端各套件钉住 baseline 替换、last-wins 折叠、缺失键表示、移除清理,以及组件的排序、时长与关闭行为。 ## 影响 diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index 01617f6564..da0b495dee 100644 --- a/docs/architecture.i18n.yaml +++ b/docs/architecture.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 docs/architecture.md -architecture.md: 825dac9cf44bd39f7297d2323b63b9f2bca6aa46 -architecture.zh.md: ca929d52cb20b97b522bf1ca04ff8046da208583 +architecture.md: 07bb03abca22bcef018aefcde9515d42df9f1b7e +architecture.zh.md: 214927d0ebcf8e76a98fc10911b097827e86c7a4 diff --git a/docs/architecture.md b/docs/architecture.md index 825dac9cf4..07bb03abca 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -129,7 +129,7 @@ New behavior attaches to a documented extension point. Changing the loop itself | Add persistent terminal execution | register a `ctx.terminals` backend plus `dsh-tool-terminal` | | Add a human command | register on `ctx.commands`; it dispatches without a model turn | | Add background work | register on `ctx.jobs`; `job_*` tools collect or stop it | -| Stream live output to observers | declare `record: true` on the `ctx.jobs` start; the Web client renders it | +| Stream live output to observers | name pull `output` sources on the `ctx.jobs` spec or push through its `JobHandle`; the Web client renders the ring | | Start a Session from an external webhook | register a trusted rule on `ctx.webhookRuntime` and mount a provider adapter | | Add filesystem access or policy | register a `ctx.fs` provider or listen to `fs/*` events | | Confine spawned processes | use a `ctx.sandbox` backend; consumers wrap argv before spawning | diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index ca929d52cb..214927d0eb 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -133,7 +133,7 @@ seam 正是替换一个提供方就能改变整个产品的原因。文件系统 | 添加持久化终端执行 | 注册 `ctx.terminals` 后端和 `dsh-tool-terminal` | | 添加用户命令 | 在 `ctx.commands` 上注册;它无需模型轮次即可分派 | | 添加后台工作 | 在 `ctx.jobs` 上注册;`job_*` 工具负责收集或停止 | -| 向观察者流式输出 | 在 `ctx.jobs` 启动时声明 `record: true`;Web 客户端负责渲染 | +| 向观察者流式输出 | 在 `ctx.jobs` 的 spec 上声明拉取式 `output` 源,或经其 `JobHandle` 推送;Web 客户端负责渲染输出环 | | 从外部 webhook 启动 Session | 在 `ctx.webhookRuntime` 上注册可信规则,并挂载提供方适配器 | | 添加文件系统访问或策略 | 注册 `ctx.fs` 提供方,或监听 `fs/*` 事件 | | 限制所启动的进程 | 使用 `ctx.sandbox` 后端;消费方在启动进程前包装 argv | diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index 45eda97034..e1becf5027 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.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 docs/config-catalog.md -config-catalog.md: bac3a232db4daaf8f3d251e8bf47e3add1e3e640 -config-catalog.zh.md: 8ad8906e2b558eec8e092971f4ab2aa1d3aec020 +config-catalog.md: 9b6f869107a7a04e282f45af757cdacf50e729b7 +config-catalog.zh.md: e57226dd1ed37f070078894d10c277d914acf437 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index bac3a232db..9b6f869107 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -203,12 +203,12 @@ Source: [`packages/api/gateway/src/index.ts:119`](../packages/api/gateway/src/in ## `@deepseek-ai/dsh-api-job-controller` -Requires: `agents` · `jobs` · `typert` +Requires: `jobs` · `typert` ```ts config-catalog /** Job Controller deployment policy. */ export interface Config { - /** Coalescing window after new record output before an observation read, in milliseconds (default 100). */ + /** Coalescing window after a registry commit before the next rows or output read, in milliseconds (default 100). */ readonly observeFlushMs?: number /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */ readonly observeMaxFrameBytes?: number @@ -948,14 +948,16 @@ export interface Config { * omission defaults to 10. */ maxConcurrentJobsPerOwner?: number - /** Live record retention per job in UTF-8 bytes; omission defaults to 262144. */ + /** Live ring retention per job in UTF-8 bytes; omission defaults to 262144. */ retainBytes?: number - /** Record retention kept after a job settles, in UTF-8 bytes; omission defaults to 16384. */ + /** Ring retention kept after a job settles, in UTF-8 bytes; omission defaults to 16384. */ settledRetainBytes?: number + /** Poll interval for a job's pull sources, in milliseconds; omission defaults to 150. */ + pumpPollMs?: number } ``` -Source: [`packages/jobs/jobs-local/src/index.ts:38`](../packages/jobs/jobs-local/src/index.ts) +Source: [`packages/jobs/jobs-local/src/index.ts:45`](../packages/jobs/jobs-local/src/index.ts) @@ -2645,12 +2647,10 @@ Requires: `tools` · `shell` · `systemPrompt` · `shellEnv` export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean - /** Poll cadence for copying background output into the job record, in milliseconds (default 150). */ - recordPollMs?: number } ``` -Source: [`packages/shell/tool-bash/src/index.ts:34`](../packages/shell/tool-bash/src/index.ts) +Source: [`packages/shell/tool-bash/src/index.ts:33`](../packages/shell/tool-bash/src/index.ts) @@ -2751,7 +2751,7 @@ Source: [`packages/goal/tool-goal/src/index.ts:25`](../packages/goal/tool-goal/s ## `@deepseek-ai/dsh-tool-jobs` -Requires: `tools` · `jobs` · `systemPrompt` +Requires: `tools` · `jobs` · `agents` · `systemPrompt` ```ts config-catalog /** Configures bounded `job_output` waits and completion-notice delivery. */ @@ -2772,14 +2772,14 @@ export interface Config { } /** - * How an unreported completion reaches an owner that is already idle: `wakeup` + * How an uncollected completion reaches an owner that is already idle: `wakeup` * opens a turn for it, `quiet` leaves it pending until something else wakes the * owner. A busy owner is injected either way. */ export type CompletionDelivery = 'quiet' | 'wakeup' ``` -Source: [`packages/jobs/tool-jobs/src/index.ts:31`](../packages/jobs/tool-jobs/src/index.ts) +Source: [`packages/jobs/tool-jobs/src/index.ts:37`](../packages/jobs/tool-jobs/src/index.ts) @@ -2812,12 +2812,10 @@ Requires: `tools` · `shell` · `systemPrompt` · `shellEnv` export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean - /** Poll cadence for copying background output into the job record, in milliseconds (default 150). */ - recordPollMs?: number } ``` -Source: [`packages/shell/tool-pwsh/src/index.ts:53`](../packages/shell/tool-pwsh/src/index.ts) +Source: [`packages/shell/tool-pwsh/src/index.ts:52`](../packages/shell/tool-pwsh/src/index.ts) @@ -3001,7 +2999,7 @@ export interface Config { } ``` -Source: [`packages/terminal/tool-terminal/src/index.ts:35`](../packages/terminal/tool-terminal/src/index.ts) +Source: [`packages/terminal/tool-terminal/src/index.ts:36`](../packages/terminal/tool-terminal/src/index.ts) diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index 8ad8906e2b..e57226dd1e 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -205,12 +205,12 @@ export interface Config { ## `@deepseek-ai/dsh-api-job-controller` -需要:`agents` · `jobs` · `typert` +需要:`jobs` · `typert` ```ts config-catalog /** Job Controller deployment policy. */ export interface Config { - /** Coalescing window after new record output before an observation read, in milliseconds (default 100). */ + /** Coalescing window after a registry commit before the next rows or output read, in milliseconds (default 100). */ readonly observeFlushMs?: number /** Soft byte budget per observation output frame (default 65536); one larger chunk ships whole. */ readonly observeMaxFrameBytes?: number @@ -952,14 +952,16 @@ export interface Config { * omission defaults to 10. */ maxConcurrentJobsPerOwner?: number - /** Live record retention per job in UTF-8 bytes; omission defaults to 262144. */ + /** Live ring retention per job in UTF-8 bytes; omission defaults to 262144. */ retainBytes?: number - /** Record retention kept after a job settles, in UTF-8 bytes; omission defaults to 16384. */ + /** Ring retention kept after a job settles, in UTF-8 bytes; omission defaults to 16384. */ settledRetainBytes?: number + /** Poll interval for a job's pull sources, in milliseconds; omission defaults to 150. */ + pumpPollMs?: number } ``` -来源:[`packages/jobs/jobs-local/src/index.ts:38`](../packages/jobs/jobs-local/src/index.ts) +来源:[`packages/jobs/jobs-local/src/index.ts:45`](../packages/jobs/jobs-local/src/index.ts) @@ -2649,12 +2651,10 @@ export type TokenMeterConfig = Record export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean - /** Poll cadence for copying background output into the job record, in milliseconds (default 150). */ - recordPollMs?: number } ``` -来源:[`packages/shell/tool-bash/src/index.ts:34`](../packages/shell/tool-bash/src/index.ts) +来源:[`packages/shell/tool-bash/src/index.ts:33`](../packages/shell/tool-bash/src/index.ts) @@ -2755,7 +2755,7 @@ export interface Config { ## `@deepseek-ai/dsh-tool-jobs` -需要:`tools` · `jobs` · `systemPrompt` +需要:`tools` · `jobs` · `agents` · `systemPrompt` ```ts config-catalog /** Configures bounded `job_output` waits and completion-notice delivery. */ @@ -2776,14 +2776,14 @@ export interface Config { } /** - * How an unreported completion reaches an owner that is already idle: `wakeup` + * How an uncollected completion reaches an owner that is already idle: `wakeup` * opens a turn for it, `quiet` leaves it pending until something else wakes the * owner. A busy owner is injected either way. */ export type CompletionDelivery = 'quiet' | 'wakeup' ``` -来源:[`packages/jobs/tool-jobs/src/index.ts:31`](../packages/jobs/tool-jobs/src/index.ts) +来源:[`packages/jobs/tool-jobs/src/index.ts:37`](../packages/jobs/tool-jobs/src/index.ts) @@ -2816,12 +2816,10 @@ export interface Config { export interface Config { /** Expose `run_in_background` (default true); disabled calls are also rejected. */ enableRunInBackground?: boolean - /** Poll cadence for copying background output into the job record, in milliseconds (default 150). */ - recordPollMs?: number } ``` -来源:[`packages/shell/tool-pwsh/src/index.ts:53`](../packages/shell/tool-pwsh/src/index.ts) +来源:[`packages/shell/tool-pwsh/src/index.ts:52`](../packages/shell/tool-pwsh/src/index.ts) @@ -3005,7 +3003,7 @@ export interface Config { } ``` -来源:[`packages/terminal/tool-terminal/src/index.ts:35`](../packages/terminal/tool-terminal/src/index.ts) +来源:[`packages/terminal/tool-terminal/src/index.ts:36`](../packages/terminal/tool-terminal/src/index.ts) diff --git a/docs/cookbook/adding-a-tool.i18n.yaml b/docs/cookbook/adding-a-tool.i18n.yaml index 9d02664a90..b7d90c82c1 100644 --- a/docs/cookbook/adding-a-tool.i18n.yaml +++ b/docs/cookbook/adding-a-tool.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 docs/cookbook/adding-a-tool.md -adding-a-tool.md: f6b2703f3db69a6abc04dbd0fd9893555eed0602 -adding-a-tool.zh.md: d4831e2be061c2565e88004062cbb1558491bb9d +adding-a-tool.md: e6d1a9702d21420eeb42d743bd26f7738be2c217 +adding-a-tool.zh.md: a0d35f0b2c821333d82170945aa14f913fa7e034 diff --git a/docs/cookbook/adding-a-tool.md b/docs/cookbook/adding-a-tool.md index f6b2703f3d..e6d1a9702d 100644 --- a/docs/cookbook/adding-a-tool.md +++ b/docs/cookbook/adding-a-tool.md @@ -52,7 +52,7 @@ Registration is effect-based: disposing the plugin fiber unregisters the tool. S Gate `run_in_background` with producer config, then register through `ctx.jobs.start({ kind, label, owner: exec.agent, run })`. The registry rejects a pre-aborted invocation before the producer body; the runtime validates ownership and task-controller availability before `run()` starts work, then supplies the id, session fence, generic control tools, notices, and owner cleanup. A successful background branch returns a typed canonical handle such as `{ kind: 'background', jobId }`; its Native renderer may keep human prose such as `started background job bash-1`, but PTC mode must never parse that prose to recover the id. -The producer supplies synchronous `cancel`, non-rejecting `done` that settles after resource cleanup, and optional consuming `readOutput` with bounded-output formatting. A pre-aborted call is a failure because no task exists whose id could satisfy the successful output schema. Once `ctx.jobs.start()` publishes the id, use a task-owned cancellation signal rather than `exec.signal`: later outer-call cancellation stops waiting for the call but does not kill published work; `job_kill`, owner disposal, and service teardown own that lifetime. Foreground work remains coupled to `exec.signal`. See the [background job runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and `dsh-tool-bash` for a stream producer. +The spec supplies synchronous `cancel`, a non-rejecting `done` that settles after resource cleanup, and either pull `output` sources the registry pumps into the job's output ring or pushes through the `JobHandle` its starter receives; `dsh-tool-jobs` renders the model's consuming read from that ring. A pre-aborted call is a failure because no task exists whose id could satisfy the successful output schema. Once `ctx.jobs.start()` publishes the id, use a task-owned cancellation signal rather than `exec.signal`: later outer-call cancellation stops waiting for the call but does not kill published work; `job_kill`, owner disposal, and service teardown own that lifetime. Foreground work remains coupled to `exec.signal`. See the [background job runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) and `dsh-tool-bash` for a stream producer. ## Execution policy and observation diff --git a/docs/cookbook/adding-a-tool.zh.md b/docs/cookbook/adding-a-tool.zh.md index d4831e2be0..a0d35f0b2c 100644 --- a/docs/cookbook/adding-a-tool.zh.md +++ b/docs/cookbook/adding-a-tool.zh.md @@ -52,7 +52,7 @@ export function apply(ctx: Context) { 通过 producer 配置控制 `run_in_background`,然后使用 `ctx.jobs.start({ kind, label, owner: exec.agent, run })` 注册任务。注册表会在进入 producer 主体前将已预先中止的调用判为失败;运行时会在 `run()` 启动工作前校验 owner 和任务控制器是否可用,随后提供 id、会话围栏、通用控制工具、通知和 owner cleanup。成功的后台分支会返回类型化的规范句柄,如 `{ kind: 'background', jobId }`;其 Native 渲染器可以保留 `started background job bash-1` 这类供人阅读的自然语言,但 PTC mode 绝不能通过解析该文本取得 id。 -producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`,以及可选的消费式 `readOutput`(负责有界输出的格式化)。预先中止的调用属于失败,因为此时没有任务,其 id 无法满足成功输出 schema。`ctx.jobs.start()` 发布 id 后,应使用任务自有的取消信号,而不是 `exec.signal`:之后取消外层调用只会停止等待本次调用,不会终止已经发布的工作;该生命周期归 `job_kill`、owner dispose 和服务 teardown 所有。前台工作仍与 `exec.signal` 耦合。流式 producer 的示例和完整约定见[后台任务运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md)与 `dsh-tool-bash`。 +spec 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 `done`,以及由注册表泵入 job 输出环的拉取式 `output` 源或经 starter 收到的 `JobHandle` 推送的追加;模型的消费式读取由 `dsh-tool-jobs` 从该环渲染。预先中止的调用属于失败,因为此时没有任务,其 id 无法满足成功输出 schema。`ctx.jobs.start()` 发布 id 后,应使用任务自有的取消信号,而不是 `exec.signal`:之后取消外层调用只会停止等待本次调用,不会终止已经发布的工作;该生命周期归 `job_kill`、owner dispose 和服务 teardown 所有。前台工作仍与 `exec.signal` 耦合。流式 producer 的示例和完整约定见[后台任务运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md)与 `dsh-tool-bash`。 diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml index 9d71df140c..fc09aa63be 100644 --- a/docs/event-producer-consumer.i18n.yaml +++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md -event-producer-consumer.md: e0b4709875723bd96f9910b1bf518600612f0a12 -event-producer-consumer.zh.md: 0f0fa1317eb5a017daf435648f5c3e36208626e0 +event-producer-consumer.md: 53f524875794bd6f088adc093e68d47816512098 +event-producer-consumer.zh.md: b07570110077da6c3c775d6c1381cf69ef534c70 diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index e0b4709875..53f5248757 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -21,11 +21,11 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:224`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:185`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` | | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:285`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:551`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:531`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:558`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:537`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:544`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:530`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:510`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:537`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:516`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:523`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` | | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:81`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md index 0f0fa1317e..b075701100 100644 --- a/docs/event-producer-consumer.zh.md +++ b/docs/event-producer-consumer.zh.md @@ -23,11 +23,11 @@ | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:224`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:185`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` | | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:285`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:551`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:531`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:558`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:537`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:544`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:530`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:510`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:537`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:516`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:523`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` | | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:81`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml index 77ffa1744e..294e9032a4 100644 --- a/docs/module-graph.i18n.yaml +++ b/docs/module-graph.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 docs/module-graph.md -module-graph.md: 7d3db9fbf2c078bfcf8ad542cc02cd459c303730 -module-graph.zh.md: 726326b378dccc3b5208b67bf94117fb2f2e3d57 +module-graph.md: ad0a401fe90a7eb7f58b0ca0d81ff311667b0f61 +module-graph.zh.md: a16f710ea2476ef28467e5f6e0a1417c095b80df diff --git a/docs/module-graph.md b/docs/module-graph.md index 7d3db9fbf2..ad0a401fe9 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -1048,7 +1048,6 @@ flowchart TD pkg_api_session_controller --> pkg_attachment pkg_api_session_controller --> pkg_client_connection pkg_api_session_controller --> pkg_file_reference - pkg_api_session_controller --> pkg_jobs pkg_api_session_controller --> pkg_llm pkg_api_session_controller --> pkg_native_command pkg_api_session_controller --> pkg_scope @@ -1383,7 +1382,7 @@ flowchart TD | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | -| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | +| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`file-reference`](../packages/context/file-reference), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | | [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index 726326b378..a16f710ea2 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -1050,7 +1050,6 @@ flowchart TD pkg_api_session_controller --> pkg_attachment pkg_api_session_controller --> pkg_client_connection pkg_api_session_controller --> pkg_file_reference - pkg_api_session_controller --> pkg_jobs pkg_api_session_controller --> pkg_llm pkg_api_session_controller --> pkg_native_command pkg_api_session_controller --> pkg_scope @@ -1385,7 +1384,7 @@ flowchart TD | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | -| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`file-reference`](../packages/context/file-reference), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | +| [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`file-reference`](../packages/context/file-reference), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | | [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml index b6e2f8ac7f..32aec02eef 100644 --- a/docs/persistence-catalog.i18n.yaml +++ b/docs/persistence-catalog.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 docs/persistence-catalog.md -persistence-catalog.md: 1c0c6919987c691b82c4639aff0f779c95dca83c -persistence-catalog.zh.md: 4cc8ba5b7fc76708a80285013ebcbb03fe3e8e4a +persistence-catalog.md: 55a5596b3f37f31824eac77141abd0f6662ffa33 +persistence-catalog.zh.md: 2971549e08886fe7e39e77daf0785ea9060f9139 diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index 1c0c691998..55a5596b3f 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -512,7 +512,7 @@ Source: [`packages/llm/llm-retry/src/types.ts:11`](../packages/llm/llm-retry/src 'model/selection': ModelSelection ``` -Source: [`packages/api/session-controller/src/types.ts:41`](../packages/api/session-controller/src/types.ts) +Source: [`packages/api/session-controller/src/types.ts:40`](../packages/api/session-controller/src/types.ts) ### `permission/*` diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md index 4cc8ba5b7f..2971549e08 100644 --- a/docs/persistence-catalog.zh.md +++ b/docs/persistence-catalog.zh.md @@ -514,7 +514,7 @@ export type SessionEvent = { 'model/selection': ModelSelection ``` -来源:[`packages/api/session-controller/src/types.ts:41`](../packages/api/session-controller/src/types.ts) +来源:[`packages/api/session-controller/src/types.ts:40`](../packages/api/session-controller/src/types.ts) ### `permission/*` diff --git a/docs/subsystems/jobs.i18n.yaml b/docs/subsystems/jobs.i18n.yaml index 8e4c26b4bb..f71f76aa0e 100644 --- a/docs/subsystems/jobs.i18n.yaml +++ b/docs/subsystems/jobs.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 docs/subsystems/jobs.md -jobs.md: 639faa8da3836cb3efc865c494cd8ca8c60f49fb -jobs.zh.md: 3d008671657847520eccd41b8a3bd75014777680 +jobs.md: cdbeb6df0c0f69458bfae89981c8f2b6d3dfc381 +jobs.zh.md: a502fff316a0c2ebccf7888d4eb5aee10de07576 diff --git a/docs/subsystems/jobs.md b/docs/subsystems/jobs.md index 639faa8da3..cdbeb6df0c 100644 --- a/docs/subsystems/jobs.md +++ b/docs/subsystems/jobs.md @@ -2,7 +2,7 @@ English | [中文](jobs.zh.md) -Types shared by long-running producers, `ctx.jobs`, and job controls. The [runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) owns the design; this page records the exact fields and variants from [`packages/jobs/jobs/src/types.ts`](../../packages/jobs/jobs/src/types.ts). +Types shared by long-running producers, `ctx.jobs`, and job controls. The [seam consolidation Agent Note](../../.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.md) owns the current design and the [runtime Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) its origin; this page records the exact fields and variants from [`packages/jobs/jobs/src/types.ts`](../../packages/jobs/jobs/src/types.ts) and the client-safe [`view.ts`](../../packages/jobs/jobs/src/view.ts) leaf. ## Ids and status @@ -19,63 +19,83 @@ interface JobKindMap { } ``` -`JobStatus` is `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`; producer-specific facts belong in `JobSnapshot.detail`. +`JobStatus` is `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`; producer-specific facts belong in `JobView.progress` while the job runs and in `JobView.detail` once it settled. ## Producer contract -`JobStart` declares identity and a starter, discriminated by `record`: a `RecordingJobStart` receives the `RecordingJob` face, a `PlainJobStart` the `RunningJob` face without `append`. The runtime finishes preflight before calling `run()` with that face and commits without a later failable step. Producers own execution resources; the runtime owns identity, access, and lifecycle state. +A `JobSpec` declares identity, the owning session, optional pull `output` sources, and a starter. The runtime finishes preflight before calling `run()` with the job's `JobHandle` and commits without a later failable step. Producers own execution resources; the runtime owns identity, access, lifecycle state, and the output ring. ```ts type-equiv /** - * A start with the model-facing surfaces only. Its producer face carries no - * `append`, so output the registry would have nowhere to keep is - * unrepresentable rather than dropped. + * Producer declaration passed to {@link JobRegistry.start}. The runtime + * preflights access and cleanup before invoking {@link run}; the producer owns + * execution resources while the runtime owns identity, lifecycle state, and + * the output ring. */ -interface PlainJobStart extends JobStartBase { - record?: undefined +interface JobSpec { + /** Producer kind — also the id prefix (`bash`, `subagent`, …). */ + kind: JobKind + /** One-line model-facing label (the command; the delegation description). */ + label: string + /** + * Owning session. Access is fenced by it, and the owner's live Agent must be + * the one currently registered under that id: its disposal cancels and + * awaits the job. Omitting the owner creates an unowned job, open to any + * caller until service disposal. + */ + owner?: SessionId + /** + * Optional UTF-8 byte cap for each complete model-facing completion notice or + * output read, including controller status metadata. Independent of ring + * retention: it bounds the consuming model surface, never observers. + */ + outputLimitBytes?: number + /** + * Pull sources the registry pumps into the ring at its own cadence. + * Producers that narrate their own progress use {@link JobHandle.append} + * instead; a job may use both. + */ + output?: readonly JobOutputSource[] /** * Start the work after preflight and synchronously return its hooks. Called * once with the job's producer face; a throw leaves nothing registered (the * spent ordinal is skipped), and the producer must clean up any partially * started resources. - * @param job - the issued id plus the live-detail writer. + * @param job - the issued id plus the ring append and progress writers. */ - run(job: RunningJob): JobHooks + run(job: JobHandle): JobHooks } ``` ```ts type-equiv /** - * A start that declares an observable output record beside the model-facing - * surfaces: {@link RecordingJob.append} retains chunks in a bounded ring that - * any number of observers read at absolute byte offsets through - * {@link JobRegistry.readRecord}, and snapshots carry - * {@link JobSnapshot.outputTotal} and {@link JobSnapshot.outputEarliest}. + * Producer face of one registered job, handed to {@link JobSpec.run} and + * valid for the job's whole life. All methods are synchronous. Writes staged + * inside the starter call are retained and become visible with the + * registration commit; after settlement — the producer's own outcome, a kill, + * or a registry-forced teardown end — writes log and drop instead of + * throwing, so a producer's trailing flush cannot break its own teardown path. */ -interface RecordingJobStart extends JobStartBase { - record: true +interface JobHandle { + /** The registry-issued id (`-N`). */ + readonly id: JobId /** - * Start the work after preflight and synchronously return its hooks. Called - * once with the job's producer face; a throw leaves nothing registered (the - * spent ordinal is skipped), and the producer must clean up any partially - * started resources. - * @param job - the issued id plus the record append and live-detail writers. + * Append one chunk to the output ring. Offsets advance by the chunk's UTF-8 + * byte length; an empty chunk is dropped without waking observers. + * @param text - the chunk text, exactly as produced. + * @param options - stream label and gap marker. */ - run(job: RecordingJob): JobHooks + append(text: string, options?: JobAppendOptions): void + /** + * Replace the live progress line (`3/10`, the current phase). Settlement + * clears it; the terminal reason travels in {@link JobOutcome.detail}. + * @param line - the new progress line. + */ + updateProgress(line: string): void } ``` -```ts type-equiv -/** - * Producer declaration passed to {@link JobRegistry.start}, discriminated by - * `record`. The runtime preflights access and cleanup before invoking `run`; - * the producer owns execution resources while the runtime owns identity and - * lifecycle state. - */ -type JobStart = PlainJobStart | RecordingJobStart -``` - -`JobHooks.done` resolves after the producer releases its resources, not merely when work finishes. Optional `readOutput` distinguishes consuming stream jobs from final-output-only jobs. +`JobHooks.done` resolves after the producer releases its resources, not merely when work finishes. A job whose result is a value rather than a stream — a subagent's report, a workflow's rendered result — returns it as `JobOutcome.result`; the model's first read after settlement carries it once. ```ts type-equiv /** Hooks through which the runtime controls and observes producer work. */ @@ -89,18 +109,9 @@ interface JobHooks { * Resolves after the producer releases its resources, not merely when work * finishes. Must not reject; the runtime converts a rejection to `failed`. * If teardown cancellation throws, the runtime may force-fail only the - * registry record without claiming that the work stopped. Settlement also - * ends the record: fold any record-filling pump into this promise so the - * final drain lands before the registry trims and closes the stream. + * registry record without claiming that the work stopped. */ done: Promise - /** - * Consume output produced since the previous call. The producer formats - * truncation and spill notices. Absence marks a final-output-only job; each - * job has one consuming cursor. Independent of the record: this is the - * model-facing projection, {@link JobRegistry.readRecord} the observer one. - */ - readOutput?(): string } ``` @@ -109,74 +120,82 @@ interface JobHooks { interface JobOutcome { /** How the job ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */ status: 'completed' | 'killed' | 'failed' - /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */ + /** + * Terminal reason rendered into status lines (`exit code: 3`, `max-tokens`). + * When the job settles `killed` after a {@link VisibleJobs.kill} with a + * reason, the registry appends that reason. + */ detail?: string - /** Final output for jobs without `readOutput`; stream jobs leave it unset. */ - output?: string + /** + * Return value for jobs whose result is a value rather than a stream (a + * workflow's rendered result, a subagent's report). The output ring carries + * the stream; this is handed out once by the model's next {@link VisibleJobs.read}. + */ + result?: string } ``` -## Observation record - -A producer that declares `record: true` streams raw output into a bounded per-job ring through the `RecordingJob` face its starter receives; any number of observers read retained chunks at absolute byte offsets through `readRecord` without touching the consuming model cursor or notice state. Job settlement ends the stream and trims retention to the settled cap — the record has no separate lifecycle. `pumpJobOutput` copies producer offset-readers (the subprocess `readFrom` family) into the record at a bounded cadence. Browsers reach the record through `job.observe`, the Remote stream of [`dsh-api-job-controller`](../../packages/api/job-controller/README.md), whose frames are listed under its Cordis API section below. +A pull source hands the registry a non-consuming offset reader — the subprocess `readFrom` family. The registry pumps every source at its own cadence (`pumpPollMs` on `dsh-jobs-local`) and drains it once more before settlement closes the ring, so producers fold nothing into `done`. ```ts type-equiv /** - * Producer face of one registered job, handed to `run` and valid for the - * job's whole life. All methods are synchronous. Writes staged inside the - * starter call are retained and become visible with the registration commit; - * after settlement — the producer's own outcome, a kill, or a registry-forced - * teardown end — writes log and drop instead of throwing, so a producer's - * trailing flush cannot break its own teardown path. + * A pull source the registry pumps into the job's output ring — the subprocess + * `readFrom` family. The registry owns the cadence and drains every source one + * last time before settlement closes the ring, so a producer folds nothing + * into its `done`. */ -interface RunningJob { - /** The registry-issued id (`-N`). */ - readonly id: JobId - /** - * Replace the snapshot's status detail with a live progress line (`3/10`). - * @param detail - the new detail line. - */ - updateDetail(detail: string): void -} -``` - -```ts type-equiv -/** Producer face of a {@link RecordingJobStart}: {@link RunningJob} plus the record append. */ -interface RecordingJob extends RunningJob { - /** - * Append one record chunk. Offsets advance by the chunk's UTF-8 byte - * length; an empty chunk is dropped without waking observers. - * @param text - the chunk text, exactly as produced. - * @param options - stream label and gap marker. - */ - append(text: string, options?: JobAppendOptions): void -} -``` - -```ts type-equiv -/** One retained record chunk returned by {@link JobRegistry.readRecord}. */ -interface JobRecordChunk { - /** Absolute offset of the chunk's first byte. */ - at: number - /** Chunk text exactly as appended (possibly tail-trimmed by retention). */ - text: string - /** Stream label, when the producer supplied one. */ +interface JobOutputSource { + /** Stream label attached to every chunk this source yields. */ channel?: JobChannel - /** Producer-reported loss immediately before this chunk. */ - gapBefore?: true + /** + * Read everything captured since `fromByte` without consuming it. + * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 first). + * @returns the delta text, the next offset, and the lossy flag. + */ + read(fromByte: number): JobSourceRead } ``` ```ts type-equiv -/** Result of one non-consuming {@link JobRegistry.readRecord}. */ -interface JobRecordRead { +/** One incremental read from a {@link JobOutputSource}. */ +interface JobSourceRead { + /** Text captured since the requested offset (the whole retained tail when lossy). */ + text: string + /** Whole-stream offset to resume from on the next read. */ + nextOffset: number + /** True when the requested offset slid out of the source's retained window. */ + lossy: boolean +} +``` + +## The output ring + +Every job owns one bounded ring. Pull sources are pumped into it and `JobHandle.append` pushes land whole; the model consumes the ring through a registry-kept cursor (`VisibleJobs.read`), any number of observers read it at absolute byte offsets (`VisibleJobs.readAt`), and neither disturbs the other. `JobChannel` labels `stdout`, `stderr`, and `log`; `log` is producer narration that reaches observers only, never the model's consuming read. Settlement ends the stream and trims retention to the settled cap — the ring has no separate lifecycle. Browsers reach the roster and the ring through `job.rows` and `job.observe`, the Remote streams of [`dsh-api-job-controller`](../../packages/api/job-controller/README.md), whose frames are listed under its Cordis API section below. + +```ts type-equiv +/** One chunk of a job's output ring: absolute offset, text, and its provenance. */ +interface JobChunk { + /** Absolute offset of the chunk's first byte; offsets never move once assigned. */ + readonly at: number + /** Chunk text exactly as appended (possibly tail-trimmed by retention). */ + readonly text: string + /** Stream label, when the producer supplied one. */ + readonly channel?: JobChannel + /** Bytes immediately before this chunk were lost, at the producer or to retention. */ + readonly gapBefore?: true +} +``` + +```ts type-equiv +/** Result of one non-consuming {@link VisibleJobs.readAt}. */ +interface JobOutputRead { /** Retained chunks overlapping `[from, total)`, in offset order. */ - chunks: readonly JobRecordChunk[] + chunks: readonly JobChunk[] /** - * Offset to resume from — the record's current `outputTotal`. Always a - * chunk boundary: appends land whole and trimming only advances chunk - * starts, and consumers concatenate `chunks` under that assumption, so a - * provider serving partial chunks would silently duplicate text. + * Offset to resume from — the ring's current `total`. Always a chunk + * boundary: appends land whole and trimming only advances chunk starts, and + * consumers concatenate `chunks` under that assumption, so a provider + * serving partial chunks would silently duplicate text. */ next: number /** True when `from` fell below the oldest retained byte, so bytes are missing before `chunks`. */ @@ -186,78 +205,167 @@ interface JobRecordRead { ## Consumer views -Snapshots are fresh read-only projections. `ownerSession` carries the shared `SessionId` used for authorization; completion listeners separately receive the exact owner object used for lifecycle cleanup. `reported` suppresses a completion notice after another reporter has delivered or committed to deliver the terminal state, including the teardown cancel that drains an owner or the service. +`JobView` is the one projection every reader consumes: the model tools, the browser roster, and the observation stream. `owner` carries the session id that fences access; the registry resolves the live `Agent` behind it for lifecycle cleanup and never hands the object out. `progress` is the producer's live line and is cleared at settlement; `detail` is the terminal reason, with a recorded kill reason merged in. ```ts type-equiv /** - * A read-only projection of one job, safe to hand to listeners and tools — - * a fresh object per call, never live registry state. + * Read-only projection of one job — a fresh object per call, never live + * registry state. The model tools, the browser roster, and the observation + * stream all consume this one shape. */ -interface JobSnapshot { +interface JobView { /** The registry-issued id (`-N`). */ - id: JobId + readonly id: JobId /** The producer kind the job was registered with. */ - kind: JobKind + readonly kind: JobKind /** The producer-supplied one-line label. */ - label: string - /** Producer-owned cap for complete model-facing notices and output reads. */ - outputLimitBytes?: number - /** - * Owner session id used for authorization and correlation; absent for - * unowned jobs. Completion listeners receive the exact {@link Agent} - * separately through {@link JobDoneListener}. - */ - ownerSession?: SessionId + readonly label: string + /** Owning session; absent for an unowned job, which every caller can see. */ + readonly owner?: SessionId + /** Producer-owned cap for complete model-facing notices and reads, in UTF-8 bytes. */ + readonly outputLimitBytes?: number /** Current lifecycle state. */ - status: JobStatus - /** - * Kind-specific status detail: live progress while the producer updates it - * through {@link RunningJob.updateDetail}, the terminal detail once settled. - */ - detail?: string + readonly status: JobStatus + /** The producer's live progress line (`3/10`, the current phase); cleared at settlement. */ + readonly progress?: string + /** Terminal reason (`exit code: 3`); a recorded kill reason is merged in. */ + readonly detail?: string /** Epoch ms when the job was registered. */ - startedAt: number - /** Epoch ms when the job settled; absent while `running`/`stopping`. */ - finishedAt?: number + readonly startedAt: number + /** Epoch ms when the job settled; absent while live. */ + readonly finishedAt?: number /** - * True when a kill, read, wait, or teardown cancel has reported or committed - * to report the terminal state. Completion reporters suppress redundant - * notices when set. Teardown claims it because the owner or service being - * destroyed leaves no reader: a reporter that opens a turn on notice would - * otherwise spend a model request per teardown layer. + * The output ring's absolute coordinates. `total` is the offset the next + * chunk starts at (0 while nothing was written); `earliest` is the oldest + * retained byte, greater than zero exactly when retention dropped the head. */ - reported: boolean - /** - * Total UTF-8 bytes ever appended to the record — the offset the next chunk - * starts at. Present exactly when the job declared {@link JobStart.record}. - */ - outputTotal?: number - /** - * Offset of the oldest retained record byte. Greater than zero exactly when - * retention dropped the head; a reader starting below it gets a lossy read. - * Present exactly when the job declared {@link JobStart.record}. - */ - outputEarliest?: number + readonly output: { readonly total: number; readonly earliest: number } +} +``` + +`JobRegistry.visibleTo(caller)` binds one caller's identity and returns its operations; a caller sees its own jobs and every unowned job, and every operation throws for an id outside that set. + +```ts type-equiv +/** Output and post-read state returned by the consuming {@link VisibleJobs.read}. */ +interface JobRead { + /** Ring chunks appended since the model cursor, in offset order; every channel included. */ + chunks: readonly JobChunk[] + /** True when the cursor fell below the oldest retained byte, so bytes are missing before `chunks`. */ + lossy: boolean + /** The producer's {@link JobOutcome.result}, handed out by the first read after settlement only. */ + result?: string + /** The job's state at read time. */ + job: JobView } ``` ```ts type-equiv -/** Output and post-read state returned by {@link JobRegistry.read}. */ -interface JobRead { +/** + * The operations one caller may perform, bound by {@link JobRegistry.visibleTo}. + * A caller sees its own jobs and every unowned job; every method throws for + * an id outside that set, without distinguishing unknown from foreign. + */ +interface VisibleJobs { /** - * Stream kinds: the consuming delta since the previous read. Final-output - * kinds: empty while live, the terminal {@link JobOutcome.output} (or - * empty) once settled — idempotent, never consumed. + * List the visible jobs in registration order. + * @returns fresh projections. */ - text: string - /** The job's state at read time. */ - snapshot: JobSnapshot + list(): JobView[] + /** + * Project one job without touching its cursor. + * @param id - job to look up. + * @returns a fresh projection. + */ + get(id: JobId): JobView + /** + * Consume the ring from the model cursor and advance it to the current + * total. After settlement the first read also carries the producer's + * result; later reads return only what was appended since. + * @param id - job to read. + * @returns the chunks since the cursor, the lossy flag, the result once, and the post-read projection. + */ + read(id: JobId): JobRead + /** + * Read retained ring output from an absolute byte offset without consuming + * it. Resume by passing a previous read's `next`; an offset inside a + * retained chunk returns that whole chunk (its `at` may precede `from`). + * Never moves the model cursor. Throws for a negative or non-integer offset. + * @param id - job to read. + * @param from - absolute byte offset to read from (0 for the retained head). + * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. + */ + readAt(id: JobId, from: number): JobOutputRead + /** + * Request cancellation, then mark the job stopping. A recorded + * {@link JobKillOptions.reason} merges into the terminal `detail` when the + * job settles `killed`. A producer throw propagates without changing job + * state. + * @param id - job to cancel. + * @param options - cancellation reason. + * @returns `requested` for live work, otherwise `already-finished`. + */ + kill(id: JobId, options?: JobKillOptions): 'requested' | 'already-finished' + /** + * Wait for settlement or timeout without cancelling the job. Caller abort + * rejects only while the job is live; after settlement the terminal + * projection wins. Throws for an invalid timeout. + * @param id - job to wait for. + * @param timeoutMs - positive finite wait bound in milliseconds. + * @param signal - optional cancellation of the wait itself. + * @returns projection at settlement or timeout. + */ + wait(id: JobId, timeoutMs: number, signal?: AbortSignal): Promise } ``` +## Events + +The registry announces every commit through one filtered stream. Lifecycle events carry the projection after the commit they announce; `settled` names its cause so a completion reporter can skip a teardown; `output` carries only the id and the new total, so observers read from their own cursor and the registry never pushes payloads. + +```ts type-equiv +/** + * One lifecycle or output event. Lifecycle events carry the job's projection + * after the commit they announce; `output` carries only the id and the new + * total, so an observer schedules a {@link VisibleJobs.readAt} from its own + * cursor and the registry never pushes payloads. + */ +type JobEvent = + | { + /** Registration commit, progress line change, stopping transition, or removal from the visible set. */ + readonly type: 'registered' | 'progress' | 'stopping' | 'removed' + readonly job: JobView + } + | { + readonly type: 'settled' + readonly job: JobView + readonly cause: JobSettleCause + } + | { + readonly type: 'output' + readonly id: JobId + /** Owning session, absent for an unowned job. */ + readonly owner?: SessionId + /** The ring's total after the append (or at settlement, which ends the stream). */ + readonly total: number + } +``` + +```ts type-equiv +/** + * Who a subscription hears about. `{ owner }` delivers that session's jobs + * plus every unowned job (the set that session can see). `{ owners: 'scope' }` + * delivers the owners composed under the subscribing context — one registry + * serves every composition in the process, and a mount under one preset must + * not hear another preset's agents. `{ owners: 'all' }` delivers everything. + */ +type JobEventFilter = + | { readonly owner: SessionId } + | { readonly owners: 'all' | 'scope' } +``` + ## Service behavior -The abstract [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition specifies atomic `start`, caller-scoped `get` and `list`, `read`, non-consuming `readRecord`, `kill`, bounded `wait`, failure-isolated `onJobDone`, `onJobsChanged`, and `onOutput` listeners, and `attachController`; [`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) is the process-local Service Provider. Authorization compares owner sessions; owner cleanup and admission use the exact registered `Agent` instance. The local provider's positive-safe-integer `maxConcurrentJobsPerOwner` config defaults to `10` and counts `running` plus `stopping` records per exact owner, with one shared bucket for unowned jobs; terminal producer settlement releases capacity, and `retainBytes` (default 262144) with `settledRetainBytes` (default 16384) bound each declared record's live and settled retention. See [`dsh-jobs`](../../packages/jobs/jobs/README.md) for the Service Definition contract, [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.md) for the registry lifecycle and admission policy, and [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.md) for the model-facing Consumer. +The abstract [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition specifies atomic `start`, caller-bound `visibleTo` (`list`, `get`, the consuming `read`, the non-consuming `readAt`, `kill`, and bounded `wait`), the filtered `events` stream, and `attachController`; [`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) is the process-local Service Provider. Authorization compares owner sessions; owner cleanup and admission use the live `Agent` registered under the owner session when the job starts. The local provider's positive-safe-integer `maxConcurrentJobsPerOwner` config defaults to `10` and counts `running` plus `stopping` records per exact owner, with one shared bucket for unowned jobs; terminal producer settlement releases capacity; `retainBytes` (default 262144) and `settledRetainBytes` (default 16384) bound each ring's live and settled retention, and `pumpPollMs` (default 150) is the pull cadence. See [`dsh-jobs`](../../packages/jobs/jobs/README.md) for the Service Definition contract, [`dsh-jobs-local`](../../packages/jobs/jobs-local/README.md) for the registry lifecycle and admission policy, and [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.md) for the model-facing Consumer. @@ -275,11 +383,21 @@ Host service backing the generated `ctx.remote.job` namespace. ```ts cordis-catalog /** - * Stream one job's retained record output from an absolute byte offset, - * then its terminal status once settled and drained. Non-consuming: the + * Stream the jobs one session can see — its own plus every unowned job — + * as whole-set frames: one on open, then one after each coalesced burst of + * lifecycle commits. The stream has no natural end; the carrier closes it. + * @param request - the session whose visible set to mirror. + * @param signal - cancellation owned by the Remote stream carrier. + * @returns the roster frames. + */ +@Remote({ mode: 'stream' }) rows(request: JobRowsRequest, signal: AbortSignal): AsyncIterable + +/** + * Stream one job's retained output from an absolute byte offset, then its + * terminal projection once settled and drained. Non-consuming: the * model-facing cursor and notice state never observe these reads. The - * request's session resolves the fenced-read caller; the registry rejects a - * job the session does not own, a job without a record, or an unknown job. + * request's session is the fenced read's caller; the registry rejects a + * job the session cannot see and an unknown job. * @param request - target job, owning session, and optional resume offset. * @param signal - cancellation owned by the Remote stream carrier. * @returns anchor, coalesced output frames, and the terminal status. @@ -293,16 +411,16 @@ Source: [`packages/api/job-controller/src/index.ts`](../../packages/api/job-cont ### `ctx.jobs` — `JobRegistry` (abstract seam) -Abstract background job registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior). +Abstract background job registry. Subclass, implement the abstract members, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior). Implementations must honor these semantics: -- Registrations outlive producer and controller fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record. Teardown cancellation also marks the record reported, because a record its owner is being destroyed for has no reader left. +- Registrations outlive producer and controller fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record. Such settlements announce `cause: 'teardown'`, because a job whose owner is being destroyed has no reader left. - Owned-job access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary. -- Settlement is first-wins: one terminal record, released waiters, and one round of contained listener notification, even against a late producer outcome. Completion is announced last, after the record is committed and every other observer of the settlement has seen it, because a reporter may open a model turn synchronously. -- start refuses work while no attached job controller serves the spec's owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and completion-listener delivery — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition's scope serve exactly the agents composed under it. -- Record observation never consumes. Any number of readRecord readers hold their own absolute byte offsets; a record read changes no cursor and no notice state, so the model-facing surfaces (the consuming read, completion notices) are unaffected. -- Record retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement — the producer outcome, a kill, or teardown — trims retention to the settled cap and ends the stream; the record has no separate lifecycle. +- Settlement is first-wins: one terminal record, released waiters, then one round of contained event delivery, even against a late producer outcome. The `settled` event follows every released waiter, so a consumer that claims a settlement while waiting always claims before the event. +- start refuses work while no attached job controller serves the spec's owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and event delivery under `{ owners: 'scope' }` — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition's scope serve exactly the agents composed under it. +- Every job owns one output ring. Pull sources named by the spec are pumped by the registry and drained once more before settlement; pushed appends land whole. The model's consuming cursor and observers' absolute offsets read the same bytes and never disturb each other. +- Ring retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement trims retention to the settled cap and ends the stream; the ring has no separate lifecycle. ```ts cordis-catalog /** @@ -310,120 +428,20 @@ Implementations must honor these semantics: * admission before starting and atomically registering work. Any preflight * rejection leaves no job id or execution resource. A throwing starter * leaves nothing registered; after it returns, registration cannot fail. - * Settlement records the outcome, notifies listeners, and releases waiters. - * @param spec - job identity, owner, and synchronous starter. + * @param spec - job identity, owner, output sources, and synchronous starter. * @returns the registry-issued `-N` id. */ -abstract start(spec: JobStart): JobId +abstract start(spec: JobSpec): JobId /** - * List caller-owned and unowned jobs in registration order without exposing - * another session's labels. - * @param caller - reading agent; a non-agent caller sees only unowned jobs. - * @returns fresh snapshots. + * Bind the caller's identity once and return its operations. A caller sees + * its own jobs and every unowned job; a caller-less view sees unowned jobs + * only. The view resolves visibility on every call, so it stays valid as + * jobs come and go. + * @param caller - the reading session, or undefined for an anonymous caller. + * @returns the operations available to that caller. */ -abstract list(caller?: Agent): JobSnapshot[] - -/** - * Return a non-consuming snapshot without changing its read cursor or notice - * state. Throws for an unknown or foreign job. - * @param id - job to look up. - * @param caller - reading agent checked against the owner. - * @returns a fresh snapshot. - */ -abstract get(id: JobId, caller?: Agent): JobSnapshot - -/** - * Read the next stream delta, or the idempotent final output after settlement. - * A terminal read marks the job reported. Throws for an unknown or foreign - * job. - * @param id - job to read. - * @param caller - reading agent checked against the owner. - * @returns output text and the post-read snapshot. - */ -abstract read(id: JobId, caller?: Agent): JobRead - -/** - * Request cancellation, then mark the job stopping and reported. A producer - * throw propagates without changing job state. Throws for an unknown or - * foreign job. - * @param id - job to cancel. - * @param caller - killing agent checked against the owner. - * @param reason - logged reason forwarded to the producer. - * @returns `requested` for live work, otherwise `already-finished`. - */ -abstract kill(id: JobId, caller?: Agent, reason?: string): 'requested' | 'already-finished' - -/** - * Wait for settlement or timeout without cancelling the job. Caller abort - * rejects only while the job is live; after settlement the terminal - * snapshot wins so a notice suppressed for this waiter is still delivered. - * Throws for invalid, unknown, or foreign input. - * @param id - job to wait for. - * @param timeoutMs - positive finite wait bound in milliseconds. - * @param caller - waiting agent checked against the owner. - * @param signal - optional cancellation of the wait itself. - * @returns snapshot at settlement or timeout. - */ -abstract wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise - -/** - * Register an effect-scoped completion listener. It receives the settlements - * of the owners its registering context's scope covers; each listener is - * contained; returned promises are observed but not awaited. No listener runs - * after service disposal. - * @param listener - receives each terminal snapshot and its exact owner. - * @returns disposer that unregisters the listener. - */ -abstract onJobDone(listener: JobDoneListener): () => void - -/** - * Register an effect-scoped observer of visible-set changes. It fires after - * every commit that changes what {@link list} returns for that owner — - * registration, every stopping transition (including the one teardown - * performs before it awaits a slow producer), settlement, owner-disposal - * removal, and the emptying that service disposal commits — so an observer - * re-reads rather than accumulating deltas. - * - * Delivery is owner-relative on the same terms as {@link onJobDone}: an - * observer registered from an unscoped context — a host composition's own - * carrier — sees every owner, while one registered under an agent - * composition's scope sees exactly the agents composed under it. - * - * This is not a superset of {@link onJobDone}: that one delivers the terminal - * record under first-wins semantics a job controller couples to notice - * delivery, while this one carries no delivery meaning and marks nothing - * reported. Listeners are contained and never awaited. - * @param listener - receives the owner whose visible set changed, or - * `undefined` when an unowned job changed and every caller's set did. - * @returns disposer that unregisters the listener. - */ -abstract onJobsChanged(listener: JobsChangedListener): () => void - -/** - * Read retained record output from an absolute byte offset without consuming - * it. Resume by passing a previous read's `next`; a foreign offset inside a - * retained chunk returns that whole chunk (its `at` may precede `from`). - * Never marks the job reported. Throws for an unknown or foreign job, a job - * without a {@link JobStart.record} declaration, or a negative or - * non-integer offset. - * @param id - job to read. - * @param from - absolute byte offset to read from (0 for the retained head). - * @param caller - reading agent checked against the owner. - * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. - */ -abstract readRecord(id: JobId, from: number, caller?: Agent): JobRecordRead - -/** - * Register an effect-scoped observer of record advancement — one signal per - * committed append and one at settlement, carrying only the job id. A - * consumer schedules a {@link readRecord} from its own cursor; the registry - * never pushes payloads. Delivery is owner-relative on the same terms as - * {@link onJobsChanged}. Listeners are contained and never awaited. - * @param listener - receives the id whose record advanced. - * @returns disposer that unregisters the listener. - */ -abstract onOutput(listener: JobOutputListener): () => void +abstract visibleTo(caller?: SessionId): VisibleJobs /** * Attach an effect-scoped controller that can read and stop jobs. It serves the @@ -435,7 +453,7 @@ abstract onOutput(listener: JobOutputListener): () => void abstract attachController(name: string): () => void ``` -Types: [Agent](core.md) +Types: [SessionId](core.md) Source: [`packages/jobs/jobs/src/index.ts`](../../packages/jobs/jobs/src/index.ts) diff --git a/docs/subsystems/jobs.zh.md b/docs/subsystems/jobs.zh.md index 3d00867165..a502fff316 100644 --- a/docs/subsystems/jobs.zh.md +++ b/docs/subsystems/jobs.zh.md @@ -2,7 +2,7 @@ [English](jobs.md) | 中文 -长时间运行的生产方、`ctx.jobs` 与任务控制命令共用的类型。[运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md) 负责设计;本页记录 [`packages/jobs/jobs/src/types.ts`](../../packages/jobs/jobs/src/types.ts) 中的确切字段和变体。 +长时间运行的生产方、`ctx.jobs` 与任务控制命令共用的类型。[seam 收敛 Agent Note](../../.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.zh.md) 负责当前设计,[运行时 Agent Note](../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md) 记录其起源;本页记录 [`packages/jobs/jobs/src/types.ts`](../../packages/jobs/jobs/src/types.ts) 与客户端安全叶子 [`view.ts`](../../packages/jobs/jobs/src/view.ts) 中的确切字段与变体。 ## ID 与状态 @@ -19,63 +19,83 @@ interface JobKindMap { } ``` -`JobStatus` 为 `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`;生产方特有的事实归入 `JobSnapshot.detail`。 +`JobStatus` 为 `'running' | 'stopping' | 'completed' | 'killed' | 'failed'`;生产方特有的事实在运行期间归入 `JobView.progress`,结算后归入 `JobView.detail`。 ## 生产方约定 -`JobStart` 声明身份和启动器,并按 `record` 判别:`RecordingJobStart` 收到 `RecordingJob` 面,`PlainJobStart` 收到没有 `append` 的 `RunningJob` 面。运行时会在完成预检后携带该面调用 `run()`,随后提交注册,不再执行可能失败的步骤。生产方拥有执行资源;运行时拥有身份、访问权限和生命周期状态。 +`JobSpec` 声明身份、拥有者会话、可选的拉取式 `output` 源与启动器。运行时会在完成预检后携带该 job 的 `JobHandle` 调用 `run()`,随后提交注册,不再执行可能失败的步骤。生产方拥有执行资源;运行时拥有身份、访问、生命周期状态与输出环。 ```ts type-equiv /** - * A start with the model-facing surfaces only. Its producer face carries no - * `append`, so output the registry would have nowhere to keep is - * unrepresentable rather than dropped. + * Producer declaration passed to {@link JobRegistry.start}. The runtime + * preflights access and cleanup before invoking {@link run}; the producer owns + * execution resources while the runtime owns identity, lifecycle state, and + * the output ring. */ -interface PlainJobStart extends JobStartBase { - record?: undefined +interface JobSpec { + /** Producer kind — also the id prefix (`bash`, `subagent`, …). */ + kind: JobKind + /** One-line model-facing label (the command; the delegation description). */ + label: string + /** + * Owning session. Access is fenced by it, and the owner's live Agent must be + * the one currently registered under that id: its disposal cancels and + * awaits the job. Omitting the owner creates an unowned job, open to any + * caller until service disposal. + */ + owner?: SessionId + /** + * Optional UTF-8 byte cap for each complete model-facing completion notice or + * output read, including controller status metadata. Independent of ring + * retention: it bounds the consuming model surface, never observers. + */ + outputLimitBytes?: number + /** + * Pull sources the registry pumps into the ring at its own cadence. + * Producers that narrate their own progress use {@link JobHandle.append} + * instead; a job may use both. + */ + output?: readonly JobOutputSource[] /** * Start the work after preflight and synchronously return its hooks. Called * once with the job's producer face; a throw leaves nothing registered (the * spent ordinal is skipped), and the producer must clean up any partially * started resources. - * @param job - the issued id plus the live-detail writer. + * @param job - the issued id plus the ring append and progress writers. */ - run(job: RunningJob): JobHooks + run(job: JobHandle): JobHooks } ``` ```ts type-equiv /** - * A start that declares an observable output record beside the model-facing - * surfaces: {@link RecordingJob.append} retains chunks in a bounded ring that - * any number of observers read at absolute byte offsets through - * {@link JobRegistry.readRecord}, and snapshots carry - * {@link JobSnapshot.outputTotal} and {@link JobSnapshot.outputEarliest}. + * Producer face of one registered job, handed to {@link JobSpec.run} and + * valid for the job's whole life. All methods are synchronous. Writes staged + * inside the starter call are retained and become visible with the + * registration commit; after settlement — the producer's own outcome, a kill, + * or a registry-forced teardown end — writes log and drop instead of + * throwing, so a producer's trailing flush cannot break its own teardown path. */ -interface RecordingJobStart extends JobStartBase { - record: true +interface JobHandle { + /** The registry-issued id (`-N`). */ + readonly id: JobId /** - * Start the work after preflight and synchronously return its hooks. Called - * once with the job's producer face; a throw leaves nothing registered (the - * spent ordinal is skipped), and the producer must clean up any partially - * started resources. - * @param job - the issued id plus the record append and live-detail writers. + * Append one chunk to the output ring. Offsets advance by the chunk's UTF-8 + * byte length; an empty chunk is dropped without waking observers. + * @param text - the chunk text, exactly as produced. + * @param options - stream label and gap marker. */ - run(job: RecordingJob): JobHooks + append(text: string, options?: JobAppendOptions): void + /** + * Replace the live progress line (`3/10`, the current phase). Settlement + * clears it; the terminal reason travels in {@link JobOutcome.detail}. + * @param line - the new progress line. + */ + updateProgress(line: string): void } ``` -```ts type-equiv -/** - * Producer declaration passed to {@link JobRegistry.start}, discriminated by - * `record`. The runtime preflights access and cleanup before invoking `run`; - * the producer owns execution resources while the runtime owns identity and - * lifecycle state. - */ -type JobStart = PlainJobStart | RecordingJobStart -``` - -`JobHooks.done` 会在生产方释放其资源后 resolve,而不是仅在工作完成时 resolve。可选的 `readOutput` 用来区分会消费输出的流式任务和仅有最终输出的任务。 +`JobHooks.done` 会在生产方释放其资源后 resolve,而不是仅在工作完成时 resolve。结果是一个值而非流的 job——subagent 的报告、workflow 渲染出的结果——把它作为 `JobOutcome.result` 返回;模型在结算后的第一次读取携带它一次。 ```ts type-equiv /** Hooks through which the runtime controls and observes producer work. */ @@ -89,18 +109,9 @@ interface JobHooks { * Resolves after the producer releases its resources, not merely when work * finishes. Must not reject; the runtime converts a rejection to `failed`. * If teardown cancellation throws, the runtime may force-fail only the - * registry record without claiming that the work stopped. Settlement also - * ends the record: fold any record-filling pump into this promise so the - * final drain lands before the registry trims and closes the stream. + * registry record without claiming that the work stopped. */ done: Promise - /** - * Consume output produced since the previous call. The producer formats - * truncation and spill notices. Absence marks a final-output-only job; each - * job has one consuming cursor. Independent of the record: this is the - * model-facing projection, {@link JobRegistry.readRecord} the observer one. - */ - readOutput?(): string } ``` @@ -109,74 +120,82 @@ interface JobHooks { interface JobOutcome { /** How the job ended: finished (`completed`), cancelled (`killed`), or broke (`failed`). */ status: 'completed' | 'killed' | 'failed' - /** Kind-specific detail rendered into status lines ('exit code: 3', 'max-tokens'). */ + /** + * Terminal reason rendered into status lines (`exit code: 3`, `max-tokens`). + * When the job settles `killed` after a {@link VisibleJobs.kill} with a + * reason, the registry appends that reason. + */ detail?: string - /** Final output for jobs without `readOutput`; stream jobs leave it unset. */ - output?: string + /** + * Return value for jobs whose result is a value rather than a stream (a + * workflow's rendered result, a subagent's report). The output ring carries + * the stream; this is handed out once by the model's next {@link VisibleJobs.read}. + */ + result?: string } ``` -## 观测 record - -声明 `record: true` 的生产方通过 starter 收到的 `RecordingJob` 面把原始输出流入按 job 划分的有界环形缓冲;任意数量的观察者通过 `readRecord` 按绝对字节偏移读取保留块,不触碰消耗型的模型游标与通知状态。job 结算即封流并把保留量裁剪到结算上限——record 没有独立生命周期。`pumpJobOutput` 以有界节奏把生产方的偏移读取器(subprocess 的 `readFrom` 家族)复制进 record。浏览器经 [`dsh-api-job-controller`](../../packages/api/job-controller/README.zh.md) 的 Remote 流 `job.observe` 读取 record,其帧类型列在下方该控制器的 Cordis API 一节。 +拉取源把一个非消耗的偏移读取器——子进程的 `readFrom` 家族——交给注册表。注册表按自己的节奏(`dsh-jobs-local` 的 `pumpPollMs`)泵送每个源,并在结算封环之前再排干一次,因此生产方不需要把任何东西折进 `done`。 ```ts type-equiv /** - * Producer face of one registered job, handed to `run` and valid for the - * job's whole life. All methods are synchronous. Writes staged inside the - * starter call are retained and become visible with the registration commit; - * after settlement — the producer's own outcome, a kill, or a registry-forced - * teardown end — writes log and drop instead of throwing, so a producer's - * trailing flush cannot break its own teardown path. + * A pull source the registry pumps into the job's output ring — the subprocess + * `readFrom` family. The registry owns the cadence and drains every source one + * last time before settlement closes the ring, so a producer folds nothing + * into its `done`. */ -interface RunningJob { - /** The registry-issued id (`-N`). */ - readonly id: JobId - /** - * Replace the snapshot's status detail with a live progress line (`3/10`). - * @param detail - the new detail line. - */ - updateDetail(detail: string): void -} -``` - -```ts type-equiv -/** Producer face of a {@link RecordingJobStart}: {@link RunningJob} plus the record append. */ -interface RecordingJob extends RunningJob { - /** - * Append one record chunk. Offsets advance by the chunk's UTF-8 byte - * length; an empty chunk is dropped without waking observers. - * @param text - the chunk text, exactly as produced. - * @param options - stream label and gap marker. - */ - append(text: string, options?: JobAppendOptions): void -} -``` - -```ts type-equiv -/** One retained record chunk returned by {@link JobRegistry.readRecord}. */ -interface JobRecordChunk { - /** Absolute offset of the chunk's first byte. */ - at: number - /** Chunk text exactly as appended (possibly tail-trimmed by retention). */ - text: string - /** Stream label, when the producer supplied one. */ +interface JobOutputSource { + /** Stream label attached to every chunk this source yields. */ channel?: JobChannel - /** Producer-reported loss immediately before this chunk. */ - gapBefore?: true + /** + * Read everything captured since `fromByte` without consuming it. + * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 first). + * @returns the delta text, the next offset, and the lossy flag. + */ + read(fromByte: number): JobSourceRead } ``` ```ts type-equiv -/** Result of one non-consuming {@link JobRegistry.readRecord}. */ -interface JobRecordRead { +/** One incremental read from a {@link JobOutputSource}. */ +interface JobSourceRead { + /** Text captured since the requested offset (the whole retained tail when lossy). */ + text: string + /** Whole-stream offset to resume from on the next read. */ + nextOffset: number + /** True when the requested offset slid out of the source's retained window. */ + lossy: boolean +} +``` + +## 输出环 + +每个 job 拥有一个有界的环。拉取源被泵入其中,`JobHandle.append` 的推送整块落地;模型通过注册表保管的游标(`VisibleJobs.read`)消耗该环,任意数量的观察者按绝对字节偏移读取它(`VisibleJobs.readAt`),二者互不干扰。`JobChannel` 标记 `stdout`、`stderr` 与 `log`;`log` 是只到达观察者、从不进入模型消耗式读取的生产方叙述。结算即封流并把保留量裁剪到结算上限——环没有独立的生命周期。浏览器通过 [`dsh-api-job-controller`](../../packages/api/job-controller/README.zh.md) 的 Remote 流 `job.rows` 与 `job.observe` 触达名册与环,其帧列于下文的 Cordis API 一节。 + +```ts type-equiv +/** One chunk of a job's output ring: absolute offset, text, and its provenance. */ +interface JobChunk { + /** Absolute offset of the chunk's first byte; offsets never move once assigned. */ + readonly at: number + /** Chunk text exactly as appended (possibly tail-trimmed by retention). */ + readonly text: string + /** Stream label, when the producer supplied one. */ + readonly channel?: JobChannel + /** Bytes immediately before this chunk were lost, at the producer or to retention. */ + readonly gapBefore?: true +} +``` + +```ts type-equiv +/** Result of one non-consuming {@link VisibleJobs.readAt}. */ +interface JobOutputRead { /** Retained chunks overlapping `[from, total)`, in offset order. */ - chunks: readonly JobRecordChunk[] + chunks: readonly JobChunk[] /** - * Offset to resume from — the record's current `outputTotal`. Always a - * chunk boundary: appends land whole and trimming only advances chunk - * starts, and consumers concatenate `chunks` under that assumption, so a - * provider serving partial chunks would silently duplicate text. + * Offset to resume from — the ring's current `total`. Always a chunk + * boundary: appends land whole and trimming only advances chunk starts, and + * consumers concatenate `chunks` under that assumption, so a provider + * serving partial chunks would silently duplicate text. */ next: number /** True when `from` fell below the oldest retained byte, so bytes are missing before `chunks`. */ @@ -186,78 +205,167 @@ interface JobRecordRead { ## 消费方视图 -快照是每次新建的只读投影。`ownerSession` 携带用于授权的共享 `SessionId`;完成监听器则会另行收到用于生命周期清理的确切拥有者对象。另一个接口已经交付终止状态或承诺交付时,`reported` 会抑制完成通知;排空 owner 或服务的 teardown 取消同样计入。 +`JobView` 是每个读者都消费的唯一投影:模型工具、浏览器名册与观测流。`owner` 携带划定访问边界的会话 id;注册表为生命周期清理解析其背后的活体 `Agent`,从不把该对象交出去。`progress` 是生产方的实时行,结算时清除;`detail` 是终态原因,合并了记录下来的 kill 原因。 ```ts type-equiv /** - * A read-only projection of one job, safe to hand to listeners and tools — - * a fresh object per call, never live registry state. + * Read-only projection of one job — a fresh object per call, never live + * registry state. The model tools, the browser roster, and the observation + * stream all consume this one shape. */ -interface JobSnapshot { +interface JobView { /** The registry-issued id (`-N`). */ - id: JobId + readonly id: JobId /** The producer kind the job was registered with. */ - kind: JobKind + readonly kind: JobKind /** The producer-supplied one-line label. */ - label: string - /** Producer-owned cap for complete model-facing notices and output reads. */ - outputLimitBytes?: number - /** - * Owner session id used for authorization and correlation; absent for - * unowned jobs. Completion listeners receive the exact {@link Agent} - * separately through {@link JobDoneListener}. - */ - ownerSession?: SessionId + readonly label: string + /** Owning session; absent for an unowned job, which every caller can see. */ + readonly owner?: SessionId + /** Producer-owned cap for complete model-facing notices and reads, in UTF-8 bytes. */ + readonly outputLimitBytes?: number /** Current lifecycle state. */ - status: JobStatus - /** - * Kind-specific status detail: live progress while the producer updates it - * through {@link RunningJob.updateDetail}, the terminal detail once settled. - */ - detail?: string + readonly status: JobStatus + /** The producer's live progress line (`3/10`, the current phase); cleared at settlement. */ + readonly progress?: string + /** Terminal reason (`exit code: 3`); a recorded kill reason is merged in. */ + readonly detail?: string /** Epoch ms when the job was registered. */ - startedAt: number - /** Epoch ms when the job settled; absent while `running`/`stopping`. */ - finishedAt?: number + readonly startedAt: number + /** Epoch ms when the job settled; absent while live. */ + readonly finishedAt?: number /** - * True when a kill, read, wait, or teardown cancel has reported or committed - * to report the terminal state. Completion reporters suppress redundant - * notices when set. Teardown claims it because the owner or service being - * destroyed leaves no reader: a reporter that opens a turn on notice would - * otherwise spend a model request per teardown layer. + * The output ring's absolute coordinates. `total` is the offset the next + * chunk starts at (0 while nothing was written); `earliest` is the oldest + * retained byte, greater than zero exactly when retention dropped the head. */ - reported: boolean - /** - * Total UTF-8 bytes ever appended to the record — the offset the next chunk - * starts at. Present exactly when the job declared {@link JobStart.record}. - */ - outputTotal?: number - /** - * Offset of the oldest retained record byte. Greater than zero exactly when - * retention dropped the head; a reader starting below it gets a lossy read. - * Present exactly when the job declared {@link JobStart.record}. - */ - outputEarliest?: number + readonly output: { readonly total: number; readonly earliest: number } +} +``` + +`JobRegistry.visibleTo(caller)` 绑定一个调用方的身份并返回其操作;调用方看得到自己的 job 与所有无主 job,每个操作对该集合之外的 id 抛出。 + +```ts type-equiv +/** Output and post-read state returned by the consuming {@link VisibleJobs.read}. */ +interface JobRead { + /** Ring chunks appended since the model cursor, in offset order; every channel included. */ + chunks: readonly JobChunk[] + /** True when the cursor fell below the oldest retained byte, so bytes are missing before `chunks`. */ + lossy: boolean + /** The producer's {@link JobOutcome.result}, handed out by the first read after settlement only. */ + result?: string + /** The job's state at read time. */ + job: JobView } ``` ```ts type-equiv -/** Output and post-read state returned by {@link JobRegistry.read}. */ -interface JobRead { +/** + * The operations one caller may perform, bound by {@link JobRegistry.visibleTo}. + * A caller sees its own jobs and every unowned job; every method throws for + * an id outside that set, without distinguishing unknown from foreign. + */ +interface VisibleJobs { /** - * Stream kinds: the consuming delta since the previous read. Final-output - * kinds: empty while live, the terminal {@link JobOutcome.output} (or - * empty) once settled — idempotent, never consumed. + * List the visible jobs in registration order. + * @returns fresh projections. */ - text: string - /** The job's state at read time. */ - snapshot: JobSnapshot + list(): JobView[] + /** + * Project one job without touching its cursor. + * @param id - job to look up. + * @returns a fresh projection. + */ + get(id: JobId): JobView + /** + * Consume the ring from the model cursor and advance it to the current + * total. After settlement the first read also carries the producer's + * result; later reads return only what was appended since. + * @param id - job to read. + * @returns the chunks since the cursor, the lossy flag, the result once, and the post-read projection. + */ + read(id: JobId): JobRead + /** + * Read retained ring output from an absolute byte offset without consuming + * it. Resume by passing a previous read's `next`; an offset inside a + * retained chunk returns that whole chunk (its `at` may precede `from`). + * Never moves the model cursor. Throws for a negative or non-integer offset. + * @param id - job to read. + * @param from - absolute byte offset to read from (0 for the retained head). + * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. + */ + readAt(id: JobId, from: number): JobOutputRead + /** + * Request cancellation, then mark the job stopping. A recorded + * {@link JobKillOptions.reason} merges into the terminal `detail` when the + * job settles `killed`. A producer throw propagates without changing job + * state. + * @param id - job to cancel. + * @param options - cancellation reason. + * @returns `requested` for live work, otherwise `already-finished`. + */ + kill(id: JobId, options?: JobKillOptions): 'requested' | 'already-finished' + /** + * Wait for settlement or timeout without cancelling the job. Caller abort + * rejects only while the job is live; after settlement the terminal + * projection wins. Throws for an invalid timeout. + * @param id - job to wait for. + * @param timeoutMs - positive finite wait bound in milliseconds. + * @param signal - optional cancellation of the wait itself. + * @returns projection at settlement or timeout. + */ + wait(id: JobId, timeoutMs: number, signal?: AbortSignal): Promise } ``` +## 事件 + +注册表通过一条带过滤的流宣布每次提交。生命周期事件携带其所宣布的提交之后的投影;`settled` 标出原因,完成播报方据此跳过 teardown;`output` 只携带 id 与新的 total,观察者从自己的游标读取,注册表从不推送负载。 + +```ts type-equiv +/** + * One lifecycle or output event. Lifecycle events carry the job's projection + * after the commit they announce; `output` carries only the id and the new + * total, so an observer schedules a {@link VisibleJobs.readAt} from its own + * cursor and the registry never pushes payloads. + */ +type JobEvent = + | { + /** Registration commit, progress line change, stopping transition, or removal from the visible set. */ + readonly type: 'registered' | 'progress' | 'stopping' | 'removed' + readonly job: JobView + } + | { + readonly type: 'settled' + readonly job: JobView + readonly cause: JobSettleCause + } + | { + readonly type: 'output' + readonly id: JobId + /** Owning session, absent for an unowned job. */ + readonly owner?: SessionId + /** The ring's total after the append (or at settlement, which ends the stream). */ + readonly total: number + } +``` + +```ts type-equiv +/** + * Who a subscription hears about. `{ owner }` delivers that session's jobs + * plus every unowned job (the set that session can see). `{ owners: 'scope' }` + * delivers the owners composed under the subscribing context — one registry + * serves every composition in the process, and a mount under one preset must + * not hear another preset's agents. `{ owners: 'all' }` delivers everything. + */ +type JobEventFilter = + | { readonly owner: SessionId } + | { readonly owners: 'all' | 'scope' } +``` + ## 服务行为 -抽象的 [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition 规定了原子化的 `start`、按调用方划定的 `get` 与 `list`、`read`、非消耗的 `readRecord`、`kill`、有界的 `wait`、故障隔离的 `onJobDone`、`onJobsChanged` 与 `onOutput` 监听器,以及 `attachController`;[`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) 是进程本地的 Service Provider。授权比较 owner 会话;owner 清理与准入使用注册在案的确切 `Agent` 实例。本地 provider 的正安全整数配置 `maxConcurrentJobsPerOwner` 默认 `10`,按确切 owner 统计 `running` 加 `stopping` 记录,无主任务共享一个桶;生产方终态结算释放容量,`retainBytes`(默认 262144)与 `settledRetainBytes`(默认 16384)约束每个已声明 record 的运行期与结算后保留量。参见 [`dsh-jobs`](../../packages/jobs/jobs/README.zh.md)(Service Definition 契约)、[`dsh-jobs-local`](../../packages/jobs/jobs-local/README.zh.md)(注册表生命周期与准入策略)与 [`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.zh.md)(模型侧 Consumer)。 +抽象的 [`JobRegistry`](../../packages/jobs/jobs/src/index.ts) Service Definition 规定了原子化的 `start`、绑定调用方的 `visibleTo`(`list`、`get`、消耗式 `read`、非消耗的 `readAt`、`kill` 与有界的 `wait`)、带过滤的 `events` 流,以及 `attachController`;[`LocalJobRegistry`](../../packages/jobs/jobs-local/src/index.ts) 是进程本地的 Service Provider。授权比较拥有者会话;拥有者清理与准入使用 job 启动时登记在该拥有者会话下的活体 `Agent`。本地提供方的正安全整数配置 `maxConcurrentJobsPerOwner` 默认为 `10`,按精确拥有者统计 `running` 加 `stopping` 记录,无主任务共享一个桶;生产方的终态结算释放容量;`retainBytes`(默认 262144)与 `settledRetainBytes`(默认 16384)约束每个环的运行期与结算后保留量,`pumpPollMs`(默认 150)是拉取节奏。参见 [`dsh-jobs`](../../packages/jobs/jobs/README.zh.md) 了解 Service Definition 约定,[`dsh-jobs-local`](../../packages/jobs/jobs-local/README.zh.md) 了解注册表生命周期与准入策略,[`dsh-tool-jobs`](../../packages/jobs/tool-jobs/README.zh.md) 了解面向模型的 Consumer。 @@ -275,11 +383,21 @@ Host service backing the generated `ctx.remote.job` namespace. ```ts cordis-catalog /** - * Stream one job's retained record output from an absolute byte offset, - * then its terminal status once settled and drained. Non-consuming: the + * Stream the jobs one session can see — its own plus every unowned job — + * as whole-set frames: one on open, then one after each coalesced burst of + * lifecycle commits. The stream has no natural end; the carrier closes it. + * @param request - the session whose visible set to mirror. + * @param signal - cancellation owned by the Remote stream carrier. + * @returns the roster frames. + */ +@Remote({ mode: 'stream' }) rows(request: JobRowsRequest, signal: AbortSignal): AsyncIterable + +/** + * Stream one job's retained output from an absolute byte offset, then its + * terminal projection once settled and drained. Non-consuming: the * model-facing cursor and notice state never observe these reads. The - * request's session resolves the fenced-read caller; the registry rejects a - * job the session does not own, a job without a record, or an unknown job. + * request's session is the fenced read's caller; the registry rejects a + * job the session cannot see and an unknown job. * @param request - target job, owning session, and optional resume offset. * @param signal - cancellation owned by the Remote stream carrier. * @returns anchor, coalesced output frames, and the terminal status. @@ -293,16 +411,16 @@ Source: [`packages/api/job-controller/src/index.ts`](../../packages/api/job-cont ### `ctx.jobs` — `JobRegistry` (abstract seam) -Abstract background job registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior). +Abstract background job registry. Subclass, implement the abstract members, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior). Implementations must honor these semantics: -- Registrations outlive producer and controller fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record. Teardown cancellation also marks the record reported, because a record its owner is being destroyed for has no reader left. +- Registrations outlive producer and controller fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record. Such settlements announce `cause: 'teardown'`, because a job whose owner is being destroyed has no reader left. - Owned-job access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary. -- Settlement is first-wins: one terminal record, released waiters, and one round of contained listener notification, even against a late producer outcome. Completion is announced last, after the record is committed and every other observer of the settlement has seen it, because a reporter may open a model turn synchronously. -- start refuses work while no attached job controller serves the spec's owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and completion-listener delivery — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition's scope serve exactly the agents composed under it. -- Record observation never consumes. Any number of readRecord readers hold their own absolute byte offsets; a record read changes no cursor and no notice state, so the model-facing surfaces (the consuming read, completion notices) are unaffected. -- Record retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement — the producer outcome, a kill, or teardown — trims retention to the settled cap and ends the stream; the record has no separate lifecycle. +- Settlement is first-wins: one terminal record, released waiters, then one round of contained event delivery, even against a late producer outcome. The `settled` event follows every released waiter, so a consumer that claims a settlement while waiting always claims before the event. +- start refuses work while no attached job controller serves the spec's owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and event delivery under `{ owners: 'scope' }` — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition's scope serve exactly the agents composed under it. +- Every job owns one output ring. Pull sources named by the spec are pumped by the registry and drained once more before settlement; pushed appends land whole. The model's consuming cursor and observers' absolute offsets read the same bytes and never disturb each other. +- Ring retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement trims retention to the settled cap and ends the stream; the ring has no separate lifecycle. ```ts cordis-catalog /** @@ -310,120 +428,20 @@ Implementations must honor these semantics: * admission before starting and atomically registering work. Any preflight * rejection leaves no job id or execution resource. A throwing starter * leaves nothing registered; after it returns, registration cannot fail. - * Settlement records the outcome, notifies listeners, and releases waiters. - * @param spec - job identity, owner, and synchronous starter. + * @param spec - job identity, owner, output sources, and synchronous starter. * @returns the registry-issued `-N` id. */ -abstract start(spec: JobStart): JobId +abstract start(spec: JobSpec): JobId /** - * List caller-owned and unowned jobs in registration order without exposing - * another session's labels. - * @param caller - reading agent; a non-agent caller sees only unowned jobs. - * @returns fresh snapshots. + * Bind the caller's identity once and return its operations. A caller sees + * its own jobs and every unowned job; a caller-less view sees unowned jobs + * only. The view resolves visibility on every call, so it stays valid as + * jobs come and go. + * @param caller - the reading session, or undefined for an anonymous caller. + * @returns the operations available to that caller. */ -abstract list(caller?: Agent): JobSnapshot[] - -/** - * Return a non-consuming snapshot without changing its read cursor or notice - * state. Throws for an unknown or foreign job. - * @param id - job to look up. - * @param caller - reading agent checked against the owner. - * @returns a fresh snapshot. - */ -abstract get(id: JobId, caller?: Agent): JobSnapshot - -/** - * Read the next stream delta, or the idempotent final output after settlement. - * A terminal read marks the job reported. Throws for an unknown or foreign - * job. - * @param id - job to read. - * @param caller - reading agent checked against the owner. - * @returns output text and the post-read snapshot. - */ -abstract read(id: JobId, caller?: Agent): JobRead - -/** - * Request cancellation, then mark the job stopping and reported. A producer - * throw propagates without changing job state. Throws for an unknown or - * foreign job. - * @param id - job to cancel. - * @param caller - killing agent checked against the owner. - * @param reason - logged reason forwarded to the producer. - * @returns `requested` for live work, otherwise `already-finished`. - */ -abstract kill(id: JobId, caller?: Agent, reason?: string): 'requested' | 'already-finished' - -/** - * Wait for settlement or timeout without cancelling the job. Caller abort - * rejects only while the job is live; after settlement the terminal - * snapshot wins so a notice suppressed for this waiter is still delivered. - * Throws for invalid, unknown, or foreign input. - * @param id - job to wait for. - * @param timeoutMs - positive finite wait bound in milliseconds. - * @param caller - waiting agent checked against the owner. - * @param signal - optional cancellation of the wait itself. - * @returns snapshot at settlement or timeout. - */ -abstract wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise - -/** - * Register an effect-scoped completion listener. It receives the settlements - * of the owners its registering context's scope covers; each listener is - * contained; returned promises are observed but not awaited. No listener runs - * after service disposal. - * @param listener - receives each terminal snapshot and its exact owner. - * @returns disposer that unregisters the listener. - */ -abstract onJobDone(listener: JobDoneListener): () => void - -/** - * Register an effect-scoped observer of visible-set changes. It fires after - * every commit that changes what {@link list} returns for that owner — - * registration, every stopping transition (including the one teardown - * performs before it awaits a slow producer), settlement, owner-disposal - * removal, and the emptying that service disposal commits — so an observer - * re-reads rather than accumulating deltas. - * - * Delivery is owner-relative on the same terms as {@link onJobDone}: an - * observer registered from an unscoped context — a host composition's own - * carrier — sees every owner, while one registered under an agent - * composition's scope sees exactly the agents composed under it. - * - * This is not a superset of {@link onJobDone}: that one delivers the terminal - * record under first-wins semantics a job controller couples to notice - * delivery, while this one carries no delivery meaning and marks nothing - * reported. Listeners are contained and never awaited. - * @param listener - receives the owner whose visible set changed, or - * `undefined` when an unowned job changed and every caller's set did. - * @returns disposer that unregisters the listener. - */ -abstract onJobsChanged(listener: JobsChangedListener): () => void - -/** - * Read retained record output from an absolute byte offset without consuming - * it. Resume by passing a previous read's `next`; a foreign offset inside a - * retained chunk returns that whole chunk (its `at` may precede `from`). - * Never marks the job reported. Throws for an unknown or foreign job, a job - * without a {@link JobStart.record} declaration, or a negative or - * non-integer offset. - * @param id - job to read. - * @param from - absolute byte offset to read from (0 for the retained head). - * @param caller - reading agent checked against the owner. - * @returns retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag. - */ -abstract readRecord(id: JobId, from: number, caller?: Agent): JobRecordRead - -/** - * Register an effect-scoped observer of record advancement — one signal per - * committed append and one at settlement, carrying only the job id. A - * consumer schedules a {@link readRecord} from its own cursor; the registry - * never pushes payloads. Delivery is owner-relative on the same terms as - * {@link onJobsChanged}. Listeners are contained and never awaited. - * @param listener - receives the id whose record advanced. - * @returns disposer that unregisters the listener. - */ -abstract onOutput(listener: JobOutputListener): () => void +abstract visibleTo(caller?: SessionId): VisibleJobs /** * Attach an effect-scoped controller that can read and stop jobs. It serves the @@ -435,7 +453,7 @@ abstract onOutput(listener: JobOutputListener): () => void abstract attachController(name: string): () => void ``` -Types: [Agent](core.zh.md) +Types: [SessionId](core.zh.md) Source: [`packages/jobs/jobs/src/index.ts`](../../packages/jobs/jobs/src/index.ts) diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml index a70f3d6e35..d862a8995b 100644 --- a/docs/tool-catalog.i18n.yaml +++ b/docs/tool-catalog.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 docs/tool-catalog.md -tool-catalog.md: 416585106de28296a3105fafbbe6e4edc0d0f16b -tool-catalog.zh.md: 89d2e467863c09b78805fd9db8ec785ad7936a9d +tool-catalog.md: 5bc212bd17256443ba98141ba5952e17abcfd2fe +tool-catalog.zh.md: fbbc265ac30e461a93fcf2a948797dc0c8ca67ad diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 416585106d..5bc212bd17 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -35,7 +35,7 @@ This table connects model-visible tool names to the plugin package and service s | `@deepseek-ai/dsh-tool-session-query` | `session_event_read`, `session_event_search`, `session_event_trace`, `session_search`, `session_trace` | `ctx.tools`, `ctx.systemPrompt`, `ctx.sessionQuery`, `a calling Agent for workspace authority` | `tool/call`, `tool/result` | - | The five read-only tools hide provider cursors and authorize every result from the immutable calling agent session. The package is opt-in; compositions that need enforced deadlines or bounded inline output also mount the generic timeout or spill policies. | | `@deepseek-ai/dsh-tool-subagent` | `list_subagent_models`, `subagent` | `ctx.tools`, `ctx.subagents`, `ctx.systemPrompt`, `ctx.llm for model discovery and selected-route validation` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered delegation name is the load-time `toolName` config (default `subagent`); the default schema above has model selection off, while the discovery schema is shown as the fixed companion available in an enabled Session. Web presets sample the Plugins preference for each new top-level Session and preserve that decision for its child Sessions; `subagent_fork` remains fixed-route. Each instance independently controls whether it reads model-selection settings and its background behavior through `modelSelectionSettings`, `backgroundMode`, and `enableRunInBackground`. | | `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`, `list_agents`, `send_message` | `ctx.tools`, `ctx.subagents`, `ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`, `tool/result`, `child session events through ctx.subagents` | - | The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` and `interrupt_agent` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows use the sessionProjections and live Agent registries). | -| `@deepseek-ai/dsh-tool-jobs` | `job_kill`, `job_list`, `job_output` | `ctx.tools`, `ctx.jobs`, `ctx.systemPrompt` | `tool/call`, `tool/result`, `user/message via agent.inject() for background completion notices` | - | The kind-agnostic background-job controller: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the controller that arms producers' `ctx.jobs.start()`. | +| `@deepseek-ai/dsh-tool-jobs` | `job_kill`, `job_list`, `job_output` | `ctx.tools`, `ctx.jobs`, `ctx.agents`, `ctx.systemPrompt` | `tool/call`, `tool/result`, `user/message via agent.inject() for background completion notices` | - | The kind-agnostic background-job controller: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the controller that arms producers' `ctx.jobs.start()`. | | `@deepseek-ai/dsh-experimental-tool-agent-team` | `interrupt_agent`, `list_agents`, `send_message`, `spawn_teammate`, `team_task_create`, `team_task_get`, `team_task_list`, `team_task_update`, `wait_agent` | `ctx.tools`, `ctx.systemPrompt`, `ctx.agentTeams`, `an exact live Team member Agent` | `tool/call`, `team/member`, `team/message/queued`, `team/message/delivered`, `team/task`, `tool/result` | - | All nine tools are scoped to implicit Team Leads and durable teammates. The shipped dsh-base bundle keeps the package disabled; the documented Agent Teams profile patch enables it while disabling the legacy continuable-child control names. | | `@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. `allowParallelInProgress` is required with no default, so the catalog states its choice: `true`, whose description invites several `in_progress` items. A deployment choosing `false` receives the same tool with a description asking for exactly one active task. | | `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`, `ctx.workflowEngine`, `ctx.systemPrompt`, `a calling Agent (exec.agent parents the script children)` | `tool/call`, `tool/result` | - | - | diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md index 89d2e46786..fbbc265ac3 100644 --- a/docs/tool-catalog.zh.md +++ b/docs/tool-catalog.zh.md @@ -39,7 +39,7 @@ | `@deepseek-ai/dsh-tool-session-query` | `session_event_read`、`session_event_search`、`session_event_trace`、`session_search`、`session_trace` | `ctx.tools`、`ctx.systemPrompt`、`ctx.sessionQuery`、`a calling Agent for workspace authority` | `tool/call`、`tool/result` | - | 这 5 个只读工具会隐藏提供方游标,并根据不可变的调用 agent 会话为每个结果授权。该包需要选择启用;需要强制截止时间或限制行内输出的组合还会挂载通用超时或 spill 策略。 | | `@deepseek-ai/dsh-tool-subagent` | `list_subagent_models`、`subagent` | `ctx.tools`、`ctx.subagents`、`ctx.systemPrompt`、`用于模型发现和所选路由校验的 ctx.llm` | `tool/call`、`tool/result`、`child session events through the chosen provider` | `subagent`、`subagent_fork` | 注册的委派工具名称取决于加载时 `toolName` 配置(默认为 `subagent`);上述默认 schema 关闭模型选择,而发现 schema 则展示为已启用 Session 中可用的固定配套工具。Web preset 会在每个新顶层 Session 创建时读取插件页偏好,并为其子 Session 保留该决定;`subagent_fork` 始终使用固定路由。每个实例通过 `modelSelectionSettings`、`backgroundMode` 与 `enableRunInBackground` 独立控制是否读取模型选择设置及其后台行为。 | | `@deepseek-ai/dsh-tool-subagent-control` | `interrupt_agent`、`list_agents`、`send_message` | `ctx.tools`、`ctx.subagents`、`ctx.agents and ctx.sessionProjections (list_agents only)` | `tool/call`、`tool/result`、`child session events through ctx.subagents` | - | 这些是控制可继续后台 subagent 的全局命名工具:绑定提供方的 `tool-subagent` 实例注册不同的委派工具;本包注册一次 `send_message` 和 `interrupt_agent`,另由 `list_agents` 通过单独加载的 `/list-agents` 插件提供,其目录行使用 sessionProjections 和实时 Agent 注册表。 | -| `@deepseek-ai/dsh-tool-jobs` | `job_kill`、`job_list`、`job_output` | `ctx.tools`、`ctx.jobs`、`ctx.systemPrompt` | `tool/call`、`tool/result`、`user/message via agent.inject() for background completion notices` | - | 与任务种类无关的后台任务控制器:后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制器,从而启用生产方的 `ctx.jobs.start()`。 | +| `@deepseek-ai/dsh-tool-jobs` | `job_kill`、`job_list`、`job_output` | `ctx.tools`、`ctx.jobs`、`ctx.agents`、`ctx.systemPrompt` | `tool/call`、`tool/result`、`user/message via agent.inject() for background completion notices` | - | 与任务种类无关的后台任务控制器:后台 bash 命令、PTY 发送和 subagent 都通过相同的 3 个工具读取、列出和终止。加载该插件会挂接控制器,从而启用生产方的 `ctx.jobs.start()`。 | | `@deepseek-ai/dsh-experimental-tool-agent-team` | `interrupt_agent`、`list_agents`、`send_message`、`spawn_teammate`、`team_task_create`、`team_task_get`、`team_task_list`、`team_task_update`、`wait_agent` | `ctx.tools`、`ctx.systemPrompt`、`ctx.agentTeams`、`an exact live Team member Agent` | `tool/call`、`team/member`、`team/message/queued`、`team/message/delivered`、`team/task`、`tool/result` | - | 这 9 个工具限定于隐式 Team Lead 与持久 teammate 作用域。随产品发布的 dsh-base bundle 默认禁用该包;文档中的 Agent Teams profile patch 会启用它,并禁用旧 continuable child 的同名控制工具。 | | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`、`owning Agent session` | `tool/call`、`todo/write`、`tool/result` | - | todo_write 是会话所有的状态;UI 将最新的 todo/write 事件渲染为检查清单。`allowParallelInProgress` 是没有默认值的必填项,因此本目录明确选择 `true`,对应描述允许同时存在多个 `in_progress` 项。选择 `false` 的部署会获得同一工具,但描述会要求只能有 1 个活动任务。 | | `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`、`ctx.workflowEngine`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents the script children)` | `tool/call`、`tool/result` | - | - | diff --git a/packages/api/job-controller/src/client/model.ts b/packages/api/job-controller/src/client/model.ts index 2b58208bb0..cdcc884c9d 100644 --- a/packages/api/job-controller/src/client/model.ts +++ b/packages/api/job-controller/src/client/model.ts @@ -8,8 +8,9 @@ import { notifySubscribers } from '@deepseek-ai/dsh-client-store' import type { JobId } from '@deepseek-ai/dsh-jobs/brand' +import type { JobView } from '@deepseek-ai/dsh-jobs/view' import type { SessionId } from '@deepseek-ai/dsh-session/types' -import type { JobObserveFrame, JobView } from '../types.ts' +import type { JobObserveFrame } from '../types.ts' /** Bounded per-job render tail, in UTF-16 code units. */ const RENDER_TAIL_LIMIT = 128 * 1024 diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index ff56058008..3537921fee 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -1038,9 +1038,15 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ summary: 'Host service backing the generated `ctx.remote.job` namespace.', description: 'Host service backing the generated `ctx.remote.job` namespace.', methods: [ + { + signature: '@Remote({ mode: \'stream\' }) rows(request: JobRowsRequest, signal: AbortSignal): AsyncIterable', + description: 'Stream the jobs one session can see — its own plus every unowned job — as whole-set frames: one on open, then one after each coalesced burst of lifecycle commits. The stream has no natural end; the carrier closes it.', + parameters: [{ name: 'request', description: 'the session whose visible set to mirror.' }, { name: 'signal', description: 'cancellation owned by the Remote stream carrier.' }], + returns: 'the roster frames.', + }, { signature: '@Remote({ mode: \'stream\' }) observe(request: JobObserveRequest, signal: AbortSignal): AsyncIterable', - description: 'Stream one job\'s retained record output from an absolute byte offset, then its terminal status once settled and drained. Non-consuming: the model-facing cursor and notice state never observe these reads. The request\'s session resolves the fenced-read caller; the registry rejects a job the session does not own, a job without a record, or an unknown job.', + description: 'Stream one job\'s retained output from an absolute byte offset, then its terminal projection once settled and drained. Non-consuming: the model-facing cursor and notice state never observe these reads. The request\'s session is the fenced read\'s caller; the registry rejects a job the session cannot see and an unknown job.', parameters: [{ name: 'request', description: 'target job, owning session, and optional resume offset.' }, { name: 'signal', description: 'cancellation owned by the Remote stream carrier.' }], returns: 'anchor, coalesced output frames, and the terminal status.', }, @@ -1049,67 +1055,24 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ { key: 'jobs', summary: 'Abstract background job registry.', - description: 'Abstract background job registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis\' standard duplicate-service behavior).\n\nImplementations must honor these semantics:\n\n- Registrations outlive producer and controller fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record. Teardown cancellation also marks the record reported, because a record its owner is being destroyed for has no reader left.\n- Owned-job access is fenced by the owner\'s session id. Ids are predictable, so authorization — not secrecy — is the boundary.\n- Settlement is first-wins: one terminal record, released waiters, and one round of contained listener notification, even against a late producer outcome. Completion is announced last, after the record is committed and every other observer of the settlement has seen it, because a reporter may open a model turn synchronously.\n- start refuses work while no attached job controller serves the spec\'s owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and completion-listener delivery — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition\'s scope serve exactly the agents composed under it.\n- Record observation never consumes. Any number of readRecord readers hold their own absolute byte offsets; a record read changes no cursor and no notice state, so the model-facing surfaces (the consuming read, completion notices) are unaffected.\n- Record retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement — the producer outcome, a kill, or teardown — trims retention to the settled cap and ends the stream; the record has no separate lifecycle.', + description: 'Abstract background job registry. Subclass, implement the abstract members, and load the subclass as a plugin — it registers as `ctx.jobs` (one implementation per context; loading a second throws, which is cordis\' standard duplicate-service behavior).\n\nImplementations must honor these semantics:\n\n- Registrations outlive producer and controller fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record. Such settlements announce `cause: \'teardown\'`, because a job whose owner is being destroyed has no reader left.\n- Owned-job access is fenced by the owner\'s session id. Ids are predictable, so authorization — not secrecy — is the boundary.\n- Settlement is first-wins: one terminal record, released waiters, then one round of contained event delivery, even against a late producer outcome. The `settled` event follows every released waiter, so a consumer that claims a settlement while waiting always claims before the event.\n- start refuses work while no attached job controller serves the spec\'s owner, so a producer cannot start work that owner cannot collect or stop. One registry serves every composition in the process, so this question — and event delivery under `{ owners: \'scope\' }` — is owner-relative rather than process-wide: registrations made from an unscoped context serve every owner, and registrations made under an agent composition\'s scope serve exactly the agents composed under it.\n- Every job owns one output ring. Pull sources named by the spec are pumped by the registry and drained once more before settlement; pushed appends land whole. The model\'s consuming cursor and observers\' absolute offsets read the same bytes and never disturb each other.\n- Ring retention is bounded. Appends past the live cap drop the oldest retained bytes; a reader below the retained window gets a lossy read, never an error. Settlement trims retention to the settled cap and ends the stream; the ring has no separate lifecycle.', methods: [ { - signature: 'abstract start(spec: JobStart): JobId', - description: 'Preflight access, validation, owner cleanup, and implementation-owned admission before starting and atomically registering work. Any preflight rejection leaves no job id or execution resource. A throwing starter leaves nothing registered; after it returns, registration cannot fail. Settlement records the outcome, notifies listeners, and releases waiters.', - parameters: [{ name: 'spec', description: 'job identity, owner, and synchronous starter.' }], + signature: 'abstract readonly events: JobEvents', + description: 'Lifecycle and output events, filtered per subscription.', + parameters: [], + }, + { + signature: 'abstract start(spec: JobSpec): JobId', + description: 'Preflight access, validation, owner cleanup, and implementation-owned admission before starting and atomically registering work. Any preflight rejection leaves no job id or execution resource. A throwing starter leaves nothing registered; after it returns, registration cannot fail.', + parameters: [{ name: 'spec', description: 'job identity, owner, output sources, and synchronous starter.' }], returns: 'the registry-issued `-N` id.', }, { - signature: 'abstract list(caller?: Agent): JobSnapshot[]', - description: 'List caller-owned and unowned jobs in registration order without exposing another session\'s labels.', - parameters: [{ name: 'caller', description: 'reading agent; a non-agent caller sees only unowned jobs.' }], - returns: 'fresh snapshots.', - }, - { - signature: 'abstract get(id: JobId, caller?: Agent): JobSnapshot', - description: 'Return a non-consuming snapshot without changing its read cursor or notice state. Throws for an unknown or foreign job.', - parameters: [{ name: 'id', description: 'job to look up.' }, { name: 'caller', description: 'reading agent checked against the owner.' }], - returns: 'a fresh snapshot.', - }, - { - signature: 'abstract read(id: JobId, caller?: Agent): JobRead', - description: 'Read the next stream delta, or the idempotent final output after settlement. A terminal read marks the job reported. Throws for an unknown or foreign job.', - parameters: [{ name: 'id', description: 'job to read.' }, { name: 'caller', description: 'reading agent checked against the owner.' }], - returns: 'output text and the post-read snapshot.', - }, - { - signature: 'abstract kill(id: JobId, caller?: Agent, reason?: string): \'requested\' | \'already-finished\'', - description: 'Request cancellation, then mark the job stopping and reported. A producer throw propagates without changing job state. Throws for an unknown or foreign job.', - parameters: [{ name: 'id', description: 'job to cancel.' }, { name: 'caller', description: 'killing agent checked against the owner.' }, { name: 'reason', description: 'logged reason forwarded to the producer.' }], - returns: '`requested` for live work, otherwise `already-finished`.', - }, - { - signature: 'abstract wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise', - description: 'Wait for settlement or timeout without cancelling the job. Caller abort rejects only while the job is live; after settlement the terminal snapshot wins so a notice suppressed for this waiter is still delivered. Throws for invalid, unknown, or foreign input.', - parameters: [{ name: 'id', description: 'job to wait for.' }, { name: 'timeoutMs', description: 'positive finite wait bound in milliseconds.' }, { name: 'caller', description: 'waiting agent checked against the owner.' }, { name: 'signal', description: 'optional cancellation of the wait itself.' }], - returns: 'snapshot at settlement or timeout.', - }, - { - signature: 'abstract onJobDone(listener: JobDoneListener): () => void', - description: 'Register an effect-scoped completion listener. It receives the settlements of the owners its registering context\'s scope covers; each listener is contained; returned promises are observed but not awaited. No listener runs after service disposal.', - parameters: [{ name: 'listener', description: 'receives each terminal snapshot and its exact owner.' }], - returns: 'disposer that unregisters the listener.', - }, - { - signature: 'abstract onJobsChanged(listener: JobsChangedListener): () => void', - description: 'Register an effect-scoped observer of visible-set changes. It fires after every commit that changes what list returns for that owner — registration, every stopping transition (including the one teardown performs before it awaits a slow producer), settlement, owner-disposal removal, and the emptying that service disposal commits — so an observer re-reads rather than accumulating deltas.\n\nDelivery is owner-relative on the same terms as onJobDone: an observer registered from an unscoped context — a host composition\'s own carrier — sees every owner, while one registered under an agent composition\'s scope sees exactly the agents composed under it.\n\nThis is not a superset of onJobDone: that one delivers the terminal record under first-wins semantics a job controller couples to notice delivery, while this one carries no delivery meaning and marks nothing reported. Listeners are contained and never awaited.', - parameters: [{ name: 'listener', description: 'receives the owner whose visible set changed, or `undefined` when an unowned job changed and every caller\'s set did.' }], - returns: 'disposer that unregisters the listener.', - }, - { - signature: 'abstract readRecord(id: JobId, from: number, caller?: Agent): JobRecordRead', - description: 'Read retained record output from an absolute byte offset without consuming it. Resume by passing a previous read\'s `next`; a foreign offset inside a retained chunk returns that whole chunk (its `at` may precede `from`). Never marks the job reported. Throws for an unknown or foreign job, a job without a JobStart.record declaration, or a negative or non-integer offset.', - parameters: [{ name: 'id', description: 'job to read.' }, { name: 'from', description: 'absolute byte offset to read from (0 for the retained head).' }, { name: 'caller', description: 'reading agent checked against the owner.' }], - returns: 'retained chunks overlapping `[from, total)`, the resume offset, and the lossy flag.', - }, - { - signature: 'abstract onOutput(listener: JobOutputListener): () => void', - description: 'Register an effect-scoped observer of record advancement — one signal per committed append and one at settlement, carrying only the job id. A consumer schedules a readRecord from its own cursor; the registry never pushes payloads. Delivery is owner-relative on the same terms as onJobsChanged. Listeners are contained and never awaited.', - parameters: [{ name: 'listener', description: 'receives the id whose record advanced.' }], - returns: 'disposer that unregisters the listener.', + signature: 'abstract visibleTo(caller?: SessionId): VisibleJobs', + description: 'Bind the caller\'s identity once and return its operations. A caller sees its own jobs and every unowned job; a caller-less view sees unowned jobs only. The view resolves visibility on every call, so it stays valid as jobs come and go.', + parameters: [{ name: 'caller', description: 'the reading session, or undefined for an anonymous caller.' }], + returns: 'the operations available to that caller.', }, { signature: 'abstract attachController(name: string): () => void', @@ -4175,20 +4138,44 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'JobChannel', - declaration: 'export type JobChannel = \'stdout\' | \'stderr\';', + declaration: 'export type JobChannel = \'stdout\' | \'stderr\' | \'log\';', }, { - name: 'JobDoneListener', - declaration: 'export type JobDoneListener = (snapshot: JobSnapshot, owner: Agent | undefined) => void | PromiseLike;', + name: 'JobChunk', + declaration: 'export interface JobChunk {\n readonly at: number;\n readonly text: string;\n readonly channel?: JobChannel;\n readonly gapBefore?: true;\n}', + }, + { + name: 'JobEvent', + declaration: 'export type JobEvent = {\n readonly type: \'registered\' | \'progress\' | \'stopping\' | \'removed\';\n readonly job: JobView;\n} | {\n readonly type: \'settled\';\n readonly job: JobView;\n readonly cause: JobSettleCause;\n} | {\n readonly type: \'output\';\n readonly id: JobId;\n readonly owner?: SessionId;\n readonly total: number;\n};', + }, + { + name: 'JobEventFilter', + declaration: 'export type JobEventFilter = {\n readonly owner: SessionId;\n} | {\n readonly owners: \'all\' | \'scope\';\n};', + }, + { + name: 'JobEventListener', + declaration: 'export type JobEventListener = (event: JobEvent) => void;', + }, + { + name: 'JobEvents', + declaration: 'export interface JobEvents {\n subscribe(filter: JobEventFilter, listener: JobEventListener): () => void;\n}', + }, + { + name: 'JobHandle', + declaration: 'export interface JobHandle {\n readonly id: JobId;\n append(text: string, options?: JobAppendOptions): void;\n updateProgress(line: string): void;\n}', }, { name: 'JobHooks', - declaration: 'export interface JobHooks {\n cancel(reason?: string): void;\n done: Promise;\n readOutput?(): string;\n}', + declaration: 'export interface JobHooks {\n cancel(reason?: string): void;\n done: Promise;\n}', }, { name: 'JobId', declaration: 'export type JobId = Branded<\'JobId\'>;', }, + { + name: 'JobKillOptions', + declaration: 'export interface JobKillOptions {\n reason?: string;\n}', + }, { name: 'JobKind', declaration: 'export type JobKind = JobKindMap[keyof JobKindMap];', @@ -4199,55 +4186,55 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'JobObserveFrame', - declaration: 'export type JobObserveFrame = {\n readonly type: \'opened\';\n readonly jobId: JobId;\n readonly from: number;\n readonly earliest: number;\n readonly total: number;\n readonly status: JobObserveStatus;\n readonly detail?: string;\n} | {\n readonly type: \'output\';\n readonly chunks: readonly JobWireChunk[];\n readonly next: number;\n readonly lossy?: true;\n} | {\n readonly type: \'status\';\n readonly status: JobObserveStatus;\n readonly detail?: string;\n readonly finishedAt?: number;\n};', + declaration: 'export type JobObserveFrame = {\n readonly type: \'opened\';\n readonly job: JobView;\n readonly from: number;\n} | {\n readonly type: \'output\';\n readonly chunks: readonly JobChunk[];\n readonly next: number;\n readonly lossy?: true;\n} | {\n readonly type: \'status\';\n readonly job: JobView;\n};', }, { name: 'JobObserveRequest', declaration: 'export interface JobObserveRequest {\n readonly sessionId?: SessionId;\n readonly jobId: JobId;\n readonly from?: number;\n}', }, - { - name: 'JobObserveStatus', - declaration: 'export type JobObserveStatus = \'running\' | \'stopping\' | \'completed\' | \'killed\' | \'failed\';', - }, { name: 'JobOutcome', - declaration: 'export interface JobOutcome {\n status: \'completed\' | \'killed\' | \'failed\';\n detail?: string;\n output?: string;\n}', + declaration: 'export interface JobOutcome {\n status: \'completed\' | \'killed\' | \'failed\';\n detail?: string;\n result?: string;\n}', }, { - name: 'JobOutputListener', - declaration: 'export type JobOutputListener = (id: JobId) => void;', + name: 'JobOutputRead', + declaration: 'export interface JobOutputRead {\n chunks: readonly JobChunk[];\n next: number;\n lossy: boolean;\n}', + }, + { + name: 'JobOutputSource', + declaration: 'export interface JobOutputSource {\n channel?: JobChannel;\n read(fromByte: number): JobSourceRead;\n}', }, { name: 'JobRead', - declaration: 'export interface JobRead {\n text: string;\n snapshot: JobSnapshot;\n}', + declaration: 'export interface JobRead {\n chunks: readonly JobChunk[];\n lossy: boolean;\n result?: string;\n job: JobView;\n}', }, { - name: 'JobRecordChunk', - declaration: 'export interface JobRecordChunk {\n at: number;\n text: string;\n channel?: JobChannel;\n gapBefore?: true;\n}', + name: 'JobRowsFrame', + declaration: 'export interface JobRowsFrame {\n readonly type: \'rows\';\n readonly jobs: readonly JobView[];\n}', }, { - name: 'JobRecordRead', - declaration: 'export interface JobRecordRead {\n chunks: readonly JobRecordChunk[];\n next: number;\n lossy: boolean;\n}', + name: 'JobRowsRequest', + declaration: 'export interface JobRowsRequest {\n readonly sessionId: SessionId;\n}', }, { - name: 'JobsChangedListener', - declaration: 'export type JobsChangedListener = (owner: Agent | undefined) => void;', + name: 'JobSettleCause', + declaration: 'export type JobSettleCause = \'producer\' | \'kill\' | \'teardown\';', }, { - name: 'JobSnapshot', - declaration: 'export interface JobSnapshot {\n id: JobId;\n kind: JobKind;\n label: string;\n outputLimitBytes?: number;\n ownerSession?: SessionId;\n status: JobStatus;\n detail?: string;\n startedAt: number;\n finishedAt?: number;\n reported: boolean;\n outputTotal?: number;\n outputEarliest?: number;\n}', + name: 'JobSourceRead', + declaration: 'export interface JobSourceRead {\n text: string;\n nextOffset: number;\n lossy: boolean;\n}', }, { - name: 'JobStart', - declaration: 'export type JobStart = PlainJobStart | RecordingJobStart;', + name: 'JobSpec', + declaration: 'export interface JobSpec {\n kind: JobKind;\n label: string;\n owner?: SessionId;\n outputLimitBytes?: number;\n output?: readonly JobOutputSource[];\n run(job: JobHandle): JobHooks;\n}', }, { name: 'JobStatus', declaration: 'export type JobStatus = \'running\' | \'stopping\' | \'completed\' | \'killed\' | \'failed\';', }, { - name: 'JobWireChunk', - declaration: 'export interface JobWireChunk {\n readonly at: number;\n readonly text: string;\n readonly channel?: string;\n readonly gapBefore?: true;\n}', + name: 'JobView', + declaration: 'export interface JobView {\n readonly id: JobId;\n readonly kind: JobKind;\n readonly label: string;\n readonly owner?: SessionId;\n readonly outputLimitBytes?: number;\n readonly status: JobStatus;\n readonly progress?: string;\n readonly detail?: string;\n readonly startedAt: number;\n readonly finishedAt?: number;\n readonly output: {\n readonly total: number;\n readonly earliest: number;\n };\n}', }, { name: 'JsonSchemaNode', @@ -4537,10 +4524,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'PermissionSelect', declaration: 'export interface PermissionSelect {\n options: PresetOption[];\n currentValue: string;\n}', }, - { - name: 'PlainJobStart', - declaration: 'export interface PlainJobStart extends JobStartBase {\n record?: undefined;\n run(job: RunningJob): JobHooks;\n}', - }, { name: 'PostToolDecision', declaration: 'export type PostToolDecision = {\n kind: \'accept\';\n content?: ContentBlock[];\n value?: never;\n additionalContexts?: UserMessage[];\n} | {\n kind: \'accept\';\n value: JsonValue;\n content?: never;\n additionalContexts?: UserMessage[];\n} | {\n kind: \'block\';\n feedback: ContentBlock[];\n additionalContexts?: UserMessage[];\n};', @@ -4661,14 +4644,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'ReasoningEffortId', declaration: 'export type ReasoningEffortId = Branded<\'ReasoningEffortId\'>;', }, - { - name: 'RecordingJob', - declaration: 'export interface RecordingJob extends RunningJob {\n append(text: string, options?: JobAppendOptions): void;\n}', - }, - { - name: 'RecordingJobStart', - declaration: 'export interface RecordingJobStart extends JobStartBase {\n record: true;\n run(job: RecordingJob): JobHooks;\n}', - }, { name: 'RedactedSecret', declaration: 'export interface RedactedSecret {\n path: string[];\n set: boolean;\n}', @@ -4749,10 +4724,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'RunnerFailureRule', declaration: 'export interface RunnerFailureRule {\n allowedExitCodes?: readonly number[];\n fatalSignatures: readonly string[];\n informationalLines?: readonly string[];\n}', }, - { - name: 'RunningJob', - declaration: 'export interface RunningJob {\n readonly id: JobId;\n updateDetail(detail: string): void;\n}', - }, { name: 'SandboxEnforcement', declaration: 'export type SandboxEnforcement = \'full\' | \'partial\';', @@ -4863,11 +4834,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SessionControlBaseline', - declaration: 'export interface SessionControlBaseline {\n readonly queues: Readonly>;\n readonly jobs: Readonly>;\n readonly projections: Readonly>;\n}', + declaration: 'export interface SessionControlBaseline {\n readonly queues: Readonly>;\n readonly projections: Readonly>;\n}', }, { name: 'SessionControlFrame', - declaration: 'export type SessionControlFrame = {\n readonly type: \'baseline\';\n readonly value: SessionControlBaseline;\n} | {\n readonly type: \'queue\';\n readonly sessionId: SessionId;\n readonly items: readonly SessionQueuedItem[];\n} | {\n readonly type: \'jobs\';\n readonly sessionId: SessionId;\n readonly jobs: readonly SessionJob[];\n} | ({\n readonly type: \'projection\';\n} & SessionProjectionUpdate);', + declaration: 'export type SessionControlFrame = {\n readonly type: \'baseline\';\n readonly value: SessionControlBaseline;\n} | {\n readonly type: \'queue\';\n readonly sessionId: SessionId;\n readonly items: readonly SessionQueuedItem[];\n} | ({\n readonly type: \'projection\';\n} & SessionProjectionUpdate);', }, { name: 'SessionCreateRequest', @@ -4997,10 +4968,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'SessionInspection', declaration: 'export interface SessionInspection extends SessionStorageMetadata {\n readonly events: readonly SessionEvent[];\n}', }, - { - name: 'SessionJob', - declaration: 'export interface SessionJob {\n readonly id: JobId;\n readonly kind: string;\n readonly label: string;\n readonly status: \'running\' | \'stopping\' | \'completed\' | \'killed\' | \'failed\';\n readonly detail?: string;\n readonly startedAt: number;\n readonly finishedAt?: number;\n readonly record?: true;\n}', - }, { name: 'SessionLineageNode', declaration: 'export interface SessionLineageNode {\n session: SessionRecord;\n descendants: SessionLineageNode[];\n}', @@ -6009,6 +5976,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'VerifiedWebhookDelivery', declaration: 'export interface VerifiedWebhookDelivery {\n readonly kind: K;\n readonly source: WebhookSourceId;\n readonly deliveryId: WebhookDeliveryId;\n readonly event: WebhookEventOf;\n readonly receivedAt: number;\n}', }, + { + name: 'VisibleJobs', + declaration: 'export interface VisibleJobs {\n list(): JobView[];\n get(id: JobId): JobView;\n read(id: JobId): JobRead;\n readAt(id: JobId, from: number): JobOutputRead;\n kill(id: JobId, options?: JobKillOptions): \'requested\' | \'already-finished\';\n wait(id: JobId, timeoutMs: number, signal?: AbortSignal): Promise;\n}', + }, { name: 'WebBootBatch', declaration: 'export interface WebBootBatch {\n phase: WebBootBatchPhase;\n url: string;\n rev: string;\n entries: string[];\n}', diff --git a/packages/jobs/jobs-local/README.i18n.yaml b/packages/jobs/jobs-local/README.i18n.yaml index 9c5a47c63b..1405d2ee15 100644 --- a/packages/jobs/jobs-local/README.i18n.yaml +++ b/packages/jobs/jobs-local/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/jobs/jobs-local/README.md -README.md: 07772f3a8de79f4e812e5217843eb770925050fb -README.zh.md: bf728c5b935941ee3bb783866a9dbf09f7865d76 +README.md: 58a35e813af03a00cf978d001a12f26bbb848ff4 +README.zh.md: 486a9cef3813d4d07c328339ee179e08e97c98b3 diff --git a/packages/jobs/jobs-local/README.md b/packages/jobs/jobs-local/README.md index 07772f3a8d..58a35e813a 100644 --- a/packages/jobs/jobs-local/README.md +++ b/packages/jobs/jobs-local/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -`dsh-jobs-local` runs background jobs inside the harness process: work keeps running while the agent moves on, and the owning agent can read, wait on, list, and cancel it, with completion delivered as an in-session notice when `dsh-tool-jobs` is also mounted. It implements the `dsh-jobs` contract with in-memory records handed out as fresh snapshots, never live state. A per-owner concurrency limit (default 10) bounds how many jobs one agent can have running or stopping at once, and a job that declares a record keeps a bounded in-memory output ring (256 KiB live, trimmed to 16 KiB at settlement by default) that observers read at absolute offsets; jobs die with the harness process and are not durable across restarts. +`dsh-jobs-local` runs background jobs inside the harness process: work keeps running while the agent moves on, and the owning agent can read, wait on, list, and cancel it, with completion delivered as an in-session notice when `dsh-tool-jobs` is also mounted. It implements the `dsh-jobs` contract with in-memory records handed out as fresh projections, never live state. A per-owner concurrency limit (default 10) bounds how many jobs one agent can have running or stopping at once, and every job keeps a bounded in-memory output ring (256 KiB live, trimmed to 16 KiB at settlement) that the registry fills from the producer's pull sources at `pumpPollMs` (default 150 ms) and from pushed appends. ## Table of Contents @@ -33,7 +33,7 @@ Choose it when jobs should live in the harness process and die with it. Avoid it ### Minimal configuration -Loading the plugin registers `ctx.jobs`; `maxConcurrentJobsPerOwner` is optional and defaults to `10`. +Loading the plugin registers `ctx.jobs`; every field is optional. ```yaml - name: '@deepseek-ai/dsh-jobs-local' @@ -42,8 +42,9 @@ Loading the plugin registers `ctx.jobs`; `maxConcurrentJobsPerOwner` is optional | Field | Default | Meaning | |---|---|---| | `maxConcurrentJobsPerOwner` | `10` | Maximum `running` plus `stopping` jobs per exact owner, or in the shared unowned bucket | -| `retainBytes` | `262144` | Live record retention per job, in UTF-8 bytes | -| `settledRetainBytes` | `16384` | Record retention kept after a job settles, in UTF-8 bytes | +| `retainBytes` | `262144` | Live ring retention per job, in UTF-8 bytes | +| `settledRetainBytes` | `16384` | Ring retention kept after a job settles, in UTF-8 bytes | +| `pumpPollMs` | `150` | Poll interval for a job's pull sources, in milliseconds | The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-jobs-local) is the exhaustive source for the accepted fields. @@ -71,11 +72,11 @@ This section explains the design decisions behind the registry and points at the ### Design philosophy -- **In-memory records, fresh snapshots.** `LocalJobRegistry` keeps one `TrackedTask` per job — lifecycle state plus the optional record ring — and projects a new read-only snapshot or chunk copy per call; callers never receive live state. -- **Retention is bounded per record.** Appends past the live cap drop the oldest retained chunks (a single oversized chunk keeps its UTF-8-safe tail); a reader below the retained window gets a lossy read, never an error, and settlement trims to the settled cap. -- **Owner-relative layers, one process-wide registry.** Controllers, completion listeners, and change observers are filed into the scope that registered them (`ScopedLayers`), and reads union the global layer with the owner's scope chain — so one preset's job controls never hold `start()` open for an agent whose own composition loads none, and a settlement reaches only the listeners its owner's composition registered. +- **In-memory records, fresh projections.** `LocalJobRegistry` keeps one `TrackedJob` per job — lifecycle state, the output ring, and the model cursor — and projects a new read-only view or chunk copy per call; callers never receive live state. +- **Retention is bounded per ring.** Appends past the live cap drop the oldest retained chunks (a single oversized chunk keeps its UTF-8-safe tail); a reader below the retained window gets a lossy read, never an error, and settlement trims to the settled cap. +- **Owner-relative layers, one process-wide registry.** Controllers and `{ owners: 'scope' }` subscriptions are filed into the scope that registered them (`ScopedLayers`), and reads union the global layer with the owner's scope chain — so one preset's job controls never hold `start()` open for an agent whose own composition loads none, and a scoped settlement reaches only the listeners its owner's composition registered. - **Preflight before start.** `start()` checks controller service, spec validity, live ownership, and capacity before invoking the producer, so a rejection leaves no job id or execution resource; registration commits without a later failable step. -- **First-wins settlement, completion last.** The earliest terminal outcome records once, releases waiters, and notifies listeners once with per-listener containment; completion is announced after the record is committed and the visible-set change published, because a reporter may open a model turn synchronously. +- **First-wins settlement, event last.** The earliest terminal outcome records once, waits for the pump's final drain, trims the ring, releases waiters, and then delivers one `settled` event with per-listener containment, followed by the ring's final `output` signal. - **Teardown never deadlocks.** A throwing cancel force-fails the record and reports a possible orphan instead of stalling disposal. ### Source map @@ -83,19 +84,22 @@ This section explains the design decisions behind the registry and points at the | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | Plugin entry: `Config` schema, `LocalJobRegistry`, admission, lifecycle, teardown | +| [`src/events.ts`](src/events.ts) | Scope-layered event routing: `{ owner }`, `{ owners: 'all' }`, and `{ owners: 'scope' }` subscriptions | +| [`src/ring.ts`](src/ring.ts) | The bounded per-job output ring: append, retention trim, offset reads | +| [`src/pump.ts`](src/pump.ts) | The registry-owned pull pump: one timer per job, final drain before settlement | | — | No runtime invariant companion is published; `@deepseek-ai/dsh-jobs/invariant` owns per-snapshot identity, status, timestamp, and owner checks. This provider's admission decision uses private configuration and must fail before a backend starter runs; `LocalJobRegistry.start()` enforces it synchronously for current producers. Repeating an aggregate after publication would expose private configuration solely to this companion and would not verify the fail-closed pre-start guarantee. | ### Scope layers -`attachController`, `onJobDone`, `onJobsChanged`, and `onOutput` register into the calling context's scope layer. The controller question (`servesOwner`) and listener delivery (`listenersFor`, `changedFor`, `outputFor`) walk the same chain: global layer first, then each scoped layer along the owner's chain. Registrations are anonymous tokens so duplicate labels stay independently disposable. +`attachController` and `{ owners: 'scope' }` subscriptions register into the calling context's scope layer; `{ owner }` and `{ owners: 'all' }` subscriptions are unscoped. The controller question (`servesOwner`) and scoped delivery walk the same chain: global layer first, then each scoped layer along the owner's chain. Registrations are anonymous tokens so duplicate labels stay independently disposable. ### Admission and settlement -`activeTaskCount` counts authoritative records per exact owner or in the shared unowned bucket. `settle` marks a job reported when waiters are pending, trims a declared record to the settled cap, resolves every waiter, records the terminal snapshot, announces the visible-set change and the record's final output signal, then notifies completion listeners. Pending waits mark the job reported before listeners run so completion reporters do not duplicate notices; a teardown cancel marks it for the same reason — nothing will read a notice addressed to an owner being destroyed. +`activeTaskCount` counts authoritative records per exact owner or in the shared unowned bucket. `settle` records the terminal outcome once (merging a recorded kill reason into a `killed` detail), clears the progress line, trims the ring to the settled cap, resolves every waiter, then emits `settled` with its cause and the ring's final `output` signal. The cause is `kill` after `VisibleJobs.kill`, `teardown` after an owner or service cancel, and `producer` otherwise; `dsh-tool-jobs` uses it to skip notices nobody can read. ### Teardown -Owner disposal (`disposeOwned`) cancels the owner's jobs, awaits their settlement, removes their records, and announces the removal — the one visible-set change no per-job record carries. Service disposal (`disposeAll`) closes listeners, cancels all live jobs, awaits settlement, clears the store, announces the emptying to the distinct owners, then detaches the cross-fiber owner-cleanup effects. +Owner disposal (`disposeOwned`) cancels the owner's jobs, awaits their settlement, removes their records, and announces each removal — the one visible-set change no per-job record carries. Service disposal (`disposeAll`) cancels all live jobs, awaits settlement, removes every record (announcing each removal, so a subscriber mounted outside the service drops its rows), then detaches the cross-fiber owner-cleanup effects. @@ -106,7 +110,7 @@ Owner disposal (`disposeOwned`) cancels the owner's jobs, awaits their settlemen Read these pages when the package-level contract is not enough. They move from the registry contract to the model-facing controls and the design records. -- [Background task runtime subsystem](../../../docs/subsystems/jobs.md) — the job types, snapshot fields, and `ctx.jobs` cordis surface. +- [Background task runtime subsystem](../../../docs/subsystems/jobs.md) — the job types, projection fields, and `ctx.jobs` cordis surface. - [jobs group map](../README.md) — the sibling group page and its package table. - [Registry contract](../jobs/README.md) — the abstract `ctx.jobs` service this package implements. - [Model-facing job controls](../tool-jobs/README.md) — the `job_output`, `job_list`, and `job_kill` tools and completion notices. diff --git a/packages/jobs/jobs-local/README.zh.md b/packages/jobs/jobs-local/README.zh.md index bf728c5b93..486a9cef38 100644 --- a/packages/jobs/jobs-local/README.zh.md +++ b/packages/jobs/jobs-local/README.zh.md @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -`dsh-jobs-local` 在 harness 进程内运行后台任务:工作会在 agent 继续推进的同时保持运行,拥有它的 agent 可以读取、等待、列出和取消它;同时挂载 `dsh-tool-jobs` 时,完成以会话内通知送达。它用内存记录实现 `dsh-jobs` 约定,并且只交出全新快照,从不交出实时状态。按所有者的并发上限(默认 10)约束一个 agent 同时处于运行或停止中的任务数量,声明了 record 的任务另持有一个有界的内存输出环(默认运行期 256 KiB、结算时裁剪到 16 KiB),供观察者按绝对偏移读取;任务会随 harness 进程终止而消失,无法跨重启持久。 +`dsh-jobs-local` 在 harness 进程内运行后台任务:工作会在 agent 继续推进的同时保持运行,拥有它的 agent 可以读取、等待、列出和取消它;同时挂载 `dsh-tool-jobs` 时,完成以会话内通知送达。它用内存记录实现 `dsh-jobs` 约定,并且只交出全新投影,从不交出实时状态。按所有者的并发上限(默认 10)约束一个 agent 同时处于运行或停止中的任务数量;每个 job 保有一个有界的内存输出环(运行期 256 KiB,结算时裁剪到 16 KiB),注册表按 `pumpPollMs`(默认 150 毫秒)从生产方的拉取源以及推送的追加填充它。 ## 目录 @@ -33,7 +33,7 @@ kind: "package-reference" ### 最小配置 -加载插件即注册 `ctx.jobs`;`maxConcurrentJobsPerOwner` 可选,默认为 `10`。 +加载插件即注册 `ctx.jobs`;每个字段都是可选的。 ```yaml - name: '@deepseek-ai/dsh-jobs-local' @@ -42,8 +42,9 @@ kind: "package-reference" | 字段 | 默认值 | 含义 | |---|---|---| | `maxConcurrentJobsPerOwner` | `10` | 每个精确所有者,或共享的无主桶中,`running` 加 `stopping` 任务的最大数量 | -| `retainBytes` | `262144` | 每个任务 record 的运行期保留量,UTF-8 字节 | -| `settledRetainBytes` | `16384` | 任务结算后保留的 record 量,UTF-8 字节 | +| `retainBytes` | `262144` | 每个任务输出环的运行期保留量,UTF-8 字节 | +| `settledRetainBytes` | `16384` | 任务结算后保留的环容量,UTF-8 字节 | +| `pumpPollMs` | `150` | 任务拉取源的轮询间隔,毫秒 | 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-jobs-local)是每个受支持字段的穷尽式真源。 @@ -71,11 +72,11 @@ kind: "package-reference" ### 设计理念 -- **内存记录、全新快照。** `LocalJobRegistry` 为每个任务保存一份 `TrackedTask`——生命周期状态加可选的 record 环——每次调用都投影新的只读快照或块副本;调用方永远拿不到实时状态。 -- **record 保留量有界。** 追加超出运行期上限时丢弃最老的保留块(单个超限块保留其 UTF-8 安全尾部);低于保留窗口的读取得到 lossy 结果而非错误,结算时裁剪到结算上限。 -- **按所有者分层,一个进程级注册表。** 控制器、完成监听器与变更观察者归档到注册方所在的 scope(`ScopedLayers`),读取把全局层与所有者的 scope 链求并集——因此某个 preset 的任务控制绝不会为自身组合未加载任何控制器的 agent 保持 `start()` 可用,一次结算也只会抵达其所有者所属组合注册的监听器。 +- **内存记录、全新投影。** `LocalJobRegistry` 为每个任务保存一份 `TrackedJob`——生命周期状态、输出环与模型游标——每次调用都投影新的只读视图或块副本;调用方永远拿不到实时状态。 +- **环的保留量有界。** 追加超出运行期上限时丢弃最老的保留块(单个超限块保留其 UTF-8 安全尾部);低于保留窗口的读取得到 lossy 结果而非错误,结算时裁剪到结算上限。 +- **按所有者分层,一个进程级注册表。** 控制器与 `{ owners: 'scope' }` 订阅归档到注册方所在的 scope(`ScopedLayers`),读取把全局层与所有者的 scope 链求并集——因此某个 preset 的任务控制绝不会为自身组合未加载任何控制器的 agent 保持 `start()` 可用,一次带 scope 的结算也只会抵达其所有者所属组合注册的监听器。 - **启动前先预检。** `start()` 在调用生产方之前检查控制器服务、spec 有效性、仍存活的所有权与容量,因此拒绝不会留下 job id 或执行资源;注册一旦提交,后续不再有可失败步骤。 -- **结算首次优先,完成最后。** 最早的终止结果只记录一次,释放等待方,并只通知监听器一次,各监听器故障单独隔离;完成在记录提交且可见集变更发布之后才宣布,因为报告方可能同步开启一个模型轮次。 +- **结算首次优先,事件最后。** 最早的终止结果只记录一次,等待泵的最后一次排干,裁剪环,释放等待方,然后投递一次带逐监听器隔离的 `settled` 事件,再跟上环的最终 `output` 信号。 - **销毁永不死锁。** 抛出的取消会强制失败记录并报告可能的孤立工作,而不是让释放停滞。 ### 源码地图 @@ -83,19 +84,22 @@ kind: "package-reference" | 文件 | 职责 | |---|---| | [`src/index.ts`](src/index.ts) | 插件入口:`Config` schema、`LocalJobRegistry`、准入、生命周期、销毁 | +| [`src/events.ts`](src/events.ts) | 按 scope 分层的事件路由:`{ owner }`、`{ owners: 'all' }` 与 `{ owners: 'scope' }` 订阅 | +| [`src/ring.ts`](src/ring.ts) | 每个任务的有界输出环:追加、保留裁剪、按偏移读取 | +| [`src/pump.ts`](src/pump.ts) | 注册表拥有的拉取泵:每个任务一个定时器,结算前最后一次排干 | | — | 不发布运行时不变式伴生入口;快照检查位于 `dsh-jobs/invariant`。 | ### scope 分层 -`attachController`、`onJobDone`、`onJobsChanged` 与 `onOutput` 注册到调用上下文所在的 scope 层。控制器问题(`servesOwner`)与监听器投递(`listenersFor`、`changedFor`、`outputFor`)走同一条链:先是全局层,再沿所有者的链逐层。注册是无名 token,因此重复标签仍可独立释放。 +`attachController` 与 `{ owners: 'scope' }` 订阅注册到调用上下文所在的 scope 层;`{ owner }` 与 `{ owners: 'all' }` 订阅不带 scope。控制器问题(`servesOwner`)与带 scope 的投递走同一条链:先是全局层,再沿所有者的链逐层。注册是无名 token,因此重复标签仍可独立释放。 ### 准入与结算 -`activeTaskCount` 按精确所有者或共享无主桶统计权威记录。`settle` 在存在挂起等待方时把任务标为已报告,把已声明的 record 裁剪到结算保留量,解析每个等待方,记录终止快照,宣布可见集变更与 record 的最终输出信号,然后通知完成监听器。挂起的等待会在监听器运行前把任务标为已报告,因此完成报告方不会重复通知;销毁时的取消出于同样理由标记——面向正在被销毁的所有者的通知不会有人读到。 +`activeTaskCount` 按精确所有者或共享无主桶统计权威记录。`settle` 只记录一次终止结果(把记录下来的 kill 原因合并进 `killed` 的 detail),清除进度行,把环裁剪到结算保留量,解析每个等待方,然后发出带原因的 `settled` 与环的最终 `output` 信号。原因在 `VisibleJobs.kill` 之后为 `kill`,在所有者或服务取消之后为 `teardown`,否则为 `producer`;`dsh-tool-jobs` 据此跳过没人能读的通知。 ### 销毁 -所有者释放(`disposeOwned`)会取消该所有者的任务、等待其结算、移除其记录,并宣布移除——这是任何逐任务记录都无法表达的可见集变更。服务释放(`disposeAll`)会关闭监听器、取消所有存活任务、等待结算、清空存储、向不同的所有者宣布清空,然后分离跨 fiber 的所有者清理 effect。 +所有者释放(`disposeOwned`)会取消该所有者的任务、等待其结算、移除其记录,并逐条宣布移除——这是任何逐任务记录都无法表达的可见集变更。服务释放(`disposeAll`)会取消所有存活任务、等待结算、移除每条记录(逐条宣布移除,让挂载在服务之外的订阅者丢掉它的行),然后分离跨 fiber 的所有者清理 effect。 @@ -106,7 +110,7 @@ kind: "package-reference" 当包级约定不够用时阅读以下页面。它们从注册表约定逐步进入模型侧控制与设计记录。 -- [后台任务运行时子系统](../../../docs/subsystems/jobs.zh.md)——任务类型、快照字段与 `ctx.jobs` 的 cordis 接口面。 +- [后台任务运行时子系统](../../../docs/subsystems/jobs.zh.md)——任务类型、投影字段与 `ctx.jobs` 的 cordis 接口面。 - [jobs 组映射](../README.zh.md)——同级组页面及其包表格。 - [注册表约定](../jobs/README.zh.md)——本包实现的抽象 `ctx.jobs` 服务。 - [模型侧任务控制](../tool-jobs/README.zh.md)——`job_output`、`job_list` 与 `job_kill` 工具及完成通知。 diff --git a/packages/jobs/jobs-local/src/events.ts b/packages/jobs/jobs-local/src/events.ts index 333d5db5fc..8c13e4dd9c 100644 --- a/packages/jobs/jobs-local/src/events.ts +++ b/packages/jobs/jobs-local/src/events.ts @@ -23,7 +23,9 @@ interface Subscription { * by a name a second registrant could shadow. */ export class JobLayer implements ScopeLayer { + /** Tokens of the job controllers attached from this scope. */ readonly controllers = new AnonymousEntries() + /** The `{ owners: 'scope' }` subscriptions registered from this scope. */ readonly scoped = new AnonymousEntries() isEmpty(): boolean { diff --git a/packages/jobs/jobs/README.i18n.yaml b/packages/jobs/jobs/README.i18n.yaml index 54d4ecc8e9..ca8c2269ef 100644 --- a/packages/jobs/jobs/README.i18n.yaml +++ b/packages/jobs/jobs/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/jobs/jobs/README.md -README.md: 5d4e10de9fa852dc4a38c521321bae53c744909b -README.zh.md: b584191a6b94e79ba8908875e7a0706a525edf4f +README.md: 4a82606f7988827ce8279c649f0fe1caeb34745e +README.zh.md: 56e4711acd550b7cb1278739cb60415c9e7ad065 diff --git a/packages/jobs/jobs/README.md b/packages/jobs/jobs/README.md index 5d4e10de9f..4a82606f79 100644 --- a/packages/jobs/jobs/README.md +++ b/packages/jobs/jobs/README.md @@ -1,5 +1,5 @@ --- -description: "The background-job registry contract for users and maintainers composing, implementing, or debugging background work: ids, ownership, lifecycle, and completion listeners." +description: "The background-job registry contract for users and maintainers composing, implementing, or debugging background work: ids, ownership, lifecycle, the output ring, and the event stream." kind: "package-reference" --- @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -`dsh-jobs` lets tools run long work as background jobs: the work gets a stable `-N` id, keeps running while the agent moves on, and the owning agent can read its output, wait for it with a timeout, or request cancellation at any time. Jobs belong to the agent session that started them, so one agent's work is never visible to another, and completion reaches the owner as an in-session notice rather than by polling. A producer can also declare a per-job observation record: an append-only bounded output stream that any number of observers (the Web client) read at absolute byte offsets without touching the model-facing consuming cursor. This package ships the contract only: the process-local registry lives in `dsh-jobs-local`, and the model-facing controls and completion notices live in `dsh-tool-jobs`. Load an implementation to get background jobs; without one, `ctx.jobs` does not exist and `start()` cannot run. +`dsh-jobs` lets tools run long work as background jobs: the work gets a stable `-N` id, keeps running while the agent moves on, and the owning agent can read its output, wait for it with a timeout, or request cancellation at any time. Jobs belong to the agent session that started them, so one agent's work is never visible to another, and completion reaches the owner as an in-session notice rather than by polling. Every job owns one bounded output ring: the registry pumps the producer's pull sources into it and accepts pushed appends, the model consumes it through a registry-kept cursor, and any number of observers (the Web client) read it at absolute byte offsets without touching that cursor. ## Table of Contents @@ -29,9 +29,9 @@ Use this package when you are composing a background-job capability or writing a ### What a background job gives you -A producer registers work with a kind and a one-line label; the registry returns a `-N` id such as `bash-1`. Anyone who owns the job can read output, list jobs, wait up to a timeout for settlement, and request cancellation — each call returns a fresh snapshot of the job's status, from `running` and `stopping` to the terminal `completed`, `killed`, or `failed`. When a job settles, the owning agent is notified through the completion listener that `dsh-tool-jobs` turns into an in-session notice, so no polling is needed. A producer may attach an optional byte cap so each complete model-facing output read or completion notice stays bounded. +A producer registers work with a kind and a one-line label; the registry returns a `-N` id such as `bash-1`. Anyone who owns the job can read output, list jobs, wait up to a timeout for settlement, and request cancellation — each call returns a fresh projection of the job's status, from `running` and `stopping` to the terminal `completed`, `killed`, or `failed`. When a job settles, the registry's event stream announces it and `dsh-tool-jobs` turns the settlement into an in-session notice, so no polling is needed. A producer may attach an optional byte cap so each complete model-facing read or notice stays bounded. -A producer that declares `record: true` additionally streams raw output into the job's bounded record through the `RecordingJob` face its starter receives — a start without the declaration receives the plain `RunningJob` face, which has no `append`: observers read retained chunks at absolute byte offsets and get signaled on advancement, the settlement that ends the job also ends the stream, and `updateDetail` publishes a live progress line into every snapshot. The record is invisible to the model: reads consume nothing and never touch notice state. +A producer streams output by naming pull sources on its spec — non-consuming offset readers the registry pumps at its own cadence — or by pushing chunks through the `JobHandle` its starter receives; both land in the job's bounded ring, where `stdout` and `stderr` chunks reach the model and `log` chunks reach observers only. Observers read retained chunks at absolute byte offsets and are signaled on advancement; the settlement that ends the job also ends the stream, and `updateProgress` publishes a live progress line into every projection until then. Observation is invisible to the model: `readAt` consumes nothing and never touches notice state. ### The ownership boundary @@ -69,7 +69,7 @@ This section explains the design decisions behind the contract and points at the - **Contract and implementation are separate packages.** `JobRegistry` is an abstract Cordis service; loading the class directly throws, so a misconfigured composition fails at load instead of registering an empty `ctx.jobs`. - **One registry per process, owner-relative answers.** One instance serves every composition in the process, so registrations and deliveries are relative to the registering scope: a controller or listener registered from an unscoped context serves every owner; one registered under an agent composition's scope serves exactly the agents composed under it. - **Access is fenced by the owner's session id.** Ids are predictable, so authorization — not secrecy — is the boundary. -- **Settlement is first-wins, and completion is announced last.** One terminal record, released waiters, and one round of contained listener notification; completion is announced after the record is committed and every other observer has seen it, because a reporter may open a model turn synchronously. +- **Settlement is first-wins, and its event follows every released waiter.** One terminal record, released waiters, then one round of contained event delivery; a consumer that claims a settlement while waiting therefore always claims before the event, so `dsh-tool-jobs` never announces a completion the model already collected. - **Registrations outlive producer and controller fibers.** Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record. ### Source map @@ -77,14 +77,14 @@ This section explains the design decisions behind the contract and points at the | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | Plugin entry: the abstract `JobRegistry` service and its contract | -| [`src/types.ts`](src/types.ts) | Shared vocabulary: `JobKindMap`, `JobStart`, `JobHooks`, `RunningJob`, `RecordingJob`, `JobSnapshot`, listener types | +| [`src/types.ts`](src/types.ts) | Shared vocabulary: `JobSpec`, `JobHandle`, `JobHooks`, `JobOutcome`, `VisibleJobs`, `JobEvent`, and the read results | +| [`src/view.ts`](src/view.ts) | Client-safe leaf: `JobView`, `JobChunk`, `JobStatus`, and the merge-extensible `JobKindMap` | | [`src/brand.ts`](src/brand.ts) | `JobId` branded identifier, importable without the agent dependency | -| [`src/pump.ts`](src/pump.ts) | `pumpJobOutput`: poll pump copying producer offset-readers into a job record | -| [`src/invariant.ts`](src/invariant.ts) | Invariant companion: validates snapshot identity, status, timestamps, owner, and record-offset fields | +| [`src/invariant.ts`](src/invariant.ts) | Invariant companion: validates every projection the registry hands out — identity, status, timestamps, owner, and ring offsets | ### Service operations -Every operation is a thin projection over the registered jobs: `get` and `list` return non-consuming snapshots, `read` advances the single stream cursor, `readRecord` reads retained record chunks at an absolute offset without consuming anything, `kill` invokes producer cancellation before changing status, `wait` blocks up to a timeout, and `start()` preflights access, validation, and admission before invoking the producer's `run()` once while refusing any owner no attached controller serves; listeners observe terminal records, visible-set changes, and record advancement at owner granularity, and `attachController` scopes controller availability to its effect lifetime. Exact signatures and behavior live in the JSDoc on [`src/index.ts`](src/index.ts) and the generated [`ctx.jobs` cordis surface](../../../docs/subsystems/jobs.md). +Every operation is a thin projection over the registered jobs, bound to one caller by `visibleTo`: `list` and `get` return fresh projections, `read` advances the model's cursor and hands out the producer's result once after settlement, `readAt` reads retained chunks at an absolute offset without consuming anything, `kill` invokes producer cancellation before changing status and records the reason for the terminal `detail`, `wait` blocks up to a timeout, and `start()` preflights access, validation, and admission before invoking the producer's `run()` once while refusing any owner no attached controller serves; `events.subscribe` delivers registration, progress, stopping, settlement, removal, and output commits at owner, scope, or process granularity. @@ -95,12 +95,13 @@ Every operation is a thin projection over the registered jobs: `get` and `list` Read these pages when the package-level contract is not enough. They move from the job types to the shipped implementation, the model-facing controls, and the design records. -- [Background task runtime subsystem](../../../docs/subsystems/jobs.md) — the job types, snapshot fields, and `ctx.jobs` cordis surface. +- [Background task runtime subsystem](../../../docs/subsystems/jobs.md) — the job types, projection fields, and `ctx.jobs` cordis surface. - [jobs group map](../README.md) — the sibling group page and its package table. - [Process-local registry](../jobs-local/README.md) — the shipped implementation that runs jobs in this process. - [Model-facing job controls](../tool-jobs/README.md) — the `job_output`, `job_list`, and `job_kill` tools and completion notices. - [Generic long-running tool runtime Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md) — the design behind the background-job runtime. - [job-registry seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-job-registry-seam.md) — the owner-fenced registry contract and its rationale. +- [Jobs seam consolidation Agent Note](../../../.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.md) — one output ring, one projection, one event stream. ----- @@ -120,8 +121,8 @@ No direct invalidation; the named consumers own any request-prefix changes. These limits define when the contract is a poor fit. They are current package constraints, not a task backlog. -- **The contract is in-process** — `JobStart.run()` passes callbacks and exact `Agent` objects; a durable or cross-process backend must reshape identity, restart, ownership, and observation semantics before it can implement this seam. -- **Stream output has one consuming cursor** — the model owns it; independent observers read the job's declared record through the non-consuming `readRecord` instead. +- **The contract is in-process** — `JobSpec.run()` passes callbacks and the registry resolves the live `Agent` behind the owner session; a durable or cross-process backend must reshape identity, restart, ownership, and observation semantics before it can implement this seam. +- **The model's cursor is the only consuming read** — independent observers use the non-consuming `readAt` and never move it. - **Foreground work cannot be promoted** — producers choose foreground or background before starting. diff --git a/packages/jobs/jobs/README.zh.md b/packages/jobs/jobs/README.zh.md index b584191a6b..56e4711acd 100644 --- a/packages/jobs/jobs/README.zh.md +++ b/packages/jobs/jobs/README.zh.md @@ -1,5 +1,5 @@ --- -description: "后台任务注册表约定,供组合、实现或排查后台工作的用户与维护者阅读:id、归属、生命周期与完成监听器。" +description: "后台任务注册表约定,供组合、实现或排查后台工作的用户与维护者阅读:id、归属、生命周期、输出环与事件流。" kind: "package-reference" --- @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -`dsh-jobs` 让工具可以把长时间工作注册为后台任务:工作获得稳定的 `-N` id,在 agent 继续推进的同时保持运行,拥有它的 agent 可以随时读取输出、带超时等待或请求取消。任务属于启动它的 agent 会话,因此一个 agent 的工作永远不会被另一个 agent 看到;完成以会话内通知而非轮询的方式送达给拥有者。生产方还可以声明按 job 划分的观测 record:一条追加式的有界输出流,任意数量的观察者(Web 客户端)按绝对字节偏移读取,不触碰模型侧的消耗型游标。本包只提供约定:进程本地注册表位于 `dsh-jobs-local`,模型侧控制与完成通知位于 `dsh-tool-jobs`。加载一个实现才能获得后台任务;没有实现时 `ctx.jobs` 不存在,`start()` 无法运行。 +`dsh-jobs` 让工具可以把长时间工作注册为后台任务:工作获得稳定的 `-N` id,在 agent 继续推进的同时保持运行,拥有它的 agent 可以随时读取输出、带超时等待或请求取消。任务属于启动它的 agent 会话,因此一个 agent 的工作永远不会被另一个 agent 看到;完成以会话内通知而非轮询的方式送达给拥有者。每个 job 拥有一个有界的输出环:注册表把生产方的拉取源泵入其中并接受推送的追加,模型通过注册表保管的游标消耗它,任意数量的观察者(Web 客户端)按绝对字节偏移读取它而不触碰该游标。 ## 目录 @@ -29,9 +29,9 @@ kind: "package-reference" ### 后台任务提供什么 -生产方以 kind 和一行标签注册工作;注册表返回 `-N` id,例如 `bash-1`。拥有任务的任何一方都可以读取输出、列出任务、带超时等待结算或请求取消——每次调用都返回任务状态的全新快照,从 `running`、`stopping` 到终止态的 `completed`、`killed` 或 `failed`。任务结算时,拥有它的 agent 会通过 `dsh-tool-jobs` 转成会话内通知的完成监听器得到通知,因此无需轮询。生产方还可以附加可选的字节上限,让每次完整的模型侧输出读取或完成通知保持有界。 +生产方以 kind 和一行标签注册工作;注册表返回 `-N` id,例如 `bash-1`。拥有任务的任何一方都可以读取输出、列出任务、带超时等待结算或请求取消——每次调用都返回任务状态的全新投影,从 `running`、`stopping` 到终止态的 `completed`、`killed` 或 `failed`。任务结算时,注册表的事件流宣布它,`dsh-tool-jobs` 把结算变成会话内通知,因此无需轮询。生产方可以附加一个可选的字节上限,让每次完整的模型侧读取或通知保持有界。 -声明 `record: true` 的生产方还会通过 starter 收到的 `RecordingJob` 面(未声明的 start 收到的是没有 `append` 的普通 `RunningJob` 面)把原始输出流入该 job 的有界 record:观察者按绝对字节偏移读取保留块并在推进时收到信号,结束 job 的结算同时封流,`updateDetail` 把实时进度行发布进每个快照。record 对模型不可见:读取不消耗任何东西,也永不触碰通知状态。 +生产方通过在 spec 上声明拉取源——由注册表按自己的节奏泵送的非消耗偏移读取器——或经 starter 收到的 `JobHandle` 推送块来流式输出;二者都落入该 job 的有界环,其中 `stdout` 与 `stderr` 块到达模型,`log` 块只到达观察者。观察者按绝对字节偏移读取保留块并在推进时收到信号;结束 job 的结算同时封流,在此之前 `updateProgress` 把实时进度行发布进每个投影。观测对模型不可见:`readAt` 不消耗任何东西,也从不触碰通知状态。 ### 归属边界 @@ -69,7 +69,7 @@ kind: "package-reference" - **约定与实现分属不同包。** `JobRegistry` 是抽象 Cordis 服务;直接加载该类会抛出异常,因此错误配置的组合会在加载时失败,而不是注册一个空的 `ctx.jobs`。 - **每进程一个注册表,按所有者给出答案。** 一个实例服务进程内的每套组合,因此注册与投递都相对注册方所在 scope:从不带 scope 的上下文注册的控制器或监听器服务于每个所有者;在某套 agent 组合的 scope 下注册的,恰好服务于该组合下组合出的 agent。 - **访问以所有者的会话 id 为界。** id 可预测,因此是授权——而非保密——构成边界。 -- **结算首次优先,完成最后宣布。** 一条终止记录、释放的等待方,以及一轮受到隔离的监听器通知;完成在记录提交且该结算的所有其他观察者都已看到之后才宣布,因为报告方可能同步开启一个模型轮次。 +- **结算首次优先,其事件跟在每个被释放的等待方之后。** 一条终止记录、释放的等待方,然后是一轮受到隔离的事件投递;在等待中认领结算的消费方因此总是在事件之前认领,`dsh-tool-jobs` 永远不会播报模型已经收走的完成。 - **注册的存续期长于生产方与控制器 fiber。** 所有者与服务释放会取消正在运行的工作并等待守约的生产方;抛出异常的销毁取消只强制失败记录。 ### 源码地图 @@ -77,14 +77,14 @@ kind: "package-reference" | 文件 | 职责 | |---|---| | [`src/index.ts`](src/index.ts) | 插件入口:抽象 `JobRegistry` 服务及其约定 | -| [`src/types.ts`](src/types.ts) | 共享词汇:`JobKindMap`、`JobStart`、`JobHooks`、`RunningJob`、`RecordingJob`、`JobSnapshot`、监听器类型 | +| [`src/types.ts`](src/types.ts) | 共享词汇:`JobSpec`、`JobHandle`、`JobHooks`、`JobOutcome`、`VisibleJobs`、`JobEvent` 与读取结果 | +| [`src/view.ts`](src/view.ts) | 客户端安全叶子:`JobView`、`JobChunk`、`JobStatus` 与可合并扩展的 `JobKindMap` | | [`src/brand.ts`](src/brand.ts) | `JobId` 带类型标记的标识符,无需 agent 依赖即可导入 | -| [`src/pump.ts`](src/pump.ts) | `pumpJobOutput`:把生产方偏移读取器复制进 job record 的轮询泵 | -| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件:校验快照标识、状态、时间戳、所有者与 record 偏移字段 | +| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件:校验注册表交出的每个投影——标识、状态、时间戳、所有者与环偏移 | ### 服务操作 -每个操作都是已注册任务之上的薄投影:`get` 与 `list` 返回非消费式快照,`read` 推进唯一的流游标,`readRecord` 按绝对偏移读取保留的 record 块且不消耗任何东西,`kill` 在改变状态前调用生产方取消,`wait` 阻塞至超时,`start()` 在调用生产方 `run()` 一次之前预检访问、校验与准入,同时拒绝任何没有已附加控制器服务的所有者;监听器按所有者粒度观察终止记录、可见集变化与 record 推进,`attachController` 把控制器可用性限定在其 effect 生命周期内。确切签名与行为见 [`src/index.ts`](src/index.ts) 的 JSDoc 与生成的 [`ctx.jobs` cordis 接口面](../../../docs/subsystems/jobs.zh.md)。 +每个操作都是已注册任务之上的薄投影,由 `visibleTo` 绑定到一个调用方:`list` 与 `get` 返回全新投影,`read` 推进模型游标并在结算后把生产方的 result 交出一次,`readAt` 按绝对偏移读取保留块且不消耗任何东西,`kill` 在改变状态前调用生产方取消并为终态 `detail` 记录原因,`wait` 阻塞至超时,`start()` 在调用生产方 `run()` 一次之前预检访问、校验与准入,同时拒绝任何没有已附加控制器服务的所有者;`events.subscribe` 按所有者、scope 或进程粒度投递注册、进度、停止中、结算、移除与输出提交。 @@ -95,12 +95,13 @@ kind: "package-reference" 当包级约定不够用时阅读以下页面。它们从任务类型逐步进入随附实现、模型侧控制与设计记录。 -- [后台任务运行时子系统](../../../docs/subsystems/jobs.zh.md)——任务类型、快照字段与 `ctx.jobs` 的 cordis 接口面。 +- [后台任务运行时子系统](../../../docs/subsystems/jobs.zh.md)——任务类型、投影字段与 `ctx.jobs` 的 cordis 接口面。 - [jobs 组映射](../README.zh.md)——同级组页面及其包表格。 - [进程本地注册表](../jobs-local/README.zh.md)——在本进程中运行任务的随附实现。 - [模型侧任务控制](../tool-jobs/README.zh.md)——`job_output`、`job_list` 与 `job_kill` 工具及完成通知。 - [通用长时间运行工具运行时 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-generic-long-running-tool-runtime.zh.md)——后台任务运行时背后的设计。 - [任务注册表 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-job-registry-seam.zh.md)——按所有者隔离的注册表约定及其理由。 +- [jobs seam 收敛 Agent Note](../../../.agents/notes/implemented/architecture/2026-09-03-jobs-seam-consolidation.zh.md)——一个输出环、一个投影、一条事件流。 ----- @@ -120,8 +121,8 @@ kind: "package-reference" 这些限制说明约定何时不合适。它们是当前包约束,不是任务积压。 -- **约定是进程内的**——`JobStart.run()` 传入回调和确切的 `Agent` 对象;持久化或跨进程后端必须先重塑身份、重启、所有权与观察语义,才能实现此 seam。 -- **流输出只有一个消费游标**——它属于模型;独立观察者改用非消耗的 `readRecord` 读取 job 声明的 record。 +- **约定是进程内的**——`JobSpec.run()` 传入回调,注册表解析拥有者会话背后的活体 `Agent`;持久化或跨进程后端必须先重塑身份、重启、所有权与观察语义,才能实现此 seam。 +- **模型游标是唯一的消耗式读取**——独立观察者使用非消耗的 `readAt`,从不移动它。 - **前台工作无法转为后台**——生产方在启动前选择前台或后台。 diff --git a/packages/jobs/tool-jobs/README.i18n.yaml b/packages/jobs/tool-jobs/README.i18n.yaml index ca617bc8fb..df53b29100 100644 --- a/packages/jobs/tool-jobs/README.i18n.yaml +++ b/packages/jobs/tool-jobs/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/jobs/tool-jobs/README.md -README.md: bb9fea89b4aabe38296c01c910f36e99244680db -README.zh.md: 9820b1536f7f5c8860e7f67b1eee956e6d240462 +README.md: a596aad916f37a0a5778958d7b4cae966221ad3c +README.zh.md: 72fbe6c2d287649337ee41681b7b05c17ffb377a diff --git a/packages/jobs/tool-jobs/README.md b/packages/jobs/tool-jobs/README.md index bb9fea89b4..a596aad916 100644 --- a/packages/jobs/tool-jobs/README.md +++ b/packages/jobs/tool-jobs/README.md @@ -25,19 +25,19 @@ English | [中文](README.zh.md) ## Use this package -Load this plugin in any composition where the agent should start, observe, and stop background jobs: it registers the three tools, attaches the controller producers need, and delivers completion notices. It requires the `ctx.tools`, `ctx.jobs`, and `ctx.systemPrompt` services from the composed harness. +Load this plugin in any composition where the agent should start, observe, and stop background jobs: it registers the three tools, attaches the controller producers need, and delivers completion notices. It requires the `ctx.tools`, `ctx.jobs`, `ctx.agents`, and `ctx.systemPrompt` services from the composed harness. ### The three tools -- `job_output(job_id, wait?, timeout_ms?)` — Read a job's output. Stream jobs return only the output since the previous read; final-output jobs return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap and leaves a still-running job alive on timeout. +- `job_output(job_id, wait?, timeout_ms?)` — Read a job's output. Stream jobs return only the output since the previous read; final-output jobs return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap and leaves a still-running job alive on timeout. A read renders stdout first and stderr in one `[stderr]` section, notes output that left memory before the read, and carries a job's result (a subagent's answer) exactly once, on the first read after settlement. - `job_list()` — List your background jobs with their ids, kinds, and statuses, one per line: ` [] —
      • ) } - const open = !adding && editing?.provider === row.entry.provider + const open = !addOpen && editing?.provider === row.entry.provider const credentialConfigured = row.credential?.configured === true const credentialMissing = !credentialConfigured && row.apiKeyEnv !== undefined @@ -392,11 +412,10 @@ function Loaded({ injected, renderSlot }: { injected: ModelsSectionFace; renderS aria-label={providerCopy(t('editProvider'), target)} onClick={() => { setSavedTarget(undefined) - // One card at a time: leaving `declaring` set would show - // the create card beside this editor, and closing either - // one discards the other's draft. - setDeclaring(false) - setAdding(false) + // One card at a time: the add card closes with whatever + // it held, since closing either card would otherwise + // discard the other's draft. + setAddOpen(false) setEditing(open ? undefined : target) }} > @@ -443,110 +462,130 @@ function Loaded({ injected, renderSlot }: { injected: ModelsSectionFace; renderS })}
      - {addTarget !== undefined && addNamespace !== undefined + {addOpen ? (
      -
      - {t('provider')} - -
      - { closeEditor(changed, addTarget) }} - /> - {addRow === undefined - ? null - : renderSlot( - 'settings.models.provider-card', - { provider: addRow.entry, configured: addRow.configured, keyConfigured: keyConfiguredOf(addRow) }, - { entryKey: addRow.entry.settingsNs }, - )} + {catalogOffered && customOffered + ? ( +
      + { + setAddMode(next) + setVisited(previous => new Set([...previous, next])) + }} + /> +

      + {t(mode === 'catalog' ? 'addCatalogHint' : 'addCustomHint')} +

      +
      + ) + : null} + {visited.has('catalog') && addTarget !== undefined && addNamespace !== undefined + ? ( + + ) + : null} + {visited.has('custom') + ? ( + + ) + : null}
      ) - : declaring + : catalogOffered || customOffered ? ( -
      - row.entry.provider)} - protocols={protocols} - /* v8 ignore next -- the card only opens from a button disabled without this namespace */ - revision={state.namespaces.get('llm-pi-ai')?.revision ?? 0} - operations={operations} - t={t} - readOnly={!state.writable} - onClose={(changed) => { - setDeclaring(false) - if (changed) void controller.load() + // One entry for both ways to gain a provider; the card behind it + // splits them. Full width, so it lines up with the rows above. +
      +
      ) - : ( - // One row for the two ways to gain a provider: adopt one the - // adapter already knows, or declare one it does not. Side by side - // and equal-width so they read as siblings and line up with the - // rows above, rather than two pills of different lengths. -
      - {configurable.length > 0 && ( - - )} - {state.namespaces.has('llm-pi-ai') && ( - - )} -
      - )} + : null}
      {renderSlot('settings.models.footer', {})} {t('customApiUnset')} : null} - {protocols.map(choice => )} + {protocols.map(choice => )}
      ) diff --git a/packages/client/ui-settings-models/src/client/locales.ts b/packages/client/ui-settings-models/src/client/locales.ts index 2b0f92d8df..9cd6d52321 100644 --- a/packages/client/ui-settings-models/src/client/locales.ts +++ b/packages/client/ui-settings-models/src/client/locales.ts @@ -14,7 +14,12 @@ export const en = { deleteDescriptionWithCredential: 'Deleting {provider} removes its configuration and stored API key.', deleteConfirm: 'Delete {provider}', deleting: 'Deleting {provider}…', - add: 'Add provider', + add: 'Add model provider', + addMode: 'How to add', + addCatalog: 'Third-party model provider', + addCustom: 'Custom model API', + addCatalogHint: 'Pick OpenAI, Anthropic, Kimi, or another provider from the built-in catalog and enter its API key.', + addCustomHint: 'Connect a relay, a self-hosted server, or any other OpenAI- or Anthropic-compatible endpoint by its base URL, protocol, and models.', provider: 'Provider', close: 'Close', cancel: 'Cancel', @@ -79,8 +84,6 @@ export const en = { fetchSelectAll: 'Select all', fetchDeselectAll: 'Deselect all', fetchAdopt: 'Add selected', - customAdd: 'Add a custom provider', - customTitle: 'Custom provider', customTag: 'Custom', customRoute: 'Provider ID', customRouteHint: 'Lowercase identifier, starting with a letter, that uniquely names this provider in requests and as its credential name.', @@ -89,6 +92,9 @@ export const en = { customDisplayName: 'Display name', customApi: 'API protocol', customApiUnset: 'Not selected', + protocolOpenAiCompletions: 'OpenAI Chat Completions', + protocolOpenAiResponses: 'OpenAI Responses', + protocolAnthropicMessages: 'Anthropic Messages', customNeedsBaseUrl: 'A custom provider needs a base URL.', customBaseUrlInvalid: 'Enter a valid HTTP or HTTPS URL.', customNeedsModels: 'A custom provider needs at least one model.', @@ -116,7 +122,7 @@ export type ModelsKey = keyof typeof en export const zh: { [Key in keyof typeof en]: string } = { nav: '模型', title: '模型', - intro: '填入各提供方的 API 密钥即可使用其模型。', + intro: '填入各提供商的 API 密钥即可使用其模型。', edit: '编辑', editProvider: '编辑 {provider}', remove: '删除', @@ -126,8 +132,13 @@ export const zh: { [Key in keyof typeof en]: string } = { deleteDescriptionWithCredential: '删除 {provider} 会移除其配置和存储的 API 密钥。', deleteConfirm: '删除 {provider}', deleting: '正在删除 {provider}…', - add: '添加提供方', - provider: '提供方', + add: '添加模型提供商', + addMode: '添加方式', + addCatalog: '第三方模型提供商', + addCustom: '自定义模型 API', + addCatalogHint: '从内置目录中选择 OpenAI、Anthropic、Kimi 等提供商,填入其 API 密钥即可使用。', + addCustomHint: '连接中转站、自部署服务或其他兼容 OpenAI / Anthropic 协议的接口,需填写 API 地址、协议和模型。', + provider: '提供商', close: '关闭', cancel: '取消', apply: '保存', @@ -136,7 +147,7 @@ export const zh: { [Key in keyof typeof en]: string } = { credentialConfigured: 'API 密钥已配置', credentialMissing: 'API 密钥缺失', readOnly: '当前部署的设置文档为只读。', - loadFailed: '加载提供方目录失败', + loadFailed: '加载提供商目录失败', conflict: '这张卡片打开期间,这些设置已被其他地方改动。请关闭后重新打开,在当前值上编辑。', retry: '重试', keyInput: 'API 密钥', @@ -146,7 +157,7 @@ export const zh: { [Key in keyof typeof en]: string } = { keyEnvLocked: '由启动环境提供(只读)', customized: '自定义设置', baseUrl: 'API 地址', - baseUrlDefault: '提供方默认', + baseUrlDefault: '提供商默认', deepSeekChatBaseUrl: 'https://api.deepseek.com', deepSeekMessagesBaseUrl: 'https://api.deepseek.com/anthropic', deepSeekEndpointHint: '请填写与当前连接配置兼容的 API 地址。', @@ -159,9 +170,9 @@ export const zh: { [Key in keyof typeof en]: string } = { modelName: '显示名称', modelNamePlaceholder: '留空时使用模型 ID', contextWindow: '上下文窗口', - contextWindowPlaceholder: '使用提供方默认值', + contextWindowPlaceholder: '使用提供商默认值', maxTokens: '最大输出 token 数', - maxTokensPlaceholder: '使用提供方默认值', + maxTokensPlaceholder: '使用提供商默认值', modelAdvanced: '模型选项', modelInputTypes: '输入类型', modelInputText: '文本', @@ -170,7 +181,7 @@ export const zh: { [Key in keyof typeof en]: string } = { removeModel: '删除模型', modelsEmpty: '模型选择器中将不显示任何模型;目录外 ID 仍可直接发送。', keyBlank: '请输入 API 密钥;留空则保持已存储的密钥。', - keyBlankNew: '请输入 API 密钥;若该提供方以其他方式鉴权,可以留空。', + keyBlankNew: '请输入 API 密钥;若该提供商以其他方式鉴权,可以留空。', keyIllegalCharacters: '该 API 密钥格式错误,请检查。', modelIdRequired: '模型 ID 不能为空。', modelIdDuplicate: '模型 ID 不能重复。', @@ -181,33 +192,34 @@ export const zh: { [Key in keyof typeof en]: string } = { modelCapacityInvalid: '容量需为数字,可加 K 或 M 后缀。', modelDuplicate: '每个模型 ID 只能出现一次。', fetchModels: '获取可用模型', - fetching: '正在询问提供方\u2026', + fetching: '正在询问提供商\u2026', fetchNeedsBaseUrl: '请先填写 API 地址,再获取。', - fetchEmpty: '该提供方没有列出任何模型,请手动添加。', + fetchEmpty: '该提供商没有列出任何模型,请手动添加。', fetchTitle: '选择要添加的模型', - fetchDescription: '以下是模型提供方的可用模型,勾选要添加的模型。', + fetchDescription: '以下是模型提供商的可用模型,勾选要添加的模型。', fetchSearch: '搜索模型', fetchNoMatches: '没有匹配的模型。', fetchSelectAll: '全选', fetchDeselectAll: '取消全选', fetchAdopt: '添加所选', - customAdd: '添加自定义提供方', - customTitle: '自定义提供方', customTag: '自定义', customRoute: 'Provider ID', - customRouteHint: '以小写字母开头的标识,在请求中唯一标识该提供方,并用于派生凭据名。', + customRouteHint: '以小写字母开头的标识,在请求中唯一标识该提供商,并用于派生凭据名。', customRouteInvalid: '需以小写字母开头,之后可用小写字母、数字和短横线。', - customRouteTaken: '已有提供方使用了这个 ID。', + customRouteTaken: '已有提供商使用了这个 ID。', customDisplayName: '显示名称', customApi: 'API 协议', customApiUnset: '未选择', - customNeedsBaseUrl: '自定义提供方需要填写 API 地址。', + protocolOpenAiCompletions: 'OpenAI Chat Completions', + protocolOpenAiResponses: 'OpenAI Responses', + protocolAnthropicMessages: 'Anthropic Messages', + customNeedsBaseUrl: '自定义模型 API 需要填写 API 地址。', customBaseUrlInvalid: '请输入有效的 HTTP 或 HTTPS 地址。', - customNeedsModels: '自定义提供方至少需要一个模型。', + customNeedsModels: '自定义模型 API 至少需要一个模型。', customBaseUrlPlaceholder: 'https://gateway.example/v1', customAnthropicBaseUrlPlaceholder: 'https://gateway.example', settingsPathUnresolvable: '无法解析设置路径', - create: '创建提供方', + create: '创建提供商', creating: '创建中\u2026', welcomeTitle: '内测声明', welcomeBody: 'DeepSeek Harness 目前的 0.1 版本仍处在面向 Harness 开发者进行测试的阶段,还有许多地方需要持续改进和打磨,希望听取广大开发者的反馈建议。预计 DeepSeek Harness 的核心插件以及基础 API 都会在接下来的一段时间内快速迭代、持续演化。\n\n我们期待与全球开发者一起,在开源、开放、可复用、可组合的基础设施之上,共同探索智能上限。欢迎全球 Harness 开发者加入 DSH 插件生态。', diff --git a/packages/client/ui-settings-models/src/client/protocol-label.ts b/packages/client/ui-settings-models/src/client/protocol-label.ts new file mode 100644 index 0000000000..f65323f32c --- /dev/null +++ b/packages/client/ui-settings-models/src/client/protocol-label.ts @@ -0,0 +1,27 @@ +/** + * Product names for the wire protocols a pi-ai route may speak. The pickers + * show these instead of the schema identifiers (`openai-completions`), which + * are what `settings.yaml` carries and what the option values stay. + */ + +import type { ModelsKey } from './locales.ts' + +/** The protocols this page names, keyed by their schema identifier. */ +const PROTOCOL_LABEL_KEYS: Readonly> = { + 'openai-completions': 'protocolOpenAiCompletions', + 'openai-responses': 'protocolOpenAiResponses', + 'anthropic-messages': 'protocolAnthropicMessages', +} + +/** + * The picker text for one protocol identifier. + * @param t - section copy. + * @param protocol - the schema identifier of the protocol. + * @returns the product name this page knows the protocol by; a protocol the + * adapter adds before this page names it shows its identifier, the spelling + * `settings.yaml` needs anyway. + */ +export function protocolLabel(t: (key: ModelsKey) => string, protocol: string): string { + const key = PROTOCOL_LABEL_KEYS[protocol] + return key === undefined ? protocol : t(key) +} diff --git a/packages/client/ui-settings-models/tests/components.client.spec.tsx b/packages/client/ui-settings-models/tests/components.client.spec.tsx index e9cec03e60..125209e81b 100644 --- a/packages/client/ui-settings-models/tests/components.client.spec.tsx +++ b/packages/client/ui-settings-models/tests/components.client.spec.tsx @@ -46,6 +46,7 @@ function capacityInputs(label: string): HTMLInputElement[] { const PiAiConfig = Schema.object({ providers: Schema.dict(Schema.object({ apiKeyEnv: Schema.string().role('credential-ref'), + api: Schema.union(['openai-completions', 'openai-responses', 'anthropic-messages']), baseURL: Schema.string(), reasoning: Schema.union(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']), headers: Schema.dict(Schema.string()), @@ -307,12 +308,11 @@ async function mountDeepSeekCard(overrides: Parameters[0] = } describe('ModelsSection', () => { - it('hides both add actions when their settings namespaces are absent', async () => { + it('hides the add action when no settings namespace can open an editor', async () => { const scripted = scriptedFace() scripted.face.settings.describe.mockResolvedValue(remoteOk({ writable: true, hasDocument: false, namespaces: [] })) await mountFace(scripted) expect(screen.queryByRole('button', { name: en.add })).toBeNull() - expect(screen.queryByRole('button', { name: en.customAdd })).toBeNull() }) it('offers only providers whose settings namespace can open an editor', async () => { @@ -322,8 +322,11 @@ describe('ModelsSection', () => { namespaces: wireNamespaces().filter(view => view.ns !== 'llm-pi-ai'), })) await mountFace(scripted) - expect(screen.queryByRole('button', { name: en.customAdd })).toBeNull() fireEvent.click(screen.getByRole('button', { name: en.add })) + // Without the pi-ai namespace nothing can be hand-declared, so the card + // is the catalog form alone: no mode switch, no custom panel. + expect(screen.queryByRole('tablist')).toBeNull() + expect(screen.queryByRole('textbox', { name: en.customRoute })).toBeNull() expect(screen.queryByRole('option', { name: 'anthropic' })).toBeNull() expect(screen.getByRole('option', { name: 'plain' })).toBeTruthy() }) @@ -339,7 +342,6 @@ describe('ModelsSection', () => { fireEvent.click(screen.getByRole('button', { name: openaiCopy(en.editProvider) })) expect(await screen.findByLabelText(en.keyInput)).toBeTruthy() expect(screen.getByRole('button', { name: en.add })).toBeTruthy() - expect(screen.getByRole('button', { name: en.customAdd })).toBeTruthy() }) it('renders nothing before the slot injects its dependencies', () => { @@ -1437,6 +1439,88 @@ describe('ModelsSection', () => { expect(mutate).not.toHaveBeenCalled() }) + it('opens the add card on the catalog mode with both modes offered', async () => { + await mountSection() + fireEvent.click(screen.getByRole('button', { name: en.add })) + const modes = screen.getByRole('tablist', { name: en.addMode }) + expect(within(modes).getByRole('tab', { name: en.addCatalog }).getAttribute('aria-selected')).toBe('true') + expect(within(modes).getByRole('tab', { name: en.addCustom }).getAttribute('aria-selected')).toBe('false') + expect(screen.getByText(en.addCatalogHint)).toBeTruthy() + expect(screen.queryByText(en.addCustomHint)).toBeNull() + expect(screen.getByRole('combobox', { name: en.provider })).toBeTruthy() + // The custom panel is mounted but hidden, so its fields are not reachable. + expect(screen.queryByRole('textbox', { name: en.customRoute })).toBeNull() + }) + + it('switches between the modes without losing either draft', async () => { + await mountSection() + fireEvent.click(screen.getByRole('button', { name: en.add })) + fireEvent.change(screen.getByLabelText(en.keyInput), { target: { value: 'sk-catalog' } }) + + fireEvent.click(screen.getByRole('tab', { name: en.addCustom })) + expect(screen.getByText(en.addCustomHint)).toBeTruthy() + expect(screen.queryByText(en.addCatalogHint)).toBeNull() + expect(screen.queryByRole('combobox', { name: en.provider })).toBeNull() + fireEvent.change(screen.getByRole('textbox', { name: en.customRoute }), { target: { value: 'acme' } }) + + // Both panels stay mounted from here on, so the shown one is queried by name. + fireEvent.click(screen.getByRole('tab', { name: en.addCatalog })) + const catalog = screen.getByRole('tabpanel', { name: en.addCatalog }) + expect(within(catalog).getByLabelText(en.keyInput).value).toBe('sk-catalog') + fireEvent.click(screen.getByRole('tab', { name: en.addCustom })) + expect(screen.getByRole('textbox', { name: en.customRoute }).value).toBe('acme') + }) + + it('opens on the custom mode when every catalog provider is already configured', async () => { + const scripted = scriptedFace() + scripted.face.llm.listConfigurableProviders.mockResolvedValue(remoteOk([ + { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [] }, + { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'] }, + ])) + await mountFace(scripted) + fireEvent.click(screen.getByRole('button', { name: en.add })) + const catalog = screen.getByRole('tab', { name: en.addCatalog }) + expect(catalog.disabled).toBe(true) + expect(screen.getByRole('tab', { name: en.addCustom }).getAttribute('aria-selected')).toBe('true') + expect(screen.getByRole('textbox', { name: en.customRoute })).toBeTruthy() + }) + + it('shows the custom form alone when no directory row can be adopted', async () => { + const scripted = scriptedFace() + scripted.face.llm.listConfigurableProviders.mockResolvedValue(remoteOk([])) + await mountFace(scripted) + fireEvent.click(screen.getByRole('button', { name: en.add })) + expect(screen.queryByRole('tablist')).toBeNull() + expect(screen.queryByRole('combobox', { name: en.provider })).toBeNull() + expect(screen.getByRole('textbox', { name: en.customRoute })).toBeTruthy() + }) + + it('disables the add action when neither mode can proceed', async () => { + const scripted = scriptedFace() + scripted.face.llm.listConfigurableProviders.mockResolvedValue(remoteOk([ + { provider: 'openai', displayName: 'openai', settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'] }, + ])) + // A pi-ai schema naming no protocol leaves nothing to declare either. + const protocolless = JSON.parse(JSON.stringify( + Schema.object({ providers: Schema.dict(Schema.object({})) }).toJSON(), + )) as JsonValue + scripted.face.settings.describe.mockResolvedValue(remoteOk({ + writable: true, hasDocument: false, + namespaces: wireNamespaces().map(view => view.ns === 'llm-pi-ai' ? { ...view, schema: protocolless } : view), + })) + await mountFace(scripted) + expect(screen.getByRole('button', { name: en.add }).disabled).toBe(true) + }) + + it('collapses the add card from the custom mode on cancel', async () => { + await mountSection() + fireEvent.click(screen.getByRole('button', { name: en.add })) + fireEvent.click(screen.getByRole('tab', { name: en.addCustom })) + fireEvent.click(within(screen.getByRole('tabpanel', { name: en.addCustom })).getByText(en.cancel)) + expect(screen.queryByRole('tablist')).toBeNull() + expect(screen.getByRole('button', { name: en.add })).toBeTruthy() + }) + it('cancels the add card back to the add button', async () => { await mountSection() fireEvent.click(screen.getByText(en.add)) diff --git a/packages/client/ui-settings-models/tests/provider-form.client.spec.tsx b/packages/client/ui-settings-models/tests/provider-form.client.spec.tsx index 9b6ff1f55a..36dc899778 100644 --- a/packages/client/ui-settings-models/tests/provider-form.client.spec.tsx +++ b/packages/client/ui-settings-models/tests/provider-form.client.spec.tsx @@ -225,6 +225,12 @@ function openEditor(provider: string): void { fireEvent.click(summary) } +/** Open the add card from the section and switch it to the custom-API mode. */ +function openCustomMode(): void { + fireEvent.click(screen.getByRole('button', { name: en.add })) + fireEvent.click(screen.getByRole('tab', { name: en.addCustom })) +} + /** Open one model row's advanced fold, where the capacities live. */ function expandModel(index: number): void { fireEvent.click(screen.getByLabelText(`${en.modelAdvanced} ${index}`)) @@ -1417,27 +1423,40 @@ describe('hand-declared providers', () => { expect(buttonNamed(en.create).disabled).toBe(true) }) - it('closes the create card when an existing row is opened for editing', async () => { + it('closes the add card when an existing row is opened for editing', async () => { await mountSection({ providers: { openai: { baseURL: 'https://proxy.example/v1' } } }) - fireEvent.click(screen.getByRole('button', { name: en.customAdd })) - expect(screen.getByText(en.customTitle)).toBeTruthy() + openCustomMode() + expect(screen.getByRole('textbox', { name: en.customRoute })).toBeTruthy() // Two cards at once would each be closable by the other: whichever one is // dismissed clears the shared state and discards the other's draft. openEditor('openai') - expect(screen.queryByText(en.customTitle)).toBeNull() + expect(screen.queryByRole('tablist')).toBeNull() + expect(screen.queryByRole('textbox', { name: en.customRoute })).toBeNull() }) - it('reaches the card from the section and returns to the button on cancel', async () => { + it('reaches the custom form from the section and returns to the button on cancel', async () => { await mountSection() - fireEvent.click(screen.getByRole('button', { name: en.customAdd })) - expect(screen.getByText(en.customTitle)).toBeTruthy() + openCustomMode() + expect(screen.getByRole('textbox', { name: en.customRoute })).toBeTruthy() fireEvent.click(screen.getByText(en.cancel)) - await waitFor(() => { expect(screen.queryByText(en.customTitle)).toBeNull() }) - expect(screen.getByRole('button', { name: en.customAdd })).toBeTruthy() + await waitFor(() => { expect(screen.queryByRole('textbox', { name: en.customRoute })).toBeNull() }) + expect(screen.getByRole('button', { name: en.add })).toBeTruthy() + }) + + it('names each protocol by its product name and falls back to the identifier of an unknown one', () => { + mountCard({ protocols: [...PROTOCOLS, 'google-generative-ai'] }) + const protocol = screen.getByLabelText(en.customApi) + const labels = [...protocol.options].map(option => [option.value, option.textContent]) + expect(labels).toEqual([ + ['openai-completions', en.protocolOpenAiCompletions], + ['openai-responses', en.protocolOpenAiResponses], + ['anthropic-messages', en.protocolAnthropicMessages], + ['google-generative-ai', 'google-generative-ai'], + ]) }) it('refuses an unusable key on the field and blocks creation', () => { @@ -1608,15 +1627,15 @@ describe('API key field', () => { const { controller, mutate } = await mountSection() const load = vi.spyOn(controller, 'load') - fireEvent.click(screen.getByRole('button', { name: en.customAdd })) - fireEvent.change(screen.getByLabelText(en.customRoute), { target: { value: 'acme' } }) - fireEvent.change(screen.getByLabelText(en.baseUrl), { target: { value: 'https://acme.test/v1' } }) + openCustomMode() + fireEvent.change(screen.getByRole('textbox', { name: en.customRoute }), { target: { value: 'acme' } }) + fireEvent.change(screen.getByRole('textbox', { name: en.baseUrl }), { target: { value: 'https://acme.test/v1' } }) fireEvent.click(screen.getByRole('button', { name: en.addModel })) fireEvent.change(screen.getByLabelText(`${en.modelId} 1`), { target: { value: 'm' } }) fireEvent.click(screen.getByText(en.create)) await waitFor(() => { expect(mutate).toHaveBeenCalledOnce() }) await waitFor(() => { expect(load).toHaveBeenCalledOnce() }) - expect(screen.queryByText(en.customTitle)).toBeNull() + expect(screen.queryByRole('textbox', { name: en.customRoute })).toBeNull() }) }) From 536a94b18809905d11a432d4e17e6ce11ba17be9 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Sat, 19 Sep 2026 15:48:10 +0800 Subject: [PATCH 066/100] fix(settings-models): exact Models nav locators, scoped vendor term, review nits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new "添加模型提供商" button shares a prefix with the Models nav entry, so every e2e that clicked the nav through a non-exact locator resolved two buttons once the page rendered; the nav locators are exact now. The vendor sense of "provider" is registered in the terminology table as 模型提供商 with its scope — the Models settings copy, the providers user guide, and this package's README — while the generic provider rows keep 提供方, and the package's Chinese README uses the vendor term throughout. The custom card's header comment no longer claims a mode switch that a custom-only card does not render, and the SegmentedControl suite gains a positive Home/End case whose first enabled option is not the first option. --- apps/web/tests/models-settings.e2e.ts | 2 +- .../tests/onboarding-deepseek-config.e2e.ts | 4 +-- .../tests/onboarding-usable-provider.e2e.ts | 4 +-- apps/web/tests/settings-chrome.e2e.ts | 6 ++-- docs/i18n/terminology.md | 4 +-- .../tests/segmented-control.client.spec.tsx | 11 +++++++ .../ui-settings-models/README.i18n.yaml | 2 +- .../client/ui-settings-models/README.zh.md | 32 +++++++++---------- .../src/client/CustomProviderCard.tsx | 10 +++--- 9 files changed, 44 insertions(+), 31 deletions(-) diff --git a/apps/web/tests/models-settings.e2e.ts b/apps/web/tests/models-settings.e2e.ts index 6d514cf97b..a46439dcbb 100644 --- a/apps/web/tests/models-settings.e2e.ts +++ b/apps/web/tests/models-settings.e2e.ts @@ -75,7 +75,7 @@ describe('web e2e: Models settings page configures a dormant provider', () => { await page.getByRole('button', { name: '设置', exact: true }).click() const dialog = page.getByRole('dialog', { name: '设置' }) await dialog.waitFor({ timeout: 10_000 }) - await dialog.getByRole('button', { name: '模型' }).click() + await dialog.getByRole('button', { name: '模型', exact: true }).click() await dialog.getByText('填入各提供商的 API 密钥即可使用其模型。').waitFor({ timeout: 10_000 }) // The dormant pi-ai adapter contributes its whole installed catalog; no // provider is configured yet, so the page is one add button. diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts index d8e201a49d..4b4f6e0929 100644 --- a/apps/web/tests/onboarding-deepseek-config.e2e.ts +++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts @@ -99,7 +99,7 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup await page.getByRole('button', { name: '设置', exact: true }).click() const settings = page.getByRole('dialog', { name: '设置' }) await settings.waitFor({ timeout: 10_000 }) - await settings.getByRole('button', { name: '模型' }).click() + await settings.getByRole('button', { name: '模型', exact: true }).click() const deepSeekRow = settings.getByText('DeepSeek', { exact: true }).first() await deepSeekRow.waitFor({ timeout: 10_000 }) await deepSeekRow.locator('xpath=ancestor::li').getByRole('button', { name: '编辑' }).click() @@ -199,7 +199,7 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup await page.getByRole('button', { name: '设置', exact: true }).click() const settings = page.getByRole('dialog', { name: '设置' }) await settings.waitFor({ timeout: 10_000 }) - await settings.getByRole('button', { name: '模型' }).click() + await settings.getByRole('button', { name: '模型', exact: true }).click() const deepSeek = settings.getByText('DeepSeek', { exact: true }).first() await deepSeek.waitFor({ timeout: 10_000 }) await deepSeek.locator('xpath=ancestor::li').getByRole('button', { name: '编辑' }).click() diff --git a/apps/web/tests/onboarding-usable-provider.e2e.ts b/apps/web/tests/onboarding-usable-provider.e2e.ts index efc04dcdaa..42a2593487 100644 --- a/apps/web/tests/onboarding-usable-provider.e2e.ts +++ b/apps/web/tests/onboarding-usable-provider.e2e.ts @@ -54,7 +54,7 @@ describe.skipIf(MODE === 'record')('web e2e: another usable provider ends first- await settings.waitFor({ timeout: 10_000 }) // Dismissing the onboarding step leaves Settings closed, so enter the // Models section explicitly before exercising its normal cards. - await settings.getByRole('button', { name: '模型' }).click() + await settings.getByRole('button', { name: '模型', exact: true }).click() const setupKey = settings.getByRole('textbox', { name: 'API 密钥', exact: true }) await setupKey.waitFor({ timeout: 10_000 }) @@ -115,7 +115,7 @@ describe.skipIf(MODE === 'record')('web e2e: another usable provider ends first- // setup card over a user who already has somewhere to send a request. await page.getByRole('button', { name: '设置', exact: true }).click() await settings.waitFor({ timeout: 10_000 }) - await settings.getByRole('button', { name: '模型' }).click() + await settings.getByRole('button', { name: '模型', exact: true }).click() await settings.getByRole('button', { name: '编辑 DeepSeek (deepseek-official)' }).waitFor({ timeout: 10_000 }) expect(await settings.getByRole('textbox', { name: 'API 密钥', exact: true }).count()).toBe(0) diff --git a/apps/web/tests/settings-chrome.e2e.ts b/apps/web/tests/settings-chrome.e2e.ts index b396d5f969..7478f8a5e8 100644 --- a/apps/web/tests/settings-chrome.e2e.ts +++ b/apps/web/tests/settings-chrome.e2e.ts @@ -94,8 +94,8 @@ describe('web e2e: settings modal and General preferences', () => { const snapshot = await captureStableAria(page, '[role="dialog"]', scaffold.workspaceCwd) await compareOrRefreshGolden(DIALOG_EXPECTED, snapshot, MODE) // Section switch: aria-current moves (the Models page itself has its own scenario file). - await dialog.getByRole('button', { name: '模型' }).click() - await expect.poll(() => dialog.getByRole('button', { name: '模型' }).getAttribute('aria-current'), { timeout: 5_000 }).toBe('true') + await dialog.getByRole('button', { name: '模型', exact: true }).click() + await expect.poll(() => dialog.getByRole('button', { name: '模型', exact: true }).getAttribute('aria-current'), { timeout: 5_000 }).toBe('true') expect(await dialog.getByRole('button', { name: '通用设置' }).getAttribute('aria-current')).toBeNull() // Built-in plugins: the read-only Plugin list, a projection of the same // assembled Loader tree, shown as the section's one page; management and @@ -137,7 +137,7 @@ describe('web e2e: settings modal and General preferences', () => { expect(await dialog.getByRole('button', { name: '内置插件', exact: true }).getAttribute('aria-current')).toBe('true') // One contribution shows as the page itself, without a tab row. expect(await dialog.getByRole('tab').count()).toBe(0) - expect(await dialog.getByRole('button', { name: '模型' }).getAttribute('aria-current')).toBeNull() + expect(await dialog.getByRole('button', { name: '模型', exact: true }).getAttribute('aria-current')).toBeNull() const pluginsSnapshot = await captureStableAria( page, PLUGIN_ROW_SELECTOR, diff --git a/docs/i18n/terminology.md b/docs/i18n/terminology.md index feb1c96792..bab89e6efd 100644 --- a/docs/i18n/terminology.md +++ b/docs/i18n/terminology.md @@ -150,7 +150,7 @@ | merge | 合并 | | | | | message | 消息 | | | | | mod | 模组 | | | | -| model provider | 模型提供方 | | | | +| model provider | 模型提供商 | | | 指为模型提供 API 的厂商或网关:模型设置页文案、用户指南 providers 与 `ui-settings-models` README 用「提供商」;llm seam 的开发者文档(可配置提供方目录、dormant 等)沿用「提供方」 | | model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 | | module | 模块 | | | | | non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境,指主体不得获得超出既有授权的权限;普通升级不适用此行 | @@ -168,7 +168,7 @@ | plugin | 插件 | | | | | postmortem | 事故复盘 | 事故复盘(postmortem) | 事后分析、事故记录 | 事故记录与分析文档;目录或路径中的 `postmortem` 保持代码形式 | | prompt | 提示词 | | | | -| provider | 提供方 | | | | +| provider | 提供方 | | | 泛指的提供方(搜索、检查、settings 文件、subagent 等);模型厂商或网关见 model provider 行 | | provider-neutral | 提供方无关 | | 提供方中立 | | | quality gate | 质量门禁 | | | | | quiescence | 完全停稳 | | 静默、静止状态 | 指生命周期工作全部结算后的状态 | diff --git a/packages/client/ui-primitives/tests/segmented-control.client.spec.tsx b/packages/client/ui-primitives/tests/segmented-control.client.spec.tsx index 56af1d3224..7972eb9f3c 100644 --- a/packages/client/ui-primitives/tests/segmented-control.client.spec.tsx +++ b/packages/client/ui-primitives/tests/segmented-control.client.spec.tsx @@ -97,6 +97,17 @@ describe('SegmentedControl', () => { expect(onChange).not.toHaveBeenCalled() }) + it('lands Home and End on the first and last enabled options, not the first and last options', () => { + const { onChange } = mount('import', { + options: [{ value: 'catalog', label: 'Catalog', disabled: true }, OPTIONS[1]!, OPTIONS[2]!], + }) + fireEvent.keyDown(tab('Import'), { key: 'Home' }) + expect(onChange).toHaveBeenLastCalledWith('custom') + onChange.mockClear() + fireEvent.keyDown(tab('Import'), { key: 'End' }) + expect(onChange).not.toHaveBeenCalled() + }) + it('skips disabled options while walking with the arrow keys', () => { const { onChange } = mount('catalog', { options: [OPTIONS[0]!, { value: 'custom', label: 'Custom', disabled: true }, OPTIONS[2]!], diff --git a/packages/client/ui-settings-models/README.i18n.yaml b/packages/client/ui-settings-models/README.i18n.yaml index c81192e0e4..f04690ca04 100644 --- a/packages/client/ui-settings-models/README.i18n.yaml +++ b/packages/client/ui-settings-models/README.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-settings-models/README.md README.md: 619941e125d6c8607246b5924c66c9a11af47948 -README.zh.md: c4ba114dbb6501f564f810efc339114ea902604e +README.zh.md: d55d0cb6c6f89867050cc33b7bb200fc2bc40401 diff --git a/packages/client/ui-settings-models/README.zh.md b/packages/client/ui-settings-models/README.zh.md index c4ba114dbb..d55d0cb6c6 100644 --- a/packages/client/ui-settings-models/README.zh.md +++ b/packages/client/ui-settings-models/README.zh.md @@ -1,5 +1,5 @@ --- -description: "dsh Web 客户端的模型设置与产品引导插件:提供方行、API 密钥管理、模型列表与 DeepSeek 首次运行弹窗。" +description: "dsh Web 客户端的模型设置与产品引导插件:提供商行、API 密钥管理、模型列表与 DeepSeek 首次运行弹窗。" kind: "package-reference" --- @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -`dsh-client-ui-settings-models` 是 dsh Web 客户端的 Models 设置页面:用户可以配置 API 密钥(以只写方式存入 profile 的凭据引用之下)、编辑每个提供方的模型列表,并手工声明自定义 pi-ai 路由;页面以提供方行展示,一次只展开一张编辑卡片。该页面把提供方目录、设置文档与凭据描述合并为一个共享快照,因此行的状态在三个方面始终一致。它还会带首次运行的用户走两个有序弹窗——版本化内测声明,以及按条件显示的官方 DeepSeek 凭据步骤。 +`dsh-client-ui-settings-models` 是 dsh Web 客户端的 Models 设置页面:用户可以配置 API 密钥(以只写方式存入 profile 的凭据引用之下)、编辑每个提供商的模型列表,并手工声明自定义 pi-ai 路由;页面以提供商行展示,一次只展开一张编辑卡片。该页面把提供商目录、设置文档与凭据描述合并为一个共享快照,因此行的状态在三个方面始终一致。它还会带首次运行的用户走两个有序弹窗——版本化内测声明,以及按条件显示的官方 DeepSeek 凭据步骤。 ## 目录 @@ -25,33 +25,33 @@ kind: "package-reference"
      ## 使用本包 -从设置导航打开 Models 页面,即可看到每个已配置的提供方都有一行。其配置键未在任何位置配置的整分节提供方会渲染为其展开的设置卡片而非一行,但仅限首次运行姿态,且仅持续到用户关闭该卡片为止。每一类卡片各自持有自己的展开状态,因此关掉其中一张绝不会丢弃另一张里的草稿。 +从设置导航打开 Models 页面,即可看到每个已配置的提供商都有一行。其配置键未在任何位置配置的整分节提供商会渲染为其展开的设置卡片而非一行,但仅限首次运行姿态,且仅持续到用户关闭该卡片为止。每一类卡片各自持有自己的展开状态,因此关掉其中一张绝不会丢弃另一张里的草稿。 -存在已存储目录错误的提供方仍显示诊断以及编辑、删除入口。添加操作只面向已注册的 settings 命名空间,因此不可用的命名空间不会留下无法打开编辑器的按钮。保存被拒绝时,编辑器保持打开并展示 Host 诊断。 +存在已存储目录错误的提供商仍显示诊断以及编辑、删除入口。添加操作只面向已注册的 settings 命名空间,因此不可用的命名空间不会留下无法打开编辑器的按钮。保存被拒绝时,编辑器保持打开并展示 Host 诊断。 ### API 密钥 -编辑卡片上的主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名。键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下,profile 没有引用时便派生 `_API_KEY`,pi-ai profile 会把这次派生记录为 `apiKeyEnv`,因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供方留空密钥会保存一个不带引用的 profile,从而保留提供方原生认证(例如 Bedrock 凭据链或 Vertex ADC)。只有确认引用的凭据已配置时,行才会以绿色实心点标示 API 密钥状态;只有确认具名引用缺失时,才会以红色实心点标示。「应用」成功后会发出本地无障碍状态消息,且绝不回显任何机密内容。 +编辑卡片上的主字段是单独一个 **API 密钥**输入框——页面从不询问环境变量名。键入的密钥经 `credentials.set` 以**只写**方式存入 profile 的引用之下,profile 没有引用时便派生 `_API_KEY`,pi-ai profile 会把这次派生记录为 `apiKeyEnv`,因此 `settings.yaml` 从不携带密钥值。为新的 pi-ai 提供商留空密钥会保存一个不带引用的 profile,从而保留提供商原生认证(例如 Bedrock 凭据链或 Vertex ADC)。只有确认引用的凭据已配置时,行才会以绿色实心点标示 API 密钥状态;只有确认具名引用缺失时,才会以红色实心点标示。「应用」成功后会发出本地无障碍状态消息,且绝不回显任何机密内容。 -### 编辑提供方 +### 编辑提供商 -收起的「自定义设置」折叠区承载精选的额外字段:两个家族都有 `baseURL`(deepseek 的占位符显示公共端点)、各适配器自己的模型目录,以及适配器未提供的 pi-ai 路由的**显示名称**与 **API 协议**。Profile `headers` 仍是 `settings.yaml` 或 Cordis 配置中的部署配置,Models 页面不提供编辑器。Provider ID 保持固定:它是 settings 的键、其他每个 namespace 与每一条已记录会话引用的名字,也是页面读不回、因而搬不走的凭据引用词干。推理等级刻意不在可编辑字段之列:它是按模型的能力,提供方级的控件只可能被设成某些模型会拒绝的值。每个模型行可编辑 `id`、可选显示 `name`、可选 `contextWindow`/`maxTokens` 和输入类型;无关的模型字段在编辑后仍会保留。 +收起的「自定义设置」折叠区承载精选的额外字段:两个家族都有 `baseURL`(deepseek 的占位符显示公共端点)、各适配器自己的模型目录,以及适配器未提供的 pi-ai 路由的**显示名称**与 **API 协议**。Profile `headers` 仍是 `settings.yaml` 或 Cordis 配置中的部署配置,Models 页面不提供编辑器。Provider ID 保持固定:它是 settings 的键、其他每个 namespace 与每一条已记录会话引用的名字,也是页面读不回、因而搬不走的凭据引用词干。推理等级刻意不在可编辑字段之列:它是按模型的能力,提供商级的控件只可能被设成某些模型会拒绝的值。每个模型行可编辑 `id`、可选显示 `name`、可选 `contextWindow`/`maxTokens` 和输入类型;无关的模型字段在编辑后仍会保留。 `llm-deepseek` 的 DeepSeek 卡片编辑共用的端点、凭据和模型目录,不提供协议选择器。Cordis YAML 选择 Messages 时,官方端点占位符为 `https://api.deepseek.com/anthropic`;保存卡片不会改写协议配置。 -展开**自定义设置 → 模型选项**编辑模型。两个提供方家族共用相同的模型行布局、标签和图标:上下文窗口与最大输出 token 数分为两列,**输入类型**独占下一行,提供**文本**和**图片**复选框。未声明输入类型的模型行优先显示已安装模型的输入类型,其次是提供方默认值,最后回退为文本。已知 pi-ai 提供方会加载已安装目录,不向端点发送请求;打开模型行不会写入覆盖值。显式输入选择具有优先权,包括为视觉模型设置的仅文本覆盖。修改复选框会保存所选类型,且至少保留一种。DeepSeek 写入 `inputModalities`,pi-ai 写入 `input`。DeepSeek 取消勾选图片时,还会移除 `imagePixelBudget` 和 `imageMaxBytes`,因为适配器在没有图片输入时拒绝这些限制。在 `settings.yaml` 中清除输入字段可恢复适配器继承;**恢复默认模型**会重置整个模型目录覆盖。仅声明上游模型实际能够处理的输入类型。 +展开**自定义设置 → 模型选项**编辑模型。两个提供商家族共用相同的模型行布局、标签和图标:上下文窗口与最大输出 token 数分为两列,**输入类型**独占下一行,提供**文本**和**图片**复选框。未声明输入类型的模型行优先显示已安装模型的输入类型,其次是提供商默认值,最后回退为文本。已知 pi-ai 提供商会加载已安装目录,不向端点发送请求;打开模型行不会写入覆盖值。显式输入选择具有优先权,包括为视觉模型设置的仅文本覆盖。修改复选框会保存所选类型,且至少保留一种。DeepSeek 写入 `inputModalities`,pi-ai 写入 `input`。DeepSeek 取消勾选图片时,还会移除 `imagePixelBudget` 和 `imageMaxBytes`,因为适配器在没有图片输入时拒绝这些限制。在 `settings.yaml` 中清除输入字段可恢复适配器继承;**恢复默认模型**会重置整个模型目录覆盖。仅声明上游模型实际能够处理的输入类型。 -### 新增与删除提供方 +### 新增与删除提供商 -**添加模型提供商**是新增卡片的唯一入口:只要任一带编辑器的设置 namespace 已挂载就会出现,下述两种方式任一可继续时才可点击。卡片打开后顶部是分段式的方式切换,下方一行小字说明所选方式的用途:**第三方模型提供商**承载休眠目录提供商选择框与提供商编辑器——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog;**自定义模型 API**承载为 pi-ai 不提供的路由(中转站、自部署服务或其他兼容 OpenAI / Anthropic 协议的接口)准备的创建表单。某种方式只在其 namespace 已挂载时提供;只剩一种方式时卡片直接显示该表单;namespace 已无可采用的提供商或没有可声明的协议时,对应方式会被禁用。面板在其方式首次显示时挂载,之后在卡片打开期间保持挂载但隐藏,因此切换方式不会丢掉任何一边的草稿。自定义表单会索要唯一的 **Provider ID**、端点、协议与至少一个可唯一识别的模型,因为没有东西能为它们兜底。协议选择框以产品名称显示各协议——OpenAI Chat Completions、OpenAI Responses、Anthropic Messages——存储的值仍是 schema 标识符;适配器新增而本页尚未命名的协议直接显示其标识符。端点占位示例随所选协议变化:OpenAI Chat Completions 与 Responses 显示 `https://gateway.example/v1`,Anthropic Messages 显示 `https://gateway.example`,因为其 SDK 会追加 `/v1/messages`。切换协议会保留已输入的地址。端点必须是可解析的 HTTP 或 HTTPS URL;localhost、IPv4 与 IPv6 字面地址以及自定义端口仍然有效。语法错误会在字段处阻止询问与创建,请求失败则继续作为独立的提供方错误显示。**获取可用模型**通过 `llm/discoverModels` Remote 查询表单显示的端点,因此新增提供方一次即可完成,而非先保存再返回;回复打开的是可搜索选择器而非直接写入,只有点击**添加所选**才会写入。每个选中候选会在提供方公布相应信息时,把 id、显示名、上下文窗口、最大输出 token 数和已公布的输入类型复制进可编辑行;已经存在的行保留用户调整过的值。搜索会匹配模型 id 与可选显示名称,且不会清除隐藏项的勾选状态。**全选**会加入可见结果,而**取消全选**会清空全部勾选,以免意外采用隐藏结果。只有用户层单独携带某行时,该行才可删除(删除会恢复组合基线),其确认对话框会指名该提供方。 +**添加模型提供商**是新增卡片的唯一入口:只要任一带编辑器的设置 namespace 已挂载就会出现,下述两种方式任一可继续时才可点击。卡片打开后顶部是分段式的方式切换,下方一行小字说明所选方式的用途:**第三方模型提供商**承载休眠目录提供商选择框与提供商编辑器——裸挂载的 `llm-pi-ai` 在任何路由存在之前就能提供其完整的已安装 catalog;**自定义模型 API**承载为 pi-ai 不提供的路由(中转站、自部署服务或其他兼容 OpenAI / Anthropic 协议的接口)准备的创建表单。某种方式只在其 namespace 已挂载时提供;只剩一种方式时卡片直接显示该表单;namespace 已无可采用的提供商或没有可声明的协议时,对应方式会被禁用。面板在其方式首次显示时挂载,之后在卡片打开期间保持挂载但隐藏,因此切换方式不会丢掉任何一边的草稿。自定义表单会索要唯一的 **Provider ID**、端点、协议与至少一个可唯一识别的模型,因为没有东西能为它们兜底。协议选择框以产品名称显示各协议——OpenAI Chat Completions、OpenAI Responses、Anthropic Messages——存储的值仍是 schema 标识符;适配器新增而本页尚未命名的协议直接显示其标识符。端点占位示例随所选协议变化:OpenAI Chat Completions 与 Responses 显示 `https://gateway.example/v1`,Anthropic Messages 显示 `https://gateway.example`,因为其 SDK 会追加 `/v1/messages`。切换协议会保留已输入的地址。端点必须是可解析的 HTTP 或 HTTPS URL;localhost、IPv4 与 IPv6 字面地址以及自定义端口仍然有效。语法错误会在字段处阻止询问与创建,请求失败则继续作为独立的提供商错误显示。**获取可用模型**通过 `llm/discoverModels` Remote 查询表单显示的端点,因此新增提供商一次即可完成,而非先保存再返回;回复打开的是可搜索选择器而非直接写入,只有点击**添加所选**才会写入。每个选中候选会在提供商公布相应信息时,把 id、显示名、上下文窗口、最大输出 token 数和已公布的输入类型复制进可编辑行;已经存在的行保留用户调整过的值。搜索会匹配模型 id 与可选显示名称,且不会清除隐藏项的勾选状态。**全选**会加入可见结果,而**取消全选**会清空全部勾选,以免意外采用隐藏结果。只有用户层单独携带某行时,该行才可删除(删除会恢复组合基线),其确认对话框会指名该提供商。 ### 首次运行弹窗 -版本化声明步骤完成后,DeepSeek 步骤从同一份合并快照投影首次运行就绪状态。用户已经能够到达的**任何**提供方都会直接结束该步骤、不做渲染;只有没有任何提供方的用户才会被询问官方 DeepSeek 密钥。「稍后配置」只完成这次协调器遍历;适配器缺失、路由不活动、合并失败、只读部署或能力不可用时,该步骤不渲染即完成——Models 仍是诊断界面。 +版本化声明步骤完成后,DeepSeek 步骤从同一份合并快照投影首次运行就绪状态。用户已经能够到达的**任何**提供商都会直接结束该步骤、不做渲染;只有没有任何提供商的用户才会被询问官方 DeepSeek 密钥。「稍后配置」只完成这次协调器遍历;适配器缺失、路由不活动、合并失败、只读部署或能力不可用时,该步骤不渲染即完成——Models 仍是诊断界面。 ### 扩展 slot -本分区为仓库外分发的插件声明两个席位,类型定义在 [`src/client/slot-contract.ts`](src/client/slot-contract.ts) 并从 `./client` 导出。`settings.models.provider-card`(keyed)渲染在每张展示目录行的卡片内部——已保存行的卡片、其首次运行 setup 形态、以及「添加提供方」草稿卡——以 `entryKey = settingsNs` 分发,owner props 携带该行的 `ConfigurableProviderView`、其 configured 状态与已确认的 api-key 凭据状态,因此以某适配器家族的 namespace 注册一次即可收到该家族的全部卡片,含手工声明的路由;手工声明的草稿卡尚无目录行,保存之前不分发。`settings.models.footer`(list)渲染在行列表与新增控件之后。注册方通过 `ctx.slots.inject` 激活,并以 type-only import 引入本包 `/client` 入口;没有注册方时两个席位均不渲染任何内容。 +本分区为仓库外分发的插件声明两个席位,类型定义在 [`src/client/slot-contract.ts`](src/client/slot-contract.ts) 并从 `./client` 导出。`settings.models.provider-card`(keyed)渲染在每张展示目录行的卡片内部——已保存行的卡片、其首次运行 setup 形态、以及「添加提供商」草稿卡——以 `entryKey = settingsNs` 分发,owner props 携带该行的 `ConfigurableProviderView`、其 configured 状态与已确认的 api-key 凭据状态,因此以某适配器家族的 namespace 注册一次即可收到该家族的全部卡片,含手工声明的路由;手工声明的草稿卡尚无目录行,保存之前不分发。`settings.models.footer`(list)渲染在行列表与新增控件之后。注册方通过 `ctx.slots.inject` 激活,并以 type-only import 引入本包 `/client` 入口;没有注册方时两个席位均不渲染任何内容。 ----- @@ -61,7 +61,7 @@ kind: "package-reference"
      实现细节——点击展开 -页面只持有脱敏后的描述符,从不持有完整设置分区:因此每次编辑都以 `settings.mutate` 路径操作落到已存分区上——每个改动字段一次 set、每个清除字段一次 unset、删除提供方行则一次 unset。 +页面只持有脱敏后的描述符,从不持有完整设置分区:因此每次编辑都以 `settings.mutate` 路径操作落到已存分区上——每个改动字段一次 set、每个清除字段一次 unset、删除提供商行则一次 unset。 ### 校验 @@ -73,7 +73,7 @@ kind: "package-reference" ### 引导协调器 -声明步骤在 `src/client/locales.ts` 中持有精确文案,并在 `src/onboarding-copy.ts` 中持有确认版本;回环时它通过既有 settings API 比较并写入 `ui-onboarding.welcomeNoticeVersion`,且只有显式点击「继续」才会记录当前版本。非回环浏览器无法使用这个仅限宿主的 namespace,因此确认只保留在进程内,刷新后声明会再次出现。DeepSeek 步骤面向 `llm-deepseek` 中的 `deepseek-official`,在共享引导模态框内以仅凭据模式渲染既有 `ProviderEditor`;`credentials.set` 仍是唯一的机密写入,且不改变任何提供方设置。 +声明步骤在 `src/client/locales.ts` 中持有精确文案,并在 `src/onboarding-copy.ts` 中持有确认版本;回环时它通过既有 settings API 比较并写入 `ui-onboarding.welcomeNoticeVersion`,且只有显式点击「继续」才会记录当前版本。非回环浏览器无法使用这个仅限宿主的 namespace,因此确认只保留在进程内,刷新后声明会再次出现。DeepSeek 步骤面向 `llm-deepseek` 中的 `deepseek-official`,在共享引导模态框内以仅凭据模式渲染既有 `ProviderEditor`;`credentials.set` 仍是唯一的机密写入,且不改变任何提供商设置。
      @@ -87,7 +87,7 @@ kind: "package-reference" - [ui-settings](../ui-settings/README.zh.md)——本页所依赖 scope 与 schema 服务所在的领域底座。 - [settings](../../settings/README.zh.md)——持久化用户设置 seam 及其文件提供方。 - [credentials](../../credentials/README.zh.md)——本页写入密钥所经的凭据引用 seam。 -- [llm](../../llm/README.zh.md)——本页所配置提供方所在的适配器注册表。 +- [llm](../../llm/README.zh.md)——本页所配置提供商所在的适配器注册表。 - [Web 配置平面](../../../.agents/notes/archived/architecture/2026-07-30-web-config-plane.md)——手写编辑器的设计依据。 ----- @@ -99,7 +99,7 @@ kind: "package-reference" #### KV Cache 影响 -无;该包既不组装也不发送提供方请求。 +无;该包既不组装也不发送提供商请求。 ## 已知限制与延期工作 diff --git a/packages/client/ui-settings-models/src/client/CustomProviderCard.tsx b/packages/client/ui-settings-models/src/client/CustomProviderCard.tsx index 92c1e762dd..f8213d2237 100644 --- a/packages/client/ui-settings-models/src/client/CustomProviderCard.tsx +++ b/packages/client/ui-settings-models/src/client/CustomProviderCard.tsx @@ -6,10 +6,12 @@ * This is a create, not an edit, which is why it is its own form rather than * the provider editor with extra fields: the route id is being *chosen* here, * and the settings address does not exist until it is. It renders as the - * custom-API panel of the section's add card, whose mode switch is its title. - * One `settings.mutate` sets the whole profile at `providers.`; the key - * travels separately through `credentials/set` under the reference the profile - * records, exactly as an existing provider's key does. + * custom-API panel of the section's add card; the card's mode switch names it + * when both modes are offered, and with the custom mode alone the card shows + * this form directly. One `settings.mutate` sets the whole profile at + * `providers.`; the key travels separately through `credentials/set` + * under the reference the profile records, exactly as an existing provider's + * key does. * * The three fields a hand-declared route cannot default — endpoint, protocol, * and at least one model — are required here rather than at load, so the From 7d06fcdc05fa891f874716665430524bb39cd2c3 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Sat, 19 Sep 2026 16:04:34 +0800 Subject: [PATCH 067/100] fix(settings-models): derive the add panels, lock the switch in flight, pair tabs with panels MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The add card's panels are now derived from the shown mode and the modes visited since it opened, and each renders only while its mode is still offered, so a refresh that changes which modes are offered — every configurable row gone, the pi-ai namespace unmounted, a route freed after the catalog was exhausted — can neither leave the card without a panel nor keep a form whose write the Host would refuse. The catalog draft resolves to the chosen row while its namespace can take the write, else to the first addable row; closing either panel forgets it, so a later refresh cannot open a row editor unasked. Both cards report a write or an endpoint interrogation in flight, and the switch and the catalog select lock while one is, since a switch underneath it would orphan the answer or the picker it opens. The SegmentedControl takes the owner's id and pairs each tab with its panel through `aria-controls` and `aria-labelledby`; a card offering one mode carries that mode as its title instead of an orphan tabpanel, and a locked segment names its reason as hover text. `fullWidth` goes: no consumer asked for it. --- .../client/ui-primitives/README.i18n.yaml | 4 +- packages/client/ui-primitives/README.md | 2 +- packages/client/ui-primitives/README.zh.md | 2 +- .../src/SegmentedControl.module.css | 7 +- .../ui-primitives/src/SegmentedControl.tsx | 19 +- .../tests/segmented-control.client.spec.tsx | 31 +++- .../ui-settings-models/README.i18n.yaml | 4 +- packages/client/ui-settings-models/README.md | 2 +- .../client/ui-settings-models/README.zh.md | 2 +- .../src/client/CustomProviderCard.tsx | 12 +- .../src/client/ModelListEditor.tsx | 10 +- .../src/client/ModelsSection.tsx | 166 +++++++++++++----- .../src/client/ProviderEditor.tsx | 10 ++ .../ui-settings-models/src/client/locales.ts | 4 + .../tests/components.client.spec.tsx | 165 +++++++++++++++++ .../tests/model-list-catalog.client.spec.tsx | 8 +- 16 files changed, 368 insertions(+), 80 deletions(-) diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml index eb89a4eb3f..f031a6b178 100644 --- a/packages/client/ui-primitives/README.i18n.yaml +++ b/packages/client/ui-primitives/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-primitives/README.md -README.md: 61db832d764d127d8e0c050a10da384b34287316 -README.zh.md: b9c1013d8280202359682dbb59988b1824fbe8ab +README.md: adfdb1cac3136553bb1e45001089fa2fe19159f2 +README.zh.md: 85666ec13b623b180600ba3311424b97468ae348 diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md index 61db832d76..adfdb1cac3 100644 --- a/packages/client/ui-primitives/README.md +++ b/packages/client/ui-primitives/README.md @@ -38,7 +38,7 @@ Check this table before writing a control in a feature package. A plugin cannot |---|---| | `Button` | Clickable action; `variant` selects `primary`, `ghost`, `outline`, or `toolbar`. | | `Switch` | Two-state toggle, 36×20. `label` is required, so the control cannot ship unnamed. | -| `SegmentedControl` | Tablist of two or more equal-width segments with one sliding indicator, for switching a card or panel between a few modes; the owner holds the selection, `label` names the list, and a segment may be `disabled` with a `title`. | +| `SegmentedControl` | Tablist of two or more equal-width segments with one sliding indicator, for switching a card or panel between a few modes; the owner holds the selection and `label` names the list. `id` seeds each tab's id (`-`) and the panel it controls (`--panel`), which the owner renders and points back at the tab with `aria-labelledby`; a segment may be `disabled` with a `title`, and `disabled` on the control locks every segment while the shown panel has work in flight. | | `Checkbox` | Labeled native checkbox with controlled state, keyboard interaction, and disabled styling; the caller supplies localized `label` text. | | `Input` | Single-line text entry for search boxes and inline forms. | | `Menu` | Dropdown of items, separators, and group labels, with nested submenus. While open, ↑/↓ (with Home and End) walk the list, Tab settles the focused row, and Escape or Shift+Tab close back to the anchor; selecting a row also returns the keyboard to the anchor unless the owner moved it itself. Only a keyboard on the anchor or inside the list is intercepted, and `autoFocus` decides solely whether opening focuses the first row. | diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md index b9c1013d82..85666ec13b 100644 --- a/packages/client/ui-primitives/README.zh.md +++ b/packages/client/ui-primitives/README.zh.md @@ -38,7 +38,7 @@ kind: "package-library" |---|---| | `Button` | 可点击操作;`variant` 选择 `primary`、`ghost`、`outline` 或 `toolbar`。 | | `Switch` | 36×20 的双态开关。`label` 必填,控件不可能在没有名称的情况下发布。 | -| `SegmentedControl` | 两段或更多等宽分段加一个滑动指示块的 tablist,用于在几种模式间切换一张卡片或面板;选中项由调用方持有,`label` 为列表命名,分段可 `disabled` 并带 `title`。 | +| `SegmentedControl` | 两段或更多等宽分段加一个滑动指示块的 tablist,用于在几种模式间切换一张卡片或面板;选中项由调用方持有,`label` 为列表命名。`id` 派生每个 tab 的 id(`-`)及其控制的面板 id(`--panel`),面板由调用方渲染并用 `aria-labelledby` 指回 tab;分段可 `disabled` 并带 `title`,控件级 `disabled` 在当前面板有进行中的操作时锁住全部分段。 | | `Checkbox` | 带标签的原生复选框,支持受控状态、键盘交互和禁用样式;调用方提供本地化的 `label` 文本。 | | `Input` | 单行文本输入,用于搜索框与行内表单。 | | `Menu` | 由条目、分隔线与分组标题构成的下拉菜单,支持嵌套子菜单。打开期间 `↑`/`↓`(以及 Home、End)在列表中走位,Tab 选定聚焦行,Escape 或 Shift+Tab 关闭并把焦点还给锚点;选定一行同样把键盘还给锚点——除非拥有者自己移动了焦点。只拦截位于锚点或列表内的键盘,`autoFocus` 仅决定打开时是否聚焦首行。 | diff --git a/packages/client/ui-primitives/src/SegmentedControl.module.css b/packages/client/ui-primitives/src/SegmentedControl.module.css index 4795c8f0e6..a35b25edd4 100644 --- a/packages/client/ui-primitives/src/SegmentedControl.module.css +++ b/packages/client/ui-primitives/src/SegmentedControl.module.css @@ -4,8 +4,7 @@ * the soft elevation shadow (border: 0), the way every elevated surface draws * its edge, so the elevation gate keeps it off the alias-border set. * - * Segments are equal-width grid tracks — sized to the widest label when the - * control hugs its content, sharing the container when it spans it — which is + * Segments are equal-width grid tracks sized to the widest label, which is * what lets one indicator be placed arithmetically: the tablist carries the * segment count and the selected index as custom properties, and the indicator * derives its width and offset from them instead of measuring the DOM. */ @@ -20,10 +19,6 @@ background: var(--dsw-alias-interactive-bg-hover); } -.control[data-full-width='true'] { - display: grid; -} - .indicator { position: absolute; top: 3px; diff --git a/packages/client/ui-primitives/src/SegmentedControl.tsx b/packages/client/ui-primitives/src/SegmentedControl.tsx index b260f0a22f..ffbe2a819e 100644 --- a/packages/client/ui-primitives/src/SegmentedControl.tsx +++ b/packages/client/ui-primitives/src/SegmentedControl.tsx @@ -2,6 +2,9 @@ // sliding indicator, for switching a card or panel between a few modes. The // owner holds the selection; `label` is required so the tablist never ships // without an accessible name, and every segment label is owner-localized. +// Each tab is `-` and controls the panel `--panel`, the +// element the owner renders for that mode and points back at the tab with +// `aria-labelledby`. import { useEffect, useRef } from 'react' import type { CSSProperties, KeyboardEvent } from 'react' @@ -52,24 +55,27 @@ function walk( /** * Render a segmented control. + * @param props.id - the owner's base id: each tab is `-` and names + * `--panel` as the panel it controls. * @param props.value - the selected option's value; the control is fully controlled. * @param props.options - the segments in display order; at least two. * @param props.onChange - called with the value a click or a walk key asks for, * never with the value already selected. * @param props.label - localized accessible name of the tablist. - * @param props.fullWidth - stretch across the container instead of hugging the - * segment labels; the segments stay equal-width either way. + * @param props.disabled - lock every segment, typically while the shown panel + * has a write or a fetch in flight that switching would orphan. * @param props.className - extra class for layout placement. * @returns the tablist element. */ export function SegmentedControl({ - value, options, onChange, label, fullWidth = false, className, + id, value, options, onChange, label, disabled = false, className, }: { + id: string value: Value options: readonly SegmentedControlOption[] onChange: (next: Value) => void label: string - fullWidth?: boolean + disabled?: boolean // `| undefined` so a caller can forward an optional class straight through // under exactOptionalPropertyTypes (a CSS-module lookup is string|undefined). className?: string | undefined @@ -104,7 +110,6 @@ export function SegmentedControl({ ref={list} role="tablist" aria-label={label} - data-full-width={fullWidth} className={clsx(css.control, className)} style={indicator} > @@ -114,11 +119,13 @@ export function SegmentedControl({ return (
    ) diff --git a/packages/client/ui-conversation/tests/async-insertion.client.spec.ts b/packages/client/ui-conversation/tests/async-insertion.client.spec.ts new file mode 100644 index 0000000000..ef7cf1fcb9 --- /dev/null +++ b/packages/client/ui-conversation/tests/async-insertion.client.spec.ts @@ -0,0 +1,38 @@ +/** Late input insertions preserve references, subsequent edits, and undo ownership. */ +import { Context } from '@deepseek-ai/cordis' +import { UNDO_COMMAND } from 'lexical' +import { expect, it, vi } from 'vitest' +import { SessionInputShell } from '../src/client/input/facade.ts' + +function shell(): SessionInputShell { + return new SessionInputShell({ actx: new Context(), defaultSink: vi.fn(), commandAttachments: { + serialize: async () => [], release: () => {}, unsupportedNotice: () => '', + } }) +} + +it('inserts text beside an existing reference and undoes only that insertion', async () => { + const input = shell() + try { + input.setDraft('@ref') + input.insertReference({ source: 'file', ref: 'src/main.ts', label: 'main.ts', clipboardText: '@[main.ts](src/main.ts)' }, + { start: 0, end: 4, draftRev: input.state.getSnapshot().draftRev }) + const original = input.state.getSnapshot() + expect(input.actions.insertText(' check types', input.actions.captureInsertion())).toBe(true) + expect(input.state.getSnapshot().draft).toContain('check types') + expect(input.state.getSnapshot().occurrences).toEqual(original.occurrences) + input.editor.dispatchCommand(UNDO_COMMAND, undefined) + await vi.waitFor(() => { expect(input.state.getSnapshot().draft).toBe(original.draft) }) + } finally { input.dispose() } +}) + +it('refuses results captured before a user edit or after editor disposal', () => { + const input = shell() + input.setDraft('before') + const span = input.actions.captureInsertion() + input.setDraft('my newer text') + expect(input.actions.insertText('late voice', span)).toBe(false) + expect(input.state.getSnapshot().draft).toBe('my newer text') + const latest = input.actions.captureInsertion() + input.dispose() + expect(input.actions.insertText('late voice', latest)).toBe(false) +}) diff --git a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx index 9e0366952c..bb79a736c7 100644 --- a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx +++ b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx @@ -19,6 +19,7 @@ import { } from '@deepseek-ai/dsh-client-test-runtime' import { createSnapshotStore } from '@deepseek-ai/dsh-client-store' import type { SessionListState, SessionSnapshot } from '@deepseek-ai/dsh-api-session-controller/client' +import type { ContextPressureProjection } from '@deepseek-ai/dsh-token-meter/client' import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts' import type { Context } from '@deepseek-ai/cordis' import type { SessionId } from '@deepseek-ai/dsh-session/types' @@ -26,7 +27,7 @@ import type { SubmitOutcome } from '../src/client/contract/input.ts' import { SessionInputShell } from '../src/client/input/facade.ts' import { $replaceDetectSpanWithText, $selectDetectSpan } from '../src/client/input/editor/span-map.ts' import type { - ComposerAttachment, ComposerAttachmentsOwnerProps, DraftFileUploads, + ComposerAttachment, ComposerAttachmentsOwnerProps, DraftFileUploads, InputActivityOwnerProps, } from '../src/client/contract/slots.ts' import type { DraftAttachmentId } from '../src/client/contract/input.ts' import { InputBar } from '../src/client/skeleton/InputBar.tsx' @@ -92,6 +93,8 @@ interface BenchOptions { overlay?: React.ReactNode leftItems?: React.ReactNode rightItems?: React.ReactNode + activityEntry?: (owner: InputActivityOwnerProps) => React.ReactNode + contextPressure?: ContextPressureProjection footer?: React.ReactNode attachments?: readonly ComposerAttachment[] /** Upload states served for file-kind drafts (absent = every file is ready). */ @@ -162,6 +165,7 @@ function bench(over?: BenchOptions) { if (key === 'conversation.input.plan') return over?.planEntry ?? null if (key === 'conversation.input.permission') return over?.permissionEntry ?? null if (key === 'conversation.input.model') return over?.modelEntry ?? null + if (key === 'conversation.input.activity') return over?.activityEntry?.(owner as InputActivityOwnerProps) ?? null return null }) as never const props: InputBarProps = { @@ -184,7 +188,8 @@ function bench(over?: BenchOptions) { (selector ?? (v => v))(key === 'plan' ? over?.plan : key === 'goal' ? over?.goal - : key === 'imageLimits' ? over?.imageLimits : undefined)), + : key === 'imageLimits' ? over?.imageLimits + : key === 'contextPressure' ? over?.contextPressure : undefined)), useInput: bindSnapshotSelector(shell.state), inputActions: shell.actions, keyboard: shell, @@ -1610,7 +1615,7 @@ describe('command launcher chrome and control seats', () => { expect([...new Set(slotCalls.map(c => c.key))]).toEqual([ 'conversation.input.overlay', 'conversation.input.attachments', 'conversation.input.permission', 'conversation.input.plan', 'conversation.input.left', - 'conversation.input.right', 'conversation.input.model', + 'conversation.input.right', 'conversation.input.model', 'conversation.input.activity', 'conversation.composer.dock', ]) expect(view.queryByLabelText('Plan mode')).toBeNull() @@ -1673,3 +1678,40 @@ describe('command launcher chrome and control seats', () => { expect((live.view.getByLabelText('添加文件或调用指令') as HTMLButtonElement).disabled).toBe(false) }) }) + +it('lets a toolbar activity replace accessories without replacing the draft editor or send action', () => { + const { view } = bench({ draft: 'keep this draft', modelEntry: , + activityEntry: owner => <> + + + , + }) + const editor = view.getByRole('textbox') + fireEvent.click(view.getByRole('button', { name: 'expand activity' })) + expect(view.queryByRole('button', { name: 'model choice' })).toBeNull() + expect(view.getByRole('textbox')).toBe(editor) + expect(editor.textContent).toBe('keep this draft') + expect(view.getByRole('button', { name: '发送消息' })).toBeTruthy() + fireEvent.click(view.getByRole('button', { name: 'close activity' })) + expect(view.getByRole('button', { name: 'model choice' })).toBeTruthy() +}) + +it('places context usage below the composer and hides it until the activity closes', () => { + const { view } = bench({ draft: 'draft', contextPressure: { pressureTokens: 32_000, contextWindow: 128_000 }, + activityEntry: owner => <> + + + , + }) + const meter = view.getByRole('button', { name: '上下文已用 25%' }) + const microphone = view.getByRole('button', { name: 'microphone' }) + expect(microphone.compareDocumentPosition(meter) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy() + fireEvent.click(microphone) + expect(view.queryByRole('button', { name: '上下文已用 25%' })).toBeNull() + expect(view.getByRole('button', { name: '发送消息' })).toBeTruthy() + fireEvent.click(view.getByRole('button', { name: 'close activity' })) + expect(view.getByRole('button', { name: '上下文已用 25%' })).toBe(meter) + fireEvent.click(meter) + expect(view.getByRole('dialog', { name: '上下文已用' })).toBeTruthy() + expect(view.getByRole('button', { name: '发送消息' })).toBeTruthy() +}) diff --git a/packages/client/ui-plugin-manager/README.i18n.yaml b/packages/client/ui-plugin-manager/README.i18n.yaml index df24d45717..2489489230 100644 --- a/packages/client/ui-plugin-manager/README.i18n.yaml +++ b/packages/client/ui-plugin-manager/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-plugin-manager/README.md -README.md: c04a614668d5afb2e09c1f923ac9be473a4aab5a -README.zh.md: f0b30c91cb87ce96349d92086673809139956e0a +README.md: 75d972a310f7f5fc505775bcc72d2f18675d0c89 +README.zh.md: 66c441950ba288f554e2e41750cfe4e0c0b0b359 diff --git a/packages/client/ui-plugin-manager/README.md b/packages/client/ui-plugin-manager/README.md index c04a614668..75d972a310 100644 --- a/packages/client/ui-plugin-manager/README.md +++ b/packages/client/ui-plugin-manager/README.md @@ -77,7 +77,9 @@ The browser plugin registers the `plugins` sidebar entry and its `main` panel th ### Configuration slots -The page's `main` registration declares `plugins.item`, `plugins.bundle.config`, and `plugins.row.config` as its children, so the slots exist while the page does and a registrant's `ctx.slots.inject` waits for them. `configLedgerSource` projects the three ledgers into one observable — the official items in ledger order with their labels resolved in the active locale, and the bundle and row keys — cached until a ledger or the locale moves; the page binds it as `useConfigLedger` beside the store and never names a configurable plugin itself. Which page is open is page-local state: the cards, a bundle, an official plugin, or a row of a bundle. A registration lives with the browser half that made it. `dsh-client-modules` attaches a package's browser half to the Loader row whose specifier is the bare package name, so every page a bundle registers, for itself or for any of its rows, goes away when that row is switched off; a sub-plugin whose page must outlive the other rows ships as its own package. +The page's `main` registration declares `plugins.item`, `plugins.bundle.config`, and `plugins.row.config` as its children, so the slots exist while the page does and a registrant's `ctx.slots.inject` waits for them. `configLedgerSource` projects the three ledgers into one observable — the official items in ledger order with their labels resolved in the active locale, and the bundle and row keys — cached until a ledger or the locale moves; the page binds it as `useConfigLedger` beside the store and never names a configurable plugin itself. Which page is open is page-local state: the cards, a bundle, an official plugin, or a row of a bundle. A registration lives with the browser half that made it. `dsh-client-modules` attaches a package's browser half to the Loader row whose specifier is the bare package name, so every page a bundle registers, for itself or for any of its rows, goes away when that row is switched off; a sub-plugin whose page must outlive the other rows ships as its own package. Official packages whose names begin with `@deepseek-ai/dsh-experimental-` display the Beta marker. + +`plugins.bundle.config` supplies bundle detail configuration, keyed by npm package name. `plugins.bundle.activation` offers bundle-owned guidance after explicit enablement from the list, with callbacks to dismiss it or open the bundle details. It does not appear merely because an enabled bundle was listed. diff --git a/packages/client/ui-plugin-manager/README.zh.md b/packages/client/ui-plugin-manager/README.zh.md index f0b30c91cb..66c441950b 100644 --- a/packages/client/ui-plugin-manager/README.zh.md +++ b/packages/client/ui-plugin-manager/README.zh.md @@ -77,7 +77,9 @@ ctx.slots.inject('plugins.row.config', () => ctx.slots.register({ ### 配置 slot -页面的 `main` 注册把 `plugins.item`、`plugins.bundle.config` 与 `plugins.row.config` 声明为子 slot,因此它们与页面同生,注册方的 `ctx.slots.inject` 会等到它们出现。`configLedgerSource` 把三份账本投影成一个可观察对象——按账本顺序排列、标签按当前语言解析的官方条目,以及组合包与行的键——在账本或语言变化前保持缓存;页面把它作为 `useConfigLedger` 绑在 store 旁边,自身从不点名任何可配置插件。打开的是哪一页是页面本地状态:卡片、某个组合包、某个官方插件,或组合包的某一行。注册与做出它的浏览器半侧同生共死。`dsh-client-modules` 只把一个包的浏览器半侧挂在说明符恰为包名的那一行 Loader 行上,所以组合包为自己或任一行注册的页面,都会在那一行被关闭时一起消失;需要在其他行关闭时仍保留页面的子插件,应作为独立的包发布。 +页面的 `main` 注册把 `plugins.item`、`plugins.bundle.config` 与 `plugins.row.config` 声明为子 slot,因此它们与页面同生,注册方的 `ctx.slots.inject` 会等到它们出现。`configLedgerSource` 把三份账本投影成一个可观察对象——按账本顺序排列、标签按当前语言解析的官方条目,以及组合包与行的键——在账本或语言变化前保持缓存;页面把它作为 `useConfigLedger` 绑在 store 旁边,自身从不点名任何可配置插件。打开的是哪一页是页面本地状态:卡片、某个组合包、某个官方插件,或组合包的某一行。注册与做出它的浏览器半侧同生共死。`dsh-client-modules` 只把一个包的浏览器半侧挂在说明符恰为包名的那一行 Loader 行上,所以组合包为自己或任一行注册的页面,都会在那一行被关闭时一起消失;需要在其他行关闭时仍保留页面的子插件,应作为独立的包发布。 名称以 `@deepseek-ai/dsh-experimental-` 开头的官方包显示 Beta 标记。 + +`plugins.bundle.config` 以 npm 包名为 key,提供 Bundle 详情配置。`plugins.bundle.activation` 在用户从列表显式启用后提供 Bundle 自有引导,并传入关闭引导和打开详情的回调。仅列出已启用的 Bundle 不会触发引导。 diff --git a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx index 5ef0212a3c..dfa77f913c 100644 --- a/packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx +++ b/packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx @@ -37,7 +37,7 @@ import css from './PluginManagerPage.module.css' export type PluginManagerPageProps = PropsRuntime<'main'> & PropsLocale<'pluginManager'> - & PropsRenderSlots<'plugins.item' | 'plugins.bundle.config' | 'plugins.row.config'> + & PropsRenderSlots<'plugins.item' | 'plugins.bundle.config' | 'plugins.row.config' | 'plugins.bundle.activation'> & InjectFace /** The page's slot renderer, narrowed to the configuration slots. */ @@ -1072,6 +1072,7 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode { const ledger = props.useConfigLedger(snapshot => snapshot) // What is open; a package that leaves the list (uninstalled) drops back to the cards. const [view, setView] = useState({ kind: 'list' }) + const [activation, setActivation] = useState(null) useEffect(() => { ensure() }, [ensure]) // A package an install just enabled: scroll it into view and mark it for a moment. const { highlight, clearHighlight } = { highlight: state.highlight, clearHighlight: props.clearHighlight } @@ -1096,6 +1097,7 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode { const openItem = view.kind === 'item' ? ledger.items.find(item => item.id === view.id) : undefined const openRow = view.kind === 'row' && openPkg !== undefined ? openPkg.rows.find(row => row.rowId === view.rowId) : undefined const showsCards = openPkg === undefined && openItem === undefined + const activated = listed.find(pkg => pkg.name === activation && pkg.enabled && !state.busy.includes(pkg.name)) const setRowEnabled = (row: PackageRow, enabled: boolean): void => { /* v8 ignore next -- a row without a live entry has its switch disabled */ if (row.entryId !== undefined) props.setRowEnabled(row.entryId, enabled) @@ -1112,8 +1114,8 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode { resolveText={resolveText} busy={state.busy.includes(pkg.name)} highlighted={state.highlight === pkg.name} - onOpen={() => { setView({ kind: 'package', name: pkg.name }) }} - onSetEnabled={(enabled) => { props.setEnabled(pkg.name, enabled) }} + onOpen={() => { setActivation(null); setView({ kind: 'package', name: pkg.name }) }} + onSetEnabled={(enabled) => { setActivation(enabled ? pkg.name : null); props.setEnabled(pkg.name, enabled) }} /> ) // The Official group: the bundles the installation ships, then the plugins that registered their configuration. @@ -1242,6 +1244,12 @@ export function PluginManagerPage(props: PluginManagerPageProps): ReactNode { ) : null} + {showsCards && activated !== undefined && !state.install.open + ? renderSlot('plugins.bundle.activation', { + packageName: activated.name, + onDismiss: () => { setActivation(null) }, + onOpenDetails: () => { setActivation(null); setView({ kind: 'package', name: activated.name }) }, + }, { entryKey: activated.name }) : null} { setActivation(state.install.installed); props.enableInstalled() }} onApproveBuilds={props.approveBuildsAndRetry} onToggleRegistry={props.toggleRegistryOptions} onChooseRegistry={props.chooseRegistry} diff --git a/packages/client/ui-plugin-manager/src/client/index.ts b/packages/client/ui-plugin-manager/src/client/index.ts index f3394b69cc..e0f9e1ea26 100644 --- a/packages/client/ui-plugin-manager/src/client/index.ts +++ b/packages/client/ui-plugin-manager/src/client/index.ts @@ -31,7 +31,7 @@ export type { PluginManagerPageProps } from './PluginManagerPage.tsx' export type { ConfigLedger, OfficialItem } from './config-ledger.ts' export type { PluginManagerFace } from './manager-store.ts' export type { PluginManagerLocaleKey } from './locales.ts' -export type { PluginConfigViewProps } from './slot-contract.ts' +export type { PluginConfigViewProps, PluginActivationOwnerProps } from './slot-contract.ts' declare module '@deepseek-ai/dsh-client-ui-slots' { interface LocaleNamespaceMap { @@ -87,6 +87,7 @@ export function apply(ctx: ClientContext): void { inject: () => controller.inject(configLedger, text => ctx.locale.resolveText(text)), children: { 'plugins.item': { kind: 'list', scope: 'root' }, + 'plugins.bundle.activation': { kind: 'keyed', scope: 'root' }, 'plugins.bundle.config': { kind: 'keyed', scope: 'root' }, 'plugins.row.config': { kind: 'keyed', scope: 'root' }, }, diff --git a/packages/client/ui-plugin-manager/src/client/presentation.ts b/packages/client/ui-plugin-manager/src/client/presentation.ts index c76633ff97..b5f004b0ac 100644 --- a/packages/client/ui-plugin-manager/src/client/presentation.ts +++ b/packages/client/ui-plugin-manager/src/client/presentation.ts @@ -8,12 +8,6 @@ import type { FailedAction, ManagerNotice, PackageRow, PackageView, PluginManage /** The translate seat of the manager's dictionary. */ export type Translate = PropsLocale<'pluginManager'>['t'] -/** Official packages whose release status the page identifies as beta. */ -const BETA_PACKAGES = new Set([ - '@deepseek-ai/dsh-experimental-agent-team-profile', - '@deepseek-ai/dsh-experimental-auto-review', -]) - /** The registries with a name of their own, by host. */ const REGISTRY_COPY = new Map([ ['registry.npmmirror.com', 'registryNpmmirror'], @@ -105,7 +99,7 @@ export function packageText( return { title: pkg.meta?.title === undefined ? pkg.name : resolveText(pkg.meta.title), description: pkg.meta?.description === undefined ? undefined : resolveText(pkg.meta.description) || undefined, - beta: BETA_PACKAGES.has(pkg.name), + beta: pkg.name.startsWith('@deepseek-ai/dsh-experimental-'), } } diff --git a/packages/client/ui-plugin-manager/src/client/slot-contract.ts b/packages/client/ui-plugin-manager/src/client/slot-contract.ts index 89a9b52115..4f291b865f 100644 --- a/packages/client/ui-plugin-manager/src/client/slot-contract.ts +++ b/packages/client/ui-plugin-manager/src/client/slot-contract.ts @@ -19,8 +19,19 @@ export interface PluginConfigViewProps { readonly view: 'summary' | 'page' } +/** One user-requested bundle activation and navigation to its configuration page. */ +export interface PluginActivationOwnerProps { + readonly packageName: string + /** Dismiss guidance for this activation. */ + readonly onDismiss: () => void + /** Dismiss guidance and open this bundle's detail page. */ + readonly onOpenDetails: () => void +} + declare module '@deepseek-ai/dsh-client-ui-slots' { interface SlotMap { + /** Optional guidance after the user enables a bundle from the list, keyed by npm package name. */ + 'plugins.bundle.activation': { kind: 'keyed'; scope: 'root'; owner: PluginActivationOwnerProps } /** * One official plugin the Plugins page lists in its Official group after * the official bundles: `label` is the card's title and `order` its place. diff --git a/packages/client/ui-plugin-manager/tests/components.client.spec.tsx b/packages/client/ui-plugin-manager/tests/components.client.spec.tsx index 9aaa8c1cee..89bf43e9b0 100644 --- a/packages/client/ui-plugin-manager/tests/components.client.spec.tsx +++ b/packages/client/ui-plugin-manager/tests/components.client.spec.tsx @@ -12,6 +12,7 @@ import type { PluginManagerPageProps } from '../src/client/index.ts' import type { ConfigLedger } from '../src/client/config-ledger.ts' import { rowKey, type InstallState, type PackageRow, type PackageView, type PluginManagerState } from '../src/client/manager-store.ts' import { en, zh, type PluginManagerLocaleKey } from '../src/client/locales.ts' +import type { PluginActivationOwnerProps } from '../src/client/slot-contract.ts' afterEach(cleanup) @@ -66,7 +67,7 @@ const READY: PluginManagerState = { } /** Configuration entries a test supplies: what each slot cell renders, by `:` and the view asked for. */ -type SlotBodies = Record ReactNode> +type SlotBodies = Record ReactNode> const NO_CONFIG: ConfigLedger = { items: [], bundles: new Set(), rows: new Set() } @@ -120,10 +121,11 @@ function renderTab(state: Partial = {}, config: Partial { const body = bodies[`${name}:${opts?.only ?? opts?.entryKey ?? ''}`] if (body === undefined) return null + if (name === 'plugins.bundle.activation') return body('activation', owner) if (!('view' in owner) || (owner.view !== 'summary' && owner.view !== 'page')) { throw new Error('Plugin configuration fixture requires a summary or page view') } - return body(owner.view) + return body(owner.view, owner) }, } const { rerender } = render() @@ -256,6 +258,7 @@ describe('PluginManagerPage', () => { it.each([ '@deepseek-ai/dsh-experimental-agent-team-profile', '@deepseek-ai/dsh-experimental-auto-review', + '@deepseek-ai/dsh-experimental-fixture-input', '@acme/dsh-local-tools', ])('localizes Host metadata for %s across cards, details, switches, and uninstall confirmation', (name) => { const meta = { @@ -272,6 +275,7 @@ describe('PluginManagerPage', () => { expect(document.getElementById(card.getAttribute('aria-describedby')!)?.textContent).toBe(description(dict)) expect(screen.getByRole('switch', { name: dict.enableToggle.replace('{name}', title(dict)) })).toBeTruthy() expect(screen.queryByText('Original metadata.')).toBeNull() + expect(screen.queryByText(dict.statusBeta) !== null).toBe(name.startsWith('@deepseek-ai/dsh-experimental-')) } assertCard(en) setLanguage(zh) @@ -1193,3 +1197,41 @@ describe('PluginManagerPage', () => { expect(actions.closeInstall).toHaveBeenCalledOnce() }) }) + +it('offers bundle-owned guidance only after explicit enablement and navigates to its detail page', () => { + const name = 'dsh-better-sidebar' + const { set, actions } = renderTab({ packages: [pkg({ enabled: false })] }, { bundles: new Set([name]) }, { + [`plugins.bundle.activation:${name}`]: (_view, owner) => , + [`plugins.bundle.config:${name}`]: () =>
    Bundle setup
    , + }) + expect(screen.queryByText('Go to setup')).toBeNull() + set({ packages: [pkg()] }) + expect(screen.queryByText('Go to setup')).toBeNull() + set({ packages: [pkg({ enabled: false })] }) + fireEvent.click(screen.getByRole('switch')) + expect(actions.setEnabled).toHaveBeenCalledWith(name, true) + expect(screen.queryByText('Go to setup')).toBeNull() + set({ packages: [pkg()], busy: [name] }) + expect(screen.queryByText('Go to setup')).toBeNull() + set({ busy: [] }) + fireEvent.click(screen.getByText('Go to setup')) + expect(screen.getByText('Bundle setup')).toBeTruthy() + expect(screen.queryByText('Go to setup')).toBeNull() +}) + +it('dismisses activation guidance until the user enables the bundle again', () => { + const name = 'dsh-better-sidebar' + const { set } = renderTab({ packages: [pkg({ enabled: false })] }, {}, { + [`plugins.bundle.activation:${name}`]: (_view, owner) => , + }) + fireEvent.click(screen.getByRole('switch')) + set({ packages: [pkg()] }) + fireEvent.click(screen.getByText('Later')) + set({ packages: [pkg()] }) + expect(screen.queryByText('Later')).toBeNull() + fireEvent.click(screen.getByRole('switch')) + set({ packages: [pkg({ enabled: false })] }) + fireEvent.click(screen.getByRole('switch')) + set({ packages: [pkg()] }) + expect(screen.getByText('Later')).toBeTruthy() +}) diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml index 5e3699e8e5..5f73b2ecc8 100644 --- a/packages/client/ui-primitives/README.i18n.yaml +++ b/packages/client/ui-primitives/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-primitives/README.md -README.md: 2606bd0dd5895319c9887b15497b2ca6b7a045ce -README.zh.md: cdf816549ea6cf12382b819a493ded7f61ecddd9 +README.md: ed6f15f80031b2a9cc6403e95d645127d343c65f +README.zh.md: c4c04980f341677fbf8dd69d37b1a5968469f5fd diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md index 2606bd0dd5..ed6f15f800 100644 --- a/packages/client/ui-primitives/README.md +++ b/packages/client/ui-primitives/README.md @@ -44,7 +44,7 @@ Check this table before writing a control in a feature package. A plugin cannot | `Pill` | Selectable capsule button for view switchers and filters; takes `active` and `onClick`. | | `SegmentedTabs` | Controlled equal-width tabs with a sliding indicator and Left/Right, Home, and End navigation. The caller supplies labels, tab/panel ids, and panel content. | | `Tag` | Read-only capsule badge; `tone` selects one of eight palettes. | -| `StateDot` | Solid green `done`, amber `warning`, red `error`, and neutral-grey `idle` marks in a 10px slot, plus a tertiary-grey 14px rotating `ongoing` loader whose animations pin to document time zero so every visible loader rotates in phase. `aria-hidden`, so the render site owns the name. | +| `StateDot` | Solid green `done`, amber `warning`, red `error`, and neutral-grey `idle` marks in a 10px slot, plus a tertiary-grey 14px rotating `ongoing` loader whose animations pin to document time zero so every visible loader rotates in phase. `aria-hidden`, so the render site owns the name. `appearance="step"` shows a filled check for completion and a hollow pending circle. | | `ConnectionIndicator` | Inline connection-recovery control across outage, retry, and recovered states. | | `DisclosureRow` | 24px compact disclosure that lays title and content side by side. Memoized with shallow prop comparison; keep callbacks and React-node props stable when their content is unchanged. | | `Modal` | Centered dialog over a page mask. | diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md index cdf816549e..c4c04980f3 100644 --- a/packages/client/ui-primitives/README.zh.md +++ b/packages/client/ui-primitives/README.zh.md @@ -44,7 +44,7 @@ kind: "package-library" | `Pill` | 可选中的胶囊按钮,用于视图切换与筛选器;接受 `active` 与 `onClick`。 | | `SegmentedTabs` | 受控的等宽分段标签,支持滑动指示条及左/右方向键、Home、End 导航。调用方提供文案、标签与面板 id,以及面板内容。 | | `Tag` | 只读胶囊徽章;`tone` 选择八种配色之一。 | -| `StateDot` | 10px 槽内的绿色 `done`、琥珀色 `warning`、红色 `error`、中性灰色 `idle` 圆点,以及 tertiary 灰色 14px 旋转 `ongoing` loading,其动画固定到文档时间零点,所以所有可见 loading 同相旋转。它是 `aria-hidden` 的,名称由渲染点提供。 | +| `StateDot` | 10px 槽内的绿色 `done`、琥珀色 `warning`、红色 `error`、中性灰色 `idle` 圆点,以及 tertiary 灰色 14px 旋转 `ongoing` loading,其动画固定到文档时间零点,所以所有可见 loading 同相旋转。它是 `aria-hidden` 的,名称由渲染点提供。 `appearance="step"` 以实心勾表示完成、空心圆表示等待。 | | `ConnectionIndicator` | 行内连接恢复控件,覆盖断线、重试与已恢复三种状态。 | | `DisclosureRow` | 24px 紧凑折叠行,标题与内容左右排列。使用浅层 prop 比较进行 memo;内容未变时,保持回调与 React 节点 prop 的引用稳定。 | | `Modal` | 页面遮罩之上的居中对话框。 | diff --git a/packages/client/ui-primitives/src/StateDot.module.css b/packages/client/ui-primitives/src/StateDot.module.css index 186e54eb57..1a692c6892 100644 --- a/packages/client/ui-primitives/src/StateDot.module.css +++ b/packages/client/ui-primitives/src/StateDot.module.css @@ -93,3 +93,8 @@ stroke-dashoffset: -3; } } + +.step { display: inline-flex; flex: none; align-items: center; justify-content: center; box-sizing: border-box; border-radius: 50%; corner-shape: round; border: 1.5px solid var(--dsw-alias-label-tertiary); color: var(--dsw-alias-label-primary-foreground); } +.step[data-state='done'] { border-color: var(--dsw-alias-state-success-primary); background: var(--dsw-alias-state-success-primary); } +.step[data-state='error'] { border-color: var(--dsw-alias-state-error-primary); background: var(--dsw-alias-state-error-primary); } +.step[data-state='warning'] { border-color: var(--dsw-alias-state-warn-primary); } diff --git a/packages/client/ui-primitives/src/StateDot.tsx b/packages/client/ui-primitives/src/StateDot.tsx index b0d84b89ec..ede3c6b98c 100644 --- a/packages/client/ui-primitives/src/StateDot.tsx +++ b/packages/client/ui-primitives/src/StateDot.tsx @@ -1,5 +1,6 @@ import clsx from 'clsx' import css from './StateDot.module.css' +import { IconCheckOutlineRegular } from './icons/index.tsx' /** * State semantic: green done / amber user-attention / tertiary-grey loading / @@ -26,12 +27,14 @@ function syncSpinner(element: SVGSVGElement | null): void { * @param props.state - which of `done`, `warning`, `ongoing`, `error`, or `idle` to show. * @param props.size - outer diameter in px; defaults to 14 for ongoing and 10 for solid states. * @param props.className - extra class for layout placement. + * @param props.appearance - compact dot by default; step uses a filled check or hollow pending circle. * @returns the dot element (aria-hidden; pair with text for accessibility). */ -export function StateDot({ state, size, className }: { +export function StateDot({ state, size, className, appearance = 'dot' }: { state: StateDotState size?: number | undefined className?: string | undefined + appearance?: 'dot' | 'step' }) { const edge = size ?? (state === 'ongoing' ? 14 : 10) if (state === 'ongoing') { @@ -54,10 +57,10 @@ export function StateDot({ state, size, className }: { } return ( ) } diff --git a/packages/client/ui-primitives/src/icons/index.tsx b/packages/client/ui-primitives/src/icons/index.tsx index 1a31577bb3..1c048370c1 100644 --- a/packages/client/ui-primitives/src/icons/index.tsx +++ b/packages/client/ui-primitives/src/icons/index.tsx @@ -1593,3 +1593,19 @@ export const IconSlidersTwoOutlineRegular = (props: IconProps) => ( export const IconSlidersTwoOutlineMedium = (props: IconProps) => ( ) + +const IconMicrophoneOutlineArtwork = ({ size = 16, className, strokeWidth }: WeightedIconProps) => ( + +) + +/** Regular one-pixel microphone artwork. */ +export const IconMicrophoneOutlineRegular = (props: IconProps) => ( + +) + +/** Medium microphone artwork with a 1.3px stroke. */ +export const IconMicrophoneOutlineMedium = (props: IconProps) => ( + +) diff --git a/packages/client/ui-primitives/tests/icons.client.spec.tsx b/packages/client/ui-primitives/tests/icons.client.spec.tsx index d3f950e63d..62f67def95 100644 --- a/packages/client/ui-primitives/tests/icons.client.spec.tsx +++ b/packages/client/ui-primitives/tests/icons.client.spec.tsx @@ -17,13 +17,14 @@ const icons = Object.fromEntries( const iconNames = Object.keys(icons) describe('product icon set', () => { - it('exports regular and medium variants for all 91 public glyphs', () => { - expect(iconNames.length).toBe(182) + it('exports regular and medium variants for all 92 public glyphs', () => { + expect(iconNames.length).toBe(184) expect(iconNames.some(name => /\d+$/.test(name))).toBe(false) const regular = iconNames.filter(name => name.endsWith('Regular')).map(name => name.slice(0, -'Regular'.length)) const medium = iconNames.filter(name => name.endsWith('Medium')).map(name => name.slice(0, -'Medium'.length)) expect(medium.sort()).toEqual(regular.sort()) expect(iconNames).toEqual(expect.arrayContaining([ + 'IconMicrophoneOutlineRegular', 'IconPlanOutlineRegular', 'IconCompactOutlineRegular', 'IconShieldOutlineRegular', 'IconDeliverDocRegular', 'IconWarningTriangleOutlineRegular', 'IconCompareSplitOutlineRegular', 'IconCloseCircleFillRegular', ])) diff --git a/packages/client/ui-primitives/tests/state-dot.client.spec.tsx b/packages/client/ui-primitives/tests/state-dot.client.spec.tsx index d3e21fe772..5b6bad53f0 100644 --- a/packages/client/ui-primitives/tests/state-dot.client.spec.tsx +++ b/packages/client/ui-primitives/tests/state-dot.client.spec.tsx @@ -57,6 +57,14 @@ describe('StateDot', () => { }) }) +it('renders completed steps with a check and pending steps without one', () => { + const { container, rerender } = render() + expect(container.querySelector('[data-state="done"] svg')).toBeTruthy() + rerender() + expect(container.querySelector('[data-state="idle"] svg')).toBeNull() + expect(container.firstElementChild?.className).toContain('step') +}) + describe('StateDot ongoing phase', () => { it('pins every loader animation to document time zero on mount', () => { const animations = [{ startTime: 42 }, { startTime: 7 }] diff --git a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx index c314c6e669..3c2c0186b5 100644 --- a/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx +++ b/packages/client/ui-subagent/tests/conversation-ui.client.spec.tsx @@ -96,6 +96,8 @@ function props( useChat: unused, useTrajectory: unused, inputActions: { + captureInsertion: unused, + insertText: unused, setDraft: unused, addAttachments: unused, removeAttachment: unused, diff --git a/packages/client/ui-trajectory/tests/views.client.spec.tsx b/packages/client/ui-trajectory/tests/views.client.spec.tsx index ea8641c0e2..4a6c214cec 100644 --- a/packages/client/ui-trajectory/tests/views.client.spec.tsx +++ b/packages/client/ui-trajectory/tests/views.client.spec.tsx @@ -214,6 +214,8 @@ function standaloneProps( draft: '', attachmentIds: [], draftRev: 0, phase: 'plain', occurrences: [], queue: [], }) const inputActions: InputActions = { + captureInsertion: () => ({ start: 0, end: 0, draftRev: 0 }), + insertText: () => false, setDraft: () => {}, addAttachments: () => false, removeAttachment: () => {}, @@ -339,6 +341,8 @@ function mount(fixture: Awaited>) { draft: '', attachmentIds: [], draftRev: 0, phase: 'plain', occurrences: [], queue: [], })) const inputActions: InputActions = { + captureInsertion: () => ({ start: 0, end: 0, draftRev: 0 }), + insertText: () => false, setDraft: vi.fn(), addAttachments: vi.fn(() => false), removeAttachment: vi.fn(), diff --git a/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx b/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx index 4daccc5a42..7505ce2428 100644 --- a/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx +++ b/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx @@ -127,6 +127,8 @@ const kit: Omit = { useProjection: (() => undefined), useInput: selector => selector(inputState), inputActions: { + captureInsertion: () => ({ start: 0, end: 0, draftRev: 0 }), + insertText: () => false, setDraft: () => { throw new Error('unused') }, addAttachments: () => { throw new Error('unused') }, removeAttachment: () => { throw new Error('unused') }, diff --git a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx index e119213f65..325a377d53 100644 --- a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx +++ b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx @@ -125,6 +125,8 @@ const kitBase: Omit = useProjection: (() => undefined), useInput: selector => selector(inputState), inputActions: { + captureInsertion: () => ({ start: 0, end: 0, draftRev: 0 }), + insertText: () => false, setDraft: () => { throw new Error('unused') }, addAttachments: () => { throw new Error('unused') }, removeAttachment: () => { throw new Error('unused') }, diff --git a/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx b/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx index 5f7df5979e..0bbb40502b 100644 --- a/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx +++ b/packages/client/ui-workflow-run/tests/workflow-run.client.spec.tsx @@ -326,6 +326,8 @@ function panelProps(data: WorkflowRunChatData, sessions = listState(), openSessi useTrajectory: selector => selector(panelTrajectory), useInput: () => { throw new Error('unused') }, inputActions: { + captureInsertion: () => ({ start: 0, end: 0, draftRev: 0 }), + insertText: () => false, setDraft: () => {}, addAttachments: () => false, removeAttachment: () => {}, diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts index 73647081a7..3de64a30c6 100644 --- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts +++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts @@ -445,7 +445,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ ], replaceRisk: 'shadows-shipped-ui', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.composer.bar\', () => ctx.slots.register(\n { name: \'conversation.composer.bar\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', - source: 'packages/client/ui-conversation/src/client/contract/slots.ts:201', + source: 'packages/client/ui-conversation/src/client/contract/slots.ts:203', }, { key: 'conversation.composer.dock', @@ -698,6 +698,45 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.hero.workspace.directoryFlow\', () => ctx.slots.register(\n { name: \'conversation.hero.workspace.directoryFlow\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', source: 'packages/client/ui-workspace/src/client/contract/slots.ts:99', }, + { + key: 'conversation.input.activity', + kind: 'single', + scope: 'session', + summary: 'Compact action after the model selector; it can expand across the toolbar while retaining the editor and submit action.', + doc: 'Compact action after the model selector; it can expand across the toolbar while retaining the editor and submit action.', + registerOptions: [], + ownerProps: [ + '/** A toolbar activity hides ordinary accessory controls while expanded; its occupant must release expansion on unmount. */\nexport interface InputActivityOwnerProps extends InputControlOwnerProps {\n /** @param active - whether the occupant needs the toolbar width before the submit action. */\n onActiveChange: (active: boolean) => void\n}', + ], + ownerPropsReferences: [ + 'InputControlOwnerProps', + ], + standardProps: [ + 'useResource: UseResource', + 'useWorkspaces: SnapshotSelectorHook', + 'usePanelInfo: UsePanelInfo', + 'useSessions: UseSessions', + 'useSessionStatus: UseSessionStatus', + 'useSessionRetainInfo: UseSessionRetainInfo', + 'useWorkspaces: SnapshotSelectorHook', + 'useChat: UseChat', + 'useConversation: UseConversation', + 'useInput: SnapshotSelectorHook', + 'inputActions: InputActions', + 'useSession: SessionSnapshotSelector', + 'sessionId: SessionId', + 'useProjection: UseProjection', + 'useTrajectory: UseTrajectory', + ], + keyDomain: '', + hookContext: '', + slotInject: '', + declaredBy: 'an entry in \'conversation.composer.bar\' (client-ui-conversation), so it exists while that entry is mounted', + occupants: [], + replaceRisk: 'none', + example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.input.activity\', () => ctx.slots.register(\n { name: \'conversation.input.activity\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', + source: 'packages/client/ui-conversation/src/client/contract/slots.ts:201', + }, { key: 'conversation.input.attachments', kind: 'single', @@ -737,7 +776,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ ], replaceRisk: 'shadows-shipped-ui', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.input.attachments\', () => ctx.slots.register(\n { name: \'conversation.input.attachments\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', - source: 'packages/client/ui-conversation/src/client/contract/slots.ts:203', + source: 'packages/client/ui-conversation/src/client/contract/slots.ts:205', }, { key: 'conversation.input.dock', @@ -893,7 +932,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ ], replaceRisk: 'shadows-shipped-ui', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.input.model\', () => ctx.slots.register(\n { name: \'conversation.input.model\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', - source: 'packages/client/ui-conversation/src/client/contract/slots.ts:213', + source: 'packages/client/ui-conversation/src/client/contract/slots.ts:215', }, { key: 'conversation.input.overlay', @@ -990,7 +1029,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ ], replaceRisk: 'shadows-shipped-ui', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.input.permission\', () => ctx.slots.register(\n { name: \'conversation.input.permission\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', - source: 'packages/client/ui-conversation/src/client/contract/slots.ts:211', + source: 'packages/client/ui-conversation/src/client/contract/slots.ts:213', }, { key: 'conversation.input.plan', @@ -1029,7 +1068,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ ], replaceRisk: 'shadows-shipped-ui', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'conversation.input.plan\', () => ctx.slots.register(\n { name: \'conversation.input.plan\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', - source: 'packages/client/ui-conversation/src/client/contract/slots.ts:209', + source: 'packages/client/ui-conversation/src/client/contract/slots.ts:211', }, { key: 'conversation.input.right', @@ -1636,6 +1675,42 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'main.conversation\', () => ctx.slots.register(\n { name: \'main.conversation\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', source: 'packages/client/ui-conversation/src/client/contract/slots.ts:127', }, + { + key: 'plugins.bundle.activation', + kind: 'keyed', + scope: 'root', + summary: 'Optional guidance after the user enables a bundle from the list, keyed by npm package name.', + doc: 'Optional guidance after the user enables a bundle from the list, keyed by npm package name.', + registerOptions: [ + { + name: 'key', + requirement: 'required', + type: 'string', + doc: 'Your cell key: the entry renders where the owner dispatches this exact key. Registering an already-occupied key replaces that occupant.', + }, + ], + ownerProps: [ + '/** One user-requested bundle activation and navigation to its configuration page. */\nexport interface PluginActivationOwnerProps {\n readonly packageName: string\n /** Dismiss guidance for this activation. */\n readonly onDismiss: () => void\n /** Dismiss guidance and open this bundle\'s detail page. */\n readonly onOpenDetails: () => void\n}', + ], + ownerPropsReferences: [], + standardProps: [ + 'useResource: UseResource', + 'useWorkspaces: SnapshotSelectorHook', + 'usePanelInfo: UsePanelInfo', + 'useSessions: UseSessions', + 'useSessionStatus: UseSessionStatus', + 'useSessionRetainInfo: UseSessionRetainInfo', + 'useWorkspaces: SnapshotSelectorHook', + ], + keyDomain: 'open: any string the owner dispatches (no compile-time key set), none are taken yet', + hookContext: '', + slotInject: '', + declaredBy: 'an entry in \'main\' (client-ui-plugin-manager), so it exists while that entry is mounted', + occupants: [], + replaceRisk: 'none', + example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'plugins.bundle.activation\', () => ctx.slots.register(\n { name: \'plugins.bundle.activation\', key: \'\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', + source: 'packages/client/ui-plugin-manager/src/client/slot-contract.ts:34', + }, { key: 'plugins.bundle.config', kind: 'keyed', @@ -1670,7 +1745,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ occupants: [], replaceRisk: 'none', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'plugins.bundle.config\', () => ctx.slots.register(\n { name: \'plugins.bundle.config\', key: \'\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', - source: 'packages/client/ui-plugin-manager/src/client/slot-contract.ts:39', + source: 'packages/client/ui-plugin-manager/src/client/slot-contract.ts:50', }, { key: 'plugins.item', @@ -1723,7 +1798,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ ], replaceRisk: 'none', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'plugins.item\', () => ctx.slots.register(\n { name: \'plugins.item\', id: \'my-entry\', order: 100, label: \'My entry\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', - source: 'packages/client/ui-plugin-manager/src/client/slot-contract.ts:33', + source: 'packages/client/ui-plugin-manager/src/client/slot-contract.ts:44', }, { key: 'plugins.row.config', @@ -1759,7 +1834,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ occupants: [], replaceRisk: 'none', example: 'return {\n inject: [\'slots\'],\n apply(ctx) {\n ctx.slots.inject(\'plugins.row.config\', () => ctx.slots.register(\n { name: \'plugins.row.config\', key: \'\' },\n () => React.createElement(\'div\', null, \'hello\'),\n ))\n },\n}', - source: 'packages/client/ui-plugin-manager/src/client/slot-contract.ts:47', + source: 'packages/client/ui-plugin-manager/src/client/slot-contract.ts:58', }, { key: 'rightbar', diff --git a/tsconfig.host.json b/tsconfig.host.json index 01cca0cb14..b15992769f 100644 --- a/tsconfig.host.json +++ b/tsconfig.host.json @@ -49,6 +49,7 @@ "apps/web/tests/office-fixture.ts", "apps/web/tests/sidebar-browser.e2e.ts", "apps/web/tests/plugin-config.e2e.ts", + "apps/web/tests/input-plugin-extensions.e2e.ts", "apps/web/tests/plugin-manager.e2e.ts", "apps/web/tests/plugin-install-cancel.e2e.ts", "apps/web/tests/plugin-install-approve.e2e.ts", From 9df1b6033abb3425340ca12ab85106811e5e358e Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Mon, 21 Sep 2026 11:35:35 +0800 Subject: [PATCH 077/100] fix(web): keep the empty composer dock collapsed --- packages/client/ui-conversation/README.i18n.yaml | 4 ++-- packages/client/ui-conversation/README.md | 2 +- packages/client/ui-conversation/README.zh.md | 2 +- .../ui-conversation/src/client/skeleton/InputBar.module.css | 6 +++--- .../client/ui-conversation/src/client/skeleton/InputBar.tsx | 2 +- .../client/ui-conversation/tests/input-bar.client.spec.tsx | 6 ++++-- 6 files changed, 12 insertions(+), 10 deletions(-) diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index 84c42ef4a7..e655890c11 100644 --- a/packages/client/ui-conversation/README.i18n.yaml +++ b/packages/client/ui-conversation/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md -README.md: 5e42c1e11bd33f764ae85ef029a127f99541fc71 -README.zh.md: 3827193e703e19df142e3526cc2bbc8b8e5eb57a +README.md: b1bfea3d4ccef1076ed337a8ec229b64c9044ec0 +README.zh.md: d529286f2609b02aad1ed26f69aa54d9ef9bc710 diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index 5e42c1e11b..b1bfea3d4c 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -122,7 +122,7 @@ The selector must be a pure function of the owner currency. Its non-null return `InputActions.captureInsertion()` captures the draft selection and revision; `insertText(text, span)` inserts one undoable plain-text edit only while that revision is current and the editor permits editing. Asynchronous consumers retain rejected results for user action. -`conversation.input.activity` hosts one control between the model selector and Send. Its `onActiveChange` callback expands that control across the toolbar and hides ordinary accessory controls and the context meter while preserving the editor and submit action. Closing the activity restores those controls. The occupant releases expansion on unmount and owns any activity-specific feedback. +`conversation.input.activity` hosts one control between the model selector and Send. Its `onActiveChange` callback expands that control across the toolbar and hides ordinary accessory controls and the context meter while preserving the editor and submit action. Closing the activity restores those controls with context details closed. The empty hero dock remains collapsed when it has no content. The occupant releases expansion on unmount and owns any activity-specific feedback. ## Model Experience diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index 3827193e70..d529286f26 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -122,7 +122,7 @@ selector 必须是 owner currency 的纯函数。非 null 返回值作为 `match `InputActions.captureInsertion()` 捕获草稿选区与版本;`insertText(text, span)` 仅在版本未变且编辑器允许编辑时,插入一次可撤销的纯文本编辑。异步消费者在插入被拒绝后负责保留结果,等待用户操作。 -`conversation.input.activity` 在模型选择器与发送按钮之间承载一个控件。其 `onActiveChange` 回调将控件展开至整条工具栏并隐藏普通辅助控件和上下文用量按钮,同时保留编辑器与提交按钮。关闭活动后恢复这些控件。占用者在卸载时释放展开状态,并拥有活动专属反馈。 +`conversation.input.activity` 在模型选择器与发送按钮之间承载一个控件。其 `onActiveChange` 回调将控件展开至整条工具栏并隐藏普通辅助控件和上下文用量按钮,同时保留编辑器与提交按钮。关闭活动后恢复这些控件,上下文详情保持关闭。首页输入框下方没有内容时,该区域保持收起。占用者在卸载时释放展开状态,并拥有活动专属反馈。 ## 模型体验 diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css index d0b6b7224e..fbd07f2810 100644 --- a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css +++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css @@ -409,8 +409,8 @@ } .standardControls { display: flex; align-items: center; gap: 12px; min-width: 0; } -.tools[hidden], .standardControls[hidden], .contextControl[hidden] { display: none; } +.tools[hidden], .standardControls[hidden] { display: none; } .trailingActive { flex: 1; margin-left: 0; } -.activity, .contextControl { display: flex; align-items: center; flex: none; } -.activity:empty, .contextControl:empty { display: none; } +.activity { display: flex; align-items: center; flex: none; } +.activity:empty { display: none; } .activityExpanded { flex: 1; min-width: 0; } diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx index 7d7e834e64..5b045fb05c 100644 --- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx +++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx @@ -492,7 +492,7 @@ export const InputBar = memo(function InputBar({ {variant === 'composer' && input !== undefined && sessionId !== undefined ? renderSlot('conversation.composer.dock', {}) : null} - + {activity ? null : } ) diff --git a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx index bb79a736c7..90ea3c1cb1 100644 --- a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx +++ b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx @@ -1706,12 +1706,14 @@ it('places context usage below the composer and hides it until the activity clos const meter = view.getByRole('button', { name: '上下文已用 25%' }) const microphone = view.getByRole('button', { name: 'microphone' }) expect(microphone.compareDocumentPosition(meter) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy() + fireEvent.click(meter) + expect(view.getByRole('dialog', { name: '上下文已用' })).toBeTruthy() fireEvent.click(microphone) + expect(view.queryByRole('dialog', { name: '上下文已用' })).toBeNull() expect(view.queryByRole('button', { name: '上下文已用 25%' })).toBeNull() expect(view.getByRole('button', { name: '发送消息' })).toBeTruthy() fireEvent.click(view.getByRole('button', { name: 'close activity' })) - expect(view.getByRole('button', { name: '上下文已用 25%' })).toBe(meter) - fireEvent.click(meter) + fireEvent.click(view.getByRole('button', { name: '上下文已用 25%' })) expect(view.getByRole('dialog', { name: '上下文已用' })).toBeTruthy() expect(view.getByRole('button', { name: '发送消息' })).toBeTruthy() }) From d0ac0afbe2442697bce9a38ddcabfa26644a7f5d Mon Sep 17 00:00:00 2001 From: creatixchu Date: Mon, 21 Sep 2026 11:38:44 +0800 Subject: [PATCH 078/100] fix(composer): recognize pasted directories through entry metadata --- .../client/ui-conversation/README.i18n.yaml | 4 +-- packages/client/ui-conversation/README.md | 2 +- packages/client/ui-conversation/README.zh.md | 2 +- .../src/client/input/editor/keymap.ts | 25 +++++++++++++------ .../src/client/input/editor/view-binding.ts | 4 +-- .../tests/apply-inject.client.spec.tsx | 15 +++++------ .../tests/input-bar.client.spec.tsx | 23 +++++++++++++++++ 7 files changed, 55 insertions(+), 20 deletions(-) diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index 9d85f538e3..245cefdc28 100644 --- a/packages/client/ui-conversation/README.i18n.yaml +++ b/packages/client/ui-conversation/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md -README.md: 2154a7231e25123070b41f240f46cb71c754e3d2 -README.zh.md: 60943a47c63f92d8d1c8de70ce262da689cfccd4 +README.md: bcb4e15a56da8dde0441d825b354d6ae7352246d +README.zh.md: 1779bd6576cc87a5d6deaae1e9c32699c89b8368 diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index 2154a7231e..bcb4e15a56 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -62,7 +62,7 @@ Active transcripts in the main occurrence expose content-width drag handles in t The resident composer survives no-Session and Session transitions. Whitespace hides its placeholder; a whitespace-only draft without attachments cannot be sent. The no-Session state keeps the same composer surface mounted but inert while the Workspace picker connects a blank Session. The surface is a shell-owned Lexical editor: reference chips are atomic decorator nodes carrying the owner's serialization identity (submission expands them through the owner codec), claimed slash commands stay styled leading text, folder text references carry the folder glyph as an icon prefix, and the draft's clipboard projection is mirrored into the per-Session Conversation store. QueueDock reads `next-turn` directly from the Session `inbox` projection, including cold recovered messages. Queue operations address exact queue occurrences through the scoped `ctx.conversation` service; queue previews render sent text through the shared inline reference projection from `ui-primitives` (wire session forms fold to their label) and show local or durable images and files in original attachment order. Images use thumbnails; files use compact name-and-size cards. An edit exposes the literal sent text, and durable thumbnails resolve through the session image URL cache. Busy Enter behavior is stored in the Host-backed `ui-conversation` settings namespace. The composer keymap arbitrates the trigger menu's keys through the slash pipeline — Tab settles the highlighted completion (or drills a drillable one), Escape and Shift+Tab leave the menu without settling — and leaves every other key to the editor. An overlay that takes the keyboard hands it back through `SessionInput.focus()`, which rides Lexical's own focus so the caret returns where the draft left it rather than at the start. -Default sends commit optimistically: Enter clears the draft, occurrence table, and undo history in the same transaction, keeps the composer in `plain`, and runs the send as a detached attempt, so typing and further sends continue during the flight. `sendSession` registers a Session submission echo (`session.beginSubmission`) with the delivery mode before serializing, preserving selected image and file order in `pendingSubmissions`; Session derives the placement from that mode and its current running state, so idle sends use the transcript, busy Queue sends use QueueDock, and busy Steer sends use the pending-steering surface. It then yields one paint, encodes images through the browser's native `FileReader` data-URL path, and cites staged file receipts. Command submissions use the same receipts for generic files, so sending `/goal` or `/plan` never reads those browser files again. The prompt reuses the submission `requestId`; queue and history observation by that `rpcId` retires the echo once. Concurrent failures are restored together in submission order until the user edits the restored content; command submissions keep the frozen `submitting` phase. Detached attempts retain their attachment ids through admission and Session scope disposal. An observed retirement immediately exposes each image preview through the durable cache, replaces it with the canonical URL after fetching the admitted attachment, revokes each URL after its use ends, and releases file cards. Selected generic files enter one FIFO background-upload queue; `maxConcurrentFileUploads` defaults to two active Worker transports, the Conversation service retains queued and active operations plus byte progress across Session navigation, and removing a draft skips its queued transfer or aborts its active transport. Where the browser shell exposes `__DSH_HOST_PATHS__` (the Desktop application), dropped folders and dropped, picked, or pasted non-image files with a real path become `@path` chips; images keep uploading. Only drag-and-drop identifies directories; the file picker cannot select them, and clipboard files carry no directory classification. References require the `ui-reference` plugin and the original paths to remain readable by the model's file tools. Paths inside the workspace are relative; others remain absolute. The whole batch is validated before insertion, retains source order and selected text, and uses whitespace-separated, closed-quote mentions. A browser without the bridge refuses dropped folders; a Desktop folder without a reported path is rejected separately. Continuable subagents disable attachment intake and skip local echoes because their transport does not preserve the browser request id. +Default sends commit optimistically: Enter clears the draft, occurrence table, and undo history in the same transaction, keeps the composer in `plain`, and runs the send as a detached attempt, so typing and further sends continue during the flight. `sendSession` registers a Session submission echo (`session.beginSubmission`) with the delivery mode before serializing, preserving selected image and file order in `pendingSubmissions`; Session derives the placement from that mode and its current running state, so idle sends use the transcript, busy Queue sends use QueueDock, and busy Steer sends use the pending-steering surface. It then yields one paint, encodes images through the browser's native `FileReader` data-URL path, and cites staged file receipts. Command submissions use the same receipts for generic files, so sending `/goal` or `/plan` never reads those browser files again. The prompt reuses the submission `requestId`; queue and history observation by that `rpcId` retires the echo once. Concurrent failures are restored together in submission order until the user edits the restored content; command submissions keep the frozen `submitting` phase. Detached attempts retain their attachment ids through admission and Session scope disposal. An observed retirement immediately exposes each image preview through the durable cache, replaces it with the canonical URL after fetching the admitted attachment, revokes each URL after its use ends, and releases file cards. Selected generic files enter one FIFO background-upload queue; `maxConcurrentFileUploads` defaults to two active Worker transports, the Conversation service retains queued and active operations plus byte progress across Session navigation, and removing a draft skips its queued transfer or aborts its active transport. Where the browser shell exposes `__DSH_HOST_PATHS__` (the Desktop application), dropped or pasted folders and dropped, picked, or pasted non-image files with a real path become `@path` chips; images keep uploading. Drag-and-drop and paste identify directories through the browser entry API; when that API is absent or returns no entry, pasted items retain ordinary file handling. The file picker cannot select directories. References require the `ui-reference` plugin and the original paths to remain readable by the model's file tools. Paths inside the workspace are relative; others remain absolute. The whole batch is validated before insertion, retains source order and selected text, and uses whitespace-separated, closed-quote mentions. A browser without the bridge refuses dropped folders; a Desktop folder without a reported path is rejected separately. Continuable subagents disable attachment intake and skip local echoes because their transport does not preserve the browser request id. Queued submission echoes show “Sending…” beside disabled edit, remove, and steer buttons; a collapsed dock keeps the sending status in its header. A matching Host queue row replaces the echo and enables each action according to its normal text-content and running-state requirements. Prompt acknowledgement alone does not enable queue actions. A failed submission removes its echo and displays an error; the composer restores the failed draft when it is empty or still contains the previous automatic restoration, preserving subsequently typed text. diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index 60943a47c6..1779bd6576 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -62,7 +62,7 @@ Session 首次绑定或缓存的 Session 成为 current 时,shell 会在渲染 常驻 composer 在无 Session 与有 Session 之间保持挂载。输入空白字符会隐藏占位提示;没有附件的纯空白草稿无法发送。无 Session 时,同一个编辑器表面保持 inert,Workspace picker 连接 blank Session。该表面是 shell 所有的 Lexical 编辑器:引用 chip 是携带 owner 序列化身份的原子 decorator 节点(提交时经 owner codec 展开),已认领的 slash command 保持为带样式的行首文本,文件夹文本引用以图标前缀携带文件夹图形,草稿的剪贴板投影镜像到逐 Session Conversation store。QueueDock 直接从 Session 的 `inbox` 投影读取 `next-turn`,包含从冷状态恢复的消息。Queue 操作通过 scoped `ctx.conversation` service 寻址准确的 queue occurrence;queue 预览经 `ui-primitives` 的共享行内引用投影渲染已发送文本(wire 会话形式折叠为其标签),并按原始附件顺序展示本地或持久化的图片和文件。图片使用缩略图,文件使用紧凑的名称与大小卡片。编辑态展示字面发送文本,持久化缩略图通过会话图片 URL 缓存解析。繁忙时 Enter 行为保存在 Host-backed `ui-conversation` settings namespace。 composer 键盘映射经斜杠流水线裁决触发菜单的按键——Tab 确认高亮补全项(可下钻项则下钻),Escape 与 Shift+Tab 离开菜单且不选定——其余按键交给编辑器自身。 接管键盘的浮层通过 `SessionInput.focus()` 把键盘还回来,该路径走 Lexical 自己的 focus,因此光标回到草稿原来的位置而不是开头。 -默认发送采用乐观提交:Enter 在同一事务里清空草稿、occurrence 表和撤销历史,composer 保持 `plain`,发送作为 detached attempt 运行,发送期间可以继续输入和提交。`sendSession` 在序列化之前用投递模式注册 Session 提交回显(`session.beginSubmission`),并在 `pendingSubmissions` 中保留图片与文件的选择顺序;Session 根据该模式与当前运行状态推导位置,因此空闲发送进入 transcript(文本记录),繁忙时 Queue 进入 QueueDock,繁忙时 Steer 进入 pending-steering 区域。随后让出一帧,图片经浏览器原生 `FileReader` data-URL 路径编码,文件则引用已暂存凭证。命令提交也用同一凭证表示通用文件,因此发送 `/goal` 或 `/plan` 时不会再次读取这些浏览器文件。提示词复用提交 `requestId`;queue 或历史以同一 `rpcId` 被观察后,回显只退休一次。多个并发发送失败时,在用户编辑还原内容之前按提交顺序合并还原;命令提交保持冻结的 `submitting` 阶段。Detached attempt 持有附件 id,直到 admission 完成或 Session scope 销毁。回显以 observed 退休时,durable 图片缓存立即公开每个预览 URL,读取 admitted 附件后用规范化 URL 替换预览,并在各 URL 停止使用后撤销,同时释放文件卡。选中的通用文件进入同一个先进先出的后台上传队列;`maxConcurrentFileUploads` 默认允许两个 Worker transport 同时运行,Conversation 服务在切换 Session 时继续持有排队和运行中的传输操作及字节进度,移除草稿会跳过排队中的传输或中止正在运行的传输。浏览器 shell 暴露 `__DSH_HOST_PATHS__` 时(桌面应用),拖入的文件夹以及拖入、选择或粘贴的带真实路径的非图片文件会成为 `@路径` chip;图片仍然上传。只有拖放会识别目录,文件选择器不能选择目录,剪贴板文件也不携带目录分类。引用需要启用 `ui-reference` 插件,原路径也必须仍可由模型的文件工具读取。工作区内的路径使用相对形式,其他路径保留绝对形式。整批文件先校验再插入,保留来源顺序和已选中的文字,引用之间有空白分隔,含空格的路径使用闭合引号。没有该桥的浏览器会拒绝拖入的文件夹,桌面端无法获取文件夹路径时单独报错。continuable 子代理禁用附件入口,也不创建本地回显,因为其 transport 不保留浏览器 request id。 +默认发送采用乐观提交:Enter 在同一事务里清空草稿、occurrence 表和撤销历史,composer 保持 `plain`,发送作为 detached attempt 运行,发送期间可以继续输入和提交。`sendSession` 在序列化之前用投递模式注册 Session 提交回显(`session.beginSubmission`),并在 `pendingSubmissions` 中保留图片与文件的选择顺序;Session 根据该模式与当前运行状态推导位置,因此空闲发送进入 transcript(文本记录),繁忙时 Queue 进入 QueueDock,繁忙时 Steer 进入 pending-steering 区域。随后让出一帧,图片经浏览器原生 `FileReader` data-URL 路径编码,文件则引用已暂存凭证。命令提交也用同一凭证表示通用文件,因此发送 `/goal` 或 `/plan` 时不会再次读取这些浏览器文件。提示词复用提交 `requestId`;queue 或历史以同一 `rpcId` 被观察后,回显只退休一次。多个并发发送失败时,在用户编辑还原内容之前按提交顺序合并还原;命令提交保持冻结的 `submitting` 阶段。Detached attempt 持有附件 id,直到 admission 完成或 Session scope 销毁。回显以 observed 退休时,durable 图片缓存立即公开每个预览 URL,读取 admitted 附件后用规范化 URL 替换预览,并在各 URL 停止使用后撤销,同时释放文件卡。选中的通用文件进入同一个先进先出的后台上传队列;`maxConcurrentFileUploads` 默认允许两个 Worker transport 同时运行,Conversation 服务在切换 Session 时继续持有排队和运行中的传输操作及字节进度,移除草稿会跳过排队中的传输或中止正在运行的传输。浏览器 shell 暴露 `__DSH_HOST_PATHS__` 时(桌面应用),拖入或粘贴的文件夹以及拖入、选择或粘贴的带真实路径的非图片文件会成为 `@路径` chip;图片仍然上传。拖放和粘贴通过浏览器 entry API 识别目录;该 API 不可用或没有返回 entry 时,粘贴项沿用普通文件处理。文件选择器不能选择目录。引用需要启用 `ui-reference` 插件,原路径也必须仍可由模型的文件工具读取。工作区内的路径使用相对形式,其他路径保留绝对形式。整批文件先校验再插入,保留来源顺序和已选中的文字,引用之间有空白分隔,含空格的路径使用闭合引号。没有该桥的浏览器会拒绝拖入的文件夹,桌面端无法获取文件夹路径时单独报错。continuable 子代理禁用附件入口,也不创建本地回显,因为其 transport 不保留浏览器 request id。 排队提交的本地回显在禁用的编辑、删除、插话按钮旁显示“发送中…”;折叠后的队列在标题栏保留发送状态。匹配的 Host 队列行替换回显后,各操作按原有的纯文本内容和运行状态要求启用。仅收到提示词确认不会启用队列操作。提交失败会移除回显并显示错误;输入框为空或仍保留上一次自动恢复的内容时,composer 恢复失败草稿,保留用户随后输入的文字。 diff --git a/packages/client/ui-conversation/src/client/input/editor/keymap.ts b/packages/client/ui-conversation/src/client/input/editor/keymap.ts index 42c217caa0..7291f2c25a 100644 --- a/packages/client/ui-conversation/src/client/input/editor/keymap.ts +++ b/packages/client/ui-conversation/src/client/input/editor/keymap.ts @@ -34,8 +34,12 @@ export interface ComposerKeymapHandlers { canSubmit(): boolean /** The Enter gesture after every guard passed; `accelerated` = Ctrl/Cmd held. */ submit(accelerated: boolean): void - /** Pasted files (image intake). */ - intakeFiles(files: readonly File[]): void + /** + * Pasted files with directory metadata supplied by the clipboard entry API. + * @param files - browser files in clipboard order. + * @param directories - known directory members; absent when no entry identifies a directory. + */ + intakeFiles(files: readonly File[], directories?: ReadonlySet): void /** Pasted plain text (sanitized insertion through the shell). */ pasteText(text: string): void } @@ -154,11 +158,18 @@ export function registerComposerKeymap(editor: LexicalEditor, handlers: Composer // deliver clipboardData on plain events. const clipboardData = (event as ClipboardEvent).clipboardData ?? null if (clipboardData === null) return false - const files = Array.from(clipboardData.items) - .filter(item => item.kind === 'file') - .map(item => item.getAsFile()) - .filter((file): file is File => file !== null) - if (files.length > 0) handlers.intakeFiles(files) + const files: File[] = [] + const directories = new Set() + for (const item of clipboardData.items) { + if (item.kind !== 'file') continue + const file = item.getAsFile() + if (file === null) continue + files.push(file) + if (typeof item.webkitGetAsEntry === 'function' && item.webkitGetAsEntry()?.isDirectory === true) { + directories.add(file) + } + } + if (files.length > 0) handlers.intakeFiles(files, directories.size === 0 ? undefined : directories) const text = clipboardData.getData('text/plain') if (text === '') { if (files.length === 0) return false diff --git a/packages/client/ui-conversation/src/client/input/editor/view-binding.ts b/packages/client/ui-conversation/src/client/input/editor/view-binding.ts index 8dcd3d8c63..89218a887c 100644 --- a/packages/client/ui-conversation/src/client/input/editor/view-binding.ts +++ b/packages/client/ui-conversation/src/client/input/editor/view-binding.ts @@ -14,7 +14,7 @@ interface DraftViewGate { running: boolean steeringAvailable: boolean busyEnter: BusyEnterBehavior - intakeFiles: (files: readonly File[]) => void + intakeFiles: (files: readonly File[], directories?: ReadonlySet) => void uploadsPending: boolean showToast: (text: string) => void t: ComposerBarProps['t'] @@ -136,7 +136,7 @@ export function installDraftKeymap( g.steeringAvailable, )) }, - intakeFiles: (files) => { gate.current.intakeFiles(files) }, + intakeFiles: (files, directories) => { gate.current.intakeFiles(files, directories) }, pasteText: (text) => { if (gate.current.machineBusy || gate.current.locked) return keyboard.paste(text) diff --git a/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx b/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx index e62f51b58b..db7eb068ba 100644 --- a/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx +++ b/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx @@ -436,7 +436,7 @@ describe('Conversation inject API', () => { } }) - it('preserves selected text and source order when files arrive inside a paste transaction', async () => { + it('preserves selected text and file order and restores pasted directory chips from the draft', async () => { vi.stubGlobal('__DSH_HOST_PATHS__', { pathFor: (file: File) => `/proj/${file.name}` }) onTestFinished(() => { vi.unstubAllGlobals(); cleanup() }) const b = await bench() @@ -453,18 +453,19 @@ describe('Conversation inject API', () => { const off = registerComposerKeymap(editor, { arbitrate: () => 'pass', space: () => false, dismissPopup: () => {}, canSubmit: () => true, submit: () => {}, pasteText: (text) => { composer.keyboard!.paste(text) }, - intakeFiles: (files) => { expect(composer.addFiles?.(files)).toBeNull() }, + intakeFiles: (files, directories) => { expect(composer.addFiles?.(files, directories)).toBeNull() }, }) onTestFinished(off) - const files = [new File([], 'a.txt'), new File([], 'b.txt')] + const folder = new File([], 'my project') + const files = [new File([], 'a.txt'), folder, new File([], 'b.txt')] const event = new KeyboardEvent('paste', { cancelable: true }) Object.defineProperty(event, 'clipboardData', { value: { - items: files.map(file => ({ kind: 'file', getAsFile: () => file })), getData: () => '', + items: files.map(file => ({ + kind: 'file', getAsFile: () => file, webkitGetAsEntry: () => ({ isDirectory: file === folder }), + })), getData: () => '', } }) editor.update(() => { editor.dispatchCommand(PASTE_COMMAND, event) }, { discrete: true }) - expect(state.getSnapshot().draft).toBe('读取 @a.txt @b.txt ') - const folder = new File([], 'my project') - expect(composer.addFiles?.([folder], new Set([folder]))).toBeNull() + expect(state.getSnapshot().draft).toBe('读取 @a.txt @"my project/" @b.txt ') const view = render(
    {projectUserText(state.getSnapshot().draft, [])}
    ) expect(view.container.querySelector('[data-ref-chip="folder"]')?.textContent).toBe('my project') expect(view.container.querySelector('[data-ref-chip="folder"]')?.getAttribute('title')).toBe('@"my project/"') diff --git a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx index fc02732780..e1090b866e 100644 --- a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx +++ b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx @@ -349,6 +349,29 @@ describe('image draft rail', () => { await vi.waitFor(() => { expect(shell.snapshot.draft).toBe('同时粘贴的文字') }) }) + it('passes known clipboard directories and keeps files whose entry metadata is unavailable', () => { + const addFiles = vi.fn(() => null) + const { textarea } = bench({ addFiles }) + const folder = new File([], 'folder with spaces') + const emptyFile = new File([], 'empty-file') + const withoutApi = new File([], 'without-api') + const withoutEntry = new File([], 'without-entry') + fireEvent.paste(textarea, { + clipboardData: { + items: [ + { kind: 'string', getAsFile: () => null }, + { kind: 'file', getAsFile: () => folder, webkitGetAsEntry: () => ({ isDirectory: true }) }, + { kind: 'file', getAsFile: () => emptyFile, webkitGetAsEntry: () => ({ isDirectory: false }) }, + { kind: 'file', getAsFile: () => withoutApi }, + { kind: 'file', getAsFile: () => withoutEntry, webkitGetAsEntry: () => null }, + { kind: 'file', getAsFile: () => null }, + ], + getData: () => '', + }, + }) + expect(addFiles).toHaveBeenCalledWith([folder, emptyFile, withoutApi, withoutEntry], new Set([folder])) + }) + it('pre-checks projected limits at intake: whole-batch refusal with product copy, none added', () => { const limits = { maxImageBytes: 1024 * 1024, From 35f3abf1fa76a9de9110fb24cb7f489c2ba0d14e Mon Sep 17 00:00:00 2001 From: _Kerman Date: Mon, 21 Sep 2026 11:44:37 +0800 Subject: [PATCH 079/100] fix(agent-loop): copy the cancel cause before logging turn/end Node's fetch assigns an enumerable `stack` string onto the abort reason object it receives, and the loop logged that same object into `turn/end`. The undici trace became durable session data under a field no reader declares. A transport adding a property JSON discards instead made `Session.append` reject the ending, leaving a turn with no close. `abortedCancelCause()` narrows the untyped `AbortSignal.reason` once and copies the declared fields, replacing the three `as AgentCancelCause` assertions at the two read sites and the log write. --- docs/architecture.i18n.yaml | 4 +- docs/architecture.md | 2 +- docs/architecture.zh.md | 2 +- docs/subsystems/core.i18n.yaml | 4 +- docs/subsystems/core.md | 2 +- docs/subsystems/core.zh.md | 2 +- packages/core/agent-loop/README.i18n.yaml | 4 +- packages/core/agent-loop/README.md | 2 + packages/core/agent-loop/README.zh.md | 2 + packages/core/agent-loop/src/agent.ts | 37 +++++++- packages/core/agent-loop/tests/cancel.spec.ts | 91 ++++++++++++++++++- 11 files changed, 135 insertions(+), 17 deletions(-) diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index 66b457c8fa..a63b916549 100644 --- a/docs/architecture.i18n.yaml +++ b/docs/architecture.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 docs/architecture.md -architecture.md: 5e0bb09770e013349bcc1326bea1eab9cdc3e595 -architecture.zh.md: a146c93c14ef0f563babf98f7311f1e5686895cc +architecture.md: 9b0daeef5ab95335d650ea987cd4588f28d3f870 +architecture.zh.md: 0d8581063d43723a8fdbf4190ec468f6de103a27 diff --git a/docs/architecture.md b/docs/architecture.md index 5e0bb09770..9b0daeef5a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -112,7 +112,7 @@ One inbox feeds the driver; injected context waits for a waking message. AgentLo `agent/pre-step` decides the accepted input. Listeners may rewrite or reject claimed messages; a rejected or empty first claim closes a durable turn without a step. An enter decision may set `startsRequestSeries`: the loop logs a fresh `request/header` (reason `series`, or `change` with `startsSeries: true` when the envelope also changed). Wrapping listeners preserve that declaration with `{ ...decision, messages }`. After assembly and `step/start`, `agent/request` and `prepareCall()` resolve the actual route before the system prompt and accepted users are committed; cancellation during either async phase commits neither. The prepared call capability governs prompt admission, not the preceding `request/context`. Every attempt synchronously reconciles the same rendered assembly, appends users only on the first attempt, logs header/context as needed, and derives and freezes the request before streaming the bound call. Retries do not repeat assembly or `agent/pre-step`. Surface replacements and image-offload decisions after attachment start a new request series, including during the first resumed pre-step; unchanged resume continues the series. The first admitted step reserves the system head before user messages even for an empty prompt (no wire message). The prompt travels only as `system/message` history: an empty rendering clears all active system nodes, leaving no old prompt model-visible; capable routes can append non-empty updates after the cached prefix; incapable routes and new request series consolidate non-empty prompt text at the first system node, with logged empty replacements for non-empty later system nodes ([decision](../.agents/notes/implemented/architecture/2026-09-02-system-prompt-as-surface-node.md); [decision rule](../packages/core/agent-loop/README.md#understand-the-implementation)). -The loop sends immutable requests while keeping cancellation live. It reuses message-freeze evidence only for identities it has fully frozen; [agent-loop](../packages/core/agent-loop/README.md) owns the request construction rules. +The loop sends immutable requests while keeping cancellation live. It reuses message-freeze evidence only for identities it has fully frozen; [agent-loop](../packages/core/agent-loop/README.md) owns the request construction and cancellation-cause rules. Details: the [sequence diagram](agent-lifecycle.md), the [tool pipeline](tool-execution-pipeline.md), and [cancellation and error recovery](subsystems/core.md#the-agent-handle). diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index a146c93c14..0d8581063d 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -116,7 +116,7 @@ turn/end `agent/pre-step` 决定接纳的输入。监听器可以改写或拒绝已领取消息;首次领取被拒绝或为空时,关闭不含步骤的持久轮次。enter 决策可设置 `startsRequestSeries`:循环记录新的 `request/header`(原因为 `series`,或在封装同时变化时为携带 `startsSeries: true` 的 `change`)。包装监听器通过 `{ ...decision, messages }` 保留该声明。组装与 `step/start` 之后,`agent/request` 和 `prepareCall()` 先解析实际路由,再提交系统提示词与已接纳用户消息;在任一异步阶段取消都不会提交这两者。提示词准入依据已准备调用的能力,而非先前的 `request/context`。每次尝试同步协调同一份已渲染组装结果、仅在首次尝试追加用户消息、按需记录 header/context、派生并冻结请求,再通过绑定调用发起流式请求。重试不重复组装或 `agent/pre-step`。附接后的 surface 替换和图片省略决定开启新请求序列,包括恢复后的首次 pre-step 中发生的替换;未变化的恢复延续序列。首次接纳的步骤在用户消息之前预留系统头节点,即使提示词为空(不产生协议消息)。提示词仅通过 `system/message` 历史传递:空渲染文本清除所有生效的系统节点,模型不再看到旧提示词;具备能力的路由可在缓存前缀之后追加非空更新;不具备能力的路由与新请求序列将非空提示词文本归并到首个系统节点,并为非空的后续系统节点记录空内容替换([决策](../.agents/notes/implemented/architecture/2026-09-02-system-prompt-as-surface-node.zh.md);[决策规则](../packages/core/agent-loop/README.zh.md#understand-the-implementation))。 -循环发送不可变请求,同时保留实时取消能力。只有已由该循环完整冻结的消息对象身份才能复用冻结证明;[agent-loop](../packages/core/agent-loop/README.zh.md)拥有请求构造规则。 +循环发送不可变请求,同时保留实时取消能力。只有已由该循环完整冻结的消息对象身份才能复用冻结证明;[agent-loop](../packages/core/agent-loop/README.zh.md)拥有请求构造与取消原因记录规则。 详情见[时序图](agent-lifecycle.zh.md)、[工具流水线](tool-execution-pipeline.zh.md)和[取消与错误恢复](subsystems/core.zh.md#the-agent-handle)。 diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml index e1fd460b35..3c4fdb398a 100644 --- a/docs/subsystems/core.i18n.yaml +++ b/docs/subsystems/core.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 docs/subsystems/core.md -core.md: bba024e8ee4cb89ceac4698bf66f060c7f74dcd6 -core.zh.md: 2e04d5a9a078f3411b2a0d338835ec7d71296f10 +core.md: a1e876dcfcd31dfb9fd4840d0d0e217bb71e43bb +core.zh.md: a63e38cf6381d97656f2350cc16502030772b1a7 diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md index bba024e8ee..a1e876dcfc 100644 --- a/docs/subsystems/core.md +++ b/docs/subsystems/core.md @@ -297,7 +297,7 @@ type AgentCancelCause = | { readonly kind: 'disposed' } ``` -The cause is a TypeScript-enforced same-process input. An active cancellation holder copies it into the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` records the outcome as `{ kind: 'aborted', reason: TurnEndCancelCause }`, so the cancel cause lands in the terminal result. +The cause is a TypeScript-enforced same-process input. An active cancellation holder exposes that same object as the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` records the outcome as `{ kind: 'aborted', reason: TurnEndCancelCause }`, so the cancel cause lands in the terminal result. The [event taxonomy](../architecture.md#events) owns the `agent/*` lifecycle, checkpoint, and waterfall contracts. Turn and step boundaries are durable session events rather than agent emits. diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md index 2e04d5a9a0..a63e38cf63 100644 --- a/docs/subsystems/core.zh.md +++ b/docs/subsystems/core.zh.md @@ -301,7 +301,7 @@ type AgentCancelCause = | { readonly kind: 'disposed' } ``` -cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者会将它复制到仅运行时的 `AbortSignal.reason`;signal 不授予协作监听器任何分类权限。持久 `turn/end` 以 `{ kind: 'aborted', reason: TurnEndCancelCause }` 记录结果,取消原因随终态结果一起持久化。 +cause 是由 TypeScript 强制约束的同进程输入。活跃的取消持有者把同一个对象暴露为仅运行时的 `AbortSignal.reason`;signal 不授予协作监听器任何分类权限。持久 `turn/end` 以 `{ kind: 'aborted', reason: TurnEndCancelCause }` 记录结果,取消原因随终态结果一起持久化。 [事件分类](../architecture.zh.md#events)负责 `agent/*` 生命周期、检查点与 waterfall(瀑布式事件)约定。轮次和步骤边界是持久会话事件,而不是 agent emit。 diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml index 8a503e803f..7bd774e9a4 100644 --- a/packages/core/agent-loop/README.i18n.yaml +++ b/packages/core/agent-loop/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/core/agent-loop/README.md -README.md: 7c3073aefb90fa2ec74d521d6c9d97aff5f74ace -README.zh.md: 44621a0b02eadfc574f6f6b924f64cfeb4141cd3 +README.md: bfe7944c75f7cab7565f966863f7d7118c61ed97 +README.zh.md: d44f6cd16e728491d97a3e00085f0225d52c5cdf diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md index 7c3073aefb..bfe7944c75 100644 --- a/packages/core/agent-loop/README.md +++ b/packages/core/agent-loop/README.md @@ -122,6 +122,8 @@ Prompt admission uses the actual `prepareCall()` result, not the preceding `requ ### Failure and cancellation +Cancellation records a fresh `AgentCancelCause` in `turn/end`, retaining the caller's `kind` and the hook's `reason` text. The live `AbortSignal.reason` remains the caller's object, which a transport may extend — Node's fetch assigns a `stack` onto it — so the copy keeps that trace out of the log and keeps the ending appendable. + Final adapter selection, dispatch, and iteration failures arrive as terminal finishes and enter `agent/request-error`; a handling listener returns `{ kind: 'retry' }` without calling `next()`, while an unhandled failure is terminal. Middleware, result-processing, tool, and other extension failures remain thrown and close the turn directly — plugin failure ends the turn, not the loop. Undispatched model tool calls after cancellation receive synthetic `tool/call` plus `ABORTED_BEFORE_DISPATCH` result pairs. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns the signal lifecycle. diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md index 44621a0b02..d44f6cd16e 100644 --- a/packages/core/agent-loop/README.zh.md +++ b/packages/core/agent-loop/README.zh.md @@ -122,6 +122,8 @@ const handle = await ctx.agents.create({ ### 失败与取消 +取消时,循环在 `turn/end` 中记录一份新的 `AgentCancelCause`,保留调用方的 `kind` 和 hook 的 `reason` 文本。实时 `AbortSignal.reason` 仍是调用方的那个对象,传输层可能向其添加属性——Node 的 fetch 会给它赋一个 `stack`——因此这份拷贝既让该调用栈不进入日志,也让结束事件保持可追加。 + 最终适配器选择、分发与迭代失败以终止结束的形式到达并进入 `agent/request-error`;处理该失败的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`,未被处理的失败则是终态。Middleware、结果处理、工具及其他扩展失败仍会抛出并直接关闭轮次——插件失败结束的是轮次,不是循环。取消后未分发的模型工具调用会收到合成的 `tool/call` 加 `ABORTED_BEFORE_DISPATCH` 结果对。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md)拥有信号生命周期。 diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index 4ea7593551..ce7bbe8ab8 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -23,7 +23,7 @@ import { errorChain, markAgentLoopRequest, } from '@deepseek-ai/dsh-llm' -import { deepFreeze } from '@deepseek-ai/dsh-util-values' +import { assertNever, deepFreeze } from '@deepseek-ai/dsh-util-values' import type { Scope } from '@deepseek-ai/dsh-scope' import { createScope } from '@deepseek-ai/dsh-scope' import type { EpochHeader, RequestContext, Session, SessionId, TurnEndReason, UserMessage } from '@deepseek-ai/dsh-session' @@ -68,6 +68,31 @@ function requestProposal(header: EpochHeader): LlmCallConfig { return proposal } +/** + * Read the cause {@link ReactLoopAgent.cancel} aborted a loop-owned signal + * with, copying the fields `turn/end` records. The live reason stays the + * caller's object, and Node's fetch assigns a `stack` onto it that + * `Session.append` would either log or reject as data JSON cannot hold. + * @param signal - a turn or maintenance signal this loop owns. + * @returns the copied cause, or undefined while the signal is still live. + */ +function abortedCancelCause(signal: AbortSignal): AgentCancelCause | undefined { + if (!signal.aborted) return undefined + // `cancel()` is the only aborter of the signals this loop owns. + const cause = signal.reason as AgentCancelCause + switch (cause.kind) { + case 'user': + case 'parent': + case 'disposed': + return { kind: cause.kind } + case 'hook': + return { kind: 'hook', reason: cause.reason } + /* v8 ignore next -- cancel accepts the closed AgentCancelCause union */ + default: + return assertNever(cause) + } +} + /** Drives one session through turn and step boundaries. */ export class ReactLoopAgent implements Agent { readonly inbox: ReactLoopInbox @@ -170,7 +195,7 @@ export class ReactLoopAgent implements Agent { return await job(maintenance.abort.signal) } finally { this.setPhase({ kind: 'idle', lastTurn: maintenance.lastTurn }) - const cause = maintenance.abort.signal.reason as AgentCancelCause | undefined + const cause = abortedCancelCause(maintenance.abort.signal) if (cause?.kind !== 'disposed' && maintenance.wakeRequested && this.inbox.hasPending) this.wakeDriver() done.resolve() } @@ -190,7 +215,7 @@ export class ReactLoopAgent implements Agent { // Maintenance and aborted drivers cannot deliver the wake: latch it for // replay at convergence. Live drivers claim queued work themselves; // disposal never latches, so teardown waits on no model turn. - const reason = this.phase.abort.signal.reason as AgentCancelCause | undefined + const reason = abortedCancelCause(this.phase.abort.signal) if (reason?.kind !== 'disposed' && (this.phase.kind === 'maintenance' || wakeAfterAbort)) { this.phase.wakeRequested = true } @@ -321,8 +346,10 @@ export class ReactLoopAgent implements Agent { target = 'next-step' } } catch (error: unknown) { - if (signal.aborted) { - turnEnds = { kind: 'aborted', reason: signal.reason as AgentCancelCause } + // A cause is present exactly while the signal is aborted. + const cause = abortedCancelCause(signal) + if (cause !== undefined) { + turnEnds = { kind: 'aborted', reason: cause } throw error } // Every failure is structured: an `LlmError` keeps its facts, anything diff --git a/packages/core/agent-loop/tests/cancel.spec.ts b/packages/core/agent-loop/tests/cancel.spec.ts index 872e983639..add362835b 100644 --- a/packages/core/agent-loop/tests/cancel.spec.ts +++ b/packages/core/agent-loop/tests/cancel.spec.ts @@ -3,7 +3,8 @@ import { ToolCallId, createUserMessage, expandAssistantStream } from '@deepseek- * Tests for the queue-aware `Agent.cancel()` primitive. The default clears * queued and steering work, while `keepInbox` preserves pending input for a * later wake after the active turn reaches quiescence. The suite - * covers every landing window plus signal reset and `whenIdle()` quiescence. + * covers every landing window plus signal reset, `whenIdle()` quiescence, and + * the cause each cancelled turn records. * @module dsh-agent-loop/tests/cancel */ @@ -13,7 +14,7 @@ import LlmRuntime from '@deepseek-ai/dsh-llm' import SessionStore, { Session, SessionId, SessionLogOffset, TurnEndReason } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' import ToolRuntime, { defineContentToolFixture, TOOL_ABORTED_BEFORE_DISPATCH } from '@deepseek-ai/dsh-tools' -import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent' +import AgentRegistry, { type Agent, type AgentCancelCause } from '@deepseek-ai/dsh-agent' import AgentLoop from '@deepseek-ai/dsh-agent-loop' import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection' import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts' @@ -57,6 +58,92 @@ function userTexts(agent: Agent): string[] { } describe('Agent.cancel()', () => { + /** + * Cancel one turn, let `mutate` alter the caller's cause the way a transport + * does once it observes the abort, then report every recorded turn ending. + */ + async function endingsAfterMutatingCancel( + cause: AgentCancelCause, + mutate: (cause: AgentCancelCause) => void, + ): Promise<{ endings: TurnEndReason[]; errors: unknown[]; requests: number }> { + const adapter = new MockAdapter([textResponse('next turn')]) + const ctx = await harness(adapter) + try { + const agent = await ctx.agentLoop.create(SessionId('cancel-mutated-cause'), { provider: 'mock', model: 'mock' }) + const errors: unknown[] = [] + ctx.on('agent/error', ({ error }) => { errors.push(error) }) + ctx.on('agent/request', ({ signal, turn }, next) => { + if (turn === 1) { + signal.addEventListener('abort', () => { mutate(cause) }, { once: true }) + agent.cancel(cause) + } + return next() + }) + + send(agent, 'cancel this turn') + await agent.whenIdle() + // A second turn proves the cancelled one closed: an unclosed turn would + // make the next `turn/start` fail the session's turn-bracket invariant. + send(agent, 'continue') + await agent.whenIdle() + + return { + endings: agent.session.snapshotEvents() + .flatMap(event => event.type === 'turn/end' ? [event.data.reason] : []), + errors, + requests: adapter.requests.length, + } + } finally { + await ctx.fiber.dispose() + } + } + + /** + * Node's fetch assigns an enumerable `stack` string onto the abort reason it + * receives (`node:internal/deps/undici`), which a plain assignment reproduces. + */ + function assignTransportStack(cause: AgentCancelCause): void { + Object.defineProperty(cause, 'stack', { + value: 'Error\n at node:internal/deps/undici/undici', + enumerable: true, + writable: true, + configurable: true, + }) + } + + /** Add an own property JSON discards, the descriptor `Error.captureStackTrace` produces. */ + function captureNonEnumerableStack(cause: AgentCancelCause): void { + Error.captureStackTrace(cause) + } + + it.each([ + { kind: 'user' }, + { kind: 'parent' }, + { kind: 'hook', reason: 'policy stopped this turn' }, + { kind: 'disposed' }, + ])('records $kind cancellation without the stack a transport assigned to the abort reason', async (cause) => { + const expectedCause = { ...cause } + + const { endings, errors, requests } = await endingsAfterMutatingCancel(cause, assignTransportStack) + + expect(Object.getOwnPropertyDescriptor(cause, 'stack')?.enumerable).toBe(true) + expect(errors).toEqual([]) + expect(endings).toEqual([{ kind: 'aborted', reason: expectedCause }, { kind: 'completed' }]) + expect(requests).toBe(1) + }) + + it('closes a cancelled turn whose abort reason acquired an own property JSON discards', async () => { + const cause: AgentCancelCause = { kind: 'user' } + + // `Session.append` rejects a payload JSON cannot hold rather than logging a + // lossy ending, so the caller's object must not reach the log by reference. + const { endings, errors } = await endingsAfterMutatingCancel(cause, captureNonEnumerableStack) + + expect(Object.getOwnPropertyDescriptor(cause, 'stack')?.enumerable).toBe(false) + expect(errors).toEqual([]) + expect(endings).toEqual([{ kind: 'aborted', reason: { kind: 'user' } }, { kind: 'completed' }]) + }) + it('cancel() on an idle agent with nothing queued is a no-op; the next prompt runs (F2 leak guard)', async () => { const adapter = new MockAdapter([textResponse('reply')]) const ctx = await harness(adapter) From 3f17ab99d497a4717d76e017893530b93fa7ef64 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Mon, 21 Sep 2026 11:46:55 +0800 Subject: [PATCH 080/100] refactor(chat): restore ui-chat import paths to master Six ui-chat modules carried import-path and line-wrap differences unrelated to the jobs seam; they now match master byte for byte. --- packages/client/ui-chat/src/client/chat/CompactionItem.tsx | 2 +- packages/client/ui-chat/src/client/chat/ContextBody.tsx | 5 ++--- packages/client/ui-chat/src/client/chat/MessageItem.tsx | 2 +- packages/client/ui-chat/src/client/chat/turn-assistant.ts | 2 +- .../client/ui-chat/src/client/conversation-nodes/partial.ts | 4 +++- packages/client/ui-chat/src/client/model/tool-call-tree.ts | 4 +++- 6 files changed, 11 insertions(+), 8 deletions(-) diff --git a/packages/client/ui-chat/src/client/chat/CompactionItem.tsx b/packages/client/ui-chat/src/client/chat/CompactionItem.tsx index 2a70b148c4..006b570557 100644 --- a/packages/client/ui-chat/src/client/chat/CompactionItem.tsx +++ b/packages/client/ui-chat/src/client/chat/CompactionItem.tsx @@ -1,4 +1,3 @@ -import type { CompactionSummaryNode } from '@deepseek-ai/dsh-client-ui-conversation/client' // A compaction marker does not replace shadowed transcript rows. It is // expandable only when the current window includes its cited summary. @@ -11,6 +10,7 @@ import { } from '@deepseek-ai/dsh-client-ui-primitives' import type { ChatViewSlotProps } from '../contract/slots.ts' import { markdownLabels } from '../markdown-labels.ts' +import type { CompactionSummaryNode } from '../contract/snapshot.ts' import css from './MessageItem.module.css' interface CompactionItemProps { diff --git a/packages/client/ui-chat/src/client/chat/ContextBody.tsx b/packages/client/ui-chat/src/client/chat/ContextBody.tsx index 3278f3d876..6501ffda8f 100644 --- a/packages/client/ui-chat/src/client/chat/ContextBody.tsx +++ b/packages/client/ui-chat/src/client/chat/ContextBody.tsx @@ -7,9 +7,8 @@ import type { ReactNode } from 'react' import { JsonBlock } from '@deepseek-ai/dsh-client-ui-primitives' import type { ChatViewSlotProps } from '../contract/slots.ts' -import type { - ContextMessageNode, KnownContextForm, -} from '@deepseek-ai/dsh-client-ui-conversation/client' +import type { ContextMessageNode } from '../contract/snapshot.ts' +import type { KnownContextForm } from '@deepseek-ai/dsh-client-ui-conversation/client' import css from './ContextBody.module.css' /** Model-facing text stays bounded at the disclosure, not at the producer. */ diff --git a/packages/client/ui-chat/src/client/chat/MessageItem.tsx b/packages/client/ui-chat/src/client/chat/MessageItem.tsx index 12296dff11..e1875f5ce2 100644 --- a/packages/client/ui-chat/src/client/chat/MessageItem.tsx +++ b/packages/client/ui-chat/src/client/chat/MessageItem.tsx @@ -1,10 +1,10 @@ -import type { ModelRetryNode, TurnErrorNode, UserMessageNode } from '@deepseek-ai/dsh-client-ui-conversation/client' import { Fragment, memo, useEffect, useMemo, useState } from 'react' import type { ReactNode } from 'react' import type { PendingSubmission } from '@deepseek-ai/dsh-api-session-controller/client' import type { MessageImageSource } from '@deepseek-ai/dsh-client-ui-conversation/client' import { fileExtension, FileTypeIcon, fileSizeText, JsonBlock, projectUserText, StateDot } from '@deepseek-ai/dsh-client-ui-primitives' import type { ChatNodeOwnerProps, ChatNodeViewProps, ChatViewSlotProps } from '../contract/slots.ts' +import type { ModelRetryNode, TurnErrorNode, UserMessageNode } from '../contract/snapshot.ts' import { CompactionItem } from './CompactionItem.tsx' import { ContextInjectionRow } from './ContextInjectionRow.tsx' import { MessageIconActions } from './MessageIconActions.tsx' diff --git a/packages/client/ui-chat/src/client/chat/turn-assistant.ts b/packages/client/ui-chat/src/client/chat/turn-assistant.ts index 36c2ad2ec5..90e075d79a 100644 --- a/packages/client/ui-chat/src/client/chat/turn-assistant.ts +++ b/packages/client/ui-chat/src/client/chat/turn-assistant.ts @@ -1,4 +1,4 @@ -import type { AssistantBlock } from '@deepseek-ai/dsh-client-ui-conversation/client' +import type { AssistantBlock } from '../contract/snapshot.ts' /** * Collect visible prose from one Assistant lifecycle. diff --git a/packages/client/ui-chat/src/client/conversation-nodes/partial.ts b/packages/client/ui-chat/src/client/conversation-nodes/partial.ts index 6d7d4f24dc..ea73fae9f6 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/partial.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/partial.ts @@ -1,5 +1,7 @@ -import type { AssistantBlock, PartialAssistant } from '@deepseek-ai/dsh-client-ui-conversation/client' import type { StreamChunk } from '@deepseek-ai/dsh-llm/types' +import type { + AssistantBlock, PartialAssistant, +} from '@deepseek-ai/dsh-client-ui-conversation/client' import { emptyAssistantBlock, toAssistantBlock } from './event-projection.ts' /** diff --git a/packages/client/ui-chat/src/client/model/tool-call-tree.ts b/packages/client/ui-chat/src/client/model/tool-call-tree.ts index 2620ded03b..8426873941 100644 --- a/packages/client/ui-chat/src/client/model/tool-call-tree.ts +++ b/packages/client/ui-chat/src/client/model/tool-call-tree.ts @@ -1,6 +1,8 @@ -import type { ConversationNode, RunningToolCall, ToolCallBlock, ToolResultNode } from '@deepseek-ai/dsh-client-ui-conversation/client' import type { SessionEvent } from '@deepseek-ai/dsh-session/types' import type {} from '@deepseek-ai/dsh-tools/types' +import type { + ConversationNode, RunningToolCall, ToolCallBlock, ToolResultNode, +} from '@deepseek-ai/dsh-client-ui-conversation/client' interface ProjectedBlock { source: ToolCallBlock From e649981497966affee57a2f12f6cad53d13821a1 Mon Sep 17 00:00:00 2001 From: ZiyaZhang <199893125+ZiyaZhang@users.noreply.github.com> Date: Sun, 20 Sep 2026 20:49:56 -0700 Subject: [PATCH 081/100] fix(web): describe PTC mode by the tasks it suits The PTC card in Settings explained the mechanism (the agent chains tools through code) rather than which tasks to pick it for, so readers could not tell it apart from Standard mode the way the Minimal and Creator cards allow. Reword the Chinese and English card and new-task menu copy to name the tasks: batch tool calls whose results are then filtered, organized, deduplicated, counted, or summarized. Update the four ARIA snapshots that embed this text. --- .../tests/expected/agent-preset-authoring/created.expected.md | 2 +- .../tests/expected/agent-preset-authoring/damaged.expected.md | 2 +- .../tests/expected/agent-preset-authoring/section.expected.md | 2 +- .../tests/expected/agent-preset-selection/menu.expected.md | 2 +- packages/client/ui-agent-preset/src/client/locales.ts | 4 ++-- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/apps/web/tests/expected/agent-preset-authoring/created.expected.md b/apps/web/tests/expected/agent-preset-authoring/created.expected.md index 6a52ce25ac..20455df885 100644 --- a/apps/web/tests/expected/agent-preset-authoring/created.expected.md +++ b/apps/web/tests/expected/agent-preset-authoring/created.expected.md @@ -27,7 +27,7 @@ - 'button "设为新任务默认: PTC 模式"': - text: PTC 模式 内置 - code: ptc - - text: 包含标准模式的所有能力,让 Agent 用代码串联多个工具,完成批量处理、筛选和汇总。你只需描述任务。 + - text: 包含标准模式的所有能力,更适合批量调用工具,并对结果进行筛选、整理、去重、统计或汇总的任务。 - 'button "模式说明: PTC 模式"': 模式说明 - 'button "如何使用: PTC 模式"': 如何使用 - 'button "查看配置: PTC 模式"': 查看配置 diff --git a/apps/web/tests/expected/agent-preset-authoring/damaged.expected.md b/apps/web/tests/expected/agent-preset-authoring/damaged.expected.md index 3a032b92f1..a7434c0336 100644 --- a/apps/web/tests/expected/agent-preset-authoring/damaged.expected.md +++ b/apps/web/tests/expected/agent-preset-authoring/damaged.expected.md @@ -27,7 +27,7 @@ - 'button "设为新任务默认: PTC 模式"': - text: PTC 模式 内置 - code: ptc - - text: 包含标准模式的所有能力,让 Agent 用代码串联多个工具,完成批量处理、筛选和汇总。你只需描述任务。 + - text: 包含标准模式的所有能力,更适合批量调用工具,并对结果进行筛选、整理、去重、统计或汇总的任务。 - 'button "模式说明: PTC 模式"': 模式说明 - 'button "如何使用: PTC 模式"': 如何使用 - 'button "查看配置: PTC 模式"': 查看配置 diff --git a/apps/web/tests/expected/agent-preset-authoring/section.expected.md b/apps/web/tests/expected/agent-preset-authoring/section.expected.md index 20ee272950..44b226efc0 100644 --- a/apps/web/tests/expected/agent-preset-authoring/section.expected.md +++ b/apps/web/tests/expected/agent-preset-authoring/section.expected.md @@ -27,7 +27,7 @@ - 'button "设为新任务默认: PTC 模式"': - text: PTC 模式 内置 - code: ptc - - text: 包含标准模式的所有能力,让 Agent 用代码串联多个工具,完成批量处理、筛选和汇总。你只需描述任务。 + - text: 包含标准模式的所有能力,更适合批量调用工具,并对结果进行筛选、整理、去重、统计或汇总的任务。 - 'button "模式说明: PTC 模式"': 模式说明 - 'button "如何使用: PTC 模式"': 如何使用 - 'button "查看配置: PTC 模式"': 查看配置 diff --git a/apps/web/tests/expected/agent-preset-selection/menu.expected.md b/apps/web/tests/expected/agent-preset-selection/menu.expected.md index a765eb87ac..76b76a3463 100644 --- a/apps/web/tests/expected/agent-preset-selection/menu.expected.md +++ b/apps/web/tests/expected/agent-preset-selection/menu.expected.md @@ -1,6 +1,6 @@ - menu: - menuitem "Standard mode Work with code, files, and information. Suitable for most tasks, with search, editing, terminal commands, and other tools available as needed." - - menuitem "PTC mode Includes all Standard mode capabilities, with the agent connecting tools through code for batch processing, filtering, and summaries. Just describe your task." + - menuitem "PTC mode Includes all Standard mode capabilities. Better suited to tasks that call tools in batches and then filter, organize, deduplicate, count, or summarize the results." - menuitem "Minimal mode The agent works using only a terminal tool. Useful for testing and comparing its basic performance." - menuitem "Creator mode Customize DSH through conversation. Let the agent write plugins that add features or UI, or combine tools and prompts to create your own mode." - menuitem "Refusing mode Resolves, then refuses to start." diff --git a/packages/client/ui-agent-preset/src/client/locales.ts b/packages/client/ui-agent-preset/src/client/locales.ts index 9e5a689f01..4d15827ecc 100644 --- a/packages/client/ui-agent-preset/src/client/locales.ts +++ b/packages/client/ui-agent-preset/src/client/locales.ts @@ -42,7 +42,7 @@ export const en: Record = { 'Work with code, files, and information. Suitable for most tasks, with search, editing, terminal commands, and other tools available as needed.', presetPtcName: 'PTC mode', presetPtcDescription: - 'Includes all Standard mode capabilities, with the agent connecting tools through code for batch processing, filtering, and summaries. Just describe your task.', + 'Includes all Standard mode capabilities. Better suited to tasks that call tools in batches and then filter, organize, deduplicate, count, or summarize the results.', presetMinimalName: 'Minimal mode', presetMinimalDescription: 'The agent works using only a terminal tool. Useful for testing and comparing its basic performance.', @@ -110,7 +110,7 @@ export const zh: Record = { presetStandardName: '标准模式', presetStandardDescription: '处理代码、文件和资料,适合大多数任务。Agent 会按需使用检索、编辑和终端等工具。', presetPtcName: 'PTC 模式', - presetPtcDescription: '包含标准模式的所有能力,让 Agent 用代码串联多个工具,完成批量处理、筛选和汇总。你只需描述任务。', + presetPtcDescription: '包含标准模式的所有能力,更适合批量调用工具,并对结果进行筛选、整理、去重、统计或汇总的任务。', presetMinimalName: '极简模式', presetMinimalDescription: 'Agent 仅使用终端工具完成任务,适合测试和对比其基础表现。', presetCordisName: '创造模式', From e30f0c77747927a092aa87061c849bef74a5c764 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Mon, 21 Sep 2026 11:58:04 +0800 Subject: [PATCH 082/100] test(terminal): check descendant quiescence instead of PID removal --- packages/terminal/terminal-bash/tests/local.spec.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/terminal/terminal-bash/tests/local.spec.ts b/packages/terminal/terminal-bash/tests/local.spec.ts index 7ef28c6929..962421ce9c 100644 --- a/packages/terminal/terminal-bash/tests/local.spec.ts +++ b/packages/terminal/terminal-bash/tests/local.spec.ts @@ -233,9 +233,10 @@ describe.skipIf(process.platform === 'win32')('terminal-bash real shell', () => const child = /CHILD=(\d+)/.exec(output)?.[1] expect(child).toBeDefined() const pid = Number(child) - expect(() => process.kill(pid, 0)).not.toThrow() + expect(processIsRunning(pid)).toBe(true) await ctx.terminals.kill(agent, created.sessionId) - expect(() => process.kill(pid, 0)).toThrow() + // Linux can retain a stopped descendant as a zombie until its parent reaps it. + expect(processIsRunning(pid)).toBe(false) }, 10_000) it('quiesces a disowned same-session descendant after the shell exits naturally', async () => { From 6f07deab31833471e5808ad95a33bbe492d21abd Mon Sep 17 00:00:00 2001 From: creatixchu Date: Mon, 21 Sep 2026 12:33:59 +0800 Subject: [PATCH 083/100] test(llm): preserve coverage timeout budget and drain stalled fixtures --- .../llm/llm-retry/tests/transport-recovery.spec.ts | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/packages/llm/llm-retry/tests/transport-recovery.spec.ts b/packages/llm/llm-retry/tests/transport-recovery.spec.ts index 6322a88f27..d9a7d4d756 100644 --- a/packages/llm/llm-retry/tests/transport-recovery.spec.ts +++ b/packages/llm/llm-retry/tests/transport-recovery.spec.ts @@ -17,9 +17,16 @@ let context: Context | undefined const servers: MockLlmServer[] = [] afterEach(async () => { - await context?.fiber.dispose() + const ownedContext = context context = undefined - await Promise.all(servers.splice(0).map(server => server.close())) + // A failed transport can still await a stalled socket while its context disposes. + const results = await Promise.allSettled([ + ownedContext?.fiber.dispose(), + ...servers.splice(0).map(server => server.close()), + ]) + vi.unstubAllEnvs() + const failure = results.find(result => result.status === 'rejected') + if (failure?.status === 'rejected') throw failure.reason }) async function start( @@ -218,7 +225,7 @@ describe('bounded retry through the real DeepSeek HTTP/SSE adapter', () => { expect(agent.session.snapshotEvents().filter(event => event.type === 'llm/retry').map(event => event.data.failure.code)) .toEqual(['TIMEOUT']) expect(finalAssistantText(agent)).toBe('recovered after timeout') - }, 10_000) + }) it('stops after the configured transport retry budget is exhausted', async () => { const server = await start(['connection_reset', 'connection_reset', 'connection_reset'], { From 6ac2d741a69b92ba83737db3bc6ce7c43f936086 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Mon, 21 Sep 2026 12:36:54 +0800 Subject: [PATCH 084/100] test(llm): retain pending mock listeners through teardown --- packages/llm/llm-retry/tests/transport-recovery.spec.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/llm/llm-retry/tests/transport-recovery.spec.ts b/packages/llm/llm-retry/tests/transport-recovery.spec.ts index d9a7d4d756..8fd91ece9e 100644 --- a/packages/llm/llm-retry/tests/transport-recovery.spec.ts +++ b/packages/llm/llm-retry/tests/transport-recovery.spec.ts @@ -14,7 +14,7 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session' import * as Retry from '../src/index.ts' let context: Context | undefined -const servers: MockLlmServer[] = [] +const servers: Promise[] = [] afterEach(async () => { const ownedContext = context @@ -22,18 +22,18 @@ afterEach(async () => { // A failed transport can still await a stalled socket while its context disposes. const results = await Promise.allSettled([ ownedContext?.fiber.dispose(), - ...servers.splice(0).map(server => server.close()), + ...servers.splice(0).map(async server => (await server).close()), ]) vi.unstubAllEnvs() const failure = results.find(result => result.status === 'rejected') if (failure?.status === 'rejected') throw failure.reason }) -async function start( +function start( sequence: readonly MockLlmBehavior[], options: Omit[0], 'sequence'> = {}, ): Promise { - const server = await startMockLlmServer({ sequence, ...options }) + const server = startMockLlmServer({ sequence, ...options }) servers.push(server) return server } From 3773c4f85bc54334418812fcff08d8da737c1249 Mon Sep 17 00:00:00 2001 From: _Kerman Date: Mon, 21 Sep 2026 12:42:36 +0800 Subject: [PATCH 085/100] docs(agent-loop): correct the owning cancellation note The 2026-07-16 explicit-turn-cancellation note still described a frozen, detached signal reason and a two-variant cause union. The README paragraph added here points readers at that note as the owner of the signal lifecycle, so the stale mechanism was load-bearing. It now records why freezing the caller's cause is not an alternative: undici assigns `stack` from strict-mode code, so a frozen reason makes fetch reject with `TypeError: Cannot add property stack` in place of the abort reason. Also names `turn/end`'s declared `TurnEndCancelCause` in the README and takes the reviewer's helper-doc wording. --- .../2026-07-16-explicit-turn-cancellation.i18n.yaml | 4 ++-- .../architecture/2026-07-16-explicit-turn-cancellation.md | 6 +++--- .../2026-07-16-explicit-turn-cancellation.zh.md | 6 +++--- packages/core/agent-loop/README.i18n.yaml | 4 ++-- packages/core/agent-loop/README.md | 2 +- packages/core/agent-loop/README.zh.md | 2 +- packages/core/agent-loop/src/agent.ts | 8 ++++---- 7 files changed, 16 insertions(+), 16 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml index 16ecfcc400..a3dae54b9b 100644 --- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.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 .agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md -2026-07-16-explicit-turn-cancellation.md: 09631349226837d7f93112fe5e9c517f2fee099c -2026-07-16-explicit-turn-cancellation.zh.md: baf039d49578895d53ffae4c6b88d29b3d1563b6 +2026-07-16-explicit-turn-cancellation.md: d59accf2dc3f894ffab226e5ddc9d2e746f4d93e +2026-07-16-explicit-turn-cancellation.zh.md: 8fb0728eb2bbe8fa01dbefebe7e02aa8c836617a diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md index 0963134922..d59accf2dc 100644 --- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md +++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md @@ -12,7 +12,7 @@ The [initiating Agent scope decision](2026-07-15-agent-initiator-scope.md) inten ## Decision -Agent owns the runtime-only `AgentCancelCause` union `{ kind: 'user' } | { kind: 'parent' }`; `agent.cancel()` defaults to `user`. TypeScript enforces that vocabulary at this typed same-process boundary, with no runtime validator, fallback, or special compatibility contract for untyped callers. An active `TurnCancellation` copies the typed discriminant into a fresh frozen signal reason; idle cancellation has no holder to mutate and does not arm later work. +Agent owns the runtime-only `AgentCancelCause` union `{ kind: 'user' } | { kind: 'parent' } | { kind: 'hook'; reason: string } | { kind: 'disposed' }`, and `agent.cancel()` requires one. TypeScript enforces that vocabulary at this typed same-process boundary, with no runtime validator, fallback, or special compatibility contract for untyped callers. The holder aborts with the caller's own object rather than a detached copy, so a transport reaching that signal can extend it: Node's fetch assigns a `stack` onto the reason it receives. The loop therefore copies the declared fields where the cause becomes durable data. Freezing the cause at `cancel()` is not an alternative — undici performs that assignment from strict-mode code, so a frozen reason makes `fetch` reject with `TypeError: Cannot add property stack` in place of the abort reason. Idle cancellation has no holder to mutate and does not arm later work. 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. Session seed/load rejects legacy aborted records with a reason or any other extra field, so replay cannot reintroduce caller-owned cancellation detail. The process-local `agent/cancel-requested` notification is not durable; a future audit requirement uses a separate durable 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. @@ -22,7 +22,7 @@ The driver keeps only a cause-less pre-run marker for queued work cancelled befo The explicit event signatures pass a single payload object: agent-scoped events carry `agent` and `signal` in the payload with `next` last, and the remaining APIs keep `signal` immediately before a waterfall's final `next`. `PreStepContext` and `RequestFailureContext` are retired, with their fields folded into the `agent/pre-step` and `agent/request-error` payloads ([payload-object events](../../archived/architecture/2026-08-06-agent-event-payload-objects.md)). Pre-step entry, request configuration, request-error recovery, model generation, tool execution, approval, turn stopping, and subagent or workflow requests all receive the current signal. Hook bridges must also supply `RunHookOptions.signal`, so a turn cancellation reaches the bash executor's provider-managed termination and join boundary; the [native-containment decision](2026-08-28-subprocess-native-containment.md) owns the supported local scope, Job, and fallback mechanics. `SystemPrompt.assemble()` carries `signal?: AbortSignal` in `AssembleContext` because that object is an explicit request value that can also represent signal-less assembly outside a turn. Listeners may cooperate with the signal but must not retain it to control another turn. -`ctx.agents` continues to carry only the initiating Agent. Ambient Agent presence does not imply liveness, a current turn, or cancellation authority. The cause reader is private to the loop and states the machine-private slot invariant (only `cancel()` aborts a turn controller, always with a canonical frozen cause) instead of re-validating the reason structurally; no public helper reads a cause off an arbitrary signal. Concurrent Agents isolate both their initiator identities and their turn signals; a child driver shadows the parent initiator while its parent request signal still travels through the subagent seam. +`ctx.agents` continues to carry only the initiating Agent. Ambient Agent presence does not imply liveness, a current turn, or cancellation authority. The cause reader is private to the loop and states the machine-private slot invariant (only `cancel()` aborts a turn controller, always with a typed cause) instead of re-validating the reason structurally; no public helper reads a cause off an arbitrary signal. Concurrent Agents isolate both their initiator identities and their turn signals; a child driver shadows the parent initiator 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. @@ -30,7 +30,7 @@ Cancellation remains cooperative. The loop checks interruption before and after ## Verification -Contract tests verify the typed caller union, frozen detachment, default and first-wins behavior, the coarse Session JSON round trip and legacy-record rejection, ACP `user`, in-process subagent `parent`, and disposal precedence. Loop tests make cooperative listeners wait on the signal at pre-step, system-prompt assembly, request, model stream, request-error recovery, tool execution, and turn stopping; they assert one signal within a turn, a fresh signal across turns, and no cancellation authority during terminal publication or a blocked durability flush. A real hook bridge test cancels and reaps a blocked prompt hook before idle. +Contract tests verify the typed caller union, field copying where the cause becomes durable data, default and first-wins behavior, the coarse Session JSON round trip and legacy-record rejection, ACP `user`, in-process subagent `parent`, and disposal precedence. Loop tests make cooperative listeners wait on the signal at pre-step, system-prompt assembly, request, model stream, request-error recovery, tool execution, and turn stopping; they assert one signal within a turn, a fresh signal across turns, and no cancellation authority during terminal publication or a blocked durability flush. A real hook bridge test cancels and reaps a blocked prompt hook before idle. Initiator-scope tests assert that every hook still observes the exact Agent and no ambient turn signal, concurrent Agents retain independent identities and signals, and a nested child driver shadows only identity. Race tests cover idle cancellation, pre-run cancellation, replacement submission from a `running` listener, repeated cancellation, and cancel-versus-dispose quiescence. diff --git a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md index baf039d495..8fb0728eb2 100644 --- a/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md @@ -12,7 +12,7 @@ Status: implemented ## 决策 -Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user' } | { kind: 'parent' }`;`agent.cancel()` 默认使用 `user`。TypeScript 在这个类型化的同进程边界中强制执行该词汇,不提供运行时校验器、后备行为,也不为无类型调用方提供特殊兼容性约定。活跃的 `TurnCancellation` 会把类型化判别字段复制为一个全新且已冻结的 signal 原因;空闲状态下没有可修改的持有者,也不会让后续工作预先进入取消状态。 +Agent 拥有仅用于运行时的 `AgentCancelCause` 联合类型 `{ kind: 'user' } | { kind: 'parent' } | { kind: 'hook'; reason: string } | { kind: 'disposed' }`,`agent.cancel()` 必须显式传入其一。TypeScript 在这个类型化的同进程边界中强制执行该词汇,不提供运行时校验器、后备行为,也不为无类型调用方提供特殊兼容性约定。持有者中止时携带的是调用方自己的那个对象,而非一份分离的拷贝,因此能接触到该 signal 的传输层可以向其添加属性:Node 的 fetch 会给它收到的 reason 赋一个 `stack`。所以循环在 cause 成为持久数据的那一步拷贝已声明字段。在 `cancel()` 处冻结 cause 并非可选方案——undici 是在严格模式代码中执行该赋值的,被冻结的 reason 会让 `fetch` 以 `TypeError: Cannot add property stack` 取代中止原因而拒绝。空闲状态下没有可修改的持有者,也不会让后续工作预先进入取消状态。 正在运行的轮次被中断后,以粗粒度的持久化结果 `{ kind: 'aborted' }` 结束。终态事件记录轮次发生了什么,运行时 signal 标识谁请求了取消;回放不会重复保存 `user` 或 `parent`。会话 seed/load 会拒绝携带取消原因或任何其他额外字段的旧式中止记录,因此回放无法重新引入由调用方持有的取消细节。仅限进程内的 `agent/cancel-requested` 通知不会持久化;未来若有审计需求,应使用独立的持久化控制请求事件,让请求与最终结果保持为两项事实。持久化事件不包含调用栈、signal、错误对象、自由文本取消原因或后端私有细节。 @@ -22,7 +22,7 @@ AgentLoop 为每个待启动轮次私有地持有一个 `TurnCancellation`。它 显式事件签名传递单个 payload 对象:agent 作用域事件在 payload 中携带 `agent` 和 `signal`,`next` 位于最后;其余 API 保持 `signal` 紧邻 waterfall(瀑布式事件)的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役,其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload([payload-object 事件](../../archived/architecture/2026-08-06-agent-event-payload-objects.md))。进入 pre-step 时、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`,使轮次取消能够到达 Bash 执行器由提供方管理的终止与等待边界;[原生 containment 决策](2026-08-28-subprocess-native-containment.zh.md)负责受支持本地路径上的 scope、Job 与 fallback 机制。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`,因为该对象是显式请求值,也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消,但不得保留它来控制其他轮次。 -`ctx.agents` 仍只携带发起 Agent。环境中的 Agent 并不代表存活、当前轮次或取消权限。cause 读取器是 loop 私有的,它直接陈述机器私有的 slot 不变量(只有 `cancel()` 会中止轮次控制器,且总是携带规范的冻结 cause),而不是对 reason 做结构化再校验;不存在从任意 signal 读取 cause 的公开辅助函数。并发 Agent 会同时隔离各自的发起方身份和轮次 signal;子驱动会遮蔽父发起方,而父请求 signal 仍通过 subagent seam 传递。 +`ctx.agents` 仍只携带发起 Agent。环境中的 Agent 并不代表存活、当前轮次或取消权限。cause 读取器是 loop 私有的,它直接陈述机器私有的 slot 不变量(只有 `cancel()` 会中止轮次控制器,且总是携带类型化的 cause),而不是对 reason 做结构化再校验;不存在从任意 signal 读取 cause 的公开辅助函数。并发 Agent 会同时隔离各自的发起方身份和轮次 signal;子驱动会遮蔽父发起方,而父请求 signal 仍通过 subagent seam 传递。 Agent dispose(资源释放)会在活跃持有者上请求仅用于运行时的 `{ kind: 'disposed' }` 中断。若取消已经先占用控制器的中断原因,该原因便无法改写,因此终态分类会先检查生命周期状态:资源释放结果优先,之后受支持的 `user` 或 `parent` 取消原因形成粗粒度的中止结果,其他异常保留现有错误路径。ACP(Agent Client Protocol)取消映射为 `user`;进程内 spawn 和 fork 的传播映射为 `parent`。远程 ACP subagent 保持现有协议。 @@ -30,7 +30,7 @@ Agent dispose(资源释放)会在活跃持有者上请求仅用于运行时 ## 验证 -约定测试验证类型化调用方联合类型、冻结且与调用方分离、默认行为与首次请求优先行为、粗粒度的会话 JSON 往返与旧式记录拒绝、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。AgentLoop 测试让协作式监听器在 pre-step、系统提示词组装、请求、模型流、请求错误恢复、工具执行和轮次停止处等待 signal;并断言同一轮次使用一个 signal,不同轮次使用全新的 signal,终态发布期间和持久化刷新受阻期间不存在取消权限。真实钩子桥接器测试会在报告空闲状态前取消并回收受阻的提示词钩子。 +约定测试验证类型化调用方联合类型、在 cause 成为持久数据处拷贝字段、默认行为与首次请求优先行为、粗粒度的会话 JSON 往返与旧式记录拒绝、ACP `user`、进程内 subagent `parent` 以及 dispose 优先级。AgentLoop 测试让协作式监听器在 pre-step、系统提示词组装、请求、模型流、请求错误恢复、工具执行和轮次停止处等待 signal;并断言同一轮次使用一个 signal,不同轮次使用全新的 signal,终态发布期间和持久化刷新受阻期间不存在取消权限。真实钩子桥接器测试会在报告空闲状态前取消并回收受阻的提示词钩子。 发起方作用域测试断言所有钩子仍观察到同一个 Agent 且没有环境中的轮次 signal,并发 Agent 保持独立的身份与 signal,嵌套子驱动只遮蔽身份。竞态测试覆盖空闲状态取消、运行前取消、从 `running` 监听器提交替代提示词、重复取消以及取消与 dispose 竞争下的完全停稳。 diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml index 7bd774e9a4..bfbfe913e9 100644 --- a/packages/core/agent-loop/README.i18n.yaml +++ b/packages/core/agent-loop/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/core/agent-loop/README.md -README.md: bfe7944c75f7cab7565f966863f7d7118c61ed97 -README.zh.md: d44f6cd16e728491d97a3e00085f0225d52c5cdf +README.md: f74182e468c8c844be71f762c6f0dd266cf799f3 +README.zh.md: e55d481dc61ae52b7d08ff09ffb0595ce085fd76 diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md index bfe7944c75..f74182e468 100644 --- a/packages/core/agent-loop/README.md +++ b/packages/core/agent-loop/README.md @@ -122,7 +122,7 @@ Prompt admission uses the actual `prepareCall()` result, not the preceding `requ ### Failure and cancellation -Cancellation records a fresh `AgentCancelCause` in `turn/end`, retaining the caller's `kind` and the hook's `reason` text. The live `AbortSignal.reason` remains the caller's object, which a transport may extend — Node's fetch assigns a `stack` onto it — so the copy keeps that trace out of the log and keeps the ending appendable. +`turn/end` declares `TurnEndCancelCause`; cancellation records a fresh `AgentCancelCause` there, retaining the caller's `kind` and the hook's `reason` text. The live `AbortSignal.reason` remains the caller's object, which a transport may extend — Node's fetch assigns a `stack` onto it — so the copy keeps that trace out of the log and keeps the ending appendable. Final adapter selection, dispatch, and iteration failures arrive as terminal finishes and enter `agent/request-error`; a handling listener returns `{ kind: 'retry' }` without calling `next()`, while an unhandled failure is terminal. Middleware, result-processing, tool, and other extension failures remain thrown and close the turn directly — plugin failure ends the turn, not the loop. Undispatched model tool calls after cancellation receive synthetic `tool/call` plus `ABORTED_BEFORE_DISPATCH` result pairs. The [explicit-cancellation decision](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md) owns the signal lifecycle. diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md index d44f6cd16e..e55d481dc6 100644 --- a/packages/core/agent-loop/README.zh.md +++ b/packages/core/agent-loop/README.zh.md @@ -122,7 +122,7 @@ const handle = await ctx.agents.create({ ### 失败与取消 -取消时,循环在 `turn/end` 中记录一份新的 `AgentCancelCause`,保留调用方的 `kind` 和 hook 的 `reason` 文本。实时 `AbortSignal.reason` 仍是调用方的那个对象,传输层可能向其添加属性——Node 的 fetch 会给它赋一个 `stack`——因此这份拷贝既让该调用栈不进入日志,也让结束事件保持可追加。 +`turn/end` 声明的类型是 `TurnEndCancelCause`;取消时,循环在其中记录一份新的 `AgentCancelCause`,保留调用方的 `kind` 和 hook 的 `reason` 文本。实时 `AbortSignal.reason` 仍是调用方的那个对象,传输层可能向其添加属性——Node 的 fetch 会给它赋一个 `stack`——因此这份拷贝既让该调用栈不进入日志,也让结束事件保持可追加。 最终适配器选择、分发与迭代失败以终止结束的形式到达并进入 `agent/request-error`;处理该失败的监听器返回 `{ kind: 'retry' }` 且不调用 `next()`,未被处理的失败则是终态。Middleware、结果处理、工具及其他扩展失败仍会抛出并直接关闭轮次——插件失败结束的是轮次,不是循环。取消后未分发的模型工具调用会收到合成的 `tool/call` 加 `ABORTED_BEFORE_DISPATCH` 结果对。[显式取消决策](../../../.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md)拥有信号生命周期。 diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index ce7bbe8ab8..98114f53cd 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -69,10 +69,10 @@ function requestProposal(header: EpochHeader): LlmCallConfig { } /** - * Read the cause {@link ReactLoopAgent.cancel} aborted a loop-owned signal - * with, copying the fields `turn/end` records. The live reason stays the - * caller's object, and Node's fetch assigns a `stack` onto it that - * `Session.append` would either log or reject as data JSON cannot hold. + * Read the cause `cancel()` passed when aborting a loop-owned signal, copying + * only the fields `turn/end` records. The live reason stays the caller's + * object, and Node's fetch assigns a `stack` onto it that `Session.append` + * would either log or reject as data JSON cannot hold. * @param signal - a turn or maintenance signal this loop owns. * @returns the copied cause, or undefined while the signal is still live. */ From 7520fe94e1444b8c0a37038b074fbb937a881620 Mon Sep 17 00:00:00 2001 From: Turtle Date: Mon, 21 Sep 2026 12:43:38 +0800 Subject: [PATCH 086/100] =?UTF-8?q?refactor(preset):=20=E7=B2=BE=E7=AE=80?= =?UTF-8?q?=E5=88=9B=E9=80=A0=E6=A8=A1=E5=BC=8F=E7=9A=84=20system=20prompt?= =?UTF-8?q?=20(#4745)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * refactor(preset): trim the creation-mode system prompt The `cordis` preset persona repeated what the plugin_manager and cordis_inspect_* tool descriptions and the two shipped skills already carry. Keep only identity, the shipped-preset constraint, the visual request routing rule, and which skill to load for what. Drop the tool-cordis prompt section, which restated its own tool descriptions, and the cordis_inspect_query navigation hints that the provider manifests returned by cordis_inspect_list already state. Shorten both skill descriptions so the first-turn catalog stays small. First-turn request for the cordis preset, measured through the DeepSeek API with deepseek-v4-flash: 9572 -> 8975 prompt tokens. * docs: regenerate config catalog after section order removal * docs: regenerate module graph after tool-cordis dependency removal * refactor(preset): give the cordis preset the standard persona Creation mode's system prompt now equals standard mode's; the skill catalog and the shipped skills carry every routing and off-limits rule. The plugin skill description states the visual-request destination. First-turn request for the cordis preset: 9572 -> 8815 prompt tokens. * fix(review): document current tool-cordis state and pin the shared persona The tool-cordis README pair now states that only the two tool schemas enter requests, that disposal removes tools and providers, and that the first-turn skill catalog carries the routing. The Web skill row test resolves the owner's selected fixture generation instead of a fixed v3 path. The preset e2e asserts the cordis persona sections equal standard's. --- apps/cli/tests/web-agent-presets.e2e.ts | 17 +++++++++++ apps/web/tests/skill-tool-row.e2e.ts | 7 +++-- docs/config-catalog.i18n.yaml | 4 +-- docs/config-catalog.md | 4 +-- docs/config-catalog.zh.md | 2 +- docs/module-graph.i18n.yaml | 4 +-- docs/module-graph.md | 3 +- docs/module-graph.zh.md | 3 +- docs/tool-catalog.i18n.yaml | 4 +-- docs/tool-catalog.md | 2 +- docs/tool-catalog.zh.md | 2 +- packages/core/system-prompt/src/index.ts | 1 - .../system-prompt/tests/system-prompt.spec.ts | 2 +- .../extensions/tool-cordis/README.i18n.yaml | 4 +-- packages/extensions/tool-cordis/README.md | 8 ++--- packages/extensions/tool-cordis/README.zh.md | 8 ++--- packages/extensions/tool-cordis/package.json | 2 -- packages/extensions/tool-cordis/src/index.ts | 14 +++------ packages/extensions/tool-cordis/src/prompt.ts | 4 --- .../presets/cordis/agent.cordis.yml | 30 +++++-------------- .../skills/cordis-plugin-development/SKILL.md | 8 ++--- .../editing-cordis-compositions/SKILL.md | 2 +- pnpm-lock.yaml | 3 -- .../system-prompt.expected.md | 6 +--- .../tool-schemas.expected.json | 2 +- snapshots/session/skill-load/session.v4.jsonl | 23 ++++++++++++++ .../tool-schemas.expected.json | 2 +- snapshots/web/skill-tool-row/snapshot.yml | 2 +- 28 files changed, 88 insertions(+), 85 deletions(-) delete mode 100644 packages/extensions/tool-cordis/src/prompt.ts create mode 100644 snapshots/session/skill-load/session.v4.jsonl diff --git a/apps/cli/tests/web-agent-presets.e2e.ts b/apps/cli/tests/web-agent-presets.e2e.ts index 692cad3ebd..1122a1c36e 100644 --- a/apps/cli/tests/web-agent-presets.e2e.ts +++ b/apps/cli/tests/web-agent-presets.e2e.ts @@ -369,6 +369,23 @@ describe('the shipped Web composition', () => { expect(tools).not.toContain('str_replace_editor') expect(ctx.commands.find(handle.agent, 'goal')).toBeDefined() + // The persona is `standard`'s, pinned verbatim so the two composition + // files cannot drift apart: tool descriptions and the skill catalog + // carry every creation-mode instruction. + const standard = await ctx.agents.create({ + sessionId: SessionId('preset-cordis-standard-persona'), + setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined), + }) + try { + const persona = async (agent: Agent) => (await ctx.systemPrompt.assemble({ scope: agent })).sections + .filter(section => section.name.startsWith('deployment:persona-')) + const cordisPersona = await persona(handle.agent) + expect(cordisPersona.map(section => section.name)).toEqual(['deployment:persona-prefix', 'deployment:persona-suffix']) + expect(cordisPersona).toEqual(await persona(standard.agent)) + } finally { + await standard.dispose() + } + // The preset's own authoring skill registers into ITS layer of the host // registry: the cordis agent's view carries it, the global view does not. const scoped = (await ctx.skills.list({ scope: handle.agent })).map(skill => skill.name) diff --git a/apps/web/tests/skill-tool-row.e2e.ts b/apps/web/tests/skill-tool-row.e2e.ts index 628803ad48..1b6a9e7f10 100644 --- a/apps/web/tests/skill-tool-row.e2e.ts +++ b/apps/web/tests/skill-tool-row.e2e.ts @@ -8,11 +8,12 @@ import { chromium } from 'playwright' import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' import { assertFixtureInventory, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts, - launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold, + launchWebScaffold, seedSession, selectedSessionFixture, watchConsole, webSnapshotMode, type WebScaffold, } from './scaffold.ts' import { expandOwningTurnProcess, newEnglishPage, saveFailureShot } from './support.ts' -const FIXTURE = fileURLToPath(new URL('../../../snapshots/session/skill-load/session.v3.jsonl', import.meta.url)) +// Any generation path names the role; the owner's highest committed generation replays. +const FIXTURE = fileURLToPath(new URL('../../../snapshots/session/skill-load/session.v4.jsonl', import.meta.url)) const SNAPSHOT_DIR = fileURLToPath(new URL('../../../snapshots/web/skill-tool-row', import.meta.url)) const UI_EXPECTED = fileURLToPath(new URL('../../../snapshots/web/skill-tool-row/ui.expected.md', import.meta.url)) const MODE = webSnapshotMode() @@ -26,7 +27,7 @@ describe.skipIf(MODE === 'record')('web e2e: dedicated Skill tool row', () => { let tripwire: ReturnType beforeAll(async () => { - const fixture = await readFile(FIXTURE, 'utf8') + const fixture = await readFile(await selectedSessionFixture(FIXTURE), 'utf8') expect(fixtureUserPrompts(fixture)).toEqual([PROMPT]) scaffold = await launchWebScaffold({}) await seedSession(scaffold, fixture, SEED_ID) diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index 49f9303865..2aa6cd3874 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.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 docs/config-catalog.md -config-catalog.md: 31b4df25d762c25deb1d591e8a44f51a0993f1c2 -config-catalog.zh.md: ce3bf45a781092665652ec0298a57ca5b760add9 +config-catalog.md: bb95bd3794b0be4fd7688f77c2ac77efd4249ecf +config-catalog.zh.md: b1297bf254db369d063a39395d1678f91f807550 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 31b4df25d7..bb95bd3794 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -2966,7 +2966,7 @@ export interface Config { } ``` -Source: [`packages/core/system-prompt/src/index.ts:248`](../packages/core/system-prompt/src/index.ts) +Source: [`packages/core/system-prompt/src/index.ts:247`](../packages/core/system-prompt/src/index.ts) @@ -3931,7 +3931,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co - `@deepseek-ai/dsh-terminal` ([`packages/terminal/terminal/src/index.ts`](../packages/terminal/terminal/src/index.ts)) - `@deepseek-ai/dsh-tool-ask-user` — requires `tools` · `userQuestions` ([`packages/interaction/tool-ask-user/src/index.ts`](../packages/interaction/tool-ask-user/src/index.ts)) - `@deepseek-ai/dsh-tool-call-timeout-policy` — requires `tools` ([`packages/guard/timeout-policy/src/index.ts`](../packages/guard/timeout-policy/src/index.ts)) -- `@deepseek-ai/dsh-tool-cordis` — requires `tools` · `systemPrompt` · `cordisInspect` ([`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/tool-cordis/src/index.ts)) +- `@deepseek-ai/dsh-tool-cordis` — requires `tools` · `cordisInspect` ([`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/tool-cordis/src/index.ts)) - `@deepseek-ai/dsh-tool-subagent-control` — requires `tools` · `subagents` ([`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)) - `@deepseek-ai/dsh-user-questions` ([`packages/interaction/user-questions/src/index.ts`](../packages/interaction/user-questions/src/index.ts)) - `@deepseek-ai/dsh-webhook` — requires `agents` · `agentDefaultModel` · `agentPresets` · `permissionPresets` · `sessionTitle` · `workspaceRegistry` ([`packages/webhook/webhook/src/index.ts`](../packages/webhook/webhook/src/index.ts)) diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index ce3bf45a78..b1297bf254 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -2970,7 +2970,7 @@ export interface Config { } ``` -来源:[`packages/core/system-prompt/src/index.ts:248`](../packages/core/system-prompt/src/index.ts) +来源:[`packages/core/system-prompt/src/index.ts:247`](../packages/core/system-prompt/src/index.ts) diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml index f90ee530e1..e22d460cd0 100644 --- a/docs/module-graph.i18n.yaml +++ b/docs/module-graph.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 docs/module-graph.md -module-graph.md: e0f1fa5f504b04a2ee4e33e2d8fa4013f70cd7a1 -module-graph.zh.md: f4ad086634178aaa79371a6adc6b9e14d2c89e64 +module-graph.md: af297ec0b0d143ad8917eac00e2faf44f3477b5d +module-graph.zh.md: f56bdc422d9e74d922cb015c9d35e020cbd69b89 diff --git a/docs/module-graph.md b/docs/module-graph.md index e0f1fa5f50..af297ec0b0 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -994,7 +994,6 @@ flowchart TD pkg_experimental_auto_review --> pkg_tools pkg_tool_cordis --> pkg_agent pkg_tool_cordis --> pkg_cordis_host_runner - pkg_tool_cordis --> pkg_system_prompt pkg_tool_cordis --> pkg_tools pkg_host_plugin_inventory --> pkg_agent_presets pkg_host_plugin_inventory --> pkg_brand @@ -1557,7 +1556,7 @@ flowchart TD | [`api-settings-controller`](../packages/api/settings-controller) | `api` | [`agent-presets`](../packages/preset/agent-presets), [`credentials`](../packages/credentials/credentials), [`native-command`](../packages/util/native-command), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`typert-protocol`](../packages/typert/protocol) | | [`web-app`](../packages/bundle/web-app) | `bundle` | [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt) | | [`experimental-auto-review`](../packages/experimental/auto-review) | `experimental` | [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | -| [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | +| [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`tools`](../packages/core/tools) | | [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`typert-protocol`](../packages/typert/protocol) | | [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`mcp-resources`](../packages/mcp/mcp-resources), [`scope`](../packages/core/scope), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index f4ad086634..f56bdc422d 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -996,7 +996,6 @@ flowchart TD pkg_experimental_auto_review --> pkg_tools pkg_tool_cordis --> pkg_agent pkg_tool_cordis --> pkg_cordis_host_runner - pkg_tool_cordis --> pkg_system_prompt pkg_tool_cordis --> pkg_tools pkg_host_plugin_inventory --> pkg_agent_presets pkg_host_plugin_inventory --> pkg_brand @@ -1559,7 +1558,7 @@ flowchart TD | [`api-settings-controller`](../packages/api/settings-controller) | `api` | [`agent-presets`](../packages/preset/agent-presets), [`credentials`](../packages/credentials/credentials), [`native-command`](../packages/util/native-command), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`typert-protocol`](../packages/typert/protocol) | | [`web-app`](../packages/bundle/web-app) | `bundle` | [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt) | | [`experimental-auto-review`](../packages/experimental/auto-review) | `experimental` | [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | -| [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | +| [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`tools`](../packages/core/tools) | | [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`typert-protocol`](../packages/typert/protocol) | | [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`mcp-resources`](../packages/mcp/mcp-resources), [`scope`](../packages/core/scope), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`command-feedback`](../packages/feedback/command-feedback), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) | diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml index 54934936dc..8cdff8b24e 100644 --- a/docs/tool-catalog.i18n.yaml +++ b/docs/tool-catalog.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 docs/tool-catalog.md -tool-catalog.md: a4441a1b6bdbd0c2f7cedf506244a8a4a2a1ca97 -tool-catalog.zh.md: 0a82afad88f5362ca997f2e563f1b53c4bf633e8 +tool-catalog.md: c60d3979e65f3c5a2bc363fd082a3f63a446e8b5 +tool-catalog.zh.md: dc061b51681cc73f9d10059276bcdfa5b3268cff diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index a4441a1b6b..c60d3979e6 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -732,7 +732,7 @@ Source: [`packages/extensions/tool-cordis/src/index.ts`](../packages/extensions/ ### `cordis_inspect_query` -Run a read-only query explicitly declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before writing plugin code to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime. For Service.listService and Event.listEvents, query without input to navigate the compact signature directory, then query the exact service or event for its structured contract and referenced types. For Slots.listSubTree, query without root to navigate the compact tree, then query an exact Slot root for its complete registration contract and props; an exact Factory root returns its identity, scope, and registrant. +Run a read-only query declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before writing plugin code to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime. ```json { diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md index 0a82afad88..dc061b5168 100644 --- a/docs/tool-catalog.zh.md +++ b/docs/tool-catalog.zh.md @@ -736,7 +736,7 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费 ### `cordis_inspect_query` -执行 Inspect Provider 明确声明的只读查询。platform、provider 和 method 必须来自 cordis_inspect_list,input 必须符合该方法的 schema。编写插件代码前,用本工具读取准确的 Service 方法、Event 模式、Builtin 签名、Tool schema、主题 token,或实时 Slot 树与 props。Host 查询在本地运行。Client 查询等待页面首个有效响应,直到页面回应或工具取消。本工具不能调用业务 Service 方法或修改运行时。对于 Service.listService 和 Event.listEvents,不传 input 可浏览精简签名目录,再查询准确服务或事件以获得完整约定及引用类型。对于 Slots.listSubTree,不传 root 可浏览精简树;查询准确的 Slot root 可获得完整注册约定和 props,而查询准确的 Factory root 只返回 identity、scope 与 registrant。 +执行 Inspect Provider 声明的只读查询。platform、provider 和 method 必须来自 cordis_inspect_list,input 必须符合该方法的 schema。编写插件代码前,用本工具读取准确的 Service 方法、Event 模式、Builtin 签名、Tool schema、主题 token,或实时 Slot 树与 props。Host 查询在本地运行。Client 查询等待页面首个有效响应,直到页面回应或工具取消。本工具不能调用业务 Service 方法或修改运行时。 ```json { diff --git a/packages/core/system-prompt/src/index.ts b/packages/core/system-prompt/src/index.ts index 0a5d7555f0..6935ed1d06 100644 --- a/packages/core/system-prompt/src/index.ts +++ b/packages/core/system-prompt/src/index.ts @@ -143,7 +143,6 @@ const SECTION_ORDERS = { TOOL_LSP: 2200, TOOL_SESSION_QUERY: 2300, TOOL_GOAL: 2400, - TOOL_CORDIS: 2500, TOOL_WORKFLOW: 2600, TOOL_RALPH: 2700, TOOL_SUBAGENT: 2800, diff --git a/packages/core/system-prompt/tests/system-prompt.spec.ts b/packages/core/system-prompt/tests/system-prompt.spec.ts index 1d73203062..16a79c807f 100644 --- a/packages/core/system-prompt/tests/system-prompt.spec.ts +++ b/packages/core/system-prompt/tests/system-prompt.spec.ts @@ -18,7 +18,7 @@ const SECTION_ORDER_NAMES = [ 'PLAN_POLICY', 'TEAM_POLICY', 'PTC_ONLY', 'FILE_REFERENCE', 'TOOL_BASH', 'TOOL_PWSH', 'TOOL_READ', 'TOOL_WRITE', 'TOOL_EDIT', 'TOOL_GLOB', 'TOOL_GREP', 'TOOL_JOBS', 'TOOL_PTY', 'TOOL_WEB_SEARCH', 'TOOL_WEB_FETCH', - 'TOOL_LSP', 'TOOL_SESSION_QUERY', 'TOOL_GOAL', 'TOOL_CORDIS', 'TOOL_WORKFLOW', + 'TOOL_LSP', 'TOOL_SESSION_QUERY', 'TOOL_GOAL', 'TOOL_WORKFLOW', 'TOOL_RALPH', 'TOOL_SUBAGENT', 'TOOL_REPORT', 'TOOLS_SDK', 'DELIVERABLE_FILE_REFERENCES', 'STRUCTURED_OUTPUT', 'HARNESS_SOURCE', 'WEB_SURFACE', 'DEPLOYMENT_PERSONA_SUFFIX', diff --git a/packages/extensions/tool-cordis/README.i18n.yaml b/packages/extensions/tool-cordis/README.i18n.yaml index d9eef3eede..c149c628cd 100644 --- a/packages/extensions/tool-cordis/README.i18n.yaml +++ b/packages/extensions/tool-cordis/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/extensions/tool-cordis/README.md -README.md: a0152cf3dbdd08599ba431113123c6aaf097723d -README.zh.md: cde328fce54b4c18f57b7a044e6afc24215417dd +README.md: 3536ae2fc39f7a8db425da89df3f4d93e1ca8b4f +README.zh.md: 8127683111f1807b6920d6bb6f56479e1495f281 diff --git a/packages/extensions/tool-cordis/README.md b/packages/extensions/tool-cordis/README.md index a0152cf3db..3536ae2fc3 100644 --- a/packages/extensions/tool-cordis/README.md +++ b/packages/extensions/tool-cordis/README.md @@ -35,7 +35,7 @@ Creator mode includes this toolset. Other compositions mount `@deepseek-ai/dsh-t
    Implementation internals — click to expand -Host providers combine generated Service/Event catalogs and the requesting agent's tool registry. Client providers synchronize their manifests through the existing inspection registry and answer queries from a connected page. The tool plugin owns its registrations through Cordis effects; disposal removes both tools and prompt contributions. No invariant companion is published because inspection reads its providers directly and maintains no independent runtime projection. +Host providers combine generated Service/Event catalogs and the requesting agent's tool registry. Client providers synchronize their manifests through the existing inspection registry and answer queries from a connected page. The tool plugin owns its registrations through Cordis effects; disposal removes the two tools and the Host inspect providers. No invariant companion is published because inspection reads its providers directly and maintains no independent runtime projection.
    @@ -54,15 +54,15 @@ Host providers combine generated Service/Event catalogs and the requesting agent #### What the model sees -The [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-cordis) describes two read-only inspection tools. The [prompt](src/prompt.ts) directs persistent changes through Plugin Manager and describes MCP setup. Creator visual requests default to an installed UI plugin displayed in the current Web page; the development skill covers Client packaging and slot registration. Query results contain the requested API declarations or live tool schemas. +The [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-cordis) describes two read-only inspection tools. The plugin contributes no system prompt section: the tool descriptions state when to call each tool and that queries never invoke business methods. In the `cordis` preset, the first-turn skill catalog carries the descriptions of the two shipped skills, which route plugin, MCP, composition, and destination-less visual requests to the skill covering Plugin Manager, MCP setup, Client packaging, and slot registration. Query results contain the requested API declarations or live tool schemas. #### Token effect -Both tool schemas and the guidance section enter model requests while this plugin is visible. Query results append to the transcript; exact queries avoid loading unrelated declarations. +Only the two tool schemas enter model requests while this plugin is visible. Query results append to the transcript; exact queries avoid loading unrelated declarations. #### KV Cache effect -Unchanged schemas and guidance remain prefix-stable. Query results append to history; enabling other plugins can change subsequent tool schemas. +Unchanged tool schemas remain prefix-stable. Query results append to history; enabling other plugins can change subsequent tool schemas. ## Known Limitations and Deferred Work diff --git a/packages/extensions/tool-cordis/README.zh.md b/packages/extensions/tool-cordis/README.zh.md index cde328fce5..8127683111 100644 --- a/packages/extensions/tool-cordis/README.zh.md +++ b/packages/extensions/tool-cordis/README.zh.md @@ -35,7 +35,7 @@ kind: "package-reference"
    实现细节 — 点击展开 -Host provider 结合生成的 Service/Event 目录与请求 agent 的工具注册表。Client provider 通过现有检查注册表同步清单,并从已连接页面回答查询。工具插件通过 Cordis effect 持有注册;释放时移除工具和提示词贡献。检查直接读取 provider,不维护独立运行时投影,因此不发布不变式配套插件。 +Host provider 结合生成的 Service/Event 目录与请求 agent 的工具注册表。Client provider 通过现有检查注册表同步清单,并从已连接页面回答查询。工具插件通过 Cordis effect 持有注册;释放时移除两个工具和 Host inspect provider。检查直接读取 provider,不维护独立运行时投影,因此不发布不变式配套插件。
    @@ -54,15 +54,15 @@ Host provider 结合生成的 Service/Event 目录与请求 agent 的工具注 #### 模型所见 -[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-cordis) 描述两个只读检查工具。[提示词](src/prompt.ts) 指引模型通过 Plugin Manager 进行持久化变更并说明 MCP 设置方式。创造模式的视觉请求默认通过已安装的 UI 插件显示在当前 Web 页面;开发技能说明 Client 打包和 slot 注册方法。查询结果包含所请求的 API 声明或当前工具 schema。 +[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-cordis) 描述两个只读检查工具。插件不贡献 system prompt 段落:工具描述已说明何时调用每个工具以及查询不会调用业务方法。在 `cordis` preset 中,首轮 skill catalog 携带两个随附技能的描述,把插件、MCP、组合编辑和未指定去向的视觉请求路由到覆盖 Plugin Manager、MCP 设置、Client 打包和 slot 注册的技能。查询结果包含所请求的 API 声明或当前工具 schema。 #### Token 影响 -插件可见时,两个工具 schema 和指导段落进入模型请求。查询结果追加到转录中;精确查询避免加载无关声明。 +插件可见时,只有两个工具 schema 进入模型请求。查询结果追加到转录中;精确查询避免加载无关声明。 #### KV Cache 影响 -未改变的 schema 和指导保持前缀稳定。查询结果追加到历史中;启用其他插件可能改变后续工具 schema。 +未改变的工具 schema 保持前缀稳定。查询结果追加到历史中;启用其他插件可能改变后续工具 schema。 ## 已知限制与待办 diff --git a/packages/extensions/tool-cordis/package.json b/packages/extensions/tool-cordis/package.json index 8e9d109d8b..883eac2792 100644 --- a/packages/extensions/tool-cordis/package.json +++ b/packages/extensions/tool-cordis/package.json @@ -29,7 +29,6 @@ "peerDependencies": { "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-cordis-host-runner": "workspace:^", - "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, @@ -37,7 +36,6 @@ "@deepseek-ai/cordis-plugin-loader": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-cordis-host-runner": "workspace:^", - "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", "@deepseek-ai/cordis": "workspace:^" } diff --git a/packages/extensions/tool-cordis/src/index.ts b/packages/extensions/tool-cordis/src/index.ts index 90f3401d75..4bbf72fe83 100644 --- a/packages/extensions/tool-cordis/src/index.ts +++ b/packages/extensions/tool-cordis/src/index.ts @@ -5,11 +5,10 @@ import type { JsonValue } from '@deepseek-ai/dsh-util-values' import { defineTool } from '@deepseek-ai/dsh-tools' import type { ToolExecution } from '@deepseek-ai/dsh-tools' import { presentInspectListCall, presentInspectQueryCall } from './present.ts' -import { CORDIS_SYSTEM_PROMPT } from './prompt.ts' import { hostInspectProviders } from './providers.ts' export const name = 'tool-cordis' -export const inject = ['tools', 'systemPrompt', 'cordisInspect'] +export const inject = ['tools', 'cordisInspect'] function requireAgent(exec: ToolExecution): Agent { if (exec.agent === undefined) throw new Error('Cordis inspection requires an Agent-backed session') @@ -20,7 +19,6 @@ function requireAgent(exec: ToolExecution): Agent { * @param ctx Agent-scoped registration context. */ export function apply(ctx: Context): void { - ctx.systemPrompt.section({ name: 'tool:cordis', order: ctx.systemPrompt.getSectionOrder('TOOL_CORDIS'), text: CORDIS_SYSTEM_PROMPT }) for (const provider of hostInspectProviders(ctx)) { ctx.effect(() => ctx.cordisInspect.register(provider), `tool-cordis: inspect ${provider.manifest.id}`) } @@ -46,16 +44,12 @@ export function apply(ctx: Context): void { ctx.tools.register(defineTool({ name: 'cordis_inspect_query', description: - 'Run a read-only query explicitly declared by an Inspect Provider. platform, provider, and method must come ' - + 'from cordis_inspect_list, and input must satisfy that method\'s schema. Use this Tool before writing plugin code ' + 'Run a read-only query declared by an Inspect Provider. platform, provider, and method must come from ' + + 'cordis_inspect_list, and input must satisfy that method\'s schema. Use this Tool before writing plugin code ' + 'to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot ' + 'trees and props. Host queries run locally. A Client query waits for the first valid page response and ' + 'remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service ' - + 'methods or modify the runtime. For Service.listService and Event.listEvents, query without input to navigate ' - + 'the compact signature directory, then query the exact service or event for its structured contract and ' - + 'referenced types. For Slots.listSubTree, query without root to navigate the compact tree, then query an ' - + 'exact Slot root for its complete registration contract and props; an exact Factory root returns its identity, ' - + 'scope, and registrant.', + + 'methods or modify the runtime.', parameters: { platform: { type: 'string', required: true, enum: ['host', 'client'], description: 'Runtime platform that owns the Provider.' }, provider: { type: 'string', required: true, description: 'Exact Provider ID returned by cordis_inspect_list.' }, diff --git a/packages/extensions/tool-cordis/src/prompt.ts b/packages/extensions/tool-cordis/src/prompt.ts deleted file mode 100644 index 6f0dd7eafb..0000000000 --- a/packages/extensions/tool-cordis/src/prompt.ts +++ /dev/null @@ -1,4 +0,0 @@ -/** Model guidance for read-only runtime API discovery. */ -export const CORDIS_SYSTEM_PROMPT = `# Harness runtime inspection - -Use cordis_inspect_list to discover Host and Client providers, then cordis_inspect_query to read exact Service, Event, Tool, Theme or Slot APIs. These tools are read-only; queries do not invoke business methods.` diff --git a/packages/preset/agent-presets/presets/cordis/agent.cordis.yml b/packages/preset/agent-presets/presets/cordis/agent.cordis.yml index 9df711310c..5cb8b059f5 100644 --- a/packages/preset/agent-presets/presets/cordis/agent.cordis.yml +++ b/packages/preset/agent-presets/presets/cordis/agent.cordis.yml @@ -5,37 +5,21 @@ # # It exists so a person can ask an agent to author another agent. Everything in # `standard` is here unchanged; Creator adds persistent plugin management, -# runtime inspection, composition-authoring skills, and a persona that explains -# where profile and preset changes belong. +# runtime inspection, and composition-authoring skills. The persona is the +# `standard` one: tool descriptions and the skill catalog carry the operating +# detail, and the skills own the off-limits rule (an upgrade overwrites the +# shipped preset install, and corrupting the `cordis` preset disables this mode). # # Profile management persists configuration shared by every session in that profile. -# The preset's own persona, shadowing the deployment default for this agent. +# Same persona as `standard`, shadowing the deployment default for this agent. # `{{model}}` and `{{cwd}}` resolve from the agent's own route and workspace. - id: persona name: '@deepseek-ai/dsh-persona' config: suffix: Your working directory is {{cwd}}. - prefix: |- - You are a coding agent powered by the {{model}} model, running on the DeepSeek Harness. - - You can read and modify the harness you run on. Its composition is Cordis: every capability is a plugin row in a `cordis.yml`, and an agent preset is one such file mounted for a single session. - - Two planes decide where an edit belongs. The HOST composition holds the registries and anything shared across sessions — persistence, the sandbox and approval stack, the model route, the subagent registry and its backends. An AGENT PRESET holds what one session contributes to those registries: its tools, its persona, its prompt sections. A row that publishes a service belongs in the host composition, or inside an `isolate` realm if the preset genuinely owns that service and nothing outside one agent reads it. - - Presets you author live one directory per preset under `${DSH_HOME:-$HOME/.dsh}/.agent-presets//`. Load `editing-cordis-compositions` for file discovery and copying instructions. NEVER edit or delete the shipped preset install (the `agent-presets` directory beside the deployment's own config): it belongs to the deployment, an upgrade overwrites it, and corrupting the `cordis` preset would disable this very mode. To change what a shipped preset does, copy its composition into a new preset directory and edit the copy. - - Load the `editing-cordis-compositions` skill before writing or changing a composition. - - Use plugin_manager for persistent bundle installation, removal and enablement in the current profile. Author plugin code and configuration as ordinary workspace bundle files. Changes affect every session in that profile. Read saved-state and activation outcomes separately; restart-required means the new capability is not available yet. - - In Creator mode, requests to make a visual object, decoration, or widget mean creating an installed UI plugin that displays it in this Harness Web UI, unless the user specifies another destination. Choose reasonable visual details and proceed. Load cordis-plugin-development, inspect the Client slots, build the plugin in the workspace, and install it with plugin_manager. Install a minimal working version before visual refinement; use the connected page as its preview. Verify that the open page renders it; a standalone image or HTML file does not complete an in-app creation request. - - Load the cordis-plugin-development skill before authoring an installed plugin. Use cordis_inspect_list to discover Host and Client providers, then cordis_inspect_query to read exact Service, Event, Tool, Theme or Slot APIs. These tools are read-only; queries do not invoke business methods. - - To connect an MCP server, create a configuration-only bundle whose patch inserts @deepseek-ai/dsh-mcp-client, then install it with plugin_manager. Load cordis-plugin-development for the package and YAML examples. After successful activation, call one of the newly available mcp____ tools to verify the connection. - - Use installed bundles for new plugin code. Package installation may require explicit user approval for build scripts. Preserve returned failures and pending states; only report success after observing the requested capability. + prefix: >- + You are a coding agent powered by the {{model}} model. - id: agent-instructions name: '@deepseek-ai/dsh-agent-instructions' diff --git a/packages/preset/agent-presets/presets/cordis/skills/cordis-plugin-development/SKILL.md b/packages/preset/agent-presets/presets/cordis/skills/cordis-plugin-development/SKILL.md index 84a48f2a75..67aadc1cd7 100644 --- a/packages/preset/agent-presets/presets/cordis/skills/cordis-plugin-development/SKILL.md +++ b/packages/preset/agent-presets/presets/cordis/skills/cordis-plugin-development/SKILL.md @@ -1,6 +1,6 @@ --- name: cordis-plugin-development -description: Use when authoring, installing, configuring, or debugging persistent plugins and MCP connections in the current Harness profile. +description: Use when authoring, installing, configuring, or debugging persistent plugins and MCP connections in the current Harness profile, and for any visual object, decoration, or widget request that names no other destination, which means an installed UI plugin rendered in the Harness Web UI. --- # Persistent Harness plugins @@ -9,7 +9,7 @@ Use ordinary workspace files to author a bundle, then `plugin_manager install_bu ## Deliver a working plugin first -1. Resolve the requested result and destination. In Creator mode, an unspecified visual destination is the current Harness Web UI. Choose reasonable visual details and implement a small first version. +1. Resolve the requested result and destination. An unspecified visual destination is the current Harness Web UI; a standalone image or HTML file does not complete such a request. Choose reasonable visual details and implement a small first version; install it before visual refinement. 2. Discover only the APIs needed for that version: `cordis_inspect_list`, then targeted `cordis_inspect_query` calls. For UI, query Client `Slots.listSubTree` and the selected slot's registration options and props. Treat the recipes below and returned API declarations as the supported implementation path. Once the chosen slot and registration API are known, write the plugin. Before the first installation, resolve missing declarations through inspection; do not re-check these recipes by reading Loader, manifest-parser, package-manager, React, or slot implementation source. Source-level diagnosis starts from a concrete installation or runtime failure. 3. The first files you write are the installable package, patch, and required Host/Client files in one workspace directory. Check JavaScript syntax and the manifest, then install it. Before that first installation, do not create preview HTML, mock shells, design variants, screenshot scripts, or rasterizer tooling. Use the installed plugin itself as the first preview. 4. Read the installation result. After `application: applied`, exercise the capability or inspect the live Client registration. Use the connected page for visual verification when browser control is available. State any verification limitation explicitly; installation and slot registration alone do not establish what the user can see. @@ -47,7 +47,7 @@ For a simple drawing, prefer a slot with allocated space, such as `conversation. name: '@local/my-decoration' ``` -Call `plugin_manager` with `action: install_bundle` and the absolute package directory as `target`. It performs package installation and bundle selection; do not reproduce those steps with shell commands. Only pass `approvedBuilds` after the user explicitly approves the reported pending build scripts. +Call `plugin_manager` with `action: install_bundle` and the absolute package directory as `target`. It performs package installation and bundle selection; do not reproduce those steps with shell commands. Only pass `approvedBuilds` after the user explicitly approves the reported pending build scripts. Preserve returned failures and pending states; report success only after observing the requested capability. Use `list_plugins` or `list_bundles` to obtain exact identifiers for existing installations. `set_plugin` and `set_bundle` toggle them; `remove_bundle` removes a bundle. Inspect saved-state and activation outcomes separately: `failed` requires diagnosis, `overridden` means a higher-priority layer wins, and `restart-required` means the change is not live. Installing a new bundle can activate through HMR; replacing an installed package requires restart to load a fresh JavaScript module generation. Do not infer updated browser code from an unchanged slot id. @@ -105,4 +105,4 @@ Create a configuration-only bundle: its manifest needs a unique name, version, a failOnStartupError: true ``` -Replace the endpoint, install the bundle through `plugin_manager`, then call `mcp__demo__ping` or another discovered tool. For stdio, use `transport: stdio`, `command`, and optional `args`, `env`, and `cwd`. Ambient credentials are scrubbed; reference existing credentials with Loader `!!js` rather than copying secrets into conversation text. Repair the same bundle on failure instead of creating duplicates. +Replace the endpoint, install the bundle through `plugin_manager`, then call `mcp__demo__ping` or another newly available `mcp____` tool to verify the connection. For stdio, use `transport: stdio`, `command`, and optional `args`, `env`, and `cwd`. Ambient credentials are scrubbed; reference existing credentials with Loader `!!js` rather than copying secrets into conversation text. Repair the same bundle on failure instead of creating duplicates. diff --git a/packages/preset/agent-presets/presets/cordis/skills/editing-cordis-compositions/SKILL.md b/packages/preset/agent-presets/presets/cordis/skills/editing-cordis-compositions/SKILL.md index 727099f6fc..dfdc4de73a 100644 --- a/packages/preset/agent-presets/presets/cordis/skills/editing-cordis-compositions/SKILL.md +++ b/packages/preset/agent-presets/presets/cordis/skills/editing-cordis-compositions/SKILL.md @@ -1,6 +1,6 @@ --- name: editing-cordis-compositions -description: Use when creating, changing, or validating a Cordis composition for this harness — writing or editing an agent preset, adding or removing a plugin row, deciding whether something belongs to the host composition or to one session, checking whether a preset you authored actually mounts, or diagnosing a row that mounted but contributed nothing. +description: Use when creating, changing, or validating an agent preset or other Cordis composition for this harness, including deciding host versus preset placement and checking that an authored preset mounts. --- # Editing Cordis compositions diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 8a3a2d3f04..3b40c32243 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -7125,9 +7125,6 @@ importers: '@deepseek-ai/dsh-cordis-host-runner': specifier: workspace:^ version: link:../cordis-host-runner - '@deepseek-ai/dsh-system-prompt': - specifier: workspace:^ - version: link:../../core/system-prompt '@deepseek-ai/dsh-tools': specifier: workspace:^ version: link:../../core/tools diff --git a/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md b/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md index 158f24c1af..ac4c592e35 100644 --- a/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md +++ b/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md @@ -25,10 +25,6 @@ Use the web_fetch tool to retrieve the content of a specific HTTP(S) URL (for ex Use goal tools for one long-running completion objective in the current session. create_goal may infer goal intent from a direct human request in any language; do not create a goal for routine single-turn work. Call get_goal before update_goal and copy its exact goal_id and revision. After session resume or fork, an active goal is disarmed: when a human asks to continue or resume in any wording or language, use update_goal action resume to rearm it. Mark complete only when the objective is actually achieved. Mark blocked only after the same blocking condition persists for at least 3 consecutive goal rounds, and report that concrete condition in blocked_reason; difficulty, uncertainty, or useful remaining work is not blocked. -# Harness runtime inspection - -Use cordis_inspect_list to discover Host and Client providers, then cordis_inspect_query to read exact Service, Event, Tool, Theme or Slot APIs. These tools are read-only; queries do not invoke business methods. - 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. Use subagent in the background by default. Start independent delegations together in one assistant message and continue useful work while they run. Set `run_in_background: false` only when your next action depends on that subagent's result. When a background run settles, the runtime sends you a notice containing its outcome and any final assistant message. @@ -71,7 +67,7 @@ interface ToolArgsMap { } & Record; /** List every Cordis Inspect Provider currently known to the Host, including local Host Providers and the latest manifests synchronized from the Client. Each entry includes its platform, purpose, read-only methods, and input/output schemas. Call this Tool before writing or configuring a plugin, then select the provider and method for cordis_inspect_query from its result. Do not guess names or treat an Inspect method as a business Service that Plugin code can call. */ cordis_inspect_list: Record; - /** Run a read-only query explicitly declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before writing plugin code to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime. For Service.listService and Event.listEvents, query without input to navigate the compact signature directory, then query the exact service or event for its structured contract and referenced types. For Slots.listSubTree, query without root to navigate the compact tree, then query an exact Slot root for its complete registration contract and props; an exact Factory root returns its identity, scope, and registrant. */ + /** Run a read-only query declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before writing plugin code to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime. */ cordis_inspect_query: { /** Runtime platform that owns the Provider. */ platform: "host" | "client"; diff --git a/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json b/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json index a48efa53bf..532e048e81 100644 --- a/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json +++ b/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json @@ -55,7 +55,7 @@ }, { "name": "cordis_inspect_query", - "description": "Run a read-only query explicitly declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before writing plugin code to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime. For Service.listService and Event.listEvents, query without input to navigate the compact signature directory, then query the exact service or event for its structured contract and referenced types. For Slots.listSubTree, query without root to navigate the compact tree, then query an exact Slot root for its complete registration contract and props; an exact Factory root returns its identity, scope, and registrant.", + "description": "Run a read-only query declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before writing plugin code to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/skill-load/session.v4.jsonl b/snapshots/session/skill-load/session.v4.jsonl new file mode 100644 index 0000000000..62c83cec58 --- /dev/null +++ b/snapshots/session/skill-load/session.v4.jsonl @@ -0,0 +1,23 @@ +{"type":"session","version":4,"id":"{{session:1}}","createdAt":1783654655599,"cwd":"{{cwd}}","isSeeded":false,"delegationDepth":0} +{"type":"permission/preset","data":{"preset":"danger-full-access"}} +{"type":"sandbox/mode","data":{"mode":"danger-full-access"}} +{"type":"approval/policy","data":{"policy":"never"}} +{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Load the editing-cordis-compositions skill with the skill tool, then reply DONE."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}} +{"type":"turn/start","data":{"turn":1}} +{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}} +{"type":"step/start","data":{"turn":1,"step":1}} +{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"system-prompt"},"id":"{{message:2}}"}},"surfaceOp":"append"} +{"type":"user/message","data":{"content":[{"type":"text","text":"Load the editing-cordis-compositions skill with the skill tool, then reply DONE."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"} +{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"runtime-context","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"} +{"type":"user/message","data":{"content":[{"type":"text","text":"\nA skill is a reusable set of task-specific instructions. The following skills are available in this session:\n\n\n- `editing-cordis-compositions`: Use when creating, changing, or validating an agent preset or other Cordis composition for this harness, including deciding host versus preset placement and checking that an authored preset mounts.\n- `model-only-skill`: Prove user-disabled skills remain available to the model.\n- `snapshot-skill`: Exercise project skill discovery and loading in snapshot tests.\n\n\nIf the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.\nA user may also invoke a skill directly; its block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.\n"}],"source":{"kind":"skill-catalog","form":"catalog","entries":[{"name":"editing-cordis-compositions","description":"Use when creating, changing, or validating an agent preset or other Cordis composition for this harness, including deciding host versus preset placement and checking that an authored preset mounts."},{"name":"model-only-skill","description":"Prove user-disabled skills remain available to the model."},{"name":"snapshot-skill","description":"Exercise project skill discovery and loading in snapshot tests."}]},"role":"user","id":"{{message:4}}"},"surfaceOp":"append"} +{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"tools":"{{tools}}"},"reason":"initial"}} +{"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}} +{"type":"session/title","data":{"title":"Load the editing-cordis-compositions ski","messageSeqs":[8],"source":{"kind":"fallback"}}} +{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"Load the requested skill."},{"type":"tool-call","id":"call_skill_load","name":"skill","arguments":"{\"name\":\"editing-cordis-compositions\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:5}}"},"usage":{"inputTokens":100,"outputTokens":20,"cacheReadTokens":0,"reasoningTokens":5},"stream":[{"type":"chunk","time":1788699430688,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788699430688,"index":0,"dt":[],"texts":["Load the requested skill."]},{"type":"chunk","time":1788699430688,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788699430688,"index":1,"dt":[],"id":"call_skill_load","name":"skill","args":["{\"name\":\"editing-cordis-compositions\"}"]},{"type":"chunk","time":1788699430688,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"Load the requested skill."}}},{"type":"chunk","time":1788699430688,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_skill_load","name":"skill","arguments":"{\"name\":\"editing-cordis-compositions\"}"}}},{"type":"chunk","time":1788699430688,"chunk":{"type":"usage","usage":{"inputTokens":100,"outputTokens":20,"cacheReadTokens":0,"reasoningTokens":5}}},{"type":"chunk","time":1788699430688,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"} +{"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_skill_load","name":"skill","arguments":"{\"name\":\"editing-cordis-compositions\"}"}} +{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"tool","source":{"kind":"tool","callId":"call_skill_load"},"toolCallId":"call_skill_load","content":[{"type":"text","text":"\n\nBase directory for this skill: {{cwd}}/.dsh/skills/editing-cordis-compositions\nResolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.\n\n\n\n# Editing Cordis compositions\n\nEvery capability in this harness is a plugin row in a `cordis.yml`. There is no separate configuration language: changing what an agent can do means changing which rows are composed for it.\n\n## Off-limits\n\n**Never edit, delete, or overwrite a preset that ships with the deployment** — the `agent-presets` directory beside the deployment's own config, which supplies `standard`, `ptc`, `minimal`, and `cordis`. Never escalate the sandbox to reach it, even when a change there looks quicker. An upgrade overwrites that install, and corrupting `cordis` disables preset authoring itself. Reading a shipped composition is the intended way to start; writing to one is not, and neither is editing the host composition to work around a preset limitation.\n\nTo change what a shipped preset does, copy it and edit the copy. Locally authored presets under the user root are yours to create, edit, and delete.\n\n## Decide the plane first\n\nTwo planes, and the choice is not about how \"agent-related\" something feels — it is about whether the thing must be shared.\n\n**Host composition.** The registries themselves (`tools`, `systemPrompt`, `agents`, `agent-loop`, `sessions`), anything crossing sessions (persistence, session query, storage, settings, credentials, telemetry), the sandbox and approval stack, the model route, and the subagent registry with its spawn/fork backends. One instance for the process.\n\n**Agent preset.** What one session contributes to those registries: its tool plugins, its persona and prompt sections, its compaction policy. One instance per session, mounted under that session's scope and unwound with it.\n\n**A service with a consumer outside the agent plane cannot move into a preset.** `subagents` is the worked example: the registry answers cross-session queries for the host api-proxy, so a per-session copy both starves that host row — it waits forever for a service nothing provides — and collides on the second session, since a provider name registers once. The preset contributes the delegation *tools*; the registry and its backends stay host-side.\n\nA preset is a directory holding one `agent.cordis.yml`, optionally beside a `preset.yml` carrying display metadata — `name` and `description` (and, for shipped presets, a roster `order`). Write the metadata too: a preset without it shows up in every picker as its bare directory name.\n\nLocally authored presets live one directory per preset under `${DSH_HOME:-$HOME/.dsh}/.agent-presets/`, and the shipped set sits beside the deployment's own config. Use those when the user asks where to look. For deployment overrides, read `${DSH_HOME:-$HOME/.dsh}/profiles//cordis.patch.yml`, `${DSH_HOME:-$HOME/.dsh}/cordis.patch.yml`, and any launch `--patch` files for the `agent-presets` row's `roots` and `includeUserRoot`. Obtain the active profile and extra patch paths from the user when they are not in the task context; do not guess a different profile.\n\n## Authoring a preset\n\nUse shell and file tools to locate the installed `@deepseek-ai/dsh-agent-presets` package under the active profile's `node_modules` or the deployment installation. Its `presets//` directory contains each shipped preset. If those files are unavailable, ask the user to copy the preset through the Web preset picker and provide the copied directory; runtime API inspection does not execute Remote methods.\n\nCopy the complete source directory, including skills and assets, into a new `${DSH_HOME:-$HOME/.dsh}/.agent-presets//` directory (or the explicitly configured writable root). Refuse an existing destination. Set `name` and `description` in `preset.yml` and remove the copied roster `order`. Never overwrite the installed source.\n\nEdit the copy's `agent.cordis.yml` with the normal file tools. Writes outside the workspace follow the active filesystem approval policy. For profile-wide capabilities, author a workspace bundle and install it with `plugin_manager`; load `cordis-plugin-development` for packaging guidance.\n\n## Service isolation\n\nA preset row that publishes a service needs an `isolate` realm containing both the provider and all its consumers. A tool that only consumes a host service remains outside that realm. Copy the shipped preset's existing groups rather than introducing service instances into the process-global realm.\n\n```yaml\n- id: delegation\n name: cordis:group\n group: true\n isolate:\n workflowEngine: true\n config:\n - id: workflow-ptc\n name: '@deepseek-ai/dsh-workflow-ptc'\n config:\n provider: spawn\n - id: tool-workflow\n name: '@deepseek-ai/dsh-tool-workflow'\n```\n\n## Verify a preset\n\nCheck the edited YAML and referenced local files with file tools. Ask the user to select the new preset in the Web picker and start a session; this authoring agent cannot invoke the preset Remote API or start a Web session through inspection. Once the user provides a running session or browser control, inspect the visible tools and any activation diagnostic. File validation alone does not verify imports, service dependencies, or isolation. Report which checks ran and leave activation unverified until that session check succeeds.\n\n## Native product subagents\n\nCodex and Claude Code providers are independent optional Profile Bundles. Install only the products a Profile needs, then restart the Profile so its Host registers those providers:\n\n```sh\ndsh plugin --profile add @deepseek-ai/dsh-subagent-codex\ndsh plugin --profile add @deepseek-ai/dsh-subagent-claude-code\ndsh plugin --profile remove @deepseek-ai/dsh-subagent-codex\ndsh plugin --profile remove @deepseek-ai/dsh-subagent-claude-code\n```\n\nEach Bundle owns its Host availability; the preset separately grants one Agent its ordinary delegation tool. Never move a product provider into the preset and never add a product-specific settings field. Removing one package withdraws only that provider on the next Profile start.\n\nCopy these disabled templates from a shipped full preset and remove `disabled` only for the products the user requested:\n\n```yaml\n- id: tool-subagent-codex\n name: '@deepseek-ai/dsh-tool-subagent'\n disabled: true\n config:\n provider: codex\n toolName: subagent_codex\n backgroundMode: one-shot\n maxDepth: provider-managed\n\n- id: tool-subagent-claude-code\n name: '@deepseek-ai/dsh-tool-subagent'\n disabled: true\n config:\n provider: claude-code\n toolName: subagent_claude_code\n backgroundMode: one-shot\n maxDepth: provider-managed\n```\n\nFor additional named Codex or Claude Code instances, mount a separate host-plane provider row for each instance with a unique `providerName`, then add a separate preset tool row whose `provider` exactly matches that name and whose `toolName` is also unique. Keep the shipped rows for the default `codex` and `claude-code` names; do not reuse one tool row for several providers or derive either name from permission or environment settings.\n\nThe two rows are independent. Leaving both disabled preserves the copied preset, enabling one exposes only that product tool, and enabling both exposes both. Production `dsh` does not install either optional provider: before enabling a row, install the matching `@deepseek-ai/dsh-subagent-codex` or `@deepseek-ai/dsh-subagent-claude-code` Bundle in the Profile and restart it. Each Bundle registers its dormant default provider and exclusively uses its pinned package-local platform CLI; additional named instances use extra host-plane rows from the same installed package. A preset cannot provide that host dependency. `backgroundMode: one-shot` keeps omitted or `false` calls in the foreground and lets explicit `run_in_background: true` return a generic Job id. Full presets already carry `tool-jobs`, while the base host carries the job registry; retain both so `job_output`, `job_list`, `job_kill`, cancellation, and completion notices stay available. Installing a Bundle or composing a preset row does not start a product, authenticate an account, select a model, probe credentials, or manage native product settings.\n\n## What not to move into a preset\n\n`agent-loop` registers the one agent factory and throws on a second. The registries own the per-session layering and cannot themselves be per-session. Session persistence must stay host-side or the session list fragments. The sandbox, approval, and permission rows are a deliberate boundary: a preset is exactly as privileged as the plugins it names, so letting one relax its own confinement would defeat the confinement.\n\n"}],"isError":false,"id":"{{message:6}}"}},"sourceEventSeqs":[15],"surfaceOp":"append"} +{"type":"step/end","data":{"turn":1,"step":1}} +{"type":"step/start","data":{"turn":1,"step":2}} +{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The skill is loaded."},{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:7}}"},"usage":{"inputTokens":180,"outputTokens":10,"cacheReadTokens":0,"reasoningTokens":4},"stream":[{"type":"chunk","time":1788699430709,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788699430709,"index":0,"dt":[],"texts":["The skill is loaded."]},{"type":"chunk","time":1788699430709,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":1788699430709,"index":1,"dt":[],"texts":["DONE"]},{"type":"chunk","time":1788699430709,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The skill is loaded."}}},{"type":"chunk","time":1788699430709,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}},{"type":"chunk","time":1788699430709,"chunk":{"type":"usage","usage":{"inputTokens":180,"outputTokens":10,"cacheReadTokens":0,"reasoningTokens":4}}},{"type":"chunk","time":1788699430709,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} +{"type":"step/end","data":{"turn":1,"step":2}} +{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/snapshots/web/cordis-tool-round/tool-schemas.expected.json b/snapshots/web/cordis-tool-round/tool-schemas.expected.json index ca7afe0add..bb6f987d5a 100644 --- a/snapshots/web/cordis-tool-round/tool-schemas.expected.json +++ b/snapshots/web/cordis-tool-round/tool-schemas.expected.json @@ -195,7 +195,7 @@ }, { "name": "cordis_inspect_query", - "description": "Run a read-only query explicitly declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before cordis_define to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime. For Service.listService and Event.listEvents, query without input to navigate the compact signature directory, then query the exact service or event for its structured contract and referenced types. For Slots.listSubTree, query without root to navigate the compact tree, then query an exact Slot root for its complete registration contract and props; an exact Factory root returns its identity, scope, and registrant.", + "description": "Run a read-only query declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before writing plugin code to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/web/skill-tool-row/snapshot.yml b/snapshots/web/skill-tool-row/snapshot.yml index 4c82c05edb..8b01149257 100644 --- a/snapshots/web/skill-tool-row/snapshot.yml +++ b/snapshots/web/skill-tool-row/snapshot.yml @@ -6,4 +6,4 @@ recording: authored header: class: skill session: - source: ../../session/skill-load/session.v3.jsonl + source: ../../session/skill-load/session.v4.jsonl From ecf6acfb15d91b5a253d026cd7c4fac760891bc7 Mon Sep 17 00:00:00 2001 From: Yudong Date: Sat, 19 Sep 2026 03:06:04 +0800 Subject: [PATCH 087/100] feat(api): support binary fields in Remote results --- ...08-02-typert-remote-method-calls.i18n.yaml | 4 +- .../2026-08-02-typert-remote-method-calls.md | 4 +- ...026-08-02-typert-remote-method-calls.zh.md | 4 +- ...26-09-05-workspace-files-service.i18n.yaml | 4 +- .../2026-09-05-workspace-files-service.md | 28 +- .../2026-09-05-workspace-files-service.zh.md | 28 +- ...9-08-document-preview-operations.i18n.yaml | 4 +- .../2026-09-08-document-preview-operations.md | 6 +- ...26-09-08-document-preview-operations.zh.md | 6 +- ...09-workspace-file-read-authority.i18n.yaml | 4 +- ...026-09-09-workspace-file-read-authority.md | 4 +- ...-09-09-workspace-file-read-authority.zh.md | 4 +- .../2026-09-11-node-office-kit.i18n.yaml | 4 +- .../2026-09-11-node-office-kit.md | 2 +- .../2026-09-11-node-office-kit.zh.md | 2 +- ...7-workspace-file-binary-transfer.i18n.yaml | 6 + ...26-09-17-workspace-file-binary-transfer.md | 31 ++ ...09-17-workspace-file-binary-transfer.zh.md | 31 ++ ...debar-text-preview-and-file-tree.i18n.yaml | 4 +- ...9-05-sidebar-text-preview-and-file-tree.md | 2 +- ...5-sidebar-text-preview-and-file-tree.zh.md | 2 +- apps/web/tests/document-preview.e2e.ts | 12 + docs/api-gateway.i18n.yaml | 4 +- docs/api-gateway.md | 6 +- docs/api-gateway.zh.md | 6 +- docs/config-catalog.i18n.yaml | 4 +- docs/config-catalog.md | 2 +- docs/config-catalog.zh.md | 2 +- docs/subsystems/office-to-pdf.i18n.yaml | 4 +- docs/subsystems/office-to-pdf.md | 2 +- docs/subsystems/office-to-pdf.zh.md | 2 +- docs/subsystems/sidebar-right.i18n.yaml | 4 +- docs/subsystems/sidebar-right.md | 6 +- docs/subsystems/sidebar-right.zh.md | 6 +- docs/subsystems/typert.i18n.yaml | 4 +- docs/subsystems/typert.md | 15 +- docs/subsystems/typert.zh.md | 15 +- docs/subsystems/web-client.i18n.yaml | 4 +- docs/subsystems/web-client.md | 2 +- docs/subsystems/web-client.zh.md | 2 +- docs/subsystems/workspace.i18n.yaml | 4 +- docs/subsystems/workspace.md | 30 +- docs/subsystems/workspace.zh.md | 30 +- packages/api/gateway/README.i18n.yaml | 4 +- packages/api/gateway/README.md | 4 +- packages/api/gateway/README.zh.md | 4 +- packages/api/gateway/src/client/index.ts | 6 +- packages/api/gateway/src/index.ts | 82 ++++- .../api/gateway/tests/gateway.client.spec.ts | 93 +++++- .../api/gateway/tests/gateway.host.spec.ts | 141 +++++++- packages/api/workspace-files/README.i18n.yaml | 4 +- packages/api/workspace-files/README.md | 22 +- packages/api/workspace-files/README.zh.md | 22 +- packages/api/workspace-files/package.json | 1 + packages/api/workspace-files/src/index.ts | 76 ++--- packages/api/workspace-files/src/types.ts | 14 +- .../workspace-files/tests/binary-rpc.spec.ts | 93 ++++++ .../workspace-files/tests/read-all.spec.ts | 91 ++++-- .../workspace-files/tests/read-bytes.spec.ts | 75 +++-- packages/client/connection/README.i18n.yaml | 4 +- packages/client/connection/README.md | 4 +- packages/client/connection/README.zh.md | 4 +- packages/client/connection/src/client/rpc.ts | 60 +++- packages/client/connection/src/http-bridge.ts | 10 +- packages/client/connection/src/rpc-host.ts | 60 +++- packages/client/connection/src/rpc.ts | 20 +- .../connection/tests/binary-rpc.host.spec.ts | 309 ++++++++++++++++++ .../connection/tests/http-bridge.host.spec.ts | 65 ++++ packages/client/connection/tsconfig.host.json | 2 + .../README.i18n.yaml | 4 +- .../ui-sidebar-documentpreview/README.md | 8 +- .../ui-sidebar-documentpreview/README.zh.md | 8 +- .../src/client/face.ts | 2 +- .../src/client/html/index.ts | 2 +- .../src/client/html/read-relative.ts | 13 +- .../src/client/index.ts | 11 +- .../src/client/office/index.ts | 5 +- .../src/client/rpc.ts | 12 +- .../tests/apply.client.spec.ts | 38 +-- .../tests/document-seat.client.spec.tsx | 12 +- .../tests/face.client.spec.ts | 1 + .../tests/fixtures.client.ts | 7 +- .../tests/html-apply.client.spec.ts | 9 +- .../tests/html-body.client.spec.tsx | 8 +- .../tests/html-read-relative.client.spec.ts | 12 +- .../tests/office-registration.client.spec.ts | 10 +- .../tests/rpc.client.spec.ts | 16 +- packages/document/office-to-pdf/src/index.ts | 2 +- packages/document/office-to-pdf/src/types.ts | 4 +- .../office-to-pdf/tests/remote.spec.ts | 4 +- packages/host/webserver/README.i18n.yaml | 4 +- packages/host/webserver/README.md | 2 +- packages/host/webserver/README.zh.md | 2 +- packages/host/webserver/src/index.ts | 1 + packages/typert/generator/README.i18n.yaml | 4 +- packages/typert/generator/README.md | 2 + packages/typert/generator/README.zh.md | 2 + packages/typert/generator/src/analyzer.ts | 39 ++- packages/typert/generator/src/emitter.ts | 176 +++++++++- .../generator/tests/remote-model.spec.ts | 238 +++++++++++++- packages/typert/loader/src/index.ts | 5 + packages/typert/loader/tests/loader.spec.ts | 8 + packages/typert/protocol/README.i18n.yaml | 4 +- packages/typert/protocol/README.md | 2 + packages/typert/protocol/README.zh.md | 2 + packages/typert/protocol/src/types.ts | 13 + packages/typert/registry/tests/typert.spec.ts | 12 + pnpm-lock.yaml | 3 + scripts/gen-cordis-catalog.ts | 1 + 109 files changed, 1882 insertions(+), 446 deletions(-) create mode 100644 .agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.i18n.yaml create mode 100644 .agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md create mode 100644 .agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.zh.md create mode 100644 packages/api/workspace-files/tests/binary-rpc.spec.ts create mode 100644 packages/client/connection/tests/binary-rpc.host.spec.ts diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml index 190fecf123..534a9fddcd 100644 --- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md -2026-08-02-typert-remote-method-calls.md: b599b3f9a353738bbb44a4da9b5a72be8309e2fb -2026-08-02-typert-remote-method-calls.zh.md: 64dc84f0ae07b10d50452ef7e36c30db102953cf +2026-08-02-typert-remote-method-calls.md: 9986e0dac5e85d0aadc745ca4084ed3d1cecae54 +2026-08-02-typert-remote-method-calls.zh.md: 282af768413498658722af3adee17fb59a8e93c2 diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md index b599b3f9a3..9986e0dac5 100644 --- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md +++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md @@ -181,7 +181,7 @@ Consequently, `SessionId`, the Agent wire ID, the request, and the result all re Remote methods themselves use declaration-map navigation. Typert anchors `InvocationModel.location` to the decorated Host method-name token and emits a source-map segment on the corresponding property of the namespace interface. For an adapter-backed endpoint, after the TypeScript editor resolves `ctx.remote.models.list` to its generated declaration, `typert.remote-client.d.ts.map` takes it to the Host Service's `remoteExportList` entry point. That entry point explicitly calls the existing, unrenamed `list()` method; the map does not misidentify the decorator, class, or full signature as the method definition. -Typert generates a wire Zod codec for the same symbol key. The Host Gateway uses parameter and identity codecs to validate input. Client Remote trusts its generated TypeScript arguments and successful Host results instead of executing invocation codecs. If a complex type cannot produce a strict codec, the LIB build fails instead of degrading to `unknown` or unchecked JSON. +Typert generates a wire Zod codec for the same symbol key. The Host Gateway uses parameter and identity codecs to validate input. Client Remote trusts its generated TypeScript arguments and JSON success results. Binary success results use their generated codec after multipart decoding, as specified by [binary Remote transfer](2026-09-17-workspace-file-binary-transfer.md). If a complex type cannot produce a strict codec, the LIB build fails instead of degrading to `unknown` or unchecked JSON. Named business types referenced by Remote methods must be exported from public, type-only subpaths. If the only reachable entry also imports Host Services, Cordis `Context` merges, or Host-only implementations, the build fails and requires the business package to provide a safe type entry. Primitives, literals, and simple compositions explicitly supported by Typert need no additional names. @@ -514,7 +514,7 @@ Canonical public types require business DTOs to have type-only entries, which ma Type imports and runtime contributions have different effects. `import type {}` extends only the static Remote surface. If a real calling environment omits the value contribution, the Client Remote Service must fail with an explicit "Remote not mounted" error. -Generated Host and Client artifacts carry matching Zod factories, but Client Remote does not materialize invocation schemas. Canonical symbol keys, the same generated model, and Host wire validation keep the two sides aligned without comparing schema object identities across realms. +Generated Host and Client artifacts carry matching Zod factories; Client Remote materializes only binary result schemas. Canonical symbol keys, the same generated model, and Host wire validation keep the two sides aligned without comparing schema object identities across realms. A consumer may import a Remote contract that is not currently mounted on the Host. The types mean "this protocol capability was selected by the consumer," not that a corresponding Service currently exists in the target process; an unavailable endpoint must fail explicitly at runtime. diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md index 64dc84f0ae..282af76841 100644 --- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md @@ -181,7 +181,7 @@ import type { CreateGoalRequest, CreateGoalResult } from '@deepseek-ai/dsh-goal/ Remote 方法本身使用 declaration map 导航。Typert 把 `InvocationModel.location` 固定在 Host 被装饰方法的方法名 token,并在 namespace interface 的对应属性上写入 source-map segment。对于由适配器支撑的 endpoint,TypeScript editor 从 `ctx.remote.models.list` 取得生成 declaration 后,再沿 `typert.remote-client.d.ts.map` 跳到 Host Service 的 `remoteExportList` 远程出口。该出口继续显式调用不改名的存量 `list()`,map 不把 decorator、class 或整个签名误当成方法定义位置。 -Typert 为同一 symbol key 生成 wire Zod codec。Host Gateway 用参数与 identity codec 校验输入;Client Remote 信任生成的 TypeScript 参数与成功的 Host 结果,不执行调用 codec。复杂类型无法生成严格 codec 时,LIB 构建失败,不降级为 `unknown` 或无校验 JSON。 +Typert 为同一 symbol key 生成 wire Zod codec。Host Gateway 用参数与身份 codec 校验输入。Client Remote 信任生成的 TypeScript 参数与 JSON 成功结果。二进制成功结果在 multipart 解码后执行生成的结果 codec,具体由[二进制 Remote 传输](2026-09-17-workspace-file-binary-transfer.zh.md)规定。复杂类型若无法生成严格 codec,LIB 构建失败,不降级为 `unknown` 或未校验 JSON。 Remote 方法引用的命名业务类型必须从纯类型公共 subpath 导出。如果唯一可达入口会带入 Host Service、Cordis `Context` merge 或 Host-only 实现,构建失败并要求业务包提供安全的类型出口。原始值、字面量和 Typert 明确支持的简单组合不需要额外命名。 @@ -514,7 +514,7 @@ SRC 弱 descriptor 不验证普通 JSON 内部结构。Host Remote 签名变化 类型 import 与运行时 contribution 是两种不同效果。`import type {}` 只扩展静态 Remote surface;真实调用环境遗漏 value contribution 时,Client Remote Service 必须以明确的「Remote 未挂载」错误失败。 -生成的 Host 与 Client 产物携带匹配的 Zod factory,但 Client Remote 不实例化调用 schema。规范 symbol key、同一生成模型和 Host wire 校验让两侧保持一致,而无需跨 realm 比较 schema 对象 identity。 +生成的 Host 与 Client 产物携带匹配的 Zod factory;Client Remote 仅实例化二进制结果 schema。规范 symbol key、同一生成模型和 Host wire 校验让两侧保持一致,而无需跨 realm 比较 schema 对象 identity。 消费端可以导入 Host 当前未挂载的 Remote contract。类型表示「该协议能力已被消费端选择」,不保证目标进程当前存在对应 Service;运行时 endpoint 不可用必须明确失败。 diff --git a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.i18n.yaml index 050ce7d48f..f44cffc1fa 100644 --- a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.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 .agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md -2026-09-05-workspace-files-service.md: 40157508a83abc61245845a1dbe4f1749e175563 -2026-09-05-workspace-files-service.zh.md: 51de0ad5b644f27e30557ea6b11ba62b8ef9a715 +2026-09-05-workspace-files-service.md: 65bebf18175d9a94452c92cd36ada3c5ef267ce5 +2026-09-05-workspace-files-service.zh.md: b4ca420042dc702f9bc1eaf5bb09f2667a19322d diff --git a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md index 40157508a8..65bebf1817 100644 --- a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md +++ b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md @@ -25,15 +25,13 @@ Two constraints frame the service. File reads through `ctx.fs` use the Session's `api/remotes` and both root aggregates reference the matching Host/Client leaf. The package exports `.`, `./client`, `./types`, `./typert`, and `./remote`, with one `workspace-files` web-app row supplying both faces. The Client plugin injects `['resources', 'remote', 'remote.workspaceFiles']`; the resource model takes result types directly from the protocol package, and the text preview owns the Sidebar parameter declaration, so the Client compilation graph has no reverse dependency on Remote assembly or Sidebar UI. -### The `workspaceFiles` Remote namespace +### The `workspaceFiles` file operations -Every Host method takes `WorkspaceFileScope` first. The Gateway resolves it from the wire Session identity by reading the live Session header or, for a cold Session, `SessionPersistence.stat`; it never activates an Agent, reads the event body, or falls back to a parent Session. The scope carries the selected Session id and its `cwd`, with the sandbox policy's deployment root used only when that header has no `cwd`. A Client passes its Session id and never names a root. The seven signatures, as `src/index.ts` declares them: +Every Host method takes `WorkspaceFileScope` first. The `workspaceFileScope` Gateway lookup resolves Session identity. It reads the live Session header or, for a cold Session, `SessionPersistence.stat`; it never activates an Agent, reads the event body, or falls back to a parent Session. The scope carries the selected Session id and its `cwd`, with the sandbox policy's deployment root used only when that header has no `cwd`. A Client passes its Session id and never names a root. The five signatures, as `src/index.ts` declares them: ```ts ignore-check @Remote async read(workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise -@Remote async readBytes(workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise -@Remote async readAll(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise -@Remote async readRelated(workspaceFileScope: WorkspaceFileScope, path: string, relativePath: string, signal: AbortSignal): Promise +@Remote async readBytes(workspaceFileScope: WorkspaceFileScope, path: string, options: WorkspaceByteReadOptions, signal: AbortSignal): Promise @Remote async stat(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise @Remote async list(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise @Remote({ mode: 'stream' }) changes(workspaceFileScope: WorkspaceFileScope, signal: AbortSignal): AsyncIterable @@ -41,20 +39,20 @@ Every Host method takes `WorkspaceFileScope` first. The Gateway resolves it from - **`stat`** returns `WorkspaceFileStat { absolutePath, version, bytes? }`: the file's identity, its opaque freshness token, and its size when the backend reports one. It accepts a regular file only. - **`read`** returns one window of lines, `WorkspaceFileText = WorkspaceFileStat & { offset, text, lines, eof }`; `lines` counts the page's lines, so a page holding one empty line (`text: ''`, `lines: 1`) and a page past the end (`lines: 0`) read differently. `range.offset` is the 1-based first line and defaults to 1; `range.limit` is the largest number of lines and defaults to `maxLines`, which it may not exceed. Lines end at `\n` and a final `\n` terminates the last line rather than opening an empty one; `text` joins the page's lines with `\n` and carries no terminator; `eof` is true when the page includes the last line, and an offset past the end returns an empty page with `eof` true. The pager walks `streamText`, counts the lines before the window without keeping them, admits each in-window segment against `maxBytes` before buffering it, and returns at the first character past the window, so a file of any size costs one page of memory. The `version` and `bytes` on a page are the stat's, taken before the stream. -- **`readBytes`** returns one window of raw bytes, `WorkspaceFileBytes = WorkspaceFileStat & { offset, data, eof }`. `range.offset` is the 0-based first byte and defaults to 0; `range.length` is the largest byte count and defaults to `maxBytes`, which it may not exceed. `data` is base64, shorter than `length` where the file ends and empty at or past it; `eof` is true when the window includes the last byte. Nothing is decoded and nothing is refused as binary. `read` pages by lines and never by bytes; a byte window is `readBytes`. -- **`readAll` and `readRelated`** return complete `WorkspaceFileBytes` under `maxFileBytes`. `readRelated` resolves a relative filesystem path from the base file's directory; the Host applies the same regular-file checks and backend read authority to both files. [Document Preview](2026-09-08-document-preview-operations.md) owns their loading and address semantics. +- **`readBytes`** returns native bytes with file metadata, offset, and EOF. The required options object selects a complete read under `maxFileBytes` when `range` is absent, or a bounded window under `maxBytes` when present. `range: {}` uses offset zero and the configured window cap; windows can read files above the complete-file cap. The [binary transfer decision](2026-09-17-workspace-file-binary-transfer.md) owns the Remote response encoding. +- **`baseFile`** selects target resolution independently of `range`: the target `path` must be relative and resolves from the base file's directory. The Host applies regular-file checks to both files and preserves backend read authority. [Document Preview](2026-09-08-document-preview-operations.md) owns content loading and address semantics. - **`list`** returns `WorkspaceDirectoryListing { path, entries, truncated }`: the listed directory as a workspace path relative to the root (empty for the root), its direct children in the backend's stable name order as `{ name, type, size? }`, and whether `maxEntries` cut the list. `type` is `file`, `directory`, or `other`; a symlink child reports the type of what it points to and a dangling one is `other`, while opening such a child still fails the link gate below. Dotfiles are listed; nothing is filtered. - **`changes`** yields `WorkspaceFileWatchFrame`: `{ kind: 'ready' }` after the observation queue is registered and the workspace root resolves, followed by `{ kind: 'change', change }`. The `WorkspaceFileChange` payload is `{ absolutePath, version }` for a present file or `{ absolutePath, absent: true }` for one observed gone. Its source is `fs/observed` inside the workspace root, never an OS watcher. Observations after the first pull are queued, including during root resolution; cancellation or plugin disposal ends the generation. ### Paths on the wire -Two path vocabularies leave the service, and each method uses exactly one. `read`, `readBytes`, `readAll`, `readRelated`, `stat`, and `changes` name a file by `absolutePath`: its absolute path in the filesystem's execution world, symlinks resolved (`ctx.fs.processPath(target)`), so the Client provider matches a change frame to an open address by absolute path: the Client sends the address's path unchanged to the Host and binds the follower only to a successful `stat.absolutePath`, without reading a Session summary's cwd. `list` speaks workspace paths — the same syntax its `path` argument accepts, absolute or relative to the root — because its consumer is a tree rooted there. The field is called `absolutePath` and not `url` because it is not a resource address; the address grammar belongs to `dsh-util-workspace-path` and is described with the resource model. Input paths to `read`, `readBytes`, `readAll`, `readRelated`, `stat`, and `list` are absolute or relative to the session's workspace root, never to the backend's own cwd. +Two path vocabularies leave the service, and each method uses exactly one. `read`, `readBytes`, `stat`, and `changes` name a file by `absolutePath`: its absolute path in the filesystem's execution world, symlinks resolved (`ctx.fs.processPath(target)`), so the Client provider matches a change frame to an open address by absolute path: the Client sends the address's path unchanged to the Host and binds the follower only to a successful `stat.absolutePath`, without reading a Session summary's cwd. `list` speaks workspace paths — the same syntax its `path` argument accepts, absolute or relative to the root — because its consumer is a tree rooted there. The field is called `absolutePath` and not `url` because it is not a resource address; the address grammar belongs to `dsh-util-workspace-path` and is described with the resource model. Input paths to `read`, `readBytes`, `stat`, and `list` are absolute or relative to the session's workspace root, never to the backend's own cwd; `readBytes` with `baseFile` resolves the target from that file's directory. `version` is an opaque string a consumer compares for equality and never parses: the local backend derives it from device, inode, size, and nanosecond mtime and ctime, so a rewrite that leaves the content identical still changes it. `offset` means a line on `read` and a byte on `readBytes`; the two units never mix, and `eof` on either means the window reached the file's end. ### File checks and workspace containment -`read`, `readBytes`, `readAll`, `readRelated`, and `stat` share regular-file checks and then rely on the filesystem backend's read authority. `list` shares path inspection but also checks workspace containment, while `changes` filters observations to the workspace root. The service applies the following checks: +`read`, `readBytes`, and `stat` share regular-file checks and then rely on the filesystem backend's read authority. `list` shares path inspection but also checks workspace containment, while `changes` filters observations to the workspace root. The service applies the following checks: 1. **The path itself.** `lstat` inspects the path before anything follows it: a missing path is `not-found`, and a symlink — wherever it points, including back inside the workspace — is `not-regular-file` (kind `symlink`) for the file methods and `not-directory` for `list`. An empty path is a `gateway/bad-request`. 2. **Workspace containment for `list`.** The directory resolves to a target and `ctx.fs.contains(root, target)` decides, where `root` is the `WorkspaceFileScope.workspaceRoot` resolved from the selected Session header. A `..` traversal or an absolute directory outside the root is `outside-workspace`. `changes` applies the same backend containment predicate to observed targets. @@ -73,7 +71,7 @@ Each failure is one `RemoteError` code with typed details, declared beside the t | `workspace-file/outside-workspace` | a `list` target is not inside the workspace root | `{ path }` | | `workspace-file/too-large` | a page's text or byte window exceeds `maxBytes`, or a complete read exceeds `maxFileBytes` | `{ path, limit }` | | `workspace-file/not-text` | invalid UTF-8 up to the page's end, or a NUL byte in the sample or the page (`read` only) | `{ path }` | -| `workspace-file/not-regular-file` | `read`, `readBytes`, `readAll`, `readRelated`, or `stat` on something that is not a regular file | `{ path, kind: 'directory' \| 'symlink' \| 'other' }` | +| `workspace-file/not-regular-file` | `read`, `readBytes`, or `stat` on something that is not a regular file | `{ path, kind: 'directory' \| 'symlink' \| 'other' }` | | `workspace-file/not-directory` | `list` on something that is not a directory | `{ path, kind: 'file' \| 'symlink' \| 'other' }` | | `workspace-file/unsupported-address` | Client-minted: a resource address this provider cannot serve | `{ address }` | | `workspace-file/unknown-workspace` | Client-minted: an `absolute` address, which carries no Session | `{ address }` | @@ -109,7 +107,7 @@ The Client export registers one `ResourceProvider<'file'>` into `ctx.resources` ### Related notes -The [resource model](2026-09-05-client-resource-model.md) owns `ctx.resources`, `useResource`, the `dsh-resource:///…` address grammar, and the reasoning for one resource per address; the [text preview and file tree](../feature/2026-09-05-sidebar-text-preview-and-file-tree.md) are the shipped consumers of `read`, `list`, and the `file` provider; the [right Sidebar docking infrastructure](../feature/2026-09-04-right-sidebar-docking-infrastructure.md) is the surface they open into; [workspace file links](../feature/2026-07-31-web-workspace-file-links.md) is where serving files over HTTP was rejected. Anyone extending this system reaches the same seven methods through `remote.workspaceFiles` and the same `file` resource through `useResource<'file'>`; the wire types are published as `@deepseek-ai/dsh-api-workspace-files/types`. The [workspace file read authority](2026-09-09-workspace-file-read-authority.md) owns Host read access and the HTML security trade-off; [Document Preview](2026-09-08-document-preview-operations.md) owns content loading and per-tab freshness. +The [resource model](2026-09-05-client-resource-model.md) owns `ctx.resources`, `useResource`, the `dsh-resource:///…` address grammar, and the reasoning for one resource per address; the [text preview and file tree](../feature/2026-09-05-sidebar-text-preview-and-file-tree.md) are the shipped consumers of `read`, `list`, and the `file` provider; the [right Sidebar docking infrastructure](../feature/2026-09-04-right-sidebar-docking-infrastructure.md) is the surface they open into; [workspace file links](../feature/2026-07-31-web-workspace-file-links.md) is where serving files over HTTP was rejected. Anyone extending this system reaches the same five methods through `remote.workspaceFiles` and the same `file` resource through `useResource<'file'>`; the wire types are published as `@deepseek-ai/dsh-api-workspace-files/types`. The [workspace file read authority](2026-09-09-workspace-file-read-authority.md) owns Host read access and the HTML security trade-off; [Document Preview](2026-09-08-document-preview-operations.md) owns content loading and per-tab freshness. ## Alternatives considered @@ -117,7 +115,7 @@ The [resource model](2026-09-05-client-resource-model.md) owns `ctx.resources`, **A dual-face package with reverse UI dependencies.** The split-package choice followed two project-reference cycles after `api/remotes` referenced the Client leaf: the resource model imported Remote assembly for result types, and the file provider imported Sidebar UI for its parameter map. TypeScript rejected these cycles with `TS6202`. [dual-face packaging](2026-09-07-workspace-files-dual-face-package.md) supersedes that split: result types come directly from the protocol package, and Sidebar parameter registration belongs to the text preview; both root aggregates retain explicit compiler entries. -**Serving workspace files over HTTP.** Already rejected by [workspace file links](../feature/2026-07-31-web-workspace-file-links.md) on origin grounds and not revisited: `read` and `readBytes` carry plain text and base64 over the authenticated Remote carrier, so no document is served, no URL is minted, and no origin question arises. +**Serving navigable workspace documents.** Rejected on origin grounds; the [binary transfer](2026-09-17-workspace-file-binary-transfer.md) returns multipart data while HTML remains isolated in a Blob iframe. **Log-reachable or workspace-contained authorization for file reads.** The one precedent that sends file content over the wire, command attachments, authorizes only files that appear in the session log. That excludes typed paths, while workspace containment excludes readable files elsewhere on the Session backend. The [workspace file read authority](2026-09-09-workspace-file-read-authority.md) instead makes the backend's read decision authoritative and keeps containment only for workspace-shaped operations. @@ -138,14 +136,14 @@ The [resource model](2026-09-05-client-resource-model.md) owns `ctx.resources`, - Change frames report the agent's own operations only. A file edited by the user's editor, a shell, or a subprocess raises no frame; an agent merely reading a file that something else changed does raise one, because the read observes a new version. - File-kind inspection precedes backend reads, and `list` reports kind before an outside position. A page's `version` may be one write behind its content, and a stalled `changes` consumer grows Host memory because a generation's queue is unbounded; each is a known trade-off recorded in the package README. - The `file` resource pushes change, not content, so a preview learns a file moved on without a payload and reads the pages it wants; a failed open keeps following the address, so the agent creating the file brings the tab live without user action. -- `readBytes` has no shipped consumer yet; Document Preview uses `readAll` for complete-file formats. +- Office authorization probes use `readBytes` with a one-byte `range`; Document Preview uses the same method without `range` for complete-file formats. ## Testing -Host specs in `packages/api/workspace-files/tests` exercise header-only scope resolution for live and cold subagent Sessions, the deployment fallback, missing identities, and lookup disposal; the paged read (whole file, nested path, empty file, multi-byte UTF-8, the line window's edges, defaults and refused limits, carriage returns kept); the byte window (defaults, a middle window with more following, tail windows exact and short, past-end and empty files, NUL and invalid UTF-8 round-tripping through base64, version parity with `stat`, the cap as `too-large`, bad ranges, a window of a file far above the cap, and `eof` inferred without a size); `stat`; outside-workspace reads and backend refusals; `list` with containment, truncation, symlink children, and `not-directory`; and the `changes` stream driven by `fs/observed` and filtered by root. Client specs cover the provider's frames, the change feed, unsupported addresses, and registration and disposal. `fs/fs` and `fs-local` specs pin `readByteRange`; `dsh-util-workspace-path` specs pin the file-address grammar. The connection fixture serves `stat`, paged `read`, `list`, and an opt-in `changes` frame for the web e2e suite. +Host specs in `packages/api/workspace-files/tests` exercise header-only scope resolution for live and cold subagent Sessions, the deployment fallback, missing identities, and lookup disposal; the paged read (whole file, nested path, empty file, multi-byte UTF-8, the line window's edges, defaults and refused limits, carriage returns kept); the byte window (defaults, a middle window with more following, tail windows exact and short, past-end and empty files, NUL and invalid UTF-8 round-tripping through `Uint8Array`, version parity with `stat`, the cap as `too-large`, bad ranges, a window of a file far above the cap, and `eof` inferred without a size); `stat`; outside-workspace reads and backend refusals; `list` with containment, truncation, symlink children, and `not-directory`; and the `changes` stream driven by `fs/observed` and filtered by root. Client specs cover the provider's frames, the change feed, unsupported addresses, and registration and disposal. `fs/fs` and `fs-local` specs pin `readByteRange`; `dsh-util-workspace-path` specs pin the file-address grammar. The connection fixture serves `stat`, paged `read`, `list`, and an opt-in `changes` frame for the web e2e suite. ## Deferred - A bound on a `changes` generation's queue. -- The shipped consumer of `readBytes` (image and binary previews) and any write, search, or media route; the service is read-only. +- Write and search operations; the service is read-only. - Scopes other than `session` in the file address; the grammar leaves room, the provider serves one. diff --git a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md index 51de0ad5b6..b4ca420042 100644 --- a/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md @@ -25,15 +25,13 @@ Web 客户端需要从一个未必在 Host 机器上的浏览器查看会话工 `api/remotes` 和两个根聚合分别引用匹配的 Host/Client 叶子。包导出 `.`、`./client`、`./types`、`./typert` 和 `./remote`,web-app 中单个 `workspace-files` 条目供应两面。Client 插件注入 `['resources', 'remote', 'remote.workspaceFiles']`;资源模型直接从协议包取结果类型,Sidebar 参数声明归文本预览,因此 Client 编译图不再反向依赖 Remote 装配或右栏 UI。 -### `workspaceFiles` Remote 命名空间 +### `workspaceFiles` 文件操作 -每个 Host 方法首参都是 `WorkspaceFileScope`。Gateway 从线路上的 Session 身份解析它:优先读取 live Session header,cold Session 则只调用 `SessionPersistence.stat`;不会激活 Agent、读取事件正文或回退到父 Session。scope 携带所选 Session id 及其 `cwd`,仅当该 header 没有 `cwd` 时才使用沙箱策略的部署根。Client 传入 Session id,从不自行命名根。七个签名照 `src/index.ts` 的声明: +每个 Host 方法首参都是 `WorkspaceFileScope`。`workspaceFileScope` Gateway lookup 解析 Session 身份。它优先读取 live Session header,cold Session 则只调用 `SessionPersistence.stat`;不会激活 Agent、读取事件正文或回退到父 Session。scope 携带所选 Session id 及其 `cwd`,仅当该 header 没有 `cwd` 时才使用沙箱策略的部署根。Client 传入 Session id,从不自行命名根。五个签名照 `src/index.ts` 的声明: ```ts ignore-check @Remote async read(workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise -@Remote async readBytes(workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise -@Remote async readAll(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise -@Remote async readRelated(workspaceFileScope: WorkspaceFileScope, path: string, relativePath: string, signal: AbortSignal): Promise +@Remote async readBytes(workspaceFileScope: WorkspaceFileScope, path: string, options: WorkspaceByteReadOptions, signal: AbortSignal): Promise @Remote async stat(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise @Remote async list(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise @Remote({ mode: 'stream' }) changes(workspaceFileScope: WorkspaceFileScope, signal: AbortSignal): AsyncIterable @@ -41,20 +39,20 @@ Web 客户端需要从一个未必在 Host 机器上的浏览器查看会话工 - **`stat`** 返回 `WorkspaceFileStat { absolutePath, version, bytes? }`:文件身份、不透明的新鲜度令牌,以及后端报得出时的大小。它只接受普通文件。 - **`read`** 返回一个行窗口 `WorkspaceFileText = WorkspaceFileStat & { offset, text, lines, eof }`;`lines` 计页内行数,使只含一个空行的页(`text: ''`、`lines: 1`)与越过文件末尾的页(`lines: 0`)可区分。`range.offset` 是 1 起算的首行,缺省 1;`range.limit` 是最多行数,缺省 `maxLines` 且不得超过。行以 `\n` 结束,末尾的 `\n` 终止最后一行而不是开启一空行;`text` 以 `\n` 连接本页各行且不带终止符;页含最后一行时 `eof` 为 true,越过末尾的 offset 返回 `eof` 为 true 的空页。切页器沿 `streamText` 前进,数过窗口前的行而不保留,把每个窗内片段先按 `maxBytes` 核准再缓冲,并在越过窗口的第一个字符处返回,因此任意大小的文件只花一页内存。页上的 `version` 与 `bytes` 来自流之前的那次 stat。 -- **`readBytes`** 返回一个原始字节窗口 `WorkspaceFileBytes = WorkspaceFileStat & { offset, data, eof }`。`range.offset` 是 0 起算的首字节,缺省 0;`range.length` 是最多字节数,缺省 `maxBytes` 且不得超过。`data` 为 base64,文件在窗内结束则短于 `length`,位于或越过末尾则为空;窗口含最后一个字节时 `eof` 为 true。不做任何解码,也不按二进制拒绝。`read` 按行分页、绝不按字节;字节窗口走 `readBytes`。 -- **`readAll` 与 `readRelated`** 在 `maxFileBytes` 上限内返回完整的 `WorkspaceFileBytes`。`readRelated` 从基准文件所在目录解析相对文件系统路径;Host 对两个文件执行相同的普通文件检查和后端读取权限。[Document Preview](2026-09-08-document-preview-operations.zh.md) 负责其加载与地址语义。 +- **`readBytes`** 返回原生字节、文件元数据、偏移量和 EOF。必填选项对象未传 `range` 时,在 `maxFileBytes` 上限内完整读取;传入时,在 `maxBytes` 上限内读取有界窗口。`range: {}` 使用零偏移和配置的窗口上限;窗口可读取超过完整文件上限的文件。[二进制传输决议](2026-09-17-workspace-file-binary-transfer.zh.md)负责 Remote 响应编码。 +- **`baseFile`** 独立于 `range` 选择目标解析方式:目标 `path` 必须为相对路径,从基准文件所在目录解析。Host 对两个文件执行普通文件检查,并保留后端读取权限。[Document Preview](2026-09-08-document-preview-operations.zh.md)负责内容加载与地址语义。 - **`list`** 返回 `WorkspaceDirectoryListing { path, entries, truncated }`:被列目录相对根的工作区路径(根为空串)、其直接子项按后端的稳定名序以 `{ name, type, size? }` 给出,以及 `maxEntries` 是否截断了列表。`type` 为 `file`、`directory` 或 `other`;符号链接子项报告其指向目标的类型,悬空者为 `other`,而打开这样的子项仍会在下文的链接关被拒。dotfile 照常列出,不做任何过滤。 - **`changes`** 产出 `WorkspaceFileWatchFrame`:在观察队列注册且工作区根解析完成后先发 `{ kind: 'ready' }`,随后为 `{ kind: 'change', change }`。载荷 `WorkspaceFileChange` 对存在的文件为 `{ absolutePath, version }`,对消失的文件为 `{ absolutePath, absent: true }`。来源是工作区根内的 `fs/observed`,不监视操作系统。首次拉取后的观察都会排队,包括根解析期间的观察;取消或插件释放会结束该代流。 ### 线路上的路径 -离开服务的路径词汇有两套,每个方法只用其中一套。`read`、`readBytes`、`readAll`、`readRelated`、`stat` 与 `changes` 以 `absolutePath` 命名文件:它在文件系统执行环境中、符号链接已解析的绝对路径(`ctx.fs.processPath(target)`),因此 Client 提供者按绝对路径把变更帧匹配到已打开的地址:Client 把地址路径原样交给 Host,并只按成功的 `stat.absolutePath` 绑定跟随者,不读取会话摘要的 cwd。`list` 说工作区路径——与其 `path` 参数相同的语法,绝对或相对根——因为其消费方是一棵以根为起点的树。该字段叫 `absolutePath` 而不叫 `url`,因为它不是资源地址;地址语法归 `dsh-util-workspace-path` 所有,与资源模型一并描述。`read`、`readBytes`、`readAll`、`readRelated`、`stat` 与 `list` 的输入路径是绝对路径或相对会话工作区根的路径,从不相对后端自己的 cwd。 +离开服务的路径词汇有两套,每个方法只用其中一套。`read`、`readBytes`、`stat` 与 `changes` 以 `absolutePath` 命名文件:它在文件系统执行环境中、符号链接已解析的绝对路径(`ctx.fs.processPath(target)`),因此 Client 提供者按绝对路径把变更帧匹配到已打开的地址:Client 把地址路径原样交给 Host,并只按成功的 `stat.absolutePath` 绑定跟随者,不读取会话摘要的 cwd。`list` 说工作区路径——与其 `path` 参数相同的语法,绝对或相对根——因为其消费方是一棵以根为起点的树。该字段叫 `absolutePath` 而不叫 `url`,因为它不是资源地址;地址语法归 `dsh-util-workspace-path` 所有,与资源模型一并描述。`read`、`readBytes`、`stat` 与 `list` 的输入路径是绝对路径或相对会话工作区根的路径,从不相对后端自己的 cwd;带 `baseFile` 的 `readBytes` 从基准文件所在目录解析目标。 `version` 是消费者只比较是否相等、从不解析的不透明字符串:本地后端由设备、inode、大小及纳秒级 mtime 与 ctime 导出,因此内容不变的重写也会改变它。`offset` 在 `read` 上指行、在 `readBytes` 上指字节;两套单位从不混用,二者的 `eof` 都表示窗口到达了文件末尾。 ### 文件检查与工作区包含 -`read`、`readBytes`、`readAll`、`readRelated` 与 `stat` 共享普通文件检查,之后依赖文件系统后端的读取权限。`list` 共享路径检查,但还会检查工作区包含关系;`changes` 则把观察过滤到工作区根内。服务执行以下检查: +`read`、`readBytes` 与 `stat` 共享普通文件检查,之后依赖文件系统后端的读取权限。`list` 共享路径检查,但还会检查工作区包含关系;`changes` 则把观察过滤到工作区根内。服务执行以下检查: 1. **路径本身。** `lstat` 在跟随任何东西之前检查路径:缺失路径为 `not-found`;符号链接——不论指向哪里,包括指回工作区内——对文件方法为 `not-regular-file`(kind 为 `symlink`),对 `list` 为 `not-directory`。空路径是 `gateway/bad-request`。 2. **`list` 的工作区包含。** 目录解析为目标,由 `ctx.fs.contains(root, target)` 判定,其中 `root` 是从所选 Session header 解析出的 `WorkspaceFileScope.workspaceRoot`。`..` 爬出或根外绝对目录为 `outside-workspace`。`changes` 对观察到的目标使用相同的后端包含判定。 @@ -73,7 +71,7 @@ Web 客户端需要从一个未必在 Host 机器上的浏览器查看会话工 | `workspace-file/outside-workspace` | `list` 的目标不在工作区根内 | `{ path }` | | `workspace-file/too-large` | 一页文本或字节窗口超过 `maxBytes`,或全文读取超过 `maxFileBytes` | `{ path, limit }` | | `workspace-file/not-text` | 到页末为止的非法 UTF-8,或样本或页内的 NUL 字节(仅 `read`) | `{ path }` | -| `workspace-file/not-regular-file` | 对非普通文件执行 `read`、`readBytes`、`readAll`、`readRelated` 或 `stat` | `{ path, kind: 'directory' \| 'symlink' \| 'other' }` | +| `workspace-file/not-regular-file` | 对非普通文件执行 `read`、`readBytes` 或 `stat` | `{ path, kind: 'directory' \| 'symlink' \| 'other' }` | | `workspace-file/not-directory` | 对非目录执行 `list` | `{ path, kind: 'file' \| 'symlink' \| 'other' }` | | `workspace-file/unsupported-address` | Client 铸出:本提供者无法服务的资源地址 | `{ address }` | | `workspace-file/unknown-workspace` | Client 铸出:不携带 Session 的 `absolute` 地址 | `{ address }` | @@ -109,7 +107,7 @@ Client 导出向 `ctx.resources` 注册一个 `ResourceProvider<'file'>`,存 ### 相关记录 -[资源模型](2026-09-05-client-resource-model.zh.md)拥有 `ctx.resources`、`useResource`、`dsh-resource:///…` 地址语法以及"每个地址一份资源"的推理;[文本预览与文件树](../feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md)是 `read`、`list` 与 `file` 提供者随包交付的消费方;[右侧 Sidebar 停靠基础设施](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)是它们打开进去的界面;[工作区文件链接](../feature/2026-07-31-web-workspace-file-links.zh.md)是经 HTTP 供文件被否决之处。任何在这套体系上扩展的人都经 `remote.workspaceFiles` 触达同样的七个方法、经 `useResource<'file'>` 触达同样的 `file` 资源;线路类型以 `@deepseek-ai/dsh-api-workspace-files/types` 发布。[工作区文件读取权限](2026-09-09-workspace-file-read-authority.zh.md)负责 Host 读取权限与 HTML 安全取舍;[Document Preview](2026-09-08-document-preview-operations.zh.md)负责内容加载和逐 tab 新鲜度。 +[资源模型](2026-09-05-client-resource-model.zh.md)拥有 `ctx.resources`、`useResource`、`dsh-resource:///…` 地址语法以及"每个地址一份资源"的推理;[文本预览与文件树](../feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md)是 `read`、`list` 与 `file` 提供者随包交付的消费方;[右侧 Sidebar 停靠基础设施](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)是它们打开进去的界面;[工作区文件链接](../feature/2026-07-31-web-workspace-file-links.zh.md)是经 HTTP 供文件被否决之处。任何在这套体系上扩展的人都经 `remote.workspaceFiles` 触达同样的五个方法、经 `useResource<'file'>` 触达同样的 `file` 资源;线路类型以 `@deepseek-ai/dsh-api-workspace-files/types` 发布。[工作区文件读取权限](2026-09-09-workspace-file-read-authority.zh.md)负责 Host 读取权限与 HTML 安全取舍;[Document Preview](2026-09-08-document-preview-operations.zh.md)负责内容加载和逐 tab 新鲜度。 ## Alternatives considered @@ -117,7 +115,7 @@ Client 导出向 `ctx.resources` 注册一个 `ResourceProvider<'file'>`,存 **带有反向 UI 依赖的双面包。** 拆包选择源于 `api/remotes` 引用 Client 叶子后形成的两条工程引用环:资源模型为了结果类型引用 Remote 装配,文件提供者为了 Sidebar 参数表引用右栏 UI。TypeScript 以 `TS6202` 拒绝这些环。[双面包组织](2026-09-07-workspace-files-dual-face-package.zh.md)取代拆包选择:结果类型直接取自协议包,Sidebar 参数注册移至文本预览;保留两个根聚合中的显式编译入口。 -**经 HTTP 供工作区文件。** 已被[工作区文件链接](../feature/2026-07-31-web-workspace-file-links.zh.md)以 origin 理由否决且未重议:`read` 与 `readBytes` 经认证的 Remote 载体传送纯文本与 base64,因此不供文档、不铸 URL,也不产生 origin 问题。 +**提供可导航的工作区文档。** 因源隔离问题不采用;[二进制传输](2026-09-17-workspace-file-binary-transfer.zh.md)返回 multipart 数据,HTML 仍隔离在 Blob iframe 中。 **文件读取采用“日志可达”或工作区包含授权。** 唯一把文件内容送过线路的先例——命令附件——只授权出现在会话日志里的文件,这会排除手输路径;工作区包含则会排除 Session 后端其他位置的可读文件。[工作区文件读取权限](2026-09-09-workspace-file-read-authority.zh.md)改为以后端读取决策为准,只对工作区形态的操作保留包含限制。 @@ -138,14 +136,14 @@ Client 导出向 `ctx.resources` 注册一个 `ResourceProvider<'file'>`,存 - 变更帧只报告 agent 自己的操作。用户编辑器、shell 或子进程改动的文件不产生帧;agent 仅仅读取一个被别处改动的文件却会产生帧,因为读取观察到了新版本。 - 文件类型检查先于后端读取,`list` 也先报种类再报根外位置。页的 `version` 可能落后内容一次写入,停滞的 `changes` 消费者会让 Host 内存增长,因为一代流的队列无界;每一条都是包 README 记录在册的已知取舍。 - `file` 资源推送变更而非内容,因此预览不靠载荷就得知文件已更新并读取它想要的页;失败的打开继续跟随地址,因此 agent 创建该文件时 tab 无需用户动作即恢复正常。 -- `readBytes` 尚无随包交付的消费方;Document Preview 对整文件格式使用 `readAll`。 +- Office 授权探测使用带单字节 `range` 的 `readBytes`;Document Preview 对整文件格式使用同一方法并省略 `range`。 ## Testing -`packages/api/workspace-files/tests` 中的 Host spec 覆盖 live 与 cold subagent Session 的 header-only scope 解析、部署 fallback、缺失身份与 lookup 释放;分页读取(整文件、嵌套路径、空文件、多字节 UTF-8、行窗口边界、缺省与拒绝的 limit、保留回车);字节窗口(缺省、中段与尾窗、越界与空文件、base64 往返、版本、上限、坏范围以及无大小时的 `eof`);`stat`;工作区外读取及后端拒绝;`list` 的包含、截断、符号链接与 `not-directory`;以及由 `fs/observed` 驱动并按根过滤的 `changes`。Client spec 覆盖提供者帧、变更流、不支持地址及注册与释放。`fs/fs` 与 `fs-local` spec 钉住 `readByteRange`;`dsh-util-workspace-path` spec 钉住文件地址语法。connection fixture 为 web e2e 套件提供 `stat`、分页 `read`、`list` 与一帧可选启用的 `changes`。 +`packages/api/workspace-files/tests` 中的 Host spec 覆盖 live 与 cold subagent Session 的 header-only scope 解析、部署 fallback、缺失身份与 lookup 释放;分页读取(整文件、嵌套路径、空文件、多字节 UTF-8、行窗口边界、缺省与拒绝的 limit、保留回车);字节窗口(缺省、中段与尾窗、越界与空文件、`Uint8Array` 往返、版本、上限、坏范围以及无大小时的 `eof`);`stat`;工作区外读取及后端拒绝;`list` 的包含、截断、符号链接与 `not-directory`;以及由 `fs/observed` 驱动并按根过滤的 `changes`。Client spec 覆盖提供者帧、变更流、不支持地址及注册与释放。`fs/fs` 与 `fs-local` spec 钉住 `readByteRange`;`dsh-util-workspace-path` spec 钉住文件地址语法。connection fixture 为 web e2e 套件提供 `stat`、分页 `read`、`list` 与一帧可选启用的 `changes`。 ## Deferred - 给 `changes` 一代流的队列加上限。 -- `readBytes` 随包交付的消费方(图片与二进制预览)以及任何写入、搜索或媒体路由;本服务只读。 +- 写入和搜索操作;本服务只读。 - 文件地址中 `session` 之外的作用域;语法留有余地,提供者只服务一个。 diff --git a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml index 414fda0806..ecb554c14d 100644 --- a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.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 .agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md -2026-09-08-document-preview-operations.md: be3a835a6296cb28d9a90c5c5e8b9bf7367598c2 -2026-09-08-document-preview-operations.zh.md: efb87e16cc126001c1a6eb2bf938124d7e00044a +2026-09-08-document-preview-operations.md: 0b90c17ba94d0c7cd30afb0a6e6a033f8f12d0df +2026-09-08-document-preview-operations.zh.md: ec9c208c97dfe75afdb0915c655d9c1c7b4d42ff diff --git a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md index be3a835a62..0b90c17ba9 100644 --- a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md +++ b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md @@ -16,9 +16,9 @@ Document Preview separates resource observation from content reads. The [resourc Readable files use `dsh-resource://file/session//`. The path may be workspace-relative or absolute; an encoded absolute path retains its leading slash. `fileAddressFor` always emits this Session-address form. The provider and Preview RPC take the Session only from that address, never from the current selection, first holder, or owning tab. A Session-less `absolute` URI cannot be read; the provider reports `workspace-file/unknown-workspace`. Session authorization is a file-protocol rule, not an additional Resource identity. -[Document Preview](../../../../packages/client/ui-sidebar-documentpreview/README.md) owns format selection and loading policy. Metadata registers with `ctx.documentPreviews`; components register separately into the keyed `sidebar.right.tab.document` Slot. Extension registrations precede builtins, then longer suffixes and registration order decide. The toolbar lists supported alternatives and remembers a manual choice per tab. Plain text remains available for unknown extensions and text-compatible renderers. Registered binary suffixes determine text compatibility independently of loading mode; HTML and SVG remain outside those suffixes and retain source viewing. A single candidate renders no viewer control. Registered binary suffixes omit plain text; known binary suffixes without a renderer show an unsupported state without reading the file ([sidebar preview polish](../feature/2026-09-11-sidebar-document-preview-polish.md)). The child receives accumulated text or complete native bytes, the original resource address, and the standard `useResource` and `useTabInfo` hooks. Preview calls existing `read`, `readAll`, and `readRelated` through ordinary injection and decodes bytes in its own `rpc.ts`. Refresh remains per tab, with no resource reload, shared `changed` acknowledgement, extra resource wrapper, or content Session. +[Document Preview](../../../../packages/client/ui-sidebar-documentpreview/README.md) owns format selection and loading policy. Metadata registers with `ctx.documentPreviews`; components register separately into the keyed `sidebar.right.tab.document` Slot. Extension registrations precede builtins, then longer suffixes and registration order decide. The toolbar lists supported alternatives and remembers a manual choice per tab. Plain text remains available for unknown extensions and text-compatible renderers. Registered binary suffixes determine text compatibility independently of loading mode; HTML and SVG remain outside those suffixes and retain source viewing. A single candidate renders no viewer control. Registered binary suffixes omit plain text; known binary suffixes without a renderer show an unsupported state without reading the file ([sidebar preview polish](../feature/2026-09-11-sidebar-document-preview-polish.md)). The child receives accumulated text or complete native bytes, the original resource address, and the standard `useResource` and `useTabInfo` hooks. Preview calls `ctx.remote.workspaceFiles.read` for text and `ctx.remote.workspaceFiles.readBytes` for native bytes, with `baseFile` for related resources. Refresh remains per tab, with no resource reload, shared `changed` acknowledgement, extra resource wrapper, or content Session. -Markdown and code reuse the incremental primitives with cumulative paged text. HTML, PDF, and images read complete `Uint8Array` data; Host transport remains base64. Published buffers are borrowed read-only and never persist into layout or Session JSON. PDF.js runs in an owned Worker with version-matched bundled font and decoder data, and copies input before transfer to preserve Preview's retained buffer. With [Developer tools](../feature/2026-09-17-developer-tools-settings.md) enabled, HTML runs in a Blob iframe with `sandbox="allow-scripts"`, without same-origin, popup, form, download, or top-navigation privileges. The browser retains its normal external-network rules. Bounded static local JS/CSS reads stay in the parent; the opaque frame creates its own asset Blobs, because it cannot load parent-origin Blobs. PNG, JPEG, GIF, WebP, BMP, ICO, and SVG use image-specific Blob URLs in an `` static-image context. An image wider than the pane scales down to its width at its aspect ratio; a smaller image keeps its intrinsic CSS-pixel dimensions centred by auto margins, and a taller image extends the shared scroller's vertical range ([sidebar preview polish](../feature/2026-09-11-sidebar-document-preview-polish.md)). The renderer provides no zoom or drag-to-pan. SVG markup never enters the application DOM or an iframe, so scripts remain inert and cannot reach the parent page. Replacing HTML or an image revokes its root Blob URL. +Markdown and code reuse the incremental primitives with cumulative paged text. HTML, PDF, and images read complete `Uint8Array` data; Host transport uses the [binary workspace file transfer](2026-09-17-workspace-file-binary-transfer.md). Published buffers are borrowed read-only and never persist into layout or Session JSON. PDF.js runs in an owned Worker with version-matched bundled font and decoder data, and copies input before transfer to preserve Preview's retained buffer. With [Developer tools](../feature/2026-09-17-developer-tools-settings.md) enabled, HTML runs in a Blob iframe with `sandbox="allow-scripts"`, without same-origin, popup, form, download, or top-navigation privileges. The browser retains its normal external-network rules. Bounded static local JS/CSS reads stay in the parent; the opaque frame creates its own asset Blobs, because it cannot load parent-origin Blobs. PNG, JPEG, GIF, WebP, BMP, ICO, and SVG use image-specific Blob URLs in an `` static-image context. An image wider than the pane scales down to its width at its aspect ratio; a smaller image keeps its intrinsic CSS-pixel dimensions centred by auto margins, and a taller image extends the shared scroller's vertical range ([sidebar preview polish](../feature/2026-09-11-sidebar-document-preview-polish.md)). The renderer provides no zoom or drag-to-pan. SVG markup never enters the application DOM or an iframe, so scripts remain inert and cannot reach the parent page. Replacing HTML or an image revokes its root Blob URL. PDF.js's official TextLayerBuilder owns selection boundaries and copy normalization over the width-fitted canvas, with shared page cleanup and a component-owned resize observer. Responsive sizing uses the CSS `scale` property independently of PDF.js's page rotation and translation transforms. Its end-of-content marker and stacking rules constrain selection in blank regions; line-break highlighting is suppressed. Per-page cancellation uses the builder's cleanup rather than aborting the first page's signal, because the official selection listeners are shared across pages. @@ -28,7 +28,7 @@ PDF.js's official TextLayerBuilder owns selection boundaries and copy normalizat **Methods attached to an Iterator or its values.** This conflates observation with commands and repeats capability identity in data frames. Frames carry data and failures; explicit Preview RPC callbacks perform reads. -**A core public-projection factory, or the same assembly inside `open`.** Separate stream values, operations bundles, and public interfaces add assembly without another current consumer that needs it. Preview's shared RPC adapter already keeps Session decoding and base64 out of renderers. Resource offers no provider-agnostic command interface or opening-bound command lifetime; adding either needs consumer evidence beyond file preview. +**A core public-projection factory, or the same assembly inside `open`.** Separate stream values, operations bundles, and public interfaces add assembly without another current consumer that needs it. Preview's shared RPC adapter already keeps Session addressing and byte transport out of renderers. Resource offers no provider-agnostic command interface or opening-bound command lifetime; adding either needs consumer evidence beyond file preview. **UI Session as extra Resource identity, or authorization from the first holder or current selection.** A retained tab can belong to a different Session from the selected one, and the UI location does not identify the addressed file. Encoding the required Session in the file address preserves Host authorization while letting all readers of one address share observation. diff --git a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md index efb87e16cc..ec9c208c97 100644 --- a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md @@ -16,9 +16,9 @@ Document Preview 将资源观察与内容读取分开。[资源模型](2026-09-0 可读取的文件使用 `dsh-resource://file/session//`。路径可以相对工作区,也可以是绝对路径;编码后的绝对路径保留前导斜杠。`fileAddressFor` 始终生成这种 Session 地址。提供方与 Preview RPC 只从该地址取 Session,不取当前选择、首个持有者或 tab 所属 Session。不带 Session 的 `absolute` URI 无法读取;提供方报告 `workspace-file/unknown-workspace`。Session 授权是文件协议规则,不是额外的 Resource 身份。 -[Document Preview](../../../../packages/client/ui-sidebar-documentpreview/README.zh.md) 负责格式选择和加载策略。元数据通过 `ctx.documentPreviews` 注册;组件单独注册到 keyed `sidebar.right.tab.document` Slot。扩展注册优先于内置注册,其次比较后缀长度和注册顺序。工具栏列出受支持的候选,按 tab 记住手动选择。未知扩展名及文本兼容的渲染器仍可使用纯文本。文本兼容性由注册的二进制后缀决定,与加载方式无关;HTML 和 SVG 不属于二进制后缀,保留源码查看。只有一个候选时不显示查看器控件。注册声明为二进制的后缀不提供纯文本;已知二进制后缀没有注册渲染器时不发起读取,并显示不支持预览的空态([侧边栏预览打磨](../feature/2026-09-11-sidebar-document-preview-polish.zh.md))。子组件收到累积文本或完整原生字节、原始资源地址,以及标准 `useResource` 和 `useTabInfo` 钩子。Preview 经普通注入调用既有 `read`、`readAll` 与 `readRelated`,在自己的 `rpc.ts` 解码字节。刷新仍按 tab 独立进行,不引入资源 reload、共享 `changed` 确认、额外资源包装层或内容 Session。 +[Document Preview](../../../../packages/client/ui-sidebar-documentpreview/README.zh.md) 负责格式选择和加载策略。元数据通过 `ctx.documentPreviews` 注册;组件单独注册到 keyed `sidebar.right.tab.document` Slot。扩展注册优先于内置注册,其次比较后缀长度和注册顺序。工具栏列出受支持的候选,按 tab 记住手动选择。未知扩展名及文本兼容的渲染器仍可使用纯文本。文本兼容性由注册的二进制后缀决定,与加载方式无关;HTML 和 SVG 不属于二进制后缀,保留源码查看。只有一个候选时不显示查看器控件。注册声明为二进制的后缀不提供纯文本;已知二进制后缀没有注册渲染器时不发起读取,并显示不支持预览的空态([侧边栏预览打磨](../feature/2026-09-11-sidebar-document-preview-polish.zh.md))。子组件收到累积文本或完整原生字节、原始资源地址,以及标准 `useResource` 和 `useTabInfo` 钩子。Preview 通过 `ctx.remote.workspaceFiles.read` 读取文本,通过 `ctx.remote.workspaceFiles.readBytes` 读取原生字节,关联资源使用 `baseFile`。刷新仍按 tab 独立进行,不引入资源 reload、共享 `changed` 确认、额外资源包装层或内容 Session。 -Markdown 和代码通过累积的分页文本复用增量渲染原语。HTML、PDF 和图片读取完整 `Uint8Array` 数据;Host 传输保持 base64。发布后的缓冲区只读借用,绝不持久化进布局或 Session JSON。PDF.js 在自有 Worker 中运行,字体和解码数据以相同版本随包发布,转移输入前先复制,以保留 Preview 的缓冲区。开启[开发者工具](../feature/2026-09-17-developer-tools-settings.zh.md)时,HTML 在 Blob iframe 中运行,设置 `sandbox="allow-scripts"`,不授予同源、弹窗、表单、下载或顶层导航权限。浏览器保持正常的外部网络规则。有上限的静态本地 JS/CSS 读取由父页面负责;不透明源 iframe 创建自己的资源 Blob,因为它不能加载父源创建的 Blob。PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 使用图片专用 Blob URL,在 `` 静态图片上下文中渲染。比面板宽的图片按纵横比缩小到面板宽度;较小的图片保留固有 CSS 像素尺寸并由 auto margin 居中,较高的图片扩展共享滚动区的纵向范围([侧边栏预览打磨](../feature/2026-09-11-sidebar-document-preview-polish.zh.md))。渲染器不提供缩放或拖拽平移。SVG 标记绝不进入应用 DOM 或 iframe,因此脚本保持不可执行,也无法访问父页面。替换 HTML 或图片时会撤销其根 Blob URL。 +Markdown 和代码通过累积的分页文本复用增量渲染原语。HTML、PDF 和图片读取完整 `Uint8Array` 数据;Host 传输使用[工作区文件二进制传输](2026-09-17-workspace-file-binary-transfer.zh.md)。发布后的缓冲区只读借用,绝不持久化进布局或 Session JSON。PDF.js 在自有 Worker 中运行,字体和解码数据以相同版本随包发布,转移输入前先复制,以保留 Preview 的缓冲区。开启[开发者工具](../feature/2026-09-17-developer-tools-settings.zh.md)时,HTML 在 Blob iframe 中运行,设置 `sandbox="allow-scripts"`,不授予同源、弹窗、表单、下载或顶层导航权限。浏览器保持正常的外部网络规则。有上限的静态本地 JS/CSS 读取由父页面负责;不透明源 iframe 创建自己的资源 Blob,因为它不能加载父源创建的 Blob。PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 使用图片专用 Blob URL,在 `` 静态图片上下文中渲染。比面板宽的图片按纵横比缩小到面板宽度;较小的图片保留固有 CSS 像素尺寸并由 auto margin 居中,较高的图片扩展共享滚动区的纵向范围([侧边栏预览打磨](../feature/2026-09-11-sidebar-document-preview-polish.zh.md))。渲染器不提供缩放或拖拽平移。SVG 标记绝不进入应用 DOM 或 iframe,因此脚本保持不可执行,也无法访问父页面。替换 HTML 或图片时会撤销其根 Blob URL。 PDF.js 官方 TextLayerBuilder 在适配宽度的 canvas 上负责选择边界和复制规范化,共享页面清理,并使用由组件拥有的 resize observer。响应式尺寸适配使用独立的 CSS `scale` 属性,与 PDF.js 的页面旋转和平移变换组合。其内容结束标记和堆叠规则限制空白区域中的选择;换行高亮被抑制。逐页取消使用 builder 的清理操作,而不 abort 第一页的信号,因为官方选择监听器跨页面共享。 @@ -28,7 +28,7 @@ PDF.js 官方 TextLayerBuilder 在适配宽度的 canvas 上负责选择边界 **把方法挂到 Iterator 或其值上。** 这会混淆观察与命令,并在数据帧中重复能力身份。帧携带数据和失败;显式 Preview RPC 回调负责读取。 -**核心公开投影工厂,或在 `open` 内做同样的组装。** 分开的流值、operations 组合与公开接口增加了组装步骤,没有另一个当前消费方需要它。Preview 的共享 RPC 适配已让渲染器无需解码 Session 和 base64。Resource 不提供与提供方无关的命令接口,也不提供绑定于打开实例的命令生命周期;增加任一种都需要文件预览之外的消费方证据。 +**核心公开投影工厂,或在 `open` 内做同样的组装。** 分开的流值、operations 组合与公开接口增加了组装步骤,没有另一个当前消费方需要它。Preview 的共享 RPC 适配已让渲染器无需处理 Session 寻址和字节传输。Resource 不提供与提供方无关的命令接口,也不提供绑定于打开实例的命令生命周期;增加任一种都需要文件预览之外的消费方证据。 **把 UI Session 作为额外 Resource 身份,或由首个持有者、当前选择决定授权。** 保留的 tab 可以属于不同于当前选择的 Session,UI 所在位置也不能标识地址指向的文件。将所需 Session 编入文件地址,既保留 Host 授权,也让同地址的所有读者共享观察。 diff --git a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.i18n.yaml index 97cdb07d3f..eed28e3666 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.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 .agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md -2026-09-09-workspace-file-read-authority.md: d1a5b9d9634381cb74b17651c67f2b701402ff1c -2026-09-09-workspace-file-read-authority.zh.md: f8b0fae4325a90548c6b9dc33ac46b17248b04e7 +2026-09-09-workspace-file-read-authority.md: 140816e8c48a6628133cf9208d5b48545e2e5eaf +2026-09-09-workspace-file-read-authority.zh.md: 75ffee32c40930c459018ab0fde42d5324371ba8 diff --git a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md index d1a5b9d963..140816e8c4 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md +++ b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md @@ -10,11 +10,11 @@ Workspace Files serves both file content and workspace navigation. Applying work ## Decision -`read`, `readBytes`, `readAll`, `readRelated`, and `stat` inherit the addressed Session filesystem backend's read authority. The workspace root is the base for relative input paths, not a read boundary; absolute paths and relative paths that leave the workspace are readable when the backend allows them. The service still requires regular files, refuses symlinks, and applies its text and byte caps. +`read`, `readBytes`, and `stat` inherit the addressed Session filesystem backend's read authority. The workspace root is the base for relative input paths, not a read boundary; absolute paths and relative paths that leave the workspace are readable when the backend allows them. The service still requires regular files, refuses symlinks, and applies its text and byte caps. `list` and `changes` remain workspace-scoped because they expose workspace navigation and observation rather than a named file read. `list` rejects a directory outside the root, and `changes` filters observations through the backend's workspace-containment predicate. -`readRelated` resolves a relative path from the base file's directory. A `..` path may therefore read JavaScript or CSS outside the workspace when the Session backend permits it. With [Developer tools](../feature/2026-09-17-developer-tools-settings.md) enabled, Document Preview packages bounded, statically declared local scripts and stylesheets into an HTML Blob iframe with `sandbox="allow-scripts"`; the opaque origin blocks parent access, but the browser retains normal network access. This exposure is an intentional security trade-off for rendering static generated HTML. +`readBytes` with `baseFile` resolves a relative path from the base file's directory. A `..` path may therefore read JavaScript or CSS outside the workspace when the Session backend permits it. With [Developer tools](../feature/2026-09-17-developer-tools-settings.md) enabled, Document Preview packages bounded, statically declared local scripts and stylesheets into an HTML Blob iframe with `sandbox="allow-scripts"`; the opaque origin blocks parent access, but the browser retains normal network access. This exposure is an intentional security trade-off for rendering static generated HTML. The [Workspace Files service](2026-09-05-workspace-files-service.md) owns paging, file checks, listing, and observation. [Document Preview](2026-09-08-document-preview-operations.md) owns which related files are packaged and the iframe sandbox. diff --git a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.zh.md b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.zh.md index f8b0fae432..75ffee32c4 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.zh.md @@ -10,11 +10,11 @@ Workspace Files 同时提供文件内容与工作区导航。对所有操作应 ## Decision -`read`、`readBytes`、`readAll`、`readRelated` 与 `stat` 继承被寻址 Session 的文件系统后端读取权限。工作区根是输入相对路径的基准,而不是读取边界;只要后端允许,就可以读取绝对路径和离开工作区的相对路径。服务仍要求普通文件、拒绝符号链接,并应用文本和字节上限。 +`read`、`readBytes` 与 `stat` 继承被寻址 Session 的文件系统后端读取权限。工作区根是输入相对路径的基准,而不是读取边界;只要后端允许,就可以读取绝对路径和离开工作区的相对路径。服务仍要求普通文件、拒绝符号链接,并应用文本和字节上限。 `list` 与 `changes` 仍限于工作区,因为它们暴露工作区导航和观察,而不是读取一个具名文件。`list` 拒绝根外目录,`changes` 通过后端的工作区包含判定过滤观察。 -`readRelated` 从基准文件所在目录解析相对路径。因此,只要 Session 后端允许,`..` 路径就可以读取工作区外的 JavaScript 或 CSS。开启[开发者工具](../feature/2026-09-17-developer-tools-settings.zh.md)时,Document Preview 把有界、静态声明的本地脚本与样式表打包进带 `sandbox="allow-scripts"` 的 HTML Blob iframe;不透明源阻止访问父应用,但浏览器保留正常网络访问。这种暴露是为渲染静态生成 HTML 而有意接受的安全取舍。 +带 `baseFile` 的 `readBytes` 从基准文件所在目录解析相对路径。因此,只要 Session 后端允许,`..` 路径就可以读取工作区外的 JavaScript 或 CSS。开启[开发者工具](../feature/2026-09-17-developer-tools-settings.zh.md)时,Document Preview 把有界、静态声明的本地脚本与样式表打包进带 `sandbox="allow-scripts"` 的 HTML Blob iframe;不透明源阻止访问父应用,但浏览器保留正常网络访问。这种暴露是为渲染静态生成 HTML 而有意接受的安全取舍。 [Workspace Files 服务](2026-09-05-workspace-files-service.zh.md)负责分页、文件检查、列举和观察。[Document Preview](2026-09-08-document-preview-operations.zh.md)负责选择要打包的关联文件及 iframe sandbox。 diff --git a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.i18n.yaml index 9947e91ff2..b40fa370ec 100644 --- a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.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 .agents/notes/implemented/architecture/2026-09-11-node-office-kit.md -2026-09-11-node-office-kit.md: b8e94bf6b392edf7931346400fda9ca5d3416188 -2026-09-11-node-office-kit.zh.md: 41b84f26c8150db90f09e4ae2b01abb3dddfdc6d +2026-09-11-node-office-kit.md: 132ac8b3dd709f9f16254a5569dec59f01d29fda +2026-09-11-node-office-kit.zh.md: c7bdab2322766c42cfee4092f158d7b6b530e875 diff --git a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.md b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.md index b8e94bf6b3..132ac8b3dd 100644 --- a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.md +++ b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.md @@ -24,7 +24,7 @@ DSH exports raster images at configurable resolution, defaulting to 192 DPI for The [Office viewer](../../../../packages/client/ui-sidebar-documentpreview/README.md#office-preview) lives under Document Preview’s `client/office/` directory, alongside the loading lifecycle, PDF body, and reader types it uses. Keeping these components in one package removes an independent UI boot entry without creating cross-plugin runtime imports. Its bounded cache validates authorized source metadata, shares pending conversions between readers, cancels only when the final reader leaves, excludes failures, and clears on connection reset. Conversion starts when a user opens a preview. Missing declared font families accompany the PDF and are available from the document toolbar’s warning icon; font-table inventories and unrelated engine defaults are not warnings. The shared preview entry’s `office` cache settings use the existing page-global injection channel because the module boot graph carries package identities, not Loader configuration. Reloading the page adopts updated YAML values. -Ordinary file reads and Office responses share `documentFileBytes()`, which decodes into one typed byte buffer rather than materializing a JavaScript element array from the binary string. Element-array expansion can exhaust the browser heap for a PDF that the configured Host limits permit. A child-process regression checks byte equality within a fixed heap, while the built browser scenario verifies the transport and PDF Worker together. Cache byte limits do not bound transient transport or viewer memory. +Office responses use `documentFileBytes()`, which decodes into one typed byte buffer rather than materializing a JavaScript element array from the binary string. Element-array expansion can exhaust the browser heap for a PDF that the configured Host limits permit. A child-process regression checks byte equality within a fixed heap, while the built browser scenario verifies the transport and PDF Worker together. Cache byte limits do not bound transient transport or viewer memory. The [kit ownership decision](2026-09-14-independent-libreoffice-kit.md) defines npm distribution and bundled offline conversion. diff --git a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.zh.md b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.zh.md index 41b84f26c8..c7bdab2322 100644 --- a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.zh.md @@ -24,7 +24,7 @@ DSH 按可配置分辨率导出栅格图片,默认 192 DPI,对应共享 PDF [Office 查看器](../../../../packages/client/ui-sidebar-documentpreview/README.zh.md#office-preview)位于文档预览的 `client/office/` 目录,与其使用的加载生命周期、PDF 正文和读取器类型同属一个包。这些组件放在同一包中,既减少一个独立 UI 启动入口,也无需跨插件运行时导入。其有界缓存校验已授权的源元数据,在读取方之间共享待完成转换,仅在最后一个读取方离开时取消,不缓存失败,并在连接重置时清空。用户打开预览时才开始转换。缺失的已声明字体族随 PDF 返回,可通过文档工具栏的警告图标查看;字体表清单与无关的引擎默认字体不构成警告。共享预览入口的 `office` 缓存设置复用页面全局注入通道,因为模块启动图携带包标识而不传递 Loader 配置。重新加载页面后采用更新的 YAML 值。 -普通文件读取与 Office 响应共享 `documentFileBytes()`,解码使用一个类型化字节缓冲区,不将二进制字符串物化为 JavaScript 元素数组。即使 PDF 符合 Host 配置的大小限制,元素数组展开也可能耗尽浏览器堆内存。子进程回归测试在固定堆容量内检查字节一致性,构建后的浏览器场景则一起验证传输和 PDF Worker。缓存字节限制不约束临时传输或查看器内存。 +Office 响应使用 `documentFileBytes()`,解码使用一个类型化字节缓冲区,不将二进制字符串物化为 JavaScript 元素数组。即使 PDF 符合 Host 配置的大小限制,元素数组展开也可能耗尽浏览器堆内存。子进程回归测试在固定堆容量内检查字节一致性,构建后的浏览器场景则一起验证传输和 PDF Worker。缓存字节限制不约束临时传输或查看器内存。 [kit 归属决策](2026-09-14-independent-libreoffice-kit.zh.md)定义 npm 分发和随应用打包的离线转换。 diff --git a/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.i18n.yaml new file mode 100644 index 0000000000..87ea138f6d --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.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 .agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md +2026-09-17-workspace-file-binary-transfer.md: 1cfffb4113619fba17479065bac6bb420f214d7d +2026-09-17-workspace-file-binary-transfer.zh.md: 1cacc2c294b979ed7e840c84293eb3f6421c6bcb diff --git a/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md new file mode 100644 index 0000000000..1cfffb4113 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md @@ -0,0 +1,31 @@ +# Agent Note: Binary workspace file transfer + +Status: implemented + +English | [中文](2026-09-17-workspace-file-binary-transfer.zh.md) + +## Problem + +Document previews need native bytes. Encoding file contents as base64 adds about one third to the payload before compression and requires browser decoding. A separate file Fetch route also duplicates the Gateway's method dispatch, Session lookup, and error handling. + +## Decision + +The [Remote method architecture](2026-08-02-typert-remote-method-calls.md) owns method dispatch and lifetime; this note defines binary success encoding and Client validation. The [workspace file service](2026-09-05-workspace-files-service.md) exposes one binary `readBytes` Remote. Its required options object independently selects a byte `range` and a `baseFile` for relative target resolution. Without `range`, it reads a complete file. This avoids separate method names for orthogonal choices while preserving bounded `fs.readBytes` and `fs.readByteRange` reads. + +Typert recursively recognizes `Uint8Array` in unary result types, including root values, optional fields, and containers. Generated result codecs provide `encode()` for subtrees whose types can contain bytes and `decode()` to validate the reconstructed value without iterating, copying, or freezing byte payloads; Client declarations narrow each byte buffer to `ArrayBuffer`. Gateway supplies the encoder to Connection, using identity for strict JSON results so they avoid recursive detection. Source-mode calls retain runtime byte detection. Connection owns standard `FormData` parts and preserves the RPC envelope and correlation id in JSON metadata; it does not depend on Typert reflection. An attachment table associates byte parts with paths through the JSON result; field names remain business-owned. The Client restores `Uint8Array` views over `Blob.arrayBuffer()` and Gateway delegates validation to the generated decoder. Ordinary results and errors retain JSON responses. Gateway owns method dispatch, Session lookup, cancellation, and mount lifetime; feature code needs no multipart reader or dedicated route. + +## Alternatives considered + +- Separate `readAll`, range, and related-file methods mix independent path and extent choices. One options object permits their combination without adding another method. +- A workspace-only Fetch route keeps binary transport out of Remote but requires feature-specific dispatch, Session lookup, and error decoding. +- A whole-result binary marker or a reserved `data` field couples transport to one business result. Type-directed codecs and attachment paths support independently named and nested fields without adding result-wide categories. +- A custom metadata prefix needs owned framing and length validation. FormData delegates those mechanics to the platform, at the cost of Blob copies. +- Metadata HTTP headers constrain long Unicode paths. Multipart fields keep paths in the body; HTML stays in an isolated Blob iframe rather than a navigable Host response. + +## Consequences + +Byte ranges retain only the requested bytes under `maxBytes`, independently of `maxFileBytes`. Complete reads retain a bounded whole file; this is not a streaming preview or zero-copy optimization. On HTTP disconnect, the bridge aborts the request signal and drains materialized response chunks without writing to the socket: cancelling Node multipart bodies can race their producer and cause an unhandled `ERR_INVALID_STATE` rejection. Office authorization probes use the same Remote with a one-byte range; converted PDFs remain base64 in the separate Office Remote and use its bounded decoder. Plugin callers migrate to `readBytes` options and stop decoding its data as base64. Binary arguments, events, and stream items remain unsupported; recursive types require acyclic runtime values. No Session event or persistence format changes. + +## Validation + +Workspace tests cover complete and ranged reads, combined base-file resolution, limits, Session lookup, cancellation, and binary RPC round trips. Connection and Gateway tests cover nested and multiple attachments, framing, correlation, malformed multipart, and cancelled or withdrawn calls; Typert tests cover recursive result codecs, Client declarations, and rejected binary inputs or streams. The built browser scenario checks raw PNG bytes plus HTML, PDF, image, and text previews. Local benchmarks compare full and ranged reads using identical synthetic files, and distinguish transport/decoding from the complete read path. diff --git a/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.zh.md b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.zh.md new file mode 100644 index 0000000000..1cacc2c294 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.zh.md @@ -0,0 +1,31 @@ +# Agent Note: 工作区文件二进制传输 + +Status: implemented + +[English](2026-09-17-workspace-file-binary-transfer.md) | 中文 + +## 问题 + +文档预览需要原生字节。将文件内容编码为 base64 会在压缩前使载荷增加约三分之一,并要求浏览器解码。独立的文件 Fetch 路由还会重复 Gateway 的方法分发、Session 查找和错误处理。 + +## 决策 + +[Remote 方法架构](2026-08-02-typert-remote-method-calls.zh.md)负责方法分发与生命周期;本记录规定二进制成功响应的编码及 Client 校验。[工作区文件服务](2026-09-05-workspace-files-service.zh.md)提供单一的二进制 `readBytes` Remote。其必填选项对象独立选择字节 `range` 和用于相对目标解析的 `baseFile`。未传 `range` 时读取完整文件。这避免为正交的选择设置不同方法名,同时保留有界的 `fs.readBytes` 和 `fs.readByteRange` 读取。 + +Typert 递归识别一元结果类型中的 `Uint8Array`,包括根值、可选字段和容器。生成的结果 codec 提供 `encode()` 处理类型可能包含字节的子树,并通过 `decode()` 校验还原后的值,不逐字节遍历、复制或冻结字节载荷;Client 声明将每个字节缓冲区限定为 `ArrayBuffer`。Gateway 将 encoder 交给 Connection,对 strict JSON 结果原值传递,从而避免递归识别。源码模式调用保留运行时字节识别。Connection 负责标准 `FormData` 部分,并在 JSON 元数据中保留 RPC 信封和关联 id,不依赖 Typert 反射。附件表将字节部分与 JSON 结果中的路径关联,字段名仍由业务拥有。Client 恢复基于 `Blob.arrayBuffer()` 的 `Uint8Array` 视图,Gateway 将校验交给生成的解码器。普通结果与错误继续使用 JSON 响应。Gateway 负责方法分发、Session 查找、取消及挂载生命周期;功能代码无需 multipart 读取器或专用路由。 + +## 考虑过的替代方案 + +- 分立的 `readAll`、范围和关联文件方法混合了路径与读取范围两个独立选择。单一选项对象支持组合,无需再增加方法。 +- 工作区专用 Fetch 路由让二进制传输独立于 Remote,但需要功能专属的方法分发、Session 查找与错误解码。 +- 整体结果的二进制标记或保留的 `data` 字段会将传输与某一种业务结果耦合。按类型生成的 codec 和附件路径支持独立命名及嵌套字段,无需新增整体结果分类。 +- 自定义元数据前缀需要自有的帧格式与长度校验。FormData 将这些机制交给平台,代价是 Blob 复制。 +- 元数据 HTTP 头会限制较长的 Unicode 路径。Multipart 字段将路径保留在正文中;HTML 仍置于隔离的 Blob iframe,不作为可导航的 Host 响应。 + +## 影响 + +字节范围仅保留 `maxBytes` 内的请求字节,不受 `maxFileBytes` 约束。完整读取保留有上限的整个文件;这不是流式预览或零复制优化。HTTP 连接断开后,桥接器中止请求信号,并排空已准备的响应块,不再写入 socket:取消 Node multipart 响应体可能与其生产方竞争,导致未处理的 `ERR_INVALID_STATE` 拒绝。Office 授权探测使用同一 Remote 的单字节范围;转换后的 PDF 仍通过独立的 Office Remote 传输 base64,并使用其有界解码器。插件调用方迁移到 `readBytes` 选项,并停止将其 data 按 base64 解码。仍不支持二进制参数、事件和流条目;递归类型要求运行时值无环。不改变 Session 事件或持久化格式。 + +## 验证 + +Workspace 测试覆盖完整与分段读取、基准文件解析组合、上限、Session 查找、取消以及二进制 RPC 往返。Connection 和 Gateway 测试覆盖嵌套及多附件、帧格式、关联关系、畸形 multipart,以及取消或撤销的调用;Typert 测试覆盖递归结果 codec、Client 声明,以及对二进制输入和流的拒绝。构建后的浏览器场景验证原始 PNG 字节以及 HTML、PDF、图片和文本预览。本机 benchmark 使用相同合成文件比较完整与分段读取,并区分传输/解码和完整读取路径。 diff --git a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml index 702e3bf1fc..0d328978e1 100644 --- a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.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 .agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md -2026-09-05-sidebar-text-preview-and-file-tree.md: 8ddb1a336307011d8f6ce9bbe927f00642a83e60 -2026-09-05-sidebar-text-preview-and-file-tree.zh.md: 294a2b456008837882f7f82e55e8e9e435254554 +2026-09-05-sidebar-text-preview-and-file-tree.md: e978043545b7f172f2b67053fe44b5936ea9b529 +2026-09-05-sidebar-text-preview-and-file-tree.zh.md: 088d4a58c973843ac5085cfaa1ca9980387bcc8f diff --git a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md index 8ddb1a3363..e978043545 100644 --- a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md +++ b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md @@ -34,7 +34,7 @@ The [Document Preview decision](../architecture/2026-09-08-document-preview-oper A tab uses `dsh-resource://file/session//`, where the path may be relative or absolute ([Workspace Files](../architecture/2026-09-05-workspace-files-service.md) owns the grammar and the `fileAddressFor` / `parseFileAddress` helpers). `hostFileOf` accepts only this Session scope and takes both Session and path from the address; a Session-less `absolute` address is not claimed. A malformed claimed address throws as a programming error. -Metadata and content come from different places. `useResource<'file'>(tab.contentId)`, the global standard hook from the [client resource model](../architecture/2026-09-05-client-resource-model.md), yields `WorkspaceFileStat`; the body compares that observed version with the version of its loaded content. The Preview face reads text through `remote.workspaceFiles.read` and complete bytes through `readAll`. A later text page from a newer version restarts from page one, and a retired request cannot write after reload or tab disposal. The [Document Preview decision](../architecture/2026-09-08-document-preview-operations.md) owns renderer-specific loading. +Metadata and content come from different places. `useResource<'file'>(tab.contentId)`, the global standard hook from the [client resource model](../architecture/2026-09-05-client-resource-model.md), yields `WorkspaceFileStat`; the body compares that observed version with the version of its loaded content. The Preview face reads text through `remote.workspaceFiles.read` and complete bytes through `readBytes` with `{}` options. A later text page from a newer version restarts from page one, and a retired request cannot write after reload or tab disposal. The [Document Preview decision](../architecture/2026-09-08-document-preview-operations.md) owns renderer-specific loading. The store is Slot-standard: one exclusive instance per session, bucketed by tab id, holding `{ version, pages, eof, loading, failure, scrollTop, wrap, revision }`. Bucketing by tab, not by file, is deliberate — two tabs of one file scroll independently. The face (`loadPage`, `reloadPages`) is the only asynchronous half: it marks a read in flight, awaits the Remote result, and writes a page or a failure through the store's actions, writing nothing if the owner's `signal` has fired. The `signal` also ends the bucket: the face arms one abort listener per tab at the tab's first read, and that listener forgets the bucket — not the body, which mounts and unmounts as tabs switch; a tab that never read has no bucket and no listener, and a record can end while its body is unmounted behind another tab. Scroll offset, wrap, and the navigation already answered therefore outlive the body: a tab comes back where the reader left it rather than re-reading or jumping again. Nothing persists across a page reload. diff --git a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md index 294a2b4560..088d4a58c9 100644 --- a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md +++ b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md @@ -34,7 +34,7 @@ Sidebar 随包交付三个 tab 类型:**引导页**(`ui-sidebar-right`)、 tab 使用 `dsh-resource://file/session//`,其中路径可以是相对路径或绝对路径([Workspace Files](../architecture/2026-09-05-workspace-files-service.zh.md)负责该语法与 `fileAddressFor` / `parseFileAddress` 辅助函数)。`hostFileOf` 只接受这种 Session scope,并从地址取得 Session 与路径;不认领不带 Session 的 `absolute` 地址。被认领的地址若格式错误,则作为程序错误抛出。 -元数据与内容来自不同的地方。`useResource<'file'>(tab.contentId)`——[client 资源模型](../architecture/2026-09-05-client-resource-model.zh.md)提供的全局标准 hook——产生 `WorkspaceFileStat`;正文把其观察版本与已加载内容版本比较。Preview face 通过 `remote.workspaceFiles.read` 读取文本,通过 `readAll` 读取完整字节。后续文本页若来自更新版本,则从第一页重新开始;被重载或 tab 销毁淘汰的请求不能再写入。[Document Preview 决议](../architecture/2026-09-08-document-preview-operations.zh.md)负责各渲染器的加载方式。 +元数据与内容来自不同的地方。`useResource<'file'>(tab.contentId)`——[client 资源模型](../architecture/2026-09-05-client-resource-model.zh.md)提供的全局标准 hook——产生 `WorkspaceFileStat`;正文把其观察版本与已加载内容版本比较。Preview face 通过 `remote.workspaceFiles.read` 读取文本,通过带 `{}` 选项的 `readBytes` 读取完整字节。后续文本页若来自更新版本,则从第一页重新开始;被重载或 tab 销毁淘汰的请求不能再写入。[Document Preview 决议](../architecture/2026-09-08-document-preview-operations.zh.md)负责各渲染器的加载方式。 store 是 Slot 标准件:每会话一个独占实例,按 tab id 分桶,持有 `{ version, pages, eof, loading, failure, scrollTop, wrap, revision }`。按 tab 而非按文件分桶是有意的——同一文件的两个 tab 各自滚动。face(`loadPage`、`reloadPages`)是唯一的异步半边:它标记读取进行中,等待 Remote 结果,再经 store 的 action 写入一页或一次失败;若 owner 的 `signal` 已触发则什么也不写。`signal` 同时终结这个桶:face 在 tab 首次读取时挂一个 abort 监听器,由它忘掉桶——不是体,体随 tab 切换反复挂载卸载;从未读过的 tab 没有桶也没有监听器,而 tab 记录可能在其体被另一 tab 挡住而卸载时结束。因此滚动位置、换行与已答过的导航都活得比体久:tab 回来时停在读者离开的地方,而不是重读或再跳一次。刷新页面后什么都不保留。 diff --git a/apps/web/tests/document-preview.e2e.ts b/apps/web/tests/document-preview.e2e.ts index 603569a567..e2dc9c1713 100644 --- a/apps/web/tests/document-preview.e2e.ts +++ b/apps/web/tests/document-preview.e2e.ts @@ -571,7 +571,19 @@ else process.exit(1); await successShot(page, 'pdf-drag-selection') sections.push('## PDF drag selection\n\n- Table selection: forward and backward drags exclude later sections\n- Line-break highlight: transparent') + const pngResponse = page.waitForResponse(response => new URL(response.url()).pathname === '/api/workspaceFiles/readBytes' + && (response.request().postDataJSON() as { payload: { args: { path: string } } }).payload.args.path === 'tiny.png') await openFile('tiny.png') + const transferred = await pngResponse + expect(transferred.headers()['content-type']).toMatch(/^multipart\/form-data;/) + const transferredBody = await new Response(new Uint8Array(await transferred.body()), { headers: transferred.headers() }).formData() + const metadata = transferredBody.get('metadata') + if (typeof metadata !== 'string') throw new Error('missing PNG metadata') + const { attachments } = JSON.parse(metadata) as { attachments: { path: string[]; codec: string; part: string }[] } + expect(attachments).toEqual([{ path: ['data'], codec: 'bytes', part: expect.any(String) as unknown }]) + const transferredFile = transferredBody.get(attachments[0]!.part) + if (transferredFile === null || typeof transferredFile === 'string') throw new Error('missing PNG payload') + expect(Buffer.from(await transferredFile.arrayBuffer())).toEqual(TINY_PNG) const tinyImage = preview.getByRole('img', { name: 'Image preview: tiny.png', exact: true }) await tinyImage.waitFor({ state: 'visible', timeout: 15_000 }) expect(await viewer.count()).toBe(0) diff --git a/docs/api-gateway.i18n.yaml b/docs/api-gateway.i18n.yaml index 018bb1abc0..e11ee881f4 100644 --- a/docs/api-gateway.i18n.yaml +++ b/docs/api-gateway.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 docs/api-gateway.md -api-gateway.md: 52e91c48104ac8a8a46ad27f2b329ca72d6abc06 -api-gateway.zh.md: 9f062eaa6e6618354afa9ed1101e9cf6ed67d465 +api-gateway.md: 957f40775857d8f57af436a44690fd5a453aeeae +api-gateway.zh.md: 1062adcc89909d5ce3701ac82b55c5d0ece21ab0 diff --git a/docs/api-gateway.md b/docs/api-gateway.md index 52e91c4810..232ee859c7 100644 --- a/docs/api-gateway.md +++ b/docs/api-gateway.md @@ -122,9 +122,9 @@ Strict analysis requires a Remote to be a public, non-static instance method wit Remote calls use the Connection's `/api` route. The Client Remote calls `connection.rpc.call('/api', '/', { args }, signal)`; the HTTP carrier maps this to `POST /api//`, with a payload containing only a named `args` object. -The Connection performs the unified trust check for `/api` before the HTTP bridge, then dispatches inside the shared FetchHandler. The Typert Gateway claims only two-segment endpoints that have a strict descriptor or active SRC marker; feature-owned exact Fetch routes handle non-JSON responses, and other requests return 404. The Connection owns transport, RPC ids, response envelopes, and request cancellation, while the Gateway owns only the Remote data protocol and business dispatch. Replacing the Connection carrier does not require changes to Remote descriptors or the Client programming interface. +The Connection performs the unified trust check for `/api` before the HTTP bridge, then dispatches inside the shared FetchHandler. The Typert Gateway claims only two-segment endpoints that have a strict descriptor or active SRC marker; binary Remote successes use multipart responses, and feature-owned exact Fetch routes handle responses outside the RPC envelope, and other requests return 404. The Connection owns transport, RPC ids, response envelopes, and request cancellation, while the Gateway owns only the Remote data protocol and business dispatch. Replacing the Connection carrier does not require changes to Remote descriptors or the Client programming interface. -For every call, the Gateway resolves the descriptor and live service from the current registries instead of caching business objects. It requires the fields in `args` to match the descriptor exactly, validates wire values with codecs, resolves objects or receivers through registered lookup or Context providers, invokes the service method targeted by the binding, and validates the return value. A missing provider, unknown identity, binding mismatch, missing or extra argument, schema failure, or missing method fails before entering or after leaving business code. +For every call, the Gateway resolves the descriptor and live service from the current registries instead of caching business objects. It requires the fields in `args` to match the descriptor exactly, validates wire values with codecs, resolves objects or receivers through registered lookup or Context providers, and invokes the service method targeted by the binding. The Client Gateway validates decoded binary results with the generated result codec; ordinary JSON results retain their existing handling. A missing provider, unknown identity, binding mismatch, missing or extra argument, schema failure, or missing method fails before entering or after leaving business code. The lookup provider's `register()` supplies both the stable declaration and the default resolver; `configure()` supplies a resolver owned by Host composition that may execute asynchronously and is scoped to an effect lifetime. Configuration may precede provider mounting; without a provider, invocation still fails with `gateway/lookup-unavailable`, and unloading the configuration restores the provider's default policy. The Session Controller owns the standard resolver semantics for `agent` and `session`: it reuses a live Agent, automatically resumes ordinary cold sessions, deduplicates concurrent resumes, and rejects identities owned by subagent routing; the `session` lookup returns that Agent's Session. A resume failure and an ownership fence raise a `RemoteError` carrying their own code, `session/not-found` or `session/agent-busy`, which the Gateway encodes onto the wire unchanged; only an unclassified throw folds into `gateway/internal`. @@ -160,6 +160,6 @@ The running Client watcher consumes these generated files when it rebundles. If Remote handles unary method calls with one request and one result, and stream methods whose items flow Host → Client while the Client's items reach the running Host method through `this.ctx.invocation.uplink()`. Session event streams, pagination, incremental reduce, projection, and entity substreams still require a separate data protocol and registration model; even when they reuse the Connection, they must not masquerade as Remote methods or enter invocation descriptors. -The API layers are organized as `remotes → gateway → connection → webserver`. The BFF and Typert RPC layers live under `packages/api`; Connection and WebServer live at `packages/client/connection` and `packages/host/webserver`. A feature that needs a streamed or browser-native response registers an exact Connection Fetch route instead of defining a Remote method. +The API layers are organized as `remotes → gateway → connection → webserver`. The BFF and Typert RPC layers live under `packages/api`; Connection and WebServer live at `packages/client/connection` and `packages/host/webserver`. Unary results containing `Uint8Array`, including nested fields and array entries, use [binary Remote transfer](../.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md). A feature that needs a response outside the RPC envelope registers an exact Connection Fetch route. Lookup policy is configured per key, so all `agent` or `session` parameters share the cold-resume behavior. Accepting live objects only would require an explicit per-parameter or per-endpoint policy, which does not exist; the business method must not guess whether the object came from restoration. diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md index 9f062eaa6e..aa980adca0 100644 --- a/docs/api-gateway.zh.md +++ b/docs/api-gateway.zh.md @@ -122,9 +122,9 @@ Remote Client 声明中的参数名来自 wire 字段,参数和返回类型则 Remote 调用使用 Connection 的 `/api` 路由。Client Remote 调用 `connection.rpc.call('/api', '/', { args }, signal)`;HTTP carrier 对应 `POST /api//`,payload 只包含一个具名 `args` 对象。 -Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查,再在共享 FetchHandler 内分发。Typert Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint;功能自有的精确 Fetch 路由处理非 JSON 响应,其他请求返回 404。Connection 拥有传输、RPC id、响应 envelope 和请求取消,Gateway 只拥有 Remote 数据协议和业务分发。替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程接口。 +Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查,再在共享 FetchHandler 内分发。Typert Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint;二进制 Remote 成功响应使用 multipart,功能自有的精确 Fetch 路由处理 RPC 信封之外的响应,其他请求返回 404。Connection 拥有传输、RPC id、响应 envelope 和请求取消,Gateway 只拥有 Remote 数据协议和业务分发。替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程接口。 -Gateway 每次调用都从当前注册表解析描述符和实时服务,不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致,先用 codec 校验 wire 值,再通过注册的 lookup 或 Context 提供方解析对象或接收者,最后调用 binding 指向的服务方法并校验返回值。缺少提供方、identity 未命中、binding 不一致、参数缺失或多余、schema 失败和方法不存在都会在进入业务代码前或离开业务代码后失败。 +Gateway 每次调用都从当前注册表解析描述符和实时服务,不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致,先用 codec 校验 wire 值,再通过注册的 lookup 或 Context 提供方解析对象或接收者,最后调用 binding 指向的服务方法。Client Gateway 使用生成的结果 codec 校验解码后的二进制结果;普通 JSON 结果保持原有处理方式。缺少提供方、identity 未命中、binding 不一致、参数缺失或多余、schema 失败和方法不存在都会在进入业务代码前或离开业务代码后失败。 lookup 提供方的 `register()` 同时提供稳定声明和默认 resolver;`configure()` 提供由 Host 组合拥有、可异步执行且受 effect 生命周期约束的 resolver。配置可以先于提供方挂载;没有提供方时调用仍以 `gateway/lookup-unavailable` 失败,配置卸载后则恢复提供方默认策略。Session Controller 负责 `agent` 与 `session` 的标准 resolver 语义:复用 live Agent,自动恢复普通冷会话,对并发恢复去重,并拒绝由 subagent routing 拥有的 identity;`session` lookup 返回该 Agent 的 Session。恢复失败与 ownership fence 抛出携带自有码的 `RemoteError`(`session/not-found` 或 `session/agent-busy`),Gateway 原样编码上 wire;只有未归类的 throw 才折成 `gateway/internal`。 @@ -160,6 +160,6 @@ pnpm run build:lib Remote 处理单请求单结果的一元方法调用,以及项沿 Host → Client 方向流动、而 Client 的项经 `this.ctx.invocation.uplink()` 到达正在运行的 Host 方法的流方法。会话事件流、分页、增量 reduce、projection 和实体子流仍需要独立的数据协议与注册模型;即使它们复用 Connection,也不应伪装成 Remote 方法或放入调用描述符。 -API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 Typert RPC 层位于 `packages/api`;Connection 与 WebServer 位于 `packages/client/connection` 和 `packages/host/webserver`。需要流式或浏览器原生响应的功能注册精确的 Connection Fetch 路由,而不定义 Remote 方法。 +API 各层按 `remotes → gateway → connection → webserver` 组织。BFF 与 Typert RPC 层位于 `packages/api`;Connection 与 WebServer 位于 `packages/client/connection` 和 `packages/host/webserver`。包含 `Uint8Array` 的一元结果(包括嵌套字段和数组条目)使用[二进制 Remote 传输](../.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.zh.md)。需要 RPC 信封之外响应的功能注册精确的 Connection Fetch 路由。 lookup 策略按 key 配置,因此所有 `agent` 或 `session` 参数共享冷恢复行为。只接受 live 对象需要显式的逐参数或逐 endpoint 策略,而这种策略并不存在;不能通过业务方法内部猜测对象是否来自恢复。 diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index 2aa6cd3874..16eda74241 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.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 docs/config-catalog.md -config-catalog.md: bb95bd3794b0be4fd7688f77c2ac77efd4249ecf -config-catalog.zh.md: b1297bf254db369d063a39395d1678f91f807550 +config-catalog.md: 645c64b43a95d227a9373985f05bc50b4b4e93f6 +config-catalog.zh.md: e9f8db259539b83f771027062019039b930f8d37 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index bb95bd3794..645c64b43a 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -338,7 +338,7 @@ export interface Config { } ``` -Source: [`packages/api/workspace-files/src/index.ts:69`](../packages/api/workspace-files/src/index.ts) +Source: [`packages/api/workspace-files/src/index.ts:70`](../packages/api/workspace-files/src/index.ts) diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index b1297bf254..e9f8db2595 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -342,7 +342,7 @@ export interface Config { } ``` -来源:[`packages/api/workspace-files/src/index.ts:69`](../packages/api/workspace-files/src/index.ts) +来源:[`packages/api/workspace-files/src/index.ts:70`](../packages/api/workspace-files/src/index.ts) diff --git a/docs/subsystems/office-to-pdf.i18n.yaml b/docs/subsystems/office-to-pdf.i18n.yaml index 7f4afe0589..200c1c670b 100644 --- a/docs/subsystems/office-to-pdf.i18n.yaml +++ b/docs/subsystems/office-to-pdf.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 docs/subsystems/office-to-pdf.md -office-to-pdf.md: 65f46ded856e81f9bcd7890c11c82f0a22f769c4 -office-to-pdf.zh.md: df46af01d78241bbc88f6b85a83c47551faf4bfe +office-to-pdf.md: dd0f6392f264775f12c0f7612656f1c07366567d +office-to-pdf.zh.md: 5c99f87681dd8d98da3717a311a7f858d4b52b32 diff --git a/docs/subsystems/office-to-pdf.md b/docs/subsystems/office-to-pdf.md index 65f46ded85..dd0f6392f2 100644 --- a/docs/subsystems/office-to-pdf.md +++ b/docs/subsystems/office-to-pdf.md @@ -29,7 +29,7 @@ The provider admits the deferred read before allocating source bytes, shares con ## Preview reads -`RenderedDocumentBytes` extends the workspace byte response with `missingFonts` and `generation`; the original source identity accompanies the converted PDF. +`RenderedDocumentBytes` carries workspace file metadata, base64 PDF `data`, `missingFonts`, and `generation`; the original source identity accompanies the converted PDF. The `officeToPdf.render` Remote method checks source authorization and versions through the Session's [Workspace Files](../../packages/api/workspace-files/README.md) service. After conversion admission, `fs.readBytes` supplies raw input within the reserved byte capacity; Office input limits govern this read. The response carries base64 PDF bytes with the source absolute path and freshness version. Source access failures pass through; size and engine failures expose a classified reason without diagnostics. Conversion does not activate an Agent or append events. diff --git a/docs/subsystems/office-to-pdf.zh.md b/docs/subsystems/office-to-pdf.zh.md index df46af01d7..5c99f87681 100644 --- a/docs/subsystems/office-to-pdf.zh.md +++ b/docs/subsystems/office-to-pdf.zh.md @@ -29,7 +29,7 @@ ## 预览读取 -`RenderedDocumentBytes` 在工作区字节响应上增加 `missingFonts` 和 `generation`;转换后的 PDF 附带原始源文件身份。 +`RenderedDocumentBytes` 携带工作区文件元数据、base64 PDF `data`、`missingFonts` 和 `generation`;转换后的 PDF 附带原始源文件身份。 `officeToPdf.render` Remote 方法通过 Session 的[工作区文件](../../packages/api/workspace-files/README.zh.md)服务检查源文件授权与版本。取得转换容量后,`fs.readBytes` 在预留字节容量内提供原始输入;该读取受 Office 输入上限约束。响应携带 base64 PDF 字节、源文件绝对路径与新鲜度版本。源访问失败直接传递;大小和引擎失败只暴露分类原因,不含诊断信息。转换不激活 Agent 或追加事件。 diff --git a/docs/subsystems/sidebar-right.i18n.yaml b/docs/subsystems/sidebar-right.i18n.yaml index 091c70c940..b4d97350d4 100644 --- a/docs/subsystems/sidebar-right.i18n.yaml +++ b/docs/subsystems/sidebar-right.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 docs/subsystems/sidebar-right.md -sidebar-right.md: e3a4ffcf4e4b17975c10c0358f6f53dc5eea6ec2 -sidebar-right.zh.md: a588dc99b92314c54ea1309e4a44d305e23b970f +sidebar-right.md: bade9a958a62368b84ddfae8b5dbe869dfe11e4a +sidebar-right.zh.md: 93a6f1f25171b19fef5876e353e4b8be46aef78d diff --git a/docs/subsystems/sidebar-right.md b/docs/subsystems/sidebar-right.md index e3a4ffcf4e..bade9a958a 100644 --- a/docs/subsystems/sidebar-right.md +++ b/docs/subsystems/sidebar-right.md @@ -112,7 +112,7 @@ The `text` tab is the shared Document Preview owner. Its [root registration](../ The [registry](../../packages/client/ui-sidebar-documentpreview/src/client/document/registry.ts) records unique `id`, `extensions`, localized `title()`, `loading`, optional `priority`, and optional `wrap`. Case-insensitive suffix matching ranks `extension` (the default) before `builtin`, then longer suffixes before shorter ones, then registration order. Unlike tab-kind replacement, the registry keeps all implementations available; the toolbar lists matching alternatives and remembers the selection per tab. Unknown extensions use plain text. Suffixes declared in `binaryExtensions` suppress the plain-text alternative, as described in the [package README](../../packages/client/ui-sidebar-documentpreview/README.md#what-it-registers). `loading` is `text-pages`, `bytes-complete`, or `renderer`; `wrap` advertises support for the shared source-wrap control. -[`DocumentPreviewProps`](../../packages/client/ui-sidebar-documentpreview/src/client/document/contract.ts) derives from `PropsRuntime<'sidebar.right.tab.document'>`. The owner supplies the original `resourceAddress`, `content`, current `wrap`, and `addResource` / `setResources` dependency callbacks: text content is `{ kind: 'text', text, pages: [{ offset, text, lines }], eof }`, with cumulative `text`; complete bytes are `{ kind: 'bytes', data }`, with `Uint8Array` data. These transient buffers are borrowed read-only and must not enter durable layout or Session JSON. PDF copies the bytes before Worker transfer, preserving the owner's buffer. The child receives the same framework-bound `useTabInfo` and the global metadata-only `useResource`. The parent reads through ordinary inject callbacks to `remote.workspaceFiles.read`/`readAll` and owns page appends, per-tab refresh, and loading status. HTML's own inject callback uses `readRelated`; Host code resolves paths. Markdown and code retain one incremental renderer across appends and settle at EOF; HTML and PDF receive complete bytes. +[`DocumentPreviewProps`](../../packages/client/ui-sidebar-documentpreview/src/client/document/contract.ts) derives from `PropsRuntime<'sidebar.right.tab.document'>`. The owner supplies the original `resourceAddress`, `content`, current `wrap`, and `addResource` / `setResources` dependency callbacks: text content is `{ kind: 'text', text, pages: [{ offset, text, lines }], eof }`, with cumulative `text`; complete bytes are `{ kind: 'bytes', data }`, with `Uint8Array` data. These transient buffers are borrowed read-only and must not enter durable layout or Session JSON. PDF copies the bytes before Worker transfer, preserving the owner's buffer. The child receives the same framework-bound `useTabInfo` and the global metadata-only `useResource`. The parent reads text through `remote.workspaceFiles.read` and bytes through `remote.workspaceFiles.readBytes`, and owns page appends, per-tab refresh, and loading status. HTML passes `baseFile` to the same byte reader; Host code resolves paths. Markdown and code retain one incremental renderer across appends and settle at EOF; HTML and PDF receive complete bytes. Preview records its loaded version and the version observed when a read starts. Automatic refresh defaults to enabled; initial member metadata establishes a baseline, and later changes reload the tab. Refresh rereads only that tab, without changing shared metadata or another tab's content. Reads are non-transactional; versions are opaque equality tokens, not ordered timestamps ([resource observation and Preview RPC](../../.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md)). @@ -128,9 +128,9 @@ A resource stays open while it has a holder — a subscribed `useResource` or a ## Workspace Files -The Host `ctx.workspaceFiles` service and generated `workspaceFiles` Remote namespace read files allowed by the Session filesystem backend: `stat(path)` returns `{ absolutePath, version, bytes? }`; `read(path, { offset?, limit? })` returns one page of lines (`offset` 1-based, `limit` capped by the configured page size) as `{ …stat, offset, text, eof }`; `readBytes(path, { offset?, length? })` returns one raw byte window (`offset` 0-based, `length` capped by the configured byte limit) as base64 `{ …stat, offset, data, eof }` with no text decoding. `list(path)` remains inside the workspace root and returns a directory's direct children (`name`, `type: 'file' | 'directory' | 'other'`, `size?`) cut to the configured cap with `truncated` set. `changes(path)` watches one target; the Host determines its type and confines directories to the workspace. It yields `{ kind: 'ready' }` once subscribed, then `{ kind: 'change', change }` frames whose payload is `{ absolutePath, version }` or `{ absolutePath, absent: true }` ([README](../../packages/api/workspace-files/README.md#use-this-package)). File reads reject final symlinks and enforce transfer caps; `read` additionally requires UTF-8 text. Failures use `workspace-file/*` codes ([failures](../../packages/api/workspace-files/README.md)). +The Host `ctx.workspaceFiles` service and generated `workspaceFiles` Remote namespace read files allowed by the Session filesystem backend: `stat(path)` returns `{ absolutePath, version, bytes? }`; `read(path, { offset?, limit? })` returns one page of lines (`offset` 1-based, `limit` capped by the configured page size) as `{ …stat, offset, text, eof }`; `readBytes(path, { range?, baseFile? })` returns a complete file under `maxFileBytes` or a byte window under `maxBytes` as `{ …stat, offset, data, eof }` with native `Uint8Array` data. Its optional `range` uses 0-based `offset` and a byte `length`; `baseFile` resolves the relative target from another file’s directory. `list(path)` remains inside the workspace root and returns a directory's direct children (`name`, `type: 'file' | 'directory' | 'other'`, `size?`) cut to the configured cap with `truncated` set. `changes(path)` watches one target; the Host determines its type and confines directories to the workspace. It yields `{ kind: 'ready' }` once subscribed, then `{ kind: 'change', change }` frames whose payload is `{ absolutePath, version }` or `{ absolutePath, absent: true }` ([README](../../packages/api/workspace-files/README.md#use-this-package)). File reads reject final symlinks and enforce transfer caps; `read` additionally requires UTF-8 text. Failures use `workspace-file/*` codes ([failures](../../packages/api/workspace-files/README.md)). -[`dsh-api-workspace-files`](../../packages/api/workspace-files/README.md) registers the `file` provider, with `ResourceProtocolMap.file` directly naming `WorkspaceFileStat`. A Session address carries the authorizing Session and a relative or absolute path, passed unchanged to the Host for resolution. The provider waits for Host `ready` before stat and filters changes by `stat.absolutePath`. Bare `absolute` addresses have no authorizing Session and fail with `workspace-file/unknown-workspace`, without borrowing current or Tab Session. Any UI, including Global components, shares the observation for the same complete address. Preview's ordinary Remote callbacks use the Session in that address; Host `readAll` and `readRelated` remain, and Preview's `rpc.ts` decodes byte results. +[`dsh-api-workspace-files`](../../packages/api/workspace-files/README.md) registers the `file` provider, with `ResourceProtocolMap.file` directly naming `WorkspaceFileStat`. A Session address carries the authorizing Session and a relative or absolute path, passed unchanged to the Host for resolution. The provider waits for Host `ready` before stat and filters changes by `stat.absolutePath`. Bare `absolute` addresses have no authorizing Session and fail with `workspace-file/unknown-workspace`, without borrowing current or Tab Session. Any UI, including Global components, shares the observation for the same complete address. Preview's Remote callbacks use the Session in that address; `remote.workspaceFiles.readBytes` returns native bytes through Connection's binary RPC transport. ## Shipped types diff --git a/docs/subsystems/sidebar-right.zh.md b/docs/subsystems/sidebar-right.zh.md index a588dc99b9..93a6f1f251 100644 --- a/docs/subsystems/sidebar-right.zh.md +++ b/docs/subsystems/sidebar-right.zh.md @@ -112,7 +112,7 @@ Sidebar 声明四个扩展 slot;其文档 tab 另行声明下表中的 keyed [注册表](../../packages/client/ui-sidebar-documentpreview/src/client/document/registry.ts)记录唯一的 `id`、`extensions`、本地化 `title()`、`loading`,以及可选的 `priority` 和 `wrap`。后缀匹配不区分大小写,先排 `extension`(缺省值)、再排 `builtin`,随后比较后缀长度(长者优先)与注册顺序。与 tab kind 替换不同,注册表保留所有实现;工具栏列出匹配的候选,按 tab 记住选择。未知扩展名使用纯文本。`binaryExtensions` 声明的后缀不提供纯文本备选,见[包 README](../../packages/client/ui-sidebar-documentpreview/README.zh.md#what-it-registers)。`loading` 为 `text-pages`、`bytes-complete` 或 `renderer`;`wrap` 声明是否支持共享的源码换行控件。 -[`DocumentPreviewProps`](../../packages/client/ui-sidebar-documentpreview/src/client/document/contract.ts) 派生自 `PropsRuntime<'sidebar.right.tab.document'>`。owner 提供原始 `resourceAddress`、`content`、当前 `wrap`,以及声明依赖的 `addResource` / `setResources` 回调:文本内容为 `{ kind: 'text', text, pages: [{ offset, text, lines }], eof }`,其中 `text` 为累积文本;完整字节为 `{ kind: 'bytes', data }`,其中 `data` 为 `Uint8Array`。这些瞬时缓冲区按只读方式借用,不得进入持久布局或 Session JSON。PDF 在转移到 Worker 前复制字节,以保留 owner 的缓冲区。子组件收到同一个框架绑定的 `useTabInfo`,以及全局共享、仅提供元数据的 `useResource`。父组件通过普通 inject 回调调用 `remote.workspaceFiles.read`/`readAll`,拥有追加分页、逐 tab 刷新与加载状态。HTML 自己的 inject 回调使用 `readRelated`;路径由 Host 代码解析。Markdown 和代码在追加期间保留同一个增量渲染器,到 EOF 完成最终解析;HTML 和 PDF 接收完整字节。 +[`DocumentPreviewProps`](../../packages/client/ui-sidebar-documentpreview/src/client/document/contract.ts) 派生自 `PropsRuntime<'sidebar.right.tab.document'>`。owner 提供原始 `resourceAddress`、`content`、当前 `wrap`,以及声明依赖的 `addResource` / `setResources` 回调:文本内容为 `{ kind: 'text', text, pages: [{ offset, text, lines }], eof }`,其中 `text` 为累积文本;完整字节为 `{ kind: 'bytes', data }`,其中 `data` 为 `Uint8Array`。这些瞬时缓冲区按只读方式借用,不得进入持久布局或 Session JSON。PDF 在转移到 Worker 前复制字节,以保留 owner 的缓冲区。子组件收到同一个框架绑定的 `useTabInfo`,以及全局共享、仅提供元数据的 `useResource`。父组件通过 `remote.workspaceFiles.read` 读取文本,通过 `remote.workspaceFiles.readBytes` 读取字节,拥有追加分页、逐 tab 刷新与加载状态。HTML 向同一个字节读取方法传入 `baseFile`;路径由 Host 代码解析。Markdown 和代码在追加期间保留同一个增量渲染器,到 EOF 完成最终解析;HTML 和 PDF 接收完整字节。 Preview 记录已载入版本和读取开始时的观察版本。自动刷新默认开启;成员首次元数据只建立基线,后续变化才重新加载 tab。刷新只重读当前 tab,不改变共享元数据或其他 tab 的内容。读取不具备事务性;版本是不透明的相等性令牌,不是可排序的时间戳([资源观察与 Preview RPC](../../.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md))。 @@ -128,9 +128,9 @@ Preview 记录已载入版本和读取开始时的观察版本。自动刷新默 ## Workspace Files -Host 的 `ctx.workspaceFiles` 服务与生成的 `workspaceFiles` Remote 命名空间读取 Session 文件系统后端允许的文件:`stat(path)` 返回 `{ absolutePath, version, bytes? }`;`read(path, { offset?, limit? })` 返回一页行(`offset` 1 起,`limit` 受配置页长限制),形如 `{ …stat, offset, text, eof }`;`readBytes(path, { offset?, length? })` 返回一个原始字节窗口(`offset` 0 起,`length` 受配置字节上限限制),形如 base64 的 `{ …stat, offset, data, eof }`、不做文本解码。`list(path)` 仍限定在工作区根内,返回目录的直接子项(`name`、`type: 'file' | 'directory' | 'other'`、`size?`),按配置上限截断并置 `truncated`。`changes(path)` 监听一个目标,由 Host 判断目标类型并将目录限制在工作区内;订阅就绪后产出 `{ kind: 'ready' }`,随后产出 `{ kind: 'change', change }` 帧,其载荷为 `{ absolutePath, version }` 或 `{ absolutePath, absent: true }`([README](../../packages/api/workspace-files/README.zh.md#use-this-package))。文件读取拒绝末端符号链接并执行传输上限;`read` 还要求 UTF-8 文本。失败使用 `workspace-file/*` 错误码([失败](../../packages/api/workspace-files/README.zh.md))。 +Host 的 `ctx.workspaceFiles` 服务与生成的 `workspaceFiles` Remote 命名空间读取 Session 文件系统后端允许的文件:`stat(path)` 返回 `{ absolutePath, version, bytes? }`;`read(path, { offset?, limit? })` 返回一页行(`offset` 1 起,`limit` 受配置页长限制),形如 `{ …stat, offset, text, eof }`;`readBytes(path, { range?, baseFile? })` 在 `maxFileBytes` 上限内返回完整文件,或在 `maxBytes` 上限内返回字节窗口,形如 `{ …stat, offset, data, eof }`,其中 `data` 为原生 `Uint8Array`。可选 `range` 使用 0 起算的 `offset` 与字节数 `length`;`baseFile` 从另一文件所在目录解析相对目标。`list(path)` 仍限定在工作区根内,返回目录的直接子项(`name`、`type: 'file' | 'directory' | 'other'`、`size?`),按配置上限截断并置 `truncated`。`changes(path)` 监听一个目标,由 Host 判断目标类型并将目录限制在工作区。订阅就绪后产出 `{ kind: 'ready' }`,随后产出 `{ kind: 'change', change }` 帧,其载荷为 `{ absolutePath, version }` 或 `{ absolutePath, absent: true }`([README](../../packages/api/workspace-files/README.zh.md#use-this-package))。文件读取拒绝末端符号链接并执行传输上限;`read` 还要求 UTF-8 文本。失败使用 `workspace-file/*` 错误码([失败](../../packages/api/workspace-files/README.zh.md))。 -[`dsh-api-workspace-files`](../../packages/api/workspace-files/README.zh.md) 注册 `file` 提供方,`ResourceProtocolMap.file` 直接是 `WorkspaceFileStat`。Session 地址携带授权 Session 与相对或绝对路径,Host 原样接收并解析。提供方在 stat 前等待 Host 的 `ready` 帧,并按 `stat.absolutePath` 过滤变更。裸 `absolute` 地址没有授权 Session,以 `workspace-file/unknown-workspace` 失败,不借用当前或 Tab Session。任何 UI(包括 Global)访问同一完整地址都共享观察。Preview 的普通 Remote 回调使用地址中的 Session;Host `readAll` 和 `readRelated` 保留,字节结果由 Preview 的 `rpc.ts` 解码。 +[`dsh-api-workspace-files`](../../packages/api/workspace-files/README.zh.md) 注册 `file` 提供方,`ResourceProtocolMap.file` 直接是 `WorkspaceFileStat`。Session 地址携带授权 Session 与相对或绝对路径,Host 原样接收并解析。提供方在 stat 前等待 Host 的 `ready` 帧,并按 `stat.absolutePath` 过滤变更。裸 `absolute` 地址没有授权 Session,以 `workspace-file/unknown-workspace` 失败,不借用当前或 Tab Session。任何 UI(包括 Global)访问同一完整地址都共享观察。Preview 的 Remote 回调使用地址中的 Session;`remote.workspaceFiles.readBytes` 通过 Connection 的二进制 RPC 传输返回原生字节。 ## 内置类型 diff --git a/docs/subsystems/typert.i18n.yaml b/docs/subsystems/typert.i18n.yaml index 2f43dc6d54..374b43c01f 100644 --- a/docs/subsystems/typert.i18n.yaml +++ b/docs/subsystems/typert.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 docs/subsystems/typert.md -typert.md: a8192b319215957b8d373ec01f6f29d73e165e45 -typert.zh.md: 08d1e8f466ef1e516c04426165b8180bd9881c83 +typert.md: a8ad968b7af77c90cfcdbeb910f435be461bf442 +typert.zh.md: d020b75ee7c52cc87aaea371978aeebe78d6fa45 diff --git a/docs/subsystems/typert.md b/docs/subsystems/typert.md index a8192b3192..a8ad968b7a 100644 --- a/docs/subsystems/typert.md +++ b/docs/subsystems/typert.md @@ -38,7 +38,7 @@ interface TypertLookupDefinition { ## Invocation descriptors -An `InvocationDescriptor` is local reflection, not a wire message. Host and consumer builds generate corresponding descriptors; the request sends only the endpoint and named `args`. Strict codecs carry generated schema factories, while SRC codecs enforce JSON-safe values without structural type recovery. Cancellation is an out-of-band carrier signal injected after business parameters and never enters `args`. +An `InvocationDescriptor` is local reflection, not a wire message. Host and consumer builds generate corresponding descriptors; the request sends only the endpoint and named `args`. Strict codecs carry generated schema factories, while SRC codecs enforce JSON-safe inputs without structural type recovery. Unary result codecs can supply `encode()` for byte-containing subtrees and `decode()` for recursive native-byte validation; Client declarations narrow every `Uint8Array` to `ArrayBuffer` backing. Pure JSON results need neither byte detection nor Client decoding. Cancellation is an out-of-band carrier signal injected after business parameters and never enters `args`. ```ts type-equiv /** Codec attached to one invocation parameter or result. */ @@ -48,6 +48,19 @@ type TypertCodec = readonly typeSymbol: string /** Materialize and return the process-realm schema on first boundary use. */ readonly create: () => TypertSchema + /** + * Decode a unary result whose fields require type-specific handling. + * @param value - result reconstructed by the RPC carrier. + * @returns the validated result, retaining native byte views. + */ + readonly decode?: (value: unknown) => unknown + /** + * Project typed binary fields into carrier-owned multipart attachments. + * @param value - native unary result. + * @param writeBytes - records a byte view at its result-relative path and returns its JSON placeholder. + * @returns JSON metadata with untouched JSON subtrees retained. + */ + readonly encode?: (value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown } | { readonly mode: 'src-json' diff --git a/docs/subsystems/typert.zh.md b/docs/subsystems/typert.zh.md index 08d1e8f466..d020b75ee7 100644 --- a/docs/subsystems/typert.zh.md +++ b/docs/subsystems/typert.zh.md @@ -38,7 +38,7 @@ interface TypertLookupDefinition { ## 调用 descriptor -`InvocationDescriptor` 是本地反射信息,不是 wire message。Host 与消费方构建会生成彼此对应的 descriptor;请求只发送 endpoint 与具名 `args`。strict codec 携带生成的 schema factory,SRC codec 则在不恢复结构类型的前提下强制要求 JSON 安全值。取消通过带外 carrier signal 表达:它在业务参数之后注入,绝不进入 `args`。 +`InvocationDescriptor` 是本地反射信息,不是 wire message。Host 与消费方构建会生成彼此对应的 descriptor;请求只发送 endpoint 与具名 `args`。strict codec 携带生成的 schema factory,SRC codec 则在不恢复结构类型的前提下强制要求输入为 JSON 安全值。一元结果 codec 可提供 `encode()` 处理含字节的子树,并通过 `decode()` 递归校验原生字节;Client 声明将每个 `Uint8Array` 限定为以 `ArrayBuffer` 为底层缓冲区。纯 JSON 结果无需字节识别或 Client 解码。取消通过带外 carrier signal 表达:它在业务参数之后注入,绝不进入 `args`。 ```ts type-equiv /** Codec attached to one invocation parameter or result. */ @@ -48,6 +48,19 @@ type TypertCodec = readonly typeSymbol: string /** Materialize and return the process-realm schema on first boundary use. */ readonly create: () => TypertSchema + /** + * Decode a unary result whose fields require type-specific handling. + * @param value - result reconstructed by the RPC carrier. + * @returns the validated result, retaining native byte views. + */ + readonly decode?: (value: unknown) => unknown + /** + * Project typed binary fields into carrier-owned multipart attachments. + * @param value - native unary result. + * @param writeBytes - records a byte view at its result-relative path and returns its JSON placeholder. + * @returns JSON metadata with untouched JSON subtrees retained. + */ + readonly encode?: (value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown } | { readonly mode: 'src-json' diff --git a/docs/subsystems/web-client.i18n.yaml b/docs/subsystems/web-client.i18n.yaml index 0f1163393e..f89b3c13dc 100644 --- a/docs/subsystems/web-client.i18n.yaml +++ b/docs/subsystems/web-client.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 docs/subsystems/web-client.md -web-client.md: c43b7553d1a223b82fec73c7431e4655cf1cbee1 -web-client.zh.md: d98febb7494a2b2fe082f8544850dbf67ee75794 +web-client.md: 80d233b634f57bb150d8eb6604428557e1e16033 +web-client.zh.md: f14cdbe9b1d5605b90bd595a384ef7ac9c0d7286 diff --git a/docs/subsystems/web-client.md b/docs/subsystems/web-client.md index c43b7553d1..80d233b634 100644 --- a/docs/subsystems/web-client.md +++ b/docs/subsystems/web-client.md @@ -27,7 +27,7 @@ The Web boot kernel creates the module system, prefetches `immediately` entries, Host business services annotate callable methods with Typert Remote decorators. Host generation emits strict descriptors, runtime codecs, declaration merges, and source maps. The Client-side `api-remotes` assembly selects those generated contributions and mounts concrete methods under `ctx.remote.` and Session-scoped `agentCtx.remote.`. Feature packages depend on the generated service face, not the Gateway implementation or a Host package's runtime entry. -The Connection owns request correlation, the `/api` carrier, trust checks, exact Fetch routes, and connection generations. API Gateway owns Remote dispatch, cancellation, logical streams, and selected Host event forwarding. Controller operations belong on generated Remote methods or explicit Remote streams; feature-owned downloads register exact Fetch routes. The [API Gateway reference](../api-gateway.md) defines generation and invocation, while the [Connection README](../../packages/client/connection/README.md) defines the physical carrier and trust policy. +The Connection owns request URL resolution, correlation, the `/api` carrier, trust checks, exact Fetch routes, and connection generations. API Gateway owns Remote dispatch, cancellation, logical streams, and selected Host event forwarding. Controller operations belong on generated Remote methods or explicit Remote streams; feature-owned downloads register exact Fetch routes. The [API Gateway reference](../api-gateway.md) defines generation and invocation, while the [Connection README](../../packages/client/connection/README.md) defines the physical carrier and trust policy. The internal `$events` logical stream is the Connection generation source. Its opening `ready` frame carries the Host home used for path display and establishes the generation after Host listeners are attached, before any controller begins a baseline read. `ctx.remote.$on()` delivers allowlisted ordinary events to the root Client Context and scoped waterfall events to the resolved Session Context; a waterfall listener returns a result, calls `next()`, or rejects. diff --git a/docs/subsystems/web-client.zh.md b/docs/subsystems/web-client.zh.md index d98febb749..f14cdbe9b1 100644 --- a/docs/subsystems/web-client.zh.md +++ b/docs/subsystems/web-client.zh.md @@ -27,7 +27,7 @@ Web boot kernel 创建模块系统、预取 `immediately` entry、挂载 vendore Host 业务 service 使用 Typert Remote decorator 标记可调用 method。Host generation 产出严格 descriptor、runtime codec、declaration merge 与 source map。Client 侧 `api-remotes` assembly 选择这些生成贡献,并把具体 method 挂到 `ctx.remote.` 与 Session scope 的 `agentCtx.remote.`。功能包依赖生成的 service face,而不依赖 Gateway 实现或 Host 包的运行时 entry。 -Connection 拥有 request correlation、`/api` carrier、trust check、精确 Fetch 路由与 connection generation。API Gateway 拥有 Remote dispatch、取消、logical stream 与选定 Host event 的转发。Controller 操作应进入生成的 Remote method 或显式 Remote stream;功能自有的下载则注册精确 Fetch 路由。[API Gateway 参考](../api-gateway.zh.md)定义 generation 与调用,[Connection README](../../packages/client/connection/README.zh.md)定义物理 carrier 与信任策略。 +Connection 拥有请求 URL 解析、request correlation、`/api` carrier、trust check、精确 Fetch 路由与 connection generation。API Gateway 拥有 Remote dispatch、取消、logical stream 与选定 Host event 的转发。Controller 操作应进入生成的 Remote method 或显式 Remote stream;功能自有的下载则注册精确 Fetch 路由。[API Gateway 参考](../api-gateway.zh.md)定义 generation 与调用,[Connection README](../../packages/client/connection/README.zh.md)定义物理 carrier 与信任策略。 内部 `$events` logical stream 是 Connection generation source。它的 opening `ready` frame 携带用于路径显示的 Host home,并在 Host listener 已挂载、任何 controller 开始 baseline read 之前建立 generation。`ctx.remote.$on()` 把 allowlist 内的普通 event 交付给 root Client Context,并把 scoped waterfall event 交付给已解析的 Session Context;waterfall listener 可以返回结果、调用 `next()` 或拒绝。 diff --git a/docs/subsystems/workspace.i18n.yaml b/docs/subsystems/workspace.i18n.yaml index 452d200cf5..b03f962bef 100644 --- a/docs/subsystems/workspace.i18n.yaml +++ b/docs/subsystems/workspace.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 docs/subsystems/workspace.md -workspace.md: 323323946ac92bbc03962b83c5e77a81a960d89a -workspace.zh.md: aedd1134305aaa7e97ccd449631ff72446bf28b4 +workspace.md: 8a3369778f0eac10d5fe077686d336eb47f6b41e +workspace.zh.md: f1e7e96f1fb5e983de30bd8e2f9fe08ed0635beb diff --git a/docs/subsystems/workspace.md b/docs/subsystems/workspace.md index 323323946a..8a3369778f 100644 --- a/docs/subsystems/workspace.md +++ b/docs/subsystems/workspace.md @@ -397,34 +397,14 @@ Host Remote file reads and workspace directory observations over the composed fi @Remote async read( workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceFileRange, signal: AbortSignal, ): Promise /** - * Read one byte window of a regular file readable by the filesystem backend: raw - * bytes, no text decoding and no binary rejection. + * Read a complete regular file or one byte range without text decoding. * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire. - * @param path - absolute path or path relative to the workspace root; files outside it are allowed. - * @param range - the byte window; omitted fields take the window defaults. + * @param path - target path, absolute or workspace-relative; relative to the base file's directory when provided. + * @param options - optional base file and range; without a range the complete-file cap applies. * @param signal - caller cancellation. - * @returns the window in base64, the file's version and size at the stat before it, and whether it reaches the last byte. + * @returns native bytes with the file's version and size at the preceding stat, byte offset, and EOF marker. */ -@Remote async readBytes( workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceByteRange, signal: AbortSignal, ): Promise - -/** - * Read a complete regular file as bytes, subject to the configured full-file cap. - * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire. - * @param path - absolute or workspace-relative file path. - * @param signal - caller cancellation. - * @returns one complete base64 window with offset zero and eof true; oversized files fail with too-large. - */ -@Remote async readAll(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise - -/** - * Read a complete file relative to another file's directory, including outside the workspace. - * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire. - * @param path - base file, absolute or workspace-relative. - * @param relativePath - relative filesystem path, not a URL or absolute path. - * @param signal - caller cancellation. - * @returns the complete related file using the ordinary file-size and access checks. - */ -@Remote async readRelated( workspaceFileScope: WorkspaceFileScope, path: string, relativePath: string, signal: AbortSignal, ): Promise +@Remote async readBytes( workspaceFileScope: WorkspaceFileScope, path: string, options: WorkspaceByteReadOptions, signal: AbortSignal, ): Promise /** * Report one regular file's identity, version, and size without its content. diff --git a/docs/subsystems/workspace.zh.md b/docs/subsystems/workspace.zh.md index aedd113430..f1e7e96f1f 100644 --- a/docs/subsystems/workspace.zh.md +++ b/docs/subsystems/workspace.zh.md @@ -397,34 +397,14 @@ Host Remote file reads and workspace directory observations over the composed fi @Remote async read( workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceFileRange, signal: AbortSignal, ): Promise /** - * Read one byte window of a regular file readable by the filesystem backend: raw - * bytes, no text decoding and no binary rejection. + * Read a complete regular file or one byte range without text decoding. * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire. - * @param path - absolute path or path relative to the workspace root; files outside it are allowed. - * @param range - the byte window; omitted fields take the window defaults. + * @param path - target path, absolute or workspace-relative; relative to the base file's directory when provided. + * @param options - optional base file and range; without a range the complete-file cap applies. * @param signal - caller cancellation. - * @returns the window in base64, the file's version and size at the stat before it, and whether it reaches the last byte. + * @returns native bytes with the file's version and size at the preceding stat, byte offset, and EOF marker. */ -@Remote async readBytes( workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceByteRange, signal: AbortSignal, ): Promise - -/** - * Read a complete regular file as bytes, subject to the configured full-file cap. - * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire. - * @param path - absolute or workspace-relative file path. - * @param signal - caller cancellation. - * @returns one complete base64 window with offset zero and eof true; oversized files fail with too-large. - */ -@Remote async readAll(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise - -/** - * Read a complete file relative to another file's directory, including outside the workspace. - * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire. - * @param path - base file, absolute or workspace-relative. - * @param relativePath - relative filesystem path, not a URL or absolute path. - * @param signal - caller cancellation. - * @returns the complete related file using the ordinary file-size and access checks. - */ -@Remote async readRelated( workspaceFileScope: WorkspaceFileScope, path: string, relativePath: string, signal: AbortSignal, ): Promise +@Remote async readBytes( workspaceFileScope: WorkspaceFileScope, path: string, options: WorkspaceByteReadOptions, signal: AbortSignal, ): Promise /** * Report one regular file's identity, version, and size without its content. diff --git a/packages/api/gateway/README.i18n.yaml b/packages/api/gateway/README.i18n.yaml index 5f05ce5e1e..832baf5fd0 100644 --- a/packages/api/gateway/README.i18n.yaml +++ b/packages/api/gateway/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/api/gateway/README.md -README.md: 996e68fd2b99989523b01272c693d4039fdc9f44 -README.zh.md: 23b83fbf2c7559434dfd47d6b06994a8d390d1ac +README.md: 71171ef65c9113315cbd401a6b59eefb5a9a45a1 +README.zh.md: f9f2068eb593acc25f1fd384d08979d5c48c7743 diff --git a/packages/api/gateway/README.md b/packages/api/gateway/README.md index 996e68fd2b..71171ef65c 100644 --- a/packages/api/gateway/README.md +++ b/packages/api/gateway/README.md @@ -26,7 +26,7 @@ Two-sided Typert RPC endpoint for Host and Client Cordis environments. The Host `ctx.typertGateway.invoke()` resolves the current descriptor and Cordis Service for each call, validates exact named arguments, resolves registered object or Context identities, and invokes the public business method. Business Services extend `TypertRemoteService` and mark methods with `@Remote` or `@RemoteScope` from [`dsh-typert-protocol`](../../typert/protocol/README.md); `bindTypertRemote()` remains available when another base class owns inheritance. -Strict mode reads generated invocation descriptors from `ctx.typert.local`. Lookup parameters use the currently active resolver in `ctx.typert.lookups`: the business package registers the stable declaration and default policy, while Host composition can override resolution behavior with effect-scoped `configure()`; `@RemoteScope` resolves its receiver through a registered Host Context adapter. SRC mode is a development fallback for endpoints that have never had a strict definition; it parses simple parameter names and accepts only JSON-safe values for non-lookup parameters. Withdrawing an observed strict definition fails instead of weakening validation. +Strict mode reads generated invocation descriptors from `ctx.typert.local`. Lookup parameters use the currently active resolver in `ctx.typert.lookups`: the business package registers the stable declaration and default policy, while Host composition can override resolution behavior with effect-scoped `configure()`; `@RemoteScope` resolves its receiver through a registered Host Context adapter. SRC mode is a development fallback for endpoints that have never had a strict definition; it parses simple parameter names and accepts only JSON-safe values for non-lookup parameters. Withdrawing an observed strict definition fails instead of weakening validation. For unary results, Gateway executes the generated codec's `encode()` when present and otherwise keeps strict JSON values unchanged; SRC recursively detects runtime byte values. Both paths return JSON-compatible metadata and result-relative byte attachments to Connection for transport framing. The Host entry registers a trusted-host interceptor on Connection's shared `/api` FetchHandler. Connection passes this composite handler through its HTTP bridge; the handler dispatches claimed endpoints to Gateway and returns 404 for unclaimed requests unless an exact Fetch route owns them. Direct `invoke()` calls preserve business errors; `TypertGatewayError` is a `RemoteError` subclass whose `gateway/*` codes name the failures owned by dispatch, binding, providers, lookup, Context, arguments, codecs, and the uplink: `gateway/uplink-overflow` for an uplink whose buffered frames exceed `streamInboxBytes`, `gateway/protocol` for an uplink item after `end`, and the codec code `gateway/input-invalid` for a rejected uplink item. A resolver that refuses on policy grounds — a cold-resume failure or an ownership fence — throws its own `RemoteError`, and the code it chose reaches the caller unchanged. @@ -45,7 +45,7 @@ The browser carrier accepts the shell-owned stream origin described by [Connecti `ctx.remote.$mount()` validates and registers a generated Host-for-Client contribution, then installs concrete direct and scoped methods for the calling Cordis fiber. Each namespace is a traced `remote.` child Service and unloads after its last method is withdrawn. Duplicate endpoints, namespace collisions, and Client-supplied fields without strict generated codecs fail before methods become callable. -Each unary call checks positional arity, constructs the descriptor's exact named `args`, and sends the typed values through `ctx.connection.rpc.call('/api', endpoint, ...)` without executing Client-side schemas; the Host validates the received wire fields before business invocation. A generated stream method returns a `RemoteStreamHandle` from `dsh-typert-protocol` and opens one logical stream when it is called, through an in-process Connection carrier when available, otherwise through the shared Gateway WebSocket. The handle iterates the downlink once. `send(item)` queues an uplink item, sent after the `open` frame; `end()` half-closes the uplink; `dispose()` sends `cancel` unless a terminal frame has arrived and ends the iteration quietly. Breaking out of the iteration early disposes the handle; after the downlink terminates `send` throws and `end` is ignored. Generated cancellation-aware methods accept a final optional `AbortSignal`; the Client combines it with the contribution mount lifetime before invoking the carrier. Successful unary results and stream items pass through without Client-side type parsing. Withdrawing a contribution removes its descriptors and methods together, aborts in-flight calls and streams, and makes retained method handles reject. +Each unary call checks positional arity, constructs the descriptor's exact named `args`, and sends the typed values through `ctx.connection.rpc.call('/api', endpoint, ...)` without executing Client-side schemas; the Host validates the received wire fields before business invocation. A generated stream method returns a `RemoteStreamHandle` from `dsh-typert-protocol` and opens one logical stream when it is called, through an in-process Connection carrier when available, otherwise through the shared Gateway WebSocket. The handle iterates the downlink once. `send(item)` queues an uplink item, sent after the `open` frame; `end()` half-closes the uplink; `dispose()` sends `cancel` unless a terminal frame has arrived and ends the iteration quietly. Breaking out of the iteration early disposes the handle; after the downlink terminates `send` throws and `end` is ignored. Generated cancellation-aware methods accept a final optional `AbortSignal`; the Client combines it with the contribution mount lifetime before invoking the carrier. The Client delegates unary result conversion to the codec's optional `decode()`. Generated decoders validate nested metadata and native byte types without iterating, copying, or freezing byte payloads. JSON unary results and stream items pass through without Client-side type parsing. Withdrawing a contribution removes its descriptors and methods together, aborts in-flight calls and streams, and makes retained method handles reject. Every unary call resolves to `RemoteResult` — `{ ok: true, value }` or `{ ok: false, error }` — and never rejects for a carrier problem: this face folds an offline carrier into the error branch and answers `gateway/cancelled` when the caller's signal aborts, so no consumer wraps a call to recover one. Only an assembly fault still rejects: wrong arity, an unmounted method, a withdrawn contribution, a missing Context adapter. `error` is a live `RemoteError` instance, so `throw result.error` keeps throw semantics, and `isRemoteFailure(value)` is the one predicate a consumer needs — a caught value it accepts carries a Host code, and anything it rejects is a local fault the caller should let crash. `carrierFailure(endpoint, error)` and `cancelledFailure(endpoint, cause)` build those two folded results, so a test stand-in for this face folds identically. diff --git a/packages/api/gateway/README.zh.md b/packages/api/gateway/README.zh.md index 23b83fbf2c..f9f2068eb5 100644 --- a/packages/api/gateway/README.zh.md +++ b/packages/api/gateway/README.zh.md @@ -26,7 +26,7 @@ kind: "package-reference" 每次调用时,`ctx.typertGateway.invoke()` 都会解析当前的描述符和 Cordis 服务,校验具名参数是否完全匹配,解析已注册的对象或 Context 身份标识,并调用公开的业务方法。业务服务继承 [`dsh-typert-protocol`](../../typert/protocol/README.zh.md) 的 `TypertRemoteService`,并用 `@Remote` 或 `@RemoteScope` 标记方法;已有其他基类时仍可改用 `bindTypertRemote()`。 -严格模式从 `ctx.typert.local` 读取生成的调用描述符。查找参数使用 `ctx.typert.lookups` 中当前有效的解析器:业务包注册稳定声明与默认策略,Host 组合可用 effect-scoped `configure()` 覆盖解析行为;`@RemoteScope` 则通过已注册的 Host Context 适配器解析其接收者。SRC 模式是开发阶段的回退路径,适用于从未具备严格定义的端点;它解析简单参数名,并且只允许非查找参数使用可安全表示为 JSON 的值。已观测到的严格定义一旦撤回,系统会直接报错,而不会降低校验强度。 +严格模式从 `ctx.typert.local` 读取生成的调用描述符。查找参数使用 `ctx.typert.lookups` 中当前有效的解析器:业务包注册稳定声明与默认策略,Host 组合可用 effect-scoped `configure()` 覆盖解析行为;`@RemoteScope` 则通过已注册的 Host Context 适配器解析其接收者。SRC 模式是开发阶段的回退路径,适用于从未具备严格定义的端点;它解析简单参数名,并且只允许非查找参数使用可安全表示为 JSON 的值。已观测到的严格定义一旦撤回,系统会直接报错,而不会降低校验强度。对于一元结果,Gateway 在生成 codec 提供 `encode()` 时执行它,否则保持 strict JSON 值不变;SRC 则递归识别运行时字节值。两条路径都向 Connection 返回 JSON 兼容元数据及相对于结果的字节附件,由 Connection 完成传输帧封装。 Connection 可用时,Host 入口会在 Connection 共享的 `/api` FetchHandler 上注册 trusted-host interceptor。Connection 把这个复合 handler 交给 HTTP bridge;handler 将已认领 endpoint 分发给 Gateway,未认领且没有精确 Fetch 路由负责的请求返回 404。直接调用 `invoke()` 会保留业务错误;`TypertGatewayError` 是 `RemoteError` 的子类,其 `gateway/*` 码命名了分发、绑定、提供方、查找、Context、参数、编解码器以及上行各自负责的故障:缓冲帧超过 `streamInboxBytes` 的上行报 `gateway/uplink-overflow`,`end` 之后的上行项报 `gateway/protocol`,被 codec 拒绝的上行项报编解码码 `gateway/input-invalid`。因策略而拒绝的解析器——冷恢复失败或 ownership fence——抛出自己的 `RemoteError`,它选定的码原样到达调用方。 @@ -45,7 +45,7 @@ Host 组合可通过 `registerRemoteEvents()` 注册唯一的应用事件 source `ctx.remote.$mount()` 会校验并注册生成的 Host-for-Client 贡献项,然后为发起调用的 Cordis fiber 安装具体的直接方法和作用域方法。每个 namespace 都是可追踪的 `remote.` 子 Service,并在最后一个方法撤回后卸载。重复端点、命名空间冲突,以及缺少生成的严格 codec 的 Client 供值字段,都会在方法可调用前报错。 -每次一元调用都会检查位置参数数量,构造与描述符完全匹配的具名 `args`,再把带类型的值原样交给 `ctx.connection.rpc.call('/api', endpoint, ...)`,而不执行 Client 侧 schema;Host 会在业务调用前校验收到的 wire 字段。生成的流方法返回 `dsh-typert-protocol` 的 `RemoteStreamHandle`,并在被调用时就打开一条逻辑流,进程内 Connection 载体可用时通过它打开,否则通过共享的 Gateway WebSocket 打开。句柄只迭代下行一次。`send(item)` 把一个上行项入队,在 `open` 帧之后发出;`end()` 半关闭上行;`dispose()` 在未收到终止帧时发送 `cancel`,并让迭代安静结束。提前跳出迭代等价于 dispose 句柄;下行终止后 `send` 抛错,`end` 被忽略。生成的支持取消的方法接受最后一个可选 `AbortSignal`;Client 会在调用载体前将它与贡献项的挂载生命周期合并。成功的一元结果与流项不经 Client 侧类型解析直接传递。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用与流,并使外部仍持有的方法句柄在调用时返回拒绝。 +每次一元调用都会检查位置参数数量,构造与描述符完全匹配的具名 `args`,再把带类型的值原样交给 `ctx.connection.rpc.call('/api', endpoint, ...)`,而不执行 Client 侧 schema;Host 会在业务调用前校验收到的 wire 字段。生成的流方法返回 `dsh-typert-protocol` 的 `RemoteStreamHandle`,并在被调用时就打开一条逻辑流,进程内 Connection 载体可用时通过它打开,否则通过共享的 Gateway WebSocket 打开。句柄只迭代下行一次。`send(item)` 把一个上行项入队,在 `open` 帧之后发出;`end()` 半关闭上行;`dispose()` 在未收到终止帧时发送 `cancel`,并让迭代安静结束。提前跳出迭代等价于 dispose 句柄;下行终止后 `send` 抛错,`end` 被忽略。生成的支持取消的方法接受最后一个可选 `AbortSignal`;Client 会在调用载体前将它与贡献项的挂载生命周期合并。Client 将一元结果转换交给 codec 的可选 `decode()`。生成的解码器校验嵌套元数据与原生字节类型,不逐字节遍历、复制或冻结字节载荷。JSON 一元结果与流项不经 Client 侧类型解析直接传递。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用与流,并使外部仍持有的方法句柄在调用时返回拒绝。 每次一元调用都解析为 `RemoteResult`——`{ ok: true, value }` 或 `{ ok: false, error }`——且绝不因载体问题 reject:本面把断线载体折入错误分支,调用方 signal 中止时答以 `gateway/cancelled`,因此没有消费方需要包一层来兜载体失败。只有装配故障仍会 reject:参数个数不符、方法未挂载、贡献已撤下、缺少 Context 适配器。`error` 是活的 `RemoteError` 实例,所以 `throw result.error` 保持 throw 语义;而 `isRemoteFailure(value)` 是消费方唯一需要的谓词——它认下的捕获值带着 Host 码,它拒绝的一律是本地故障,调用方应当让其崩掉。`carrierFailure(endpoint, error)` 与 `cancelledFailure(endpoint, cause)` 构造这两种折叠结果,测试里的替代实现据此采用相同的折叠方式。 diff --git a/packages/api/gateway/src/client/index.ts b/packages/api/gateway/src/client/index.ts index 43992cb60e..9a6cb07d16 100644 --- a/packages/api/gateway/src/client/index.ts +++ b/packages/api/gateway/src/client/index.ts @@ -444,8 +444,12 @@ class ClientRemoteService extends Service implements ClientRemote { try { const result = await connection.rpc.call('/api', endpoint, { args: prepared.args }, prepared.signal) if (!mountActive(token)) return withdrawn(endpoint) + prepared.signal.throwIfAborted() if (!result.ok) return { ok: false, error: rebuiltFailure(result.error) } - return { ok: true, value: result.value } + const value = descriptor.result.mode === 'strict' && descriptor.result.decode !== undefined + ? descriptor.result.decode(result.value) + : result.value + return { ok: true, value } } catch (error) { // Carrier throws (offline or abort) are outcomes of the call, not assembly // faults, so they join the same error branch. A caller-aborted call is a diff --git a/packages/api/gateway/src/index.ts b/packages/api/gateway/src/index.ts index 02b4c7fbbb..d9bc91d52a 100644 --- a/packages/api/gateway/src/index.ts +++ b/packages/api/gateway/src/index.ts @@ -7,7 +7,11 @@ import { randomUUID } from 'node:crypto' import { Context, Service, symbols } from '@deepseek-ai/cordis' -import { OperatorPeer, type ConnectionRpcHandler } from '@deepseek-ai/dsh-client-connection' +import { + OperatorPeer, + type ConnectionRpcAttachment, + type ConnectionRpcHandler, +} from '@deepseek-ai/dsh-client-connection' import { Deque } from '@deepseek-ai/dsh-deque' import type { WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver' import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout' @@ -325,7 +329,10 @@ export class TypertGatewayService extends Service implements TypertGateway { * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; lookup-policy and business errors retain identity. */ async invoke(request: InvokeRemoteRequest): Promise { - const prepared = await this.prepareInvocation(request, new AbortController()) + return this.invokePrepared(await this.prepareInvocation(request, new AbortController())) + } + + private async invokePrepared(prepared: PreparedInvocation): Promise { if (prepared.descriptor.mode !== undefined) { throw new TypertGatewayError( 'gateway/signature-invalid', @@ -337,7 +344,7 @@ export class TypertGatewayService extends Service implements TypertGateway { try { return await Reflect.apply(prepared.method, prepared.receiver, prepared.args) as unknown } catch (error) { - if (request.signal?.aborted === true) throw remoteCancelled(prepared.endpoint, error) + if (prepared.invocation.signal.aborted) throw remoteCancelled(prepared.endpoint, error) throw error } finally { // A unary call's uplink is readable only while the method runs. @@ -647,11 +654,15 @@ export class TypertGatewayService extends Service implements TypertGateway { peer: PeerScope, ): Promise { try { - const value = await this.invoke(remoteRequest(endpoint, payload, signal, peer)) + const prepared = await this.prepareInvocation( + remoteRequest(endpoint, payload, signal, peer), + new AbortController(), + ) + const value = await this.invokePrepared(prepared) // A void or explicitly absent business result carries no `value` field; // JSON has no `undefined`, and the envelope's optional slot is the one // representation of absence that both args and results already use. - return { ok: true, value } + return encodeRpcResult(value, prepared.descriptor.result) } catch (error) { return rpcFailure(error) } @@ -963,6 +974,67 @@ export class TypertGatewayService extends Service implements TypertGateway { } } +function encodeRpcResult(value: unknown, codec: TypertCodec): ConnectionRpcResult { + const attachments: ConnectionRpcAttachment[] = [] + const writeBytes = (bytes: Uint8Array, path: readonly (string | number)[]): null => { + attachments.push({ path: [...path], bytes }) + return null + } + const encoded = codec.mode === 'strict' + ? codec.encode?.(value, writeBytes) ?? value + : encodeRuntimeResult(value, writeBytes) + return { ok: true, value: encoded, ...(attachments.length === 0 ? {} : { attachments }) } +} + +function encodeRuntimeResult( + input: unknown, + writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null, +): unknown { + const path: (string | number)[] = [] + const ancestors = new Set() + const extract = (input: unknown, key: string): unknown => { + // Capture accessors and toJSON once, before materializing the JSON metadata. + let value = input + if (input !== null && typeof input === 'object' && !(input instanceof Uint8Array)) { + const toJSON: unknown = Reflect.get(input, 'toJSON') + if (typeof toJSON === 'function') value = Reflect.apply(toJSON, input, [key]) + } + if (value instanceof Uint8Array) return writeBytes(value, path) + if (typeof value !== 'object' || value === null) return value + if (value instanceof Number || value instanceof String || value instanceof Boolean) return value.valueOf() + if (ancestors.has(value)) throw new TypeError('gateway: circular RPC result') + ancestors.add(value) + let copy: object + if (Array.isArray(value)) { + const items: unknown[] = [] + // JSON arrays include every index, even holes and non-enumerable elements. + for (let index = 0, length = value.length; index < length; index++) items.push(child(value[index], index)) + copy = items + } else { + const fields: Record = {} + for (const key of Object.keys(value)) { + const item: unknown = Reflect.get(value, key) + // A toJSON method on the projected object must not run a second time. + if (key === 'toJSON' && typeof item === 'function') continue + const extracted = child(item, key) + if (key === '__proto__') Object.defineProperty(fields, key, { value: extracted, enumerable: true }) + else fields[key] = extracted + } + copy = fields + } + ancestors.delete(value) + return copy + } + const child = (value: unknown, key: string | number): unknown => { + if (typeof value !== 'object' || value === null) return value + path.push(key) + const extracted = extract(value, String(key)) + path.pop() + return extracted + } + return extract(input, 'value') +} + type RemoteEventWireFrame = | RemoteEventEmitFrame | RemoteEventInvocationFrame diff --git a/packages/api/gateway/tests/gateway.client.spec.ts b/packages/api/gateway/tests/gateway.client.spec.ts index ddd6a846b8..aeec14ecf1 100644 --- a/packages/api/gateway/tests/gateway.client.spec.ts +++ b/packages/api/gateway/tests/gateway.client.spec.ts @@ -24,7 +24,7 @@ import type { } from '@deepseek-ai/dsh-typert-protocol' import TypertRegistry from '@deepseek-ai/dsh-typert-registry' import type { ClientRemote } from '../src/client/index.ts' -import { apply, inject, RemoteStream } from '../src/client/index.ts' +import { apply, inject, isRemoteFailure, RemoteStream } from '../src/client/index.ts' import { ClientUplinkQueue, RemoteStreamCarrierError, @@ -95,6 +95,7 @@ declare module '@deepseek-ai/dsh-typert-protocol' { signal?: AbortSignal, ) => Promise> 'probe/maybe': (value: string | null | undefined) => Promise> + 'probe/bytes': (signal?: AbortSignal) => Promise; readonly offset: number }>> 'probe/watch': (topic: string, signal?: AbortSignal) => AsyncIterable 'probe/attach': (topic: string, signal?: AbortSignal) => RemoteStreamHandle } @@ -3156,6 +3157,96 @@ async function withFakeWebSocket( } } +describe('Remote result decoders', () => { + const schema = z.object({ data: z.instanceof(Uint8Array), offset: z.number() }) + const descriptor: InvocationDescriptor = { + id: '@fixture/probe#probe/bytes', + service: 'probe', namespace: 'probe', method: 'bytes', + invocation: { kind: 'direct' }, parameters: [], + cancellation: { parameter: 'signal' }, + result: { + mode: 'strict', typeSymbol: '@fixture#Bytes', + create: () => schema, + decode: value => schema.parse(value), + }, + } + + it('validates metadata without copying or freezing native data on a logical RPC carrier', async () => { + const data = new Uint8Array([0, 128, 255]) + const call = vi.fn().mockResolvedValue({ ok: true, value: { data, offset: 2 } }) + const { ctx, client } = await benchFiber(call) + try { + await ctx.remote.$mount({ package: '@fixture/binary', descriptors: [descriptor] }) + const result = await ctx.remote.probe.bytes() + expect(result).toEqual({ ok: true, value: { data, offset: 2 } }) + if (result.ok) expect(result.value.data).toBe(data) + expect(Object.isFrozen(data)).toBe(false) + for (const value of [{ data: 'base64', offset: 2 }, { data: [0, 128], offset: 2 }, { data, offset: '2' }]) { + call.mockResolvedValueOnce({ ok: true, value }) + const failure = await ctx.remote.probe.bytes() + expect(failure).toMatchObject({ ok: false, error: { code: 'gateway/internal' } }) + if (!failure.ok) expect(isRemoteFailure(failure.error)).toBe(true) + } + } finally { + await client.dispose() + } + }) + + it('delegates nested fields to the result decoder and leaves JSON results untouched', async () => { + const data = new Uint8Array([0, 128, 255]) + const value = { files: [{ content: data }], thumbnail: data } + const call = vi.fn().mockResolvedValue({ ok: true, value }) + const decode = vi.fn((input: unknown) => z.object({ + files: z.array(z.object({ content: z.instanceof(Uint8Array) })), + thumbnail: z.instanceof(Uint8Array), + }).parse(input)) + const { ctx, client } = await benchFiber(call) + try { + const dispose = await ctx.remote.$mount({ + package: '@fixture/binary', descriptors: [{ + ...descriptor, result: { mode: 'strict', typeSymbol: '@fixture#Files', create: () => schema, decode }, + }], + }) + expect(await ctx.remote.probe.bytes()).toEqual({ ok: true, value }) + expect(decode).toHaveBeenCalledWith(value) + expect((decode.mock.results[0]?.value as ReturnType).files[0]?.content).toBe(data) + expect(Object.isFrozen(data)).toBe(false) + await dispose() + const json = { base64: 'AP8=', items: [1, 2] } + call.mockResolvedValue({ ok: true, value: json }) + const create = vi.fn(() => schema) + await ctx.remote.$mount({ package: '@fixture/json', descriptors: [{ + ...descriptor, result: { mode: 'strict', typeSymbol: '@fixture#Json', create }, + }] }) + const result = await ctx.remote.probe.bytes() + if (result.ok) expect(result.value).toBe(json) + expect(create).not.toHaveBeenCalled() + } finally { + await client.dispose() + } + }) + + it.each(['cancel', 'withdraw'] as const)('discards late binary results after %s', async (action) => { + const response = Promise.withResolvers>>() + const call = vi.fn().mockReturnValue(response.promise) + const { ctx, client } = await benchFiber(call) + try { + const dispose = await ctx.remote.$mount({ package: '@fixture/binary', descriptors: [descriptor] }) + const abort = new AbortController() + const pending = ctx.remote.probe.bytes(abort.signal) + expect(call).toHaveBeenCalledOnce() + if (action === 'cancel') abort.abort() + else await dispose() + response.resolve({ ok: true, value: { data: new Uint8Array([7]), offset: 0 } }) + expect(await pending).toMatchObject({ + ok: false, error: { code: action === 'cancel' ? 'gateway/cancelled' : 'gateway/internal' }, + }) + } finally { + await client.dispose() + } + }) +}) + async function drainStream(source: AsyncIterable): Promise { const values: unknown[] = [] for await (const value of source) values.push(value) diff --git a/packages/api/gateway/tests/gateway.host.spec.ts b/packages/api/gateway/tests/gateway.host.spec.ts index 94f75e9138..24522ce846 100644 --- a/packages/api/gateway/tests/gateway.host.spec.ts +++ b/packages/api/gateway/tests/gateway.host.spec.ts @@ -4,7 +4,12 @@ import { describe, expect, it } from 'vitest' import { Context, Service, symbols } from '@deepseek-ai/cordis' import { z } from 'zod' import { apply as applyConnection, inject as connectionInject } from '@deepseek-ai/dsh-client-connection' -import type { HostConnectionHandle, PeerId, PeerScope } from '@deepseek-ai/dsh-client-connection' +import type { + ConnectionRpcHandler, + HostConnectionHandle, + PeerId, + PeerScope, +} from '@deepseek-ai/dsh-client-connection' import type { WebServer, WebRoute } from '@deepseek-ai/dsh-host-webserver' import { bindTypertRemote, @@ -53,6 +58,7 @@ class GoalService extends Service { readonly typertRemote = bindTypertRemote(this, 'goals') readonly calls: string[] = [] lastSignal: AbortSignal | undefined + lastPeer: PeerScope | undefined nextResult: unknown = undefined businessError: Error | undefined @@ -64,6 +70,7 @@ class GoalService extends Service { create(agent: FixtureAgent, request: { readonly title: string }, signal: AbortSignal): unknown { this.calls.push('create') this.lastSignal = signal + this.lastPeer = this.ctx.invocation?.peer return { agentId: agent.id, title: request.title, @@ -102,10 +109,7 @@ class GoalService extends Service { } } -type FakeRpcResult = - | { readonly ok: true; readonly value: unknown } - | { readonly ok: false; readonly error: { readonly code: string; readonly message: string; readonly details: object } } - +type FakeRpcResult = Awaited> type FakeRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal) => Promise class FakeConnectionService extends Service { @@ -126,12 +130,12 @@ class FakeConnectionService extends Service { intercept: ( channel: string, matches: (endpoint: string) => boolean, - handler: FakeRpcHandler, + handler: ConnectionRpcHandler, ) => owner.effect(() => { this.channel = channel this.matches = matches - this.handler = handler + this.handler = (endpoint, payload, signal) => handler(endpoint, payload, signal, this.operator) return () => { this.channel = undefined this.matches = undefined @@ -996,16 +1000,25 @@ describe('TypertGatewayService', () => { const signal = abort.signal const handler = connection.handler if (handler === undefined) throw new Error('fixture Connection did not retain the /api interceptor') - await expect(handler('goals/create', { + const success = await handler('goals/create', { args: { agentId: 'agent-1', request: { title: 'ship' } }, - }, signal)).resolves.toEqual({ + }, signal) + expect(success).toMatchObject({ ok: true, value: { agentId: 'agent-1', title: 'ship', scope: 'rpc-caller' }, }) + if (!success.ok) throw new Error('fixture Remote failed') + expect(success.attachments).toBeUndefined() const service = rawGoalService(ctx) expect(service.lastSignal).toBe(signal) abort.abort(new Error('client disconnected')) expect(service.lastSignal?.aborted).toBe(true) + await expect(ctx.typertGateway.invoke({ + namespace: 'goals', + method: 'create', + args: { agentId: 'agent-1', request: { title: 'direct' } }, + })).resolves.toMatchObject({ title: 'direct' }) + expect(service.lastPeer).toBe(connection.operator) const invalid = await handler('goals/create', { invalid: true }, signal) expect(invalid).toMatchObject({ ok: false, @@ -1014,11 +1027,11 @@ describe('TypertGatewayService', () => { if (invalid.ok) throw new Error('invalid Remote payload unexpectedly succeeded') expect(invalid.error.message).toMatch(/exactly one plain-object args field/) - await expect(handler('goals/maybe', { args: {} }, signal)).resolves.toEqual({ + await expect(handler('goals/maybe', { args: {} }, signal)).resolves.toMatchObject({ ok: true, value: undefined, }) - await expect(handler('goals/maybe', { args: { value: null } }, signal)).resolves.toEqual({ + await expect(handler('goals/maybe', { args: { value: null } }, signal)).resolves.toMatchObject({ ok: true, value: null, }) @@ -1068,6 +1081,112 @@ describe('TypertGatewayService', () => { expect(connection.handler).toBeUndefined() }) + it('projects strict and SRC result bytes before returning to Connection', async () => { + const { ctx } = await setup() + const fiber = ctx.plugin(FakeConnectionService) + await fiber + try { + const value = { content: new Uint8Array([0, 128, 255]) } + rawGoalService(ctx).nextResult = value + const handler = rawConnection(ctx).handler! + const source = await handler('goals/passthrough', { args: { value: null } }, new AbortController().signal) + expect(source).toEqual({ + ok: true, + value: { content: null }, + attachments: [{ path: ['content'], bytes: value.content }], + }) + const descriptor = passthroughDescriptor() + const codec = { + mode: 'strict' as const, + typeSymbol: '@fixture/gateway#Bytes', + create: () => z.object({ content: z.instanceof(Uint8Array) }), + encode: (input: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => { + const result = input as { readonly content: Uint8Array } + return { content: writeBytes(result.content, ['content']) } + }, + } + const remove = registerStrict(ctx, [{ ...descriptor, result: codec }]) + const strict = await handler('goals/passthrough', { args: { value: null } }, new AbortController().signal) + expect(strict).toEqual({ + ok: true, + value: { content: null }, + attachments: [{ path: ['content'], bytes: value.content }], + }) + await remove() + } finally { + await fiber.dispose() + } + }) + + it('owns runtime result projection for SRC methods', async () => { + const { ctx, service } = await setup() + const fiber = ctx.plugin(FakeConnectionService) + await fiber + try { + const handler = rawConnection(ctx).handler! + const call = () => handler('goals/passthrough', { args: { value: null } }, new AbortController().signal) + let reads = 0 + const bytes = new Uint8Array([1, 2]) + service.nextResult = { get content() { reads++; return bytes }, get count() { return ++reads } } + await expect(call()).resolves.toEqual({ + ok: true, + value: { content: null, count: 2 }, + attachments: [{ path: ['content'], bytes }], + }) + expect(reads).toBe(2) + + const array: Uint8Array[] = [] + Object.defineProperty(array, 0, { value: bytes }) + service.nextResult = array + await expect(call()).resolves.toEqual({ + ok: true, + value: [null], + attachments: [{ path: [0], bytes }], + }) + + service.nextResult = Object.assign(new Date('2026-01-01T00:00:00Z'), { content: bytes }) + await expect(call()).resolves.toEqual({ ok: true, value: '2026-01-01T00:00:00.000Z' }) + const json = { self: {} as object, toJSON: () => ({ selected: true }) } + json.self = json + service.nextResult = json + await expect(call()).resolves.toEqual({ ok: true, value: { selected: true } }) + let conversions = 0 + service.nextResult = { toJSON(key: string) { conversions++; expect(key).toBe('value'); return this }, count: 5 } + await expect(call()).resolves.toEqual({ ok: true, value: { count: 5 } }) + expect(conversions).toBe(1) + for (const primitive of [1, 'text', true]) { + service.nextResult = Object(primitive) as object + await expect(call()).resolves.toEqual({ ok: true, value: primitive }) + } + service.nextResult = { toJSON: 'ordinary' } + await expect(call()).resolves.toEqual({ ok: true, value: service.nextResult }) + + const protectedName = JSON.parse('{"__proto__":null}') as Record + Object.defineProperty(protectedName, '__proto__', { value: bytes, enumerable: true }) + service.nextResult = protectedName + const protectedResult = await call() + expect(protectedResult).toMatchObject({ + ok: true, + attachments: [{ path: ['__proto__'], bytes }], + }) + if (!protectedResult.ok || typeof protectedResult.value !== 'object' || protectedResult.value === null) { + throw new Error('SRC protected-name result was not projected') + } + expect(Object.hasOwn(protectedResult.value, '__proto__')).toBe(true) + expect(Reflect.get(protectedResult.value, '__proto__')).toBeNull() + + const circular: { next?: object } = {} + circular.next = circular + service.nextResult = circular + await expect(call()).resolves.toMatchObject({ + ok: false, + error: { code: 'gateway/internal', message: 'gateway: circular RPC result' }, + }) + } finally { + await fiber.dispose() + } + }) + it('claims and validates in-process Remote event results for the active Client generation', async () => { const ctx = new Context() await ctx.plugin(TypertRegistry) diff --git a/packages/api/workspace-files/README.i18n.yaml b/packages/api/workspace-files/README.i18n.yaml index 7611258318..0f0e41d9c1 100644 --- a/packages/api/workspace-files/README.i18n.yaml +++ b/packages/api/workspace-files/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/api/workspace-files/README.md -README.md: 6e5025b8f5543d810fa951acf5baa32a3c060494 -README.zh.md: c913145966cc982e10c7a533274941c6c52b8b55 +README.md: 0345887e58975b9ef2764144ded20a4f25e8f04d +README.zh.md: 572b83ec37696ee32ba9c3e1e0babdf696afe903 diff --git a/packages/api/workspace-files/README.md b/packages/api/workspace-files/README.md index 6e5025b8f5..0345887e58 100644 --- a/packages/api/workspace-files/README.md +++ b/packages/api/workspace-files/README.md @@ -25,29 +25,29 @@ Use this package to preview files readable through a Session's filesystem from t ## Use this package -Mount the package beside `dsh-fs`, `dsh-sandbox-policy`, the Session store, and the Typert Gateway; the bundle does so right after the Session Controller. Every method takes the Session identity on the wire, so a Client calls `remote.workspaceFiles.read(sessionId, path, range, signal)`, `stat(sessionId, path, signal)`, `readBytes(sessionId, path, range, signal)`, `list(sessionId, path, signal)`, or `changes(sessionId, path, signal)` and never names a root itself. The Host reads a live Session header or uses persistence `stat` for a cold Session; it does not activate an Agent, read the event body, or borrow a parent Session's root. Session persistence is optional for live reads, but without it a cold Session cannot resolve and the Gateway returns `gateway/lookup-not-found`. +Mount the package beside `dsh-fs`, `dsh-sandbox-policy`, the Session store, and the Typert Gateway; the bundle does so right after the Session Controller. Every method takes the Session identity on the wire, so a Client calls `remote.workspaceFiles.read(sessionId, path, range, signal)`, `stat(sessionId, path, signal)`, `readBytes(sessionId, path, options, signal)`, `list(sessionId, path, signal)`, or `changes(sessionId, path, signal)` and never names a root itself. The Host reads a live Session header or uses persistence `stat` for a cold Session; it does not activate an Agent, read the event body, or borrow a parent Session's root. Session persistence is optional for live reads, but without it a cold Session cannot resolve and the Gateway returns `gateway/lookup-not-found`. | Method | Returns | Purpose | |---|---|---| | `stat(path)` | `WorkspaceFileStat { absolutePath, version, bytes? }` | Identity, version, and size of one regular file, without content | | `read(path, { offset?, limit? })` | `WorkspaceFileText` = stat + `{ offset, text, lines, eof }` | One window of lines from a UTF-8 text file; `lines` counts them, so one empty line and a page past the end read differently | -| `readBytes(path, { offset?, length? })` | `WorkspaceFileBytes` = stat + `{ offset, data, eof }` | One window of raw bytes from any regular file, base64-encoded | -| `readAll(path)` | `WorkspaceFileBytes` with `offset: 0`, `eof: true` | Complete raw bytes under `maxFileBytes`; oversized files fail instead of being truncated | -| `readRelated(path, relativePath)` | `WorkspaceFileBytes` | Complete bytes of a file resolved from the base file's directory on the Host | +| `readBytes(path, { range?, baseFile? })` | `WorkspaceFileBytes` = stat + `{ offset, data, eof }` | Complete file or bounded byte range as `Uint8Array`; optionally resolve from another file's directory | | `list(path)` | `WorkspaceDirectoryListing { path, entries, truncated }` | Direct children of one directory | | `changes(path)` | stream of `WorkspaceFileWatchFrame` | Subscription readiness, then invalidations of one file or a directory's direct entries | ### Addressing and paths -`read`, `readBytes`, `readAll`, `readRelated`, and `stat` accept an absolute path or one relative to the selected Session's workspace root. The composed filesystem decides whether the path is readable; the service does not impose workspace containment on file reads. `readRelated` resolves a relative filesystem path from the base file's directory, including when either file is outside the workspace. These methods report the file's absolute path in the filesystem's execution world. `list` remains workspace-scoped and reports the listed directory relative to that root. `changes` uses the same path resolution: file watches follow file-read authority, while directory watches remain workspace-scoped. +`read`, `readBytes`, and `stat` accept an absolute path or one relative to the selected Session's workspace root. The composed filesystem decides whether the path is readable; the service does not impose workspace containment on file reads. `readBytes` with `options.baseFile` resolves the relative target `path` from that file's directory, including when either file is outside the workspace. The base file itself accepts an absolute or workspace-relative path. Both files receive the same regular-file checks; an empty target, absolute target, URL, or NUL-containing target is rejected. File results report the absolute path in the filesystem's execution world. `list` remains workspace-scoped and reports the listed directory relative to that root. `changes` uses the same path resolution: file watches follow file-read authority, while directory watches remain workspace-scoped. ### Pages `read` returns one line window, never the whole file. `range.offset` is the 1-based first line and defaults to 1; `range.limit` is the largest number of lines on the page and defaults to `maxLines`, which it may not exceed — a larger limit, or an offset or limit that is not a positive integer, is a `gateway/bad-request`. Lines end at `\n`, and a final `\n` terminates the last line rather than starting an empty one, so a two-line file has two lines. The page's `text` joins its lines with `\n` and carries no terminator after the last; `eof` is true when the page includes the file's last line, and an offset past the end returns an empty page with `eof` true. Every page also carries the file's `version` from the stat that preceded it, so a consumer can tell a fresh page from a stale one, and `bytes`, the complete file's size when the backend reports it. The service reads the file only up to the first character past the page, so a very large file costs one page of memory per request. -### Byte windows +### Binary reads -`read` pages by lines and never by bytes; a byte window is `readBytes`. `range.offset` is the 0-based first byte and defaults to 0; `range.length` is the largest number of bytes in the window and defaults to `maxBytes`, which it may not exceed — a longer window fails with `too-large` instead of arriving shortened, and an offset or length that is not an integer in range is a `gateway/bad-request`. The window comes back as base64 `data`, shorter than `length` at the end of the file and empty at or past it; `eof` is true when the window includes the file's last byte. Nothing is decoded and nothing is refused as binary, so an image or a NUL-laden file reads where `read` fails with `not-text`. The same `version` and `bytes` ride along as on a page. +`read` pages by lines and never by bytes; a byte window is `readBytes(path, { range: { offset?, length? } })`. `options.range.offset` is the 0-based first byte and defaults to 0; `options.range.length` is the largest number of bytes in the window and defaults to `maxBytes`, which it may not exceed — a longer window fails with `too-large` instead of arriving shortened, and an offset or length that is not an integer in range is a `gateway/bad-request`. The window comes back as `Uint8Array` data, shorter than `length` at the end of the file and empty at or past it; `eof` is true when the window includes the file's last byte. Nothing is decoded and nothing is refused as binary, so an image or a NUL-laden file reads where `read` fails with `not-text`. The same `version` and `bytes` ride along as on a page. + +Pass the required options object as `{}` for a complete file under `maxFileBytes`, or `{ range: {} }` for the default byte window under `maxBytes`. Oversized complete files fail rather than arriving truncated. `baseFile` and `range` can be combined, and windows remain independent of the complete-file cap. The binary Remote uses Connection's multipart response with JSON metadata and raw bytes; the generated Client returns `Uint8Array` without base64 decoding. Caller cancellation reaches the filesystem. The endpoint returns data, not a navigable document. ### File-read and directory checks @@ -62,7 +62,7 @@ File reads and directory listing first use `lstat` to reject a missing path, a f | Field | Default | Meaning | |---|---|---| | `maxBytes` | `2097152` (2 MiB) | Inclusive byte cap on one page's text and on one byte window; a larger page or window fails | -| `maxFileBytes` | `33554432` (32 MiB) | Inclusive complete-file cap for `readAll` and `readRelated`; larger files fail with `too-large` | +| `maxFileBytes` | `33554432` (32 MiB) | Inclusive complete-file cap for `readBytes` without `range`; larger files fail with `too-large` | | `maxLines` | `5000` | Default and largest page size in lines; a larger `limit` is refused | | `maxEntries` | `2000` | Cap on returned directory entries; the rest is dropped and reported cut | @@ -74,7 +74,7 @@ Each failure is one `RemoteError` code with typed details, declared in [`src/typ ### Client file resources -The browser export registers the `file` provider into `ctx.resources` and requires `resources`, `remote`, and `remote.workspaceFiles`. The bundle's single `workspace-files` row supplies both faces; the Client has no separate configuration. A component reads `WorkspaceFileStat { absolutePath, version, bytes? }` metadata through `useResource<'file'>(address)` and fetches content separately through Remote reads. Any UI, including Global components, shares the observation for the same complete address. +The browser export registers the `file` provider into `ctx.resources` and requires `resources`, `remote`, and `remote.workspaceFiles`. The bundle's single `workspace-files` row supplies both faces; the Client has no separate configuration. A component reads `WorkspaceFileStat { absolutePath, version, bytes? }` metadata through `useResource<'file'>(address)` and fetches content separately through the text or binary Remote. Any UI, including Global components, shares the observation for the same complete address. A `session//` address carries the authorizing Session and a relative or absolute path; leading slashes are preserved, as in `dsh-resource://file/session/s//etc/hosts`. The Host receives the path unchanged and owns resolution and access checks; the Client needs no Session `cwd`. `absolute/` remains parseable but has no authorizing Session and fails with `workspace-file/unknown-workspace`, without borrowing current or Tab Session. Unsupported addresses fail with `workspace-file/unsupported-address`. [Workspace-path](../../util/workspace-path/README.md) owns the grammar; the generic Resource layer knows only the address and `signal`. @@ -94,13 +94,13 @@ One supervised `changes` stream serves each Session and requested path; consumer Reads through `ctx.fs` use the backend's read authority; the sandboxing backend fences writes and edits, not reads. A Typert lookup derives `WorkspaceFileScope` from a live Session header or the persistence service's header-only `stat`, so cold subagent Sessions need neither Agent activation nor event-body reads. The service adds regular-file checks and bounded transfer, while workspace containment belongs only to directory listing and directory watching. A page is cut from `streamText`, which decodes and rejects non-UTF-8 chunk by chunk: the cutter counts lines before the window without keeping them, admits each in-window segment against the byte cap before buffering it, and returns at the first character past the window. One `stat` before the stream names the version and size the page reports. -Complete-file reads delegate size enforcement to `fs.readBytes` and encode the returned bytes as base64 for Remote responses. +Complete-file reads delegate size enforcement to `fs.readBytes` and return raw bytes through the binary Remote. ### Source map | File | Role | |---|---| -| [`src/index.ts`](src/index.ts) | `WorkspaceFiles`: the `workspaceFiles` service and Remote namespace, `Config`, the gates, the page cutter, `read`, `readBytes`, `readAll`, `readRelated`, `stat`, `list` | +| [`src/index.ts`](src/index.ts) | `WorkspaceFiles`: the `workspaceFiles` service and Remote namespace, `Config`, the gates, the page cutter, `read`, `readBytes`, `stat`, `list` | | [`src/changes.ts`](src/changes.ts) | `WorkspaceChangeFeed`: target watchers, matching `fs/observed` notifications, and one queue per generation | | [`src/types.ts`](src/types.ts) | Wire types and the `RemoteErrorDetailsMap` codes, published as `./types` for Client packages | | [`src/client/index.ts`](src/client/index.ts), [`provider.ts`](src/client/provider.ts), [`change-feed.ts`](src/client/change-feed.ts) | Browser plugin, file metadata, and per-target change feeds | diff --git a/packages/api/workspace-files/README.zh.md b/packages/api/workspace-files/README.zh.md index c913145966..572b83ec37 100644 --- a/packages/api/workspace-files/README.zh.md +++ b/packages/api/workspace-files/README.zh.md @@ -25,29 +25,29 @@ kind: "package-reference" ## 使用本包 -把本包与 `dsh-fs`、`dsh-sandbox-policy`、Session store 和 Typert Gateway 一起挂载;bundle 把它紧随 Session Controller 之后挂载。每个方法都在线路上携带 Session 身份,Client 调用 `remote.workspaceFiles.read(sessionId, path, range, signal)`、`stat(sessionId, path, signal)`、`readBytes(sessionId, path, range, signal)`、`list(sessionId, path, signal)` 或 `changes(sessionId, path, signal)`,从不自己指定根。Host 读取 live Session header,cold Session 则使用持久层 `stat`;它不会激活 Agent、读取事件正文或借用父 Session 的根。live 读取不要求挂载 Session persistence;未挂载时 cold Session 无法解析,Gateway 返回 `gateway/lookup-not-found`。 +把本包与 `dsh-fs`、`dsh-sandbox-policy`、Session store 和 Typert Gateway 一起挂载;bundle 把它紧随 Session Controller 之后挂载。每个方法都在线路上携带 Session 身份,Client 调用 `remote.workspaceFiles.read(sessionId, path, range, signal)`、`stat(sessionId, path, signal)`、`readBytes(sessionId, path, options, signal)`、`list(sessionId, path, signal)` 或 `changes(sessionId, path, signal)`,从不自己指定根。Host 读取 live Session header,cold Session 则使用持久层 `stat`;它不会激活 Agent、读取事件正文或借用父 Session 的根。live 读取不要求挂载 Session persistence;未挂载时 cold Session 无法解析,Gateway 返回 `gateway/lookup-not-found`。 | 方法 | 返回 | 用途 | |---|---|---| | `stat(path)` | `WorkspaceFileStat { absolutePath, version, bytes? }` | 一个普通文件的身份、版本与大小,不含内容 | | `read(path, { offset?, limit? })` | `WorkspaceFileText` = stat + `{ offset, text, lines, eof }` | UTF-8 文本文件的一个行窗口;`lines` 计行数,使单个空行与越过文件末尾的页可区分 | -| `readBytes(path, { offset?, length? })` | `WorkspaceFileBytes` = stat + `{ offset, data, eof }` | 任意普通文件的一个原始字节窗口,base64 编码 | -| `readAll(path)` | `WorkspaceFileBytes`,其中 `offset: 0`、`eof: true` | `maxFileBytes` 内的完整原始字节;超大文件失败,不截断 | -| `readRelated(path, relativePath)` | `WorkspaceFileBytes` | Host 从基文件目录解析出的文件的完整字节 | +| `readBytes(path, { range?, baseFile? })` | `WorkspaceFileBytes` = stat + `{ offset, data, eof }` | 以 `Uint8Array` 返回完整文件或有界字节范围;可从另一个文件所在目录解析目标 | | `list(path)` | `WorkspaceDirectoryListing { path, entries, truncated }` | 一个目录的直接子项 | | `changes(path)` | `WorkspaceFileWatchFrame` 流 | 订阅就绪确认,随后为单个文件或目录直接子项的失效通知 | ### 寻址与路径 -`read`、`readBytes`、`readAll`、`readRelated` 与 `stat` 接受绝对路径或相对于所选 Session 工作区根的路径。组合文件系统决定路径是否可读;本服务不额外要求文件读取限定于工作区。`readRelated` 从基文件所在目录解析相对文件系统路径,基文件或目标文件位于工作区外时同样适用。这些方法以文件系统执行环境中的绝对路径报告文件。`list` 仍限定于工作区,并以相对于该根的路径报告被列举目录。`changes` 使用相同的路径解析:文件监听沿用文件读取权限,目录监听仍限定于工作区。 +`read`、`readBytes` 与 `stat` 接受绝对路径或相对于所选 Session 工作区根的路径。组合文件系统决定路径是否可读;本服务不额外要求文件读取限定于工作区。`readBytes` 携带 `options.baseFile` 时,从基准文件所在目录解析相对目标 `path`,基准文件或目标文件位于工作区外时同样适用。基准文件本身接受绝对路径或工作区相对路径。两个文件执行相同的普通文件检查;目标为空、绝对路径、URL 或含 NUL 时拒绝。文件结果报告文件系统执行环境中的绝对路径。`list` 仍限定于工作区,并以相对于该根的路径报告被列举目录。`changes` 使用相同的路径解析:文件监听沿用文件读取权限,目录监听仍限定于工作区。 ### 分页 `read` 返回一个行窗口,绝不返回整个文件。`range.offset` 是 1 起算的首行,缺省为 1;`range.limit` 是该页最多的行数,缺省为 `maxLines` 且不得超过它——更大的 limit,或不是正整数的 offset / limit,都是 `gateway/bad-request`。行以 `\n` 结束,末尾的 `\n` 是最后一行的终止符而不是再起一空行,所以两行文件就是两行。页的 `text` 以 `\n` 连接各行,最后一行之后不带终止符;`eof` 在该页含文件最后一行时为 true,offset 越过末尾则返回空页且 `eof` 为 true。每页还带上前置 stat 得到的文件 `version`,消费方据此分辨新页与旧页,以及 `bytes`——后端能报告时的整文件大小。服务只把文件读到该页之后的第一个字符为止,所以再大的文件每次请求也只占一页内存。 -### 字节窗口 +### 二进制读取 -`read` 按行分页,绝不按字节;字节窗口走 `readBytes`。`range.offset` 是 0 起算的首字节,缺省为 0;`range.length` 是窗口最多的字节数,缺省为 `maxBytes` 且不得超过它——更长的窗口以 `too-large` 失败而不是被截短,不是整数或越界的 offset / length 则是 `gateway/bad-request`。窗口以 base64 的 `data` 返回,到文件末尾时短于 `length`,位于或越过末尾时为空;窗口含文件最后一个字节时 `eof` 为 true。不做任何解码,也不按二进制拒绝,因此图片或含 NUL 的文件在 `read` 以 `not-text` 失败之处仍可读出。与页一样附带同一 `version` 与 `bytes`。 +`read` 按行分页,绝不按字节;字节窗口走 `readBytes(path, { range: { offset?, length? } })`。`options.range.offset` 是 0 起算的首字节,缺省为 0;`options.range.length` 是窗口最多的字节数,缺省为 `maxBytes` 且不得超过它——更长的窗口以 `too-large` 失败而不是被截短,不是整数或越界的 offset / length 则是 `gateway/bad-request`。窗口以 `Uint8Array` 类型的 `data` 返回,到文件末尾时短于 `length`,位于或越过末尾时为空;窗口含文件最后一个字节时 `eof` 为 true。不做任何解码,也不按二进制拒绝,因此图片或含 NUL 的文件在 `read` 以 `not-text` 失败之处仍可读出。与页一样附带同一 `version` 与 `bytes`。 + +必填的选项对象传 `{}` 时,在 `maxFileBytes` 上限内读取完整文件;传 `{ range: {} }` 时,在 `maxBytes` 上限内读取默认字节窗口。超大完整文件失败,不截断。`baseFile` 与 `range` 可以组合,窗口始终不受完整文件上限约束。二进制 Remote 使用 Connection 的 multipart 响应传递 JSON 元数据与原始字节;生成的 Client 直接返回 `Uint8Array`,无需 base64 解码。调用方取消会传到文件系统。端点返回数据,不提供可导航的文档。 ### 文件读取与目录检查 @@ -62,7 +62,7 @@ kind: "package-reference" | 字段 | 默认值 | 含义 | |---|---|---| | `maxBytes` | `2097152`(2 MiB) | 单页文本与单个字节窗口的字节上限(含);更大的页或窗口失败 | -| `maxFileBytes` | `33554432`(32 MiB) | `readAll` 和 `readRelated` 的完整文件字节上限(含);更大文件以 `too-large` 失败 | +| `maxFileBytes` | `33554432`(32 MiB) | `readBytes` 未传 `range` 时的完整文件字节上限(含);更大文件以 `too-large` 失败 | | `maxLines` | `5000` | 页大小的缺省值与上限(行);更大的 `limit` 被拒绝 | | `maxEntries` | `2000` | 返回目录条目数上限;其余丢弃并报告截断 | @@ -74,7 +74,7 @@ kind: "package-reference" ### Client 文件资源 -浏览器导出向 `ctx.resources` 注册 `file` 提供方,要求 `resources`、`remote` 和 `remote.workspaceFiles` 在场。bundle 中单个 `workspace-files` 条目供应两面;Client 没有单独配置。组件通过 `useResource<'file'>(address)` 读取 `WorkspaceFileStat { absolutePath, version, bytes? }` 元数据,内容另经 Remote 读取。任何 UI(包括 Global)访问同一完整地址都共享观察。 +浏览器导出向 `ctx.resources` 注册 `file` 提供方,要求 `resources`、`remote` 和 `remote.workspaceFiles` 在场。bundle 中单个 `workspace-files` 条目供应两面;Client 没有单独配置。组件通过 `useResource<'file'>(address)` 读取 `WorkspaceFileStat { absolutePath, version, bytes? }` 元数据,文本与字节内容另经对应 Remote 读取。任何 UI(包括 Global)访问同一完整地址都共享观察。 `session//` 地址携带授权 Session,以及相对或绝对路径;前导斜杠保留,例如 `dsh-resource://file/session/s//etc/hosts`。Host 原样接收路径,负责解析与权限检查;Client 不需要 Session `cwd`。`absolute/` 仍可解析,但没有授权 Session,以 `workspace-file/unknown-workspace` 失败,不借用当前或 Tab Session。不支持的地址以 `workspace-file/unsupported-address` 失败。语法由 [workspace-path](../../util/workspace-path/README.zh.md) 定义;Resource 泛型层只认地址和 `signal`。 @@ -94,13 +94,13 @@ kind: "package-reference" 经 `ctx.fs` 的读取使用后端的读取权限;沙箱后端限制写与编辑,而不限制读取。Typert lookup 从 live Session header 或持久层的 header-only `stat` 导出 `WorkspaceFileScope`,所以 cold subagent Session 不需要激活 Agent 或读取事件正文。本服务增加普通文件检查与有界传输,工作区包含要求只属于目录列举与目录监听。页从 `streamText` 切出,后者逐块解码并拒绝非 UTF-8:切页器对窗口之前的行只计数不保留,对窗口内的每个片段先按字节上限验收再缓冲,并在窗口之后的第一个字符处返回。流之前的一次 `stat` 给出页所报告的版本与大小。 -完整文件读取将大小上限检查交给 `fs.readBytes`,并将返回的字节编码为 base64,供 Remote 响应使用。 +完整文件读取将大小上限检查交给 `fs.readBytes`,并通过二进制 Remote 返回原始字节。 ### 源码地图 | 文件 | 职责 | |---|---| -| [`src/index.ts`](src/index.ts) | `WorkspaceFiles`:`workspaceFiles` 服务与 Remote 命名空间、`Config`、四道关、切页器、`read`、`readBytes`、`readAll`、`readRelated`、`stat`、`list` | +| [`src/index.ts`](src/index.ts) | `WorkspaceFiles`:`workspaceFiles` 服务与 Remote 命名空间、`Config`、四道关、切页器、`read`、`readBytes`、`stat`、`list` | | [`src/changes.ts`](src/changes.ts) | `WorkspaceChangeFeed`:目标监听、匹配的 `fs/observed` 通知与每代流各自的队列 | | [`src/types.ts`](src/types.ts) | 线路类型与 `RemoteErrorDetailsMap` 错误码,以 `./types` 发布给 Client 包 | | [`src/client/index.ts`](src/client/index.ts)、[`provider.ts`](src/client/provider.ts)、[`change-feed.ts`](src/client/change-feed.ts) | 浏览器插件、文件元数据与按目标建立的变更流 | diff --git a/packages/api/workspace-files/package.json b/packages/api/workspace-files/package.json index 73df728df4..480f133ed8 100644 --- a/packages/api/workspace-files/package.json +++ b/packages/api/workspace-files/package.json @@ -63,6 +63,7 @@ "devDependencies": { "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-api-gateway": "workspace:^", + "@deepseek-ai/dsh-client-connection": "workspace:^", "@deepseek-ai/dsh-client-resources": "workspace:^", "@deepseek-ai/dsh-client-ui-slots": "workspace:^", "@deepseek-ai/dsh-fs": "workspace:^", diff --git a/packages/api/workspace-files/src/index.ts b/packages/api/workspace-files/src/index.ts index f9807ea534..c5d1542593 100644 --- a/packages/api/workspace-files/src/index.ts +++ b/packages/api/workspace-files/src/index.ts @@ -32,6 +32,7 @@ import { Remote, RemoteError, TypertRemoteService, type TypertLookup } from '@de import { WorkspaceChangeFeed } from './changes.ts' import type { WorkspaceByteRange, + WorkspaceByteReadOptions, WorkspaceDirectoryEntry, WorkspaceDirectoryListing, WorkspaceFileBytes, @@ -245,38 +246,29 @@ export class WorkspaceFiles extends TypertRemoteService { } /** - * Read one byte window of a regular file readable by the filesystem backend: raw - * bytes, no text decoding and no binary rejection. + * Read a complete regular file or one byte range without text decoding. * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire. - * @param path - absolute path or path relative to the workspace root; files outside it are allowed. - * @param range - the byte window; omitted fields take the window defaults. + * @param path - target path, absolute or workspace-relative; relative to the base file's directory when provided. + * @param options - optional base file and range; without a range the complete-file cap applies. * @param signal - caller cancellation. - * @returns the window in base64, the file's version and size at the stat before it, and whether it reaches the last byte. + * @returns native bytes with the file's version and size at the preceding stat, byte offset, and EOF marker. */ @Remote async readBytes( workspaceFileScope: WorkspaceFileScope, path: string, - range: WorkspaceByteRange, + options: WorkspaceByteReadOptions, signal: AbortSignal, ): Promise { - const { offset, length } = this.resolveWindow(range, path) - const { target, info } = await this.locateFile(workspaceFileScope, path, signal) - const data = await this.ctx.fs.readByteRange(target, { offset, length }, signal) - const eof = info.size === undefined ? data.length < length : offset + data.length >= info.size - return { ...this.statOf(target, info), offset, data: Buffer.from(data).toString('base64'), eof } - } - - /** - * Read a complete regular file as bytes, subject to the configured full-file cap. - * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire. - * @param path - absolute or workspace-relative file path. - * @param signal - caller cancellation. - * @returns one complete base64 window with offset zero and eof true; oversized files fail with too-large. - */ - @Remote - async readAll(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise { - const { target, info } = await this.locateFile(workspaceFileScope, path, signal) + const window = options.range === undefined ? undefined : this.resolveWindow(options.range, path) + const resolved = options.baseFile === undefined ? path : await this.relativePath(workspaceFileScope, options.baseFile, path, signal) + const { target, info } = await this.locateFile(workspaceFileScope, resolved, signal) + if (window !== undefined) { + const { offset, length } = window + const data = await this.ctx.fs.readByteRange(target, window, signal) + const eof = info.size === undefined ? data.length < length : offset + data.length >= info.size + return { ...this.statOf(target, info), offset, data, eof } + } const limit = this.config.maxFileBytes const data = await this.ctx.fs.readBytes(target, signal, limit).catch((cause: unknown) => { if (typeof cause === 'object' && cause !== null && 'code' in cause && cause.code === 'FS_TOO_LARGE') { @@ -284,32 +276,7 @@ export class WorkspaceFiles extends TypertRemoteService { } throw cause }) - return { ...this.statOf(target, info), offset: 0, data: Buffer.from(data).toString('base64'), eof: true } - } - - /** - * Read a complete file relative to another file's directory, including outside the workspace. - * @param workspaceFileScope - header-derived workspace root for the Session identity on the wire. - * @param path - base file, absolute or workspace-relative. - * @param relativePath - relative filesystem path, not a URL or absolute path. - * @param signal - caller cancellation. - * @returns the complete related file using the ordinary file-size and access checks. - */ - @Remote - async readRelated( - workspaceFileScope: WorkspaceFileScope, - path: string, - relativePath: string, - signal: AbortSignal, - ): Promise { - const relative = relativePath.replace(/\\/g, '/') - if (relative.length === 0 || relative.startsWith('/') || /^[a-z][a-z\d+.-]*:/iu.test(relative) || relative.includes(NUL)) { - throw new RemoteError('gateway/bad-request', 'relativePath must be a relative filesystem path', {}) - } - const { target } = await this.locateFile(workspaceFileScope, path, signal) - const absolute = this.ctx.fs.processPath(target) - const paths = absolute.startsWith('/') ? posix : win32 - return this.readAll(workspaceFileScope, paths.resolve(paths.dirname(absolute), relative), signal) + return { ...this.statOf(target, info), offset: 0, data, eof: true } } /** @@ -365,6 +332,17 @@ export class WorkspaceFiles extends TypertRemoteService { return this.feed.follow(workspaceFileScope.workspaceRoot, path, signal) } + private async relativePath(scope: WorkspaceFileScope, baseFile: string, path: string, signal: AbortSignal): Promise { + const relative = path.replace(/\\/g, '/') + if (relative.length === 0 || relative.startsWith('/') || /^[a-z][a-z\d+.-]*:/iu.test(relative) || relative.includes(NUL)) { + throw new RemoteError('gateway/bad-request', 'path must be relative when baseFile is provided', {}) + } + const { target } = await this.locateFile(scope, baseFile, signal) + const absolute = this.ctx.fs.processPath(target) + const paths = absolute.startsWith('/') ? posix : win32 + return paths.resolve(paths.dirname(absolute), relative) + } + /** Apply the page defaults and caps here, so the request never carries them implicitly. */ private resolvePage(range: WorkspaceFileRange): { offset: number; limit: number } { const offset = range.offset === undefined ? 1 : integerAtLeast(range.offset, 1, 'offset') diff --git a/packages/api/workspace-files/src/types.ts b/packages/api/workspace-files/src/types.ts index 184767f10e..ea6bc2c086 100644 --- a/packages/api/workspace-files/src/types.ts +++ b/packages/api/workspace-files/src/types.ts @@ -69,15 +69,23 @@ export interface WorkspaceByteRange { readonly length?: number } +/** Target resolution and optional byte range for one binary file read. */ +export interface WorkspaceByteReadOptions { + /** Byte window; omit to read the complete file under the configured `maxFileBytes` cap. */ + readonly range?: WorkspaceByteRange + /** Base file, absolute or workspace-relative; resolve the relative target from its directory. */ + readonly baseFile?: string +} + /** * One byte window of a workspace file as a Client reads it: raw bytes, no text * decoding and no binary rejection. `bytes` is the complete file's size. */ -export interface WorkspaceFileBytes extends WorkspaceFileStat { +export interface WorkspaceFileBytes extends WorkspaceFileStat { /** First byte of the window, as requested. */ readonly offset: number - /** The window's bytes in base64; empty when `offset` lies at or past the file's end. */ - readonly data: string + /** Native file bytes; empty at or past EOF. */ + readonly data: Data /** Whether the window includes the file's last byte. */ readonly eof: boolean } diff --git a/packages/api/workspace-files/tests/binary-rpc.spec.ts b/packages/api/workspace-files/tests/binary-rpc.spec.ts new file mode 100644 index 0000000000..35058d58a1 --- /dev/null +++ b/packages/api/workspace-files/tests/binary-rpc.spec.ts @@ -0,0 +1,93 @@ +/** Workspace byte reads traverse Gateway lookup and Connection's binary RPC response. */ +import { writeFile } from 'node:fs/promises' +import { join } from 'node:path' +import { beforeEach, afterEach, expect, it, vi } from 'vitest' +import SessionStore from '@deepseek-ai/dsh-session' +import TypertRegistry from '@deepseek-ai/dsh-typert-registry' +import TypertGateway from '@deepseek-ai/dsh-api-gateway' +import { HostConnectionService } from '@deepseek-ai/dsh-client-connection/src/rpc-host.ts' +import type { BrowserAuth } from '@deepseek-ai/dsh-client-connection/src/browser-auth.ts' +import { createWebConnectionRpc } from '@deepseek-ai/dsh-client-connection/src/client/rpc.ts' +import WorkspaceFiles, { type WorkspaceByteReadOptions } from '../src/index.ts' +import { openWorkspace, type Harness } from './harness.ts' + +let harness: Harness +let rpc: ReturnType + +beforeEach(async () => { + harness = await openWorkspace('dsh-workspace-binary-rpc-') + const ctx = harness.ctx + await ctx.plugin(SessionStore) + await ctx.plugin(TypertRegistry) + await ctx.plugin(TypertGateway) + await ctx.plugin((scope) => { new HostConnectionService(scope, [], {} as BrowserAuth) }) + await ctx.plugin(WorkspaceFiles, { maxBytes: 8, maxFileBytes: 4, maxLines: 100, maxEntries: 100 }) + ctx.sessions.create(harness.scope.sessionId, { meta: { cwd: harness.workspace, origin: 'subagent' } }) + const handler = (ctx.get('connection') as HostConnectionService).createSharedFetchHandler('/api') + rpc = createWebConnectionRpc(async (path, init) => handler.fetch(new Request(new URL(path, 'http://host'), init))) +}) + +afterEach(async () => { + await harness.ctx.fiber.dispose() + await harness.dispose() +}) + +function read(path: string, options: WorkspaceByteReadOptions, signal = new AbortController().signal) { + return rpc.call('/api', 'workspaceFiles/readBytes', { args: { workspaceFileScopeId: harness.scope.sessionId, path, options } }, signal) +} + +it('returns complete binary contents through the ordinary Remote endpoint', async () => { + const data = new Uint8Array([0, 128, 255, 1]) + await writeFile(join(harness.workspace, '字节.bin'), data) + expect(await read('字节.bin', {})).toMatchObject({ ok: true, value: { offset: 0, eof: true, bytes: 4, data } }) + expect(harness.ctx.get('agents')).toBeUndefined() +}) + +it.each([ + [{}, [0, 1, 2, 3, 4, 5, 6, 7], 0, false], + [{ offset: 7, length: 8 }, [7, 8, 9], 7, true], + [{ offset: 10 }, [], 10, true], +])('preserves range %j without reading the whole oversized file', async (range, data, offset, eof) => { + await writeFile(join(harness.workspace, 'base.html'), 'base') + await writeFile(join(harness.workspace, 'large.bin'), new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])) + const complete = vi.spyOn(harness.ctx.fs, 'readBytes') + const window = vi.spyOn(harness.ctx.fs, 'readByteRange') + expect(await read('large.bin', { baseFile: 'base.html', range })).toMatchObject({ + ok: true, value: { offset, eof, bytes: 10, data: new Uint8Array(data) }, + }) + expect(window).toHaveBeenCalledExactlyOnceWith(expect.anything(), { offset, length: 8 }, expect.any(AbortSignal)) + expect(complete).not.toHaveBeenCalled() +}) + +it('preserves full-file size failures and Gateway Session lookup failures', async () => { + await writeFile(join(harness.workspace, 'large'), '12345') + expect(await read('large', {})).toMatchObject({ ok: false, error: { code: 'workspace-file/too-large', details: { path: 'large', limit: 4 } } }) + expect(await rpc.call('/api', 'workspaceFiles/readBytes', { args: { workspaceFileScopeId: 'missing', path: 'large', options: {} } })) + .toMatchObject({ ok: false, error: { code: 'gateway/lookup-not-found' } }) +}) + +it.each([{}, { range: {} }])('propagates cancellation into the filesystem for options %j', async (options) => { + await writeFile(join(harness.workspace, 'file'), 'data') + const entered = Promise.withResolvers() + const controller = new AbortController() + const abortable = async (signal: AbortSignal | undefined): Promise => { + if (signal === undefined) throw new Error('read did not receive cancellation') + entered.resolve(undefined) + return new Promise((_resolve, reject) => { + signal.addEventListener('abort', () => { reject(signal.reason as Error) }, { once: true }) + }) + } + if ('range' in options) vi.spyOn(harness.ctx.fs, 'readByteRange').mockImplementation((_target, _range, signal) => abortable(signal)) + else vi.spyOn(harness.ctx.fs, 'readBytes').mockImplementation((_target, signal) => abortable(signal)) + const failure = new Error('tab closed') + const pending = read('file', options, controller.signal) + const rejected = expect(pending).rejects.toBe(failure) + try { + await entered.promise + controller.abort(failure) + await rejected + } finally { + controller.abort(failure) + await rejected + } +}) diff --git a/packages/api/workspace-files/tests/read-all.spec.ts b/packages/api/workspace-files/tests/read-all.spec.ts index 21d75bd849..cd5d3b9d73 100644 --- a/packages/api/workspace-files/tests/read-all.spec.ts +++ b/packages/api/workspace-files/tests/read-all.spec.ts @@ -1,6 +1,6 @@ /** Full-file reads retain the ordinary file gates and never return a silently truncated result. */ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' -import { mkdir, symlink, writeFile } from 'node:fs/promises' +import { mkdir, realpath, symlink, writeFile } from 'node:fs/promises' import { join } from 'node:path' import { FsVersion } from '@deepseek-ai/dsh-fs' import { failureOf, openWorkspace, signal, type Harness } from './harness.ts' @@ -10,31 +10,33 @@ let harness: Harness beforeEach(async () => { harness = await openWorkspace('dsh-workspace-files-read-all-') }) afterEach(async () => { await harness.dispose() }) -describe('workspaceFiles.readAll', () => { +describe('workspaceFiles.readBytes — complete files', () => { it('reads the complete bytes independently of the window cap', async () => { const bytes = Buffer.from([0, 255, 1, 2]) await writeFile(join(harness.workspace, 'file.bin'), bytes) - const result = await harness.endpoint({ maxBytes: 1, maxFileBytes: 4 }).readAll(harness.scope, 'file.bin', signal()) - expect(Buffer.from(result.data, 'base64')).toEqual(bytes) + const result = await harness.endpoint({ maxBytes: 1, maxFileBytes: 4 }).readBytes(harness.scope, 'file.bin', {}, signal()) + expect(Buffer.from(result.data)).toEqual(bytes) expect(result).toMatchObject({ offset: 0, eof: true, bytes: 4 }) }) it('returns an empty complete file', async () => { await writeFile(join(harness.workspace, 'empty'), '') - expect(await harness.endpoint().readAll(harness.scope, 'empty', signal())).toMatchObject({ data: '', offset: 0, eof: true, bytes: 0 }) + const result = await harness.endpoint().readBytes(harness.scope, 'empty', {}, signal()) + expect(result.data.byteLength).toBe(0) + expect(result).toMatchObject({ offset: 0, eof: true, bytes: 0 }) }) it.each(['workspace', 'outside'] as const)('maps the filesystem size refusal for a %s file', async (location) => { const path = join(harness[location], 'large') await writeFile(path, 'abcde') - expect(await failureOf(harness.endpoint({ maxFileBytes: 4 }).readAll(harness.scope, path, signal()))) + expect(await failureOf(harness.endpoint({ maxFileBytes: 4 }).readBytes(harness.scope, path, {}, signal()))) .toEqual({ code: 'workspace-file/too-large', details: { path, limit: 4 } }) }) it.each([undefined, 1])('checks the actual bytes when stat reports %s', async (size) => { await writeFile(join(harness.workspace, 'growing'), 'abcde') vi.spyOn(harness.ctx.fs, 'stat').mockResolvedValue({ type: 'file', version: FsVersion('v'), ...size === undefined ? {} : { size } }) - expect((await failureOf(harness.endpoint({ maxFileBytes: 4 }).readAll(harness.scope, 'growing', signal()))).code) + expect((await failureOf(harness.endpoint({ maxFileBytes: 4 }).readBytes(harness.scope, 'growing', {}, signal()))).code) .toBe('workspace-file/too-large') }) @@ -42,17 +44,17 @@ describe('workspaceFiles.readAll', () => { await mkdir(join(harness.workspace, 'directory')) await writeFile(join(harness.outside, 'outside'), 'outside') const files = harness.endpoint() - expect((await failureOf(files.readAll(harness.scope, 'missing', signal()))).code).toBe('workspace-file/not-found') - expect((await failureOf(files.readAll(harness.scope, 'directory', signal()))).code).toBe('workspace-file/not-regular-file') - const outside = await files.readAll(harness.scope, join(harness.outside, 'outside'), signal()) - expect(Buffer.from(outside.data, 'base64').toString()).toBe('outside') + expect((await failureOf(files.readBytes(harness.scope, 'missing', {}, signal()))).code).toBe('workspace-file/not-found') + expect((await failureOf(files.readBytes(harness.scope, 'directory', {}, signal()))).code).toBe('workspace-file/not-regular-file') + const outside = await files.readBytes(harness.scope, join(harness.outside, 'outside'), {}, signal()) + expect(Buffer.from(outside.data).toString()).toBe('outside') }) it.each([new Error('Read denied'), new DOMException('Cancelled', 'AbortError'), null, 'backend failure', { code: 'FS_NOT_FOUND' }])( 'preserves non-size filesystem failures: %s', async (failure) => { await writeFile(join(harness.workspace, 'file'), '1234') vi.spyOn(harness.ctx.fs, 'readBytes').mockRejectedValueOnce(failure) - await expect(harness.endpoint().readAll(harness.scope, 'file', signal())).rejects.toBe(failure) + await expect(harness.endpoint().readBytes(harness.scope, 'file', {}, signal())).rejects.toBe(failure) }, ) @@ -60,39 +62,39 @@ describe('workspaceFiles.readAll', () => { await writeFile(join(harness.workspace, 'file'), '1234') const failure = { code: 'FS_TOO_LARGE' } vi.spyOn(harness.ctx.fs, 'readBytes').mockRejectedValueOnce(failure) - await expect(harness.endpoint({ maxFileBytes: 4 }).readAll(harness.scope, 'file', signal())) + await expect(harness.endpoint({ maxFileBytes: 4 }).readBytes(harness.scope, 'file', {}, signal())) .rejects.toMatchObject({ code: 'workspace-file/too-large', details: { path: 'file', limit: 4 }, cause: failure }) }) }) -describe('workspaceFiles.readRelated', () => { +describe('workspaceFiles.readBytes — base file', () => { it('resolves relative paths from the base file directory on the Host', async () => { await mkdir(join(harness.workspace, 'nested')) await writeFile(join(harness.workspace, 'nested/base.txt'), 'base') await writeFile(join(harness.workspace, 'nested/near.txt'), 'near') await writeFile(join(harness.workspace, 'root.txt'), 'root') const files = harness.endpoint() - const near = await files.readRelated(harness.scope, 'nested/base.txt', './near.txt', signal()) - const root = await files.readRelated(harness.scope, 'nested/base.txt', '../root.txt', signal()) - expect(Buffer.from(near.data, 'base64').toString()).toBe('near') - expect(Buffer.from(root.data, 'base64').toString()).toBe('root') - const fromRoot = await files.readRelated(harness.scope, 'root.txt', 'nested\\near.txt', signal()) - expect(Buffer.from(fromRoot.data, 'base64').toString()).toBe('near') + const near = await files.readBytes(harness.scope, './near.txt', { baseFile: 'nested/base.txt' }, signal()) + const root = await files.readBytes(harness.scope, '../root.txt', { baseFile: 'nested/base.txt' }, signal()) + expect(Buffer.from(near.data).toString()).toBe('near') + expect(Buffer.from(root.data).toString()).toBe('root') + const fromRoot = await files.readBytes(harness.scope, 'nested\\near.txt', { baseFile: 'root.txt' }, signal()) + expect(Buffer.from(fromRoot.data).toString()).toBe('near') }) it.each(['', '/outside', 'C:\\outside', '\\\\host\\share', 'https://example.test/a.js', 'bad\0path'])('rejects non-relative path %j', async (path) => { - expect((await failureOf(harness.endpoint().readRelated(harness.scope, 'base', path, signal()))).code).toBe('gateway/bad-request') + expect((await failureOf(harness.endpoint().readBytes(harness.scope, path, { baseFile: 'base' }, signal()))).code).toBe('gateway/bad-request') }) it('resolves related files on either side of the workspace root', async () => { await writeFile(join(harness.workspace, 'base'), 'base') await writeFile(join(harness.outside, 'outside'), 'outside') const files = harness.endpoint() - expect((await failureOf(files.readRelated(harness.scope, 'missing', 'file', signal()))).code).toBe('workspace-file/not-found') - const fromOutside = await files.readRelated(harness.scope, join(harness.outside, 'outside'), '../workspace/base', signal()) - const toOutside = await files.readRelated(harness.scope, 'base', '../outside/outside', signal()) - expect(Buffer.from(fromOutside.data, 'base64').toString()).toBe('base') - expect(Buffer.from(toOutside.data, 'base64').toString()).toBe('outside') + expect((await failureOf(files.readBytes(harness.scope, 'file', { baseFile: 'missing' }, signal()))).code).toBe('workspace-file/not-found') + const fromOutside = await files.readBytes(harness.scope, '../workspace/base', { baseFile: join(harness.outside, 'outside') }, signal()) + const toOutside = await files.readBytes(harness.scope, '../outside/outside', { baseFile: 'base' }, signal()) + expect(Buffer.from(fromOutside.data).toString()).toBe('base') + expect(Buffer.from(toOutside.data).toString()).toBe('outside') }) it('reads sibling assets beside an outside HTML file with escaped path characters', async () => { @@ -100,8 +102,8 @@ describe('workspaceFiles.readRelated', () => { const base = join(harness.outside, 'space # assets', 'page.html') await writeFile(base, '') await writeFile(join(harness.outside, 'space # assets', 'app.js'), 'EXTERNAL_ASSET') - const result = await harness.endpoint().readRelated(harness.scope, base, './app.js', signal()) - expect(Buffer.from(result.data, 'base64').toString()).toBe('EXTERNAL_ASSET') + const result = await harness.endpoint().readBytes(harness.scope, './app.js', { baseFile: base }, signal()) + expect(Buffer.from(result.data).toString()).toBe('EXTERNAL_ASSET') }) it.each([ @@ -112,16 +114,41 @@ describe('workspaceFiles.readRelated', () => { await writeFile(join(harness.workspace, 'base'), 'base') const files = harness.endpoint() vi.spyOn(harness.ctx.fs, 'processPath').mockReturnValue(base) - const read = vi.spyOn(files, 'readAll').mockResolvedValue({ absolutePath: expected, version: 'v', offset: 0, data: '', eof: true }) + const lstat = harness.ctx.fs.lstat.bind(harness.ctx.fs) + const inspect = vi.spyOn(harness.ctx.fs, 'lstat').mockImplementation((path, options, abort) => + path === 'base' ? lstat(path, options, abort) : Promise.resolve(undefined)) const caller = signal() - await files.readRelated(harness.scope, 'base', './app.js', caller) - expect(read).toHaveBeenCalledWith(harness.scope, expected, caller) + await expect(files.readBytes(harness.scope, './app.js', { baseFile: 'base' }, caller)).rejects.toMatchObject({ code: 'workspace-file/not-found' }) + expect(inspect).toHaveBeenLastCalledWith(expected, { cwd: harness.workspace }, caller) + }) + + it('combines a base file with a bounded range without applying the complete-file cap', async () => { + await mkdir(join(harness.workspace, 'nested')) + await writeFile(join(harness.workspace, 'nested/base.html'), 'base') + await writeFile(join(harness.workspace, 'nested/asset.bin'), new Uint8Array([0, 255, 128, 4, 5, 6])) + const completeRead = vi.spyOn(harness.ctx.fs, 'readBytes') + const rangeRead = vi.spyOn(harness.ctx.fs, 'readByteRange') + const caller = signal() + const result = await harness.endpoint({ maxBytes: 2, maxFileBytes: 1 }).readBytes( + harness.scope, './asset.bin', { baseFile: 'nested/base.html', range: { offset: 1, length: 2 } }, caller, + ) + expect([...result.data]).toEqual([255, 128]) + expect(result).toMatchObject({ absolutePath: await realpath(join(harness.workspace, 'nested/asset.bin')), offset: 1, eof: false, bytes: 6 }) + expect(rangeRead).toHaveBeenCalledExactlyOnceWith(expect.anything(), { offset: 1, length: 2 }, caller) + expect(completeRead).not.toHaveBeenCalled() + }) + + it('checks the base file kind before reading the target', async () => { + await mkdir(join(harness.workspace, 'directory')) + await writeFile(join(harness.workspace, 'target'), 'target') + expect((await failureOf(harness.endpoint().readBytes(harness.scope, 'target', { baseFile: 'directory' }, signal()))).code) + .toBe('workspace-file/not-regular-file') }) it('rejects a related symlink rather than following it', async () => { await writeFile(join(harness.workspace, 'base'), 'base') await writeFile(join(harness.workspace, 'target'), 'target') await symlink('target', join(harness.workspace, 'link')) - expect((await failureOf(harness.endpoint().readRelated(harness.scope, 'base', 'link', signal()))).code).toBe('workspace-file/not-regular-file') + expect((await failureOf(harness.endpoint().readBytes(harness.scope, 'link', { baseFile: 'base' }, signal()))).code).toBe('workspace-file/not-regular-file') }) }) diff --git a/packages/api/workspace-files/tests/read-bytes.spec.ts b/packages/api/workspace-files/tests/read-bytes.spec.ts index 2af2ca9927..62cb55a218 100644 --- a/packages/api/workspace-files/tests/read-bytes.spec.ts +++ b/packages/api/workspace-files/tests/read-bytes.spec.ts @@ -17,18 +17,16 @@ afterEach(async () => { await harness.dispose() }) -const endpoint = (caps?: { maxBytes?: number }): ReturnType => harness.endpoint(caps) +const endpoint = (caps?: { maxBytes?: number; maxFileBytes?: number }): ReturnType => harness.endpoint(caps) /** 256 bytes, each equal to its offset: the window's content names its position. */ const RAMP = Buffer.from(Array.from({ length: 256 }, (_, i) => i)) -const decode = (data: string): Buffer => Buffer.from(data, 'base64') - describe('workspaceFiles.readBytes — the window', () => { it('returns the whole file as one window by default, with its absolute path, version, and size', async () => { await writeFile(join(workspace, 'ramp.bin'), RAMP) - const result = await endpoint().readBytes(harness.scope, 'ramp.bin', {}, signal()) - expect(decode(result.data).equals(RAMP)).toBe(true) + const result = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: {} }, signal()) + expect(Buffer.from(result.data).equals(RAMP)).toBe(true) expect(result).toMatchObject({ offset: 0, eof: true, bytes: 256 }) expect(result.absolutePath.endsWith('ramp.bin')).toBe(true) expect(result.version.length).toBeGreaterThan(0) @@ -36,61 +34,68 @@ describe('workspaceFiles.readBytes — the window', () => { it('cuts the requested window and reports that more follows', async () => { await writeFile(join(workspace, 'ramp.bin'), RAMP) - const result = await endpoint().readBytes(harness.scope, 'ramp.bin', { offset: 16, length: 8 }, signal()) - expect([...decode(result.data)]).toEqual([16, 17, 18, 19, 20, 21, 22, 23]) + const result = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: { offset: 16, length: 8 } }, signal()) + expect([...result.data]).toEqual([16, 17, 18, 19, 20, 21, 22, 23]) expect(result).toMatchObject({ offset: 16, eof: false, bytes: 256 }) }) - it('reads a window of a file far above the byte cap', async () => { + it('reads only a window of a file above both byte caps', async () => { await writeFile(join(workspace, 'huge.bin'), Buffer.alloc(200_000, 7)) - const result = await endpoint({ maxBytes: 1024 }).readBytes(harness.scope, 'huge.bin', { offset: 199_000, length: 1024 }, signal()) - expect(decode(result.data)).toHaveLength(1000) + const rangeRead = vi.spyOn(harness.ctx.fs, 'readByteRange') + const completeRead = vi.spyOn(harness.ctx.fs, 'readBytes') + const caller = signal() + const result = await endpoint({ maxBytes: 1024, maxFileBytes: 4 }).readBytes(harness.scope, 'huge.bin', { range: { offset: 199_000, length: 1024 } }, caller) + expect(rangeRead).toHaveBeenCalledExactlyOnceWith(expect.anything(), { offset: 199_000, length: 1024 }, caller) + expect(completeRead).not.toHaveBeenCalled() + expect(result.data).toHaveLength(1000) expect(result).toMatchObject({ eof: true, bytes: 200_000 }) }) it('infers eof from a short window when the backend reports no size', async () => { await writeFile(join(workspace, 'ramp.bin'), RAMP) vi.spyOn(harness.ctx.fs, 'stat').mockResolvedValue({ version: FsVersion('v-sizeless'), type: 'file' }) - const full = await endpoint().readBytes(harness.scope, 'ramp.bin', { offset: 0, length: 256 }, signal()) + const full = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: { offset: 0, length: 256 } }, signal()) expect(full.eof).toBe(false) - const short = await endpoint().readBytes(harness.scope, 'ramp.bin', { offset: 250, length: 10 }, signal()) + const short = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: { offset: 250, length: 10 } }, signal()) expect(short).toMatchObject({ eof: true }) expect(short.bytes).toBeUndefined() }) it('reports eof on the window that holds the last byte, whether or not the length is reached', async () => { await writeFile(join(workspace, 'ramp.bin'), RAMP) - const exact = await endpoint().readBytes(harness.scope, 'ramp.bin', { offset: 248, length: 8 }, signal()) + const exact = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: { offset: 248, length: 8 } }, signal()) expect(exact.eof).toBe(true) - expect(decode(exact.data)).toHaveLength(8) - const short = await endpoint().readBytes(harness.scope, 'ramp.bin', { offset: 250, length: 100 }, signal()) + expect(exact.data).toHaveLength(8) + const short = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: { offset: 250, length: 100 } }, signal()) expect(short.eof).toBe(true) - expect([...decode(short.data)]).toEqual([250, 251, 252, 253, 254, 255]) + expect([...short.data]).toEqual([250, 251, 252, 253, 254, 255]) }) it('returns an empty eof window for an offset at or past the end', async () => { await writeFile(join(workspace, 'ramp.bin'), RAMP) - const result = await endpoint().readBytes(harness.scope, 'ramp.bin', { offset: 300, length: 8 }, signal()) - expect(result).toMatchObject({ data: '', offset: 300, eof: true, bytes: 256 }) + const result = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: { offset: 300, length: 8 } }, signal()) + expect(result.data).toHaveLength(0) + expect(result).toMatchObject({ offset: 300, eof: true, bytes: 256 }) }) it('returns an empty eof window for an empty file', async () => { await writeFile(join(workspace, 'empty.bin'), Buffer.alloc(0)) - const result = await endpoint().readBytes(harness.scope, 'empty.bin', {}, signal()) - expect(result).toMatchObject({ data: '', offset: 0, eof: true, bytes: 0 }) + const result = await endpoint().readBytes(harness.scope, 'empty.bin', { range: {} }, signal()) + expect(result.data).toHaveLength(0) + expect(result).toMatchObject({ offset: 0, eof: true, bytes: 0 }) }) - it('carries bytes a text read would refuse: NUL and invalid UTF-8 round-trip through base64', async () => { + it('carries bytes a text read would refuse: NUL and invalid UTF-8 round-trip as bytes', async () => { const raw = Buffer.from([0, 0xff, 0xfe, 0x80, 0x41, 0]) await writeFile(join(workspace, 'blob.bin'), raw) - const result = await endpoint().readBytes(harness.scope, 'blob.bin', {}, signal()) - expect(decode(result.data).equals(raw)).toBe(true) + const result = await endpoint().readBytes(harness.scope, 'blob.bin', { range: {} }, signal()) + expect(Buffer.from(result.data).equals(raw)).toBe(true) }) it('names the version a stat of the same file reports', async () => { await writeFile(join(workspace, 'ramp.bin'), RAMP) const stat = await endpoint().stat(harness.scope, 'ramp.bin', signal()) - const result = await endpoint().readBytes(harness.scope, 'ramp.bin', {}, signal()) + const result = await endpoint().readBytes(harness.scope, 'ramp.bin', { range: {} }, signal()) expect(result.version).toBe(stat.version) }) }) @@ -98,22 +103,22 @@ describe('workspaceFiles.readBytes — the window', () => { describe('workspaceFiles.readBytes — defaults and cap', () => { it('defaults the length to the configured byte cap', async () => { await writeFile(join(workspace, 'ramp.bin'), RAMP.subarray(0, 64)) - const result = await endpoint({ maxBytes: 64 }).readBytes(harness.scope, 'ramp.bin', {}, signal()) - expect(decode(result.data)).toHaveLength(64) + const result = await endpoint({ maxBytes: 64 }).readBytes(harness.scope, 'ramp.bin', { range: {} }, signal()) + expect(result.data).toHaveLength(64) expect(result.eof).toBe(true) }) it('refuses a window longer than the cap as too-large rather than shortening it', async () => { await writeFile(join(workspace, 'ramp.bin'), RAMP) - const failure = await failureOf(endpoint({ maxBytes: 64 }).readBytes(harness.scope, 'ramp.bin', { length: 65 }, signal())) + const failure = await failureOf(endpoint({ maxBytes: 64 }).readBytes(harness.scope, 'ramp.bin', { range: { length: 65 } }, signal())) expect(failure.code).toBe('workspace-file/too-large') expect(failure.details).toMatchObject({ limit: 64 }) }) it('accepts a window exactly at the cap', async () => { await writeFile(join(workspace, 'ramp.bin'), RAMP.subarray(0, 64)) - const result = await endpoint({ maxBytes: 64 }).readBytes(harness.scope, 'ramp.bin', { length: 64 }, signal()) - expect(decode(result.data)).toHaveLength(64) + const result = await endpoint({ maxBytes: 64 }).readBytes(harness.scope, 'ramp.bin', { range: { length: 64 } }, signal()) + expect(result.data).toHaveLength(64) }) it('refuses a negative or fractional offset and a non-positive length as bad requests', async () => { @@ -124,7 +129,7 @@ describe('workspaceFiles.readBytes — defaults and cap', () => { { offset: 2 ** 53 }, { offset: Number.MAX_SAFE_INTEGER, length: 2 }, ] for (const range of ranges) { - const failure = await failureOf(endpoint().readBytes(harness.scope, 'ramp.bin', range, signal())) + const failure = await failureOf(endpoint().readBytes(harness.scope, 'ramp.bin', { range }, signal())) expect(failure.code).toBe('gateway/bad-request') } }) @@ -133,15 +138,15 @@ describe('workspaceFiles.readBytes — defaults and cap', () => { describe('workspaceFiles.readBytes — the gates it shares with read', () => { it('rejects a directory, a missing path, and an empty path', async () => { await mkdir(join(workspace, 'dir')) - expect((await failureOf(endpoint().readBytes(harness.scope, 'dir', {}, signal()))).code).toBe('workspace-file/not-regular-file') - expect((await failureOf(endpoint().readBytes(harness.scope, 'missing.bin', {}, signal()))).code).toBe('workspace-file/not-found') - expect((await failureOf(endpoint().readBytes(harness.scope, '', {}, signal()))).code).toBe('gateway/bad-request') + expect((await failureOf(endpoint().readBytes(harness.scope, 'dir', { range: {} }, signal()))).code).toBe('workspace-file/not-regular-file') + expect((await failureOf(endpoint().readBytes(harness.scope, 'missing.bin', { range: {} }, signal()))).code).toBe('workspace-file/not-found') + expect((await failureOf(endpoint().readBytes(harness.scope, '', { range: {} }, signal()))).code).toBe('gateway/bad-request') }) it('reads a bounded byte window outside the workspace', async () => { await writeFile(join(harness.outside, 'sample.bin'), RAMP) - const result = await endpoint().readBytes(harness.scope, join(harness.outside, 'sample.bin'), { offset: 2, length: 4 }, signal()) - expect(decode(result.data)).toEqual(RAMP.subarray(2, 6)) + const result = await endpoint().readBytes(harness.scope, join(harness.outside, 'sample.bin'), { range: { offset: 2, length: 4 } }, signal()) + expect(result.data).toEqual(RAMP.subarray(2, 6)) expect(result).toMatchObject({ offset: 2, eof: false }) }) }) diff --git a/packages/client/connection/README.i18n.yaml b/packages/client/connection/README.i18n.yaml index ddf0603df0..fbc282a42b 100644 --- a/packages/client/connection/README.i18n.yaml +++ b/packages/client/connection/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/connection/README.md -README.md: 6c49836b0e581666db0df503b175132ed1e6295b -README.zh.md: 5843efd2299526cf00b0c6331668c304d6042f56 +README.md: e50f4fb6838ae27b545bd2b3c4683224f7eb37c9 +README.zh.md: 1bf0733bd660049a5b99a7e7966d65121b0dea3f diff --git a/packages/client/connection/README.md b/packages/client/connection/README.md index 6c49836b0e..e50f4fb683 100644 --- a/packages/client/connection/README.md +++ b/packages/client/connection/README.md @@ -27,6 +27,8 @@ The package carries browser-to-Host Remote calls, exact Fetch responses, and con A static desktop page can provide `__DSH_TRANSPORT__.streamBaseUrl` for the HTTP origin of its owned Host. The Gateway uses that origin for its WebSocket while HTTP transport remains independently selected. The desktop carrier owns authentication; setting the origin alone grants no access. +Unary RPC requests use JSON. A Host handler may return byte attachments that it has already separated from the JSON-compatible result value, with each attachment naming its result-relative path. Connection writes these values as multipart parts. The JSON `metadata` part contains the RPC response envelope with `null` placeholders and an attachment table recording each path, codec, and part identifier. Paths use string keys and numeric array indices; no business field name is reserved. The Client validates the envelope, `rpcId`, attachment table, and parts, then restores each byte value as an `ArrayBuffer`-backed view. Results without attachments, including base64 strings, and failures remain JSON. Logical RPC carriers return decoded native values directly. Connection does not discover binary fields or depend on Typert; the handler that owns a result protocol performs any type-directed or runtime projection before returning. Binary parameters, events, and streamed binary results are unsupported. + The browser uses HTTP POST for Remote unary calls. API Gateway owns the `/api/remote.mux` WebSocket and its logical streams; shell-owned compositions provide equivalent Remote streams, including a stream's uplink, through `connection.rpc.open` without opening a WebSocket. The browser plugin reads the page transport, recovery settings, and location, then delegates to `installConnection(ctx, options)`. A composition that owns its carrier may call the same installer directly; the whole-client test tier does so. Each invocation creates one Context-owned service, so several Client trees can use different carriers in one realm. The Host half always provides the carrier-neutral RPC and exact `GET`/`HEAD`/`POST` route registries. When a Web carrier is present it also owns the sole `/api` route, Fetch bridge, browser authentication, and Host/Origin checks; a shell-owned carrier dispatches the shared Fetch handler directly. Each exact route declares buffered or streaming request-body handling before the bridge reads any bytes. Typert Gateway claims generated Remote endpoints, feature packages register non-JSON responses such as Session-log downloads and raw file uploads, and unclaimed requests return 404. Loopback hostname classification remains package-internal to the browser-facing Client state. Browser raw-body transfer is provided by [`dsh-client-file-upload`](../file-upload/README.md). ----- @@ -42,7 +44,7 @@ Before authentication, every request still passes `src/api-request-trust.ts`. It Every admitted request speaks for one Peer, the operator. `ctx.connection.operator` is that `PeerScope`: its `ctx` is a Cordis scope that owns connection-lifetime registrations and is disposed with the Connection. `ctx.connection.admit(request)` runs the trust and authentication checks and answers with the rejection status or the operator; the `/api` route and the Gateway's WebSocket upgrade admit through it, and every RPC handler receives the Peer of its call. `OperatorPeer` is exported so a composition without Connection, such as the Gateway's in-process carrier, owns an operator scope with the same contract. -Authenticated shared HTTP requests pass through the `connection/request` waterfall before body transfer. A listener may refuse new requests or await `next()` through response completion; removing its owning fiber removes admission behavior. Desktop uses this hook to lock new API work during an approved installation without canceling already-admitted work. WebSocket stream ownership remains with API Gateway. +Authenticated shared HTTP requests pass through the `connection/request` waterfall before body transfer. A listener may refuse new requests or await `next()` through response completion; removing its owning fiber removes admission behavior. Desktop uses this hook to lock new API work during an approved installation without canceling already-admitted work. Client disconnection aborts the handler signal; the bridge stops socket writes and drains any remaining response chunks. WebSocket stream ownership remains with API Gateway. ## Connection generation diff --git a/packages/client/connection/README.zh.md b/packages/client/connection/README.zh.md index 5843efd229..1bf0733bd6 100644 --- a/packages/client/connection/README.zh.md +++ b/packages/client/connection/README.zh.md @@ -27,6 +27,8 @@ kind: "package-reference" 静态桌面页面可以通过 `__DSH_TRANSPORT__.streamBaseUrl` 提供其所拥有 Host 的 HTTP origin。Gateway 将该 origin 用于 WebSocket,HTTP 传输仍独立选择。桌面载体负责认证;仅设置 origin 不会授予访问权限。 +一元 RPC 请求使用 JSON。Host handler 可以返回已经从 JSON 兼容结果值中分离的字节附件,每个附件标明其相对于结果的路径。Connection 将这些值写为 multipart 部分。JSON `metadata` 部分包含带 `null` 占位值的 RPC 响应信封,以及记录各路径、codec 和部分标识符的附件表。路径使用字符串键与数字数组下标,不保留任何业务字段名。Client 校验信封、`rpcId`、附件表和各部分,再将每个字节值恢复为以 `ArrayBuffer` 为底层缓冲区的视图。没有附件的结果(包括 base64 字符串)与失败仍使用 JSON。逻辑 RPC 载体直接返回解码后的原生值。Connection 不识别二进制字段,也不依赖 Typert;拥有结果协议的 handler 在返回前执行按类型或按运行时值的投影。不支持二进制参数、事件和二进制流式结果。 + 浏览器通过 HTTP POST 执行 Remote 一元调用;API Gateway 自己拥有 `/api/remote.mux` WebSocket 及其逻辑流。由 shell 持有的组合通过 `connection.rpc.open` 提供等价的 Remote 流(包括流的上行),不打开 WebSocket。浏览器插件读取页面 transport、恢复设置与 location,再委托 `installConnection(ctx, options)`。持有自身载体的组合可以直接调用同一个安装函数;整机客户端测试档就是这一消费者。每次调用都会创建一个归所属 Context 的服务,因此同一 realm 中的多棵 Client 树可以使用不同载体。Host half 始终提供与载体无关的 RPC 注册表和精确 `GET`/`HEAD`/`POST` 路由注册表。存在 Web 载体时,它还持有唯一 `/api` route、Fetch bridge、浏览器认证与 Host/Origin 校验;由 shell 持有的载体则直接分派共享 Fetch handler。每条精确路由会在 bridge 读取任何字节前声明缓冲或流式请求体处理方式。Typert Gateway 认领生成的 Remote endpoint,功能包注册 Session 日志下载、原始文件上传等非 JSON 响应,未认领的请求返回 404。Loopback hostname 判定只供浏览器侧当前页面状态使用,留在包内。浏览器原始请求体传输由 [`dsh-client-file-upload`](../file-upload/README.zh.md) 提供。 ----- @@ -42,7 +44,7 @@ cookie 签名密钥是 `ctx.credentials` 中由 `client-connection/browser-sessi 每个被接纳的请求都代表同一个 Peer——操作者。`ctx.connection.operator` 就是这个 `PeerScope`:其 `ctx` 是拥有连接期注册的 Cordis scope,随 Connection 一起释放。`ctx.connection.admit(request)` 执行信任与认证检查,以拒绝状态或操作者作答;`/api` 路由与 Gateway 的 WebSocket 升级都经它接纳,每个 RPC 处理器都收到本次调用的 Peer。`OperatorPeer` 对外导出,供没有 Connection 的组合(例如 Gateway 的进程内载体)以同一约定拥有一个操作者 scope。 -通过认证的共享 HTTP 请求在传输请求体之前经过 `connection/request` waterfall。监听器可以拒绝新请求,或等待 `next()` 直到响应完成;释放所属 fiber 会移除准入行为。Desktop 使用此扩展点,在已批准的安装期间锁住新的 API 工作,而不取消已接纳的工作。WebSocket 流仍由 API Gateway 负责。 +通过认证的共享 HTTP 请求在传输请求体之前经过 `connection/request` waterfall。监听器可以拒绝新请求,或等待 `next()` 直到响应完成;释放所属 fiber 会移除准入行为。Desktop 使用此扩展点,在已批准的安装期间锁住新的 API 工作,而不取消已接纳的工作。客户端断开会中止处理函数的信号;桥接器停止写入 socket,并排空剩余响应块。WebSocket 流仍由 API Gateway 负责。 ## Connection generation diff --git a/packages/client/connection/src/client/rpc.ts b/packages/client/connection/src/client/rpc.ts index bf4427b41c..66811432cc 100644 --- a/packages/client/connection/src/client/rpc.ts +++ b/packages/client/connection/src/client/rpc.ts @@ -58,7 +58,11 @@ export function createWebConnectionRpc(doFetch?: RpcFetch, openStream?: RpcStrea if (!response.ok) { throw new Error(`transport failure for ${channel}/${endpoint}: HTTP ${response.status}`) } - const full = parseConnectionResponse(await response.json()) + const mediaType = response.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase() + const full = mediaType === 'multipart/form-data' + ? await parseBinaryResponse(response) + : parseConnectionResponse(await response.json()) + signal?.throwIfAborted() if (full.rpcId !== rpcId) { throw new Error(`rpcId mismatch for ${endpoint}: sent ${rpcId}, got ${full.rpcId}`) } @@ -76,6 +80,60 @@ export function createWebConnectionRpc(doFetch?: RpcFetch, openStream?: RpcStrea } } +async function parseBinaryResponse(response: Response): Promise> { + const body = await response.formData() + const fields = new Map() + for (const [name, value] of body) { + if (fields.has(name)) throw new TypeError('connection: invalid binary response fields') + fields.set(name, value) + } + const metadata = fields.get('metadata') + fields.delete('metadata') + if (typeof metadata !== 'string') { + throw new TypeError('connection: invalid binary response fields') + } + const envelope: unknown = JSON.parse(metadata) + const full = parseConnectionResponse(envelope) + if (!full.result.ok || !isRecord(envelope) || !Array.isArray(envelope.attachments) || envelope.attachments.length === 0) { + throw new TypeError('connection: invalid binary response result') + } + const root = { value: full.result.value } + for (const attachment of envelope.attachments as unknown[]) { + if (!isRecord(attachment) || attachment.codec !== 'bytes' || typeof attachment.part !== 'string' + || !Array.isArray(attachment.path)) { + throw new TypeError('connection: invalid binary response attachment') + } + const data = fields.get(attachment.part) + fields.delete(attachment.part) + if (!(data instanceof Blob)) { + throw new TypeError('connection: invalid binary response fields') + } + let parent: object = root + let key: string | number = 'value' + for (const segment of attachment.path as unknown[]) { + const value = Reflect.get(parent, key) as unknown + if (typeof value !== 'object' || value === null + || (Array.isArray(value) + ? typeof segment !== 'number' || !Number.isSafeInteger(segment) || segment < 0 || segment >= value.length + : typeof segment !== 'string') + || !Object.hasOwn(value, segment as string | number)) { + throw new TypeError('connection: invalid binary response path') + } + parent = value + key = segment as string | number + } + if (Reflect.get(parent, key) !== null) throw new TypeError('connection: invalid binary response placeholder') + Object.defineProperty(parent, key, { + value: new Uint8Array(await data.arrayBuffer()), enumerable: true, writable: true, configurable: true, + }) + } + if (fields.size !== 0) throw new TypeError('connection: invalid binary response fields') + return { + rpcId: full.rpcId, + result: { ok: true, value: root.value }, + } +} + function parseConnectionResponse(value: unknown): { readonly rpcId: RpcIdType readonly result: ConnectionRpcResult diff --git a/packages/client/connection/src/http-bridge.ts b/packages/client/connection/src/http-bridge.ts index ff6042d117..03109936b4 100644 --- a/packages/client/connection/src/http-bridge.ts +++ b/packages/client/connection/src/http-bridge.ts @@ -15,7 +15,7 @@ export const DEFAULT_MAX_REQUEST_BODY_BYTES = 300 * 1024 * 1024 /** * Bridge one node:http request to the fetch-shaped handler (client close - * aborts; response bodies stream out chunk by chunk). + * aborts; response writes respect backpressure and stop on disconnect). * @param req - incoming node:http request. * @param res - node:http response the bridge writes and owns to completion. * @param apiHandler - fetch-shaped API carrier the request is dispatched to. @@ -90,11 +90,13 @@ export async function bridge( return } for await (const chunk of response.body) { + // Drain without writing after disconnect: cancelling Node multipart bodies + // can race their producer and reject with ERR_INVALID_STATE. + if (abort.signal.aborted) continue // Backpressure: a false return means the socket buffer is full — wait for drain // instead of buffering unboundedly (slow or suspended consumers). 'close' also - // resolves so a mid-wait disconnect can't park this loop forever; the close - // handler above aborts the handler stream, which then ends the iteration. - if (!res.write(chunk)) { + // resolves so a mid-wait disconnect cannot park this loop forever. + if (!res.write(chunk) && !res.destroyed) { await new Promise((resolve) => { const done = (): void => { res.off('drain', done) diff --git a/packages/client/connection/src/rpc-host.ts b/packages/client/connection/src/rpc-host.ts index ba6f2736d6..2007e3a32d 100644 --- a/packages/client/connection/src/rpc-host.ts +++ b/packages/client/connection/src/rpc-host.ts @@ -292,9 +292,65 @@ function errorResponse(rpcId: RpcIdType, error: ConnectionRpcFailure): Response return fullResponse(rpcId, { ok: false, error }) } -function fullResponse(rpcId: RpcIdType, result: ConnectionRpcResult): Response { +function fullResponse(rpcId: RpcIdType, result: Awaited>): Response { const body: ConnectionServerResponse = { type: 'server-response', rpcId, result } - return Response.json(body) + if (!result.ok) return Response.json(body) + const parts = new FormData() + const attachments: { path: (string | number)[]; codec: 'bytes'; part: string }[] = [] + const path: (string | number)[] = [] + const ancestors = new Set() + const writeBytes = (value: Uint8Array, path: readonly (string | number)[]): null => { + const part = `bytes-${attachments.length}` + attachments.push({ path: [...path], codec: 'bytes', part }) + // FileSystem bytes may have SharedArrayBuffer backing, which BlobPart excludes. + parts.set(part, new Blob([new Uint8Array(value)])) + return null + } + const extract = (input: unknown, key: string): unknown => { + // Capture accessors and toJSON once, before materializing the JSON metadata. + let value = input + if (input !== null && typeof input === 'object' && !(input instanceof Uint8Array)) { + const toJSON = Reflect.get(input, 'toJSON') as unknown + if (typeof toJSON === 'function') value = Reflect.apply(toJSON, input, [key]) as unknown + } + if (value instanceof Uint8Array) return writeBytes(value, path) + if (typeof value !== 'object' || value === null) return value + if (value instanceof Number || value instanceof String || value instanceof Boolean) return value + if (ancestors.has(value)) throw new TypeError('connection: circular RPC result') + ancestors.add(value) + let copy: object + if (Array.isArray(value)) { + const items: unknown[] = [] + // JSON arrays include every index, even holes and non-enumerable elements. + for (let index = 0, length = value.length; index < length; index++) items.push(child(value[index], index)) + copy = items + } else { + const fields: Record = {} + for (const key of Object.keys(value)) { + const item = Reflect.get(value, key) as unknown + // A toJSON method on the projected object must not run a second time. + if (key === 'toJSON' && typeof item === 'function') continue + const extracted = child(item, key) + if (key === '__proto__') Object.defineProperty(fields, key, { value: extracted, enumerable: true }) + else fields[key] = extracted + } + copy = fields + } + ancestors.delete(value) + return copy + } + const child = (value: unknown, key: string | number): unknown => { + if (typeof value !== 'object' || value === null) return value + path.push(key) + const extracted = extract(value, String(key)) + path.pop() + return extracted + } + const value = result.encode === undefined ? extract(result.value, 'value') : result.encode(result.value, writeBytes) + const metadata = { ...body, result: { ok: true, value } } + if (attachments.length === 0) return Response.json(metadata) + parts.set('metadata', JSON.stringify({ ...metadata, attachments })) + return new Response(parts) } function assertChannel(channel: string): void { diff --git a/packages/client/connection/src/rpc.ts b/packages/client/connection/src/rpc.ts index e77562acfd..0b8755bf71 100644 --- a/packages/client/connection/src/rpc.ts +++ b/packages/client/connection/src/rpc.ts @@ -27,6 +27,24 @@ export type ConnectionRpcResult = | { readonly ok: true; readonly value: T } | { readonly ok: false; readonly error: ConnectionRpcFailure } +/** One binary value separated from a successful RPC result before transport framing. */ +export interface ConnectionRpcAttachment { + /** Result-relative path occupied by the attachment's `null` placeholder. */ + readonly path: readonly (string | number)[] + /** Byte view carried outside the JSON response metadata. */ + readonly bytes: Uint8Array +} + +/** Successful or failed handler result ready for Connection transport framing. */ +export type ConnectionRpcHandlerResult = + | { + readonly ok: true + readonly value: unknown + /** Binary fields already projected by the handler that owns the result protocol. */ + readonly attachments?: readonly ConnectionRpcAttachment[] + } + | { readonly ok: false; readonly error: ConnectionRpcFailure } + /** Historical short name for a generic Connection result. */ export type RpcResult = ConnectionRpcResult @@ -111,7 +129,7 @@ export type ConnectionRpcHandler = ( payload: unknown, signal: AbortSignal, peer: PeerScope, -) => Promise> +) => Promise /** Synchronous ownership test for one endpoint on a shared RPC channel. */ export type ConnectionRpcEndpointMatcher = (endpoint: string) => boolean diff --git a/packages/client/connection/tests/binary-rpc.host.spec.ts b/packages/client/connection/tests/binary-rpc.host.spec.ts new file mode 100644 index 0000000000..b65fefed19 --- /dev/null +++ b/packages/client/connection/tests/binary-rpc.host.spec.ts @@ -0,0 +1,309 @@ +import { request } from 'node:http' +import { gunzipSync } from 'node:zlib' +import { Context } from '@deepseek-ai/cordis' +import WebServer from '@deepseek-ai/dsh-host-webserver' +import { describe, expect, it } from 'vitest' +import type { BrowserAuth } from '../src/browser-auth.ts' +import { createWebConnectionRpc } from '../src/client/rpc.ts' +import { bridge } from '../src/http-bridge.ts' +import type { ConnectionRpcResult } from '../src/rpc.ts' +import { HostConnectionService } from '../src/rpc-host.ts' + +function binaryResponse(rpcId: string, mutate: (parts: FormData) => void = () => {}): Response { + const parts = new FormData() + parts.set('metadata', JSON.stringify({ + type: 'server-response', rpcId, result: { ok: true, value: { offset: 7, data: null } }, + attachments: [{ path: ['data'], codec: 'bytes', part: 'bytes-0' }], + })) + parts.set('bytes-0', new Blob([new Uint8Array([0, 128, 255])])) + mutate(parts) + return new Response(parts) +} + +describe('Connection binary RPC', () => { + it.each(['gzip', 'none'] as const)('preserves %s configuration through the HTTP bridge', async (compression) => { + const ctx = new Context() + try { + await ctx.plugin(WebServer, { host: '127.0.0.1', port: 0, compression }) + await ctx.plugin((owner) => { new HostConnectionService(owner, [], {} as BrowserAuth) }) + const connection = ctx.get('connection') as HostConnectionService + const data = new Uint8Array(1024 * 1024).fill(65) + data.set([0, 128, 255]) + connection.rpc.intercept('/api', endpoint => endpoint === 'fixture/read', async () => ({ ok: true, value: { data, bytes: data.length } })) + const handler = connection.createSharedFetchHandler('/api') + ctx.webServer.register({ kind: 'prefix', path: '/api', handler: (req, res) => bridge(req, res, handler) }) + let transferred = 0 + let encoding: string | undefined + const rpc = createWebConnectionRpc((path, init) => new Promise((resolve, reject) => { + const req = request(new URL(path, `http://127.0.0.1:${ctx.webServer.port}`), { + method: init.method, + headers: { ...Object.fromEntries(new Headers(init.headers)), 'accept-encoding': 'gzip' }, + }, (response) => { + void (async () => { + const chunks: Buffer[] = [] + for await (const chunk of response) chunks.push(chunk as Buffer) + const body = Buffer.concat(chunks) + transferred = body.length + encoding = response.headers['content-encoding'] + return new Response(encoding === 'gzip' ? gunzipSync(body) : body, { + status: response.statusCode!, + headers: { 'content-type': response.headers['content-type']! }, + }) + })().then(resolve, reject) + }) + req.once('error', reject) + req.end(init.body as string) + })) + expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: { data, bytes: data.length } }) + if (compression === 'gzip') { + expect(encoding).toBe('gzip') + expect(transferred).toBeLessThan(data.length / 10) + } else { + expect(encoding).toBeUndefined() + expect(transferred).toBeGreaterThan(data.length) + } + } finally { + await ctx.fiber.dispose() + } + }) + + it('roundtrips raw bytes and metadata on the existing channel while JSON results and errors stay JSON', async () => { + const ctx = new Context() + const fiber = ctx.plugin((owner) => { new HostConnectionService(owner, [], {} as BrowserAuth) }) + await fiber.await() + try { + const connection = ctx.get('connection') as HostConnectionService + const results: ConnectionRpcResult[] = [ + { ok: true, value: { data: new Uint8Array([9, 0, 128, 255, 9]).subarray(1, 4), offset: 7, eof: false, bytes: 42 } }, + { ok: true, value: { data: new Uint8Array(new SharedArrayBuffer(3)).fill(255), offset: 0, eof: true, bytes: 3 } }, + { ok: true, value: { data: new Uint8Array(), offset: 0, eof: true, bytes: 0 } }, + { ok: true, value: { data: 'AID/', encoding: 'base64' } }, + { ok: true, value: { count: 4 } }, + { ok: true, value: null }, + { ok: true, value: 'plain' }, + { ok: false, error: { code: 'fixture/denied', message: 'denied', details: { path: 'private' } } }, + ] + let next: ConnectionRpcResult = results[0]! + connection.rpc.intercept('/api', endpoint => endpoint === 'fixture/read', async () => next) + const shared = connection.createSharedFetchHandler('/api') + const mediaTypes: (string | null)[] = [] + const rpc = createWebConnectionRpc(async (url, init) => { + const response = await shared.fetch(new Request(new URL(url, 'http://host'), init)) + mediaTypes.push(response.headers.get('content-type')) + return response + }) + for (const result of results) { + next = result + const received = await rpc.call('/api', 'fixture/read', { args: {} }) + expect(received).toEqual(result) + if (received.ok && typeof received.value === 'object' && received.value !== null + && 'data' in received.value && received.value.data instanceof Uint8Array) { + expect(received.value.data.buffer).toBeInstanceOf(ArrayBuffer) + } + } + expect(mediaTypes.slice(0, 3).every(type => type?.startsWith('multipart/form-data;'))).toBe(true) + expect(mediaTypes.slice(3)).toEqual(Array(5).fill('application/json')) + } finally { + await fiber.dispose() + } + }) + + it('uses owner result codecs without putting their callbacks on the wire', async () => { + const ctx = new Context() + const fiber = ctx.plugin((owner) => { new HostConnectionService(owner, [], {} as BrowserAuth) }) + await fiber.await() + try { + const connection = ctx.get('connection') as HostConnectionService + const content = Buffer.from([9, 0, 128, 255, 9]).subarray(1, 4) + let reads = 0 + const value = { content, metadata: { get count() { return ++reads } } } + connection.rpc.intercept('/api', () => true, async () => ({ + ok: true, value, + encode: (input, writeBytes) => { + expect(input).toBe(value) + return { content: writeBytes(content, ['content']), metadata: value.metadata } + }, + })) + const handler = connection.createSharedFetchHandler('/api') + const rpc = createWebConnectionRpc((url, init) => handler.fetch(new Request(new URL(url, 'http://host'), init))) + expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ + ok: true, value: { content: new Uint8Array([0, 128, 255]), metadata: { count: 1 } }, + }) + expect(reads).toBe(1) + } finally { + await fiber.dispose() + } + }) + + it.each([ + ['missing bytes', (p: FormData) => { p.delete('bytes-0') }], + ['text bytes', (p: FormData) => { p.set('bytes-0', 'AID/') }], + ['missing metadata', (p: FormData) => { p.delete('metadata') }], + ['file metadata', (p: FormData) => { p.set('metadata', new Blob(['{}'])) }], + ['duplicate metadata', (p: FormData) => { p.append('metadata', '{}') }], + ['duplicate bytes', (p: FormData) => { p.append('bytes-0', new Blob()) }], + ['extra part', (p: FormData) => { p.set('extra', 'unclaimed') }], + ['invalid JSON', (p: FormData) => { p.set('metadata', '{') }], + ['invalid envelope', (p: FormData) => { p.set('metadata', '{}') }], + ...[ + { ok: false, error: { code: 'fixture/error', message: 'failed', details: {} } }, + { ok: true, value: null }, + { ok: true, value: [] }, + { ok: true, value: { data: 'duplicate' } }, + ].map(result => ['invalid result', (p: FormData) => { p.set('metadata', JSON.stringify({ + type: 'server-response', rpcId: 'fixture', result, + })) }] as const), + ] satisfies readonly (readonly [string, (parts: FormData) => void])[])('rejects malformed multipart: %s', async (_name, mutate) => { + const rpc = createWebConnectionRpc(async (_url, init) => { + const message = JSON.parse(init.body as string) as { rpcId: string } + return binaryResponse(message.rpcId, mutate) + }) + await expect(rpc.call('/api', 'fixture/read', {})).rejects.toThrow(/invalid binary response|invalid server-response|JSON/) + }) + + it('rejects a binary response for another request', async () => { + const rpc = createWebConnectionRpc(async () => binaryResponse('unrelated')) + await expect(rpc.call('/api', 'fixture/read', {})).rejects.toThrow('rpcId mismatch') + }) + + it('roundtrips nested, optional and root bytes without changing caller objects or reserving field names', async () => { + const ctx = new Context() + const fiber = ctx.plugin((owner) => { new HostConnectionService(owner, [], {} as BrowserAuth) }) + await fiber.await() + try { + const data = new Uint8Array([0, 128, 255]) + const shared = { content: data } + const value = { + files: [{ name: 'a.png', ...shared }, { name: 'b.png', content: Buffer.from([9, 2, 3, 9]).subarray(1, 3) }, { name: 'empty' }], + 'dots./[]': [new Uint8Array(), null, [data]], + metadata: { attachments: shared }, + ...JSON.parse('{"__proto__":null,"constructor":null}') as object, + } + Object.defineProperty(value, '__proto__', { value: data, enumerable: true }) + Object.freeze(value.files) + Object.freeze(value) + let next: unknown = value + const connection = ctx.get('connection') as HostConnectionService + connection.rpc.intercept('/api', () => true, async () => ({ ok: true, value: next })) + const handler = connection.createSharedFetchHandler('/api') + const rpc = createWebConnectionRpc((url, init) => handler.fetch(new Request(new URL(url, 'http://host'), init))) + expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: { + ...value, files: [value.files[0], { name: 'b.png', content: new Uint8Array([2, 3]) }, value.files[2]], + } }) + expect(value.files[0]?.content).toBe(data) + expect(shared.content).toBe(data) + expect(Object.getPrototypeOf(value)).toBe(Object.prototype) + for (const bytes of [data, Buffer.from([0, 128, 255]), new Uint8Array(new SharedArrayBuffer(3))]) { + next = bytes + const response = await rpc.call('/api', 'fixture/read', {}) + expect(response).toEqual({ ok: true, value: new Uint8Array(bytes) }) + if (!response.ok || !(response.value instanceof Uint8Array)) throw new Error('expected root bytes') + expect(response.value.buffer).toBeInstanceOf(ArrayBuffer) + expect(Object.isFrozen(response.value)).toBe(false) + } + next = [data, [data]] + expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: next }) + const circular: { next?: object } = {} + circular.next = circular + next = circular + await expect(rpc.call('/api', 'fixture/read', {})).rejects.toThrow('HTTP 500') + next = { ordinary: [1, 'base64', null], omitted: undefined, date: new Date('2026-01-01T00:00:00Z') } + expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: { + ordinary: [1, 'base64', null], date: '2026-01-01T00:00:00.000Z', + } }) + const sparse = [data, , null] + Object.assign(sparse, { extra: data, '-1': data, '01': data, '1.5': data, Infinity: data }) + next = sparse + expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: [data, null, null] }) + } finally { + await fiber.dispose() + } + }) + + it.each([ + ['absent table', { attachments: undefined }], + ['non-array table', { attachments: {} }], + ['empty table', { attachments: [] }], + ...[ + null, {}, { path: ['data'], codec: 'numpy', part: 'bytes-0' }, + { path: ['data'], codec: 'bytes', part: 0 }, + { path: ['data'], codec: 'bytes', part: 'metadata' }, + { path: 'data', codec: 'bytes', part: 'bytes-0' }, + ...[['missing'], ['offset', 'child'], ['constructor', 'prototype'], [0], ['files', '0'], ['files', -1], ['files', 0.5], ['files', 1], ['files', false], ['files', null]].map(path => ({ path, codec: 'bytes', part: 'bytes-0' })), + ].map(attachment => ['invalid attachment', { attachments: [attachment] }] as const), + ['duplicate part', { attachments: [0, 1].map(() => ({ path: ['data'], codec: 'bytes', part: 'bytes-0' })) }], + ['duplicate path', { attachments: [0, 1].map(i => ({ path: ['data'], codec: 'bytes', part: `bytes-${i}` })) }], + ['overlapping path', { attachments: [ + { path: ['data'], codec: 'bytes', part: 'bytes-0' }, + { path: ['data', '0'], codec: 'bytes', part: 'bytes-1' }, + ] }], + ['occupied placeholder', { result: { ok: true, value: { data: 'AID/' } } }], + ] satisfies readonly (readonly [string, Record])[])('rejects malformed attachment metadata: %s', async (_name, overrides) => { + const rpc = createWebConnectionRpc(async (_url, init) => { + const { rpcId } = JSON.parse(init.body as string) as { rpcId: string } + return binaryResponse(rpcId, (parts) => { + const metadata = JSON.parse(parts.get('metadata') as string) as Record + parts.set('metadata', JSON.stringify({ ...metadata, result: { ok: true, value: { data: null, offset: 7, files: [null] } }, ...overrides })) + if (_name === 'duplicate path' || _name === 'overlapping path') parts.set('bytes-1', new Blob()) + }) + }) + await expect(rpc.call('/api', 'fixture/read', {})).rejects.toThrow('invalid binary response') + }) + + it('preserves JSON accessor and toJSON evaluation while reading all array indices', async () => { + const ctx = new Context() + const fiber = ctx.plugin((owner) => { new HostConnectionService(owner, [], {} as BrowserAuth) }) + await fiber.await() + try { + let reads = 0 + let next: unknown = { get count() { return ++reads } } + const connection = ctx.get('connection') as HostConnectionService + connection.rpc.intercept('/api', () => true, async () => ({ ok: true, value: next })) + const handler = connection.createSharedFetchHandler('/api') + const rpc = createWebConnectionRpc((url, init) => handler.fetch(new Request(new URL(url, 'http://host'), init))) + const read = () => rpc.call('/api', 'fixture/read', {}) + expect(await read()).toEqual({ ok: true, value: { count: 1 } }) + expect(reads).toBe(1) + const bytes = new Uint8Array([1, 2]) + next = { get content() { reads++; return bytes }, get count() { return ++reads } } + expect(await read()).toEqual({ ok: true, value: { content: bytes, count: 3 } }) + const array: Uint8Array[] = [] + Object.defineProperty(array, 0, { value: bytes }) + next = array + expect(await read()).toEqual({ ok: true, value: [bytes] }) + const date = Object.assign(new Date('2026-01-01T00:00:00Z'), { content: bytes }) + next = date + expect(await read()).toEqual({ ok: true, value: '2026-01-01T00:00:00.000Z' }) + const json = { self: {} as object, toJSON: () => ({ selected: true }) } + json.self = json + next = json + expect(await read()).toEqual({ ok: true, value: { selected: true } }) + let conversions = 0 + next = { toJSON(key: string) { conversions++; expect(key).toBe('value'); return this }, count: 5 } + expect(await read()).toEqual({ ok: true, value: { count: 5 } }) + expect(conversions).toBe(1) + for (const primitive of [1, 'text', true]) { + next = Object(primitive) as object + expect(await read()).toEqual({ ok: true, value: primitive }) + } + next = { toJSON: 'ordinary' } + expect(await read()).toEqual({ ok: true, value: next }) + } finally { + await fiber.dispose() + } + }) + + it('rejects truncated multipart and late bytes after caller cancellation', async () => { + const broken = createWebConnectionRpc(async () => new Response('truncated', { + headers: { 'content-type': 'multipart/form-data; boundary=fixture' }, + })) + await expect(broken.call('/api', 'fixture/read', {})).rejects.toThrow() + const abort = new AbortController() + const rpc = createWebConnectionRpc(async (_url, init) => { + const message = JSON.parse(init.body as string) as { rpcId: string } + abort.abort(new Error('caller left')) + return binaryResponse(message.rpcId) + }) + await expect(rpc.call('/api', 'fixture/read', {}, abort.signal)).rejects.toThrow('caller left') + }) +}) diff --git a/packages/client/connection/tests/http-bridge.host.spec.ts b/packages/client/connection/tests/http-bridge.host.spec.ts index 9dc6df8405..8d972824b9 100644 --- a/packages/client/connection/tests/http-bridge.host.spec.ts +++ b/packages/client/connection/tests/http-bridge.host.spec.ts @@ -75,6 +75,71 @@ describe('HTTP bridge abort', () => { expect(carrierSignal?.aborted).toBe(true) }) + it.each(['write', 'backpressure'])('finishes a multipart response without further writes when the client closes during %s', async (phase) => { + const request = Readable.from([]) as unknown as IncomingMessage + Object.assign(request, { url: '/api/workspaceFiles/readBytes', method: 'GET', headers: {} }) + const body = new FormData() + body.set('metadata', '{}') + body.set('data', new Blob([new Uint8Array(16 * 1024 * 1024)])) + let writes = 0 + let cleaningUp = false + const response = Object.assign(new EventEmitter(), { + writableEnded: false, + writeHead() { return this }, + write() { + writes++ + if (writes === 1) { + const close = (): void => { response.destroyed = true; response.emit('close') } + if (phase === 'write') close() + else queueMicrotask(close) + } + return cleaningUp + }, + end() { this.writableEnded = true; return this }, + }) as unknown as ServerResponse + let settled = false + const pending = bridge(request, response, { + requestBodyMode: () => 'buffered', + fetch: async () => new Response(body), + }).then(() => { settled = true }) + try { + await expect.poll(() => settled).toBe(true) + expect(writes).toBe(1) + expect(response.listenerCount('drain')).toBe(0) + } finally { + // Release a regressed bridge parked after the one close event. + cleaningUp = true + response.emit('drain') + await pending + } + }) + + it('discards bytes returned after the client disconnects', async () => { + const request = Readable.from([]) as unknown as IncomingMessage + Object.assign(request, { url: '/api/workspaceFiles/readBytes', method: 'GET', headers: {} }) + const response = Object.assign(new EventEmitter(), { + writableEnded: false, + writeHead() { return this }, + write() { throw new Error('a disconnected response must not receive bytes') }, + end() { this.writableEnded = true; return this }, + }) as unknown as ServerResponse + const started = Promise.withResolvers() + let controller!: ReadableStreamDefaultController + const body = new ReadableStream({ + start(value) { controller = value }, + pull() { started.resolve(undefined) }, + }) + const pending = bridge(request, response, { + requestBodyMode: () => 'buffered', + fetch: async () => new Response(body), + }) + await started.promise + response.emit('close') + controller.enqueue(Uint8Array.of(1)) + controller.close() + await pending + }) + it('streams a declared 2.19 GiB request before the body ends and bypasses the JSON buffer cap', async () => { const request = new Readable({ read() {} }) as IncomingMessage Object.assign(request, { diff --git a/packages/client/connection/tsconfig.host.json b/packages/client/connection/tsconfig.host.json index c291ff868d..66d9844f17 100644 --- a/packages/client/connection/tsconfig.host.json +++ b/packages/client/connection/tsconfig.host.json @@ -9,6 +9,8 @@ "src/api-path.ts", "src/api-request-trust.ts", "src/browser-auth.ts", + "src/client/random-uuid.ts", + "src/client/rpc.ts", "src/http-bridge.ts", "src/index.ts", "src/loopback-hostname.ts", diff --git a/packages/client/ui-sidebar-documentpreview/README.i18n.yaml b/packages/client/ui-sidebar-documentpreview/README.i18n.yaml index 141c7e0474..faad4651ee 100644 --- a/packages/client/ui-sidebar-documentpreview/README.i18n.yaml +++ b/packages/client/ui-sidebar-documentpreview/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-sidebar-documentpreview/README.md -README.md: 2797d6fd6be8f429043c8de1413f90e64bda3876 -README.zh.md: a04571ed6d76ca812aa0a70ce6f3c403ad80947d +README.md: 79c7253887cd580bdcc725054c0bbf5b2877e90b +README.zh.md: 77847e8ce7a9203a85fee360ec8a481e32e7e871 diff --git a/packages/client/ui-sidebar-documentpreview/README.md b/packages/client/ui-sidebar-documentpreview/README.md index 2797d6fd6b..79c7253887 100644 --- a/packages/client/ui-sidebar-documentpreview/README.md +++ b/packages/client/ui-sidebar-documentpreview/README.md @@ -51,10 +51,10 @@ The body reads its record, navigation and lifetime through `useTabInfo().tab`. ` - The resource snapshot contains only `status`, `value`, and `failure`; `value` is `WorkspaceFileStat` metadata. Content reads do not wait for the first metadata frame once the provider is available. Observation failures take precedence over Preview's change notice; loaded content remains while metadata is unavailable. - **Text pages** — plain text, Markdown, and code read through an inject callback to `remote.workspaceFiles.read(sessionId, path, { offset }, signal)`. The first mount reads page one; scrolling to the body end or **Load more** requests the next page until `eof`. The owner delivers the accumulated prefix as `{ kind: 'text', text, pages, eof }`, including source offsets and line counts. Markdown and code render that prefix incrementally; they do not render each page as a separate document. A newer-version page past page one restarts from the beginning rather than mixing versions. A failure before any content fills the body with the file-type icon, the explanation, and the recourse the failure names (Retry, the unpreviewable child slot, or nothing); a later failure retains loaded content and adds the retry below it. -- **Complete bytes** — PDF, HTML, and common images use an inject callback to `remote.workspaceFiles.readAll(sessionId, path, signal)`. `rpc.ts` decodes the wire base64 into `data: Uint8Array` for `{ kind: 'bytes', data }`. The Host's `maxFileBytes` cap rejects oversized files rather than truncating them. PDF copies retained bytes before worker transfer, keeping the Preview buffer usable. Bytes stay in transient view state, never persisted layouts or Session JSONL. Loading-mode changes retire previous results. -- **Reload** — manual reload rereads only the current Preview tab through its Remote callbacks, preserving its scroll preference and retiring older requests. Automatic refresh uses the same callbacks after a ResourceGroup member changes. Each member's first metadata establishes a baseline without triggering reload or first-read version reconciliation; later changes received during a read remain pending for another refresh. Reads neither refresh shared metadata nor clear another tab's notice. +- **Complete bytes** — PDF, HTML, and common images call `remote.workspaceFiles.readBytes(sessionId, path, {}, signal)`. The binary Remote returns `data: Uint8Array` directly for `{ kind: 'bytes', data }`. The Host's `maxFileBytes` cap rejects oversized files rather than truncating them. PDF copies retained bytes before worker transfer, keeping the Preview buffer usable. Bytes stay in transient view state, never persisted layouts or Session JSONL. Loading-mode changes retire previous results. +- **Reload** — manual reload rereads only the current Preview tab through its Remote callbacks, preserving its scroll preference and retiring older requests. Automatic refresh uses the same callbacks after a `ResourceGroup` member changes. Each member's first metadata establishes a baseline without triggering reload or first-read version reconciliation; later changes received during a read remain pending for another refresh. Reads neither refresh shared metadata nor clear another tab's notice. -When Developer tools is enabled, HTML fills the body edge to edge in a Blob iframe with exactly `sandbox="allow-scripts"`, without `allow-same-origin`; scripts cannot access the parent application's origin or file reader. The renderer loads directly declared relative `.js` classic scripts and `.css` stylesheets through its ordinary inject callback to `remote.workspaceFiles.readRelated`, with fixed safety limits of 4 MiB per asset, 32 MiB total, and 64 distinct assets. Host code resolves the related path; `rpc.ts` decodes the returned bytes. The dependency Resource is added after `readRelated` returns, using its `absolutePath` or a string `error.details.path` on failure; without a Host path, the Client does not guess one. Inside the renderer, base64 is used only to embed the iframe bootstrap payload in script text. A `` leaves dependency resolution to the browser, as do HTTPS resources. Local module imports, CSS `url()`/`@import`, and dynamic `fetch` do not use Host file access. Read failures, invalid UTF-8, or exceeded limits fail the preview rather than publishing a partial asset package. Replacing or unmounting the document releases its Blob URL. +When Developer tools is enabled, HTML fills the body edge to edge in a Blob iframe with exactly `sandbox="allow-scripts"`, without `allow-same-origin`; scripts cannot access the parent application's origin or file reader. The renderer loads directly declared relative `.js` classic scripts and `.css` stylesheets through its injected Remote callback, with fixed safety limits of 4 MiB per asset, 32 MiB total, and 64 distinct assets. Host code resolves the related path, and `readBytes` with `baseFile` returns native bytes. The dependency Resource is added after the read returns, using its `absolutePath` or a string `error.details.path` on failure; without a Host path, the Client does not guess one. Inside the renderer, base64 is used only to embed the iframe bootstrap payload in script text. A `` leaves dependency resolution to the browser, as do HTTPS resources. Local module imports, CSS `url()`/`@import`, and dynamic `fetch` do not use Host file access. Read failures, invalid UTF-8, or exceeded limits fail the preview rather than publishing a partial asset package. Replacing or unmounting the document releases its Blob URL. PNG, JPEG, GIF, WebP, BMP, ICO, and SVG render through Blob URLs in an `` static-image context, rounded inside a 12px inset. A wider image scales down to the pane's width at its intrinsic aspect ratio, a smaller image centres at its intrinsic CSS-pixel dimensions, and a taller image scrolls vertically. The renderer provides neither zoom nor drag-to-pan. SVG markup never enters the application DOM or an iframe, so its scripts cannot execute or reach the parent page. Replacing or unmounting the image revokes its Blob URL. @@ -86,7 +86,7 @@ A yellow rounded-triangle warning appears before Reload in the document toolbar Office registration, loading, caching, and font notices live in `src/client/office/`. The Office body owns converted PDF bytes and font metadata, and declares a nested PDF slot that reuses the lazy PDF body and its tab viewing state. The keyed `sidebar.right.tab.document.action` slot places renderer controls before Reload. The Office action shares the body’s store and reads only the current revision’s font metadata. Registration remains available without the Host renderer; optional `remote.officeToPdf` and `remote.workspaceFiles` injections supply conversion and freshness callbacks, and their removal restores unavailable guidance. Registrations and tab retention follow effect lifetimes. The [conversion service](../../document/office-to-pdf/README.md) owns the Host Remote methods, mounted by `api/remotes`. -The shared `documentFileBytes()` helper decodes ordinary file and converted PDF responses into one owned byte buffer without expanding bytes into JavaScript array elements. Renderers borrow retained bytes read-only and copy them before Worker transfer. +The `documentFileBytes()` helper decodes converted Office PDF responses into one owned byte buffer without expanding bytes into JavaScript array elements. Renderers borrow retained bytes read-only and copy them before Worker transfer. diff --git a/packages/client/ui-sidebar-documentpreview/README.zh.md b/packages/client/ui-sidebar-documentpreview/README.zh.md index a04571ed6d..77847e8ce7 100644 --- a/packages/client/ui-sidebar-documentpreview/README.zh.md +++ b/packages/client/ui-sidebar-documentpreview/README.zh.md @@ -51,10 +51,10 @@ Web 和桌面端均通过开发者工具选择 HTML 预览策略。渲染器从 - 资源快照仅包含 `status`、`value` 和 `failure`;`value` 是 `WorkspaceFileStat` 元数据。提供方可用后,内容读取无需等待首个元数据帧。观察失败优先于 Preview 的变更提示显示;元数据不可用时保留已加载内容。 - **文本页** —— 纯文本、Markdown 和代码通过 inject 回调调用 `remote.workspaceFiles.read(sessionId, path, { offset }, signal)`。首次挂载读取第一页;滚动到正文末尾或点击 **加载更多** 会读取下一页,直到 `eof`。owner 以 `{ kind: 'text', text, pages, eof }` 提供累计前缀,包含源码偏移和行数。Markdown 和代码增量渲染此前缀,不把每页当成独立文档。第一页之后到达的更新版本页会使读取从头开始,避免混合版本。尚无内容时,失败会以文件类型图标、说明和该失败对应的出路(重试、unpreviewable 子 slot,或什么都不给)填满正文;较晚的失败保留已有内容并在其下提供重试。 -- **完整字节** —— PDF、HTML 和常见图片通过 inject 回调调用 `remote.workspaceFiles.readAll(sessionId, path, signal)`。`rpc.ts` 将线路上的 base64 解码为 `data: Uint8Array`,供 `{ kind: 'bytes', data }` 使用。Host 的 `maxFileBytes` 上限拒绝超大文件,不截断。PDF 在传给 worker 前复制保留的字节,使 Preview 缓冲区仍可使用。字节仅保存在临时视图状态中,绝不进入持久布局或 Session JSONL。加载模式变化会淘汰先前结果。 -- **重新载入** —— 手动重新载入仅让当前 Preview tab 通过自己的 Remote 回调重读,保留滚动偏好并淘汰旧请求。ResourceGroup 成员变化后,自动刷新使用相同回调。各成员首次元数据仅建立基线,不触发重新载入或首读版本对账;后续在读取期间收到的变化仍会留待下一次刷新。读取既不刷新共享元数据,也不清除其它 tab 的提示。 +- **完整字节** —— PDF、HTML 和常见图片调用 `remote.workspaceFiles.readBytes(sessionId, path, {}, signal)`。二进制 Remote 直接返回 `data: Uint8Array`,供 `{ kind: 'bytes', data }` 使用。Host 的 `maxFileBytes` 上限拒绝超大文件,不截断。PDF 在传给 worker 前复制保留的字节,使 Preview 缓冲区仍可使用。字节仅保存在临时视图状态中,绝不进入持久布局或 Session JSONL。加载模式变化会淘汰先前结果。 +- **重新载入** —— 手动重新载入仅让当前 Preview tab 通过自己的 Remote 回调重读,保留滚动偏好并淘汰旧请求。`ResourceGroup` 成员变化后,自动刷新使用相同回调。各成员首次元数据仅建立基线,不触发重新载入或首读版本对账;后续在读取期间收到的变化仍会留待下一次刷新。读取既不刷新共享元数据,也不清除其它 tab 的提示。 -开启开发者工具时,HTML 以贴合正文四边的 Blob iframe 运行,沙箱属性严格为 `sandbox="allow-scripts"`,不含 `allow-same-origin`;脚本无法访问父应用的源或文件读取接口。渲染器通过普通 inject 回调调用 `remote.workspaceFiles.readRelated`,加载直接声明的相对 `.js` 经典脚本和 `.css` 样式表;固定安全上限为单个资源 4 MiB、总计 32 MiB、64 个不同资源。Host 代码解析关联路径,`rpc.ts` 解码返回的字节。依赖 Resource 在 `readRelated` 返回后加入,使用返回的 `absolutePath`,失败时则使用字符串类型的 `error.details.path`;没有 Host 路径时,Client 不自行猜测。在渲染器内部,base64 仅用于把 iframe 引导载荷嵌入脚本文本。`` 将依赖解析交给浏览器,HTTPS 资源也由浏览器处理。本地模块 import、CSS `url()`/`@import` 和动态 `fetch` 不使用 Host 文件访问。读取失败、无效 UTF-8 或超出上限都使预览失败,不发布部分资源包。替换或卸载文档会释放其 Blob URL。 +开启开发者工具时,HTML 以贴合正文四边的 Blob iframe 运行,沙箱属性严格为 `sandbox="allow-scripts"`,不含 `allow-same-origin`;脚本无法访问父应用的源或文件读取接口。渲染器通过注入的 Remote 回调,加载直接声明的相对 `.js` 经典脚本和 `.css` 样式表;固定安全上限为单个资源 4 MiB、总计 32 MiB、64 个不同资源。Host 代码解析关联路径,带 `baseFile` 的 `readBytes` 返回原生字节。依赖 Resource 在读取返回后加入,使用返回的 `absolutePath`,失败时则使用字符串类型的 `error.details.path`;没有 Host 路径时,Client 不自行猜测。在渲染器内部,base64 仅用于把 iframe 引导载荷嵌入脚本文本。`` 将依赖解析交给浏览器,HTTPS 资源也由浏览器处理。本地模块 import、CSS `url()`/`@import` 和动态 `fetch` 不使用 Host 文件访问。读取失败、无效 UTF-8 或超出上限都使预览失败,不发布部分资源包。替换或卸载文档会释放其 Blob URL。 PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 通过 Blob URL 在 `` 静态图片上下文中渲染,带 12px 内边距和圆角。宽图按固有纵横比缩小到面板宽度,小图按固有 CSS 像素尺寸居中,超高图纵向滚动。渲染器既不提供缩放,也不提供拖拽平移。SVG 标记绝不进入应用 DOM 或 iframe,因此其中的脚本无法执行,也无法访问父页面。替换或卸载图片会撤销其 Blob URL。 @@ -86,7 +86,7 @@ PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 通过 Blob URL 在 `` 静态 Office 注册、加载、缓存和字体提示位于 `src/client/office/`。Office 正文持有转换后的 PDF 字节和字体元数据,并声明嵌套 PDF slot,复用惰性 PDF 正文及其 tab 阅读状态。keyed slot `sidebar.right.tab.document.action` 将渲染器操作放在刷新按钮前。Office 操作与正文共享 store,仅读取当前 revision 的字体元数据。Host 渲染器缺失时,注册仍然可用;可选的 `remote.officeToPdf` 和 `remote.workspaceFiles` 注入提供转换与版本检查回调,移除后恢复不可用提示。注册和 tab 状态保留都遵循 effect 生命周期。[转换服务](../../document/office-to-pdf/README.zh.md)拥有 Host Remote 方法,由 `api/remotes` 挂载。 -共享 `documentFileBytes()` 辅助函数将普通文件与转换后 PDF 的响应解码到一个独立持有的字节缓冲区,不会将字节展开为 JavaScript 数组元素。渲染器以只读方式借用保留的字节,并在传给 Worker 前复制。 +`documentFileBytes()` 辅助函数将 Office 转换后的 PDF 响应解码到一个独立持有的字节缓冲区,不会将字节展开为 JavaScript 数组元素。渲染器以只读方式借用保留的字节,并在传给 Worker 前复制。 diff --git a/packages/client/ui-sidebar-documentpreview/src/client/face.ts b/packages/client/ui-sidebar-documentpreview/src/client/face.ts index 17dda43da3..914c754278 100644 --- a/packages/client/ui-sidebar-documentpreview/src/client/face.ts +++ b/packages/client/ui-sidebar-documentpreview/src/client/face.ts @@ -101,7 +101,7 @@ interface TabReads { /** * Bind the preview's face to one paged read and one complete-byte read. * @param read - the bound `workspaceFiles.read` call. - * @param readAll - ordinary complete-byte Remote read. + * @param readAll - complete-byte workspace Remote read. * @param resources - shared metadata sources for the document and its dependencies. * @returns the Slot `inject` factory: bound actions in, face out. The slot's session id is unused because the address carries its own. */ diff --git a/packages/client/ui-sidebar-documentpreview/src/client/html/index.ts b/packages/client/ui-sidebar-documentpreview/src/client/html/index.ts index 50672fc97b..88ebcfda78 100644 --- a/packages/client/ui-sidebar-documentpreview/src/client/html/index.ts +++ b/packages/client/ui-sidebar-documentpreview/src/client/html/index.ts @@ -35,7 +35,7 @@ export function apply(ctx: Context): void { hooks: { interactivePreview: ctx.settingsScope.developerTools.enabled }, readRelated: (address, relativePath, signal) => { const file = hostFileOf(address) - return ctx.remote.workspaceFiles.readRelated(file.sessionId, file.path, relativePath, signal) + return ctx.remote.workspaceFiles.readBytes(file.sessionId, relativePath, { baseFile: file.path }, signal) }, }), }, HtmlBody, diff --git a/packages/client/ui-sidebar-documentpreview/src/client/html/read-relative.ts b/packages/client/ui-sidebar-documentpreview/src/client/html/read-relative.ts index 5bbf23c94e..8421a1ab29 100644 --- a/packages/client/ui-sidebar-documentpreview/src/client/html/read-relative.ts +++ b/packages/client/ui-sidebar-documentpreview/src/client/html/read-relative.ts @@ -1,7 +1,6 @@ -/** Adapt a Remote relative read without changing its Session or Host path authority. */ +/** Adapt a relative workspace read without changing its Session or Host path authority. */ import type { RemoteResult } from '@deepseek-ai/dsh-api-remotes/client' -import type { WorkspaceFileBytes } from '@deepseek-ai/dsh-api-workspace-files/types' -import { documentFileBytes } from '../rpc.ts' +import type { DocumentFileBytes } from '../rpc.ts' import type { ReadHtmlRelative } from './pack.ts' import { sessionFileAddress } from '@deepseek-ai/dsh-util-workspace-path' import { hostFileOf } from '../rpc.ts' @@ -11,13 +10,13 @@ import { hostFileOf } from '../rpc.ts' * @param address - root HTML file address. * @param relativePath - decoded dependency path, resolved only by the Host. * @param signal - cancellation shared by the tab and packing operation. - * @returns the Remote complete-byte result, including declared failures. + * @returns the complete-byte result, including declared failures. */ -export type ReadHtmlRelated = (address: string, relativePath: string, signal: AbortSignal) => Promise> +export type ReadHtmlRelated = (address: string, relativePath: string, signal: AbortSignal) => Promise> /** * Bind a package reader to the original HTML file's address. - * @param readRelated - Remote reader using the Session in the root HTML address. + * @param readRelated - workspace reader using the Session in the root HTML address. * @param address - root HTML file address. * @param lifetime - tab lifetime. * @param addResource - subscribes to the dependency path reported by the Host. @@ -47,6 +46,6 @@ export function createReadHtmlRelative( throw new Error(result.error.message) } addResource(sessionFileAddress(file.sessionId, result.value.absolutePath)) - return documentFileBytes(result.value) + return result.value } } diff --git a/packages/client/ui-sidebar-documentpreview/src/client/index.ts b/packages/client/ui-sidebar-documentpreview/src/client/index.ts index c5edbc05a5..7c8b6907b2 100644 --- a/packages/client/ui-sidebar-documentpreview/src/client/index.ts +++ b/packages/client/ui-sidebar-documentpreview/src/client/index.ts @@ -25,7 +25,7 @@ import type { TextPreviewInjected } from './TextPreview.tsx' import { TextTitle } from './TextTitle.tsx' import { TEXTPREVIEW_ID, textDefinition } from './definition.ts' import { textFace } from './face.ts' -import { createReadPage, documentFileBytes } from './rpc.ts' +import { createReadPage } from './rpc.ts' import { createTextStore } from './store.ts' import { en, zh } from './locales.ts' import { DocumentPreviewRegistry } from './document/registry.ts' @@ -76,13 +76,13 @@ declare module '@deepseek-ai/dsh-client-ui-slots' { /** * Required browser services: the tab registry, the slot registry, copy, and the - * Remote carrier with its `workspaceFiles` namespace. + * workspace Remote for bytes and paged text reads. */ export const inject = ['slots', 'locale', 'sidebarRightTabs', 'remote', 'remote.workspaceFiles', 'settingsScope', 'resources'] /** * Client plugin body: register the type, its dictionaries, its body, and its chip title. - * @param ctx - client root context carrying the registry, the slots, copy, and the Remote face. + * @param ctx - client root context carrying the registry, slots, copy, and file readers. */ export function apply(ctx: ClientContext): void { const config = Config((globalThis as { __DSH_DOCUMENT_PREVIEW_CONFIG__?: unknown }).__DSH_DOCUMENT_PREVIEW_CONFIG__ ?? {}) @@ -95,10 +95,7 @@ export function apply(ctx: ClientContext): void { const store = createTextStore() const face = textFace( createReadPage(ctx.remote), - async (file, signal) => { - const result = await ctx.remote.workspaceFiles.readAll(file.sessionId, file.path, signal) - return result.ok ? { ok: true, value: documentFileBytes(result.value) } : result - }, + (file, signal) => ctx.remote.workspaceFiles.readBytes(file.sessionId, file.path, {}, signal), ctx.resources, ) const source = { getSnapshot: previews.getSnapshot, subscribe: previews.subscribe } diff --git a/packages/client/ui-sidebar-documentpreview/src/client/office/index.ts b/packages/client/ui-sidebar-documentpreview/src/client/office/index.ts index 0672b5f1ed..098e5dd06c 100644 --- a/packages/client/ui-sidebar-documentpreview/src/client/office/index.ts +++ b/packages/client/ui-sidebar-documentpreview/src/client/office/index.ts @@ -5,7 +5,6 @@ import type {} from '@deepseek-ai/dsh-client-ui-renderer/client' import type {} from '@deepseek-ai/dsh-office-to-pdf/remote' import type {} from '@deepseek-ai/dsh-client-locale/client' import type {} from '@deepseek-ai/dsh-api-workspace-files/remote' -import type {} from '@deepseek-ai/dsh-client-connection/client' import { documentFileBytes } from '../rpc.ts' import { failureLine } from '../failure-line.ts' import { documentTabInfoFactory } from '../document/contract.ts' @@ -81,7 +80,9 @@ export function apply(ctx: Context, config: Config['office']): void { } const createCache = () => new OfficePreviewCache( async (file, signal) => { - const authorized = await scope.remote.workspaceFiles.readBytes(file.sessionId, file.path, { offset: 0, length: 1 }, signal) + const authorized = await scope.remote.workspaceFiles.readBytes( + file.sessionId, file.path, { range: { offset: 0, length: 1 } }, signal, + ) signal.throwIfAborted() if (!authorized.ok) return authorized const metadata = await scope.remote.workspaceFiles.stat(file.sessionId, file.path, signal) diff --git a/packages/client/ui-sidebar-documentpreview/src/client/rpc.ts b/packages/client/ui-sidebar-documentpreview/src/client/rpc.ts index d609278c4f..8289374cdc 100644 --- a/packages/client/ui-sidebar-documentpreview/src/client/rpc.ts +++ b/packages/client/ui-sidebar-documentpreview/src/client/rpc.ts @@ -81,23 +81,23 @@ export function createReadPage(remote: WorkspaceFilesReadRemote): ReadWorkspaceF return (sessionId, path, offset, signal) => remote.workspaceFiles.read(sessionId, path, { offset }, signal) } -/** Complete document bytes borrowed read-only by renderers; copy before transferring to a Worker. */ -export type DocumentFileBytes = Omit & { readonly data: Uint8Array } +/** Document bytes borrowed read-only by renderers; copy before transferring to a Worker. */ +export type DocumentFileBytes = WorkspaceFileBytes> /** * Read a complete file through the Host endpoint. * @param file - Session and path decoded from the tab address. * @param signal - owning tab lifetime. - * @returns complete binary bytes, including declared failures. + * @returns complete native bytes, including declared failures. */ export type ReadDocumentBytes = (file: SessionFile, signal: AbortSignal) => Promise> /** - * Decode one successful Remote byte result for document renderers. - * @param file - Host byte result with base64 data. + * Decode the Office conversion Remote's base64 PDF response. + * @param file - converted PDF metadata and base64 contents. * @returns the same metadata with native bytes; malformed base64 throws. */ -export function documentFileBytes(file: WorkspaceFileBytes): DocumentFileBytes { +export function documentFileBytes(file: Omit & { readonly data: string }): DocumentFileBytes { const binary = atob(file.data) const data = new Uint8Array(binary.length) for (let index = 0; index < binary.length; index++) data[index] = binary.charCodeAt(index) diff --git a/packages/client/ui-sidebar-documentpreview/tests/apply.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/apply.client.spec.ts index 976da58bbc..5e82256d60 100644 --- a/packages/client/ui-sidebar-documentpreview/tests/apply.client.spec.ts +++ b/packages/client/ui-sidebar-documentpreview/tests/apply.client.spec.ts @@ -7,6 +7,8 @@ * and face — and that every registration is gone after dispose, which is what * makes a reload safe. */ +import type { ClientRemote } from '@deepseek-ai/dsh-api-remotes/client' +import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime' import { createSnapshotStore } from '@deepseek-ai/dsh-client-store' import { describe, expect, it, onTestFinished, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' @@ -29,10 +31,9 @@ import { LazyPdfBody } from '../src/client/pdf/LazyPdfBody.tsx' import { PDF_BODY_ID } from '../src/client/pdf/index.ts' import { CodeBody } from '../src/client/code/CodeBody.tsx' import { en, zh } from '../src/client/locales.ts' -import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime' import type { textFace } from '../src/client/face.ts' import type { TextStore } from '../src/client/store.ts' -import { FILE, SESSION, TAB_ID, createResources, page } from './fixtures.client.ts' +import { FILE, SESSION, TAB_ID, byteResult, createResources, page } from './fixtures.client.ts' interface Recorded { name: string @@ -65,21 +66,17 @@ async function boot() { return () => { dictionaries.delete(ns) } }), } - const workspaceFiles = { - read: vi.fn().mockResolvedValue(page(1, ['first'], true)), - readAll: vi.fn().mockResolvedValue({ - ok: true, value: { absolutePath: '/workspace/notes.md', version: 'v1', offset: 0, data: 'AAH/', eof: true }, - }), - } + const read = vi.fn().mockResolvedValue(page(1, ['first'], true)) + const readBytes = vi.fn(async () => byteResult()) ctx.provide('sidebarRightTabs', tabs as never) ctx.provide('slots', slots as never) ctx.provide('locale', locale as never) - ctx.provide('remote', { workspaceFiles } as never) - ctx.provide('remote.workspaceFiles', workspaceFiles as never) + ctx.provide('remote', { workspaceFiles: { read, readBytes } } as never) + ctx.provide('remote.workspaceFiles', { read, readBytes } as never) const fiber = ctx.plugin({ inject: [...inject], apply }) onTestFinished(async () => { await fiber.dispose() }) await fiber.await() - return { tabs, registered, dictionaries, fiber, workspaceFiles } + return { tabs, registered, dictionaries, fiber, read, readBytes } } describe('ui-sidebar-documentpreview apply', () => { @@ -115,8 +112,8 @@ describe('ui-sidebar-documentpreview apply', () => { expect(dictionaries.size).toBe(0) }) - it('injects ordinary Remote reads independently of resource metadata', async () => { - const { registered, workspaceFiles } = await boot() + it('injects paged and byte Remote reads independently of resource metadata', async () => { + const { registered, read, readBytes } = await boot() const registration = registered.find(entry => entry.component === TextPreview) if (registration === undefined) throw new Error('missing preview registration') const instance = (registration.store as TextStore).create() @@ -124,17 +121,16 @@ describe('ui-sidebar-documentpreview apply', () => { const controller = new AbortController() onTestFinished(() => { controller.abort() }) face.loadPage(TAB_ID, FILE, 1, controller.signal, 'v1') - await workspaceFiles.read.mock.results[0]?.value - expect(workspaceFiles.read).toHaveBeenCalledExactlyOnceWith(FILE.sessionId, FILE.path, { offset: 1 }, controller.signal) + await read.mock.results[0]?.value + expect(read).toHaveBeenCalledExactlyOnceWith(FILE.sessionId, FILE.path, { offset: 1 }, controller.signal) expect(instance.getSnapshot().byTab[TAB_ID]?.pages[1]?.text).toBe('first') face.loadAll(TAB_ID, FILE, controller.signal, 'v1') - await workspaceFiles.readAll.mock.results[0]?.value - expect(workspaceFiles.readAll).toHaveBeenCalledExactlyOnceWith(FILE.sessionId, FILE.path, expect.any(AbortSignal)) - await expect.poll(() => instance.getSnapshot().byTab[TAB_ID]?.complete?.data).toEqual(new Uint8Array([0, 1, 255])) - const failure = new RemoteError('workspace-file/not-found', 'File missing', { path: FILE.path }) - workspaceFiles.readAll.mockResolvedValueOnce({ ok: false, error: failure }) + await vi.waitFor(() => { expect(instance.getSnapshot().byTab[TAB_ID]?.complete).toBeDefined() }) + expect(readBytes).toHaveBeenCalledExactlyOnceWith(FILE.sessionId, FILE.path, {}, expect.any(AbortSignal)) + expect(instance.getSnapshot().byTab[TAB_ID]?.complete?.data).toEqual(new Uint8Array([0, 1, 255])) + readBytes.mockResolvedValueOnce({ ok: false, error: new RemoteError('workspace-file/not-found', 'File missing', { path: FILE.path }) }) face.reloadAll(TAB_ID, FILE, controller.signal, 'v2') - await expect.poll(() => instance.getSnapshot().byTab[TAB_ID]?.failure).toBe(failure) + await expect.poll(() => instance.getSnapshot().byTab[TAB_ID]?.failure).toMatchObject({ code: 'workspace-file/not-found', message: 'File missing' }) expect(instance.getSnapshot().byTab[TAB_ID]?.complete).toBeUndefined() }) }) diff --git a/packages/client/ui-sidebar-documentpreview/tests/document-seat.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/document-seat.client.spec.tsx index f938754af5..f3eeace3c8 100644 --- a/packages/client/ui-sidebar-documentpreview/tests/document-seat.client.spec.tsx +++ b/packages/client/ui-sidebar-documentpreview/tests/document-seat.client.spec.tsx @@ -1,18 +1,19 @@ // @vitest-environment jsdom /** Document extension registration and dispatch through the production Sidebar and Slot renderer. */ +import { byteResult } from './fixtures.client.ts' import { createSnapshotStore } from '@deepseek-ai/dsh-client-store' import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' import { act, fireEvent, screen, waitFor } from '@testing-library/react' import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime' import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client' import type { SessionId } from '@deepseek-ai/dsh-session/types' -import type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client' import { absoluteFileAddress, sessionFileAddress } from '@deepseek-ai/dsh-util-workspace-path' import { apply as resourcesApply, inject as resourcesInject } from '@deepseek-ai/dsh-client-resources/src/client/index.ts' import { apply as sidebarApply, inject as sidebarInject } from '@deepseek-ai/dsh-client-ui-sidebar-right/src/client/index.ts' import { apply, inject } from '../src/client/index.ts' import type { DocumentPreviewProps } from '../src/client/document/contract.ts' import type { DocumentLoadMode } from '../src/client/document/registry.ts' +import type { WorkspaceFilesReadRemote } from '../src/client/rpc.ts' import { PLAIN_BODY_ID } from '../src/client/text/index.ts' const SESSION = 'documents' as SessionId @@ -49,15 +50,12 @@ async function boot() { await rt.sessions.add({ id: SESSION }) await rt.sessions.retainFor(rt.ctx, SESSION, { source: 'mainView' }).ready await rt.mount({ inject: [...resourcesInject], apply: resourcesApply }) - const read = vi.fn().mockImplementation(async (_sessionId, _path, range) => ({ + const read = vi.fn().mockImplementation(async (_sessionId, _path, range) => ({ ok: true, value: { absolutePath: '/host/notes', version: 'v1', bytes: 18, offset: range.offset ?? 1, text: range.offset === 3 ? 'third' : 'first\nsecond', lines: range.offset === 3 ? 1 : 2, eof: range.offset === 3 }, })) - const bytes = vi.fn().mockResolvedValue({ - ok: true, value: { absolutePath: '/host/notes', version: 'v1', offset: 0, data: btoa('all'), bytes: 3, eof: true }, - }) - const workspaceFiles = { read, readAll: bytes } - rt.remote.provideNamespaces({ workspaceFiles }) + const bytes = vi.fn(async () => byteResult(new TextEncoder().encode('all'))) + rt.remote.provideNamespaces({ workspaceFiles: { read, readBytes: bytes } }) rt.ctx.effect(() => rt.ctx.resources.register({ protocol: 'file', open: async function* (_address, { signal }) { diff --git a/packages/client/ui-sidebar-documentpreview/tests/face.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/face.client.spec.ts index 2a8a85e183..0eead1b061 100644 --- a/packages/client/ui-sidebar-documentpreview/tests/face.client.spec.ts +++ b/packages/client/ui-sidebar-documentpreview/tests/face.client.spec.ts @@ -237,6 +237,7 @@ describe('textFace', () => { expect(tab()?.complete).toBeUndefined() await settleAll(result) expect(tab()).toMatchObject({ mode: 'bytes-complete', loading: false, complete: result.value, version: 'v1', eof: true, pages: {} }) + expect(tab()?.complete?.data).toBe(result.value.data) }) it('records a complete-read failure and clears it when the read is retried', async () => { diff --git a/packages/client/ui-sidebar-documentpreview/tests/fixtures.client.ts b/packages/client/ui-sidebar-documentpreview/tests/fixtures.client.ts index d34bd4bc5a..d71d1167b1 100644 --- a/packages/client/ui-sidebar-documentpreview/tests/fixtures.client.ts +++ b/packages/client/ui-sidebar-documentpreview/tests/fixtures.client.ts @@ -21,7 +21,7 @@ import type { WorkspaceFileStat, WorkspaceFileText } from '@deepseek-ai/dsh-api- import type { TextPreviewProps } from '../src/client/TextPreview.tsx' import { textFace } from '../src/client/face.ts' import type { TextInjected } from '../src/client/face.ts' -import type { ReadDocumentBytes, ReadWorkspaceFilePage, SessionFile } from '../src/client/rpc.ts' +import type { DocumentFileBytes, ReadDocumentBytes, ReadWorkspaceFilePage, SessionFile } from '../src/client/rpc.ts' import { createTextStore } from '../src/client/store.ts' import type { TextStore } from '../src/client/store.ts' import type { DocumentPreviewProps } from '../src/client/document/contract.ts' @@ -189,3 +189,8 @@ export function harness(script: Record> setFailure(failure) { current.failure = failure; refresh() }, } } + +/** Native byte result returned by the generated workspace Remote. */ +export function byteResult(data = new Uint8Array([0, 1, 255])): RemoteResult { + return { ok: true, value: { absolutePath: '/host/notes', version: 'v1', offset: 0, eof: true, bytes: data.byteLength, data } } +} diff --git a/packages/client/ui-sidebar-documentpreview/tests/html-apply.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/html-apply.client.spec.ts index bcf14b5c6a..e2f7a2eff6 100644 --- a/packages/client/ui-sidebar-documentpreview/tests/html-apply.client.spec.ts +++ b/packages/client/ui-sidebar-documentpreview/tests/html-apply.client.spec.ts @@ -1,3 +1,4 @@ +import { byteResult } from './fixtures.client.ts' /** HTML metadata and keyed slot contributions share one identity and unwind with their fiber. */ import { createSnapshotStore } from '@deepseek-ai/dsh-client-store' import { afterEach, describe, expect, it, vi } from 'vitest' @@ -36,8 +37,8 @@ describe('HTML registration', () => { const registry = new DocumentPreviewRegistry() const dictionaries = new Map() const bodies = new Map() - const readRelated = vi.fn().mockResolvedValue({ ok: true, value: { data: '' } }) - ctx.provide('remote', { workspaceFiles: { readRelated } } as never) + const readRelated = vi.fn(async () => byteResult()) + ctx.provide('remote', { workspaceFiles: { readBytes: readRelated } } as never) const register = vi.fn((options: Registration, body: unknown) => { bodies.set(options.key, body) return () => { bodies.delete(options.key) } @@ -62,9 +63,9 @@ describe('HTML registration', () => { expect(typeof injected?.readRelated).toBe('function') const signal = new AbortController().signal await injected?.readRelated('dsh-resource://file/session/explicit-session/sub/index.html', '../app.js', signal) - expect(readRelated).toHaveBeenLastCalledWith('explicit-session', 'sub/index.html', '../app.js', signal) + expect(readRelated).toHaveBeenLastCalledWith('explicit-session', '../app.js', { baseFile: 'sub/index.html' }, signal) await injected?.readRelated(sessionFileAddress('absolute-session', '/workspace/index.html'), './app.js', signal) - expect(readRelated).toHaveBeenLastCalledWith('absolute-session', '/workspace/index.html', './app.js', signal) + expect(readRelated).toHaveBeenLastCalledWith('absolute-session', './app.js', { baseFile: '/workspace/index.html' }, signal) expect(() => injected?.readRelated('dsh-resource://file/absolute/workspace/index.html', './app.js', signal)) .toThrow('not a session file address') expect(readRelated).toHaveBeenCalledTimes(2) diff --git a/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx index b136e6791b..fdbd5452cb 100644 --- a/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx +++ b/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx @@ -90,7 +90,7 @@ describe('HtmlBody', () => { h.bytes.mockResolvedValue({ ok: true, value: { absolutePath: ABSOLUTE_PATH, version: 'root-v1', data, offset: 0, eof: true } }) const readRelated = vi.fn().mockResolvedValue({ ok: true, value: { absolutePath: `/workspace/asset.${extension}`, version: 'asset-v1', offset: 0, eof: true, - data: btoa(extension === 'css' ? 'body { color: red }' : 'window.loaded = true'), + data: utf8(extension === 'css' ? 'body { color: red }' : 'window.loaded = true'), } }) const definition = { ...htmlBodyDefinition(() => 'HTML'), extensions: ['md'] } let interactive = true @@ -111,7 +111,7 @@ describe('HtmlBody', () => { expect(create).toHaveBeenCalledOnce() readRelated.mockResolvedValueOnce({ ok: true, value: { absolutePath: `/workspace/asset.${extension}`, version: 'asset-v2', offset: 0, eof: true, - data: btoa(extension === 'css' ? 'body { color: blue }' : 'window.loaded = false'), + data: utf8(extension === 'css' ? 'body { color: blue }' : 'window.loaded = false'), } }) act(() => { dependency.set(metadata('asset-v2')) }) await waitFor(() => { expect(screen.getByTitle(en.frame)).not.toBe(previous) }) @@ -252,7 +252,7 @@ describe('HtmlBody', () => { const signal = new AbortController().signal const bytes = vi.fn().mockResolvedValue({ ok: true, - value: { absolutePath: '/workspace/app.js', data: btoa('window.ready=true'), version: 'v1', offset: 0, eof: true }, + value: { absolutePath: '/workspace/app.js', data: utf8('window.ready=true'), version: 'v1', offset: 0, eof: true }, }) const useResource = vi.fn().mockReturnValue({ value: undefined }) const initial = { @@ -275,7 +275,7 @@ describe('HtmlBody', () => { const signal = new AbortController().signal const bytes = vi.fn().mockResolvedValue({ ok: true, - value: { absolutePath: '/workspace/app.js', version: 'v1', bytes: 16, offset: 0, data: btoa('window.ready=1'), eof: true }, + value: { absolutePath: '/workspace/app.js', version: 'v1', bytes: 16, offset: 0, data: utf8('window.ready=1'), eof: true }, }) const useResource = vi.fn(() => ({ value: { version: 'v1' } })) const initial = { diff --git a/packages/client/ui-sidebar-documentpreview/tests/html-read-relative.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/html-read-relative.client.spec.ts index d043a1a579..3c6e65e2ec 100644 --- a/packages/client/ui-sidebar-documentpreview/tests/html-read-relative.client.spec.ts +++ b/packages/client/ui-sidebar-documentpreview/tests/html-read-relative.client.spec.ts @@ -1,4 +1,4 @@ -/** HTML URL decoding stays local; ordinary Remote reads leave path resolution and authorization to the Host. */ +/** HTML URL decoding stays local; workspace reads leave path resolution and authorization to the Host. */ import { describe, expect, it, vi } from 'vitest' import { RemoteError } from '@deepseek-ai/dsh-client-test-runtime' import { sessionFileAddress } from '@deepseek-ai/dsh-util-workspace-path' @@ -8,14 +8,14 @@ import type { ReadHtmlRelated } from '../src/client/html/read-relative.ts' const ADDRESS = 'dsh-resource://file/session/html/sub/index.html' describe('HTML relative file reader', () => { - it('decodes a relative URL once and converts the Remote result to native bytes', async () => { - const value = { absolutePath: '/workspace/a b.js', data: btoa('x'), version: 'v1', offset: 0, bytes: 1, eof: true } + it('decodes a relative URL once and preserves the returned bytes', async () => { + const value = { absolutePath: '/workspace/a b.js', data: new Uint8Array([120]), version: 'v1', offset: 0, bytes: 1, eof: true } const readRelated = vi.fn().mockResolvedValue({ ok: true, value }) const tab = new AbortController() const loading = new AbortController() const addResource = vi.fn() const read = createReadHtmlRelative(readRelated, ADDRESS, tab.signal, addResource) - await expect(read('../a%20b.js?v=1#fragment', loading.signal)).resolves.toEqual({ ...value, data: new Uint8Array([120]) }) + await expect(read('../a%20b.js?v=1#fragment', loading.signal)).resolves.toBe(value) const signal = readRelated.mock.calls[0]?.[2] expect(readRelated).toHaveBeenCalledExactlyOnceWith(ADDRESS, '../a b.js', signal) expect(addResource).toHaveBeenCalledExactlyOnceWith(sessionFileAddress('html', value.absolutePath)) @@ -25,7 +25,7 @@ describe('HTML relative file reader', () => { }) it('observes the Host-resolved dependency instead of a symlink and parent-segment spelling', async () => { - const value = { absolutePath: '/workspace/style.css', data: btoa('x'), version: 'v1', offset: 0, eof: true } + const value = { absolutePath: '/workspace/style.css', data: new TextEncoder().encode('x'), version: 'v1', offset: 0, bytes: 1, eof: true } const readRelated = vi.fn().mockResolvedValue({ ok: true, value }) const addResource = vi.fn() const signal = new AbortController().signal @@ -85,7 +85,7 @@ describe('HTML relative file reader', () => { const result = read('./late.js', loading.signal) const rejected = expect(result).rejects.toMatchObject({ name: 'AbortError' }) loading.abort() - pending.resolve({ ok: true, value: { absolutePath: '/workspace/late.js', version: 'v1', bytes: 1, offset: 0, data: 'AQ==', eof: true } }) + pending.resolve({ ok: true, value: { absolutePath: '/workspace/late.js', version: 'v1', bytes: 1, offset: 0, data: new Uint8Array([1]), eof: true } }) await rejected }) }) diff --git a/packages/client/ui-sidebar-documentpreview/tests/office-registration.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/office-registration.client.spec.ts index 98a980f49d..ffa492509f 100644 --- a/packages/client/ui-sidebar-documentpreview/tests/office-registration.client.spec.ts +++ b/packages/client/ui-sidebar-documentpreview/tests/office-registration.client.spec.ts @@ -55,7 +55,7 @@ async function harness(config: Partial = {}, missing?: 'remote const render = vi.fn().mockResolvedValue(converted) const rendererGeneration = vi.fn().mockResolvedValue({ ok: true, value: generation }) const stat = vi.fn().mockResolvedValue({ ok: true, value: source }) - const readBytes = vi.fn().mockResolvedValue({ ok: true, value: source }) + const readBytes = vi.fn().mockResolvedValue({ ok: true, value: { ...source, data: pdf.subarray(0, 1), eof: false } }) const removeNotice = vi.fn() const recorded: { options: { name: string; store: OfficeStore; inject: (id: SessionId, actions: ReturnType['actions']) => OfficeBodyInjected }; component: unknown }[] = [] const register = vi.fn((options: typeof recorded[number]['options'], component: unknown) => { recorded.push({ options, component }); return removeNotice }) @@ -112,7 +112,7 @@ it('requests a Host PDF with source identity and borrows the same binary cache r expect(await h.read()).toBe(result) expect(h.stat).toHaveBeenCalledTimes(2) expect(h.readBytes).toHaveBeenCalledTimes(2) - expect(h.readBytes).toHaveBeenCalledWith(file.sessionId, file.path, { offset: 0, length: 1 }, expect.any(AbortSignal)) + expect(h.readBytes).toHaveBeenCalledWith(file.sessionId, file.path, { range: { offset: 0, length: 1 } }, expect.any(AbortSignal)) expect(h.render).toHaveBeenCalledOnce() } finally { await h.close() } }) @@ -147,8 +147,8 @@ it('refuses Client cached bytes when metadata still succeeds but the read probe try { await h.read() const failure = new Error('read denied') - h.readBytes.mockRejectedValueOnce(failure) - await expect(h.read()).rejects.toBe(failure) + h.readBytes.mockResolvedValueOnce({ ok: false, error: new RemoteError('gateway/internal', failure.message, {}) }) + expect(await h.read()).toMatchObject({ ok: false, error: { code: 'gateway/internal', message: failure.message } }) expect(h.render).toHaveBeenCalledOnce() expect(h.stat).toHaveBeenCalledOnce() } finally { await h.close() } @@ -160,7 +160,7 @@ it('returns a declared authorization failure without consulting metadata or cach await h.read() const denied = { ok: false as const, error: new RemoteError('workspace-file/not-found', 'File missing', { path: file.path }) } h.readBytes.mockResolvedValueOnce(denied) - expect(await h.read()).toBe(denied) + expect(await h.read()).toMatchObject(denied) expect(h.stat).toHaveBeenCalledOnce() expect(h.render).toHaveBeenCalledOnce() } finally { await h.close() } diff --git a/packages/client/ui-sidebar-documentpreview/tests/rpc.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/rpc.client.spec.ts index 0657e1aaf4..a7a6a74f5e 100644 --- a/packages/client/ui-sidebar-documentpreview/tests/rpc.client.spec.ts +++ b/packages/client/ui-sidebar-documentpreview/tests/rpc.client.spec.ts @@ -6,7 +6,7 @@ */ import { describe, expect, it, vi } from 'vitest' import { sessionFileAddress } from '@deepseek-ai/dsh-util-workspace-path' -import { createReadPage, documentFileBytes, hostFileOf } from '../src/client/rpc.ts' +import { createReadPage, hostFileOf } from '../src/client/rpc.ts' import type { ReadWorkspaceFilePage, WorkspaceFilesReadRemote } from '../src/client/index.ts' import { ADDRESS, FILE, PATH, SESSION, page } from './fixtures.client.ts' @@ -39,17 +39,3 @@ describe('createReadPage', () => { expect(read).toHaveBeenCalledWith(SESSION, PATH, { offset: 4 }, signal) }) }) - -describe('documentFileBytes', () => { - it.each(['', 'AAH/'])('decodes complete Remote bytes without changing metadata (%j)', (data) => { - const file = { absolutePath: '/workspace/a.bin', version: 'v1', bytes: 3, offset: 0, data, eof: true } - const result = documentFileBytes(file) - expect(result).toEqual({ ...file, data: data === '' ? new Uint8Array() : new Uint8Array([0, 1, 255]) }) - expect(result.data.buffer).toBeInstanceOf(ArrayBuffer) - expect(file.data).toBe(data) - }) - - it('rejects malformed wire base64', () => { - expect(() => documentFileBytes({ absolutePath: '/workspace/a.bin', version: 'v1', offset: 0, data: '!!!', eof: true })).toThrow() - }) -}) diff --git a/packages/document/office-to-pdf/src/index.ts b/packages/document/office-to-pdf/src/index.ts index fbcff20e1a..f8d3b993c9 100644 --- a/packages/document/office-to-pdf/src/index.ts +++ b/packages/document/office-to-pdf/src/index.ts @@ -187,7 +187,7 @@ export class OfficeToPdf extends TypertRemoteService { const files = this.ctx.get('workspaceFiles') const fs = this.ctx.get('fs') if (files === undefined || fs === undefined) throw new OfficeToPdfError('unavailable', 'Office file rendering requires workspaceFiles and fs.') - const authorized = await files.readBytes(scope, path, { offset: 0, length: 1 }, signal) + const authorized = await files.readBytes(scope, path, { range: { offset: 0, length: 1 } }, signal) const source = await files.stat(scope, path, signal) const assertUnchanged = (current: WorkspaceFileStat): void => { if (current.absolutePath !== source.absolutePath || current.version !== source.version) { diff --git a/packages/document/office-to-pdf/src/types.ts b/packages/document/office-to-pdf/src/types.ts index a1123a5ba1..5138dad52c 100644 --- a/packages/document/office-to-pdf/src/types.ts +++ b/packages/document/office-to-pdf/src/types.ts @@ -45,7 +45,9 @@ export type OfficeToPdfErrorCode = | 'invalid-output' | 'timeout' | 'unavailable' | 'failed' | 'busy' | 'source-changed' /** PDF content carries the original Office file's absolute path and version. */ -export interface RenderedDocumentBytes extends WorkspaceFileBytes { +export interface RenderedDocumentBytes extends Omit { + /** Base64 PDF contents carried by the JSON Remote response. */ + readonly data: string readonly missingFonts: string[] readonly generation: OfficeToPdfGeneration } diff --git a/packages/document/office-to-pdf/tests/remote.spec.ts b/packages/document/office-to-pdf/tests/remote.spec.ts index 542dc1a333..4029f3ea74 100644 --- a/packages/document/office-to-pdf/tests/remote.spec.ts +++ b/packages/document/office-to-pdf/tests/remote.spec.ts @@ -31,7 +31,7 @@ beforeEach(async () => { fileInfo = vi.fn().mockResolvedValue(sourceInfo) processPath = vi.fn().mockReturnValue(source.absolutePath) ctx.provide('fs', { resolve: vi.fn().mockResolvedValue(target), stat: fileInfo, processPath, readBytes: read } as never) - authorize = vi.fn().mockResolvedValue(wireSource) + authorize = vi.fn().mockResolvedValue({ ...wireSource, eof: false, data: rawSource.data.subarray(0, 1) }) metadata = vi.fn().mockResolvedValue(source) await ctx.plugin(OfficeToPdf) generation = ctx.officeToPdf.generation @@ -48,7 +48,7 @@ it.each(['doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx'])('converts authorized %s b const path = `report.${extension.toUpperCase()}` const result = await ctx.officeToPdf.render(scope, path, 'foreground', new AbortController().signal) expect(read).toHaveBeenCalledExactlyOnceWith(target, expect.any(AbortSignal), 4) - expect(authorize).toHaveBeenCalledExactlyOnceWith(scope, path, { offset: 0, length: 1 }, expect.any(AbortSignal)) + expect(authorize).toHaveBeenCalledExactlyOnceWith(scope, path, { range: { offset: 0, length: 1 } }, expect.any(AbortSignal)) expect(render).toHaveBeenCalledOnce() expect(render.mock.calls[0]?.[0]).toMatchObject({ extension, priority: 'foreground', source: { version: source.version, bytes: 4 } }) expect(result).toEqual({ ...wireSource, data: Buffer.from(pdf).toString('base64'), bytes: pdf.length, missingFonts: ['Missing Serif'], generation }) diff --git a/packages/host/webserver/README.i18n.yaml b/packages/host/webserver/README.i18n.yaml index 96a6f4432f..3f353ad6d9 100644 --- a/packages/host/webserver/README.i18n.yaml +++ b/packages/host/webserver/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/host/webserver/README.md -README.md: df1881a3a16b69f61127956127c7806c70793f91 -README.zh.md: 1d07d43ac97c616c9b7450da71ad09cb55fa4267 +README.md: 9dd698404719eecdf9fb4c40720ccc74ab37be9d +README.zh.md: d4701b79e432dfa3e8ba8485f8644758ec3b34d7 diff --git a/packages/host/webserver/README.md b/packages/host/webserver/README.md index df1881a3a1..9dd6984047 100644 --- a/packages/host/webserver/README.md +++ b/packages/host/webserver/README.md @@ -38,7 +38,7 @@ Compose the webserver as the HTTP transport of a browser-facing host, then let t `host` accepts exactly two values: `127.0.0.1` (default posture, loopback only) and `0.0.0.0` (deliberate network exposure — the server carries no TLS, authentication, or origin policy of its own). `port` 0 requests an OS-assigned port; `ctx.webServer.port` reads the listening port afterwards. -Set `compression: 'gzip'` to wrap eligible socket-backed responses without changing route APIs. The client must accept gzip and the media type must be compressible; known response lengths below `compressionThresholdBytes` remain uncompressed, while unknown-length streams are eligible immediately. Existing encodings, `Cache-Control: no-transform`, range responses, SSE, ZIP, and the packaged `.gz` Worker image remain unchanged. The shipped Web bundle uses compression level 1 with a 1024-byte threshold; other compositions default to no compression. +Set `compression: 'gzip'` to wrap eligible socket-backed responses without changing route APIs. The client must accept gzip and the media type must be compressible or `multipart/form-data`; known response lengths below `compressionThresholdBytes` remain uncompressed, while unknown-length streams are eligible immediately. Existing encodings, `Cache-Control: no-transform`, range responses, SSE, ZIP, and the packaged `.gz` Worker image remain unchanged. The shipped Web bundle uses compression level 1 with a 1024-byte threshold; other compositions default to no compression. ### Registering routes diff --git a/packages/host/webserver/README.zh.md b/packages/host/webserver/README.zh.md index 1d07d43ac9..d4701b79e4 100644 --- a/packages/host/webserver/README.zh.md +++ b/packages/host/webserver/README.zh.md @@ -38,7 +38,7 @@ kind: "package-reference" `host` 只接受两个值:`127.0.0.1`(默认姿态,仅回环)与 `0.0.0.0`(有意向网络开放——服务器自身不携带 TLS、认证或来源策略)。`port` 为 0 时请求 OS 分配端口;之后用 `ctx.webServer.port` 读取正在监听的端口。 -设置 `compression: 'gzip'` 可以包装符合条件的 socket-backed 响应,而不改变 route API。客户端必须接受 gzip,且媒体类型必须可压缩;已知长度小于 `compressionThresholdBytes` 的响应保持未压缩,未知长度的流则立即符合条件。已有编码、`Cache-Control: no-transform`、range 响应、SSE(Server-Sent Events)、ZIP 与已打包的 `.gz` Worker image 均保持不变。随附 Web bundle 使用 level 1 与 1024 字节阈值;其他组合默认不压缩。 +设置 `compression: 'gzip'` 可以包装符合条件的 socket-backed 响应,而不改变 route API。客户端必须接受 gzip,且媒体类型必须可压缩或为 `multipart/form-data`;已知长度小于 `compressionThresholdBytes` 的响应保持未压缩,未知长度的流则立即符合条件。已有编码、`Cache-Control: no-transform`、range 响应、SSE(Server-Sent Events)、ZIP 与已打包的 `.gz` Worker image 均保持不变。随附 Web bundle 使用 level 1 与 1024 字节阈值;其他组合默认不压缩。 ### 注册路由 diff --git a/packages/host/webserver/src/index.ts b/packages/host/webserver/src/index.ts index 7443d04211..5b490fc770 100644 --- a/packages/host/webserver/src/index.ts +++ b/packages/host/webserver/src/index.ts @@ -95,6 +95,7 @@ function createGzipMiddleware(config: ResolvedConfig): NodeMiddleware { if (response.getHeader('content-range') !== undefined) return false const contentType = response.getHeader('content-type') if (typeof contentType === 'string' && contentType.toLowerCase().startsWith('text/event-stream')) return false + if (typeof contentType === 'string' && /^multipart\/form-data(?:;|$)/i.test(contentType)) return true return compressionMiddleware.filter(request, response) }, }) as NodeMiddleware diff --git a/packages/typert/generator/README.i18n.yaml b/packages/typert/generator/README.i18n.yaml index c5841ecac6..7b0c085cd5 100644 --- a/packages/typert/generator/README.i18n.yaml +++ b/packages/typert/generator/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/typert/generator/README.md -README.md: aa7fd3d6e068ea6532d55de04970ab3e28b74285 -README.zh.md: e911feac821deda1d0876c26c575dcff5cd2a741 +README.md: 9c207574e9bb576a965ab1a91576a3b5a9db397e +README.zh.md: 9a6fa9e81d7950efb4d4b76df6921bc5a83b6adf diff --git a/packages/typert/generator/README.md b/packages/typert/generator/README.md index aa7fd3d6e0..9c207574e9 100644 --- a/packages/typert/generator/README.md +++ b/packages/typert/generator/README.md @@ -85,6 +85,8 @@ Host and Client are independent TypeScript programs. Direct project references e `FaceModelEmitter` emits executable JavaScript containing success-cached Zod schema factories and the `TYPERT` contribution, plus a declaration file whose factories return `z.ZodType` through the package's public export; unsupported Zod projections fail. The Host face with Remote methods additionally emits `typert.remote-client.*` projections of Host Remote contracts for the Client. `WorkspaceTypertGenerator` validates each contributor's `package.json`: `./typert` and `./client/typert` (and `./remote` when Remote methods exist) must point at the exact generated files, and the `files` list must include them. +[Unary binary results](../protocol/README.md) are recognized after generic type resolution. Their codecs validate the byte-array type and JSON metadata without iterating, copying, or freezing the byte payload; generated Client declarations retain the authored metadata and narrow the byte backing to `ArrayBuffer`. + ### Catalog projection The runtime type closure indexes exported workspace declarations and referenced framework enums. Vendored declarations stay outside business API discovery; their enums remain available when a public result refers to them. diff --git a/packages/typert/generator/README.zh.md b/packages/typert/generator/README.zh.md index e911feac82..9a6fa9e81d 100644 --- a/packages/typert/generator/README.zh.md +++ b/packages/typert/generator/README.zh.md @@ -85,6 +85,8 @@ Host 与 Client 是两个独立的 TypeScript 程序。直接项目引用确定 `FaceModelEmitter` 输出包含只缓存成功结果的 Zod schema factory 与 `TYPERT` 贡献的可执行 JavaScript,以及把 factory 通过包的公开导出标注为返回 `z.ZodType` 的声明文件;不支持的 Zod 投影会失败。含 Remote 方法的 Host face 还会额外为 Client 生成 Host Remote 约定的 `typert.remote-client.*` 投影。`WorkspaceTypertGenerator` 校验每个贡献方的 `package.json`:`./typert` 与 `./client/typert`(存在 Remote 方法时还有 `./remote`)必须指向精确的生成文件,且 `files` 清单必须包含它们。 +[一元二进制结果](../protocol/README.zh.md)在泛型类型解析后被识别。其 codec 校验字节数组类型与 JSON 元数据,不遍历、复制或冻结字节载荷;生成的 Client 声明保留原有元数据类型,并将字节的底层缓冲区收窄为 `ArrayBuffer`。 + ### 目录投影 运行时类型闭包索引导出的 workspace 声明和被引用的框架 enum。Vendor 声明不参与业务 API 发现;公共结果引用其中 enum 时,目录仍提供其定义。 diff --git a/packages/typert/generator/src/analyzer.ts b/packages/typert/generator/src/analyzer.ts index 7388d6c6b1..726828f0ed 100644 --- a/packages/typert/generator/src/analyzer.ts +++ b/packages/typert/generator/src/analyzer.ts @@ -1226,6 +1226,8 @@ class FaceAnalyzer { `${registration.name}#${binding.namespace}/${exportedMethod}:result`, false, 'undefined-or-void', + false, + mode === undefined, ), location: this.location(method.name), } @@ -1511,6 +1513,7 @@ class FaceAnalyzer { requireNamed: boolean, topLevelAbsence: 'reject' | 'undefined' | 'undefined-or-void' = 'reject', optional = false, + allowBytes = false, ): RemoteBoundaryModel { const type = this.convertType(authoredType) const declaredType = this.checker.getTypeFromTypeNode(authoredType) @@ -1519,7 +1522,7 @@ class FaceAnalyzer { const resolvedType = optional ? this.checker.getNullableType(declaredType, ts.TypeFlags.Undefined) : declaredType - const codecType = this.resolvedRemoteCodecType(authoredType, resolvedType, topLevelAbsence) + const codecType = this.resolvedRemoteCodecType(authoredType, resolvedType, topLevelAbsence, allowBytes) const acceptsUndefined = topLevelAbsence !== 'reject' && this.includesRemoteAbsence(resolvedType) const rootSymbol = this.namedWorkspaceType(authoredType) const imports = new Map() @@ -1575,6 +1578,7 @@ class FaceAnalyzer { authoredType: ts.TypeNode, resolvedType: ts.Type, topLevelAbsence: 'reject' | 'undefined' | 'undefined-or-void', + allowBytes: boolean, ): TypeNodeId { this.assertRemoteJsonType( resolvedType, @@ -1582,6 +1586,7 @@ class FaceAnalyzer { new Set(), topLevelAbsence !== 'reject', topLevelAbsence === 'undefined-or-void', + allowBytes, ) const completed = new Map() const active = new Map() @@ -1617,6 +1622,9 @@ class FaceAnalyzer { return id } const flags = type.flags + if (this.isRemoteByteArray(type)) { + return add({ kind: 'reference', name: 'Uint8Array', target: { kind: 'standard', name: 'Uint8Array' }, arguments: [] }) + } if ((flags & ts.TypeFlags.Any) !== 0) return add({ kind: 'keyword', name: 'any' }) if ((flags & ts.TypeFlags.Unknown) !== 0) return add({ kind: 'keyword', name: 'unknown' }) if ((flags & ts.TypeFlags.Never) !== 0) return add({ kind: 'keyword', name: 'never' }) @@ -1654,7 +1662,7 @@ class FaceAnalyzer { if ((flags & ts.TypeFlags.TypeParameter) !== 0) { this.fail(authoredType, 'Remote codec contains an unresolved type parameter') } - if ((flags & ts.TypeFlags.Object) === 0) { + if ((flags & (ts.TypeFlags.Object | ts.TypeFlags.Intersection)) === 0) { this.fail( authoredType, `Remote codec type ${this.checker.typeToString(type, authoredType, ts.TypeFormatFlags.NoTruncation)} has no concrete Zod projection`, @@ -1669,7 +1677,9 @@ class FaceAnalyzer { elements: arguments_.map((argument, index) => { const elementFlags = target.elementFlags[index] ?? ts.ElementFlags.Required return { - type: convert(argument), + type: (elementFlags & ts.ElementFlags.Rest) !== 0 + ? this.addNode(authoredType, { kind: 'array', element: convert(argument) }) + : convert(argument), optional: (elementFlags & ts.ElementFlags.Optional) !== 0, rest: (elementFlags & (ts.ElementFlags.Rest | ts.ElementFlags.Variadic)) !== 0, } @@ -1748,6 +1758,7 @@ class FaceAnalyzer { active: Set, allowUndefined: boolean, allowVoid: boolean, + allowBytes = false, ): void { const flags = type.flags if ((flags & ts.TypeFlags.Undefined) !== 0 && allowUndefined) return @@ -1763,22 +1774,26 @@ class FaceAnalyzer { | ts.TypeFlags.BooleanLike | ts.TypeFlags.Null | ts.TypeFlags.Never)) !== 0) return + if (this.isRemoteByteArray(type)) { + if (allowBytes) return + this.fail(site, 'Remote Uint8Array is only supported in unary results') + } if (type.isUnion()) { for (const member of type.types) { - this.assertRemoteJsonType(member, site, active, allowUndefined, allowVoid) + this.assertRemoteJsonType(member, site, active, allowUndefined, allowVoid, allowBytes) } return } if (type.isIntersection()) { const material = type.types.filter(member => !this.isRemotePhantomConstraint(member)) if (material.length === 0) this.fail(site, 'Remote boundary contains a symbol-only object') - for (const member of material) this.assertRemoteJsonType(member, site, active, false, false) + for (const member of material) this.assertRemoteJsonType(member, site, active, false, false, allowBytes) return } if ((flags & ts.TypeFlags.TypeParameter) !== 0) { this.fail(site, 'Remote boundary contains an unresolved type parameter') } - if ((flags & ts.TypeFlags.Object) === 0) { + if ((flags & (ts.TypeFlags.Object | ts.TypeFlags.Intersection)) === 0) { this.fail(site, `Remote boundary contains non-JSON type ${this.checker.typeToString(type)}`) } const symbol = type.getSymbol() @@ -1804,6 +1819,7 @@ class FaceAnalyzer { active, (elementFlags & ts.ElementFlags.Optional) !== 0, false, + allowBytes, ) }) return @@ -1811,7 +1827,7 @@ class FaceAnalyzer { if (this.checker.isArrayType(type) || this.checker.isArrayLikeType(type)) { const element = this.checker.getIndexTypeOfType(type, ts.IndexKind.Number) if (element === undefined) this.fail(site, 'Remote boundary array has no element type') - this.assertRemoteJsonType(element, site, active, false, false) + this.assertRemoteJsonType(element, site, active, false, false, allowBytes) return } const properties = this.checker.getPropertiesOfType(type) @@ -1827,19 +1843,26 @@ class FaceAnalyzer { active, (property.flags & ts.SymbolFlags.Optional) !== 0, false, + allowBytes, ) } for (const info of this.checker.getIndexInfosOfType(type)) { if ((info.keyType.flags & ts.TypeFlags.ESSymbolLike) !== 0) { this.fail(site, 'Remote boundary contains a symbol index signature') } - this.assertRemoteJsonType(info.type, site, active, false, false) + this.assertRemoteJsonType(info.type, site, active, false, false, allowBytes) } } finally { active.delete(type) } } + private isRemoteByteArray(type: ts.Type): boolean { + const symbol = type.getSymbol() + return symbol?.name === 'Uint8Array' + && symbol.declarations?.some(declaration => isStandardLibraryFile(declaration.getSourceFile().fileName)) === true + } + private includesRemoteAbsence(type: ts.Type): boolean { if ((type.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) !== 0) return true return type.isUnion() && type.types.some(member => this.includesRemoteAbsence(member)) diff --git a/packages/typert/generator/src/emitter.ts b/packages/typert/generator/src/emitter.ts index f7c1beaf71..78907abd5f 100644 --- a/packages/typert/generator/src/emitter.ts +++ b/packages/typert/generator/src/emitter.ts @@ -22,6 +22,7 @@ import type { TypeNodeModel, } from './model.ts' import { TypeGraphRenderer } from './renderer.ts' +import { childTypeNodeIds } from './model.ts' /** Failure to project a modeled construct into an emitted artifact. */ export class TypertEmitError extends Error { @@ -331,6 +332,7 @@ export class FaceModelEmitter { lines.push(` result: ${indent(strictCodec( invocation.result, schemas.boundary(resultBoundaryKey(invocation)), + schemas.encoder(resultBoundaryKey(invocation)), ), 2).trimStart()},`) lines.push(` sourceLocation: ${JSON.stringify(invocation.location)},`) lines.push('}') @@ -366,6 +368,12 @@ export class FaceModelEmitter { lines.push(`import type { ${names.join(', ')} } from ${quote(specifier)}`) } lines.push('') + if (packageModel.invocations.some(invocation => containsBytes(this.renderer, invocation.result.codecType))) { + lines.push('type RemoteDecoded = Value extends Uint8Array ? Uint8Array') + lines.push(' : Value extends string | number | boolean | null | undefined ? Value') + lines.push(' : { [Key in keyof Value]: RemoteDecoded }') + lines.push('') + } lines.push('declare module \'@deepseek-ai/dsh-typert-protocol\' {') const direct = packageModel.invocations.filter(invocation => invocation.invocation.kind === 'direct') const scoped = packageModel.invocations.filter(invocation => @@ -478,7 +486,10 @@ export class FaceModelEmitter { !scoped || invocation.invocation.kind === 'context' || parameter.wire !== invocation.scope?.wire).map(parameter => `${safeIdentifier(parameter.wire)}${parameter.optional === true ? '?' : ''}: ${this.renderer.renderType(parameter.boundary.type, referenceNames)}`) if (invocation.cancellation !== undefined) parameters.push('signal?: AbortSignal') - const result = this.renderer.renderType(invocation.result.type, referenceNames) + const authoredResult = this.renderer.renderType(invocation.result.type, referenceNames) + const result = containsBytes(this.renderer, invocation.result.codecType) + ? `RemoteDecoded<${authoredResult}>` + : authoredResult if (invocation.mode === 'stream') { const uplink = invocation.uplink === undefined ? 'never' @@ -519,6 +530,7 @@ interface SchemaArtifact { readonly definitions: readonly string[] readonly exports: readonly SchemaExport[] boundary(key: string): string + encoder(key: string): string | undefined } interface BoundarySchemaRoot { @@ -526,6 +538,118 @@ interface BoundarySchemaRoot { readonly type: TypeNodeId } +class ResultEncoderEmitter { + private readonly names = new Map() + private readonly bodies = new Map() + + constructor(private readonly renderer: TypeGraphRenderer) {} + + reference(id: TypeNodeId): string | undefined { + if (!containsBytes(this.renderer, id)) return undefined + const existing = this.names.get(id) + if (existing !== undefined) return existing + const name = `$encode${this.names.size}` + this.names.set(id, name) + const node = this.renderer.node(id) + const container = node.kind === 'object' || node.kind === 'array' || node.kind === 'tuple' + const body = container || node.kind === 'union' || node.kind === 'intersection' + ? `return $resultContainer(value, path, ancestors, value => {\n${indent(this.body(id), 2)}\n}, ${container})` + : this.body(id) + this.bodies.set(id, `const ${name} = (value, writeBytes, path, ancestors) => {\n${indent(body, 2)}\n}`) + return name + } + + definitions(): string[] { + return this.bodies.size === 0 ? [] : [RESULT_SNAPSHOT, ...this.bodies.values()] + } + + private call(id: TypeNodeId, value: string, path = 'path'): string { + const reference = this.reference(id) + return reference === undefined ? value : `${reference}(${value}, writeBytes, ${path}, ancestors)` + } + + private body(id: TypeNodeId): string { + const node = this.renderer.node(id) + switch (node.kind) { + case 'reference': { + if (node.target.kind === 'standard' && node.target.name === 'Uint8Array') { + return 'return value instanceof Uint8Array ? writeBytes(value, path) : value' + } + if (node.target.kind === 'declaration') { + const type = this.renderer.declaration(node.target.symbol).type + if (type !== undefined) return `return ${this.call(type, 'value')}` + } + break + } + case 'union': + case 'intersection': return [ + ...node.types.filter(type => containsBytes(this.renderer, type)).map(type => `value = ${this.call(type, 'value')}`), + 'return value', + ].join('\n') + case 'array': return [ + 'if (!Array.isArray(value)) return value', + `for (let index = 0; index < value.length; index++) value[index] = ${this.call(node.element, 'value[index]', '[...path, index]')}`, + 'return value', + ].join('\n') + case 'tuple': { + const lines = ['if (!Array.isArray(value)) return value'] + for (const [index, element] of node.elements.entries()) { + if (!containsBytes(this.renderer, element.type)) continue + if (element.rest) { + const rest = this.renderer.node(element.type) + if (rest.kind !== 'array') break + lines.push(`for (let index = ${index}; index < value.length; index++) value[index] = ${this.call(rest.element, 'value[index]', '[...path, index]')}`) + } else { + lines.push(`if (value.length > ${index}) value[${index}] = ${this.call(element.type, `value[${index}]`, `[...path, ${index}]`)}`) + } + } + return [...lines, 'return value'].join('\n') + } + case 'object': { + const lines = ["if (value === null || typeof value !== 'object' || Array.isArray(value) || value instanceof Uint8Array) return value"] + for (const member of node.members) { + if (member.kind === 'property' && containsBytes(this.renderer, member.type)) { + const key = quote(member.name) + lines.push(`if (Object.hasOwn(value, ${key})) value[${key}] = ${this.call(member.type, `value[${key}]`, `[...path, ${key}]`)}`) + } else if (member.kind === 'index' && containsBytes(this.renderer, member.signature.returns)) { + lines.push(`for (const key of Object.keys(value)) value[key] = ${this.call(member.signature.returns, 'value[key]', '[...path, key]')}`) + } + } + return [...lines, 'return value'].join('\n') + } + default: break + } + throw new TypertEmitError(`typert result encoder: ${node.kind} has no binary field projection`) + } +} + +const RESULT_SNAPSHOT = `const $resultSnapshot = (input, path) => { + if (input === null || typeof input !== 'object' || input instanceof Uint8Array) return input + const toJSON = input.toJSON + const value = typeof toJSON === 'function' ? toJSON.call(input, path.at(-1)?.toString() ?? 'value') : input + if (value === null || typeof value !== 'object' || value instanceof Uint8Array) return value + if (Array.isArray(value)) { + const items = [] + for (let index = 0, length = value.length; index < length; index++) items.push(value[index]) + return items + } + const fields = {} + for (const key of Object.keys(value)) { + const item = key === 'toJSON' && value === input ? toJSON : value[key] + if (key === 'toJSON' && typeof item === 'function') continue + Object.defineProperty(fields, key, { value: item, enumerable: true, writable: true, configurable: true }) + } + return fields +} +const $resultContainer = (input, path, ancestors, project, snapshot) => { + if (input === null || typeof input !== 'object') return project(input) + const owner = !ancestors.has(input) + if (!owner && ancestors.get(input) !== path.length) throw new TypeError('Remote result contains a circular object') + if (owner) ancestors.set(input, path.length) + try { return project(snapshot ? $resultSnapshot(input, path) : input) } + finally { if (owner) ancestors.delete(input) } +}` + class SchemaEmitter { private readonly names = new Map() private readonly boundaryNames = new Map() @@ -569,10 +693,15 @@ class SchemaEmitter { emit(): SchemaArtifact { const definitions = this.declarations.map(declaration => this.declarationDefinition(declaration)) + const encoder = new ResultEncoderEmitter(this.renderer) + const encoders = new Map() for (const boundary of this.boundaries) { + const encode = encoder.reference(boundary.type) + if (encode !== undefined) encoders.set(boundary.key, encode) const name = this.boundaryName(boundary.key) definitions.push(`let ${name}$value\nconst ${name} = () => (${name}$value ??= ${this.typeSchema(boundary.type)})`) } + definitions.push(...encoder.definitions()) const exports = this.schemas.map((model): SchemaExport => ({ model, exportName: safeIdentifier(model.export.name), @@ -582,6 +711,7 @@ class SchemaEmitter { definitions, exports, boundary: key => this.boundaryName(key), + encoder: key => encoders.get(key), } } @@ -699,6 +829,7 @@ class SchemaEmitter { return `z.record(${this.typeSchema(key, substitutions)}, ${this.typeSchema(value, substitutions)})` } case 'Date': return 'z.date()' + case 'Uint8Array': return 'z.instanceof(Uint8Array)' default: this.fail(node.name, `standard type ${node.target.name} has no Zod projection`) } } @@ -773,8 +904,11 @@ class SchemaEmitter { continue } if (member.kind !== 'property') this.fail(subject, `${member.kind} member ${member.name} is not data-schema projectable`) + // Freezing a union may freeze its populated Uint8Array member. + const schema = this.readonly(this.typeSchema(member.type, substitutions), + member.readonly && !containsBytes(this.renderer, member.type, false)) const property = this.describe( - this.optional(this.readonly(this.typeSchema(member.type, substitutions), member.readonly), member.optional), + this.optional(schema, member.optional), member, ) properties.push(`${quote(member.jsonName ?? member.name)}: ${property}`) @@ -890,12 +1024,40 @@ function resultBoundaryKey(invocation: InvocationModel): string { return `${invocation.id}:result` } -function strictCodec(boundary: RemoteBoundaryModel, schema: string): string { +function containsBytes( + renderer: TypeGraphRenderer, + id: TypeNodeId, + nested = true, + visited = new Set(), +): boolean { + if (visited.has(id)) return false + visited.add(id) + const node = renderer.node(id) + if (node.kind === 'reference') { + if (node.target.kind === 'standard' && node.target.name === 'Uint8Array') return true + if (node.target.kind === 'declaration') { + const declaration = renderer.declaration(node.target.symbol) + if (declaration.type !== undefined && containsBytes(renderer, declaration.type, nested, visited)) return true + } + if (!nested) return false + } + if (!nested && node.kind !== 'reference' && node.kind !== 'parenthesized' + && node.kind !== 'union' && node.kind !== 'intersection') return false + if (node.kind === 'object' && node.members.some(member => + containsBytes(renderer, member.kind === 'property' ? member.type : member.signature.returns, nested, visited))) return true + return childTypeNodeIds(node).some(child => containsBytes(renderer, child, nested, visited)) +} + +function strictCodec(boundary: RemoteBoundaryModel, schema: string, encoder?: string): string { return [ '{', ' mode: \'strict\',', ` typeSymbol: ${quote(boundary.typeSymbol)},`, ` create: ${schema},`, + ...(encoder === undefined ? [] : [ + ` decode: value => ${schema}().parse(value),`, + ` encode: (value, writeBytes) => ${encoder}(value, writeBytes, [], new Map()),`, + ]), '}', ].join('\n') } @@ -923,7 +1085,13 @@ function remoteImports(invocations: readonly InvocationModel[]): RemoteTypeImpor } function allocateRemoteImportNames(imports: readonly RemoteTypeImportModel[]): ReadonlyMap { - const used = new Set(['RemoteStreamHandle', 'TypertRemoteContribution', 'TYPERT_REMOTE']) + const used = new Set([ + 'RemoteDecoded', + 'RemoteResult', + 'RemoteStreamHandle', + 'TypertRemoteContribution', + 'TYPERT_REMOTE', + ]) const names = new Map() for (const imported of imports) { const base = safeIdentifier(imported.name) diff --git a/packages/typert/generator/tests/remote-model.spec.ts b/packages/typert/generator/tests/remote-model.spec.ts index e291df692c..e8e69be85f 100644 --- a/packages/typert/generator/tests/remote-model.spec.ts +++ b/packages/typert/generator/tests/remote-model.spec.ts @@ -15,7 +15,7 @@ function normalizedPath(path: string): string { } interface RuntimeSchema { - safeParse(value: unknown): { readonly success: boolean } + safeParse(value: unknown): { readonly success: boolean; readonly data?: unknown } } interface RuntimeDescriptor { @@ -30,7 +30,11 @@ interface RuntimeDescriptor { readonly uplink?: { readonly codec: { readonly create: () => RuntimeSchema } } - readonly result: { readonly create: () => RuntimeSchema } + readonly result: { + readonly create: () => RuntimeSchema + readonly decode?: (value: unknown) => unknown + readonly encode?: (value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown + } } interface RuntimeRemoteModule { @@ -51,6 +55,234 @@ afterEach(() => { }) describe('Remote model generation', { timeout: 60_000 }, () => { + it('projects a generic binary result without copying or freezing its bytes', async () => { + const root = copyFixture() + editFile(root, 'packages/remote/src/types.ts', source => `${source}\nexport type BinaryFile = {\n readonly data: Data\n} & { readonly size: number }\n`) + editFile(root, 'packages/remote/src/index.ts', source => `import type { BinaryFile } from './types.ts'\n${source.replace( + '\n}\n\nexport type {', + '\n @Remote\n bytes(): BinaryFile { return { data: new Uint8Array([0, 255]), size: 2 } }\n}\n\nexport type {', + )}`) + const [artifact] = new WorkspaceTypertGenerator(root).generate() + expect(artifact?.js).not.toContain('binaryResult') + expect(artifact?.remote?.dts).toContain('Promise>>') + const generated = await import(`data:text/javascript,${encodeURIComponent( + (artifact?.remote?.js ?? '').replace("from 'zod'", `from ${JSON.stringify(import.meta.resolve('zod'))}`), + )}`) as RuntimeRemoteModule + const descriptor = generated.TYPERT_REMOTE.descriptors.find(invocation => invocation.id.endsWith('/bytes')) + expect(descriptor?.result.decode).toBeTypeOf('function') + if (descriptor === undefined) throw new Error('binary descriptor missing') + const schema = descriptor.result.create() + for (const data of [new Uint8Array(), new Uint8Array([0, 128, 255]), new Uint8Array(new SharedArrayBuffer(3))]) { + const parsed = schema.safeParse({ data, size: data.length }) + expect(parsed.success).toBe(true) + expect((parsed.data as { readonly data: Uint8Array }).data).toBe(data) + expect(Object.isFrozen(data)).toBe(false) + } + expect(schema.safeParse({ data: 'AP8=', size: 2 }).success).toBe(false) + expect(schema.safeParse({ data: [0, 255], size: 2 }).success).toBe(false) + expect(schema.safeParse({ data: new Uint8Array(), size: '0' }).success).toBe(false) + expect(schema.safeParse({ size: 0 }).success).toBe(false) + assertRemoteConsumerTypechecks(artifact?.remote?.dts, artifact?.remote?.dtsMap, root, ` +async function readBytes() { + const result = await ctx.remote.goals.bytes() + if (!result.ok) return + const data: Uint8Array = result.value.data + new Blob([data]) + // @ts-expect-error binary results do not carry base64 strings. + const base64: string = result.value.data + // @ts-expect-error the Client bytes have ordinary ArrayBuffer backing. + const shared: Uint8Array = result.value.data + void base64 + void shared +} +void readBytes +`) + }) + + it.each([ + ['parameter', '@Remote\n bytes(data: Uint8Array): number { return data.length }'], + ['nested parameter', '@Remote\n bytes(files: { content: Uint8Array }[]): number { return files.length }'], + ['binary stream', "@Remote({ mode: 'stream' })\n async *bytes(): AsyncIterable<{ data: Uint8Array }> { throw new Error() }"], + ])('rejects unsupported binary %s', (_name, method) => { + const root = copyFixture() + editFile(root, 'packages/remote/src/index.ts', source => source.replace( + '\n}\n\nexport type {', `\n ${method}\n}\n\nexport type {`, + )) + expect(() => new WorkspaceTypertGenerator(root).generate()) + .toThrow('Remote Uint8Array is only supported in unary results') + }) + + it.each([ + ['undefined data', '{ data: Uint8Array | undefined }', 'Remote boundary contains non-JSON type undefined'], + ['unconstrained metadata', '{ data: Uint8Array; meta: unknown }', 'Remote boundary contains unconstrained unknown data'], + ])('rejects binary results with %s', (_name, type, message) => { + const root = copyFixture() + editFile(root, 'packages/remote/src/index.ts', source => source.replace( + '\n}\n\nexport type {', `\n @Remote\n bytes(): ${type} { throw new Error() }\n}\n\nexport type {`, + )) + expect(() => new WorkspaceTypertGenerator(root).generate()).toThrow(message) + }) + + it('decodes recursive objects, arrays, tuples, unions and root bytes by their field types', async () => { + const root = copyFixture() + editFile(root, 'packages/remote/src/types.ts', source => `${source} +declare const fileNameBrand: unique symbol +export type FileName = string & { readonly [fileNameBrand]: true } +export type LinkedBytes = { readonly content: Uint8Array } & { readonly next?: LinkedBytes } +export interface BinaryTree { + readonly name: FileName + readonly content?: Uint8Array | null + readonly files: readonly BinaryTree[] + readonly pair: readonly [Uint8Array, { readonly raw: Uint8Array }?] + readonly tail: readonly [string, ...Uint8Array[]] + readonly choice: Uint8Array | { readonly preview: Uint8Array } + readonly variants: ({ readonly content: Uint8Array } & { readonly content: Uint8Array; readonly size: number })[] + readonly chunks: Readonly> +} +`) + editFile(root, 'packages/remote/src/index.ts', source => `import type { BinaryTree, LinkedBytes } from './types.ts'\n${source.replace( + '\n}\n\nexport type {', ` + @Remote + tree(): BinaryTree { throw new Error() } + @Remote + linked(): LinkedBytes { throw new Error() } + @Remote + raw(): Uint8Array { throw new Error() } + @Remote + nullable(): Uint8Array | null { throw new Error() } + @Remote + maybe(): Uint8Array | void { throw new Error() } + @Remote + array(): readonly Uint8Array[] { throw new Error() } + @Remote + envelope(): { readonly content?: Uint8Array; readonly metadata: { readonly title: string } } { throw new Error() } + @Remote + overlap(): { content: Uint8Array } | { content: Uint8Array; title: string } { throw new Error() } + @Remote + objectOrBytes(): { content: Uint8Array } | Uint8Array { throw new Error() } +}\n\nexport type {`, + )}`) + const [artifact] = new WorkspaceTypertGenerator(root).generate() + const generated = await import(`data:text/javascript,${encodeURIComponent( + (artifact?.remote?.js ?? '').replace("from 'zod'", `from ${JSON.stringify(import.meta.resolve('zod'))}`), + )}`) as RuntimeRemoteModule + const codec = (method: string) => { + const descriptor = generated.TYPERT_REMOTE.descriptors.find(item => item.id.endsWith(`/${method}`)) + if (descriptor === undefined) throw new Error(`descriptor missing: ${method}`) + return descriptor.result + } + const content = new Uint8Array([128, 255]) + const leaf = { name: 'leaf', files: [], pair: [content], tail: ['parts', content], choice: content, variants: [], chunks: {} } + const value = { + ...leaf, content, files: [{ ...leaf, content: null }], pair: [content, { raw: content }], + choice: { preview: content }, variants: [{ content, size: 2 }], chunks: { 'a.b/c': content }, + } + expect(codec('tree').decode?.(value)).toEqual(value) + const parsed = codec('tree').decode?.(value) as typeof value + expect(parsed.content).toBe(content) + expect(Object.isFrozen(parsed.files)).toBe(true) + expect(Object.isFrozen(parsed.pair)).toBe(true) + expect(parsed.pair[0]).toBe(content) + expect(parsed.variants[0]?.content).toBe(content) + expect(parsed.tail[1]).toBe(content) + expect(Object.isFrozen(content)).toBe(false) + expect(codec('tree').decode?.(leaf)).toEqual(leaf) + expect(() => codec('tree').decode?.({ ...value, files: [{ ...leaf, content: 'base64' }] })).toThrow() + expect(() => codec('tree').decode?.({ ...value, variants: [{ content, size: '2' }] })).toThrow() + expect(codec('raw').decode?.(content)).toBe(content) + expect(codec('nullable').decode?.(null)).toBe(null) + expect(codec('nullable').decode?.(content)).toBe(content) + expect(codec('maybe').decode?.(undefined)).toBeUndefined() + expect(codec('maybe').decode?.(content)).toBe(content) + expect(() => codec('raw').decode?.([128, 255])).toThrow() + expect(codec('array').decode?.([content])).toEqual([content]) + expect((codec('array').decode?.([content]) as Uint8Array[])[0]).toBe(content) + expect(codec('create').decode).toBeUndefined() + expect(codec('create').encode).toBeUndefined() + const attachments: { bytes: Uint8Array; path: readonly (string | number)[] }[] = [] + const writeBytes = (bytes: Uint8Array, path: readonly (string | number)[]): null => { + attachments.push({ bytes, path }) + return null + } + const metadata = codec('tree').encode?.(value, writeBytes) as typeof value + expect(attachments.map(item => item.path)).toEqual([ + ['content'], ['files', 0, 'pair', 0], ['files', 0, 'tail', 1], ['files', 0, 'choice'], + ['pair', 0], ['pair', 1, 'raw'], ['tail', 1], ['choice', 'preview'], + ['variants', 0, 'content'], ['chunks', 'a.b/c'], + ]) + expect(attachments.every(item => item.bytes === content)).toBe(true) + expect(metadata.content).toBeNull() + expect(metadata.files[0]?.content).toBeNull() + expect(metadata.variants[0]?.content).toBeNull() + expect(value.content).toBe(content) + attachments.length = 0 + expect(codec('overlap').encode?.({ content, title: 'image' }, writeBytes)).toEqual({ content: null, title: 'image' }) + expect(attachments).toEqual([{ bytes: content, path: ['content'] }]) + attachments.length = 0 + const augmented = Object.assign(new Uint8Array(new SharedArrayBuffer(1)).fill(127), { content }) + expect(codec('objectOrBytes').encode?.(augmented, writeBytes)).toBeNull() + expect(augmented.content).toBe(content) + expect(attachments).toEqual([{ bytes: augmented, path: [] }]) + attachments.length = 0 + expect(codec('raw').encode?.(content, writeBytes)).toBeNull() + expect(attachments).toEqual([{ bytes: content, path: [] }]) + expect(codec('maybe').encode?.(undefined, writeBytes)).toBeUndefined() + const circular: { files: unknown[] } = { ...leaf, files: [] } + circular.files.push(circular) + expect(() => codec('tree').encode?.(circular, writeBytes)).toThrow('circular object') + const linked: { content: Uint8Array; next?: unknown } = { content } + linked.next = linked + expect(() => codec('linked').encode?.(linked, writeBytes)).toThrow('circular object') + let metadataReads = 0 + let contentReads = 0 + const opaque = { get title() { metadataReads++; return 'image' } } + const optional = { get content() { contentReads++; return undefined }, metadata: opaque } + const absent = codec('envelope').encode?.(optional, writeBytes) as typeof optional + expect(absent.metadata).toBe(opaque) + expect(metadataReads).toBe(0) + expect(JSON.stringify(absent)).toBe('{"metadata":{"title":"image"}}') + expect(contentReads).toBe(1) + expect(metadataReads).toBe(1) + let jsonCalls = 0 + const projected = codec('envelope').encode?.({ toJSON(key: string) { + jsonCalls++ + expect(key).toBe('value') + return { content, metadata: { title: 'image' } } + } }, writeBytes) + expect(JSON.stringify(projected)).toBe('{"content":null,"metadata":{"title":"image"}}') + expect(jsonCalls).toBe(1) + const dictionary = codec('tree').encode?.({ + ...leaf, chunks: Object.fromEntries([['__proto__', content]]), + }, writeBytes) as typeof value + expect(Object.hasOwn(dictionary.chunks, '__proto__')).toBe(true) + expect((dictionary.chunks as Record)['__proto__']).toBeNull() + assertRemoteConsumerTypechecks(artifact?.remote?.dts, artifact?.remote?.dtsMap, root, ` +import type { BinaryTree, FileName } from '@fixture/remote/types' +async function binaryTree() { + const result = await ctx.remote.goals.tree() + if (!result.ok) return + const tree: BinaryTree = result.value + const name: FileName = result.value.name + const leaf = result.value.files[0]! + if (leaf.content) new Blob([leaf.content]) + const pair: readonly [Uint8Array, { readonly raw: Uint8Array }?] = leaf.pair + const choice: Uint8Array | { readonly preview: Uint8Array } = leaf.choice + const chunk: Uint8Array = leaf.chunks['file']! + // @ts-expect-error array readonly modifier is preserved. + result.value.files.push(leaf) + // @ts-expect-error property readonly modifier is preserved. + result.value.name = name + const raw = await ctx.remote.goals.raw() + if (raw.ok) new Blob([raw.value]) + const maybe: Promise | void>> = ctx.remote.goals.maybe() + const absent = await maybe + if (absent.ok && absent.value !== undefined) new Blob([absent.value]) + void tree; void pair; void choice; void chunk +} +void binaryTree +`) + }) + it('discovers a Remote-only package and emits strict direct and Context descriptors', async () => { const generator = new WorkspaceTypertGenerator(fixtureRoot) @@ -740,6 +972,7 @@ function assertRemoteConsumerTypechecks( dts: string | undefined, dtsMap: string | undefined, sourceRoot = fixtureRoot, + extraConsumer = '', ): void { if (dts === undefined) throw new Error('Remote fixture emitted no Host-for-Client declaration') if (dtsMap === undefined) throw new Error('Remote fixture emitted no Host-for-Client declaration map') @@ -782,6 +1015,7 @@ void createdScoped void renamed void watched void navigated +${extraConsumer} ` writeFileSync(consumerPath, consumerSource) const configPath = join(consumerRoot, 'tsconfig.consumer.json') diff --git a/packages/typert/loader/src/index.ts b/packages/typert/loader/src/index.ts index 004a2fdc17..50ec19165d 100644 --- a/packages/typert/loader/src/index.ts +++ b/packages/typert/loader/src/index.ts @@ -273,6 +273,11 @@ function requireStrictCodec(pkgName: string, value: unknown, subject: string): v throw new Error(`typert-loader: ${pkgName} ${subject} must use a strict codec`) } requireString(pkgName, codec, 'typeSymbol', subject) + for (const method of ['decode', 'encode']) { + if (codec[method] !== undefined && typeof codec[method] !== 'function') { + throw new Error(`typert-loader: ${pkgName} ${subject} ${method} must be a function`) + } + } if (typeof codec.create !== 'function') { throw new Error(`typert-loader: ${pkgName} ${subject} has no create() factory`) } diff --git a/packages/typert/loader/tests/loader.spec.ts b/packages/typert/loader/tests/loader.spec.ts index 748f005d4a..72db60cbae 100644 --- a/packages/typert/loader/tests/loader.spec.ts +++ b/packages/typert/loader/tests/loader.spec.ts @@ -535,6 +535,14 @@ describe('validateTypertManifest', () => { const descriptor = strictInvocation() const manifest = { ...base, invocations: [descriptor] } expect(validateTypertManifest('pkg', manifest)).toBe(manifest) + const decoded = { ...descriptor, result: { ...descriptor.result, decode: (value: unknown) => value } } + expect(validateTypertManifest('pkg', { ...base, invocations: [decoded] }).invocations).toEqual([decoded]) + expect(() => validateTypertManifest('pkg', { + ...base, invocations: [{ ...decoded, result: { ...decoded.result, decode: true } }], + })).toThrow('decode must be a function') + expect(() => validateTypertManifest('pkg', { + ...base, invocations: [{ ...decoded, result: { ...decoded.result, encode: true } }], + })).toThrow('encode must be a function') const cancellable = { ...descriptor, cancellation: { parameter: 'signal' } } expect(validateTypertManifest('pkg', { ...base, invocations: [cancellable] }).invocations) .toEqual([cancellable]) diff --git a/packages/typert/protocol/README.i18n.yaml b/packages/typert/protocol/README.i18n.yaml index 8a68e37489..d1073f7952 100644 --- a/packages/typert/protocol/README.i18n.yaml +++ b/packages/typert/protocol/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/typert/protocol/README.md -README.md: e96c53fb2c8ad671fce1bb25c235c06517fc3d6b -README.zh.md: e9cb0f8496683c12ea009530a6cf97bdd023ee24 +README.md: 8a97bb339d462c8dbea7666c7855a7e51ae9b113 +README.zh.md: 9bb2cae765ee5747bf11a92d44ec2bb201b0285d diff --git a/packages/typert/protocol/README.md b/packages/typert/protocol/README.md index e96c53fb2c..8a97bb339d 100644 --- a/packages/typert/protocol/README.md +++ b/packages/typert/protocol/README.md @@ -44,6 +44,8 @@ export class GoalService extends TypertRemoteService { Generation turns the method into a wire endpoint under the service's namespace; Clients call it as a typed method through `ctx.remote` (see the [API Gateway reference](../../../docs/api-gateway.md)). A method opts into cooperative cancellation by declaring `signal: AbortSignal` as its final parameter — the signal is injected, never a JSON parameter or lookup field. +A unary method can return `Uint8Array` directly or within nested objects, arrays, tuples, optional fields, unions, and recursive types. Generation supplies optional result codec `encode()` and `decode()` functions: encoding visits only subtrees whose types can contain bytes, while decoding validates reconstructed values; Client declarations use `Uint8Array` at every byte position while retaining other field types. Pure JSON results pass through without Host byte detection or Client parsing. Parameters, events, and stream items remain JSON-only; runtime object cycles are unsupported. + A stream method (`@Remote({ mode: 'stream' })`) returns `Iterable`, `AsyncIterable`, or `RemoteStream`. `In` declares the items the Client may send back on the same logical stream; the method reads them through `this.ctx.invocation.uplink()`, and the descriptor carries their codec. `RemoteInvocation` also names the receiving `service`, the calling `peer` (a `PeerScope` the connection layer admitted), and the carrier `signal`; `ctx.invocation` is `undefined` on a Context no Remote call derived: the first `bindTypertRemote()` binding in a tree, which every `TypertRemoteService` constructor makes, registers that accessor on the root. A generated Client stream method returns `RemoteStreamHandle`: the handle with `send`, `end`, and `dispose` beside the downlink iteration. Uplink items are validated one by one at the Host because they arrive from the browser; downlink items are values the Host method produced and pass through. ### Associating Host objects and Contexts with wire identities diff --git a/packages/typert/protocol/README.zh.md b/packages/typert/protocol/README.zh.md index e9cb0f8496..9bb2cae765 100644 --- a/packages/typert/protocol/README.zh.md +++ b/packages/typert/protocol/README.zh.md @@ -44,6 +44,8 @@ export class GoalService extends TypertRemoteService { 生成会把方法变为服务命名空间下的 wire 端点;Client 通过 `ctx.remote` 以类型化方法调用它(见 [API Gateway 参考](../../../docs/api-gateway.zh.md))。方法把 `signal: AbortSignal` 声明为最后一个参数即可选择协作式取消——该信号是注入的,绝不会成为 JSON 参数或查找字段。 +一元方法可以直接返回 `Uint8Array`,也可以将其放在嵌套对象、数组、元组、可选字段、联合类型和递归类型中。生成器提供可选的结果 codec `encode()` 和 `decode()`:编码仅访问类型可能包含字节的子树,解码则校验还原后的值;Client 声明在每个字节位置使用 `Uint8Array`,同时保留其他字段类型。纯 JSON 结果不经 Host 字节识别或 Client 解析直接传递。参数、事件与流条目仍仅支持 JSON;不支持运行时对象循环。 + 流方法(`@Remote({ mode: 'stream' })`)返回 `Iterable`、`AsyncIterable` 或 `RemoteStream`。`In` 声明 Client 可以在同一条逻辑流上回送的项;方法通过 `this.ctx.invocation.uplink()` 读取它们,描述符携带其 codec。`RemoteInvocation` 还给出接收服务 `service`、发起调用的 `peer`(连接层接纳的一个 `PeerScope`)与载体 `signal`;非 Remote 调用派生的 Context 上 `ctx.invocation` 为 `undefined`:树中第一个 `bindTypertRemote()` 绑定(每个 `TypertRemoteService` 构造函数都会建立一个)在根上注册该 accessor。生成的 Client 流方法返回 `RemoteStreamHandle`:在下行迭代之外提供 `send`、`end` 与 `dispose` 的句柄。上行项在 Host 逐项校验,因为它们来自浏览器;下行项是 Host 方法产出的值,原样透传。 ### 把 Host 对象与 Context 关联到 wire identity diff --git a/packages/typert/protocol/src/types.ts b/packages/typert/protocol/src/types.ts index 14917682b7..b05ce9249b 100644 --- a/packages/typert/protocol/src/types.ts +++ b/packages/typert/protocol/src/types.ts @@ -273,6 +273,19 @@ export type TypertCodec = readonly typeSymbol: string /** Materialize and return the process-realm schema on first boundary use. */ readonly create: () => TypertSchema + /** + * Decode a unary result whose fields require type-specific handling. + * @param value - result reconstructed by the RPC carrier. + * @returns the validated result, retaining native byte views. + */ + readonly decode?: (value: unknown) => unknown + /** + * Project typed binary fields into carrier-owned multipart attachments. + * @param value - native unary result. + * @param writeBytes - records a byte view at its result-relative path and returns its JSON placeholder. + * @returns JSON metadata with untouched JSON subtrees retained. + */ + readonly encode?: (value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown } | { readonly mode: 'src-json' diff --git a/packages/typert/registry/tests/typert.spec.ts b/packages/typert/registry/tests/typert.spec.ts index 9f9b9c54cb..9df0c730e8 100644 --- a/packages/typert/registry/tests/typert.spec.ts +++ b/packages/typert/registry/tests/typert.spec.ts @@ -99,6 +99,18 @@ function scopedInvocation(): InvocationDescriptor { } describe('TypertRegistry', () => { + it('retains generated result decoders until the contribution is disposed', async () => { + const ctx = await makeCtx() + const decode = (value: unknown) => value + const descriptor: InvocationDescriptor = { + ...invocation(), result: { mode: 'strict', typeSymbol: 'fixture#bytes', create: () => ({ parse: decode }), decode }, + } + const dispose = ctx.typert.register({ ...toolsContribution(), invocations: [descriptor] }) + expect(ctx.typert.local.get('goals/create')?.result).toBe(descriptor.result) + await dispose() + expect(ctx.typert.local.get('goals/create')).toBeUndefined() + }) + it('registers and queries generated schemas separately from package reflection', async () => { const ctx = await makeCtx() const contribution = toolsContribution() diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c2803aabdc..8a78e83473 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1427,6 +1427,9 @@ importers: '@deepseek-ai/dsh-api-gateway': specifier: workspace:^ version: link:../gateway + '@deepseek-ai/dsh-client-connection': + specifier: workspace:^ + version: link:../../client/connection '@deepseek-ai/dsh-client-resources': specifier: workspace:^ version: link:../../client/resources diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index 8e6b094b10..b0d76c28ee 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -855,6 +855,7 @@ export const TYPE_LINK_EXEMPTIONS: Readonly> = { WorkflowAgentInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts', WorkflowResultInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts', WorkspaceFileScope: 'Host workspace file lookup contract is owned by packages/api/workspace-files/README.md', + WorkspaceByteReadOptions: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md', WorkspaceByteRange: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md', WorkspaceDirectoryListing: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md', WorkspaceFileBytes: 'Host workspace file endpoint contract is owned by packages/api/workspace-files/README.md', From 983b89f9a50e3d13afaeaa2567ca5dcab9a2e8e0 Mon Sep 17 00:00:00 2001 From: Yudong Date: Sat, 19 Sep 2026 06:39:20 +0800 Subject: [PATCH 088/100] refactor(fs): default unsupported file watching --- ...-17-sidebar-file-and-directory-auto-refresh.i18n.yaml | 4 ++-- ...2026-09-17-sidebar-file-and-directory-auto-refresh.md | 4 ++-- ...6-09-17-sidebar-file-and-directory-auto-refresh.zh.md | 4 ++-- docs/event-producer-consumer.i18n.yaml | 2 +- docs/event-producer-consumer.md | 6 +++--- docs/subsystems/filesystem.i18n.yaml | 4 ++-- docs/subsystems/filesystem.md | 2 +- docs/subsystems/filesystem.zh.md | 2 +- packages/extensions/tool-cordis/src/api-catalog.ts | 2 +- packages/fs/fs/src/index.ts | 8 +++++++- packages/fs/fs/tests/service.spec.ts | 9 ++++++++- packages/ssh/fs-ssh/README.i18n.yaml | 4 ++-- packages/ssh/fs-ssh/README.md | 2 +- packages/ssh/fs-ssh/README.zh.md | 2 +- packages/ssh/fs-ssh/src/index.ts | 2 -- packages/ssh/fs-ssh/tests/provider.spec.ts | 4 ++-- 16 files changed, 36 insertions(+), 25 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.i18n.yaml b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.i18n.yaml index 70ee32d07a..bee0b26a39 100644 --- a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.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 .agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md -2026-09-17-sidebar-file-and-directory-auto-refresh.md: f33be6a8d45756d3bac83d0a6e21a4110543e3b2 -2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md: 88fe6e7abb4027ec8b5c4fab4f1ad07477aef6fa +2026-09-17-sidebar-file-and-directory-auto-refresh.md: f509a8cf2642d3ca816d40e9e9817d3c962c79a6 +2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md: ff7a950aa86c663d4f5d2fb8e20d64bb2b077f6b diff --git a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md index f33be6a8d4..f509a8cf26 100644 --- a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md +++ b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.md @@ -38,11 +38,11 @@ Notifications invoke existing reload/list operations; a failed reload does not r | Class or type | File | Responsibility | |---|---|---| -| `FileSystem` | [fs/src/index.ts](../../../../packages/fs/fs/src/index.ts) | Declare abstract single-target `watch(target, changed, signal)`: a file observes itself; a directory observes its direct entries. Resolve with an async close function once ready. Unsupported providers explicitly throw, without a new FS error code | +| `FileSystem` | [fs/src/index.ts](../../../../packages/fs/fs/src/index.ts) | Declare single-target `watch(target, changed, signal)`: a file observes itself; a directory observes its direct entries. Resolve with an async close function once ready. The base implementation rejects `FS_IO_ERROR`, so a provider without watching states nothing and adds no FS error code | | `FsTarget` | [fs/src/types.ts](../../../../packages/fs/fs/src/types.ts) | Reuse the existing target type, without another FS watch-event system or upper-layer parsing of `targetKey` | | `LocalFileSystem` | [fs-local/src/index.ts](../../../../packages/fs/fs-local/src/index.ts) | Watches a file's parent with target-only filtering, or the directory itself for directory targets; awaits Chokidar readiness and closure; owns the Chokidar dependency | | `SandboxedFileSystem` | [fs-sandbox/src/index.ts](../../../../packages/fs/fs-sandbox/src/index.ts) | Inherit local read-only observation without duplicating the watcher; retain its write and edit policy checks | -| `SshFileSystem` | [fs-ssh/src/index.ts](../../../../packages/ssh/fs-ssh/src/index.ts) | `watch()` explicitly throws an ordinary exception; the Host converts it to a `workspace-file/watch-unsupported` `RemoteError`, without importing or checking an `FsError` runtime class across packages or passing remote `processPath()` values to local Chokidar | +| `SshFileSystem` | [fs-ssh/src/index.ts](../../../../packages/ssh/fs-ssh/src/index.ts) | Inherits the base `FS_IO_ERROR` rejection; the Host converts it to a `workspace-file/watch-unsupported` `RemoteError`, without importing or checking an `FsError` runtime class across packages or passing remote `processPath()` values to local Chokidar | | `WorkspaceFiles` | [workspace-files/src/index.ts](../../../../packages/api/workspace-files/src/index.ts) | Use `changes(scope, path, signal)` with only the target path. Host stat determines whether directory containment applies, including after type changes; ordinary files retain file-read authority | | `WorkspaceChangeFeed` | [workspace-files/src/changes.ts](../../../../packages/api/workspace-files/src/changes.ts) | Establish the target watch in the existing follow path and emit readiness and changes. Retain the queue and operation-observation input; filter by target before emission without rewriting dispatch | | `ChangeFollower` | [workspace-files/src/changes.ts](../../../../packages/api/workspace-files/src/changes.ts) | Receive operation observations and OS notifications; handle watch errors, close independently of generator pulls, and await watcher closure | diff --git a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md index 88fe6e7abb..ff7a950aa8 100644 --- a/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md +++ b/.agents/notes/implemented/feature/2026-09-17-sidebar-file-and-directory-auto-refresh.zh.md @@ -38,11 +38,11 @@ Sidebar 的 Document Preview 和 Files 面板都需要反映磁盘上的最新 | 类或类型 | 所在文件 | 职责 | |---|---|---| -| `FileSystem` | [fs/src/index.ts](../../../../packages/fs/fs/src/index.ts) | 声明抽象的单目标 `watch(target, changed, signal)` 方法;文件观察自身,目录观察直接子项;就绪后返回异步关闭函数,不支持的提供方显式抛异常,不新增 FS 错误码 | +| `FileSystem` | [fs/src/index.ts](../../../../packages/fs/fs/src/index.ts) | 声明单目标 `watch(target, changed, signal)` 方法;文件观察自身,目录观察直接子项;就绪后返回异步关闭函数,基类以 `FS_IO_ERROR` 拒绝,不支持监听的提供方无需覆写,也不新增 FS 错误码 | | `FsTarget` | [fs/src/types.ts](../../../../packages/fs/fs/src/types.ts) | 沿用现有目标类型,不单独增加 FS 监听事件体系,也不让上层解析 `targetKey` | | `LocalFileSystem` | [fs-local/src/index.ts](../../../../packages/fs/fs-local/src/index.ts) | 文件监听其父目录并过滤到目标,目录监听自身;等待 Chokidar 就绪和关闭;依赖声明在 `fs-local` | | `SandboxedFileSystem` | [fs-sandbox/src/index.ts](../../../../packages/fs/fs-sandbox/src/index.ts) | 继承本地只读监听能力,不复制 watcher 实现;保留自身对写入、编辑的策略检查 | -| `SshFileSystem` | [fs-ssh/src/index.ts](../../../../packages/ssh/fs-ssh/src/index.ts) | `watch()` 显式抛出普通异常;Host 转成 `workspace-file/watch-unsupported` 的 `RemoteError`,不跨包导入或判断 `FsError` 实体,也不把远端 `processPath()` 传给本机 Chokidar | +| `SshFileSystem` | [fs-ssh/src/index.ts](../../../../packages/ssh/fs-ssh/src/index.ts) | 继承基类的 `FS_IO_ERROR` 拒绝;Host 将其转换为 `workspace-file/watch-unsupported` 的 `RemoteError`,不跨包导入或判断 `FsError` 实体,也不把远端 `processPath()` 传给本机 Chokidar | | `WorkspaceFiles` | [workspace-files/src/index.ts](../../../../packages/api/workspace-files/src/index.ts) | 使用仅携带目标路径的 `changes(scope, path, signal)`;Host stat 决定是否执行目录包含检查,目标类型变化后也检查,普通文件沿用文件读取权限 | | `WorkspaceChangeFeed` | [workspace-files/src/changes.ts](../../../../packages/api/workspace-files/src/changes.ts) | 在现有 follow 中建立目标 watch,发送就绪和变化;保留原队列与操作观察入口,出流前过滤目标,不重写整套分发逻辑 | | `ChangeFollower` | [workspace-files/src/changes.ts](../../../../packages/api/workspace-files/src/changes.ts) | 接收操作观察与 OS 通知,处理监听错误;关闭独立于生成器拉取进度,并等待 watcher 关闭完成 | diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml index 33dfb05b8e..94906b4159 100644 --- a/docs/event-producer-consumer.i18n.yaml +++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md -event-producer-consumer.md: 8101bb9aa3d6e3da1cca96a5593de5c52d6454cd +event-producer-consumer.md: de767c7629adcf554b3c58e43bb91af62e7aac1c event-producer-consumer.zh.md: a57e1b7e9447939e6a6586c4743dfd39345cc15c diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 8101bb9aa3..de767c7629 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -41,9 +41,9 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `credentials/reference-updated` | `emit` | [`packages/credentials/credentials/src/types.ts:90`](../packages/credentials/credentials/src/types.ts) | [`credentials`](../packages/credentials/credentials) (`events.dispatch`) | [`credentials`](../packages/credentials/credentials), `remotes` | | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace), `workspace-controller` | | `feedback/committed` | `parallel` | [`packages/feedback/message-feedback/src/index.ts:58`](../packages/feedback/message-feedback/src/index.ts) | [`message-feedback`](../packages/feedback/message-feedback) (`parallel`) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | -| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:66`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) | -| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:76`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem), `workspace-files` | -| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:58`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) | +| `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:67`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) | +| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:77`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`emit`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy), [`skill-filesystem`](../packages/skill/skill-filesystem), `workspace-files` | +| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:59`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`), [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) (`waterfall`) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) | | `goal/activation-changed` | `emit` | [`packages/goal/goal/src/types.ts:150`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | `remotes` | | `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-round-driver`](../packages/goal/goal-round-driver) | | `hmr/change` | `emit` | [`packages/boot/hmr/src/index.ts:30`](../packages/boot/hmr/src/index.ts) | [`hmr`](../packages/boot/hmr) (`emit`) | - | diff --git a/docs/subsystems/filesystem.i18n.yaml b/docs/subsystems/filesystem.i18n.yaml index 06d2e4aa51..c04ea7446f 100644 --- a/docs/subsystems/filesystem.i18n.yaml +++ b/docs/subsystems/filesystem.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 docs/subsystems/filesystem.md -filesystem.md: a4ed5460ac333b57520b241f31f5c809e574f858 -filesystem.zh.md: 6f06c140c1a9a2c685aebd6339cd1ee97d4303bb +filesystem.md: d099e619b208f5984db6ff4561cd203d13910ff0 +filesystem.zh.md: 6e907d07b82c72453ef45d67e6bcb9809431e20a diff --git a/docs/subsystems/filesystem.md b/docs/subsystems/filesystem.md index a4ed5460ac..d099e619b2 100644 --- a/docs/subsystems/filesystem.md +++ b/docs/subsystems/filesystem.md @@ -300,7 +300,7 @@ Abstract filesystem provider. Targets must preserve identity across aliases; rea * @returns a promise resolving once observation is active, with an asynchronous close function. * @throws when the provider does not support watching or cannot initialize the watcher. */ -abstract watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise> +watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise> /** * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a diff --git a/docs/subsystems/filesystem.zh.md b/docs/subsystems/filesystem.zh.md index 6f06c140c1..6e907d07b8 100644 --- a/docs/subsystems/filesystem.zh.md +++ b/docs/subsystems/filesystem.zh.md @@ -300,7 +300,7 @@ Abstract filesystem provider. Targets must preserve identity across aliases; rea * @returns a promise resolving once observation is active, with an asynchronous close function. * @throws when the provider does not support watching or cannot initialize the watcher. */ -abstract watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise> +watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise> /** * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 06602809cb..6791693ea8 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -987,7 +987,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ description: 'Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.', methods: [ { - signature: 'abstract watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise>', + signature: 'watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise>', description: 'Observe one file or a directory\'s direct entries in this provider\'s execution world.', parameters: [{ name: 'target', description: 'resolved file or directory, including an absent path to observe for creation.' }, { name: 'changed', description: 'invalidation callback; errors can be reported during or after initialization.' }, { name: 'signal', description: 'cancels watcher initialization; the caller closes an initialized watcher.' }], returns: 'a promise resolving once observation is active, with an asynchronous close function.', diff --git a/packages/fs/fs/src/index.ts b/packages/fs/fs/src/index.ts index 6f4ebe4e50..1158a6dede 100644 --- a/packages/fs/fs/src/index.ts +++ b/packages/fs/fs/src/index.ts @@ -10,6 +10,7 @@ import { Context, Service } from '@deepseek-ai/cordis' import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox' +import { FsError } from './types.ts' import type { FsDirEntry, FsEditOutcome, @@ -96,7 +97,12 @@ export abstract class FileSystem extends Service { * @returns a promise resolving once observation is active, with an asynchronous close function. * @throws when the provider does not support watching or cannot initialize the watcher. */ - abstract watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise> + watch(target: FsTarget, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise> { + void target + void changed + signal.throwIfAborted() + return Promise.reject(new FsError('Filesystem watching is not supported by this provider.', 'FS_IO_ERROR')) + } /** * The sandbox mode this backend enforces on mutations BY DEFAULT, or diff --git a/packages/fs/fs/tests/service.spec.ts b/packages/fs/fs/tests/service.spec.ts index 41e698a70e..e3105925a5 100644 --- a/packages/fs/fs/tests/service.spec.ts +++ b/packages/fs/fs/tests/service.spec.ts @@ -21,7 +21,6 @@ import type { /** A minimal in-memory fake implementing the provider primitives. */ class FakeFileSystem extends FileSystem { - override watch(): never { throw new Error('Fixture does not support watching') } files = new Map() override async resolve(path: string): Promise { @@ -145,6 +144,14 @@ describe('FileSystem provider seam', () => { await expect(fs.readBytes(target, undefined, 1)).rejects.toMatchObject({ code: 'FS_TOO_LARGE' }) }) + it('rejects watching when a provider does not implement observation', async () => { + const ctx = new Context() + await ctx.plugin(FakeFileSystem) + const fs = ctx.fs as FakeFileSystem + await expect(fs.watch(await fs.resolve('a.txt'), () => {}, new AbortController().signal)) + .rejects.toMatchObject({ code: 'FS_IO_ERROR' }) + }) + it('listDir returns child entry targets without reading file content', async () => { const ctx = new Context() await ctx.plugin(FakeFileSystem) diff --git a/packages/ssh/fs-ssh/README.i18n.yaml b/packages/ssh/fs-ssh/README.i18n.yaml index 9c53eeb146..33b115144a 100644 --- a/packages/ssh/fs-ssh/README.i18n.yaml +++ b/packages/ssh/fs-ssh/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/ssh/fs-ssh/README.md -README.md: a950726df972952a8430ef0d00ba455f2e0de11e -README.zh.md: fa69aaee52c705b094de1b0f4860109023c2069f +README.md: fe777f672ab7cf474adf10b05f6d6f646864548f +README.zh.md: 9aa92d99584c48d9179e26ccd1f733d2bda36441 diff --git a/packages/ssh/fs-ssh/README.md b/packages/ssh/fs-ssh/README.md index a950726df9..fe777f672a 100644 --- a/packages/ssh/fs-ssh/README.md +++ b/packages/ssh/fs-ssh/README.md @@ -67,7 +67,7 @@ This provider contributes no request-prefix content. Its consumers own model-vis - Whole-text reads and individual byte windows are limited to 8 MiB by the helper. Use text streaming or multiple byte windows for larger reads; other JSON transfers also obey the connection’s frame cap. -- Filesystem watching is unsupported: `watch()` throws without polling or opening a local watcher for a remote path. Ordinary reads and consumer-owned manual refresh remain available. +- Filesystem watching is unsupported: the provider keeps no `watch()` override, so the base `FS_IO_ERROR` rejection applies without polling or opening a local watcher for a remote path. Ordinary reads and consumer-owned manual refresh remain available. - Remote file URLs are execution coordinates, not host filesystem handles or Web download links. diff --git a/packages/ssh/fs-ssh/README.zh.md b/packages/ssh/fs-ssh/README.zh.md index fa69aaee52..9aa92d9958 100644 --- a/packages/ssh/fs-ssh/README.zh.md +++ b/packages/ssh/fs-ssh/README.zh.md @@ -67,7 +67,7 @@ kind: "package-reference" - 辅助程序将整段文本读取及单次字节窗口限制为 8 MiB。更大的读取需使用文本流或多个字节窗口;其他 JSON 传输也受连接消息大小上限约束。 -- 不支持文件系统监听:`watch()` 直接抛错,不使用轮询,也不为远程路径建立本地监听。普通读取与消费方提供的手动刷新仍可用。 +- 不支持文件系统监听:提供方不覆写 `watch()`,由基类以 `FS_IO_ERROR` 拒绝;不使用轮询,也不为远程路径建立本地监听。普通读取与消费方提供的手动刷新仍可用。 - 远端文件 URL 是执行坐标,不是主机文件系统句柄或 Web 下载链接。 diff --git a/packages/ssh/fs-ssh/src/index.ts b/packages/ssh/fs-ssh/src/index.ts index 1bbcfbf097..9a20414a95 100644 --- a/packages/ssh/fs-ssh/src/index.ts +++ b/packages/ssh/fs-ssh/src/index.ts @@ -20,8 +20,6 @@ const errorCodes: Record = { export class SshFileSystem extends FileSystem { static inject = ['ssh', 'sandboxPolicy'] - override watch(): never { throw new Error('SSH filesystem watching is not supported') } - override get sandboxMode(): SandboxMode { return this.ctx.sandboxPolicy.defaultMode } override async resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise { diff --git a/packages/ssh/fs-ssh/tests/provider.spec.ts b/packages/ssh/fs-ssh/tests/provider.spec.ts index d242d4184e..b6e6626abf 100644 --- a/packages/ssh/fs-ssh/tests/provider.spec.ts +++ b/packages/ssh/fs-ssh/tests/provider.spec.ts @@ -33,8 +33,8 @@ async function setup() { describe('SSH filesystem provider', () => { it('declares watching unsupported without sending a remote request', async () => { const { fs, dispatch } = await setup() - expect(() => fs.watch(target, vi.fn(), new AbortController().signal)) - .toThrow('SSH filesystem watching is not supported') + await expect(fs.watch(target, vi.fn(), new AbortController().signal)) + .rejects.toMatchObject({ code: 'FS_IO_ERROR' }) expect(dispatch).not.toHaveBeenCalled() }) From 285f0a700550f37e20a2a1a72182771df1c43cd5 Mon Sep 17 00:00:00 2001 From: Yudong Date: Sun, 20 Sep 2026 17:46:37 +0800 Subject: [PATCH 089/100] fix(connection): narrow binary transport values --- apps/web/tests/document-preview.e2e.ts | 4 +++- packages/client/connection/src/client/rpc.ts | 20 +++++++++++-------- packages/client/connection/src/http-bridge.ts | 15 ++++++++++++-- packages/client/connection/src/rpc-host.ts | 6 +++--- .../connection/tests/http-bridge.host.spec.ts | 10 ++++++---- .../tests/html-body.client.spec.tsx | 2 +- 6 files changed, 38 insertions(+), 19 deletions(-) diff --git a/apps/web/tests/document-preview.e2e.ts b/apps/web/tests/document-preview.e2e.ts index e2dc9c1713..adefac10ee 100644 --- a/apps/web/tests/document-preview.e2e.ts +++ b/apps/web/tests/document-preview.e2e.ts @@ -580,7 +580,9 @@ else process.exit(1); const metadata = transferredBody.get('metadata') if (typeof metadata !== 'string') throw new Error('missing PNG metadata') const { attachments } = JSON.parse(metadata) as { attachments: { path: string[]; codec: string; part: string }[] } - expect(attachments).toEqual([{ path: ['data'], codec: 'bytes', part: expect.any(String) as unknown }]) + expect(attachments).toHaveLength(1) + expect(attachments[0]).toMatchObject({ path: ['data'], codec: 'bytes' }) + expect(attachments[0]!.part).toEqual(expect.any(String)) const transferredFile = transferredBody.get(attachments[0]!.part) if (transferredFile === null || typeof transferredFile === 'string') throw new Error('missing PNG payload') expect(Buffer.from(await transferredFile.arrayBuffer())).toEqual(TINY_PNG) diff --git a/packages/client/connection/src/client/rpc.ts b/packages/client/connection/src/client/rpc.ts index 66811432cc..efbb6d5c71 100644 --- a/packages/client/connection/src/client/rpc.ts +++ b/packages/client/connection/src/client/rpc.ts @@ -98,7 +98,7 @@ async function parseBinaryResponse(response: Response): Promise= value.length - : typeof segment !== 'string') - || !Object.hasOwn(value, segment as string | number)) { + for (const segment of attachment.path) { + const value: unknown = Reflect.get(parent, key) + if (typeof value !== 'object' || value === null) { throw new TypeError('connection: invalid binary response path') } + if (Array.isArray(value)) { + if (typeof segment !== 'number' || !Number.isSafeInteger(segment) || segment < 0 || segment >= value.length) { + throw new TypeError('connection: invalid binary response path') + } + } else if (typeof segment !== 'string') { + throw new TypeError('connection: invalid binary response path') + } + if (!Object.hasOwn(value, segment)) throw new TypeError('connection: invalid binary response path') parent = value key = segment as string | number } diff --git a/packages/client/connection/src/http-bridge.ts b/packages/client/connection/src/http-bridge.ts index 03109936b4..713f53dcea 100644 --- a/packages/client/connection/src/http-bridge.ts +++ b/packages/client/connection/src/http-bridge.ts @@ -3,7 +3,7 @@ * web carrier; the fetch-shaped handler itself is transport-agnostic). */ -import type { IncomingMessage, ServerResponse } from 'node:http' +import type { IncomingMessage } from 'node:http' import { Readable } from 'node:stream' import type { ConnectionFetchHandler } from './rpc.ts' @@ -13,6 +13,17 @@ import type { ConnectionFetchHandler } from './rpc.ts' * each body in memory, so this cap is also the per-request resident bound. */ export const DEFAULT_MAX_REQUEST_BODY_BYTES = 300 * 1024 * 1024 +interface BridgeServerResponse { + readonly destroyed: boolean + readonly writableEnded: boolean + on(event: 'close', listener: () => void): this + off(event: 'close' | 'drain', listener: () => void): this + once(event: 'close' | 'drain', listener: () => void): this + writeHead(statusCode: number, headers?: Record): unknown + write(chunk: Uint8Array): boolean + end(): unknown +} + /** * Bridge one node:http request to the fetch-shaped handler (client close * aborts; response writes respect backpressure and stop on disconnect). @@ -23,7 +34,7 @@ export const DEFAULT_MAX_REQUEST_BODY_BYTES = 300 * 1024 * 1024 */ export async function bridge( req: IncomingMessage, - res: ServerResponse, + res: BridgeServerResponse, apiHandler: ConnectionFetchHandler, maxRequestBodyBytes = DEFAULT_MAX_REQUEST_BODY_BYTES, ): Promise { diff --git a/packages/client/connection/src/rpc-host.ts b/packages/client/connection/src/rpc-host.ts index 2007e3a32d..fe185b9316 100644 --- a/packages/client/connection/src/rpc-host.ts +++ b/packages/client/connection/src/rpc-host.ts @@ -310,8 +310,8 @@ function fullResponse(rpcId: RpcIdType, result: Awaited = {} for (const key of Object.keys(value)) { - const item = Reflect.get(value, key) as unknown + const item: unknown = Reflect.get(value, key) // A toJSON method on the projected object must not run a second time. if (key === 'toJSON' && typeof item === 'function') continue const extracted = child(item, key) diff --git a/packages/client/connection/tests/http-bridge.host.spec.ts b/packages/client/connection/tests/http-bridge.host.spec.ts index 8d972824b9..e9fa9df364 100644 --- a/packages/client/connection/tests/http-bridge.host.spec.ts +++ b/packages/client/connection/tests/http-bridge.host.spec.ts @@ -76,7 +76,7 @@ describe('HTTP bridge abort', () => { }) it.each(['write', 'backpressure'])('finishes a multipart response without further writes when the client closes during %s', async (phase) => { - const request = Readable.from([]) as unknown as IncomingMessage + const request = Readable.from([]) as IncomingMessage Object.assign(request, { url: '/api/workspaceFiles/readBytes', method: 'GET', headers: {} }) const body = new FormData() body.set('metadata', '{}') @@ -84,6 +84,7 @@ describe('HTTP bridge abort', () => { let writes = 0 let cleaningUp = false const response = Object.assign(new EventEmitter(), { + destroyed: false, writableEnded: false, writeHead() { return this }, write() { @@ -96,7 +97,7 @@ describe('HTTP bridge abort', () => { return cleaningUp }, end() { this.writableEnded = true; return this }, - }) as unknown as ServerResponse + }) let settled = false const pending = bridge(request, response, { requestBodyMode: () => 'buffered', @@ -115,14 +116,15 @@ describe('HTTP bridge abort', () => { }) it('discards bytes returned after the client disconnects', async () => { - const request = Readable.from([]) as unknown as IncomingMessage + const request = Readable.from([]) as IncomingMessage Object.assign(request, { url: '/api/workspaceFiles/readBytes', method: 'GET', headers: {} }) const response = Object.assign(new EventEmitter(), { + destroyed: false, writableEnded: false, writeHead() { return this }, write() { throw new Error('a disconnected response must not receive bytes') }, end() { this.writableEnded = true; return this }, - }) as unknown as ServerResponse + }) const started = Promise.withResolvers() let controller!: ReadableStreamDefaultController const body = new ReadableStream({ diff --git a/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx index fdbd5452cb..8ed6f439a2 100644 --- a/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx +++ b/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx @@ -161,7 +161,7 @@ describe('HtmlBody', () => { const preference = new DeveloperToolsPreference(host.scope) const readRelated = vi.fn().mockResolvedValue({ ok: true, value: { absolutePath: '/workspace/asset.js', version: 'asset-v1', offset: 0, eof: true, - data: btoa('window.loaded = true'), + data: utf8('window.loaded = true'), } }) const scripted: HtmlBodyProps = { ...props('

    Preview

    '), From 2aac7c8ef5259fb4e4d9bcd0c8864e6cf1561bf0 Mon Sep 17 00:00:00 2001 From: Yudong Date: Sun, 20 Sep 2026 18:11:10 +0800 Subject: [PATCH 090/100] fix(connection): keep narrowed attachment path type --- packages/client/connection/src/client/rpc.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/client/connection/src/client/rpc.ts b/packages/client/connection/src/client/rpc.ts index efbb6d5c71..c5d5c9b394 100644 --- a/packages/client/connection/src/client/rpc.ts +++ b/packages/client/connection/src/client/rpc.ts @@ -124,7 +124,7 @@ async function parseBinaryResponse(response: Response): Promise Date: Sun, 20 Sep 2026 18:22:56 +0800 Subject: [PATCH 091/100] refactor(api): move Remote result projection to gateway --- ...08-02-typert-remote-method-calls.i18n.yaml | 4 +- .../2026-08-02-typert-remote-method-calls.md | 4 +- ...026-08-02-typert-remote-method-calls.zh.md | 4 +- ...7-workspace-file-binary-transfer.i18n.yaml | 4 +- ...26-09-17-workspace-file-binary-transfer.md | 2 +- ...09-17-workspace-file-binary-transfer.zh.md | 2 +- docs/api-gateway.md | 2 +- docs/api-gateway.zh.md | 2 +- docs/config-catalog.i18n.yaml | 4 +- docs/config-catalog.md | 4 +- docs/config-catalog.zh.md | 4 +- docs/event-producer-consumer.i18n.yaml | 4 +- docs/event-producer-consumer.md | 2 +- docs/event-producer-consumer.zh.md | 2 +- docs/subsystems/typert.i18n.yaml | 4 +- docs/subsystems/typert.md | 2 +- docs/subsystems/typert.zh.md | 2 +- packages/client/connection/src/index.ts | 2 + packages/client/connection/src/rpc-host.ts | 68 ++----- .../connection/tests/binary-rpc.host.spec.ts | 176 ++++++++---------- .../extensions/tool-cordis/src/api-catalog.ts | 40 ++-- packages/typert/protocol/src/types.ts | 2 +- 22 files changed, 138 insertions(+), 202 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml index 534a9fddcd..279482f67a 100644 --- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.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 .agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md -2026-08-02-typert-remote-method-calls.md: 9986e0dac5e85d0aadc745ca4084ed3d1cecae54 -2026-08-02-typert-remote-method-calls.zh.md: 282af768413498658722af3adee17fb59a8e93c2 +2026-08-02-typert-remote-method-calls.md: 2a12aaf78f638d8af786d2ca817a3fee07a2c614 +2026-08-02-typert-remote-method-calls.zh.md: bf4a7b0179b4dc878a0a53c7076c02e6f1bf0273 diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md index 9986e0dac5..2a12aaf78f 100644 --- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md +++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md @@ -31,8 +31,8 @@ The Remote consumer projection contains `.d.ts`, `.d.ts.map`, and `.js` files. T | `@deepseek-ai/dsh-typert-protocol` | Declares only the minimal `ctx.typert` protocol | `TypertRemoteService`, decorators, binding fallback, descriptors, lookup/Context, and the Remote map; no dependency on the compiler, Zod, Connection, or Browser | | Typert registry | `ctx.typert` | Separately stores reflection for the current environment, imported Remote contributions, lookup providers, and Context providers | | Typert generator/loader | No new business service | Generates three kinds of `lib` artifacts from the Host/Client Programs and registers the current environment's artifacts with `ctx.typert` | -| API Gateway's Host face | `ctx.typertGateway` | Associates Host definitions with live Services, decodes parameters, resolves receivers, and invokes methods | -| Connection | `ctx.connection` | Exclusively owns the HTTP Server/future WebSocket, the shared `/api` route, RPC envelope, rpcId, serialization, trust, error transport, Typert interception, and owner-registered exact Fetch routes on the same channel | +| API Gateway's Host face | `ctx.typertGateway` | Associates Host definitions with live Services, decodes parameters, resolves receivers, invokes methods, and projects unary results into carrier-neutral fields and attachments | +| Connection | `ctx.connection` | Exclusively owns the HTTP Server/future WebSocket, the shared `/api` route, RPC envelope, rpcId, physical serialization, trust, error transport, Typert interception, and owner-registered exact Fetch routes on the same channel | | API Gateway's Client face | `ctx.remote`, `ctx.remote.` | Mounts Remote contributions, materializes each namespace as a traced `remote.` child Service, and delegates canonical calls to `ctx.connection.rpc` | | API Remotes | No new service | Owns Host Agent/Session lookup policy and serves as the only Client business facade, selecting and mounting `/remote` contributions while exposing the selected API declarations | | Agent/Session owning packages | Existing domain services | Provide both static interface merges and runtime lookup/Context providers | diff --git a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md index 282af76841..bf4a7b0179 100644 --- a/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md @@ -31,8 +31,8 @@ Remote 消费端投影同时包含 `.d.ts`、`.d.ts.map` 和 `.js`。`.d.ts` 只 | `@deepseek-ai/dsh-typert-protocol` | 只声明 `ctx.typert` 的最小协议 | `TypertRemoteService`、decorator、binding 回退、descriptor、lookup/Context 和 Remote map;不依赖 compiler、Zod、Connection 或 Browser | | Typert registry | `ctx.typert` | 分开保存当前环境 reflection、导入的 Remote contribution、lookup provider 和 Context provider | | Typert generator/loader | 无新增业务服务 | 从 Host/Client Program 生成三类 `lib` 产物,并把当前环境产物注册到 `ctx.typert` | -| API Gateway 的 Host face | `ctx.typertGateway` | 关联 Host definition 与活 Service,解码参数、解析 receiver 并调用方法 | -| Connection | `ctx.connection` | 独占 HTTP Server/未来 WebSocket、共享 `/api` route、RPC envelope、rpcId、序列化、trust、错误传输、Typert 拦截,以及各 owner 在同一 channel 上注册的精确 Fetch route | +| API Gateway 的 Host face | `ctx.typertGateway` | 关联 Host definition 与活 Service,解码参数、解析 receiver、调用方法,并将一元结果投影为载体无关的字段与附件 | +| Connection | `ctx.connection` | 独占 HTTP Server/未来 WebSocket、共享 `/api` route、RPC envelope、rpcId、物理序列化、trust、错误传输、Typert 拦截,以及各 owner 在同一 channel 上注册的精确 Fetch route | | API Gateway 的 Client face | `ctx.remote`、`ctx.remote.` | mount Remote contribution,把每个 namespace 实体化为可追踪的 `remote.` 子 Service,并把规范调用交给 `ctx.connection.rpc` | | API Remotes | 无新增服务 | 负责 Host Agent/Session lookup 策略,并作为 Client 业务的唯一 facade,选择并挂载 `/remote` contribution,同时暴露所选 API 声明 | | Agent/Session owning 包 | 既有领域服务 | 同时提供静态 interface merge 与运行时 lookup/Context provider | diff --git a/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.i18n.yaml index 87ea138f6d..7eef4b0fa9 100644 --- a/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.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 .agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md -2026-09-17-workspace-file-binary-transfer.md: 1cfffb4113619fba17479065bac6bb420f214d7d -2026-09-17-workspace-file-binary-transfer.zh.md: 1cacc2c294b979ed7e840c84293eb3f6421c6bcb +2026-09-17-workspace-file-binary-transfer.md: b419c8bd15f51246825ceddf2905ec055bbc70ae +2026-09-17-workspace-file-binary-transfer.zh.md: 9cf3d7074c3d536a5c8a39732231c6996d6f6ead diff --git a/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md index 1cfffb4113..b419c8bd15 100644 --- a/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md +++ b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.md @@ -12,7 +12,7 @@ Document previews need native bytes. Encoding file contents as base64 adds about The [Remote method architecture](2026-08-02-typert-remote-method-calls.md) owns method dispatch and lifetime; this note defines binary success encoding and Client validation. The [workspace file service](2026-09-05-workspace-files-service.md) exposes one binary `readBytes` Remote. Its required options object independently selects a byte `range` and a `baseFile` for relative target resolution. Without `range`, it reads a complete file. This avoids separate method names for orthogonal choices while preserving bounded `fs.readBytes` and `fs.readByteRange` reads. -Typert recursively recognizes `Uint8Array` in unary result types, including root values, optional fields, and containers. Generated result codecs provide `encode()` for subtrees whose types can contain bytes and `decode()` to validate the reconstructed value without iterating, copying, or freezing byte payloads; Client declarations narrow each byte buffer to `ArrayBuffer`. Gateway supplies the encoder to Connection, using identity for strict JSON results so they avoid recursive detection. Source-mode calls retain runtime byte detection. Connection owns standard `FormData` parts and preserves the RPC envelope and correlation id in JSON metadata; it does not depend on Typert reflection. An attachment table associates byte parts with paths through the JSON result; field names remain business-owned. The Client restores `Uint8Array` views over `Blob.arrayBuffer()` and Gateway delegates validation to the generated decoder. Ordinary results and errors retain JSON responses. Gateway owns method dispatch, Session lookup, cancellation, and mount lifetime; feature code needs no multipart reader or dedicated route. +Typert recursively recognizes `Uint8Array` in unary result types, including root values, optional fields, and containers. Generated result codecs provide `encode()` for subtrees whose types can contain bytes and `decode()` to validate the reconstructed value without iterating, copying, or freezing byte payloads; Client declarations narrow each byte buffer to `ArrayBuffer`. Gateway executes the generated encoder, keeps strict JSON values unchanged, and performs runtime byte detection for source-mode calls. It returns JSON-compatible metadata and result-relative byte attachments to Connection. Connection owns standard `FormData` parts and preserves the RPC envelope and correlation id in JSON metadata; it does not inspect business values or depend on Typert reflection. An attachment table associates byte parts with paths through the JSON result; field names remain business-owned. The Client restores `Uint8Array` views over `Blob.arrayBuffer()` and Gateway delegates validation to the generated decoder. Ordinary results and errors retain JSON responses. Gateway owns method dispatch, Session lookup, cancellation, result projection, and mount lifetime; feature code needs no multipart reader or dedicated route. ## Alternatives considered diff --git a/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.zh.md b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.zh.md index 1cacc2c294..9cf3d7074c 100644 --- a/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-17-workspace-file-binary-transfer.zh.md @@ -12,7 +12,7 @@ Status: implemented [Remote 方法架构](2026-08-02-typert-remote-method-calls.zh.md)负责方法分发与生命周期;本记录规定二进制成功响应的编码及 Client 校验。[工作区文件服务](2026-09-05-workspace-files-service.zh.md)提供单一的二进制 `readBytes` Remote。其必填选项对象独立选择字节 `range` 和用于相对目标解析的 `baseFile`。未传 `range` 时读取完整文件。这避免为正交的选择设置不同方法名,同时保留有界的 `fs.readBytes` 和 `fs.readByteRange` 读取。 -Typert 递归识别一元结果类型中的 `Uint8Array`,包括根值、可选字段和容器。生成的结果 codec 提供 `encode()` 处理类型可能包含字节的子树,并通过 `decode()` 校验还原后的值,不逐字节遍历、复制或冻结字节载荷;Client 声明将每个字节缓冲区限定为 `ArrayBuffer`。Gateway 将 encoder 交给 Connection,对 strict JSON 结果原值传递,从而避免递归识别。源码模式调用保留运行时字节识别。Connection 负责标准 `FormData` 部分,并在 JSON 元数据中保留 RPC 信封和关联 id,不依赖 Typert 反射。附件表将字节部分与 JSON 结果中的路径关联,字段名仍由业务拥有。Client 恢复基于 `Blob.arrayBuffer()` 的 `Uint8Array` 视图,Gateway 将校验交给生成的解码器。普通结果与错误继续使用 JSON 响应。Gateway 负责方法分发、Session 查找、取消及挂载生命周期;功能代码无需 multipart 读取器或专用路由。 +Typert 递归识别一元结果类型中的 `Uint8Array`,包括根值、可选字段和容器。生成的结果 codec 提供 `encode()` 处理类型可能包含字节的子树,并通过 `decode()` 校验还原后的值,不逐字节遍历、复制或冻结字节载荷;Client 声明将每个字节缓冲区限定为 `ArrayBuffer`。Gateway 执行生成的 encoder,保持 strict JSON 值不变,并为源码模式调用执行运行时字节识别;随后向 Connection 返回 JSON 兼容元数据及相对于结果的字节附件。Connection 负责标准 `FormData` 部分,并在 JSON 元数据中保留 RPC 信封和关联 id;它不检查业务值,也不依赖 Typert 反射。附件表将字节部分与 JSON 结果中的路径关联,字段名仍由业务拥有。Client 恢复基于 `Blob.arrayBuffer()` 的 `Uint8Array` 视图,Gateway 将校验交给生成的解码器。普通结果与错误继续使用 JSON 响应。Gateway 负责方法分发、Session 查找、取消、结果投影及挂载生命周期;功能代码无需 multipart 读取器或专用路由。 ## 考虑过的替代方案 diff --git a/docs/api-gateway.md b/docs/api-gateway.md index 232ee859c7..957f407758 100644 --- a/docs/api-gateway.md +++ b/docs/api-gateway.md @@ -122,7 +122,7 @@ Strict analysis requires a Remote to be a public, non-static instance method wit Remote calls use the Connection's `/api` route. The Client Remote calls `connection.rpc.call('/api', '/', { args }, signal)`; the HTTP carrier maps this to `POST /api//`, with a payload containing only a named `args` object. -The Connection performs the unified trust check for `/api` before the HTTP bridge, then dispatches inside the shared FetchHandler. The Typert Gateway claims only two-segment endpoints that have a strict descriptor or active SRC marker; binary Remote successes use multipart responses, and feature-owned exact Fetch routes handle responses outside the RPC envelope, and other requests return 404. The Connection owns transport, RPC ids, response envelopes, and request cancellation, while the Gateway owns only the Remote data protocol and business dispatch. Replacing the Connection carrier does not require changes to Remote descriptors or the Client programming interface. +The Connection performs the unified trust check for `/api` before the HTTP bridge, then dispatches inside the shared FetchHandler. The Typert Gateway claims only two-segment endpoints that have a strict descriptor or active SRC marker; it projects binary Remote fields into JSON-compatible metadata and result-relative byte attachments, which Connection frames as multipart responses. Feature-owned exact Fetch routes handle responses outside the RPC envelope, and other requests return 404. Connection owns transport, RPC ids, response envelopes, and request cancellation, while Gateway owns the Remote data protocol and business dispatch. Replacing the Connection carrier does not require changes to Remote descriptors or the Client programming interface. For every call, the Gateway resolves the descriptor and live service from the current registries instead of caching business objects. It requires the fields in `args` to match the descriptor exactly, validates wire values with codecs, resolves objects or receivers through registered lookup or Context providers, and invokes the service method targeted by the binding. The Client Gateway validates decoded binary results with the generated result codec; ordinary JSON results retain their existing handling. A missing provider, unknown identity, binding mismatch, missing or extra argument, schema failure, or missing method fails before entering or after leaving business code. diff --git a/docs/api-gateway.zh.md b/docs/api-gateway.zh.md index aa980adca0..1062adcc89 100644 --- a/docs/api-gateway.zh.md +++ b/docs/api-gateway.zh.md @@ -122,7 +122,7 @@ Remote Client 声明中的参数名来自 wire 字段,参数和返回类型则 Remote 调用使用 Connection 的 `/api` 路由。Client Remote 调用 `connection.rpc.call('/api', '/', { args }, signal)`;HTTP carrier 对应 `POST /api//`,payload 只包含一个具名 `args` 对象。 -Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查,再在共享 FetchHandler 内分发。Typert Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint;二进制 Remote 成功响应使用 multipart,功能自有的精确 Fetch 路由处理 RPC 信封之外的响应,其他请求返回 404。Connection 拥有传输、RPC id、响应 envelope 和请求取消,Gateway 只拥有 Remote 数据协议和业务分发。替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程接口。 +Connection 在 HTTP bridge 之前执行 `/api` 的统一信任检查,再在共享 FetchHandler 内分发。Typert Gateway 只认领存在严格描述符或活跃 SRC marker 的两段式 endpoint;它把二进制 Remote 字段投影为 JSON 兼容元数据及相对于结果的字节附件,再由 Connection 封装为 multipart 响应。功能自有的精确 Fetch 路由处理 RPC 信封之外的响应,其他请求返回 404。Connection 拥有传输、RPC id、响应 envelope 和请求取消,Gateway 拥有 Remote 数据协议和业务分发。替换 Connection carrier 不要求改变 Remote 描述符或 Client 编程接口。 Gateway 每次调用都从当前注册表解析描述符和实时服务,不缓存业务对象。它要求 `args` 的字段集合与描述符完全一致,先用 codec 校验 wire 值,再通过注册的 lookup 或 Context 提供方解析对象或接收者,最后调用 binding 指向的服务方法。Client Gateway 使用生成的结果 codec 校验解码后的二进制结果;普通 JSON 结果保持原有处理方式。缺少提供方、identity 未命中、binding 不一致、参数缺失或多余、schema 失败和方法不存在都会在进入业务代码前或离开业务代码后失败。 diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index 16eda74241..c1cf209b2c 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.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 docs/config-catalog.md -config-catalog.md: 645c64b43a95d227a9373985f05bc50b4b4e93f6 -config-catalog.zh.md: e9f8db259539b83f771027062019039b930f8d37 +config-catalog.md: 1fac327a8a50a09cf694f6fc31a0af1f031f596f +config-catalog.zh.md: fbc043ab62d57d1b7f754e28d3469cc5ebd4fb49 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 645c64b43a..1fac327a8a 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -199,7 +199,7 @@ export interface Config { } ``` -Source: [`packages/api/gateway/src/index.ts:140`](../packages/api/gateway/src/index.ts) +Source: [`packages/api/gateway/src/index.ts:144`](../packages/api/gateway/src/index.ts) @@ -466,7 +466,7 @@ export interface ConnectionRecoveryConfig { } ``` -Source: [`packages/client/connection/src/index.ts:90`](../packages/client/connection/src/index.ts) +Source: [`packages/client/connection/src/index.ts:92`](../packages/client/connection/src/index.ts) diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index e9f8db2595..fbc043ab62 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -201,7 +201,7 @@ export interface Config { } ``` -来源:[`packages/api/gateway/src/index.ts:140`](../packages/api/gateway/src/index.ts) +来源:[`packages/api/gateway/src/index.ts:144`](../packages/api/gateway/src/index.ts) @@ -470,7 +470,7 @@ export interface ConnectionRecoveryConfig { } ``` -来源: [`packages/client/connection/src/index.ts:90`](../packages/client/connection/src/index.ts) +来源: [`packages/client/connection/src/index.ts:92`](../packages/client/connection/src/index.ts) diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml index 94906b4159..bb2e2b647b 100644 --- a/docs/event-producer-consumer.i18n.yaml +++ b/docs/event-producer-consumer.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 docs/event-producer-consumer.md -event-producer-consumer.md: de767c7629adcf554b3c58e43bb91af62e7aac1c -event-producer-consumer.zh.md: a57e1b7e9447939e6a6586c4743dfd39345cc15c +event-producer-consumer.md: 2b373821a2d0c9acf2284c4195a928947700f1ce +event-producer-consumer.zh.md: 90ca2a4c76ac477265a60dad80c5f65d04509e90 diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index de767c7629..2b373821a2 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -30,7 +30,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:89`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | | `compaction/summary-error` | `waterfall` | [`packages/compaction/compaction/src/index.ts:106`](../packages/compaction/compaction/src/index.ts) | [`compaction-basic`](../packages/compaction/compaction-basic) (`waterfall`) | [`compaction-image-offload`](../packages/compaction/compaction-image-offload) | -| `connection/request` | `waterfall` | [`packages/client/connection/src/index.ts:65`](../packages/client/connection/src/index.ts) | `connection` (`waterfall`) | - | +| `connection/request` | `waterfall` | [`packages/client/connection/src/index.ts:67`](../packages/client/connection/src/index.ts) | `connection` (`waterfall`) | - | | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:380`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` | | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:386`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` | | `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:392`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` | diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md index a57e1b7e94..90ca2a4c76 100644 --- a/docs/event-producer-consumer.zh.md +++ b/docs/event-producer-consumer.zh.md @@ -32,7 +32,7 @@ | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:89`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | | `compaction/summary-error` | `waterfall` | [`packages/compaction/compaction/src/index.ts:106`](../packages/compaction/compaction/src/index.ts) | [`compaction-basic`](../packages/compaction/compaction-basic) (`waterfall`) | [`compaction-image-offload`](../packages/compaction/compaction-image-offload) | -| `connection/request` | `waterfall` | [`packages/client/connection/src/index.ts:65`](../packages/client/connection/src/index.ts) | `connection` (`waterfall`) | - | +| `connection/request` | `waterfall` | [`packages/client/connection/src/index.ts:67`](../packages/client/connection/src/index.ts) | `connection` (`waterfall`) | - | | `cordis/dynamic-package` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:380`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` | | `cordis/dynamic-retract` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:386`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` | | `cordis/inspect-query` | `emit` | [`packages/extensions/cordis-host-runner/src/types.ts:392`](../packages/extensions/cordis-host-runner/src/types.ts) | [`cordis-host-runner`](../packages/extensions/cordis-host-runner) (`emit`) | `remotes` | diff --git a/docs/subsystems/typert.i18n.yaml b/docs/subsystems/typert.i18n.yaml index 374b43c01f..e63a0fe9d5 100644 --- a/docs/subsystems/typert.i18n.yaml +++ b/docs/subsystems/typert.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 docs/subsystems/typert.md -typert.md: a8ad968b7af77c90cfcdbeb910f435be461bf442 -typert.zh.md: d020b75ee7c52cc87aaea371978aeebe78d6fa45 +typert.md: db8b48945e2301e14d866b8a2e3df59c4ae408c9 +typert.zh.md: cdaee66201d0f27a5a18aa99cb1888438051e018 diff --git a/docs/subsystems/typert.md b/docs/subsystems/typert.md index a8ad968b7a..db8b48945e 100644 --- a/docs/subsystems/typert.md +++ b/docs/subsystems/typert.md @@ -55,7 +55,7 @@ type TypertCodec = */ readonly decode?: (value: unknown) => unknown /** - * Project typed binary fields into carrier-owned multipart attachments. + * Project typed binary fields into RPC result attachments. * @param value - native unary result. * @param writeBytes - records a byte view at its result-relative path and returns its JSON placeholder. * @returns JSON metadata with untouched JSON subtrees retained. diff --git a/docs/subsystems/typert.zh.md b/docs/subsystems/typert.zh.md index d020b75ee7..cdaee66201 100644 --- a/docs/subsystems/typert.zh.md +++ b/docs/subsystems/typert.zh.md @@ -55,7 +55,7 @@ type TypertCodec = */ readonly decode?: (value: unknown) => unknown /** - * Project typed binary fields into carrier-owned multipart attachments. + * Project typed binary fields into RPC result attachments. * @param value - native unary result. * @param writeBytes - records a byte view at its result-relative path and returns its JSON placeholder. * @returns JSON metadata with untouched JSON subtrees retained. diff --git a/packages/client/connection/src/index.ts b/packages/client/connection/src/index.ts index c76ce937c8..647174f743 100644 --- a/packages/client/connection/src/index.ts +++ b/packages/client/connection/src/index.ts @@ -21,8 +21,10 @@ export type { ConnectionIndexRequest, ConnectionIndexResponse, ConnectionRpcEndpointMatcher, + ConnectionRpcAttachment, ConnectionRpcFailure, ConnectionRpcHandler, + ConnectionRpcHandlerResult, ConnectionRequestRejection, ConnectionRpcResult, ConnectionRequestBodyMode, diff --git a/packages/client/connection/src/rpc-host.ts b/packages/client/connection/src/rpc-host.ts index fe185b9316..0f98bc1f19 100644 --- a/packages/client/connection/src/rpc-host.ts +++ b/packages/client/connection/src/rpc-host.ts @@ -293,63 +293,21 @@ function errorResponse(rpcId: RpcIdType, error: ConnectionRpcFailure): Response } function fullResponse(rpcId: RpcIdType, result: Awaited>): Response { - const body: ConnectionServerResponse = { type: 'server-response', rpcId, result } - if (!result.ok) return Response.json(body) + if (!result.ok) { + const body: ConnectionServerResponse = { type: 'server-response', rpcId, result } + return Response.json(body) + } + const { attachments, ...success } = result + const body: ConnectionServerResponse = { type: 'server-response', rpcId, result: success } + if (attachments === undefined || attachments.length === 0) return Response.json(body) const parts = new FormData() - const attachments: { path: (string | number)[]; codec: 'bytes'; part: string }[] = [] - const path: (string | number)[] = [] - const ancestors = new Set() - const writeBytes = (value: Uint8Array, path: readonly (string | number)[]): null => { - const part = `bytes-${attachments.length}` - attachments.push({ path: [...path], codec: 'bytes', part }) + const attachmentMetadata = attachments.map((attachment, index) => { + const part = `bytes-${index}` // FileSystem bytes may have SharedArrayBuffer backing, which BlobPart excludes. - parts.set(part, new Blob([new Uint8Array(value)])) - return null - } - const extract = (input: unknown, key: string): unknown => { - // Capture accessors and toJSON once, before materializing the JSON metadata. - let value = input - if (input !== null && typeof input === 'object' && !(input instanceof Uint8Array)) { - const toJSON: unknown = Reflect.get(input, 'toJSON') - if (typeof toJSON === 'function') value = Reflect.apply(toJSON, input, [key]) - } - if (value instanceof Uint8Array) return writeBytes(value, path) - if (typeof value !== 'object' || value === null) return value - if (value instanceof Number || value instanceof String || value instanceof Boolean) return value - if (ancestors.has(value)) throw new TypeError('connection: circular RPC result') - ancestors.add(value) - let copy: object - if (Array.isArray(value)) { - const items: unknown[] = [] - // JSON arrays include every index, even holes and non-enumerable elements. - for (let index = 0, length = value.length; index < length; index++) items.push(child(value[index], index)) - copy = items - } else { - const fields: Record = {} - for (const key of Object.keys(value)) { - const item: unknown = Reflect.get(value, key) - // A toJSON method on the projected object must not run a second time. - if (key === 'toJSON' && typeof item === 'function') continue - const extracted = child(item, key) - if (key === '__proto__') Object.defineProperty(fields, key, { value: extracted, enumerable: true }) - else fields[key] = extracted - } - copy = fields - } - ancestors.delete(value) - return copy - } - const child = (value: unknown, key: string | number): unknown => { - if (typeof value !== 'object' || value === null) return value - path.push(key) - const extracted = extract(value, String(key)) - path.pop() - return extracted - } - const value = result.encode === undefined ? extract(result.value, 'value') : result.encode(result.value, writeBytes) - const metadata = { ...body, result: { ok: true, value } } - if (attachments.length === 0) return Response.json(metadata) - parts.set('metadata', JSON.stringify({ ...metadata, attachments })) + parts.set(part, new Blob([new Uint8Array(attachment.bytes)])) + return { path: [...attachment.path], codec: 'bytes' as const, part } + }) + parts.set('metadata', JSON.stringify({ ...body, attachments: attachmentMetadata })) return new Response(parts) } diff --git a/packages/client/connection/tests/binary-rpc.host.spec.ts b/packages/client/connection/tests/binary-rpc.host.spec.ts index b65fefed19..05ec270545 100644 --- a/packages/client/connection/tests/binary-rpc.host.spec.ts +++ b/packages/client/connection/tests/binary-rpc.host.spec.ts @@ -6,7 +6,7 @@ import { describe, expect, it } from 'vitest' import type { BrowserAuth } from '../src/browser-auth.ts' import { createWebConnectionRpc } from '../src/client/rpc.ts' import { bridge } from '../src/http-bridge.ts' -import type { ConnectionRpcResult } from '../src/rpc.ts' +import type { ConnectionRpcHandlerResult, ConnectionRpcResult } from '../src/rpc.ts' import { HostConnectionService } from '../src/rpc-host.ts' function binaryResponse(rpcId: string, mutate: (parts: FormData) => void = () => {}): Response { @@ -29,7 +29,11 @@ describe('Connection binary RPC', () => { const connection = ctx.get('connection') as HostConnectionService const data = new Uint8Array(1024 * 1024).fill(65) data.set([0, 128, 255]) - connection.rpc.intercept('/api', endpoint => endpoint === 'fixture/read', async () => ({ ok: true, value: { data, bytes: data.length } })) + connection.rpc.intercept('/api', endpoint => endpoint === 'fixture/read', async () => ({ + ok: true, + value: { data: null, bytes: data.length }, + attachments: [{ path: ['data'], bytes: data }], + })) const handler = connection.createSharedFetchHandler('/api') ctx.webServer.register({ kind: 'prefix', path: '/api', handler: (req, res) => bridge(req, res, handler) }) let transferred = 0 @@ -73,17 +77,36 @@ describe('Connection binary RPC', () => { await fiber.await() try { const connection = ctx.get('connection') as HostConnectionService - const results: ConnectionRpcResult[] = [ - { ok: true, value: { data: new Uint8Array([9, 0, 128, 255, 9]).subarray(1, 4), offset: 7, eof: false, bytes: 42 } }, - { ok: true, value: { data: new Uint8Array(new SharedArrayBuffer(3)).fill(255), offset: 0, eof: true, bytes: 3 } }, - { ok: true, value: { data: new Uint8Array(), offset: 0, eof: true, bytes: 0 } }, - { ok: true, value: { data: 'AID/', encoding: 'base64' } }, - { ok: true, value: { count: 4 } }, - { ok: true, value: null }, - { ok: true, value: 'plain' }, - { ok: false, error: { code: 'fixture/denied', message: 'denied', details: { path: 'private' } } }, + const byteValues = [ + new Uint8Array([9, 0, 128, 255, 9]).subarray(1, 4), + new Uint8Array(new SharedArrayBuffer(3)).fill(255), + new Uint8Array(), ] - let next: ConnectionRpcResult = results[0]! + const cases: readonly { + readonly sent: ConnectionRpcHandlerResult + readonly expected: ConnectionRpcResult + }[] = [ + ...byteValues.map((data, index) => ({ + sent: { + ok: true as const, + value: { data: null, offset: index === 0 ? 7 : 0, eof: index !== 0, bytes: index === 0 ? 42 : data.length }, + attachments: [{ path: ['data'], bytes: data }], + }, + expected: { + ok: true as const, + value: { data, offset: index === 0 ? 7 : 0, eof: index !== 0, bytes: index === 0 ? 42 : data.length }, + }, + })), + { sent: { ok: true, value: { data: 'AID/', encoding: 'base64' } }, expected: { ok: true, value: { data: 'AID/', encoding: 'base64' } } }, + { sent: { ok: true, value: { count: 4 } }, expected: { ok: true, value: { count: 4 } } }, + { sent: { ok: true, value: null }, expected: { ok: true, value: null } }, + { sent: { ok: true, value: 'plain' }, expected: { ok: true, value: 'plain' } }, + { + sent: { ok: false, error: { code: 'fixture/denied', message: 'denied', details: { path: 'private' } } }, + expected: { ok: false, error: { code: 'fixture/denied', message: 'denied', details: { path: 'private' } } }, + }, + ] + let next: ConnectionRpcHandlerResult = cases[0]!.sent connection.rpc.intercept('/api', endpoint => endpoint === 'fixture/read', async () => next) const shared = connection.createSharedFetchHandler('/api') const mediaTypes: (string | null)[] = [] @@ -92,10 +115,10 @@ describe('Connection binary RPC', () => { mediaTypes.push(response.headers.get('content-type')) return response }) - for (const result of results) { - next = result + for (const { sent, expected } of cases) { + next = sent const received = await rpc.call('/api', 'fixture/read', { args: {} }) - expect(received).toEqual(result) + expect(received).toEqual(expected) if (received.ok && typeof received.value === 'object' && received.value !== null && 'data' in received.value && received.value.data instanceof Uint8Array) { expect(received.value.data.buffer).toBeInstanceOf(ArrayBuffer) @@ -108,28 +131,23 @@ describe('Connection binary RPC', () => { } }) - it('uses owner result codecs without putting their callbacks on the wire', async () => { + it('frames attachments already projected by the result owner', async () => { const ctx = new Context() const fiber = ctx.plugin((owner) => { new HostConnectionService(owner, [], {} as BrowserAuth) }) await fiber.await() try { const connection = ctx.get('connection') as HostConnectionService const content = Buffer.from([9, 0, 128, 255, 9]).subarray(1, 4) - let reads = 0 - const value = { content, metadata: { get count() { return ++reads } } } connection.rpc.intercept('/api', () => true, async () => ({ - ok: true, value, - encode: (input, writeBytes) => { - expect(input).toBe(value) - return { content: writeBytes(content, ['content']), metadata: value.metadata } - }, + ok: true, + value: { content: null, metadata: { count: 1 } }, + attachments: [{ path: ['content'], bytes: content }], })) const handler = connection.createSharedFetchHandler('/api') const rpc = createWebConnectionRpc((url, init) => handler.fetch(new Request(new URL(url, 'http://host'), init))) expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: { content: new Uint8Array([0, 128, 255]), metadata: { count: 1 } }, }) - expect(reads).toBe(1) } finally { await fiber.dispose() } @@ -166,55 +184,56 @@ describe('Connection binary RPC', () => { await expect(rpc.call('/api', 'fixture/read', {})).rejects.toThrow('rpcId mismatch') }) - it('roundtrips nested, optional and root bytes without changing caller objects or reserving field names', async () => { + it('roundtrips nested, optional and root attachment paths without reserving field names', async () => { const ctx = new Context() const fiber = ctx.plugin((owner) => { new HostConnectionService(owner, [], {} as BrowserAuth) }) await fiber.await() try { const data = new Uint8Array([0, 128, 255]) - const shared = { content: data } - const value = { - files: [{ name: 'a.png', ...shared }, { name: 'b.png', content: Buffer.from([9, 2, 3, 9]).subarray(1, 3) }, { name: 'empty' }], - 'dots./[]': [new Uint8Array(), null, [data]], - metadata: { attachments: shared }, - ...JSON.parse('{"__proto__":null,"constructor":null}') as object, + const second = Buffer.from([9, 2, 3, 9]).subarray(1, 3) + let next: ConnectionRpcHandlerResult = { + ok: true, + value: { + files: [{ name: 'a.png', content: null }, { name: 'b.png', content: null }, { name: 'empty' }], + 'dots./[]': [null, null, [null]], + metadata: { attachments: { content: null } }, + ...JSON.parse('{"__proto__":null,"constructor":null}') as object, + }, + attachments: [ + { path: ['files', 0, 'content'], bytes: data }, + { path: ['files', 1, 'content'], bytes: second }, + { path: ['dots./[]', 0], bytes: new Uint8Array() }, + { path: ['dots./[]', 2, 0], bytes: data }, + { path: ['metadata', 'attachments', 'content'], bytes: data }, + { path: ['__proto__'], bytes: data }, + ], } - Object.defineProperty(value, '__proto__', { value: data, enumerable: true }) - Object.freeze(value.files) - Object.freeze(value) - let next: unknown = value const connection = ctx.get('connection') as HostConnectionService - connection.rpc.intercept('/api', () => true, async () => ({ ok: true, value: next })) + connection.rpc.intercept('/api', () => true, async () => next) const handler = connection.createSharedFetchHandler('/api') const rpc = createWebConnectionRpc((url, init) => handler.fetch(new Request(new URL(url, 'http://host'), init))) - expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: { - ...value, files: [value.files[0], { name: 'b.png', content: new Uint8Array([2, 3]) }, value.files[2]], - } }) - expect(value.files[0]?.content).toBe(data) - expect(shared.content).toBe(data) - expect(Object.getPrototypeOf(value)).toBe(Object.prototype) + const expected = { + files: [{ name: 'a.png', content: data }, { name: 'b.png', content: new Uint8Array([2, 3]) }, { name: 'empty' }], + 'dots./[]': [new Uint8Array(), null, [data]], + metadata: { attachments: { content: data } }, + ...JSON.parse('{"__proto__":null,"constructor":null}') as object, + } + Object.defineProperty(expected, '__proto__', { value: data, enumerable: true }) + expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: expected }) for (const bytes of [data, Buffer.from([0, 128, 255]), new Uint8Array(new SharedArrayBuffer(3))]) { - next = bytes + next = { ok: true, value: null, attachments: [{ path: [], bytes }] } const response = await rpc.call('/api', 'fixture/read', {}) expect(response).toEqual({ ok: true, value: new Uint8Array(bytes) }) if (!response.ok || !(response.value instanceof Uint8Array)) throw new Error('expected root bytes') expect(response.value.buffer).toBeInstanceOf(ArrayBuffer) expect(Object.isFrozen(response.value)).toBe(false) } - next = [data, [data]] - expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: next }) - const circular: { next?: object } = {} - circular.next = circular - next = circular - await expect(rpc.call('/api', 'fixture/read', {})).rejects.toThrow('HTTP 500') - next = { ordinary: [1, 'base64', null], omitted: undefined, date: new Date('2026-01-01T00:00:00Z') } - expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: { - ordinary: [1, 'base64', null], date: '2026-01-01T00:00:00.000Z', - } }) - const sparse = [data, , null] - Object.assign(sparse, { extra: data, '-1': data, '01': data, '1.5': data, Infinity: data }) - next = sparse - expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: [data, null, null] }) + next = { + ok: true, + value: [null, [null]], + attachments: [{ path: [0], bytes: data }, { path: [1, 0], bytes: data }], + } + expect(await rpc.call('/api', 'fixture/read', {})).toEqual({ ok: true, value: [data, [data]] }) } finally { await fiber.dispose() } @@ -250,49 +269,6 @@ describe('Connection binary RPC', () => { await expect(rpc.call('/api', 'fixture/read', {})).rejects.toThrow('invalid binary response') }) - it('preserves JSON accessor and toJSON evaluation while reading all array indices', async () => { - const ctx = new Context() - const fiber = ctx.plugin((owner) => { new HostConnectionService(owner, [], {} as BrowserAuth) }) - await fiber.await() - try { - let reads = 0 - let next: unknown = { get count() { return ++reads } } - const connection = ctx.get('connection') as HostConnectionService - connection.rpc.intercept('/api', () => true, async () => ({ ok: true, value: next })) - const handler = connection.createSharedFetchHandler('/api') - const rpc = createWebConnectionRpc((url, init) => handler.fetch(new Request(new URL(url, 'http://host'), init))) - const read = () => rpc.call('/api', 'fixture/read', {}) - expect(await read()).toEqual({ ok: true, value: { count: 1 } }) - expect(reads).toBe(1) - const bytes = new Uint8Array([1, 2]) - next = { get content() { reads++; return bytes }, get count() { return ++reads } } - expect(await read()).toEqual({ ok: true, value: { content: bytes, count: 3 } }) - const array: Uint8Array[] = [] - Object.defineProperty(array, 0, { value: bytes }) - next = array - expect(await read()).toEqual({ ok: true, value: [bytes] }) - const date = Object.assign(new Date('2026-01-01T00:00:00Z'), { content: bytes }) - next = date - expect(await read()).toEqual({ ok: true, value: '2026-01-01T00:00:00.000Z' }) - const json = { self: {} as object, toJSON: () => ({ selected: true }) } - json.self = json - next = json - expect(await read()).toEqual({ ok: true, value: { selected: true } }) - let conversions = 0 - next = { toJSON(key: string) { conversions++; expect(key).toBe('value'); return this }, count: 5 } - expect(await read()).toEqual({ ok: true, value: { count: 5 } }) - expect(conversions).toBe(1) - for (const primitive of [1, 'text', true]) { - next = Object(primitive) as object - expect(await read()).toEqual({ ok: true, value: primitive }) - } - next = { toJSON: 'ordinary' } - expect(await read()).toEqual({ ok: true, value: next }) - } finally { - await fiber.dispose() - } - }) - it('rejects truncated multipart and late bytes after caller cancellation', async () => { const broken = createWebConnectionRpc(async () => new Response('truncated', { headers: { 'content-type': 'multipart/form-data; boundary=fixture' }, diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 6791693ea8..ddf1e301c6 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -3365,22 +3365,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ returns: 'the page, the file\'s version at the stat before it, and whether it reaches the last line.', }, { - signature: '@Remote async readBytes( workspaceFileScope: WorkspaceFileScope, path: string, range: WorkspaceByteRange, signal: AbortSignal, ): Promise', - description: 'Read one byte window of a regular file readable by the filesystem backend: raw bytes, no text decoding and no binary rejection.', - parameters: [{ name: 'workspaceFileScope', description: 'header-derived workspace root for the Session identity on the wire.' }, { name: 'path', description: 'absolute path or path relative to the workspace root; files outside it are allowed.' }, { name: 'range', description: 'the byte window; omitted fields take the window defaults.' }, { name: 'signal', description: 'caller cancellation.' }], - returns: 'the window in base64, the file\'s version and size at the stat before it, and whether it reaches the last byte.', - }, - { - signature: '@Remote async readAll(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise', - description: 'Read a complete regular file as bytes, subject to the configured full-file cap.', - parameters: [{ name: 'workspaceFileScope', description: 'header-derived workspace root for the Session identity on the wire.' }, { name: 'path', description: 'absolute or workspace-relative file path.' }, { name: 'signal', description: 'caller cancellation.' }], - returns: 'one complete base64 window with offset zero and eof true; oversized files fail with too-large.', - }, - { - signature: '@Remote async readRelated( workspaceFileScope: WorkspaceFileScope, path: string, relativePath: string, signal: AbortSignal, ): Promise', - description: 'Read a complete file relative to another file\'s directory, including outside the workspace.', - parameters: [{ name: 'workspaceFileScope', description: 'header-derived workspace root for the Session identity on the wire.' }, { name: 'path', description: 'base file, absolute or workspace-relative.' }, { name: 'relativePath', description: 'relative filesystem path, not a URL or absolute path.' }, { name: 'signal', description: 'caller cancellation.' }], - returns: 'the complete related file using the ordinary file-size and access checks.', + signature: '@Remote async readBytes( workspaceFileScope: WorkspaceFileScope, path: string, options: WorkspaceByteReadOptions, signal: AbortSignal, ): Promise', + description: 'Read a complete regular file or one byte range without text decoding.', + parameters: [{ name: 'workspaceFileScope', description: 'header-derived workspace root for the Session identity on the wire.' }, { name: 'path', description: 'target path, absolute or workspace-relative; relative to the base file\'s directory when provided.' }, { name: 'options', description: 'optional base file and range; without a range the complete-file cap applies.' }, { name: 'signal', description: 'caller cancellation.' }], + returns: 'native bytes with the file\'s version and size at the preceding stat, byte offset, and EOF marker.', }, { signature: '@Remote async stat(workspaceFileScope: WorkspaceFileScope, path: string, signal: AbortSignal): Promise', @@ -4452,6 +4440,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'ConnectionRequestRejection', declaration: 'export type ConnectionRequestRejection = 401 | 403 | undefined;', }, + { + name: 'ConnectionRpcAttachment', + declaration: 'export interface ConnectionRpcAttachment {\n readonly path: readonly (string | number)[];\n readonly bytes: Uint8Array;\n}', + }, { name: 'ConnectionRpcEndpointMatcher', declaration: 'export type ConnectionRpcEndpointMatcher = (endpoint: string) => boolean;', @@ -4462,7 +4454,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'ConnectionRpcHandler', - declaration: 'export type ConnectionRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal, peer: PeerScope) => Promise>;', + declaration: 'export type ConnectionRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal, peer: PeerScope) => Promise;', + }, + { + name: 'ConnectionRpcHandlerResult', + declaration: 'export type ConnectionRpcHandlerResult = {\n readonly ok: true;\n readonly value: unknown;\n readonly attachments?: readonly ConnectionRpcAttachment[];\n} | {\n readonly ok: false;\n readonly error: ConnectionRpcFailure;\n};', }, { name: 'ConnectionRpcResult', @@ -5702,7 +5698,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'RenderedDocumentBytes', - declaration: 'export interface RenderedDocumentBytes extends WorkspaceFileBytes {\n readonly missingFonts: string[];\n readonly generation: OfficeToPdfGeneration;\n}', + declaration: 'export interface RenderedDocumentBytes extends Omit {\n readonly data: string;\n readonly missingFonts: string[];\n readonly generation: OfficeToPdfGeneration;\n}', }, { name: 'ReplayEnvelope', @@ -7034,7 +7030,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'TypertCodec', - declaration: 'export type TypertCodec = {\n readonly mode: \'strict\';\n readonly typeSymbol: string;\n readonly create: () => TypertSchema;\n} | {\n readonly mode: \'src-json\';\n};', + declaration: 'export type TypertCodec = {\n readonly mode: \'strict\';\n readonly typeSymbol: string;\n readonly create: () => TypertSchema;\n readonly decode?: (value: unknown) => unknown;\n readonly encode?: (value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown;\n} | {\n readonly mode: \'src-json\';\n};', }, { name: 'TypertContribution', @@ -7332,6 +7328,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'WorkspaceByteRange', declaration: 'export interface WorkspaceByteRange {\n readonly offset?: number;\n readonly length?: number;\n}', }, + { + name: 'WorkspaceByteReadOptions', + declaration: 'export interface WorkspaceByteReadOptions {\n readonly range?: WorkspaceByteRange;\n readonly baseFile?: string;\n}', + }, { name: 'WorkspaceChangedFile', declaration: 'export interface WorkspaceChangedFile {\n path: string;\n display: string;\n added: number;\n deleted: number;\n binary?: true;\n oversized?: true;\n}', @@ -7370,7 +7370,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'WorkspaceFileBytes', - declaration: 'export interface WorkspaceFileBytes extends WorkspaceFileStat {\n readonly offset: number;\n readonly data: string;\n readonly eof: boolean;\n}', + declaration: 'export interface WorkspaceFileBytes extends WorkspaceFileStat {\n readonly offset: number;\n readonly data: Data;\n readonly eof: boolean;\n}', }, { name: 'WorkspaceFileChange', diff --git a/packages/typert/protocol/src/types.ts b/packages/typert/protocol/src/types.ts index b05ce9249b..ec2a88c4f9 100644 --- a/packages/typert/protocol/src/types.ts +++ b/packages/typert/protocol/src/types.ts @@ -280,7 +280,7 @@ export type TypertCodec = */ readonly decode?: (value: unknown) => unknown /** - * Project typed binary fields into carrier-owned multipart attachments. + * Project typed binary fields into RPC result attachments. * @param value - native unary result. * @param writeBytes - records a byte view at its result-relative path and returns its JSON placeholder. * @returns JSON metadata with untouched JSON subtrees retained. From 44fe86eaf8cd5be39d0af4b168b420027faf0df0 Mon Sep 17 00:00:00 2001 From: Yif <877193178@qq.com> Date: Mon, 21 Sep 2026 13:02:45 +0800 Subject: [PATCH 092/100] test(desktop): cover the minimize backdrop swap and extract the chrome fallback fill --- apps/desktop/src/main.ts | 15 ++++++- apps/desktop/tests/main-startup.spec.ts | 55 +++++++++++++++++++++++-- 2 files changed, 65 insertions(+), 5 deletions(-) diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts index 75fe3ab47c..9b2d263471 100644 --- a/apps/desktop/src/main.ts +++ b/apps/desktop/src/main.ts @@ -108,6 +108,17 @@ function developmentHostInspectPort(enabled: boolean): number | undefined { return port } +/** + * Opaque chrome fallback matching the built-in sidebar palette (the resolved + * `--dsw-static-neutral-bluish-900` / `-50` tokens). An approximation for + * custom themes: Windows swaps in the renderer's measured palette over the + * windowsAppearance IPC, and macOS shows it only while minimized or hidden. + * @returns the sidebar fill hex for the active system color scheme. + */ +function chromeFallbackFill(): string { + return nativeTheme.shouldUseDarkColors ? '#1b1b1c' : '#f9fafb' +} + function createWindow(preload: string, show = false, primary = false): BrowserWindow { const window = new BrowserWindow({ width: 1280, @@ -117,7 +128,7 @@ function createWindow(preload: string, show = false, primary = false): BrowserWi show, ...(process.platform === 'win32' && primary ? { titleBarStyle: 'hidden' as const, - titleBarOverlay: { height: WINDOWS_TITLEBAR_HEIGHT, color: nativeTheme.shouldUseDarkColors ? '#1b1b1c' : '#f9fafb', + titleBarOverlay: { height: WINDOWS_TITLEBAR_HEIGHT, color: chromeFallbackFill(), symbolColor: nativeTheme.shouldUseDarkColors ? '#f9fafb' : '#0f1115' }, } : {}), // hiddenInset places traffic lights inside the sidebar; sidebar vibrancy @@ -164,7 +175,7 @@ function createWindow(preload: string, show = false, primary = false): BrowserWi if (window.isDestroyed()) return if (window.isMinimized() || !window.isVisible()) { window.setVibrancy(null) - window.setBackgroundColor(nativeTheme.shouldUseDarkColors ? '#1b1b1c' : '#f9fafb') + window.setBackgroundColor(chromeFallbackFill()) } else { window.setVibrancy('sidebar') window.setBackgroundColor('#00000000') diff --git a/apps/desktop/tests/main-startup.spec.ts b/apps/desktop/tests/main-startup.spec.ts index 8547bc28fe..13d646546f 100644 --- a/apps/desktop/tests/main-startup.spec.ts +++ b/apps/desktop/tests/main-startup.spec.ts @@ -72,13 +72,18 @@ const harness = await vi.hoisted(async () => { readonly restore = vi.fn() readonly setSize = vi.fn() readonly setTitleBarOverlay = vi.fn() + readonly setVibrancy = vi.fn() + readonly setBackgroundColor = vi.fn() constructor(readonly options: { show: boolean; modal?: boolean }) { super(); if (windowFailure !== undefined) throw windowFailure; windows.push(this) } isDestroyed() { return this.destroyed } fullscreen = false isFullScreen() { return this.fullscreen } - isMinimized() { return false } + minimized = false + isMinimized() { return this.minimized } + visible = true + isVisible() { return this.visible } isFocused() { return true } async loadURL(url: string) { this.urls.push(url) @@ -136,9 +141,10 @@ const harness = await vi.hoisted(async () => { } }), }) + const nativeTheme = { themeSource: 'system', shouldUseDarkColors: false } return { failWindow(error: Error) { windowFailure = error }, - windows, hosts, handlers, app, FakeWindow, FakeHost, powerMonitor, + windows, hosts, handlers, app, FakeWindow, FakeHost, powerMonitor, nativeTheme, menu, popup, socketHeaders: vi.fn(), updateCheck, updateDownload, updateInstall, ipcOn: vi.fn<(channel: string, listener: (event: { sender: unknown; senderFrame: unknown }, ...args: unknown[]) => void) => void>(), get updateState() { return updateState }, @@ -179,6 +185,7 @@ const harness = await vi.hoisted(async () => { updateCheck.mockReset().mockImplementation(async () => updateState) updateDownload.mockReset().mockImplementation(async () => updateState) updateInstall.mockReset().mockImplementation(async () => updateState) + nativeTheme.themeSource = 'system'; nativeTheme.shouldUseDarkColors = false preparing = deferred(); prepared = deferred(); hostStarted = deferred() navigated = deferred(); dialogShown = deferred(); quitCompleted = deferred() policyBlocked = deferred() @@ -201,7 +208,7 @@ vi.mock('electron', () => ({ BrowserWindow: harness.FakeWindow, dialog: harness.dialog, shell: { openExternal: harness.openExternal }, - nativeTheme: { themeSource: 'system' }, + nativeTheme: harness.nativeTheme, ipcMain: { on: harness.ipcOn, handle: (channel: string, handler: InvokeHandler) => { @@ -589,6 +596,48 @@ describe('desktop main startup', () => { expect(window.webContents.send.mock.calls.filter(([channel]) => channel === DESKTOP_IPC.windowFullscreen)).toHaveLength(0) }) + it('covers the macOS vibrancy reattach gap with an opaque base while minimized or hidden', async () => { + vi.spyOn(process, 'platform', 'get').mockReturnValue('darwin') + await import('../src/main.ts') + await harness.preparing.promise + const window = harness.windows[0]! + // Minimizing drops the vibrancy material and paints the theme's opaque fill. + window.minimized = true + window.emit('minimize') + expect(window.setVibrancy).toHaveBeenLastCalledWith(null) + expect(window.setBackgroundColor).toHaveBeenLastCalledWith('#f9fafb') + // Restoring re-requests the material and returns to the transparent base. + window.minimized = false + window.emit('restore') + expect(window.setVibrancy).toHaveBeenLastCalledWith('sidebar') + expect(window.setBackgroundColor).toHaveBeenLastCalledWith('#00000000') + // Hiding under the dark palette picks the dark opaque fill. + harness.nativeTheme.shouldUseDarkColors = true + window.visible = false + window.emit('hide') + expect(window.setVibrancy).toHaveBeenLastCalledWith(null) + expect(window.setBackgroundColor).toHaveBeenLastCalledWith('#1b1b1c') + window.visible = true + window.emit('show') + expect(window.setBackgroundColor).toHaveBeenLastCalledWith('#00000000') + // A destroyed window ends the backdrop updates. + const applied = window.setVibrancy.mock.calls.length + window.destroyed = true + window.emit('minimize') + expect(window.setVibrancy.mock.calls).toHaveLength(applied) + }) + + it.each(['win32', 'linux'] as const)('registers no backdrop swap on %s', async (platform) => { + vi.spyOn(process, 'platform', 'get').mockReturnValue(platform) + await import('../src/main.ts') + await harness.preparing.promise + const window = harness.windows[0]! + window.minimized = true + window.emit('minimize') + expect(window.setVibrancy).not.toHaveBeenCalled() + expect(window.setBackgroundColor).not.toHaveBeenCalled() + }) + it('follows the Windows primary document language and palette without trusting other frames', async () => { vi.spyOn(process, 'platform', 'get').mockReturnValue('win32') await import('../src/main.ts') From b4886c7e5bf3a2a12577fa6eac6725b54bca6c6d Mon Sep 17 00:00:00 2001 From: Yif <877193178@qq.com> Date: Mon, 21 Sep 2026 13:02:48 +0800 Subject: [PATCH 093/100] feat(workspace): marquee hovered session titles with fades on both cut edges --- .../tests/sidebar-title-hover-scroll.e2e.ts | 67 ++++--- .../src/client/rows/Rows.module.css | 35 ++-- .../ui-workspace/src/client/rows/Rows.tsx | 99 +++++++--- .../tests/browser-styles.client.spec.ts | 17 +- .../ui-workspace/tests/rows.client.spec.tsx | 182 ++++++++++++------ 5 files changed, 284 insertions(+), 116 deletions(-) diff --git a/apps/web/tests/sidebar-title-hover-scroll.e2e.ts b/apps/web/tests/sidebar-title-hover-scroll.e2e.ts index 2a0fe8caf4..5f797f19e2 100644 --- a/apps/web/tests/sidebar-title-hover-scroll.e2e.ts +++ b/apps/web/tests/sidebar-title-hover-scroll.e2e.ts @@ -1,9 +1,10 @@ -// Web e2e scenario: hovering a sidebar session row reveals a title wider than -// its cell. The jsdom lane pins only the scroll position the handler writes; -// the assembled browser is where the title really clips, really reaches its own -// hovered extent (the trailing relative-time cell yields to the row menu while -// the pointer rests on the row, so the hovered cell is wider than the resting -// one), and really returns to its start when the pointer leaves. +// Web e2e scenario: hovering a sidebar session row marquees a title wider than +// its cell. The jsdom lane pins only the positions the handler writes; the +// assembled browser is where the title really clips, really crawls toward its +// own hovered extent (the trailing relative-time cell yields to the row menu +// while the pointer rests on the row, so the hovered cell is wider than the +// resting one), really fades its moved left edge, and really returns to its +// start when the pointer leaves. // // Zero model calls: seeding one renamed session and hovering its row touches no // provider. @@ -16,10 +17,10 @@ import { launchWebScaffold, seedSession, watchConsole, type WebScaffold } from ' import { newEnglishPage, saveFailureShot } from './support.ts' const SEED = fileURLToPath(new URL('../../../snapshots/web/seeded-history/session.v3.jsonl', import.meta.url)) -/** Wider than the sidebar cell, under the 80-byte title limit, with a far-edge suffix the reveal must reach. */ +/** Wider than the sidebar cell, under the 80-byte title limit, with a far-edge suffix the marquee must reach. */ const TITLE = 'Forked session clipped before its suffix (1)' -describe('web e2e: hovering a clipped session title scrolls it to its far edge', () => { +describe('web e2e: hovering a clipped session title marquees it to its far edge', () => { let scaffold: WebScaffold let browser: Browser let page: Page @@ -43,7 +44,7 @@ describe('web e2e: hovering a clipped session title scrolls it to its far edge', await scaffold?.close() }) - it('reveals the clipped title under the pointer and restores its start after', async () => { + it('crawls the clipped title under the pointer and restores its start after', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-title-hover-scroll')) const row = page.getByRole('treeitem').filter({ has: page.getByText(TITLE, { exact: true }) }) await row.waitFor({ timeout: 20_000 }) @@ -53,34 +54,56 @@ describe('web e2e: hovering a clipped session title scrolls it to its far edge', expect(await title.evaluate(el => el.scrollWidth - el.clientWidth)).toBeGreaterThan(0) expect(await title.evaluate(el => getComputedStyle(el).textOverflow)).toBe('ellipsis') expect(await title.evaluate(el => el.scrollLeft)).toBe(0) - expect(await title.evaluate(el => getComputedStyle(el).scrollBehavior)).toBe('smooth') await row.hover() - // Poll against the live extent: the reveal must reach the far edge of the - // hovered cell (the wider one — the relative-time label yields to the row - // menu), whatever width the handler itself read. + // The marquee crawls instead of jumping: the title is caught mid-travel, + // strictly between its start and its far edge, with both cut edges + // publishing their fade-mask hooks. + await expect.poll( + async () => title.evaluate(el => el.scrollLeft > 0), + { timeout: 5_000 }, + ).toBe(true) + expect(await title.evaluate(el => el.scrollLeft < el.scrollWidth - el.clientWidth - 1)).toBe(true) + expect(await title.evaluate(el => el.hasAttribute('data-scrolled'))).toBe(true) + expect(await title.evaluate(el => el.hasAttribute('data-clipped'))).toBe(true) + expect(await title.evaluate(el => getComputedStyle(el).maskImage)).toContain('linear-gradient') + // The crawl still reaches the far edge of the hovered cell (the wider + // one — the relative-time label yields to the row menu) and rests there, + // lifting the right fade so the final character reads at full strength. + // The fade lifts on the frame that lands exactly on the far edge, one or + // two frames after scrollLeft first rounds within a pixel of it. await expect.poll( async () => title.evaluate(el => el.scrollLeft >= el.scrollWidth - el.clientWidth - 1), - { timeout: 10_000 }, + { timeout: 20_000 }, ).toBe(true) - // Scrolled to its end, the title must not paint the ellipsis over the - // characters the reveal reached. + await expect.poll( + async () => title.evaluate(el => el.hasAttribute('data-clipped')), + { timeout: 5_000 }, + ).toBe(false) + // At its extent, the title must not paint the ellipsis over the + // characters the marquee reached. expect(await title.evaluate(el => getComputedStyle(el).textOverflow)).toBe('clip') - // Leaving returns in one step: a smooth return would still be travelling - // inside this window, and it would carry the resting ellipsis back with it. + // Leaving returns in one step: a crawl back would still be travelling + // inside this window, and it would carry the resting ellipsis with it. await page.mouse.move(0, 0) await expect.poll( async () => title.evaluate(el => el.scrollLeft), { timeout: 150, interval: 20 }, ).toBe(0) + expect(await title.evaluate(el => el.hasAttribute('data-scrolled'))).toBe(false) expect(await title.evaluate(el => getComputedStyle(el).textOverflow)).toBe('ellipsis') - // The reduce override reaches the real stylesheet, so the reveal jumps - // instead of gliding. + // Reduced motion reaches the handler's matchMedia probe: the reveal jumps + // to the far edge instead of crawling. await page.emulateMedia({ reducedMotion: 'reduce' }) - expect(await title.evaluate(el => getComputedStyle(el).scrollBehavior)).toBe('auto') + await row.hover() + await expect.poll( + async () => title.evaluate(el => el.scrollLeft >= el.scrollWidth - el.clientWidth - 1), + { timeout: 500, interval: 20 }, + ).toBe(true) + await page.mouse.move(0, 0) await page.emulateMedia({ reducedMotion: null }) expect(tripwire.pageErrors).toEqual([]) - }, 60_000) + }, 90_000) }) diff --git a/packages/client/ui-workspace/src/client/rows/Rows.module.css b/packages/client/ui-workspace/src/client/rows/Rows.module.css index 5a643c235a..26a6af0825 100644 --- a/packages/client/ui-workspace/src/client/rows/Rows.module.css +++ b/packages/client/ui-workspace/src/client/rows/Rows.module.css @@ -182,13 +182,31 @@ outline: none; } -/* Hovering a session row reveals a title wider than its cell: Rows.tsx scrolls - it to its end while the pointer rests on the row — smoothly, through the - scroll-behavior here — and returns it to the start in one step when the - pointer leaves. */ +/* Hovering a session row marquees a title wider than its cell: Rows.tsx crawls + it at a constant speed to its far edge while the pointer rests on the row, + holds it there, and returns it to the start in one step when the pointer + leaves. The motion is scripted frame by frame (reduced motion jumps), so no + scroll-behavior applies here. */ .sessionRow .title { flex: 1; - scroll-behavior: smooth; +} + +/* While the marquee travels, both clipping edges fade in over 12px instead of + hard-cutting a character: the left once the title has moved off its start + (data-scrolled), the right while text still remains beyond the cell + (data-clipped) — at the far edge the right fade lifts so the final character + reads at full strength. The mask rides the title span itself, so the status + slot and every other leading cell keep their full color. */ +.sessionRow .title[data-scrolled] { + mask-image: linear-gradient(to right, transparent, #000 12px); +} + +.sessionRow .title[data-clipped] { + mask-image: linear-gradient(to left, transparent, #000 12px); +} + +.sessionRow .title[data-scrolled][data-clipped] { + mask-image: linear-gradient(to right, transparent, #000 12px, #000 calc(100% - 12px), transparent); } .meta { @@ -287,7 +305,7 @@ } /* The unclipped hover state drops the ellipsis, which would otherwise cover - the characters the scroll reveal reached. Guarded because a touch tap + the characters the marquee reached. Guarded because a touch tap latches `:hover` on the row after the title has already returned: an unguarded rule would strand that row without its ellipsis. */ @media (hover: hover) { @@ -418,9 +436,4 @@ animation: none; transition: none; } - - /* The title reveal jumps to the far edge instead of gliding there. */ - .sessionRow .title { - scroll-behavior: auto; - } } diff --git a/packages/client/ui-workspace/src/client/rows/Rows.tsx b/packages/client/ui-workspace/src/client/rows/Rows.tsx index ee35919e1f..a3cfa707de 100644 --- a/packages/client/ui-workspace/src/client/rows/Rows.tsx +++ b/packages/client/ui-workspace/src/client/rows/Rows.tsx @@ -2,7 +2,7 @@ * Workspace browser tree row components (figma Cell set 14:3080): pure presentational — * all data and callbacks arrive via props. Hover swaps (folder->chevron, * time->ellipsis, action buttons) are CSS-only, and a session row's clipped - * title is scrolled programmatically while the row is hovered. Workspace row + * title marquees programmatically while the row is hovered. Workspace row * menus are visual-only except Rename/Delete. A Session row's "..." menu and * its hover buttons are the `sidebar.workspaces.session.menu.item` and * `sidebar.workspaces.session.row.action` lists, rendered through the @@ -11,6 +11,7 @@ * session and workspace hover cards are suppressed while a menu is open. */ import { useEffect, useMemo, useRef, useState } from 'react' +import type { RefObject } from 'react' import clsx from 'clsx' import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots' import { @@ -37,31 +38,84 @@ function displayTitle(node: SessionNode, t: RowTranslate): string { accidental jitter, so the title stays put. */ const MIN_TITLE_REVEAL_PX = 8 +/* Marquee travel speed: slow enough to read the text as it passes. */ +const TITLE_MARQUEE_PX_PER_MS = 0.03 + /** - * Reveal a title wider than its one-line cell while its row is hovered: the - * title clips its own text, so the far edge (a fork's incremented title, for - * example) is reachable by scrolling the element to its end. Overflow of at - * most {@link MIN_TITLE_REVEAL_PX} stays put — a barely-clipped title moving a - * few pixels reads as jitter, not a reveal. Leaving returns the title to the - * start in one step, because the resting ellipsis and the narrowed cell would - * otherwise meet the text while it travelled back. The stylesheet decides - * whether either move glides or jumps. + * Place the title's scroll position and publish the stylesheet's fade-mask + * hooks: `data-scrolled` while the title has left its start (left fade) and + * `data-clipped` while text remains beyond the right edge (right fade). * @param title - the row's clipping title element. - * @param revealed - whether the pointer is on the row. + * @param left - scroll offset in CSS pixels. + * @param range - the title's maximum scroll offset in CSS pixels. */ -function revealClippedTitle(title: HTMLSpanElement | null, revealed: boolean): void { - /* v8 ignore next -- defensive: the title span renders unconditionally. */ - if (title === null) return - if (revealed) { - const range = title.scrollWidth - title.clientWidth - if (range <= MIN_TITLE_REVEAL_PX) return - title.scrollLeft = range - return - } +function placeTitle(title: HTMLSpanElement, left: number, range: number): void { // jsdom implements no scrollTo; the lane's direct assignment is instant there - // anyway, so both paths land on the same resting position. + // anyway, so both paths land on the same position. + if (typeof title.scrollTo === 'function') title.scrollTo({ left, behavior: 'instant' }) + else title.scrollLeft = left + if (left > 0) title.dataset.scrolled = '' + else delete title.dataset.scrolled + if (left < range) title.dataset.clipped = '' + else delete title.dataset.clipped +} + +/** + * Return the title to its resting state: scrolled to the start with both fade + * masks off, so the resting ellipsis renders at full strength. + * @param title - the row's clipping title element. + */ +function restTitle(title: HTMLSpanElement): void { if (typeof title.scrollTo === 'function') title.scrollTo({ left: 0, behavior: 'instant' }) else title.scrollLeft = 0 + delete title.dataset.scrolled + delete title.dataset.clipped +} + +/** + * Marquee a title wider than its one-line cell while its row is hovered: the + * title clips its own text, so entering crawls it at a constant speed until the + * far edge (a fork's incremented title, for example) is in view, then rests + * there under the pointer. Overflow of at most {@link MIN_TITLE_REVEAL_PX} + * stays put — a barely-clipped title moving a few pixels reads as jitter, not a + * reveal. Leaving returns the title to the start in one step, because the + * resting ellipsis and the narrowed cell would otherwise meet the text while it + * travelled back. Reduced motion jumps to the far edge instead of crawling. + * @param title - ref to the row's clipping title element. + * @returns stable pointer enter/leave handlers for the row. + */ +function useTitleMarquee(title: RefObject): { enter: () => void; leave: () => void } { + const frame = useRef(0) + useEffect(() => () => { cancelAnimationFrame(frame.current) }, []) + return useMemo(() => ({ + enter: (): void => { + /* v8 ignore next -- defensive: the title span renders unconditionally. */ + if (title.current === null) return + const element = title.current + const range = element.scrollWidth - element.clientWidth + if (range <= MIN_TITLE_REVEAL_PX) return + if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) { + placeTitle(element, range, range) + return + } + cancelAnimationFrame(frame.current) + let previous: number | undefined + let position = 0 + const step = (now: DOMHighResTimeStamp): void => { + position += previous === undefined ? 0 : (now - previous) * TITLE_MARQUEE_PX_PER_MS + previous = now + placeTitle(element, Math.min(position, range), range) + if (position < range) frame.current = requestAnimationFrame(step) + } + frame.current = requestAnimationFrame(step) + }, + leave: (): void => { + cancelAnimationFrame(frame.current) + /* v8 ignore next -- defensive: the title span renders unconditionally. */ + if (title.current === null) return + restTitle(title.current) + }, + }), [title]) } /** Localized compact relative time ("刚刚"/"5分钟" in zh, "now"/"5min" in en). */ @@ -504,6 +558,7 @@ export function SessionNodeItem({ const menuOpenState = useMemo((): MenuOpenState => [menuOpen, setMenuOpen], [menuOpen]) const rowRef = useRef(null) const titleRef = useRef(null) + const marquee = useTitleMarquee(titleRef) useEffect(() => { if (onReveal === undefined) return rowRef.current?.scrollIntoView({ block: 'nearest' }) @@ -524,8 +579,8 @@ export function SessionNodeItem({ aria-selected={selected} aria-description={row.archived ? t('toast.archivedNotOpenable') : undefined} onClick={() => { onOpen(node.id) }} - onPointerEnter={() => { revealClippedTitle(titleRef.current, true) }} - onPointerLeave={() => { revealClippedTitle(titleRef.current, false) }} + onPointerEnter={marquee.enter} + onPointerLeave={marquee.leave} draggable={draggable} onDragStart={!draggable ? undefined diff --git a/packages/client/ui-workspace/tests/browser-styles.client.spec.ts b/packages/client/ui-workspace/tests/browser-styles.client.spec.ts index 38d4ee36a3..bf4191366b 100644 --- a/packages/client/ui-workspace/tests/browser-styles.client.spec.ts +++ b/packages/client/ui-workspace/tests/browser-styles.client.spec.ts @@ -108,13 +108,20 @@ describe('WorkspaceBrowser.module.css list', () => { .toBe('var(--dsw-alias-interactive-bg-hover)') }) - it('reveals a clipped session title by scrolling it on row hover', () => { - // Smooth versus reduced motion is pinned as a computed style in - // apps/web/tests/sidebar-title-hover-scroll.e2e.ts: this helper merges - // same-selector rules across media queries, so the reduce override would - // mask the smooth declaration here. + it('marquees a clipped session title on row hover', () => { + // The crawl itself is scripted in Rows.tsx frame by frame, so the title + // declares no scroll-behavior; the stylesheet keeps the hovered cell + // unclipped and fades whichever edges cut text mid-travel, on the title + // span itself so the status slot beside it keeps its full color. expect(rowDeclarations('.sessionRow .title')?.get('flex')).toBe('1') + expect(rowDeclarations('.sessionRow .title')?.get('scroll-behavior')).toBeUndefined() expect(rowDeclarations('.sessionRow:hover .title')?.get('text-overflow')).toBe('clip') + expect(rowDeclarations('.sessionRow .title[data-scrolled]')?.get('mask-image')) + .toBe('linear-gradient(to right, transparent, #000 12px)') + expect(rowDeclarations('.sessionRow .title[data-clipped]')?.get('mask-image')) + .toBe('linear-gradient(to left, transparent, #000 12px)') + expect(rowDeclarations('.sessionRow .title[data-scrolled][data-clipped]')?.get('mask-image')) + .toBe('linear-gradient(to right, transparent, #000 12px, #000 calc(100% - 12px), transparent)') }) it('pins both rail controls to the shared left anchor during the column slide', () => { diff --git a/packages/client/ui-workspace/tests/rows.client.spec.tsx b/packages/client/ui-workspace/tests/rows.client.spec.tsx index f41199824f..41e1b6e037 100644 --- a/packages/client/ui-workspace/tests/rows.client.spec.tsx +++ b/packages/client/ui-workspace/tests/rows.client.spec.tsx @@ -208,66 +208,136 @@ describe('workspace browser rows', () => { expect(onOpen).toHaveBeenCalledWith(node.id) }) - it('reveals a clipped session title by scrolling it while the row is hovered', () => { - const node: SessionNode = { - id: sid('clipped'), title: 'A Session Title Long Enough To Be Clipped (1)', blank: false, - running: false, runningSubagentCount: 0, completed: false, hasActiveSchedule: false, updatedAt: 0, - pinned: false, archived: false, + it('marquees a clipped session title at a constant speed while the row is hovered', () => { + vi.useFakeTimers() + // jsdom implements no matchMedia; the stub answers the reduced-motion probe. + vi.stubGlobal('matchMedia', vi.fn(() => ({ matches: false }))) + try { + const node: SessionNode = { + id: sid('clipped'), title: 'A Session Title Long Enough To Be Clipped (1)', blank: false, + running: false, runningSubagentCount: 0, completed: false, hasActiveSchedule: false, updatedAt: 0, + pinned: false, archived: false, + } + render( + , + ) + const row = screen.getByRole('treeitem') + const title = screen.getByText(node.title) + // jsdom lays out nothing: the title's clipped geometry is stated outright. + const geometry = (scrollWidth: number, clientWidth: number): void => { + Object.defineProperty(title, 'scrollWidth', { value: scrollWidth, configurable: true }) + Object.defineProperty(title, 'clientWidth', { value: clientWidth, configurable: true }) + } + + geometry(320, 180) + fireEvent.pointerEnter(row) + // The first frame only records the clock; travel begins on the second. + vi.advanceTimersByTime(16) + expect(title.scrollLeft).toBe(0) + expect(title.hasAttribute('data-scrolled')).toBe(false) + expect(title.hasAttribute('data-clipped')).toBe(true) + // Constant 30px/s: 1600ms of frames crawl 48px, and the moved title + // publishes both fade-mask hooks — off its start, short of its far edge. + vi.advanceTimersByTime(1600) + expect(title.scrollLeft).toBeCloseTo(48, 5) + expect(title.hasAttribute('data-scrolled')).toBe(true) + expect(title.hasAttribute('data-clipped')).toBe(true) + // The crawl clamps at the far edge and rests there under the pointer; + // the right fade lifts so the final character reads at full strength. + vi.advanceTimersByTime(10_000) + expect(title.scrollLeft).toBe(140) + expect(title.hasAttribute('data-clipped')).toBe(false) + fireEvent.pointerLeave(row) + expect(title.scrollLeft).toBe(0) + expect(title.hasAttribute('data-scrolled')).toBe(false) + expect(title.hasAttribute('data-clipped')).toBe(false) + + // A title that fits has no scroll range: hovering leaves it at its start. + geometry(180, 180) + fireEvent.pointerEnter(row) + vi.advanceTimersByTime(1000) + expect(title.scrollLeft).toBe(0) + fireEvent.pointerLeave(row) + + // Overflow at the 8px jitter threshold also stays put. + geometry(188, 180) + fireEvent.pointerEnter(row) + vi.advanceTimersByTime(1000) + expect(title.scrollLeft).toBe(0) + fireEvent.pointerLeave(row) + + // One pixel past the threshold crawls to its 9px extent. + geometry(189, 180) + fireEvent.pointerEnter(row) + vi.advanceTimersByTime(1000) + expect(title.scrollLeft).toBe(9) + } finally { + vi.useRealTimers() + vi.unstubAllGlobals() } - render( - , - ) - const row = screen.getByRole('treeitem') - const title = screen.getByText(node.title) - // jsdom lays out nothing: the title's clipped geometry is stated outright. - const geometry = (scrollWidth: number, clientWidth: number): void => { - Object.defineProperty(title, 'scrollWidth', { value: scrollWidth, configurable: true }) - Object.defineProperty(title, 'clientWidth', { value: clientWidth, configurable: true }) - } - - geometry(320, 180) - fireEvent.pointerEnter(row) - expect(title.scrollLeft).toBe(140) - fireEvent.pointerLeave(row) - expect(title.scrollLeft).toBe(0) - - // A title that fits has no scroll range: hovering leaves it at its start. - geometry(180, 180) - fireEvent.pointerEnter(row) - expect(title.scrollLeft).toBe(0) - fireEvent.pointerLeave(row) - - // Overflow at the 8px jitter threshold also stays put. - geometry(188, 180) - fireEvent.pointerEnter(row) - expect(title.scrollLeft).toBe(0) - fireEvent.pointerLeave(row) - - // One pixel past the threshold reveals. - geometry(189, 180) - fireEvent.pointerEnter(row) - expect(title.scrollLeft).toBe(9) }) - it('returns a revealed title to its start in one step', () => { - const node: SessionNode = { - id: sid('instant-return'), title: 'A Session Title Long Enough To Be Clipped (1)', blank: false, - running: false, runningSubagentCount: 0, completed: false, hasActiveSchedule: false, updatedAt: 0, - pinned: false, archived: false, - } - render( - , - ) - const row = screen.getByRole('treeitem') - const title = screen.getByText(node.title) - const scrollTo = vi.fn() - Object.defineProperty(title, 'scrollTo', { value: scrollTo, configurable: true }) + it('jumps a clipped title to its far edge under reduced motion', () => { + vi.stubGlobal('matchMedia', vi.fn((query: string) => ({ matches: query === '(prefers-reduced-motion: reduce)' }))) + try { + const node: SessionNode = { + id: sid('reduced-motion'), title: 'A Session Title Long Enough To Be Clipped (1)', blank: false, + running: false, runningSubagentCount: 0, completed: false, hasActiveSchedule: false, updatedAt: 0, + pinned: false, archived: false, + } + render( + , + ) + const row = screen.getByRole('treeitem') + const title = screen.getByText(node.title) + Object.defineProperty(title, 'scrollWidth', { value: 320, configurable: true }) + Object.defineProperty(title, 'clientWidth', { value: 180, configurable: true }) - fireEvent.pointerEnter(row) - fireEvent.pointerLeave(row) - // Browsers receive the explicit instant behavior that the stylesheet's - // smooth scroll-behavior would otherwise override. - expect(scrollTo).toHaveBeenCalledWith({ left: 0, behavior: 'instant' }) + fireEvent.pointerEnter(row) + expect(title.scrollLeft).toBe(140) + expect(title.hasAttribute('data-scrolled')).toBe(true) + expect(title.hasAttribute('data-clipped')).toBe(false) + fireEvent.pointerLeave(row) + expect(title.scrollLeft).toBe(0) + expect(title.hasAttribute('data-scrolled')).toBe(false) + } finally { + vi.unstubAllGlobals() + } + }) + + it('returns a marqueed title to its start in one step and cancels the crawl', () => { + vi.useFakeTimers() + vi.stubGlobal('matchMedia', vi.fn(() => ({ matches: false }))) + try { + const node: SessionNode = { + id: sid('instant-return'), title: 'A Session Title Long Enough To Be Clipped (1)', blank: false, + running: false, runningSubagentCount: 0, completed: false, hasActiveSchedule: false, updatedAt: 0, + pinned: false, archived: false, + } + render( + , + ) + const row = screen.getByRole('treeitem') + const title = screen.getByText(node.title) + Object.defineProperty(title, 'scrollWidth', { value: 320, configurable: true }) + Object.defineProperty(title, 'clientWidth', { value: 180, configurable: true }) + const scrollTo = vi.fn() + Object.defineProperty(title, 'scrollTo', { value: scrollTo, configurable: true }) + + fireEvent.pointerEnter(row) + vi.advanceTimersByTime(160) + fireEvent.pointerLeave(row) + // Browsers receive the explicit instant behavior so mid-crawl positions + // never ease; the return is one step. + expect(scrollTo).toHaveBeenLastCalledWith({ left: 0, behavior: 'instant' }) + // Leaving cancels the crawl rather than letting it finish under the mask. + const settled = scrollTo.mock.calls.length + vi.advanceTimersByTime(1000) + expect(scrollTo.mock.calls.length).toBe(settled) + } finally { + vi.useRealTimers() + vi.unstubAllGlobals() + } }) it('keeps the active-Schedule marker between the title and time in grouped and flat rows', () => { From 4aba48ec03134c9dce78d9262263189b5a748244 Mon Sep 17 00:00:00 2001 From: Turtle Date: Mon, 21 Sep 2026 13:55:09 +0800 Subject: [PATCH 094/100] fix(cordis): register Host inspect providers once per process (#4742) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `tool-cordis` registered the four first-party Host inspect providers from every preset row that mounted it. The Host registry rejects a duplicate provider id, so a second preset carrying `tool-cordis` — or a user preset copied from a shipped one — failed to mount in the same process. - Add `@deepseek-ai/dsh-tool-cordis/host` (`cordis-inspect-providers`), the host-plane row that registers the providers; the Web host composition mounts it beside `cordis-host-runner`. The per-session `tool-cordis` row now only registers the tools and its prompt section. - Gate the `cordis` preset's `tool-plugin-manager` row on `profileContext`, the same condition `dsh-base` applies to the host `plugin-manager` service, so a profile-less embedding still mounts the preset. --- .../tests/profiles/headless/tests/ptc.e2e.ts | 2 + apps/cli/tests/web-agent-presets.e2e.ts | 76 ++++++++++++++++++- packages/bundle/web-app/cordis.patch.yml | 6 ++ packages/bundle/web-app/package.json | 1 + .../extensions/tool-cordis/README.i18n.yaml | 4 +- packages/extensions/tool-cordis/README.md | 4 +- packages/extensions/tool-cordis/README.zh.md | 4 +- packages/extensions/tool-cordis/package.json | 6 ++ packages/extensions/tool-cordis/src/host.ts | 20 +++++ packages/extensions/tool-cordis/src/index.ts | 7 +- .../extensions/tool-cordis/tests/host.spec.ts | 35 +++++++++ .../presets/cordis/agent.cordis.yml | 3 + .../agent-presets/tests/shipped-root.spec.ts | 14 ++++ pnpm-lock.yaml | 6 ++ .../cordis-inspect-jsdoc/cordis.snapshot.yml | 2 + .../session/cordis-inspect-jsdoc/cordis.yml | 2 + tsconfig.base.json | 1 + 17 files changed, 181 insertions(+), 12 deletions(-) create mode 100644 packages/extensions/tool-cordis/src/host.ts create mode 100644 packages/extensions/tool-cordis/tests/host.spec.ts diff --git a/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts b/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts index 7aac156cd8..4e0fc43235 100644 --- a/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts +++ b/apps/cli/tests/profiles/headless/tests/ptc.e2e.ts @@ -28,6 +28,7 @@ import LocalJobRegistry from '@deepseek-ai/dsh-jobs-local' import * as ToolJobs from '@deepseek-ai/dsh-tool-jobs' import CordisHostRunner from '@deepseek-ai/dsh-cordis-host-runner' import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis' +import * as CordisInspectProviders from '@deepseek-ai/dsh-tool-cordis/host' /** * With-key PTC mode proof: a real model receives only `run_code`, composes two @@ -280,6 +281,7 @@ describe('PTC mode typed values: keyless real-process contracts', () => { it('uses runtime inspection results directly through PTC', async () => { ctx = await typedPtcModeHarness() await ctx.plugin(CordisHostRunner) + await ctx.plugin(CordisInspectProviders) await ctx.plugin(ToolCordis) const agent = { id: SessionId('ptc-cordis'), diff --git a/apps/cli/tests/web-agent-presets.e2e.ts b/apps/cli/tests/web-agent-presets.e2e.ts index 1122a1c36e..0434078f16 100644 --- a/apps/cli/tests/web-agent-presets.e2e.ts +++ b/apps/cli/tests/web-agent-presets.e2e.ts @@ -1,5 +1,5 @@ import { randomUUID } from 'node:crypto' -import { mkdir, mkdtemp, readFile, stat, symlink, writeFile } from 'node:fs/promises' +import { cp, mkdir, mkdtemp, readFile, rm, stat, symlink, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { fileURLToPath } from 'node:url' import { dirname, join } from 'node:path' @@ -668,6 +668,80 @@ describe('product Bundle and user-preset intersection', () => { }, 120_000) }) +describe('a user preset copied from a shipped one', () => { + /** The JSON text a `cordis_inspect_*` result renders. */ + function resultText(result: { content: ReadonlyArray<{ type: string; text?: string }> }): string { + return result.content.filter(part => part.type === 'text').map(part => part.text ?? '').join('') + } + + it('mounts beside the shipped `cordis` preset and reads the shared Host inspect providers', async () => { + // The Host inspect providers are one process-global set registered by the + // host composition (`@deepseek-ai/dsh-tool-cordis/host`); each preset's + // `tool-cordis` row only registers the tools. Before that split the copy + // failed to mount: its row re-registered provider "Service". + const root = await mkdtemp(join(tmpdir(), 'dsh-copied-preset-')) + const userRoot = join(root, 'presets') + await cp(join(SHIPPED_PRESET_ROOT, 'cordis'), join(userRoot, 'cordis-copy'), { recursive: true }) + const settingsFile = join(root, 'settings.yaml') + await writeFile(settingsFile, '{}\n') + const copyCtx = await bootWeb(settingsFile, [{ + id: 'agent-presets', + config: { default: 'standard', roots: [{ path: userRoot, trust: 'user' }], includeUserRoot: false }, + }]) + try { + const shipped = await copyCtx.agents.create({ + sessionId: SessionId(`preset-cordis-shipped-${randomUUID()}`), + setup: agentCtx => copyCtx.agentPresets.mount(agentCtx, 'cordis').then(() => undefined), + }) + const copied = await copyCtx.agents.create({ + sessionId: SessionId(`preset-cordis-copy-${randomUUID()}`), + setup: agentCtx => copyCtx.agentPresets.mount(agentCtx, 'cordis-copy').then(() => undefined), + }) + try { + for (const handle of [shipped, copied]) { + expect(toolNames(copyCtx, handle.agent)).toEqual(expect.arrayContaining([ + 'cordis_inspect_list', 'cordis_inspect_query', 'plugin_manager', + ])) + } + const signal = new AbortController().signal + const listed = await copyCtx.tools.execute({ + callId: ToolCallId('copied-preset-inspect-list'), + name: 'cordis_inspect_list', + arguments: {}, + signal, + agent: copied.agent, + }) + expect(listed.isError).toBe(false) + const providers = (JSON.parse(resultText(listed)) as { providers: Array<{ id: string; platform: string }> }).providers + expect(providers.filter(provider => provider.platform === 'host').map(provider => provider.id)) + .toEqual(['Service', 'Event', 'Builtin', 'Tool']) + + // The `Tool` provider is the one built over the host context: it + // answers with the shared registry's view of the REQUESTING agent, + // so the copy sees its own preset's tools, not the host's empty set. + const queried = await copyCtx.tools.execute({ + callId: ToolCallId('copied-preset-inspect-tools'), + name: 'cordis_inspect_query', + arguments: { platform: 'host', provider: 'Tool', method: 'listTools' }, + signal, + agent: copied.agent, + }) + expect(queried.isError).toBe(false) + const tools = (JSON.parse(resultText(queried)) as { data: { tools: Array<{ name: string }> } }).data.tools + expect(tools.map(tool => tool.name)).toEqual(expect.arrayContaining([ + 'bash', 'cordis_inspect_list', 'cordis_inspect_query', 'plugin_manager', + ])) + } finally { + await copied.dispose() + await shipped.dispose() + } + } finally { + await copyCtx.fiber.dispose() + await rm(root, { recursive: true, force: true }) + } + }, 120_000) +}) + describe('a switch survives the session', () => { it('records the choice so the log states what the agent runs', async () => { const handle = await ctx.agents.create({ diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml index 4a055c8fd5..b069c9bba2 100644 --- a/packages/bundle/web-app/cordis.patch.yml +++ b/packages/bundle/web-app/cordis.patch.yml @@ -125,6 +125,12 @@ - id: cordis-host-runner name: '@deepseek-ai/dsh-cordis-host-runner' + # The Host inspect providers are process-global: the registry rejects a + # duplicate id, so they register here once and every preset's `tool-cordis` + # row reads them. + - id: cordis-inspect-providers + name: '@deepseek-ai/dsh-tool-cordis/host' + # Ordinary provider for the parsed Web flags. Its plugin-level injection # waits for cmdlineArgs; no launcher metadata or special row kind is needed. - id: web-startup diff --git a/packages/bundle/web-app/package.json b/packages/bundle/web-app/package.json index f40797d498..049587c941 100644 --- a/packages/bundle/web-app/package.json +++ b/packages/bundle/web-app/package.json @@ -116,6 +116,7 @@ "@deepseek-ai/dsh-session-stats": "workspace:^", "@deepseek-ai/dsh-session-turn-outline": "workspace:^", "@deepseek-ai/dsh-subprocess": "workspace:^", + "@deepseek-ai/dsh-tool-cordis": "workspace:^", "@deepseek-ai/dsh-tool-subagent": "workspace:^", "@deepseek-ai/dsh-web-frontend": "workspace:^", "@deepseek-ai/dsh-workspace": "workspace:^", diff --git a/packages/extensions/tool-cordis/README.i18n.yaml b/packages/extensions/tool-cordis/README.i18n.yaml index c149c628cd..3f3feb821d 100644 --- a/packages/extensions/tool-cordis/README.i18n.yaml +++ b/packages/extensions/tool-cordis/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/extensions/tool-cordis/README.md -README.md: 3536ae2fc39f7a8db425da89df3f4d93e1ca8b4f -README.zh.md: 8127683111f1807b6920d6bb6f56479e1495f281 +README.md: 4e7efefd21e3b7cf40e8ba5fe2291d220dfd796f +README.zh.md: 76331c25f0996c053b39e5b227a50afae84e6bb4 diff --git a/packages/extensions/tool-cordis/README.md b/packages/extensions/tool-cordis/README.md index 3536ae2fc3..4e7efefd21 100644 --- a/packages/extensions/tool-cordis/README.md +++ b/packages/extensions/tool-cordis/README.md @@ -25,7 +25,7 @@ Inspect Host and Client runtime APIs before writing plugin code. Creator mode pr ## Use this package -Creator mode includes this toolset. Other compositions mount `@deepseek-ai/dsh-tool-cordis` alongside the host runner that provides `cordisInspect`. Call `cordis_inspect_list` to discover providers, then `cordis_inspect_query` for a provider's exact methods and types. Use [Plugin Manager](../../boot/plugin-manager/README.md) to install bundles containing plugin code or MCP configuration. +Creator mode includes this toolset. Other compositions mount `@deepseek-ai/dsh-tool-cordis/host` once in the host composition beside the host runner that provides `cordisInspect`, and `@deepseek-ai/dsh-tool-cordis` in each agent preset that exposes the tools; a preset row alone registers no Host providers. Call `cordis_inspect_list` to discover providers, then `cordis_inspect_query` for a provider's exact methods and types. Use [Plugin Manager](../../boot/plugin-manager/README.md) to install bundles containing plugin code or MCP configuration. ----- @@ -35,7 +35,7 @@ Creator mode includes this toolset. Other compositions mount `@deepseek-ai/dsh-t
    Implementation internals — click to expand -Host providers combine generated Service/Event catalogs and the requesting agent's tool registry. Client providers synchronize their manifests through the existing inspection registry and answer queries from a connected page. The tool plugin owns its registrations through Cordis effects; disposal removes the two tools and the Host inspect providers. No invariant companion is published because inspection reads its providers directly and maintains no independent runtime projection. +Host providers combine generated Service/Event catalogs and the requesting agent's tool registry. Client providers synchronize their manifests through the existing inspection registry and answer queries from a connected page. The host entry owns the Host provider registrations and the preset row owns the two tools, each through Cordis effects; the registry rejects a duplicate provider id, which is why the providers register once per process rather than per preset. No invariant companion is published because inspection reads its providers directly and maintains no independent runtime projection.
    diff --git a/packages/extensions/tool-cordis/README.zh.md b/packages/extensions/tool-cordis/README.zh.md index 8127683111..76331c25f0 100644 --- a/packages/extensions/tool-cordis/README.zh.md +++ b/packages/extensions/tool-cordis/README.zh.md @@ -25,7 +25,7 @@ kind: "package-reference" ## 使用本包 -创造模式包含这组工具。其他组合需要同时挂载 `@deepseek-ai/dsh-tool-cordis` 和提供 `cordisInspect` 的 host runner。调用 `cordis_inspect_list` 发现 provider,再用 `cordis_inspect_query` 查询其具体方法和类型。通过 [Plugin Manager](../../boot/plugin-manager/README.zh.md) 安装包含插件代码或 MCP 配置的组合包。 +创造模式包含这组工具。其他组合需要在宿主组合里、提供 `cordisInspect` 的 host runner 旁挂载一次 `@deepseek-ai/dsh-tool-cordis/host`,并在每个要暴露这些工具的 agent preset 里挂载 `@deepseek-ai/dsh-tool-cordis`;仅有 preset 行不会注册任何 Host provider。调用 `cordis_inspect_list` 发现 provider,再用 `cordis_inspect_query` 查询其具体方法和类型。通过 [Plugin Manager](../../boot/plugin-manager/README.zh.md) 安装包含插件代码或 MCP 配置的组合包。 ----- @@ -35,7 +35,7 @@ kind: "package-reference"
    实现细节 — 点击展开 -Host provider 结合生成的 Service/Event 目录与请求 agent 的工具注册表。Client provider 通过现有检查注册表同步清单,并从已连接页面回答查询。工具插件通过 Cordis effect 持有注册;释放时移除两个工具和 Host inspect provider。检查直接读取 provider,不维护独立运行时投影,因此不发布不变式配套插件。 +Host provider 结合生成的 Service/Event 目录与请求 agent 的工具注册表。Client provider 通过现有检查注册表同步清单,并从已连接页面回答查询。宿主入口持有 Host provider 的注册,preset 行持有两个工具,都通过 Cordis effect;注册表拒绝重复的 provider id,所以 provider 按进程注册一次而不是按 preset 注册。检查直接读取 provider,不维护独立运行时投影,因此不发布不变式配套插件。
    diff --git a/packages/extensions/tool-cordis/package.json b/packages/extensions/tool-cordis/package.json index 883eac2792..b844de74e3 100644 --- a/packages/extensions/tool-cordis/package.json +++ b/packages/extensions/tool-cordis/package.json @@ -18,11 +18,16 @@ "types": "./lib/types/index.d.ts", "default": "./lib/index.js" }, + "./host": { + "types": "./lib/types/host.d.ts", + "default": "./lib/types/host.js" + }, "./src/*": "./src/*", "./package.json": "./package.json" }, "files": [ "lib/index.js", + "lib/types/**/*.js", "lib/types/**/*.d.ts" ], "license": "MIT", @@ -36,6 +41,7 @@ "@deepseek-ai/cordis-plugin-loader": "workspace:^", "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-cordis-host-runner": "workspace:^", + "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", "@deepseek-ai/cordis": "workspace:^" } diff --git a/packages/extensions/tool-cordis/src/host.ts b/packages/extensions/tool-cordis/src/host.ts new file mode 100644 index 0000000000..d3c024f77e --- /dev/null +++ b/packages/extensions/tool-cordis/src/host.ts @@ -0,0 +1,20 @@ +/** Host-plane registration of the first-party Cordis inspect providers. */ +import type { Context } from '@deepseek-ai/cordis' +import { hostInspectProviders } from './providers.ts' + +export const name = 'cordis-inspect-providers' +/** Required services: the Host inspect registry and the Tool registry the `Tool` provider reads. */ +export const inject = ['cordisInspect', 'tools'] + +/** + * Register the Host inspect providers once per process. The registry keys + * providers by id and rejects a duplicate, so this row belongs to the host + * composition beside `cordis-host-runner`; every per-session `tool-cordis` + * row reads the shared set through its tools. + * @param ctx Host composition context. + */ +export function apply(ctx: Context): void { + for (const provider of hostInspectProviders(ctx)) { + ctx.effect(() => ctx.cordisInspect.register(provider), `cordis-inspect-providers: ${provider.manifest.id}`) + } +} diff --git a/packages/extensions/tool-cordis/src/index.ts b/packages/extensions/tool-cordis/src/index.ts index 4bbf72fe83..d52ed7a076 100644 --- a/packages/extensions/tool-cordis/src/index.ts +++ b/packages/extensions/tool-cordis/src/index.ts @@ -5,7 +5,6 @@ import type { JsonValue } from '@deepseek-ai/dsh-util-values' import { defineTool } from '@deepseek-ai/dsh-tools' import type { ToolExecution } from '@deepseek-ai/dsh-tools' import { presentInspectListCall, presentInspectQueryCall } from './present.ts' -import { hostInspectProviders } from './providers.ts' export const name = 'tool-cordis' export const inject = ['tools', 'cordisInspect'] @@ -15,13 +14,11 @@ function requireAgent(exec: ToolExecution): Agent { return exec.agent } -/** Register read-only runtime inspection tools. +/** Register read-only runtime inspection tools over the Host providers that + * `@deepseek-ai/dsh-tool-cordis/host` registers once per process. * @param ctx Agent-scoped registration context. */ export function apply(ctx: Context): void { - for (const provider of hostInspectProviders(ctx)) { - ctx.effect(() => ctx.cordisInspect.register(provider), `tool-cordis: inspect ${provider.manifest.id}`) - } ctx.tools.register(defineTool({ name: 'cordis_inspect_list', description: diff --git a/packages/extensions/tool-cordis/tests/host.spec.ts b/packages/extensions/tool-cordis/tests/host.spec.ts new file mode 100644 index 0000000000..8763e44c44 --- /dev/null +++ b/packages/extensions/tool-cordis/tests/host.spec.ts @@ -0,0 +1,35 @@ +import { Context } from '@deepseek-ai/cordis' +import { CordisInspectRegistryService } from '@deepseek-ai/dsh-cordis-host-runner' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import { describe, expect, it } from 'vitest' +import * as CordisInspectProviders from '../src/host.ts' + +/** + * The Host inspect providers are one process-global set: the host entry + * registers them beside the registry, and the per-session tool rows only read + * them. Mounting several presets that carry `tool-cordis` over the shared + * registry is covered by `apps/cli/tests/web-agent-presets.e2e.ts`. + */ + +async function host(): Promise { + const ctx = new Context() + // The tool registry injects `systemPrompt`; nothing under test registers a prompt section. + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(CordisInspectRegistryService) + return ctx +} + +describe('the cordis-inspect-providers host entry', () => { + it('registers the first-party Host providers and withdraws them on disposal', async () => { + const ctx = await host() + const fiber = ctx.plugin(CordisInspectProviders) + await fiber + + expect(ctx.cordisInspect.list().map(provider => provider.id)).toEqual(['Service', 'Event', 'Builtin', 'Tool']) + + await fiber.dispose() + expect(ctx.cordisInspect.list()).toEqual([]) + }) +}) diff --git a/packages/preset/agent-presets/presets/cordis/agent.cordis.yml b/packages/preset/agent-presets/presets/cordis/agent.cordis.yml index 5cb8b059f5..c0a5ab802a 100644 --- a/packages/preset/agent-presets/presets/cordis/agent.cordis.yml +++ b/packages/preset/agent-presets/presets/cordis/agent.cordis.yml @@ -263,5 +263,8 @@ - id: present name: '@deepseek-ai/dsh-tool-present' +# Enabled exactly when the host `plugin-manager` service is (`dsh-base` gates +# it on a launched profile), so a profile-less embedding still mounts the preset. - id: tool-plugin-manager name: '@deepseek-ai/dsh-plugin-manager/tools' + disabled: !!js "!ctx.get('profileContext')" diff --git a/packages/preset/agent-presets/tests/shipped-root.spec.ts b/packages/preset/agent-presets/tests/shipped-root.spec.ts index 8ae0d8a261..1882d0d5b7 100644 --- a/packages/preset/agent-presets/tests/shipped-root.spec.ts +++ b/packages/preset/agent-presets/tests/shipped-root.spec.ts @@ -16,6 +16,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url' import { Context } from '@deepseek-ai/cordis' import Loader from '@deepseek-ai/cordis-plugin-loader' import Include, { entryListSchema } from '@deepseek-ai/cordis-plugin-include' +import { evaluate, isJsExpr } from '@deepseek-ai/cordis-plugin-loader' import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection' import * as yaml from 'js-yaml' import { afterEach, beforeEach, describe, expect, it } from 'vitest' @@ -153,6 +154,19 @@ describe('the shipped preset root', () => { } }) + it('enables the cordis plugin-manager tool exactly when a launched profile provides profileContext', async () => { + // Same condition as the host `plugin-manager` row in `dsh-base`: the tool + // injects `pluginManager`, so without that service the row must be + // disabled rather than left waiting and blocking the whole mount. + const disabled = findEntry(await shippedEntries('cordis'), 'tool-plugin-manager')?.disabled + if (!isJsExpr(disabled)) throw new TypeError('cordis tool-plugin-manager must gate on a !!js expression') + const scope = (profileContext: object | undefined) => ({ + ctx: { get: (name: string) => (name === 'profileContext' ? profileContext : undefined) }, + }) + expect(evaluate(scope(undefined), disabled.__jsExpr)).toBe(true) + expect(evaluate(scope({ name: 'web' }), disabled.__jsExpr)).toBe(false) + }) + it('disables the ralph tool in every shipped preset that carries it', async () => { for (const id of ['cordis', 'ptc', 'standard']) { expect(findEntry(await shippedEntries(id), 'tool-ralph')?.disabled, id).toBe(true) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 8a78e83473..8663d19a99 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -2372,6 +2372,9 @@ importers: '@deepseek-ai/dsh-subprocess': specifier: workspace:^ version: link:../../subprocess/subprocess + '@deepseek-ai/dsh-tool-cordis': + specifier: workspace:^ + version: link:../../extensions/tool-cordis '@deepseek-ai/dsh-tool-subagent': specifier: workspace:^ version: link:../../subagent/tool-subagent @@ -7131,6 +7134,9 @@ importers: '@deepseek-ai/dsh-cordis-host-runner': specifier: workspace:^ version: link:../cordis-host-runner + '@deepseek-ai/dsh-system-prompt': + specifier: workspace:^ + version: link:../../core/system-prompt '@deepseek-ai/dsh-tools': specifier: workspace:^ version: link:../../core/tools diff --git a/snapshots/session/cordis-inspect-jsdoc/cordis.snapshot.yml b/snapshots/session/cordis-inspect-jsdoc/cordis.snapshot.yml index 05682eb693..1119ac8f98 100644 --- a/snapshots/session/cordis-inspect-jsdoc/cordis.snapshot.yml +++ b/snapshots/session/cordis-inspect-jsdoc/cordis.snapshot.yml @@ -36,6 +36,8 @@ - insert: - id: cordis-host-runner name: '@deepseek-ai/dsh-cordis-host-runner' + - id: cordis-inspect-providers + name: '@deepseek-ai/dsh-tool-cordis/host' - id: tool-cordis name: '@deepseek-ai/dsh-tool-cordis' - id: llm-replay diff --git a/snapshots/session/cordis-inspect-jsdoc/cordis.yml b/snapshots/session/cordis-inspect-jsdoc/cordis.yml index 1f92269096..9c8e871aea 100644 --- a/snapshots/session/cordis-inspect-jsdoc/cordis.yml +++ b/snapshots/session/cordis-inspect-jsdoc/cordis.yml @@ -33,5 +33,7 @@ - insert: - id: cordis-host-runner name: '@deepseek-ai/dsh-cordis-host-runner' + - id: cordis-inspect-providers + name: '@deepseek-ai/dsh-tool-cordis/host' - id: tool-cordis name: '@deepseek-ai/dsh-tool-cordis' diff --git a/tsconfig.base.json b/tsconfig.base.json index 60c97b6946..313fd9eeff 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -185,6 +185,7 @@ "@deepseek-ai/dsh-plugin-manager/registry": ["./packages/boot/plugin-manager/src/registry.ts"], "@deepseek-ai/dsh-plugin-manager/operations": ["./packages/boot/plugin-manager/src/operations.ts"], "@deepseek-ai/dsh-plugin-manager/tools": ["./packages/boot/plugin-manager/src/tools.ts"], + "@deepseek-ai/dsh-tool-cordis/host": ["./packages/extensions/tool-cordis/src/host.ts"], "@deepseek-ai/dsh-host-plugin-inventory": ["./packages/host/plugin-inventory/src"], "@deepseek-ai/dsh-host-plugin-inventory/types": ["./packages/host/plugin-inventory/src/types.ts"], "@deepseek-ai/dsh-client-ui-slots": ["./packages/client/ui-slots/src"], From a946008275a47aeb0e28a46878427348bdd7c6fc Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Mon, 21 Sep 2026 01:45:57 +0800 Subject: [PATCH 095/100] docs(boot): document linked plugin peer resolution --- ...9-profile-resolution-generations.i18n.yaml | 4 +- ...26-09-09-profile-resolution-generations.md | 12 ++--- ...09-09-profile-resolution-generations.zh.md | 12 ++--- ...-profile-resolution-lookup-order.i18n.yaml | 4 +- ...6-09-19-profile-resolution-lookup-order.md | 50 +++++++++++++------ ...9-19-profile-resolution-lookup-order.zh.md | 50 +++++++++++++------ docs/user/develop/basic/publish.i18n.yaml | 4 +- docs/user/develop/basic/publish.md | 2 + docs/user/develop/basic/publish.zh.md | 2 + packages/boot/app-boot/README.i18n.yaml | 4 +- packages/boot/app-boot/README.md | 5 +- packages/boot/app-boot/README.zh.md | 5 +- 12 files changed, 100 insertions(+), 54 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml index 9e68a09547..9b7365d0b4 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.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 .agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md -2026-09-09-profile-resolution-generations.md: ced79eefc8c46a43cabd5b6a79db2644526c022f -2026-09-09-profile-resolution-generations.zh.md: 98c509488aaeaa8d1b5e722bf6e3ea6346d45c46 +2026-09-09-profile-resolution-generations.md: fe8062c434fb226982ef9d1e88355b6833293aca +2026-09-09-profile-resolution-generations.zh.md: d63ebc9a1e70c182d0d2703f06bdacfe2a7a4c49 diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md index ced79eefc8..fe8062c434 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md +++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md @@ -64,9 +64,9 @@ For example, `@deepseek-ai/dsh-tools` creates its scheduler key with `Symbol()`. ### Immutable generations -A runtime interception holds one `current` generation. Each synchronous resolution captures that reference once. Generation construction reads every required manifest before publication; an error leaves the current generation unchanged. Successful publication replaces one reference, and in-flight calls may finish against the generation they captured. +A runtime interception holds one `current` generation. Each synchronous resolution captures that reference once. Generation construction reads every required dependency-graph manifest before publication; an error leaves the current generation unchanged. Successful publication replaces one reference, and in-flight calls may finish against the generation they captured. -Selection and package-metadata caches belong to a generation. Publishing a successor invalidates them by making the old generation unreachable after its callers finish; update code does not mutate or clear individual entries. A generation hit and a successful native selection can be cached, but a generation miss is rescanned so a profile-local package installed after the miss becomes visible through native lookup. Calls with explicit CommonJS paths or non-default conditions never reuse a default-resolution cache entry. +Selection and package-metadata caches belong to a generation. Publishing a successor invalidates them by making the old generation unreachable after its callers finish; update code does not mutate or clear individual entries. Profile-importer hits and successful native selections can be cached, but a generation miss is rescanned so a profile-local package installed after the miss becomes visible through native lookup. Linked importer routes are not cached: each resolution reads the linked package's current peer declarations. Calls with explicit CommonJS paths or non-default conditions never reuse a default-resolution cache entry. The launcher constructs one startup generation. The service accepts an additive successor, but no package-manager transaction invokes replacement in this implementation. @@ -74,7 +74,7 @@ The launcher constructs one startup generation. The service accepts an additive The resolver uses `node-addon-require-builtin` to read `internal/modules/esm/loader` and `internal/modules/cjs/loader`. The ESM adapter wraps the per-thread singleton `CascadedLoader` resolve methods. The CommonJS adapter wraps the internal builtin's `Module._resolveFilename`; that `Module` is the same object exported by `node:module`. -Both adapters call one routing function. It ignores builtins, relative or absolute paths, URLs, parents outside the profile scope, and explicit calls outside the supported lookup. A `#imports` request uses Node's mapping from its owning manifest; an external bare target follows the same local, interception, and native-after-interception package order with the request's conditions, while Node retains exact target resolution. For a scoped bare request, a package self-reference keeps the original parent even when an npm alias gives its installed directory another name. A profile-local or plugin-private package also keeps the original parent when Node resolves the requested entry before the virtual shared-fallback position; a CommonJS package directory without `exports` does not suppress the fallback when only its requested subpath is absent. Otherwise the router uses an interception hit through that entry's declaring anchor or continues native lookup after the virtual fallback. Explicit CommonJS path lists apply the same insertion rule independently to each path in caller order. +Both adapters call one routing function. It ignores builtins, relative or absolute paths, URLs, parents outside the profiles and registered linked roots, and explicit calls outside the supported lookup. A `#imports` request uses Node's mapping from its owning manifest; an external bare target follows the same local, interception, and native-after-interception package order with the request's conditions, while Node retains exact target resolution. For a scoped bare request, a package self-reference keeps the original parent even when an npm alias gives its installed directory another name. A profile-local or plugin-private package also keeps the original parent when Node resolves the requested entry before the interception layer; a CommonJS package directory without `exports` does not suppress the interception entry when only its requested subpath is absent. Otherwise the router uses an interception hit through that entry's declaring anchor or continues native lookup from the physical layer. The [lookup-order Note](2026-09-19-profile-resolution-lookup-order.md) owns profile and linked-root positions, peer eligibility, and explicit CommonJS path behavior. The adapters call the captured native resolver after routing. Node remains responsible for exports, import and require conditions, main files, subpaths, extensions, native caches, and error codes. Routed ESM failures replace the internal lookup anchor in Node's diagnostic with the original importer. A selected package's invalid export or missing target does not trigger another same-name candidate. CommonJS does not replace `_findPath` or reproduce `_resolveFilename`. @@ -84,7 +84,7 @@ The guarantee covers Node's default `import`, `import()`, `import.meta.resolve`, The runtime resolution lists the packages it supplies; Loader entries form the active plugin list. Consumers keep using Loader's existing entry lifecycle and filter the entries relevant to their own scope. Consumers that need package metadata pass a specifier and owning tree base URL to a lightweight `app-boot` service without requiring a `./package.json` export. An installed runtime resolution is authoritative, including a miss; a service created without one retains native lookup for low-level embedders. -The resolver does not expose `imported(entry)` and does not observe ModuleJobs, wrap Entry methods, associate fibers with import calls, replace registry or tree methods, or adapt HMR transactions. A repeated query uses the same generation and therefore cannot drift from the route used for the import. Non-Node importers that need package metadata must explicitly implement the same deterministic resolver interface. +The resolver does not expose `imported(entry)` and does not observe ModuleJobs, wrap Entry methods, associate fibers with import calls, replace registry or tree methods, or adapt HMR transactions. Package queries and imports use the same selection rules, including the current peer declarations of linked packages. Non-Node importers that need package metadata must explicitly implement the same resolver interface. The implementation lives under `app-boot/src/profile-resolution/`. `service.ts` provides the long-lived `ctx.pluginPackages` and owns the main-thread interception and the Worker resolution lifetime; `resolver.ts` implements runtime resolution lookup and the Node Internal adapters; `worker-bootstrap.ts` installs the inherited runtime resolution in one thread. Profile selection and runtime resolution construction remain in `profile.ts`. Workers reference the bootstrap only through the public `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap` export. @@ -104,13 +104,13 @@ Replacing, upgrading, or removing an already loaded package requires process res ### Filesystem and runtime carriers -The resolver does not create, update, or remove fallback symlinks and proxy packages. Runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`; every other name sees that directory as an ordinary ancestor, and symlinks anywhere in the profile tree are ordinary filesystem content without dedicated recognition. Profile-local package metadata and bundle dependency discovery follow the same Node lookup; ordinary pnpm-installed packages retain native precedence. The [lookup-order Note](2026-09-19-profile-resolution-lookup-order.md) records the complete order. Writable profile state and package-manager transactions remain outside the resolver. +The resolver does not create, update, or remove fallback symlinks and proxy packages. Runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`; every other name sees that directory as an ordinary ancestor. Construction also records profile package links whose real targets are outside the profiles tree. At each linked root's `node_modules`, only names declared as peers and present in the runtime resolution are occupied. Profile-local package metadata and bundle dependency discovery follow the same Node lookup; ordinary pnpm-installed packages retain native precedence. The [lookup-order Note](2026-09-19-profile-resolution-lookup-order.md) records the complete order. Writable profile state and package-manager transactions remain outside the resolver. Runtime resolution requires a supported Node Internal loader interface. The Electron Host runs through the Electron executable with `ELECTRON_RUN_AS_NODE=1`; packaged builds read the dsh tree from ASAR and map executable ASAR entries to electron-builder's unpacked tree. Pkg and Electron use the same runtime resolution mechanism as ordinary Node launches. ### Performance and verification -Generation construction is startup or update work, not resolve work, and its absolute latency is reported separately. Ordinary hot paths consist of scope classification, bare-name extraction, local-before-fallback selection, a Map lookup, and one native resolution; a cache hit returns the generation-owned result directly. A CommonJS request may perform one native probe followed by one routed resolution when a local package directory exists without `exports` but lacks the requested subpath. Out-of-scope calls do not read manifests and cache only whether each parent belongs to the profile scope. +Generation construction is startup or update work, not resolve work, and its absolute latency is reported separately. Profile hot paths consist of scope classification, bare-name extraction, local-before-fallback selection, a Map lookup, and one native resolution; a cache hit returns the generation-owned result directly. Linked importer routes additionally read the package's peer declarations and do not cache the selected route. A CommonJS request may perform one native probe followed by one routed resolution when a local package directory exists without `exports` but lacks the requested subpath. Out-of-scope calls do not read manifests and cache only whether each parent has an interception layer. One-off local measurements taken during implementation ran built JavaScript under plain Node in fresh processes and compared it with a process that installed no hook. The measurement script and results are not committed, and these figures are not a benchmark or CI budget. Seven alternating rounds covered outside, profile-local, and fallback imports through dynamic import, `import.meta.resolve`, require, and `require.resolve`. Across Node 22.19, 24.18, and 26.8, the largest positive hot-path median was 4.5%. On Node 24.18, a 256-package cold workload regressed by at most 11.2% and generation construction took 16.027 ms median; the 32-package local `require.resolve` case added 1.033 ms across the batch (+34.7%) from fixed startup cost. diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md index 98c509488a..d63ebc9a1e 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md @@ -64,9 +64,9 @@ ESM `import` 和 CommonJS `require` 都选中这些版本。在每种模块格 ### 不可变 generation -一个 runtime interception 持有一个 `current` generation。每个同步 resolve 在入口只捕获一次该引用,完整调用只读该引用。generation 构造在发布前读取所有必需 manifest;失败时当前 generation 不变。发布成功只替换一个引用,执行中的调用可以继续使用它已捕获的 generation。 +一个 runtime interception 持有一个 `current` generation。每个同步 resolve 在入口只捕获一次该引用,完整调用只读该引用。generation 构造在发布前读取依赖图所需的全部 manifest;失败时当前 generation 不变。发布成功只替换一个引用,执行中的调用可以继续使用它已捕获的 generation。 -选包缓存和包元数据缓存归 generation 所有。发布下一代后,旧 generation 在调用方退出后自然不可达,不逐项清理缓存。generation 命中和原生解析成功结果可以缓存,但 generation 未命中会重新扫描,因此未命中后安装的 profile 本地包会通过原生查找变为可见。显式 CommonJS paths 或非默认 conditions 不得复用默认解析缓存。 +选包缓存和包元数据缓存归 generation 所有。发布下一代后,旧 generation 在调用方退出后自然不可达,不逐项清理缓存。profile importer 的命中和原生解析成功结果可以缓存,但 generation 未命中会重新扫描,因此未命中后安装的 profile 本地包会通过原生查找变为可见。linked importer 的路由不缓存,每次解析读取链接包当前的 peer 声明。显式 CommonJS paths 或非默认 conditions 不得复用默认解析缓存。 launcher 只构造启动 generation。服务接受新增型后继 generation,但本实现没有包管理器事务调用替换操作。 @@ -74,7 +74,7 @@ launcher 只构造启动 generation。服务接受新增型后继 generation, resolver 使用 `node-addon-require-builtin` 读取 `internal/modules/esm/loader` 和 `internal/modules/cjs/loader`。ESM 适配器包装每线程单例 `CascadedLoader` 的 resolve 方法。CommonJS 适配器包装内部 builtin 导出的 `Module._resolveFilename`;该 `Module` 与 `node:module` 导出的对象相同。 -两个适配器调用同一个路由函数。builtin、相对或绝对路径、URL、profile 作用域外 parent 和支持的查找以外的显式调用都直接委托原生实现。`#imports` 请求使用所属 manifest 中的 Node 映射;外部 bare target 按相同 conditions 遵循本地包、interception 和 native-after-interception 的选包顺序,精确 target 解析仍由 Node 负责。对于作用域内的 bare request,package self-reference 保留原 parent,即使 npm alias 使安装目录使用另一个名称。Node 能在虚拟共享 fallback 之前从 profile 本地包或插件私有包解析到所请求入口时,也保留原 parent;没有 `exports` 的 CommonJS 包目录仅缺少所请求 subpath 时,不会压过 fallback。其他请求在 interception 命中时通过该条目的声明锚点解析,未命中时从虚拟 fallback 之后继续原生查找。显式 CommonJS path 列表按调用方顺序,对每个 path 独立应用相同的插入规则。 +两个适配器调用同一个路由函数。builtin、相对或绝对路径、URL、profile 与已记录 linked root 之外的 parent,以及支持的查找以外的显式调用,都直接委托原生实现。`#imports` 请求使用所属 manifest 中的 Node 映射;外部 bare target 按相同 conditions 遵循本地包、interception 和 native-after-interception 的选包顺序,精确 target 解析仍由 Node 负责。对于作用域内的 bare request,package self-reference 保留原 parent,即使 npm alias 使安装目录使用另一个名称。Node 能在拦截层之前从 profile 本地包或插件私有包解析到所请求入口时,也保留原 parent;没有 `exports` 的 CommonJS 包目录仅缺少所请求 subpath 时,不会压过拦截条目。其他请求在 interception 命中时通过该条目的声明锚点解析,未命中时从该物理层继续原生查找。[查找顺序 Note](2026-09-19-profile-resolution-lookup-order.zh.md)统一说明 profile 与 linked root 的拦截位置、peer 条件和显式 CommonJS path 行为。 适配器完成路由后调用捕获的原生 resolver。exports、import/require conditions、main、subpath、扩展名、原生缓存和错误码仍归 Node 处理。路由后的 ESM 失败会把 Node 诊断中的内部查找锚点替换为原始 importer。选中包的无效 export 或缺失目标不会触发另一个同名候选。CommonJS 不替换 `_findPath`,也不复制 `_resolveFilename`。 @@ -84,7 +84,7 @@ resolver 使用 `node-addon-require-builtin` 读取 `internal/modules/esm/loader runtime resolution 列出它提供的包;Loader entries 组成活动插件列表,两者不能合并。消费方继续使用 Loader 原有 entry 生命周期,并按自身 scope 过滤相关 entries。需要 package metadata 的消费方将 specifier 和所属树的 base URL 交给 app-boot 中的轻量服务,无需 package 导出 `./package.json`。安装 runtime resolution 后,即使查询未命中也以它为准;底层嵌入方只安装服务而不提供 runtime resolution 时,服务保留 Node 原生查找。 -解析器不提供 `imported(entry)`,不观察 ModuleJob,不包装 Entry 方法,不把 fiber 与 import 调用关联,也不替换 registry、tree 或 HMR 方法。重复查询读取同一个 generation,因此不会偏离 import 使用的路线。需要包元数据的非 Node importer 必须显式实现同一个确定性 resolver 接口,不能把调用来源推断重新引入 Node 主路径。 +解析器不提供 `imported(entry)`,不观察 ModuleJob,不包装 Entry 方法,不把 fiber 与 import 调用关联,也不替换 registry、tree 或 HMR 方法。包查询与 import 使用同一套选包规则,包括链接包当前的 peer 声明。需要包元数据的非 Node importer 必须显式实现同一个 resolver 接口。 实现集中在 `app-boot/src/profile-resolution/`。`service.ts` 提供长期存在的 `ctx.pluginPackages`,并拥有主线程拦截与 Worker runtime resolution 的生命周期;`resolver.ts` 实现 runtime resolution 查询和 Node Internal 适配器;`worker-bootstrap.ts` 在线程内安装继承的 runtime resolution。profile 选包和 runtime resolution 构造留在 `profile.ts`。Worker 只通过 `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap` 公开入口引用 bootstrap。 @@ -104,13 +104,13 @@ runtime resolution 列出它提供的包;Loader entries 组成活动插件列 ### 文件系统与运行时载体 -解析器不创建、更新或删除 fallback 软链接与代理包。runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置;其余包名把该目录当作普通祖先,profile 树内任何位置的软链接都是普通文件系统内容,没有专门识别。profile 本地包元数据与 bundle 依赖展开遵循同一套 Node 查找;正常由 pnpm 安装的包保留原生优先级。完整顺序见[查找顺序 Note](2026-09-19-profile-resolution-lookup-order.zh.md)。可写 profile 状态和包管理器事务不属于解析器。 +解析器不创建、更新或删除 fallback 软链接与代理包。runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置;其余包名把该目录当作普通祖先。构造时还会记录真实目标位于 profiles 树外的 profile 包链接。在每个 linked root 的 `node_modules` 层,只有被声明为 peer 且 runtime resolution 中存在的包名被占据。profile 本地包元数据与 bundle 依赖展开遵循同一套 Node 查找;正常由 pnpm 安装的包保留原生优先级。完整顺序见[查找顺序 Note](2026-09-19-profile-resolution-lookup-order.zh.md)。可写 profile 状态和包管理器事务不属于解析器。 运行时解析要求受支持的 Node Internal loader 接口。Electron Host 通过设置 `ELECTRON_RUN_AS_NODE=1` 的 Electron 可执行文件运行;打包构建从 ASAR 读取 dsh 依赖树,并把 ASAR 中的可执行条目映射到 electron-builder 的 unpacked 目录。pkg 与 Electron 使用和普通 Node 启动相同的 runtime resolution 机制。 ### 性能与验证 -generation 构造发生在启动或显式更新阶段,不属于单次 resolve,但需要单独报告绝对延迟。普通热路径只包括 scope 分类、bare name 提取、本地优先判断、Map 查询和一次原生解析;缓存命中直接返回 generation 级结果。当本地 CommonJS 包目录没有 `exports` 且仅缺少所请求 subpath 时,一次请求可能先执行一次原生探测,再执行一次路由解析。作用域外调用不读取 manifest,只缓存 parent 是否位于 profile scope。 +generation 构造发生在启动或显式更新阶段,不属于单次 resolve,但需要单独报告绝对延迟。profile 热路径只包括 scope 分类、bare name 提取、本地优先判断、Map 查询和一次原生解析;缓存命中直接返回 generation 级结果。linked importer 的路由还会读取包的 peer 声明,且不缓存选中的路由。当本地 CommonJS 包目录没有 `exports` 且仅缺少所请求 subpath 时,一次请求可能先执行一次原生探测,再执行一次路由解析。作用域外调用不读取 manifest,只缓存 parent 是否具有拦截层。 实现期间的一次性本地测量用 plain Node 在全新进程中执行构建后的 JavaScript,并与完全没有安装 hook 的进程比较。测量脚本和结果未提交,这些数据不是 benchmark 或 CI 预算。七轮交替顺序覆盖 outside、profile-local 和 fallback 的 dynamic import、`import.meta.resolve`、require、`require.resolve`。Node 22.19、24.18 和 26.8 的热路径中位数最大正向回退为 4.5%。Node 24.18 的 256 包 cold workload 最大回退为 11.2%,generation 构造中位数为 16.027 ms;32 包本地 `require.resolve` 因固定启动成本在整批增加 1.033 ms(+34.7%)。 diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml index f625fbdf15..19d2fd9b0d 100644 --- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.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 .agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md -2026-09-19-profile-resolution-lookup-order.md: da9c501cff6c902863def6d39e4052097c75bcb3 -2026-09-19-profile-resolution-lookup-order.zh.md: 72a9e876a49770ed2bdc544e2ee9104619eedc80 +2026-09-19-profile-resolution-lookup-order.md: 5744a7bbb7b76417abeabb31bfa8512137ed0bff +2026-09-19-profile-resolution-lookup-order.zh.md: 2db1394701d739ed9cf56694cb028189ff38b362 diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md index da9c501cff..5744a7bbb7 100644 --- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md +++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md @@ -12,7 +12,7 @@ A developer must be able to restate the resolution rule in one sentence: which p ## Decision -Module resolution inside a profile is an ordinary Node ancestor `node_modules` chain. dsh does exactly one thing: every package name in the runtime resolution computed at startup occupies the package directory position `$DSH_HOME/profiles/node_modules/`. When the chain reaches this layer, a package name with an entry is answered by the runtime resolution's package, and a package name without an entry sees the physical directory at this layer. Every other resolution behavior matches Node. [Construction, publication, Worker inheritance, and runtime carriers of immutable generations](2026-09-09-profile-resolution-generations.md) are recorded by the existing Note and are not repeated here. +Module resolution inside a profile is an ordinary Node ancestor `node_modules` chain. dsh does exactly one thing: every package name in the runtime resolution computed at startup occupies the package directory position `$DSH_HOME/profiles/node_modules/`. When the chain reaches this layer, a package name with an entry is answered by the runtime resolution's package, and a package name without an entry sees the physical directory at this layer. A plugin linked outside the tree has the same form of interception at its real directory: runtime resolution entries that the plugin declares as peers occupy `/node_modules/`. Every other resolution behavior matches Node. [Construction, publication, Worker inheritance, and runtime carriers of immutable generations](2026-09-09-profile-resolution-generations.md) are recorded by the existing Note and are not repeated here. ### Part 1: Resolution rules @@ -46,19 +46,28 @@ Node remains responsible for `exports`, `imports`, conditions, `main`, subpaths, The interception layer reads, writes, and deletes no disk links. Leftover historical symlinks are treated as ordinary filesystem content: the positions of installation package names at ③ are already occupied by the runtime resolution, so old links are never read; all other package names see the contents of ③ normally along the ancestor chain. Profile load removes, once, the projections the link backend of the dsh 0.1.5 releases wrote into a profile: symlinks under the profile's `node_modules` whose target lies inside `/.dsh-module-fallback/node_modules`, followed by that directory. pnpm-installed packages and every other symlink stay. -#### 3. What the interception layer holds: the runtime resolution's scan contents +#### 3. Plugins linked outside the tree: interception at their real directory's `node_modules` -The runtime resolution is computed once at profile startup and consists of three parts. +When `/node_modules/` is a symlink whose real target R is outside the profiles tree, R is a linked root. Importers below R follow its real ancestor chain, with `R/node_modules` as the interception layer: deeper `node_modules` on that chain, such as a transitive dependency's own layer inside pnpm's `.pnpm/`, are local layers; above `R/node_modules`, Node continues through `parent(R)/node_modules` up to the filesystem root. + +Only some package names are occupied at this layer: names declared in `R/package.json` under `peerDependencies` that also have a runtime resolution entry. A plugin declares dsh packages whose instances it must share with the host as peers. When lookup reaches this layer, the running dsh supplies the package, and the same-named devDependency copy installed at this position for type checking is not loaded. Names declared only under `dependencies`, not as peers, remain unoccupied. The plugin's own third-party versions retain Node's nearest-wins order, just as ① and ② precede ③ inside a profile. + +Each resolution reads the peer set from `R/package.json`; runtime resolution construction does not freeze it, and linked importer routes are not memoized. After a developer changes `peerDependencies`, new resolutions during a plugin reload read the new declaration. This neither clears Node's module caches nor automatically watches plugin files. Names not occupied at this layer are delegated to Node from the `R/package.json` anchor: the physical contents of `R/node_modules`, followed by R's real ancestor chain. Runtime resolution construction scans top-level and `@scope/*` entries in `/node_modules` for linked roots. A successor may add or remove linked roots within the existing package-mapping and local-name constraints; changing the real target of an existing link name rejects publication and requires restart because Node caches real paths. An unreadable `R/package.json` occupies no names at this layer; Node reports its diagnostics. + +#### 4. What the interception layer holds: the runtime resolution's scan contents + +The runtime resolution is computed once at profile startup and consists of four parts. - Installation closure: starting from the `package.json` of the currently running dsh package, a breadth-first traversal follows `dependencies` and `peerDependencies`; each edge resolves from the manifest that declares it per Node rules, and the first installed package found owns a package name. The closure holds several hundred entries, roughly half in the `@deepseek-ai/` scope and half third-party libraries. These entries apply to every profile. - Bundle-only entries: for a bundle selected by the profile that is not part of the closure, the same traversal starts from its manifest, and package names the closure already owns are not overridden. These entries apply only to profiles that select that bundle; they let the Loader import the bundle's embedded plugins by bare name from the profile root. - Local package names: package names among the profile's direct dependencies that are already installed in `$DSH_HOME/profiles//node_modules`. They already sit at ② on the ancestor chain; recording them only saves one directory probe. +- Linked roots: top-level and `@scope/*` symlinks in `$DSH_HOME/profiles//node_modules` whose targets are outside the profiles tree and contain a `package.json`; each records its real directory and link position. Links whose targets remain inside the profiles tree are not recorded because the ancestor chain already covers them. The CLI derives the installation anchor from `import.meta.url`, which Node has already resolved to its real path; the Desktop Host builds it from its runtime directory, which is not a symlink. Both leave the installation root equal to its real directory, so bundle discovery and dependency traversal use the same location. During the traversal, every dependency level uses the real directory of its owning package as the lookup anchor for the next level and records the location of the manifest that declares it. After a hit, Node resolves from that declaring location and gets the same result the package's own internal imports get. Every entry records the package name, package directory, version, declaring location, and scope. Declared but uninstalled dependencies are skipped; the bundle package root itself does not become an entry. -#### 4. Hook coverage +#### 5. Hook coverage -The hook participates only when the importer is under `$DSH_HOME/profiles/**`. Builtin, relative-path, absolute-path, and URL requests, and every request whose importer is outside the tree, go straight to Node. +The hook participates only when the importer is under `$DSH_HOME/profiles/**` or a linked root. Builtin, relative-path, absolute-path, and URL requests, and every request whose importer is outside both locations, go straight to Node. The ESM and CommonJS adapters call the same routing function, and the main thread and Harness-owned Workers install the same runtime resolution. The implementation lives in `packages/boot/app-boot/src/profile-resolution/resolver.ts`; runtime resolution construction lives in `packages/boot/app-boot/src/profile.ts`. @@ -91,11 +100,16 @@ After a runtime resolution hit, the `ERR_MODULE_NOT_FOUND` and `ERR_PACKAGE_PATH #### Table 3: Ancestor chain when a plugin is linked outside the tree +The profile links `/node_modules/my-plugin` to the plugin's real directory R. R's manifest declares `@deepseek-ai/dsh-tools` as a peer and installs it as a devDependency, and declares `zod` as a dependency. + | Import source → target | Hook participates | Result | |---|---|---| | profile → linked plugin | Participates up to ② | Node follows the symlink at ②; the plugin loads by its real path | -| Linked plugin → its own third-party dependencies | Does not participate | The real path's ancestor chain; uses the version in the developer's own `node_modules` | -| Linked plugin → dsh installation packages | Does not participate | The copy in the developer's own `node_modules`; `ERR_MODULE_NOT_FOUND` when absent. Part 3 describes how to make it the same copy as the running dsh | +| Linked plugin → `zod` | Participates; `zod` is not occupied at `R/node_modules` | `R/node_modules/zod`, the developer's installed version | +| Linked plugin → `@deepseek-ai/dsh-tools` (peer) | Participates; the name is occupied at `R/node_modules` | The running dsh's copy; the devDependency copy in `R/node_modules` is not read | +| Linked plugin → a stateful dsh package declared only as a dependency | Participates; the name is not occupied | Its own copy in `R/node_modules`, creating a second instance; the same mistake as installing the dsh package at ② inside the tree. Declare it as a peer instead | +| Linked plugin → undeclared package name | Participates; the name is not occupied | Physical contents of `R/node_modules`, then R's real ancestor chain | +| Transitive dependency inside R → any package name | Participates | Its own local layers first, then the rules above; the occupied set still comes from the peers in `R/package.json` | ### Part 3: Developer integration guide @@ -107,12 +121,11 @@ The plugin's own third-party dependencies are hoisted to `$DSH_HOME/profiles/`. The running installation is the copy on the plugin's ancestor chain, so the runtime resolution and the real paths agree. -- Layout B: the plugin repository links the dsh packages it uses to the local dsh source repository (`link:../deepseek-harness/packages/core/tools` or `pnpm link`) and starts `pnpm dsh --profile ` from the source repository. Both sides load the same copy from the source repository. +Use the same manifest declarations as the harness packages: declare dsh packages whose instances must be shared with the host under both `peerDependencies` and `devDependencies`. The peer declaration occupies their positions at `R/node_modules`; the dev copies serve the compiler and standalone tests. Keep third-party dependencies and stateless dsh utilities such as `@deepseek-ai/dsh-brand` and `@deepseek-ai/dsh-util-values` under `dependencies`. After changing `peerDependencies`, new resolutions during a plugin reload use the new declaration; Node and Cordis still own the lifetime of already loaded modules. -Not provided and not recommended: having the hook proxy installation packages for real paths linked out of the tree, which requires tracking every real root entered from the profile, something Node itself does not do for developers either; and starting with a dsh installed elsewhere while the plugin repository installs its own dsh devDependencies, which produces two module instances and splits both `Symbol()` keys and `instanceof` checks. +Two other layouts remain available: install `@deepseek-ai/dsh` in the plugin repository and run `pnpm exec dsh --profile ` there, or link dsh packages to a local source repository and start dsh from that repository. Both make the running dsh and the repository's copies identical, but linked plugins do not require either layout. ## Alternatives considered @@ -126,16 +139,23 @@ Not provided and not recommended: having the hook proxy installation packages fo **Hide the whole physical directory that holds the interception layer.** This conflicts with "all other resolution matches Node": non-installation packages placed in `$DSH_HOME/profiles/node_modules` would become invisible to every profile. -**Extend the hook to the real directories of plugins linked outside the tree.** This requires tracking every real root entered from the profile during resolution and rewriting results for some package names under those directories; Node does this for no linked-out package, and the two layouts in Part 3 do not need it. +**Let every runtime resolution entry occupy its package directory at `R/node_modules`.** This has exactly the same form as ③, but the closure's hundreds of third-party libraries would shadow the plugin repository's own `zod` and `yaml` versions, unlike ① and ② preceding ③ inside the tree. Occupying only peers preserves the plugin's own third-party versions. + +**Use the nearest importer's manifest `dependencies` to decide which names resolve natively.** This can simulate an installation into the profile without devDependencies or peers, but every resolution must find the importer's nearest manifest, and the rule differs from ③. Occupying peers reads only the linked root's manifest. + +**Freeze the peer set during runtime resolution construction.** Every edit to `peerDependencies` would require restarting dsh. Reading at resolution time makes plugin reloads sufficient, at the cost of one small-file read per routed request in development mode. + +**Connect the ancestor chain above the linked root back to the profile's ② and ③.** This follows the form of Node's `--preserve-symlinks`: `R/node_modules` remains the first native layer, so the devDependency copy still wins and the duplicate-instance problem remains. ## Verification - The table-driven matrix in [profile-resolution.spec.ts](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts): importers are the profile root and a plugin inside the profile; package names are an installation entry, a bundle-only entry, and a name outside the table; every presence combination of the four layers ①②③④, with ② and ③ each in two forms, a real directory and a symlink pointing elsewhere; every cell asserts that ESM import, CommonJS require, `require.resolve`, and the `packageDir` metadata land in the same directory. +- Linked-root cases in the same file link a profile package to an external repository with a same-named devDependency copy in its `node_modules`. Package names cover an installation entry declared as a peer, one declared as a dependency, the repository's own third-party dependency, and an undeclared name; importers cover the repository's own files and transitive dependencies inside it. The cases assert agreement across the four resolution forms, that the devDependency copy is not read, and that the next resolution observes a rewritten `peerDependencies` declaration. - Dedicated cases in the same file cover each row of Table 1: bare names and subpaths with and without `exports`, `#alias`, explicit `paths`, package self-reference, CommonJS skipping ③ and going straight to ④ when a subpath is missing after a runtime resolution hit, and the interception position of an out-of-tree profile. -- The [real CLI launch test](../../../../apps/cli/tests/profiles/headless/tests/profile-resolution.ts), under src and lib launches and under plain-directory and npm-link layouts, places an old `@deepseek-ai/dsh-tools` link at ③ and an external package with its embedded dependency at ③, and asserts that Tools and AgentLoop share one module instance, that the external package resolves along its real path, and that every file and link target stays byte-identical. +- The [real CLI launch test](../../../../apps/cli/tests/profiles/headless/tests/profile-resolution.ts), under src and lib launches and under plain-directory and npm-link layouts, places an old `@deepseek-ai/dsh-tools` link at ③ and an external package with its embedded dependency at ③. The npm-link layout also gives the linked plugin a `@deepseek-ai/dsh-tools` devDependency copy and declares it as a peer. It asserts that Tools and AgentLoop share one module instance, that the linked plugin receives that same Tools instance, that the external package resolves along its real path, and that every file and link target stays byte-identical. ## Consequences -Gained: startup writes nothing to disk; installation packages always come from the running installation; all other resolution matches Node, so developers can predict results with their Node knowledge; no recognition code exists for any historical directory layout. +Gained: module resolution needs no disk projections; dsh installation packages selected at an interception layer come from the running installation, including peers declared by plugins linked outside the tree; other resolution retains Node's ancestor-chain and package-entry rules; the lookup path does not recognize historical projection directories. -Paid: third-party libraries in the installation closure still occupy package directories at ③, so a profile plugin that declares a third-party library as a peer or omits the declaration gets the version dsh uses internally, as in the disk-link era; plugins should declare third-party libraries as dependencies. Plugins linked outside the tree cannot obtain installation packages through the hook and must align themselves using the layouts in Part 3. Consumers that bypass the hook, namely child processes a plugin spawns itself, third-party Workers, and external tools run inside the profile directory, can no longer find installation packages through disk links in `$DSH_HOME/profiles/node_modules`. The resolver continues to depend on supported Node Internal interfaces. +Paid: third-party libraries in the installation closure still occupy package directories at ③, so a profile plugin that declares a third-party library as a peer or omits the declaration gets the version dsh uses internally, as in the disk-link era; plugins should declare third-party libraries as dependencies. A linked plugin receives dsh packages from the running installation only when it declares them as peers; dependency declarations retain its own copies. Only direct symlinks from `/node_modules` become linked roots; dependencies linked elsewhere from the plugin repository or hoisted outside it by npm workspaces remain outside every linked root and use plain Node resolution. Peer requests for other plugins inside the profile do not return to ② and fail if R's real ancestor chain cannot find them. Each routed request in development mode reads the plugin manifest. Changing a link target at the same logical path still requires restart. Consumers that bypass the hook, namely child processes a plugin spawns itself, third-party Workers, and external tools run inside the profile directory, can no longer find installation packages through disk links in `$DSH_HOME/profiles/node_modules`. The resolver continues to depend on supported Node Internal interfaces. diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md index 72a9e876a4..2db1394701 100644 --- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md @@ -12,7 +12,7 @@ profile 从自己的包项目加载插件。dsh 本体包和 bundle 内嵌的依 ## Decision -profile 内模块的解析是一条普通的 Node 祖先 `node_modules` 链。dsh 只做一件事:启动时算出的 runtime resolution 中的每个包名,占据 `$DSH_HOME/profiles/node_modules/<包名>` 这个包目录的位置。链走到这一层时,有条目的包名由 runtime resolution 的包回答,没有条目的包名看这一层的物理目录。除此之外的一切解析行为与 Node 一致。[不可变 generation 的构造、发布、Worker 继承与运行时载体](2026-09-09-profile-resolution-generations.zh.md)由既有 Note 记录,本篇不复述。 +profile 内模块的解析是一条普通的 Node 祖先 `node_modules` 链。dsh 只做一件事:启动时算出的 runtime resolution 中的每个包名,占据 `$DSH_HOME/profiles/node_modules/<包名>` 这个包目录的位置。链走到这一层时,有条目的包名由 runtime resolution 的包回答,没有条目的包名看这一层的物理目录。link 到树外的插件把同一形式的拦截层带到自己的真实目录:runtime resolution 中被该插件声明为 peer 的包名,占据 `<真实目录>/node_modules/<包名>` 的位置。除此之外的一切解析行为与 Node 一致。[不可变 generation 的构造、发布、Worker 继承与运行时载体](2026-09-09-profile-resolution-generations.zh.md)由既有 Note 记录,本篇不复述。 ### 一、解析规则 @@ -46,19 +46,28 @@ Node 仍然负责 `exports`、`imports`、conditions、`main`、子路径、扩 拦截层不读、不写、不删任何磁盘链接。历史残留的软链接一律按普通文件系统内容处理:本体包名在 ③ 上的位置已被 runtime resolution 占据,旧链接永远不会被读到;其余包名按主线正常看到 ③ 里的内容。profile 加载时一次性删除 dsh 0.1.5 系列发布版的 Link 后端写进 profile 的投影:profile `node_modules` 下目标位于 `/.dsh-module-fallback/node_modules` 内的软链接,以及该目录本身。pnpm 安装的包和其他软链接都保留。 -#### 3. 拦截层里有什么:runtime resolution 的扫描内容 +#### 3. link 到树外的插件:拦截层在插件真实目录的 `node_modules` -runtime resolution 在 profile 启动时一次算出,由三部分组成。 +`/node_modules/<包名>` 是软链接且真实目标 R 在 profiles 树外时,R 是一个 linked root。R 之下的 importer 走 R 的真实祖先链,拦截层是 `R/node_modules`:链上更深的 `node_modules`(pnpm `.pnpm/` 内传递依赖自己的那层)是本地层,`R/node_modules` 之上是 `parent(R)/node_modules` 直到文件系统根,都按 Node 处理。 + +这一层上被占据的包名只有一部分:`R/package.json` 的 `peerDependencies` 里、且 runtime resolution 有条目的包名。插件把需要与宿主共享实例的 dsh 包声明为 peer;查找走到这一层时,由运行中的 dsh 提供该包,为类型检查安装在这个位置的同名 devDependency 副本不会被加载。只声明为 `dependencies`、未声明为 peer 的包名不被占据,插件自己安装的第三方版本照 Node 规则最近者优先,与树内 ①② 赢 ③ 一致。 + +peer 集合在每次解析时从 `R/package.json` 读取,不在 runtime resolution 构造时固定,linked importer 的路由也不做 memo:开发者改完 `peerDependencies` 后,重新加载插件时的新解析会读取新声明。这不清除 Node 的模块缓存,也不自动监视插件文件。未被占据的包名从 `R/package.json` 锚点交给 Node,即 `R/node_modules` 的物理内容再沿 R 的真实祖先链。linked root 的集合在 runtime resolution 构造时扫描 `/node_modules` 的顶层与 `@scope/*` 条目得到;successor 可以在既有包映射和本地包名约束内新增或移除 linked root,同名 link 换了真实目标则拒绝发布并要求重启,因为 Node 缓存 realpath。`R/package.json` 不可读时这一层不占据任何包名,诊断由 Node 报出。 + +#### 4. 拦截层里有什么:runtime resolution 的扫描内容 + +runtime resolution 在 profile 启动时一次算出,由四部分组成。 - installation 闭包:从当前运行的 dsh 包的 `package.json` 出发,沿 `dependencies` 与 `peerDependencies` 做广度优先遍历,每条边从声明它的 manifest 按 Node 规则解析,同一个包名由第一次找到的已安装包占有。闭包有数百条,约一半在 `@deepseek-ai/` 作用域,一半是第三方库。这些条目对所有 profile 生效。 - bundle-only 条目:profile 选中的、不属于闭包的 bundle,从它的 manifest 出发做同样的遍历,闭包已占有的包名不覆盖。这些条目只对选中该 bundle 的 profile 生效,用于让 Loader 从 profile 根按裸名导入 bundle 内嵌的插件。 - 本地包名:profile 直接依赖中已经安装在 `$DSH_HOME/profiles//node_modules` 的包名。它们本来就在主线 ② 上,记录下来只为免去一次目录探测。 +- linked root:`$DSH_HOME/profiles//node_modules` 顶层与 `@scope/*` 里目标位于 profiles 树外且含 `package.json` 的软链接,记录真实目录与 link 位置。目标仍在 profiles 树内的软链接不记录,主线已经覆盖它。 CLI 的安装锚点来自 `import.meta.url`,Node 已对它做过 realpath;Desktop Host 从其运行时目录拼出锚点,该目录不是软链接。两者的安装根目录都等于真实目录,bundle 发现与依赖遍历使用同一个位置。遍历中每一层依赖都以所属包的真实目录作为下一层的查找锚点,并记录声明它的 manifest 位置。命中后 Node 从这个声明位置解析,得到与该包自己内部 import 相同的结果。每个条目记录包名、包目录、版本、声明位置与作用域。已声明但未安装的依赖跳过;bundle 包根自身不成为条目。 -#### 4. hook 覆盖范围 +#### 5. hook 覆盖范围 -hook 只在 importer 位于 `$DSH_HOME/profiles/**` 时参与。builtin、相对路径、绝对路径、URL 请求,以及 importer 在树外的一切请求,直接交给 Node。 +hook 只在 importer 位于 `$DSH_HOME/profiles/**` 或某个 linked root 之下时参与。builtin、相对路径、绝对路径、URL 请求,以及 importer 在这两处之外的一切请求,直接交给 Node。 ESM 与 CommonJS 两个适配器调用同一个路由函数,主线程与 Harness 自有 Worker 都安装同一份 runtime resolution。实现位于 `packages/boot/app-boot/src/profile-resolution/resolver.ts`,runtime resolution 的构造位于 `packages/boot/app-boot/src/profile.ts`。 @@ -91,11 +100,16 @@ ESM 与 CommonJS 两个适配器调用同一个路由函数,主线程与 Harne #### 表 3:插件被 link 到树外时的主线 +插件 `my-plugin` 被 `/node_modules/my-plugin` 链接到真实目录 R;R 的 manifest 把 `@deepseek-ai/dsh-tools` 声明为 peer 并装成 devDependency,把 `zod` 声明为 dependency。 + | import 来源 → 目标 | hook 是否参与 | 结果 | |---|---|---| | profile → 链接的插件 | 参与到 ② 为止 | ② 的软链接被 Node 跟随,插件以真实路径加载 | -| 链接插件 → 它自己的第三方依赖 | 不参与 | 真实路径的祖先链,使用开发者自己 `node_modules` 里的版本 | -| 链接插件 → dsh 本体包 | 不参与 | 开发者自己 `node_modules` 里的副本;没有则 `ERR_MODULE_NOT_FOUND`。让它与运行中的 dsh 是同一份的做法见第三章 | +| 链接插件 → `zod` | 参与,`R/node_modules` 上 `zod` 未被占据 | `R/node_modules/zod`,开发者自己安装的版本 | +| 链接插件 → `@deepseek-ai/dsh-tools`(peer) | 参与,`R/node_modules` 上该名被占据 | 运行中的 dsh 的那一份;`R/node_modules` 里的 devDependency 副本不被读到 | +| 链接插件 → 只声明为 dependency 的有状态 dsh 包 | 参与,未被占据 | `R/node_modules` 里自己的副本,产生第二个实例;与树内把 dsh 包装进 ② 的错误相同,改为 peer 即可 | +| 链接插件 → 未声明的包名 | 参与,未被占据 | `R/node_modules` 的物理内容,再沿 R 的真实祖先链 | +| R 内传递依赖 → 任何包名 | 参与 | 先它自己的本地层,再同上;占据集合仍取 `R/package.json` 的 peer | ### 三、开发者接入指引 @@ -107,12 +121,11 @@ ESM 与 CommonJS 两个适配器调用同一个路由函数,主线程与 Harne #### 2. 开发模式:插件仓库在 profile 树外 -`npm link`,或 `dsh plugin add ../my-plugin` 这类裸目录路径(pnpm 按 `link:` 处理),会让 profile 里的条目成为指向插件仓库的软链接。插件以真实路径加载,hook 不参与它的 import。dsh 本体包必须由插件仓库自己的依赖树解析到与运行中 dsh 同一份,两种布局都满足这一点。 +`npm link`,或 `dsh plugin add ../my-plugin` 这类裸目录路径(pnpm 按 `link:` 处理),会让 profile 里的条目成为指向插件仓库的软链接,仓库目录成为 linked root。插件以真实路径加载,第三方依赖用仓库里自己安装的版本;声明为 peer 的 dsh 包由 `R/node_modules` 上的拦截层提供运行中的那一份,与 dsh 的来源无关:npm 全局安装、Desktop 内置或源码仓启动都一样。仓库里为类型检查安装的 dsh devDependency 只服务编译器,运行时不会被读到。 -- 布局 A:插件仓库把 `@deepseek-ai/dsh` 以及插件用到的 `@deepseek-ai/dsh-*` peer 装成 devDependency,并用该仓库里的 dsh 启动,例如 `pnpm exec dsh --profile `。运行中的安装就是插件祖先链上的那一份,两者的 runtime resolution 与真实路径一致。 -- 布局 B:插件仓库把用到的 dsh 包 link 到本机的 dsh 源码仓(`link:../deepseek-harness/packages/core/tools` 或 `pnpm link`),并从源码仓启动 `pnpm dsh --profile `。两边加载的都是源码仓里的同一份。 +manifest 的写法与 harness 自身的包相同:需要与宿主共享实例的 dsh 包同时声明在 `peerDependencies` 与 `devDependencies`,peer 让 `R/node_modules` 上的位置被占据,dev 副本给编译器和独立测试使用;第三方依赖以及 `@deepseek-ai/dsh-brand`、`@deepseek-ai/dsh-util-values` 这类无状态 dsh 工具包放在 `dependencies`。修改 `peerDependencies` 后,重新加载插件时的新解析会使用新声明;已加载模块的生命周期仍由 Node 和 Cordis 管理。 -不提供、不建议的做法:由 hook 为 link 出去的真实路径代理本体包,这需要追踪从 profile 进入的每个真实根目录,Node 自身也不替开发者做这件事;用别处安装的 dsh 启动,同时插件仓库另装一套 dsh devDependency,这会产生两个模块实例,`Symbol()` 键与 `instanceof` 判断都会分裂。 +另两种可用布局:插件仓库自装 `@deepseek-ai/dsh` 并从仓库里启动 `pnpm exec dsh --profile `;或把 dsh 包 link 到本机源码仓并从源码仓启动。两者让运行中的 dsh 与仓库里的副本本来就是同一份,但 linked 插件不要求使用这两种布局。 ## Alternatives considered @@ -126,16 +139,23 @@ ESM 与 CommonJS 两个适配器调用同一个路由函数,主线程与 Harne **把拦截层所在的物理目录整层隐藏。** 与"其余解析与 Node 一致"冲突:放在 `$DSH_HOME/profiles/node_modules` 的非本体包会对所有 profile 不可见。 -**让 hook 覆盖 link 到树外的插件真实目录。** 需要在解析时追踪每个从 profile 进入的真实根目录,并对这些目录下的部分包名改写结果;Node 不为任何 link 出去的包做这种事,第三章的两种布局不需要它。 +**让 runtime resolution 的全部条目占据 `R/node_modules` 上的包目录。** 与 ③ 完全同形,但闭包里的几百个第三方库会遮住插件仓库自己安装的 `zod`、`yaml` 版本,与树内 ①② 赢 ③ 相反。只占据 peer 保住了「插件自己的第三方版本优先」。 + +**按 importer 最近的 manifest 的 `dependencies` 决定哪些包名走原生。** 能模拟「装进 profile 后不装 devDependencies 与 peer」的效果,但每次解析都要为 importer 找最近的 manifest,规则也不再与 ③ 同形。占据 peer 的做法只读 linked root 一份 manifest。 + +**在 runtime resolution 构造时固定 peer 集合。** 开发者改一次 `peerDependencies` 就要重启 dsh。解析时读取让重载插件即可生效,代价是开发模式下每次路由多一次小文件读取。 + +**把 linked root 之上的主线接回 profile 的 ②③。** 这是 Node `--preserve-symlinks` 的形式,`R/node_modules` 仍是原生的第一层,devDependency 副本照样先被找到,单实例问题原样保留。 ## Verification - [profile-resolution.spec.ts](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts) 中的表驱动矩阵:importer 取 profile 根与 profile 内插件,包名取 installation 条目、bundle-only 条目与表外包名,①②③④ 四层的每一种有无组合,②③ 各含真目录与指向别处的软链接两种形态;每格断言 ESM import、CommonJS require、`require.resolve` 与 `packageDir` 元数据落在同一个目录。 +- 同一文件内的 linked root 用例:`/node_modules` 的软链接指向树外仓库,仓库 `node_modules` 里放同名 devDependency 副本;包名取声明为 peer 的 installation 条目、声明为 dependency 的 installation 条目、仓库自己的第三方 dependency、未声明的包名,importer 取仓库自身文件与仓库内传递依赖;断言四种解析方式一致、devDependency 副本不被读到,以及改写 `peerDependencies` 后下一次解析立即按新声明进行。 - 同一文件内的专项用例覆盖表 1 各行:有无 `exports` 的裸包名与子路径、`#alias`、显式 `paths`、包自引用、命中 runtime resolution 后 CommonJS 子路径缺失时跳过 ③ 直接到 ④,以及树外 profile 的拦截位置。 -- [CLI 真启动测试](../../../../apps/cli/tests/profiles/headless/tests/profile-resolution.ts)在 src 与 lib 两种启动、普通目录与 npm-link 两种布局下,放置 ③ 的旧 `@deepseek-ai/dsh-tools` 链接、③ 的外部包及其内嵌依赖,断言 Tools 与 AgentLoop 共用同一模块实例、外部包沿真实路径解析、所有文件与链接目标逐字节不变。 +- [CLI 真启动测试](../../../../apps/cli/tests/profiles/headless/tests/profile-resolution.ts)在 src 与 lib 两种启动、普通目录与 npm-link 两种布局下,放置 ③ 的旧 `@deepseek-ai/dsh-tools` 链接、③ 的外部包及其内嵌依赖,npm-link 布局再给 link 出去的插件放一份 `@deepseek-ai/dsh-tools` devDependency 副本并声明为 peer;断言 Tools 与 AgentLoop 共用同一模块实例、link 出去的插件拿到的 Tools 也是这一份、外部包沿真实路径解析、所有文件与链接目标逐字节不变。 ## Consequences -买到的:启动不写盘;本体包永远来自当前运行的安装;其余解析与 Node 一致,开发者可以用 Node 的知识预测结果;没有针对任何历史目录形状的识别代码。 +买到的:模块解析无需磁盘投影;命中拦截层的 dsh 本体包来自当前运行的安装,link 到树外的插件声明的 peer 也适用;其余解析保留 Node 的祖先链和包入口规则;解析路径不识别历史投影目录。 -付出的:installation 闭包里的第三方库仍占据 ③ 上的包目录,profile 插件把第三方库声明成 peer 或漏声明时会拿到 dsh 内部使用的版本,与磁盘链接时代相同,插件应把第三方库声明成 dependency;link 到树外的插件不能通过 hook 拿到本体包,必须按第三章的布局自行对齐;不经过 hook 的消费者,即插件自己 spawn 的子进程、第三方 Worker、在 profile 目录里运行的外部工具,不再能通过 `$DSH_HOME/profiles/node_modules` 的磁盘链接找到本体包;resolver 继续依赖受支持的 Node Internal 接口。 +付出的:installation 闭包里的第三方库仍占据 ③ 上的包目录,profile 插件把第三方库声明成 peer 或漏声明时会拿到 dsh 内部使用的版本,与磁盘链接时代相同,插件应把第三方库声明成 dependency;link 到树外的插件只有声明为 peer 的 dsh 包由运行中的 dsh 提供,声明为 dependency 的仍是自己的副本;只有 `/node_modules` 的直接软链接成为 linked root,插件仓库再 link 出去的依赖、npm workspace 提升到仓库之外的依赖不在任何 linked root 下,仍是纯 Node;peer 到 profile 里其他插件的请求不接 ②,沿 R 的真实祖先链找不到就报错;开发模式下每次路由读一次插件 manifest;同一逻辑路径换 link 目标仍需重启;不经过 hook 的消费者,即插件自己 spawn 的子进程、第三方 Worker、在 profile 目录里运行的外部工具,不再能通过 `$DSH_HOME/profiles/node_modules` 的磁盘链接找到本体包;resolver 继续依赖受支持的 Node Internal 接口。 diff --git a/docs/user/develop/basic/publish.i18n.yaml b/docs/user/develop/basic/publish.i18n.yaml index 9bbb19fe2a..52fc874528 100644 --- a/docs/user/develop/basic/publish.i18n.yaml +++ b/docs/user/develop/basic/publish.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 docs/user/develop/basic/publish.md -publish.md: cde14e1ac25de709e738329f29bb68b124c32d25 -publish.zh.md: e588c52ba12e0c9afe027be44a94c216ab4c5da2 +publish.md: f7b62bce5c66dd183707795754d210f5117de7c4 +publish.zh.md: f999714d90397865d6f89e7ef02766c01f73683c diff --git a/docs/user/develop/basic/publish.md b/docs/user/develop/basic/publish.md index cde14e1ac2..f7b62bce5c 100644 --- a/docs/user/develop/basic/publish.md +++ b/docs/user/develop/basic/publish.md @@ -100,6 +100,8 @@ The first use initializes the profile (with `@deepseek-ai/dsh-base` as its first } ``` +A linked checkout keeps its own `node_modules`. Declare dsh packages whose instances the plugin must share with the host under both `peerDependencies` and `devDependencies`, as the harness packages do. The devDependency copy serves your type checker and standalone tests; peers present in the running dsh's runtime resolution use that installation's copy, whether dsh comes from npm, Desktop, or source. Keep third-party dependencies and stateless dsh utilities under `dependencies`. After changing `peerDependencies`, new resolutions during a plugin reload read the new declaration; this does not automatically reload already loaded modules. + Verify the layer without booting, then boot: ```sh diff --git a/docs/user/develop/basic/publish.zh.md b/docs/user/develop/basic/publish.zh.md index e588c52ba1..f999714d90 100644 --- a/docs/user/develop/basic/publish.zh.md +++ b/docs/user/develop/basic/publish.zh.md @@ -100,6 +100,8 @@ dsh plugin --profile demo add ./hello-plugin } ``` +通过链接安装的 checkout 保留自己的 `node_modules`。与 harness 自身的包一样,需要与宿主共享实例的 dsh 包同时声明在 `peerDependencies` 与 `devDependencies` 中。devDependency 副本供类型检查和独立测试使用;运行中 dsh 的 runtime resolution 已包含的 peer 使用该安装提供的副本,无论 dsh 来自 npm、Desktop 还是源码。第三方依赖和无状态 dsh 工具包放在 `dependencies` 中。修改 `peerDependencies` 后,重新加载插件时的新解析会读取新声明;这不会自动重载已经加载的模块。 + 先不启动、只验证该层,再启动: ```sh diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml index a8617d5fc1..b6de37fe50 100644 --- a/packages/boot/app-boot/README.i18n.yaml +++ b/packages/boot/app-boot/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md -README.md: 4763d5e0e22560373320b1f6a478e3a71212c4e6 -README.zh.md: 5fc90e3773ce152e8fca78c101753e746e986985 +README.md: bccf796fb679ebd7251baae5ae0952a8f6498ae1 +README.zh.md: fc421045ed45d639ec92be2ebe43a888c808ce0a diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md index 4763d5e0e2..bccf796fb6 100644 --- a/packages/boot/app-boot/README.md +++ b/packages/boot/app-boot/README.md @@ -114,10 +114,10 @@ This section explains how the outcomes above are realized and points at the code ### Design notes - **Profile launch data.** `ctx.profileContext` contains only profile locations, startup bundle names, parsed invocation overlays and the telemetry opt-out value. `readProfilePatches()` composes the supplied startup profile or reads current files at those locations; callers schedule and apply the result. -- **Process-local module resolution.** The launcher installs the runtime resolution as an interception on Node's internal ESM and CommonJS resolvers before profile rows mount. Node still owns exports, conditions, subpaths, module caches, and error codes; routed ESM failures report the original importer instead of the internal lookup anchor. `ctx.pluginPackages` exposes package metadata from the same runtime resolution without recording Entry imports; an installed runtime resolution is authoritative even for a miss, while low-level embedders that install the service without one retain native lookup. +- **Process-local module resolution.** The launcher installs the runtime resolution as an interception on Node's internal ESM and CommonJS resolvers before profile rows mount. Node still owns exports, conditions, subpaths, module caches, and error codes; routed ESM failures report the original importer instead of the internal lookup anchor. A profile package linked outside the profiles tree is a linked root. At `/node_modules`, the runtime resolution supplies names that have an entry and appear in the linked package's current `peerDependencies`; the same-named devDependency copy at this position is not loaded ([rule](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md)). `ctx.pluginPackages` exposes package metadata from the same runtime resolution without recording Entry imports; an installed runtime resolution is authoritative even for a miss, while low-level embedders that install the service without one retain native lookup. - **Two Loader builtins.** `mountRootInclude` registers `cordis:include` and `cordis:group` as Loader builtins: a group row gives one `isolate` realm to a provider and its consumers together, and an agent preset outside this workspace cannot resolve `@deepseek-ai/cordis-plugin-group` by name. Both load through the ambient module pipeline rather than the included tree's own specifier resolution. - **Consumer-owned strictness.** Ordinary Loader groups keep successful siblings. App-boot applies the global required-entry policy after initial settlement; agent presets and dynamic multi-entry compositions own and dispose their separate Loader subtree when they require all-or-nothing setup. App-boot reads failed fibers to report their recorded errors and coalesces duplicate Loader rejection notifications through one process checkpoint. -- **One runtime resolution.** The installation-first and ordered-bundle breadth-first traversal produces the runtime table. Runtime resolution creates no links; runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`, and every other name sees that directory as an ordinary ancestor. Profile load removes the `.dsh-module-fallback` projections that link-backend releases wrote into a profile; pnpm-installed packages stay. External bare targets selected by package `imports` use the same package order, while Node retains mapping, conditions, and exact target resolution. A complete successor may add package names atomically, while changing or removing an existing mapping requires restart. +- **One runtime resolution.** The installation-first and ordered-bundle breadth-first traversal produces the runtime table. Runtime resolution creates no links; runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`, and every other name sees that directory as an ordinary ancestor. Profile load removes the `.dsh-module-fallback` projections that link-backend releases wrote into a profile; pnpm-installed packages stay. External bare targets selected by package `imports` use the same package order, while Node retains mapping, conditions, and exact target resolution. A complete successor may add package names and update linked-root membership atomically within the existing package-mapping and local-name constraints; changing or removing an existing mapping, or pointing an existing linked root at another directory, requires restart. - **Application-owned profiles.** Application-owned profiles use the same runtime resolution. Resolution does not modify their `node_modules`; pnpm owns installed packages. - **Owned Workers.** Worker build banners import `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap` before bundled business code. Each Worker installs the structured-cloned runtime resolution in its own isolate. The bootstrap bundle has no static package imports. Source Worker entries retain their self-contained dependency closure, and third-party Workers receive no injection. - **Update completion.** App boot observes restart failures through the `internal/update` waterfall. Live patch reloads wait for the tree's fibers before auditing activation; `Fiber.update()` and `Entry.update()` alone do not establish restart success. @@ -178,6 +178,7 @@ Boot itself changes no request prefix. `addHarnessSourceSection` places its sour These limits describe when this boot library is a poor fit or needs special care. They are current package constraints, not a task backlog. - **Runtime resolution depends on Node internals** — supported Node versions require the native builtin-access addon and executable compatibility coverage. Only built Harness-owned Workers receive the runtime resolution bootstrap; third-party Workers and custom `vm` linkers keep native resolution. +- **Relinking a profile package needs a restart** — Node caches real paths, so changing the target of a profile link or a dependency link requires a process restart. - **Snapshot replay swapping is basename-specific** — only a config ending in `cordis.yml` or `cordis.yaml` maps to the sibling `cordis.snapshot.yml`; custom config names require caller-managed selection. - **Environment discovery is launch-scoped** — `loadLayeredEnv` reads only the invocation directory and Harness home once; it does not search parents or follow a workspace selected later. `loadEnv` remains the one-directory helper for non-product bins. - **A user patch replaces the whole matched config** — an id-targeted patch does not deep-merge, so a profile override restates the bundle fields it keeps. diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md index 5fc90e3773..fc421045ed 100644 --- a/packages/boot/app-boot/README.zh.md +++ b/packages/boot/app-boot/README.zh.md @@ -114,10 +114,10 @@ Loader 结算后,app-boot 在仅 optional 条目未激活时输出警告。如 ### 设计说明 - **Profile 启动数据。** `ctx.profileContext` 只包含 profile 位置、启动时组合包名称、已解析的调用级 overlay 与遥测退出值。`readProfilePatches()` 组合传入的启动 profile,或读取这些位置上的当前文件;调用方负责调度和应用结果。 -- **进程内模块解析。** runtime 解析会在挂载 profile 条目前,将 runtime resolution 作为拦截安装到 Node 的 ESM 与 CommonJS 内部 resolver。exports、conditions、subpath、模块缓存和错误码仍由 Node 负责;路由后的 ESM 失败会报告原始 importer,而不是内部查找锚点。`ctx.pluginPackages` 从同一 runtime resolution 提供 package metadata,不记录 Entry import;安装 runtime resolution 后,即使查询未命中也以 runtime resolution 为准,仅安装服务而未提供 runtime resolution 的底层嵌入方仍使用 Node 原生查找。 +- **进程内模块解析。** runtime 解析会在挂载 profile 条目前,将 runtime resolution 作为拦截安装到 Node 的 ESM 与 CommonJS 内部 resolver。exports、conditions、subpath、模块缓存和错误码仍由 Node 负责;路由后的 ESM 失败会报告原始 importer,而不是内部查找锚点。profile 中链接到 profiles 树外的包是一个 linked root。在 `/node_modules` 这一层,runtime resolution 提供同时具有表条目、且出现在该包当前 `peerDependencies` 中的包名;这个位置的同名 devDependency 副本不会被加载([规则](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md))。`ctx.pluginPackages` 从同一 runtime resolution 提供 package metadata,不记录 Entry import;安装 runtime resolution 后,即使查询未命中也以 runtime resolution 为准,仅安装服务而未提供 runtime resolution 的底层嵌入方仍使用 Node 原生查找。 - **两个 Loader builtin。** `mountRootInclude` 把 `cordis:include` 与 `cordis:group` 注册为 Loader builtin:group 行能把一个提供方与它的消费方放进同一个 `isolate` realm,而位于本工作区之外的 agent preset 无法按名称解析 `@deepseek-ai/cordis-plugin-group`。两者都通过宿主的模块管线加载,而非被包含树自身的说明符解析。 - **由 consumer 持有严格语义。** 普通 Loader group 保留成功 sibling。App-boot 在首次结算后应用全局 required-entry policy;agent preset 与动态多 entry 组合在需要 all-or-nothing setup 时,持有并拆卸各自的独立 Loader 子树。App-boot 读取 failed fiber 来报告已记录的错误,并在一个进程检查点内合并 Loader 重复的 rejection 通知。 -- **唯一 runtime resolution。** 安装优先、有序 bundle 逐根 breadth-first 遍历生成运行时表。runtime 解析不创建链接;runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置,其余包名把该目录当作普通祖先。profile 加载时删除 Link 后端发布版写进 profile 的 `.dsh-module-fallback` 投影;pnpm 安装的包保留。package `imports` 选中的外部 bare target 使用相同的选包顺序,映射、conditions 和精确 target 解析仍由 Node 负责。完整后继 runtime resolution 可以原子增加 package name,修改或删除既有映射则要求重启。 +- **唯一 runtime resolution。** 安装优先、有序 bundle 逐根 breadth-first 遍历生成运行时表。runtime 解析不创建链接;runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置,其余包名把该目录当作普通祖先。profile 加载时删除 Link 后端发布版写进 profile 的 `.dsh-module-fallback` 投影;pnpm 安装的包保留。package `imports` 选中的外部 bare target 使用相同的选包顺序,映射、conditions 和精确 target 解析仍由 Node 负责。完整后继 runtime resolution 可以在既有包映射和本地包名约束内原子增加 package name、更新 linked root 集合;修改或删除既有映射,或把既有 linked root 指向另一个目录,则要求重启。 - **应用自有 profile。** 应用自有 profile 使用相同的 runtime resolution。解析过程不修改其 `node_modules`;已安装包由 pnpm 管理。 - **自有 Worker。** Worker 构建 banner 会在业务 bundle 前导入 `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap`。每个 Worker 在自己的 isolate 中安装结构化克隆的 runtime resolution。bootstrap bundle 不静态导入任何包。源码 Worker 入口保留自包含依赖,第三方 Worker 不接受注入。 - **更新完成。** App boot 通过 `internal/update` waterfall 观察重启失败。实时 patch 重载在检查激活状态前等待配置树中的 fiber;单独调用 `Fiber.update()` 或 `Entry.update()` 不能确定重启成功。 @@ -178,6 +178,7 @@ Loader 结算后,app-boot 在仅 optional 条目未激活时输出警告。如 这些限制说明此启动库在何时不合适,或何时需要特别注意。它们是当前包约束,不是任务积压。 - **运行时解析依赖 Node 内部机制**——受支持的 Node 版本需要 native builtin access addon 和可执行兼容验证。只有构建后的 Harness 自有 Worker 接收 runtime resolution bootstrap;第三方 Worker 与自定义 `vm` linker 保持原生解析。 +- **重新链接 profile 包需要重启**——Node 缓存真实路径,因此改变 profile 链接或依赖链接的目标需要重启进程。 - **快照回放替换仅识别特定 basename**——只有以 `cordis.yml` 或 `cordis.yaml` 结尾的配置会映射到同级 `cordis.snapshot.yml`;自定义配置名称需要调用方自行选择。 - **环境发现以启动为界**——`loadLayeredEnv` 只读取一次调用目录与 harness home 中的 `.env`;它不搜索父目录,也不跟随之后选择的 workspace。`loadEnv` 仍是非产品 bin 使用的单目录 helper。 - **用户 patch 会替换匹配到的整个配置**——按 id 定位的 patch 不做深度合并,因此 profile 覆盖必须重述需要保留的组合包字段。 From 3e7af9cfbb358d12df62a711a0b6155e8faaa70c Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Mon, 21 Sep 2026 01:46:18 +0800 Subject: [PATCH 096/100] feat(boot): resolve linked plugin peers from the running installation --- .../headless/tests/profile-resolution.ts | 25 +- packages/boot/app-boot/src/index.ts | 1 + .../src/profile-resolution/resolver.ts | 232 +++++++++++------- packages/boot/app-boot/src/profile.ts | 52 +++- .../tests/profile-resolution-service.spec.ts | 3 +- ...rofile-resolution-worker-bootstrap.spec.ts | 1 + .../app-boot/tests/profile-resolution.spec.ts | 183 ++++++++++++++ .../boot/plugin-manager/tests/manager.spec.ts | 1 + .../plugin-inventory/tests/inventory.spec.ts | 2 +- 9 files changed, 406 insertions(+), 94 deletions(-) diff --git a/apps/cli/tests/profiles/headless/tests/profile-resolution.ts b/apps/cli/tests/profiles/headless/tests/profile-resolution.ts index 80601c27c6..e869e02282 100644 --- a/apps/cli/tests/profiles/headless/tests/profile-resolution.ts +++ b/apps/cli/tests/profiles/headless/tests/profile-resolution.ts @@ -33,6 +33,7 @@ interface ResolutionEvidence { sameCjsExternalLeaf: boolean externalManaged: boolean toolsInstance: boolean + pluginToolsInstance: boolean scheduler: boolean modules: string[] } @@ -91,7 +92,10 @@ export function testProfileResolution(mode: ExampleMode): void { } const sharedModules = join(home, 'profiles', 'node_modules') - const pluginDir = join(profileDir, 'node_modules', pluginName) + const installedPlugin = join(profileDir, 'node_modules', pluginName) + // npm-link keeps the plugin as a linked root outside the profile tree, so its own node_modules hold the + // developer's devDependency dsh-tools copy (stale, never read) and the declared dependency's install. + const pluginDir = layout === 'npm-link' ? join(root, 'work', pluginName) : installedPlugin const sharedExternal = join(sharedModules, externalName) const externalDir = layout === 'npm-link' ? join(root, 'external', externalName) : sharedExternal const externalLeaf = join(externalDir, 'node_modules', externalLeafName) @@ -100,8 +104,14 @@ export function testProfileResolution(mode: ExampleMode): void { const ancestorLeaf = join(home, 'node_modules', externalLeafName) await writePackage(pluginDir, { name: pluginName, version: '1.0.0', exports, dependencies: { [externalName]: '*' }, + peerDependencies: { '@deepseek-ai/dsh-tools': '*' }, devDependencies: { '@deepseek-ai/dsh-tools': '*' }, }, { - 'index.mjs': `export { external } from '${externalName}'\nexport function apply() {}`, + 'index.mjs': [ + `export { external } from '${externalName}'`, + "import Tools from '@deepseek-ai/dsh-tools'", + 'export { Tools as PluginTools }', + 'export function apply() {}', + ].join('\n'), 'index.cjs': `module.exports = require('${externalName}')`, }) for (const [dir, version] of [[externalDir, '3.0.0'], [ancestorExternal, '9.0.0']] as const) { @@ -124,7 +134,12 @@ export function testProfileResolution(mode: ExampleMode): void { }) for (const [target, link] of [ [staleTools, staleToolsLink], - ...layout === 'npm-link' ? [[externalDir, sharedExternal]] as const : [], + ...layout === 'npm-link' ? [ + [externalDir, sharedExternal], + [pluginDir, installedPlugin], + [staleTools, join(pluginDir, 'node_modules', '@deepseek-ai', 'dsh-tools')], + [externalDir, join(pluginDir, 'node_modules', externalName)], + ] as const : [], ] as const) { await mkdir(dirname(link), { recursive: true }) await symlink(target, link, 'junction') @@ -143,7 +158,7 @@ export function testProfileResolution(mode: ExampleMode): void { `import { leaf } from '${leafName}'`, `import { leaf as bridgeLeaf } from '${bridgeName}'`, `import { external } from '${externalName}'`, - `import { external as pluginExternal } from '${pluginName}'`, + `import { external as pluginExternal, PluginTools } from '${pluginName}'`, `import { leaf as externalLeaf } from ${JSON.stringify(pathToFileURL(join(externalLeaf, 'index.mjs')).href)}`, 'const require = createRequire(import.meta.url)', "export const inject = ['tools', 'agentLoop', 'loader']", @@ -165,6 +180,7 @@ export function testProfileResolution(mode: ExampleMode): void { ` sameCjsExternalLeaf: externalCjs.leaf === require(${JSON.stringify(join(externalLeaf, 'index.cjs'))}).leaf,`, ` externalManaged: entries.some(entry => [${JSON.stringify(externalName)}, ${JSON.stringify(externalLeafName)}].includes(entry.name)),`, ' toolsInstance: ctx.tools instanceof Tools,', + ' pluginToolsInstance: ctx.tools instanceof PluginTools,', " scheduler: typeof ctx.tools[TOOL_RUNTIME_SCHEDULER]?.prepare === 'function',", ' modules: [...ctx.loader.internal.loadCache.keys()]', ' .filter(url => /\\/packages\\/core\\/(?:tools|agent-loop)\\//.test(url)),', @@ -233,6 +249,7 @@ export function testProfileResolution(mode: ExampleMode): void { expect(evidence.sameCjsExternalLeaf).toBe(true) expect(evidence.externalManaged).toBe(false) expect(evidence.toolsInstance).toBe(true) + expect(evidence.pluginToolsInstance).toBe(true) expect(evidence.scheduler).toBe(true) expect(evidence.execArgv).toEqual(mode === 'src' ? launch.args.slice(0, 2) : []) for (const name of ['tools', 'agent-loop']) { diff --git a/packages/boot/app-boot/src/index.ts b/packages/boot/app-boot/src/index.ts index a4d82d0dba..e5ef8a79cf 100644 --- a/packages/boot/app-boot/src/index.ts +++ b/packages/boot/app-boot/src/index.ts @@ -55,6 +55,7 @@ export { type Profile, type ProfileLayer, type ProfileManifest, + type LinkedRoot, type RuntimeResolutionOptions, type RuntimeResolutionEntry, type RuntimeResolution, diff --git a/packages/boot/app-boot/src/profile-resolution/resolver.ts b/packages/boot/app-boot/src/profile-resolution/resolver.ts index cb6180cd19..feed6790aa 100644 --- a/packages/boot/app-boot/src/profile-resolution/resolver.ts +++ b/packages/boot/app-boot/src/profile-resolution/resolver.ts @@ -7,7 +7,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url' import { getEnvironmentData, setEnvironmentData } from 'node:worker_threads' import type { ModuleLoaderV1, ModuleLoaderV2, ResolveResult } from '@deepseek-ai/cordis-plugin-loader' import { imports as resolvePackageImports, type Package as ResolvePackageManifest } from 'resolve.exports' -import type { RuntimeResolutionEntry, RuntimeResolution } from '../profile.ts' +import type { LinkedRoot, RuntimeResolutionEntry, RuntimeResolution } from '../profile.ts' const WORKER_RESOLUTION_KEY = '@deepseek-ai/dsh-app-boot/profile-resolution' const EMPTY_ATTRIBUTES: ImportAttributes = Object.freeze({}) @@ -66,11 +66,34 @@ interface ResolutionRouteState { cjs?: string } +/** The lookup positions that one interception layer fixes on an importer's ancestor chain. */ +interface LayerPositions { + /** Search paths with this prefix lie below the layer and are answered by their physical content. */ + readonly localPrefix: string + /** Manifest anchoring Node's lookup at the layer's physical directory. */ + readonly nativeAfter: string + /** Manifest anchoring Node's lookup above the layer after a CommonJS subpath miss. */ + readonly after: string +} + +/** + * The interception layer of one importer. A profile's layer is its parent's node_modules and answers every entry + * for the active profile; a linked package's layer is its own node_modules, occupied only by the package's + * current peers and never memoized. + */ +type InterceptionLayer = + | LayerPositions & { readonly kind: 'profile'; readonly active: boolean } + | LayerPositions & { readonly kind: 'linked'; readonly root: LinkedRoot } + +interface CompiledLinkedRoot { + readonly root: LinkedRoot + readonly paths: readonly string[] + readonly layer: InterceptionLayer +} + interface ParentRoutes { readonly parent: string - /** Profile directory owning the importer; its node_modules are local, the first ancestor above it is the interception layer. */ - readonly localRoot: string - readonly activeProfile: boolean + readonly layer: InterceptionLayer readonly requests: Map selfReferenceName?: string | false | null } @@ -82,9 +105,8 @@ interface CompiledResolution { readonly profilesDir: string readonly profileDir: string | undefined readonly profilePaths: readonly string[] - readonly profileUrls: readonly string[] readonly profile: readonly string[] - readonly activeProfileUrls: readonly string[] + readonly linkedRoots: readonly CompiledLinkedRoot[] readonly localPackageNames: ReadonlySet readonly esmRoutes: ResolutionRoutes readonly cjsRoutes: ResolutionRoutes @@ -102,7 +124,7 @@ export interface RuntimeInterception { /** * Atomically publish an additive package table and fresh caches. * @param successor - fully constructed additive successor generation. - * @throws when the profile scope or an existing package mapping changes. + * @throws when the profile scope, an existing package mapping, or a linked root's real directory changes. */ replace(successor: RuntimeResolution): void /** Restore the native resolver methods. Interceptions dispose in reverse order. */ @@ -140,22 +162,69 @@ function prefixes(path: string): readonly string[] { } function compileResolution(resolution: RuntimeResolution): CompiledResolution { - const profilePaths = prefixes(resolution.profilesDir) - const profile = resolution.profileDir === undefined ? [] : prefixes(resolution.profileDir) return { entries: new Map(resolution.entries.map(entry => [entry.name, entry])), profilesDir: resolution.profilesDir, profileDir: resolution.profileDir, - profilePaths, - profileUrls: profilePaths.map(path => pathToFileURL(path).href), - profile, - activeProfileUrls: profile.map(path => pathToFileURL(path).href), + profilePaths: prefixes(resolution.profilesDir), + profile: resolution.profileDir === undefined ? [] : prefixes(resolution.profileDir), + linkedRoots: resolution.linkedRoots.map(root => ({ root, paths: prefixes(root.realPath), layer: computeLinkedLayer(root) })), localPackageNames: new Set(resolution.localPackageNames), esmRoutes: new Map(), cjsRoutes: new Map(), } } +/** + * The interception layer of a profile is `/node_modules`: an entry occupies its name there, so its + * subpath misses continue above it, and a name without an entry continues at it. + */ +function computeProfileLayer(dir: string, active: boolean): InterceptionLayer { + const profileParent = dirname(dir) + return { + kind: 'profile', active, + localPrefix: dir + sep, + nativeAfter: join(profileParent, 'package.json'), + after: join(dirname(profileParent), 'package.json'), + } +} + +/** + * A linked package keeps Node's lookup from its real path: `/node_modules` is its interception layer, + * deeper node_modules directories are local, and the layer above it belongs to the real parent directory. + */ +function computeLinkedLayer(root: LinkedRoot): InterceptionLayer { + return { + kind: 'linked', root, + localPrefix: join(root.realPath, 'node_modules') + sep, + nativeAfter: join(root.realPath, 'package.json'), + after: join(dirname(root.realPath), 'package.json'), + } +} + +/** The interception layer of a module path: from its profile directory inside a profiles tree, or its linked root. */ +function findInterceptionLayer(path: string, resolution: CompiledResolution): InterceptionLayer | undefined { + const treeRoot = resolution.profilePaths.find(prefix => path.startsWith(prefix)) + const activeProfile = resolution.profile.find(prefix => path.startsWith(prefix)) + const dir = treeRoot !== undefined ? profileChild(path, treeRoot) : activeProfile?.slice(0, -1) + if (dir !== undefined) return computeProfileLayer(dir, activeProfile !== undefined) + return resolution.linkedRoots.find(candidate => startsWithin(path, candidate.paths))?.layer +} + +/** Package names the linked package's manifest currently lists as peers; an unreadable manifest lists none. */ +function readLinkedPeerNames(root: LinkedRoot): ReadonlySet { + try { + const manifest = JSON.parse(readFileSync(join(root.realPath, 'package.json'), 'utf8')) as { + peerDependencies?: unknown + } + const peers = manifest.peerDependencies + return new Set(peers !== null && typeof peers === 'object' ? Object.keys(peers) : []) + } catch (_error) { + // Node reports the unreadable or invalid manifest itself when it resolves the package's own imports. + return new Set() + } +} + function startsWithin(path: string, roots: readonly string[]): boolean { for (const root of roots) { if (path.startsWith(root)) return true @@ -330,9 +399,48 @@ class ResolutionRouter { throw new Error(`profile resolution: overriding ${JSON.stringify(name)} locally requires a process restart`) } } + // Node memoizes real paths for the process lifetime, so a link that now points elsewhere would keep + // answering from its former directory. + for (const { root } of this.current.linkedRoots) { + const next = successor.linkedRoots.find(candidate => candidate.name === root.name) + if (next !== undefined && !sameResolution(root.realPath, next.realPath)) { + throw new Error(`profile resolution: relinking ${JSON.stringify(root.name)} requires a process restart`) + } + } this.current = compileResolution(successor) } + /** Whether a module path has an interception layer: it lies in the profiles tree, the active profile, or a linked root. */ + hasInterceptionLayerForPath(path: string): boolean { + return findInterceptionLayer(path, this.current) !== undefined + } + + /** Whether an importer URL is scoped; the answer is memoized with the importer's routes. */ + hasInterceptionLayerForUrl(parentURL: string): boolean { + return this.getOrCreateParentRoutesForUrl(parentURL) !== false + } + + private createParentRoutes(parent: string, resolution: CompiledResolution): ParentRoutes | undefined { + const layer = findInterceptionLayer(parent, resolution) + return layer === undefined ? undefined : { parent, layer, requests: new Map() } + } + + private getOrCreateParentRoutesForUrl(parentURL: string): ParentRoutes | false { + const resolution = this.current + let parentRoutes = resolution.esmRoutes.get(parentURL) + if (parentRoutes !== undefined) return parentRoutes + let parent: string | undefined + try { + parent = fileURLToPath(parentURL) + } catch { + // Only file URLs can lie inside a profile tree or linked root. + parent = undefined + } + parentRoutes = parent === undefined ? false : this.createParentRoutes(parent, resolution) ?? false + resolution.esmRoutes.set(parentURL, parentRoutes) + return parentRoutes + } + private routeScoped( request: string, parentRoutes: ParentRoutes, @@ -341,25 +449,25 @@ class ResolutionRouter { nativeResolve?: (searchPaths: readonly string[]) => string, cacheable = false, ): ResolutionRouteState | undefined { - const { parent, localRoot, requests } = parentRoutes + const { parent, layer, requests } = parentRoutes + const memo = layer.kind === 'profile' const name = barePackageName(request) if (name === undefined) return undefined - if (parentRoutes.selfReferenceName === undefined) { + if (parentRoutes.selfReferenceName === undefined || !memo) { parentRoutes.selfReferenceName = selfReferenceName(parent) } if (parentRoutes.selfReferenceName === name || parentRoutes.selfReferenceName === null) { const state = { route: { kind: 'native' as const } } - requests.set(request, state) + if (memo) requests.set(request, state) return state } const target = resolution.entries.get(name) const candidates: string[] = [] const localSearchPaths: string[] = [] - const localPrefix = localRoot + sep for (const searchPath of createRequire(parent).resolve.paths(name) as string[]) { - if (!searchPath.startsWith(localPrefix)) break + if (!searchPath.startsWith(layer.localPrefix)) break localSearchPaths.push(searchPath) const candidate = localPackageCandidate(searchPath, name, flavor) if (candidate !== undefined) candidates.push(candidate) @@ -375,9 +483,9 @@ class ResolutionRouter { const state = { route: { kind: 'native' as const, packageDir: selected }, packageDir: selected, - ...(cacheable ? { cjs: resolved } : {}), + ...(cacheable && memo ? { cjs: resolved } : {}), } - requests.set(request, state) + if (memo) requests.set(request, state) return state } } catch (error) { @@ -389,21 +497,19 @@ class ResolutionRouter { route: { kind: 'native' as const, packageDir: selected }, packageDir: selected, } - requests.set(request, state) + if (memo) requests.set(request, state) return state } } - // The interception layer is `/node_modules`: a runtime resolution entry occupies its name - // there, so its subpath misses continue above it; a name without an entry continues at it. - const profileParent = dirname(localRoot) - const eligible = target?.scope === 'installation' - || (target?.scope === 'profile' && parentRoutes.activeProfile) - const route: ResolutionRoute = eligible - ? { kind: 'interception', entry: target, after: join(dirname(profileParent), 'package.json') } - : { kind: 'native-after-interception', parent: join(profileParent, 'package.json') } + // An entry occupies its name at the interception layer; below a linked root only the names its manifest + // currently lists as peers are occupied. + const route: ResolutionRoute = target !== undefined + && (layer.kind === 'linked' ? readLinkedPeerNames(layer.root).has(name) : target.scope === 'installation' || layer.active) + ? { kind: 'interception', entry: target, after: layer.after } + : { kind: 'native-after-interception', parent: layer.nativeAfter } const state: ResolutionRouteState = { route } - if (route.kind === 'interception') requests.set(request, state) + if (route.kind === 'interception' && memo) requests.set(request, state) return state } @@ -411,7 +517,8 @@ class ResolutionRouter { request: string, parentRoutes: ParentRoutes, resolution: CompiledResolution, ): ResolutionRouteState | undefined { const name = barePackageName(request) - if (name === undefined || !parentRoutes.activeProfile || !resolution.localPackageNames.has(name)) return undefined + const { layer } = parentRoutes + if (name === undefined || layer.kind !== 'profile' || !layer.active || !resolution.localPackageNames.has(name)) return undefined const state = { route: { kind: 'native' as const } } parentRoutes.requests.set(request, state) return state @@ -419,33 +526,10 @@ class ResolutionRouter { routeUrl(request: string, parentURL: string): ResolutionRouteState | undefined { const resolution = this.current - let parentRoutes = resolution.esmRoutes.get(parentURL) + const parentRoutes = this.getOrCreateParentRoutesForUrl(parentURL) if (parentRoutes === false) return undefined - const cached = parentRoutes?.requests.get(request) + const cached = parentRoutes.requests.get(request) if (cached !== undefined) return cached - if (parentRoutes === undefined) { - const profileIndex = resolution.profileUrls.findIndex(prefix => parentURL.startsWith(prefix)) - const activeProfileIndex = resolution.activeProfileUrls.findIndex(prefix => parentURL.startsWith(prefix)) - if (profileIndex < 0 && activeProfileIndex < 0) { - resolution.esmRoutes.set(parentURL, false) - return undefined - } - let parent: string - try { - parent = fileURLToPath(parentURL) - } catch { - resolution.esmRoutes.set(parentURL, false) - return undefined - } - const treeRoot = resolution.profilePaths[profileIndex] - const localRoot = treeRoot !== undefined - ? profileChild(parent, treeRoot) - : resolution.profile[activeProfileIndex]?.slice(0, -1) - /* v8 ignore next -- one matching index was established above */ - if (localRoot === undefined) return undefined - parentRoutes = { parent, localRoot, activeProfile: activeProfileIndex >= 0, requests: new Map() } - resolution.esmRoutes.set(parentURL, parentRoutes) - } const local = this.routeLocalPackage(request, parentRoutes, resolution) if (local !== undefined) return local return this.routeScoped(request, parentRoutes, resolution, 'esm') @@ -460,17 +544,9 @@ class ResolutionRouter { const cached = parentRoutes?.requests.get(request) if (cached !== undefined) return cached if (parentRoutes === undefined) { - const treeRoot = resolution.profilePaths.find(prefix => parent.startsWith(prefix)) - const activeProfile = resolution.profile.find(prefix => parent.startsWith(prefix)) - const localRoot = treeRoot !== undefined ? profileChild(parent, treeRoot) : activeProfile?.slice(0, -1) - if (localRoot !== undefined) { - parentRoutes = { parent, localRoot, activeProfile: activeProfile !== undefined, requests: new Map() } - resolution.cjsRoutes.set(parent, parentRoutes) - } - } - if (parentRoutes === undefined) { - resolution.cjsRoutes.set(parent, false) - return undefined + parentRoutes = this.createParentRoutes(parent, resolution) ?? false + resolution.cjsRoutes.set(parent, parentRoutes) + if (parentRoutes === false) return undefined } return this.routeScoped(request, parentRoutes, resolution, 'cjs', nativeResolve, cacheable) } @@ -603,14 +679,6 @@ export function installRuntimeInterception( ): RuntimeInterception { const router = new ResolutionRouter(resolution) const { esm, esmDefaultResolve, esmConditions, cjs, cjsConditions, modern } = internalModules() - const esmScope = new Map() - const profilePaths = [ - ...prefixes(resolution.profilesDir), - ...(resolution.profileDir === undefined ? [] : prefixes(resolution.profileDir)), - ] - const profileUrls = profilePaths.map(path => pathToFileURL(path).href) - let recentEsmParent: string | undefined - let recentEsmScoped = false let delegatedEsm: { parent: string | undefined; request: string } | undefined const adaptEsm = (native: EsmResolve): EsmResolve => { @@ -620,17 +688,7 @@ export function installRuntimeInterception( if (delegated !== undefined && delegated.parent === parent && delegated.request === request) { return native(request, parent, attributes) } - if (parent === undefined) return native(request, parent, attributes) - let scoped = recentEsmParent === parent ? recentEsmScoped : esmScope.get(parent) - if (scoped === undefined) { - scoped = startsWithin(parent, profileUrls) - esmScope.set(parent, scoped) - } - if (recentEsmParent !== parent) { - recentEsmParent = parent - recentEsmScoped = scoped - } - if (!scoped) return native(request, parent, attributes) + if (parent === undefined || !router.hasInterceptionLayerForUrl(parent)) return native(request, parent, attributes) const state = router.routeUrl(request, parent) if (state === undefined) { const target = request[0] === '#' @@ -796,7 +854,7 @@ export function installRuntimeInterception( explicit === undefined && cacheable, ) if (state === undefined) { - const scoped = startsWithin(parentFilename, profilePaths) + const scoped = router.hasInterceptionLayerForPath(parentFilename) const conditions = options?.conditions ?? cjsConditions const target = request[0] === '#' && scoped ? packageImportsTarget(parentFilename, request, conditions) diff --git a/packages/boot/app-boot/src/profile.ts b/packages/boot/app-boot/src/profile.ts index 00b8198d72..d6e7cb183e 100644 --- a/packages/boot/app-boot/src/profile.ts +++ b/packages/boot/app-boot/src/profile.ts @@ -23,7 +23,7 @@ import { createRequire } from 'node:module' import { existsSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, unlinkSync, writeFileSync } from 'node:fs' -import { basename, dirname, join, resolve, sep } from 'node:path' +import { basename, dirname, join, relative, resolve, sep } from 'node:path' import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader' import { applyEntryPatches, type PatchOptions } from '@deepseek-ai/cordis-plugin-include' import { resolveDshHome } from '@deepseek-ai/dsh-home-paths' @@ -112,6 +112,20 @@ export interface RuntimeResolutionEntry { readonly scope: 'installation' | 'profile' } +/** + * A profile package whose `node_modules` entry is a symlink or junction to a directory outside the profiles tree. + * Importers below `realPath` keep Node's lookup from the real path; `/node_modules` is their interception + * layer, occupied only by the names the package's current manifest lists under `peerDependencies`. + */ +export interface LinkedRoot { + /** Package name of the profile `node_modules` entry, including its scope. */ + readonly name: string + /** The symlink or junction path under the active profile's node_modules. */ + readonly linkPath: string + /** Real directory the link resolves to; it lies outside the profiles tree and holds a package.json. */ + readonly realPath: string +} + /** Complete immutable package table for one profile launch. */ export interface RuntimeResolution { /** Directory containing every profile; its node_modules is the interception layer. */ @@ -122,6 +136,8 @@ export interface RuntimeResolution { readonly localPackageNames: readonly string[] /** Installation-scope entries followed by profile-scope entries in precedence order. */ readonly entries: readonly RuntimeResolutionEntry[] + /** Active profile packages linked to directories outside the profiles tree, sorted by name. */ + readonly linkedRoots: readonly LinkedRoot[] } /** @@ -258,6 +274,38 @@ function symlinksUnder(modules: string): string[] { return links } +/** + * Active profile `node_modules` entries linked to package directories outside the profiles tree. + * Links whose target is missing, lies inside the profiles tree, or holds no package.json are not roots. + */ +function linkedProfileRoots(profile: Profile, profilesDir: string): LinkedRoot[] { + const modules = join(profile.dir, 'node_modules') + let tree: string + try { + tree = realModuleDirectory(profilesDir) + sep + } catch (error) { + // A profiles tree that is not materialized yet holds no links. + /* v8 ignore next -- a non-ENOENT realpath failure requires a host filesystem fault */ + if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error + tree = resolve(profilesDir) + sep + } + const roots: LinkedRoot[] = [] + for (const linkPath of symlinksUnder(modules)) { + let realPath: string + try { + realPath = realModuleDirectory(linkPath) + } catch (error) { + // A dangling link is not a package Node can load from the profile. + /* v8 ignore next -- a non-ENOENT realpath failure requires a host filesystem fault */ + if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error + continue + } + if (realPath.startsWith(tree) || !existsSync(join(realPath, 'package.json'))) continue + roots.push({ name: relative(modules, linkPath).split(sep).join('/'), linkPath, realPath }) + } + return roots.sort((left, right) => left.name.localeCompare(right.name)) +} + /** Whether a symlink's target directory is `root` or lies below it. */ function pointsInto(link: string, root: string): boolean { try { @@ -368,11 +416,13 @@ export async function createRuntimeResolution( const profilePackages: ReadonlyMap = profile === undefined ? new Map() : collectProfileScopePackages(profile, packageNames, profileDeclarers, profileVersions) + const linkedRoots = profile === undefined ? [] : linkedProfileRoots(profile, profilesDir) // The Promise return type is the pre-stable API; construction has no asynchronous step. return await Promise.resolve(Object.freeze({ profilesDir, profileDir: profile?.dir, localPackageNames: Object.freeze(localPackageNames), + linkedRoots: Object.freeze(linkedRoots.map(root => Object.freeze(root))), entries: Object.freeze([ ...[...packageDirs].map(([name, packageDir]) => Object.freeze({ name, packageDir, version: versions.get(name), diff --git a/packages/boot/app-boot/tests/profile-resolution-service.spec.ts b/packages/boot/app-boot/tests/profile-resolution-service.spec.ts index 1be59df4f1..2ba557170c 100644 --- a/packages/boot/app-boot/tests/profile-resolution-service.spec.ts +++ b/packages/boot/app-boot/tests/profile-resolution-service.spec.ts @@ -47,6 +47,7 @@ function resolution( profilesDir, profileDir, localPackageNames: [], + linkedRoots: [], entries: [{ name: 'metadata-lib', packageDir, version, declarer, scope: 'installation' }], } } @@ -123,7 +124,7 @@ describe('profile package metadata service', () => { expect(ctx.pluginPackages.packageOf('missing-package', parentURL)).toBeUndefined() expect(ctx.pluginPackages.packageOf('@scope', parentURL)).toBeUndefined() expect(() => { ctx.pluginPackages.replace({ - profilesDir: join(root, 'profiles'), profileDir: undefined, localPackageNames: [], entries: [], + profilesDir: join(root, 'profiles'), profileDir: undefined, localPackageNames: [], linkedRoots: [], entries: [], }) }).toThrow(/runtime resolution is not installed/u) }) diff --git a/packages/boot/app-boot/tests/profile-resolution-worker-bootstrap.spec.ts b/packages/boot/app-boot/tests/profile-resolution-worker-bootstrap.spec.ts index 205e6a7e57..9ca24028c6 100644 --- a/packages/boot/app-boot/tests/profile-resolution-worker-bootstrap.spec.ts +++ b/packages/boot/app-boot/tests/profile-resolution-worker-bootstrap.spec.ts @@ -34,6 +34,7 @@ it('installs the inherited resolution', async () => { profilesDir: '/profiles', profileDir: '/profiles/test', localPackageNames: [], + linkedRoots: [], entries: [], } harness.data = { resolution } diff --git a/packages/boot/app-boot/tests/profile-resolution.spec.ts b/packages/boot/app-boot/tests/profile-resolution.spec.ts index 6f9e517a76..01cce9660c 100644 --- a/packages/boot/app-boot/tests/profile-resolution.spec.ts +++ b/packages/boot/app-boot/tests/profile-resolution.spec.ts @@ -1332,6 +1332,7 @@ describe('runtime resolution', { concurrent: false }, () => { profilesDir, profileDir: join(profilesDir, 'web'), localPackageNames: [], + linkedRoots: [], entries: [], }) registrations.push(registration) @@ -1595,6 +1596,14 @@ describe('runtime resolution', { concurrent: false }, () => { registration.replace({ ...first, localPackageNames: ['new-local'] }) registration.replace({ ...first, localPackageNames: ['new-local'] }) expect(() => { registration.replace(first) }).toThrow(/removing local package/u) + const linked = { name: 'linked-plugin', linkPath: join(f.profile.dir, 'node_modules', 'linked-plugin'), realPath: join(f.root, 'work', 'a') } + const withLocal = { ...first, localPackageNames: ['new-local'] } + registration.replace({ ...withLocal, linkedRoots: [linked] }) + registration.replace({ ...withLocal, linkedRoots: [] }) + registration.replace({ ...withLocal, linkedRoots: [linked] }) + expect(() => { + registration.replace({ ...withLocal, linkedRoots: [{ ...linked, realPath: join(f.root, 'work', 'b') }] }) + }).toThrow(/relinking "linked-plugin" requires a process restart/u) expect(registration.packageDir( '@deepseek-ai/dsh-core', pathToFileURL(join(f.profile.dir, 'entry.mjs')).href, )).toBe(f.installed) @@ -1661,6 +1670,180 @@ describe('runtime resolution', { concurrent: false }, () => { expect(getEnvironmentData(key)).toBe(previous) }) + it('records active profile packages linked outside the profiles tree as linked roots', async () => { + const f = fixture() + const modules = join(f.profile.dir, 'node_modules') + const outside = join(f.root, 'work', 'my-plugin') + pkg(outside, 'my-plugin', 5) + const scopedOutside = join(f.root, 'work', 'scoped') + pkg(scopedOutside, '@scope/linked', 6) + const inside = join(f.root, 'profiles', 'node_modules', 'inside-lib') + pkg(inside, 'inside-lib', 7) + const bare = join(f.root, 'work', 'bare') + mkdirSync(bare, { recursive: true }) + const dangling = join(f.root, 'work', 'dangling') + mkdirSync(dangling, { recursive: true }) + const linkType = process.platform === 'win32' ? 'junction' : 'dir' + mkdirSync(join(modules, '@scope'), { recursive: true }) + symlinkSync(outside, join(modules, 'my-plugin'), linkType) + symlinkSync(scopedOutside, join(modules, '@scope', 'linked'), linkType) + symlinkSync(inside, join(modules, 'inside-lib'), linkType) + symlinkSync(bare, join(modules, 'bare-dir'), linkType) + symlinkSync(dangling, join(modules, 'dangling'), linkType) + rmSync(dangling, { recursive: true }) + pkg(join(modules, 'installed'), 'installed', 8) + const resolution = await resolutionOf(f) + expect(resolution.linkedRoots).toEqual([ + { name: '@scope/linked', linkPath: join(modules, '@scope', 'linked'), realPath: scopedOutside }, + { name: 'my-plugin', linkPath: join(modules, 'my-plugin'), realPath: outside }, + ]) + expect(Object.isFrozen(resolution.linkedRoots)).toBe(true) + expect(Object.isFrozen(resolution.linkedRoots[0])).toBe(true) + const withoutProfile = await createRuntimeResolution({ installAnchor: f.installAnchor, home: f.root }) + expect(withoutProfile.linkedRoots).toEqual([]) + const unmaterialized = await createRuntimeResolution({ + installAnchor: f.installAnchor, + profile: { ...f.profile, dir: join(f.root, 'later', 'profiles', 'web') }, + home: join(f.root, 'later'), + }) + expect(unmaterialized.linkedRoots).toEqual([]) + }) + + /** A plugin repository linked into the profile, with the manifest a plugin developer keeps for type checking. */ + function linkedPluginFixture(peerDependencies: Record | undefined = { '@deepseek-ai/dsh-core': '*' }): { + f: ReturnType + linkedRoot: string + helper: string + writeManifest: (peers: Record | undefined) => void + } { + const f = fixture() + const installDir = dirname(f.installAnchor) + pkg(installDir, '@deepseek-ai/dsh', 0, { '@deepseek-ai/dsh-core': '*', '@deepseek-ai/dsh-util': '*' }) + pkg(join(installDir, 'node_modules', '@deepseek-ai', 'dsh-util'), '@deepseek-ai/dsh-util', 2) + const linkedRoot = join(f.root, 'work', 'my-plugin') + const writeManifest = (peers: Record | undefined): void => { + file(join(linkedRoot, 'package.json'), JSON.stringify({ + name: 'my-plugin', + version: '30.0.0', + type: 'module', + exports: { import: './index.js', require: './index.cjs' }, + imports: { '#core': '@deepseek-ai/dsh-core' }, + dependencies: { 'zod': '*', '@deepseek-ai/dsh-util': '*', 'helper': '*' }, + ...(peers === undefined ? {} : { peerDependencies: peers }), + devDependencies: { '@deepseek-ai/dsh-core': '*' }, + })) + } + writeManifest(peerDependencies) + file(join(linkedRoot, 'index.js'), 'export const marker = 30\n') + file(join(linkedRoot, 'index.cjs'), 'module.exports = { marker: 30 }\n') + // The devDependency copy a type checker needs, the plugin's own third-party version, and a dsh package + // declared as a plain dependency. + pkg(join(linkedRoot, 'node_modules', '@deepseek-ai', 'dsh-core'), '@deepseek-ai/dsh-core', 21) + pkg(join(linkedRoot, 'node_modules', 'zod'), 'zod', 22) + pkg(join(linkedRoot, 'node_modules', '@deepseek-ai', 'dsh-util'), '@deepseek-ai/dsh-util', 23) + pkg(join(f.root, 'work', 'node_modules', 'left-pad'), 'left-pad', 24) + // A transitive dependency in pnpm's isolated layout, with a sibling of its own. + const helper = join(linkedRoot, 'node_modules', '.pnpm', 'helper@1.0.0', 'node_modules', 'helper') + pkg(helper, 'helper', 25, { sibling: '*' }, { '@deepseek-ai/dsh-core': '*' }) + pkg(join(dirname(helper), 'sibling'), 'sibling', 26) + const linkType = process.platform === 'win32' ? 'junction' : 'dir' + symlinkSync(helper, join(linkedRoot, 'node_modules', 'helper'), linkType) + const modules = join(f.profile.dir, 'node_modules') + mkdirSync(modules, { recursive: true }) + symlinkSync(linkedRoot, join(modules, 'my-plugin'), linkType) + file(join(f.profile.dir, 'package.json'), JSON.stringify({ + name: 'dsh-profile-web', private: true, dependencies: { 'my-plugin': '*' }, + })) + return { f, linkedRoot, helper, writeManifest } + } + + it('occupies only the peer names of a linked plugin at its own node_modules', async () => { + const { f, linkedRoot, helper } = linkedPluginFixture() + const registration = installRuntimeInterception(await resolutionOf(f)) + registrations.push(registration) + const require = createRequire(join(linkedRoot, 'entry.cjs')) + const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href + const expectResolution = async ( + name: string, dir: string, marker: number, from: { require: NodeJS.Require; parent: string } = { require, parent }, + ): Promise => { + expect(from.require(name), name).toEqual({ marker }) + expect(from.require.resolve(name), name).toBe(join(dir, 'index.cjs')) + expect(resolveFrom(name, from.parent), name).toBe(pathToFileURL(join(dir, 'index.js')).href) + expect(await importFrom(name, from.parent), name).toMatchObject({ marker }) + expect(registration.packageDir(name, from.parent), name).toBe(dir) + } + // The peer comes from the running installation; its devDependency copy is never read. + await expectResolution('@deepseek-ai/dsh-core', f.installed, 1) + // A cache-busting query on the importer, as hot module replacement re-imports it, changes nothing. + expect(resolveFrom('@deepseek-ai/dsh-core', `${parent}?t=1`)).toBe(pathToFileURL(join(f.installed, 'index.js')).href) + expect(resolveFrom('zod', `${parent}?t=1`)).toBe(pathToFileURL(join(linkedRoot, 'node_modules', 'zod', 'index.js')).href) + // Plain dependencies keep the plugin's own copies, including a dsh package declared as one. + await expectResolution('zod', join(linkedRoot, 'node_modules', 'zod'), 22) + await expectResolution('@deepseek-ai/dsh-util', join(linkedRoot, 'node_modules', '@deepseek-ai', 'dsh-util'), 23) + // An undeclared name without an entry follows the real ancestor chain. + await expectResolution('left-pad', join(f.root, 'work', 'node_modules', 'left-pad'), 24) + // Package imports and self-references keep their Node semantics inside the linked package. + expect(require.resolve('#core')).toBe(join(f.installed, 'index.cjs')) + expect(resolveFrom('#core', parent)).toBe(pathToFileURL(join(f.installed, 'index.js')).href) + expect(require('my-plugin')).toEqual({ marker: 30 }) + expect(resolveFrom('my-plugin', parent)).toBe(pathToFileURL(join(linkedRoot, 'index.js')).href) + // A transitive dependency sees its own local layer first and the linked package's peers at the layer above. + const helperImporter = { require: createRequire(join(helper, 'entry.cjs')), parent: pathToFileURL(join(helper, 'entry.mjs')).href } + await expectResolution('sibling', join(dirname(helper), 'sibling'), 26, helperImporter) + await expectResolution('@deepseek-ai/dsh-core', f.installed, 1, helperImporter) + // The profile still reaches the linked plugin through Node's own symlink handling. + const profileRequire = createRequire(join(f.profile.dir, 'entry.cjs')) + expect(profileRequire.resolve('my-plugin')).toBe(join(linkedRoot, 'index.cjs')) + expect(resolveFrom('my-plugin', pathToFileURL(join(f.profile.dir, 'entry.mjs')).href)) + .toBe(pathToFileURL(join(linkedRoot, 'index.js')).href) + }) + + it('continues above a linked plugin after a CommonJS subpath miss in an occupied peer', async () => { + const { f, linkedRoot } = linkedPluginFixture() + file(join(f.installed, 'package.json'), JSON.stringify({ name: '@deepseek-ai/dsh-core', version: '1.0.0', main: './index.cjs' })) + const above = join(f.root, 'work', 'node_modules', '@deepseek-ai', 'dsh-core') + file(join(above, 'package.json'), JSON.stringify({ name: '@deepseek-ai/dsh-core', version: '3.0.0' })) + file(join(above, 'sub.cjs'), 'module.exports = { marker: 3 }\n') + file(join(linkedRoot, 'node_modules', '@deepseek-ai', 'dsh-core', 'sub.cjs'), 'module.exports = { marker: 21 }\n') + const registration = installRuntimeInterception(await resolutionOf(f)) + registrations.push(registration) + const require = createRequire(join(linkedRoot, 'entry.cjs')) + expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(f.installed, 'index.cjs')) + // The occupied name never falls back to the devDependency copy at the same layer. + expect(require.resolve('@deepseek-ai/dsh-core/sub.cjs')).toBe(join(above, 'sub.cjs')) + expect(require('@deepseek-ai/dsh-core/sub.cjs')).toEqual({ marker: 3 }) + }) + + it('reads a linked plugin manifest at every resolution', async () => { + const { f, linkedRoot, writeManifest } = linkedPluginFixture({}) + const registration = installRuntimeInterception(await resolutionOf(f)) + registrations.push(registration) + const devCopy = join(linkedRoot, 'node_modules', '@deepseek-ai', 'dsh-core') + const require = createRequire(join(linkedRoot, 'entry.cjs')) + const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href + expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(devCopy, 'index.cjs')) + expect(resolveFrom('@deepseek-ai/dsh-core', parent)).toBe(pathToFileURL(join(devCopy, 'index.js')).href) + expect(registration.packageDir('@deepseek-ai/dsh-core', parent)).toBe(devCopy) + + writeManifest({ '@deepseek-ai/dsh-core': '*' }) + // No memo holds for a linked importer, and the occupied name delegates from the entry's declaring manifest, + // a parent Node has never resolved this request from. + expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(f.installed, 'index.cjs')) + expect(registration.packageDir('@deepseek-ai/dsh-core', parent)).toBe(f.installed) + expect(resolveFrom('@deepseek-ai/dsh-core', parent)).toBe(pathToFileURL(join(f.installed, 'index.js')).href) + expect(await importFrom('@deepseek-ai/dsh-core', parent)).toMatchObject({ marker: 1 }) + + writeManifest({}) + expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(devCopy, 'index.cjs')) + expect(resolveFrom('@deepseek-ai/dsh-core', parent)).toBe(pathToFileURL(join(devCopy, 'index.js')).href) + expect(registration.packageDir('@deepseek-ai/dsh-core', parent)).toBe(devCopy) + writeManifest(undefined) + expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(devCopy, 'index.cjs')) + // Without a manifest the linked package occupies nothing. + rmSync(join(linkedRoot, 'package.json')) + expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(devCopy, 'index.cjs')) + }) + it('restores CommonJS resolution when the registration is disposed', async () => { const f = fixture() const registration = installRuntimeInterception(await resolutionOf(f)) diff --git a/packages/boot/plugin-manager/tests/manager.spec.ts b/packages/boot/plugin-manager/tests/manager.spec.ts index 19966e47b8..16fbed9650 100644 --- a/packages/boot/plugin-manager/tests/manager.spec.ts +++ b/packages/boot/plugin-manager/tests/manager.spec.ts @@ -217,6 +217,7 @@ it.each(['native', 'runtime'] as const)('reads a disabled bundle and its indepen const resolution: RuntimeResolution = { profilesDir: join(profile.home, 'profiles'), profileDir: dir, localPackageNames: Object.keys(manifest.dependencies), + linkedRoots: [], entries: [{ name: 'local-child', packageDir: child, version: undefined, declarer: join(child, 'package.json'), scope: 'installation' }], } diff --git a/packages/host/plugin-inventory/tests/inventory.spec.ts b/packages/host/plugin-inventory/tests/inventory.spec.ts index c403d6fe76..f55ca87a38 100644 --- a/packages/host/plugin-inventory/tests/inventory.spec.ts +++ b/packages/host/plugin-inventory/tests/inventory.spec.ts @@ -51,7 +51,7 @@ function metadataFixture(mode: 'native' | 'runtime') { ? join(root, 'installation', 'node_modules', 'local-plugin') : join(root, 'node_modules', 'local-plugin') const resolution: RuntimeResolution = { - profilesDir, profileDir, localPackageNames: [], + profilesDir, profileDir, localPackageNames: [], linkedRoots: [], entries: [{ name: 'local-plugin', packageDir: dir, version: undefined, declarer: join(dir, 'package.json'), scope: 'installation' }], } From c9d4b7561d8f096a9fca79175029d6eb9e4f37b8 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Mon, 21 Sep 2026 05:01:43 +0800 Subject: [PATCH 097/100] fix(boot): apply linked peers at each native lookup position --- ...9-profile-resolution-generations.i18n.yaml | 4 +- ...26-09-09-profile-resolution-generations.md | 10 +- ...09-09-profile-resolution-generations.zh.md | 10 +- ...-profile-resolution-lookup-order.i18n.yaml | 4 +- ...6-09-19-profile-resolution-lookup-order.md | 56 +- ...9-19-profile-resolution-lookup-order.zh.md | 56 +- .../headless/tests/profile-resolution.ts | 33 +- docs/user/develop/basic/publish.i18n.yaml | 4 +- docs/user/develop/basic/publish.md | 4 +- docs/user/develop/basic/publish.zh.md | 4 +- packages/boot/app-boot/README.i18n.yaml | 4 +- packages/boot/app-boot/README.md | 5 +- packages/boot/app-boot/README.zh.md | 5 +- .../src/profile-resolution/resolver.ts | 199 +++--- packages/boot/app-boot/src/profile.ts | 15 +- .../tests/linked-resolution-matrix.spec.ts | 644 ++++++++++++++++++ .../app-boot/tests/profile-resolution.spec.ts | 119 +++- 17 files changed, 980 insertions(+), 196 deletions(-) create mode 100644 packages/boot/app-boot/tests/linked-resolution-matrix.spec.ts diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml index 9b7365d0b4..087f067fb9 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.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 .agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md -2026-09-09-profile-resolution-generations.md: fe8062c434fb226982ef9d1e88355b6833293aca -2026-09-09-profile-resolution-generations.zh.md: d63ebc9a1e70c182d0d2703f06bdacfe2a7a4c49 +2026-09-09-profile-resolution-generations.md: e524150b4928e0ed239cd10efd668e3400718ecc +2026-09-09-profile-resolution-generations.zh.md: 1a6104586f0d4c7d5911128557485a1bc277f426 diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md index fe8062c434..e524150b49 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md +++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md @@ -66,7 +66,7 @@ For example, `@deepseek-ai/dsh-tools` creates its scheduler key with `Symbol()`. A runtime interception holds one `current` generation. Each synchronous resolution captures that reference once. Generation construction reads every required dependency-graph manifest before publication; an error leaves the current generation unchanged. Successful publication replaces one reference, and in-flight calls may finish against the generation they captured. -Selection and package-metadata caches belong to a generation. Publishing a successor invalidates them by making the old generation unreachable after its callers finish; update code does not mutate or clear individual entries. Profile-importer hits and successful native selections can be cached, but a generation miss is rescanned so a profile-local package installed after the miss becomes visible through native lookup. Linked importer routes are not cached: each resolution reads the linked package's current peer declarations. Calls with explicit CommonJS paths or non-default conditions never reuse a default-resolution cache entry. +Selection and package-metadata caches belong to a generation. Publishing a successor invalidates them by making the old generation unreachable after its callers finish; update code does not mutate or clear individual entries. Profile-importer hits and successful native selections can be cached, but a generation miss is rescanned so a profile-local package installed after the miss becomes visible through native lookup. Linked importer routes are not cached: each resolution reads current peer declarations at the ancestor positions it visits. Explicit CommonJS paths bypass interception entirely; non-default conditions never reuse a default-resolution cache entry. The launcher constructs one startup generation. The service accepts an additive successor, but no package-manager transaction invokes replacement in this implementation. @@ -74,7 +74,7 @@ The launcher constructs one startup generation. The service accepts an additive The resolver uses `node-addon-require-builtin` to read `internal/modules/esm/loader` and `internal/modules/cjs/loader`. The ESM adapter wraps the per-thread singleton `CascadedLoader` resolve methods. The CommonJS adapter wraps the internal builtin's `Module._resolveFilename`; that `Module` is the same object exported by `node:module`. -Both adapters call one routing function. It ignores builtins, relative or absolute paths, URLs, parents outside the profiles and registered linked roots, and explicit calls outside the supported lookup. A `#imports` request uses Node's mapping from its owning manifest; an external bare target follows the same local, interception, and native-after-interception package order with the request's conditions, while Node retains exact target resolution. For a scoped bare request, a package self-reference keeps the original parent even when an npm alias gives its installed directory another name. A profile-local or plugin-private package also keeps the original parent when Node resolves the requested entry before the interception layer; a CommonJS package directory without `exports` does not suppress the interception entry when only its requested subpath is absent. Otherwise the router uses an interception hit through that entry's declaring anchor or continues native lookup from the physical layer. The [lookup-order Note](2026-09-19-profile-resolution-lookup-order.md) owns profile and linked-root positions, peer eligibility, and explicit CommonJS path behavior. +Both adapters call one routing function. It ignores builtins, relative or absolute paths, URLs, parents outside the profiles and registered linked roots, and every CommonJS request with explicit `paths`. A `#imports` request uses Node's mapping from its owning manifest; an external bare target follows the same package order with the request's conditions, while Node retains exact target resolution. Package self-references keep the original parent, including npm aliases. Profiles have a fixed interception position; linked importers apply current peer eligibility at each native ancestor position. Native CommonJS probes determine whether a legacy subpath miss continues to another position. The [lookup-order Note](2026-09-19-profile-resolution-lookup-order.md) owns the complete selection rule. The adapters call the captured native resolver after routing. Node remains responsible for exports, import and require conditions, main files, subpaths, extensions, native caches, and error codes. Routed ESM failures replace the internal lookup anchor in Node's diagnostic with the original importer. A selected package's invalid export or missing target does not trigger another same-name candidate. CommonJS does not replace `_findPath` or reproduce `_resolveFilename`. @@ -84,7 +84,7 @@ The guarantee covers Node's default `import`, `import()`, `import.meta.resolve`, The runtime resolution lists the packages it supplies; Loader entries form the active plugin list. Consumers keep using Loader's existing entry lifecycle and filter the entries relevant to their own scope. Consumers that need package metadata pass a specifier and owning tree base URL to a lightweight `app-boot` service without requiring a `./package.json` export. An installed runtime resolution is authoritative, including a miss; a service created without one retains native lookup for low-level embedders. -The resolver does not expose `imported(entry)` and does not observe ModuleJobs, wrap Entry methods, associate fibers with import calls, replace registry or tree methods, or adapt HMR transactions. Package queries and imports use the same selection rules, including the current peer declarations of linked packages. Non-Node importers that need package metadata must explicitly implement the same resolver interface. +The resolver does not expose `imported(entry)` and does not observe ModuleJobs, wrap Entry methods, associate fibers with import calls, replace registry or tree methods, or adapt HMR transactions. Package-directory queries use the same package selection, including current ancestor peer declarations for linked importers, but do not validate the requested subpath or load its file. Non-Node importers that need package metadata must explicitly implement the same resolver interface. The implementation lives under `app-boot/src/profile-resolution/`. `service.ts` provides the long-lived `ctx.pluginPackages` and owns the main-thread interception and the Worker resolution lifetime; `resolver.ts` implements runtime resolution lookup and the Node Internal adapters; `worker-bootstrap.ts` installs the inherited runtime resolution in one thread. Profile selection and runtime resolution construction remain in `profile.ts`. Workers reference the bootstrap only through the public `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap` export. @@ -104,13 +104,13 @@ Replacing, upgrading, or removing an already loaded package requires process res ### Filesystem and runtime carriers -The resolver does not create, update, or remove fallback symlinks and proxy packages. Runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`; every other name sees that directory as an ordinary ancestor. Construction also records profile package links whose real targets are outside the profiles tree. At each linked root's `node_modules`, only names declared as peers and present in the runtime resolution are occupied. Profile-local package metadata and bundle dependency discovery follow the same Node lookup; ordinary pnpm-installed packages retain native precedence. The [lookup-order Note](2026-09-19-profile-resolution-lookup-order.md) records the complete order. Writable profile state and package-manager transactions remain outside the resolver. +The resolver does not create, update, or remove fallback symlinks and proxy packages. Runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`; every other name sees that directory as an ordinary ancestor. Construction also records profile links to real directories outside the profiles tree, including directories without their own manifest. Linked importers retain native ancestor order and apply peer mappings at the matching manifest's position, even without a physical `node_modules` there. Profile-local package metadata and bundle dependency discovery follow the same Node lookup. The [lookup-order Note](2026-09-19-profile-resolution-lookup-order.md) records precedence and scope. Writable profile state and package-manager transactions remain outside the resolver. Runtime resolution requires a supported Node Internal loader interface. The Electron Host runs through the Electron executable with `ELECTRON_RUN_AS_NODE=1`; packaged builds read the dsh tree from ASAR and map executable ASAR entries to electron-builder's unpacked tree. Pkg and Electron use the same runtime resolution mechanism as ordinary Node launches. ### Performance and verification -Generation construction is startup or update work, not resolve work, and its absolute latency is reported separately. Profile hot paths consist of scope classification, bare-name extraction, local-before-fallback selection, a Map lookup, and one native resolution; a cache hit returns the generation-owned result directly. Linked importer routes additionally read the package's peer declarations and do not cache the selected route. A CommonJS request may perform one native probe followed by one routed resolution when a local package directory exists without `exports` but lacks the requested subpath. Out-of-scope calls do not read manifests and cache only whether each parent has an interception layer. +Generation construction is startup or update work, not resolve work, and its absolute latency is reported separately. Profile hot paths consist of scope classification, bare-name extraction, local-before-fallback selection, a Map lookup, and one native resolution; a cache hit returns the generation-owned result directly. Linked requests for supplied package names read the visited ancestor manifests and do not cache the selected route. CommonJS can probe multiple positions when legacy subpaths are missing. Out-of-scope calls do not read manifests and cache only whether each parent has an interception layer. One-off local measurements taken during implementation ran built JavaScript under plain Node in fresh processes and compared it with a process that installed no hook. The measurement script and results are not committed, and these figures are not a benchmark or CI budget. Seven alternating rounds covered outside, profile-local, and fallback imports through dynamic import, `import.meta.resolve`, require, and `require.resolve`. Across Node 22.19, 24.18, and 26.8, the largest positive hot-path median was 4.5%. On Node 24.18, a 256-package cold workload regressed by at most 11.2% and generation construction took 16.027 ms median; the 32-package local `require.resolve` case added 1.033 ms across the batch (+34.7%) from fixed startup cost. diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md index d63ebc9a1e..1a6104586f 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md @@ -66,7 +66,7 @@ ESM `import` 和 CommonJS `require` 都选中这些版本。在每种模块格 一个 runtime interception 持有一个 `current` generation。每个同步 resolve 在入口只捕获一次该引用,完整调用只读该引用。generation 构造在发布前读取依赖图所需的全部 manifest;失败时当前 generation 不变。发布成功只替换一个引用,执行中的调用可以继续使用它已捕获的 generation。 -选包缓存和包元数据缓存归 generation 所有。发布下一代后,旧 generation 在调用方退出后自然不可达,不逐项清理缓存。profile importer 的命中和原生解析成功结果可以缓存,但 generation 未命中会重新扫描,因此未命中后安装的 profile 本地包会通过原生查找变为可见。linked importer 的路由不缓存,每次解析读取链接包当前的 peer 声明。显式 CommonJS paths 或非默认 conditions 不得复用默认解析缓存。 +选包缓存和包元数据缓存归 generation 所有。发布下一代后,旧 generation 在调用方退出后自然不可达,不逐项清理缓存。profile importer 的命中和原生解析成功结果可以缓存,但 generation 未命中会重新扫描,因此未命中后安装的 profile 本地包会通过原生查找变为可见。linked importer 的路由不缓存,每次解析读取所访问祖先位置当前的 peer 声明。显式 CommonJS paths 完全绕过拦截,非默认 conditions 不复用默认解析缓存。 launcher 只构造启动 generation。服务接受新增型后继 generation,但本实现没有包管理器事务调用替换操作。 @@ -74,7 +74,7 @@ launcher 只构造启动 generation。服务接受新增型后继 generation, resolver 使用 `node-addon-require-builtin` 读取 `internal/modules/esm/loader` 和 `internal/modules/cjs/loader`。ESM 适配器包装每线程单例 `CascadedLoader` 的 resolve 方法。CommonJS 适配器包装内部 builtin 导出的 `Module._resolveFilename`;该 `Module` 与 `node:module` 导出的对象相同。 -两个适配器调用同一个路由函数。builtin、相对或绝对路径、URL、profile 与已记录 linked root 之外的 parent,以及支持的查找以外的显式调用,都直接委托原生实现。`#imports` 请求使用所属 manifest 中的 Node 映射;外部 bare target 按相同 conditions 遵循本地包、interception 和 native-after-interception 的选包顺序,精确 target 解析仍由 Node 负责。对于作用域内的 bare request,package self-reference 保留原 parent,即使 npm alias 使安装目录使用另一个名称。Node 能在拦截层之前从 profile 本地包或插件私有包解析到所请求入口时,也保留原 parent;没有 `exports` 的 CommonJS 包目录仅缺少所请求 subpath 时,不会压过拦截条目。其他请求在 interception 命中时通过该条目的声明锚点解析,未命中时从该物理层继续原生查找。[查找顺序 Note](2026-09-19-profile-resolution-lookup-order.zh.md)统一说明 profile 与 linked root 的拦截位置、peer 条件和显式 CommonJS path 行为。 +两个适配器调用同一个路由函数。builtin、相对或绝对路径、URL、profile 与已记录 linked root 之外的 parent,以及所有带显式 `paths` 的 CommonJS 请求,都直接委托原生实现。`#imports` 请求使用所属 manifest 中的 Node 映射;外部 bare target 按请求的 conditions 遵循相同选包顺序,精确 target 解析仍由 Node 负责。包自引用保留原 parent,包括 npm alias。profile 使用固定拦截位置,linked importer 则在每个原生祖先位置应用当前 peer 条件。原生 CommonJS 探测决定旧式子路径缺失是否继续查询下一个位置。完整选包规则由[查找顺序 Note](2026-09-19-profile-resolution-lookup-order.zh.md)统一记录。 适配器完成路由后调用捕获的原生 resolver。exports、import/require conditions、main、subpath、扩展名、原生缓存和错误码仍归 Node 处理。路由后的 ESM 失败会把 Node 诊断中的内部查找锚点替换为原始 importer。选中包的无效 export 或缺失目标不会触发另一个同名候选。CommonJS 不替换 `_findPath`,也不复制 `_resolveFilename`。 @@ -84,7 +84,7 @@ resolver 使用 `node-addon-require-builtin` 读取 `internal/modules/esm/loader runtime resolution 列出它提供的包;Loader entries 组成活动插件列表,两者不能合并。消费方继续使用 Loader 原有 entry 生命周期,并按自身 scope 过滤相关 entries。需要 package metadata 的消费方将 specifier 和所属树的 base URL 交给 app-boot 中的轻量服务,无需 package 导出 `./package.json`。安装 runtime resolution 后,即使查询未命中也以它为准;底层嵌入方只安装服务而不提供 runtime resolution 时,服务保留 Node 原生查找。 -解析器不提供 `imported(entry)`,不观察 ModuleJob,不包装 Entry 方法,不把 fiber 与 import 调用关联,也不替换 registry、tree 或 HMR 方法。包查询与 import 使用同一套选包规则,包括链接包当前的 peer 声明。需要包元数据的非 Node importer 必须显式实现同一个 resolver 接口。 +解析器不提供 `imported(entry)`,不观察 ModuleJob,不包装 Entry 方法,不把 fiber 与 import 调用关联,也不替换 registry、tree 或 HMR 方法。包目录查询使用相同选包规则,包括 linked importer 祖先当前的 peer 声明,但不校验所请求的子路径或加载文件。需要包元数据的非 Node importer 必须显式实现同一个 resolver 接口。 实现集中在 `app-boot/src/profile-resolution/`。`service.ts` 提供长期存在的 `ctx.pluginPackages`,并拥有主线程拦截与 Worker runtime resolution 的生命周期;`resolver.ts` 实现 runtime resolution 查询和 Node Internal 适配器;`worker-bootstrap.ts` 在线程内安装继承的 runtime resolution。profile 选包和 runtime resolution 构造留在 `profile.ts`。Worker 只通过 `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap` 公开入口引用 bootstrap。 @@ -104,13 +104,13 @@ runtime resolution 列出它提供的包;Loader entries 组成活动插件列 ### 文件系统与运行时载体 -解析器不创建、更新或删除 fallback 软链接与代理包。runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置;其余包名把该目录当作普通祖先。构造时还会记录真实目标位于 profiles 树外的 profile 包链接。在每个 linked root 的 `node_modules` 层,只有被声明为 peer 且 runtime resolution 中存在的包名被占据。profile 本地包元数据与 bundle 依赖展开遵循同一套 Node 查找;正常由 pnpm 安装的包保留原生优先级。完整顺序见[查找顺序 Note](2026-09-19-profile-resolution-lookup-order.zh.md)。可写 profile 状态和包管理器事务不属于解析器。 +解析器不创建、更新或删除 fallback 软链接与代理包。runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置;其余包名把该目录当作普通祖先。构造时还会记录指向 profiles 树外真实目录的 profile 链接,包括没有自身 manifest 的目录。linked importer 保留原生祖先顺序,在匹配 manifest 对应的位置应用 peer 映射,即使那里没有物理 `node_modules`。profile 本地包元数据与 bundle 依赖展开遵循同一套 Node 查找。优先级和范围见[查找顺序 Note](2026-09-19-profile-resolution-lookup-order.zh.md)。可写 profile 状态和包管理器事务不属于解析器。 运行时解析要求受支持的 Node Internal loader 接口。Electron Host 通过设置 `ELECTRON_RUN_AS_NODE=1` 的 Electron 可执行文件运行;打包构建从 ASAR 读取 dsh 依赖树,并把 ASAR 中的可执行条目映射到 electron-builder 的 unpacked 目录。pkg 与 Electron 使用和普通 Node 启动相同的 runtime resolution 机制。 ### 性能与验证 -generation 构造发生在启动或显式更新阶段,不属于单次 resolve,但需要单独报告绝对延迟。profile 热路径只包括 scope 分类、bare name 提取、本地优先判断、Map 查询和一次原生解析;缓存命中直接返回 generation 级结果。linked importer 的路由还会读取包的 peer 声明,且不缓存选中的路由。当本地 CommonJS 包目录没有 `exports` 且仅缺少所请求 subpath 时,一次请求可能先执行一次原生探测,再执行一次路由解析。作用域外调用不读取 manifest,只缓存 parent 是否具有拦截层。 +generation 构造发生在启动或显式更新阶段,不属于单次 resolve,但需要单独报告绝对延迟。profile 热路径只包括 scope 分类、bare name 提取、本地优先判断、Map 查询和一次原生解析;缓存命中直接返回 generation 级结果。linked importer 请求运行时表提供的包名时,读取所访问的祖先 manifest,不缓存选中的路由。旧式子路径缺失时,CommonJS 可以探测多个位置。作用域外调用不读取 manifest,只缓存 parent 是否具有拦截层。 实现期间的一次性本地测量用 plain Node 在全新进程中执行构建后的 JavaScript,并与完全没有安装 hook 的进程比较。测量脚本和结果未提交,这些数据不是 benchmark 或 CI 预算。七轮交替顺序覆盖 outside、profile-local 和 fallback 的 dynamic import、`import.meta.resolve`、require、`require.resolve`。Node 22.19、24.18 和 26.8 的热路径中位数最大正向回退为 4.5%。Node 24.18 的 256 包 cold workload 最大回退为 11.2%,generation 构造中位数为 16.027 ms;32 包本地 `require.resolve` 因固定启动成本在整批增加 1.033 ms(+34.7%)。 diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml index 19d2fd9b0d..9adcca0495 100644 --- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.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 .agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md -2026-09-19-profile-resolution-lookup-order.md: 5744a7bbb7b76417abeabb31bfa8512137ed0bff -2026-09-19-profile-resolution-lookup-order.zh.md: 2db1394701d739ed9cf56694cb028189ff38b362 +2026-09-19-profile-resolution-lookup-order.md: cb4c677e30a8d0f104a3cacf6c97407a8ea70576 +2026-09-19-profile-resolution-lookup-order.zh.md: cf33a9b5b1d56e23c8060418d8c5c8dc076574e0 diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md index 5744a7bbb7..cb4c677e30 100644 --- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md +++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md @@ -12,13 +12,13 @@ A developer must be able to restate the resolution rule in one sentence: which p ## Decision -Module resolution inside a profile is an ordinary Node ancestor `node_modules` chain. dsh does exactly one thing: every package name in the runtime resolution computed at startup occupies the package directory position `$DSH_HOME/profiles/node_modules/`. When the chain reaches this layer, a package name with an entry is answered by the runtime resolution's package, and a package name without an entry sees the physical directory at this layer. A plugin linked outside the tree has the same form of interception at its real directory: runtime resolution entries that the plugin declares as peers occupy `/node_modules/`. Every other resolution behavior matches Node. [Construction, publication, Worker inheritance, and runtime carriers of immutable generations](2026-09-09-profile-resolution-generations.md) are recorded by the existing Note and are not repeated here. +Ordinary module requests retain Node's ancestor `node_modules` order. Inside a profile, runtime resolution entries occupy their package positions at `$DSH_HOME/profiles/node_modules`. For an importer in a recorded external linked directory, each candidate `D/node_modules` applies one rule: a name declared in `D/package.json` under `peerDependencies` and present in the runtime resolution uses the runtime package at that position; otherwise Node tries the physical package there. A nearer candidate precedes a peer declaration farther up. Explicit CommonJS `paths` always bypass interception. Node owns the remaining resolution behavior. [Construction, publication, Worker inheritance, and runtime carriers of immutable generations](2026-09-09-profile-resolution-generations.md) are recorded by the existing Note and are not repeated here. ### Part 1: Resolution rules #### 1. The ancestor chain: Node's ancestor `node_modules` lookup -The importer is the module file that issues the `import` or `require`. Node starts from the importer's directory, tries the `node_modules` under each directory level upward until the filesystem root, and then tries `NODE_PATH` and the global directories. The nearest layer wins; within one layer, matching is by package name only. +The importer is the module file that issues the `import` or `require`. Node starts from the importer's directory and searches ancestor `node_modules` positions up to the filesystem root, skipping a redundant `node_modules/node_modules` position. CommonJS also searches `NODE_PATH` and its global directories; ESM does not. The nearest matching candidate wins, subject to Node's package-entry and failure rules. Symlinks are followed to their real path per Node's default behavior. Once a module is loaded by its real path, the ancestor chain for its subsequent imports is the real path's ancestor chain, regardless of where it was linked from. @@ -32,7 +32,7 @@ The chain below defines the numbering that every table in this Note references. ⑤ /node_modules ``` -① holds the plugin's private dependencies, ② the packages the profile installed, ③ the interception layer where the runtime resolution occupies the package directories it has entries for, ④ the Harness home, and ⑤ the filesystem root followed by `NODE_PATH` and the global directories. +① holds the plugin's private dependencies, ② the packages the profile installed, ③ the interception layer where the runtime resolution occupies the package directories it has entries for, ④ the Harness home, and ⑤ the filesystem root. CommonJS then retains its `NODE_PATH` and global-directory lookup without peer interception at those extra positions. #### 2. The interception layer: the runtime resolution occupies `$DSH_HOME/profiles/node_modules/` @@ -46,13 +46,15 @@ Node remains responsible for `exports`, `imports`, conditions, `main`, subpaths, The interception layer reads, writes, and deletes no disk links. Leftover historical symlinks are treated as ordinary filesystem content: the positions of installation package names at ③ are already occupied by the runtime resolution, so old links are never read; all other package names see the contents of ③ normally along the ancestor chain. Profile load removes, once, the projections the link backend of the dsh 0.1.5 releases wrote into a profile: symlinks under the profile's `node_modules` whose target lies inside `/.dsh-module-fallback/node_modules`, followed by that directory. pnpm-installed packages and every other symlink stay. -#### 3. Plugins linked outside the tree: interception at their real directory's `node_modules` +#### 3. Linked directories: peer interception at each ancestor position -When `/node_modules/` is a symlink whose real target R is outside the profiles tree, R is a linked root. Importers below R follow its real ancestor chain, with `R/node_modules` as the interception layer: deeper `node_modules` on that chain, such as a transitive dependency's own layer inside pnpm's `.pnpm/`, are local layers; above `R/node_modules`, Node continues through `parent(R)/node_modules` up to the filesystem root. +When `/node_modules/` links to a real directory R outside the profiles tree, R is a linked root. R need not contain `package.json` or `node_modules`: it may be a package directory, a monorepo package, or a `src` directory. Importers below R follow Node's real ancestor chain. The recorded root decides which importers participate; it does not stop their lookup at R. -Only some package names are occupied at this layer: names declared in `R/package.json` under `peerDependencies` that also have a runtime resolution entry. A plugin declares dsh packages whose instances it must share with the host as peers. When lookup reaches this layer, the running dsh supplies the package, and the same-named devDependency copy installed at this position for type checking is not loaded. Names declared only under `dependencies`, not as peers, remain unoccupied. The plugin's own third-party versions retain Node's nearest-wins order, just as ① and ② precede ③ inside a profile. +At each candidate `D/node_modules`, a matching current `D/package.json` peer declaration uses the runtime package if the table supplies that name. This occupies only that package's position, including when `D/node_modules` does not physically exist. Without both a declaration and a runtime entry, Node tries the physical candidate. A missing manifest does not stop lookup. `dependencies` and `devDependencies` do not enable interception, and a peer version range is not an additional resolver filter. The same rule applies to third-party peers such as React when the runtime table supplies them. -Each resolution reads the peer set from `R/package.json`; runtime resolution construction does not freeze it, and linked importer routes are not memoized. After a developer changes `peerDependencies`, new resolutions during a plugin reload read the new declaration. This neither clears Node's module caches nor automatically watches plugin files. Names not occupied at this layer are delegated to Node from the `R/package.json` anchor: the physical contents of `R/node_modules`, followed by R's real ancestor chain. Runtime resolution construction scans top-level and `@scope/*` entries in `/node_modules` for linked roots. A successor may add or remove linked roots within the existing package-mapping and local-name constraints; changing the real target of an existing link name rejects publication and requires restart because Node caches real paths. An unreadable `R/package.json` occupies no names at this layer; Node reports its diagnostics. +A nearer physical candidate wins before any later ancestor peer declaration. If a selected package's `exports` rejects the request, Node's error is final. A legacy CommonJS subpath miss can continue to the next position, where that directory's peer rule applies again; the physical copy at an occupied position is not retried. Each new linked resolution reads the manifests at the positions it visits, without memoizing its selected route. An unreadable manifest supplies no peers; Node retains its native manifest diagnostics. This does not clear Node's caches or automatically reload already loaded modules. + +Runtime resolution construction scans top-level and `@scope/*` links in `/node_modules`. A successor may add or remove linked roots within the existing package-mapping and local-name constraints; changing the real target of an existing link name rejects publication and requires restart because Node caches real paths. A dependency whose real path lies outside every recorded linked root remains outside interception, even when a plugin links to it. #### 4. What the interception layer holds: the runtime resolution's scan contents @@ -61,16 +63,20 @@ The runtime resolution is computed once at profile startup and consists of four - Installation closure: starting from the `package.json` of the currently running dsh package, a breadth-first traversal follows `dependencies` and `peerDependencies`; each edge resolves from the manifest that declares it per Node rules, and the first installed package found owns a package name. The closure holds several hundred entries, roughly half in the `@deepseek-ai/` scope and half third-party libraries. These entries apply to every profile. - Bundle-only entries: for a bundle selected by the profile that is not part of the closure, the same traversal starts from its manifest, and package names the closure already owns are not overridden. These entries apply only to profiles that select that bundle; they let the Loader import the bundle's embedded plugins by bare name from the profile root. - Local package names: package names among the profile's direct dependencies that are already installed in `$DSH_HOME/profiles//node_modules`. They already sit at ② on the ancestor chain; recording them only saves one directory probe. -- Linked roots: top-level and `@scope/*` symlinks in `$DSH_HOME/profiles//node_modules` whose targets are outside the profiles tree and contain a `package.json`; each records its real directory and link position. Links whose targets remain inside the profiles tree are not recorded because the ancestor chain already covers them. +- Linked roots: top-level and `@scope/*` links in `$DSH_HOME/profiles//node_modules` whose targets are directories outside the profiles tree; each records its real directory and link position. Their own manifests are optional. Missing targets, files, and directories inside the profiles tree are excluded. The CLI derives the installation anchor from `import.meta.url`, which Node has already resolved to its real path; the Desktop Host builds it from its runtime directory, which is not a symlink. Both leave the installation root equal to its real directory, so bundle discovery and dependency traversal use the same location. During the traversal, every dependency level uses the real directory of its owning package as the lookup anchor for the next level and records the location of the manifest that declares it. After a hit, Node resolves from that declaring location and gets the same result the package's own internal imports get. Every entry records the package name, package directory, version, declaring location, and scope. Declared but uninstalled dependencies are skipped; the bundle package root itself does not become an entry. #### 5. Hook coverage -The hook participates only when the importer is under `$DSH_HOME/profiles/**` or a linked root. Builtin, relative-path, absolute-path, and URL requests, and every request whose importer is outside both locations, go straight to Node. +The hook participates only when the importer is under `$DSH_HOME/profiles/**` or a linked root. Builtin, relative-path, absolute-path, and URL requests, and every request whose importer is outside both locations, go straight to Node. `require.resolve(request, { paths })` also goes straight to Node, including when a path names a profile or linked directory. The ESM and CommonJS adapters call the same routing function, and the main thread and Harness-owned Workers install the same runtime resolution. The implementation lives in `packages/boot/app-boot/src/profile-resolution/resolver.ts`; runtime resolution construction lives in `packages/boot/app-boot/src/profile.ts`. +#### 6. Package directories and module files + +`packageDir('pkg', parentURL)` and `packageDir('pkg/sub', parentURL)` locate the package directory without loading code or validating the subpath. Ordinary entry and file requests still ask Node to apply `exports`, `main`, conditions, and file existence. A package-directory query can therefore succeed while importing a missing or unexported file fails. `import.meta.resolve` can return a URL for an exported file that does not exist; importing that URL still fails, as in native Node. + ### Part 2: Walkthroughs #### Table 1: Ancestor chain and interception for ESM and CommonJS across request forms @@ -79,12 +85,12 @@ The table uses the installation package `@deepseek-ai/dsh-tools` (has a runtime | Request form | ESM | CommonJS | Position of the package name at ③ | When a file is missing inside the package | |---|---|---|---|---| -| Bare name `pkg`, package has `exports` | If ① or ② has a `pkg` directory, Node takes the entry point from its `exports` | Same as ESM; a candidate directory at ① or ② whose entry file is missing does not count as a candidate | With entry: the runtime resolution's package; without entry: the physical directory | A missing entry point under `exports` is an `exports` error, final | -| Bare name `pkg`, package has no `exports` | As above, entry point from `main` or `index` | As above | As above | ESM fails, final; CommonJS continues looking for an entry point at the next layer | +| Bare name `pkg`, package has `exports` | If ① or ② has a `pkg` directory, Node takes the entry point from its `exports` | Node selects the require condition from the same candidate | With entry: the runtime resolution's package; without entry: the physical directory | A missing exported target is final | +| Bare name `pkg`, package has no `exports` | Entry point from `main` or `index` | Native legacy entry lookup | As above | ESM fails, final; CommonJS continues only for a native lookup miss, not an invalid declared `main` | | Subpath `pkg/sub`, package has `exports` | The first `pkg` found decides; if `./sub` is not exported, `ERR_PACKAGE_PATH_NOT_EXPORTED` is final | Same as ESM | As above | Final; no other copy is searched | | Subpath `pkg/sub`, package has no `exports` | If the first `pkg` found has no `sub`, `ERR_MODULE_NOT_FOUND` is final | Tries `/pkg/sub` layer by layer: ① and ②, then the position of the package name at ③ (the runtime resolution's package directory when an entry exists), then ④ | As above | ESM final; CommonJS continues to the next layer, that is ④ | | `#alias` package-internal alias | After the owning manifest's `imports` maps it to a bare name, handled per the rows above; a mapping to a relative path goes straight to Node | Same as ESM, with conditions from the caller or the defaults | Same as the matching row | Same as the matching row | -| `require.resolve(pkg, { paths })` | No such form | Applies the same rule to each item in `paths` independently: an item inside the profile tree walks ① and ②, ③, ④ from that item; an item outside the tree goes to Node; in the caller's order | As above | The item continues to its next layer, then the next item takes its turn | +| `require.resolve(pkg, { paths })` | No such form | Entire request goes to Node with the original options, regardless of the paths' locations | No interception; physical contents only | Native Node continuation and errors | | Package self-reference (the importer's package imports by its own `name`) | Goes to Node with the original importer kept | Same as ESM | Not involved | Not applicable | | Relative / absolute / URL / builtin | Goes to Node | Goes to Node | Not involved | Not applicable | @@ -108,8 +114,11 @@ The profile links `/node_modules/my-plugin` to the plugin's real direct | Linked plugin → `zod` | Participates; `zod` is not occupied at `R/node_modules` | `R/node_modules/zod`, the developer's installed version | | Linked plugin → `@deepseek-ai/dsh-tools` (peer) | Participates; the name is occupied at `R/node_modules` | The running dsh's copy; the devDependency copy in `R/node_modules` is not read | | Linked plugin → a stateful dsh package declared only as a dependency | Participates; the name is not occupied | Its own copy in `R/node_modules`, creating a second instance; the same mistake as installing the dsh package at ② inside the tree. Declare it as a peer instead | -| Linked plugin → undeclared package name | Participates; the name is not occupied | Physical contents of `R/node_modules`, then R's real ancestor chain | -| Transitive dependency inside R → any package name | Participates | Its own local layers first, then the rules above; the occupied set still comes from the peers in `R/package.json` | +| Linked plugin → undeclared package name | Participates; R does not occupy the name | Physical contents of `R/node_modules`, then the same per-position rule along the real ancestor chain | +| Transitive dependency inside R → any package name | Participates | Each position uses its own manifest's peers; nearer physical candidates precede later peer declarations | +| Link target R has no manifest → peer declared by an ancestor | Participates | Search starts at R; an earlier physical candidate wins, otherwise the ancestor peer can select the runtime package even without physical `node_modules` there | +| Hoisted dependency whose real directory is outside every linked root → any package name | Does not participate | Native Node lookup from that dependency's real directory | +| Any importer → `require.resolve(pkg, { paths })` | Does not participate | Native Node lookup using the supplied paths | ### Part 3: Developer integration guide @@ -121,7 +130,7 @@ The plugin's own third-party dependencies are hoisted to `$DSH_HOME/profiles//node_modules` become linked roots; dependencies linked elsewhere from the plugin repository or hoisted outside it by npm workspaces remain outside every linked root and use plain Node resolution. Peer requests for other plugins inside the profile do not return to ② and fail if R's real ancestor chain cannot find them. Each routed request in development mode reads the plugin manifest. Changing a link target at the same logical path still requires restart. Consumers that bypass the hook, namely child processes a plugin spawns itself, third-party Workers, and external tools run inside the profile directory, can no longer find installation packages through disk links in `$DSH_HOME/profiles/node_modules`. The resolver continues to depend on supported Node Internal interfaces. +Paid: third-party libraries in the installation closure still occupy package directories at ③; a profile plugin without a nearer copy gets the installation's version. A linked request selects a runtime package only at a matching peer position, and a nearer physical copy still wins. Developers must place declarations and dependencies accordingly. Runtime resolution does not enforce peer version ranges. + +Only direct links from `/node_modules` become linked roots; dependencies whose real directories lie outside every recorded root use native Node. Peer requests do not return to the profile's ②: a name absent from the runtime table must be found on the real ancestor chain. Linked requests pay for current peer-manifest reads. Changing a link target still requires restart; module-cache invalidation and automatic watching are separate from this rule. + +Explicit CommonJS paths, plugin-spawned processes, third-party Workers, and external tools do not receive runtime peer mappings. Consumers outside the hook cannot find installation packages through generated disk links. The resolver continues to depend on supported Node Internal interfaces. diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md index 2db1394701..cf33a9b5b1 100644 --- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md @@ -12,13 +12,13 @@ profile 从自己的包项目加载插件。dsh 本体包和 bundle 内嵌的依 ## Decision -profile 内模块的解析是一条普通的 Node 祖先 `node_modules` 链。dsh 只做一件事:启动时算出的 runtime resolution 中的每个包名,占据 `$DSH_HOME/profiles/node_modules/<包名>` 这个包目录的位置。链走到这一层时,有条目的包名由 runtime resolution 的包回答,没有条目的包名看这一层的物理目录。link 到树外的插件把同一形式的拦截层带到自己的真实目录:runtime resolution 中被该插件声明为 peer 的包名,占据 `<真实目录>/node_modules/<包名>` 的位置。除此之外的一切解析行为与 Node 一致。[不可变 generation 的构造、发布、Worker 继承与运行时载体](2026-09-09-profile-resolution-generations.zh.md)由既有 Note 记录,本篇不复述。 +普通模块请求保留 Node 的祖先 `node_modules` 顺序。profile 内,runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上对应的包位置。对于已记录的树外链接目录中的 importer,每个候选 `D/node_modules` 只应用一条规则:包名同时出现在 `D/package.json` 的 `peerDependencies` 和 runtime resolution 中,就由运行时包占据该位置;否则 Node 尝试该位置的物理包。更近的候选先于更高祖先的 peer 声明。显式 CommonJS `paths` 始终绕过拦截。其余解析行为由 Node 负责。[不可变 generation 的构造、发布、Worker 继承与运行时载体](2026-09-09-profile-resolution-generations.zh.md)由既有 Note 记录,本篇不复述。 ### 一、解析规则 #### 1. 主线:Node 的祖先 `node_modules` 链 -importer 指发起 `import` 或 `require` 的那个模块文件。Node 从 importer 所在目录开始,逐层向上尝试每一级目录下的 `node_modules`,直到文件系统根,再尝试 `NODE_PATH` 与全局目录。最近的一层优先;同一层内只按包名匹配。 +importer 指发起 `import` 或 `require` 的那个模块文件。Node 从 importer 所在目录开始,沿祖先 `node_modules` 候选位置查到文件系统根,跳过多余的 `node_modules/node_modules` 位置。CommonJS 还查询 `NODE_PATH` 与全局目录,ESM 不查询。在 Node 的包入口与失败规则下,最近的匹配候选优先。 软链接按 Node 默认行为跟随到真实路径。一个模块一旦以真实路径加载,它后续 import 的主线就是真实路径的祖先链,与它被链接到哪里无关。 @@ -32,7 +32,7 @@ importer 指发起 `import` 或 `require` 的那个模块文件。Node 从 impor ⑤ /node_modules ``` -① 是插件私有依赖,② 是 profile 安装的包,③ 是拦截层,runtime resolution 占据其中有条目的包目录,④ 是 Harness home,⑤ 是文件系统根,随后是 `NODE_PATH` 与全局目录。 +① 是插件私有依赖,② 是 profile 安装的包,③ 是拦截层,runtime resolution 占据其中有条目的包目录,④ 是 Harness home,⑤ 是文件系统根。CommonJS 随后保留 `NODE_PATH` 与全局目录的查询,不在这些额外位置应用 peer 拦截。 #### 2. 拦截层:runtime resolution 占据 `$DSH_HOME/profiles/node_modules/<包名>` @@ -46,13 +46,15 @@ Node 仍然负责 `exports`、`imports`、conditions、`main`、子路径、扩 拦截层不读、不写、不删任何磁盘链接。历史残留的软链接一律按普通文件系统内容处理:本体包名在 ③ 上的位置已被 runtime resolution 占据,旧链接永远不会被读到;其余包名按主线正常看到 ③ 里的内容。profile 加载时一次性删除 dsh 0.1.5 系列发布版的 Link 后端写进 profile 的投影:profile `node_modules` 下目标位于 `/.dsh-module-fallback/node_modules` 内的软链接,以及该目录本身。pnpm 安装的包和其他软链接都保留。 -#### 3. link 到树外的插件:拦截层在插件真实目录的 `node_modules` +#### 3. 链接目录:在每个祖先候选位置应用 peer 拦截 -`/node_modules/<包名>` 是软链接且真实目标 R 在 profiles 树外时,R 是一个 linked root。R 之下的 importer 走 R 的真实祖先链,拦截层是 `R/node_modules`:链上更深的 `node_modules`(pnpm `.pnpm/` 内传递依赖自己的那层)是本地层,`R/node_modules` 之上是 `parent(R)/node_modules` 直到文件系统根,都按 Node 处理。 +`/node_modules/<包名>` 链接到 profiles 树外的真实目录 R 时,R 是一个 linked root。R 不必包含 `package.json` 或 `node_modules`,可以是包目录、monorepo 中的单个包,也可以是 `src` 目录。R 之下的 importer 沿 Node 的真实祖先链查询。记录的根目录决定哪些 importer 参与拦截,不会把它们的查找限制在 R 内。 -这一层上被占据的包名只有一部分:`R/package.json` 的 `peerDependencies` 里、且 runtime resolution 有条目的包名。插件把需要与宿主共享实例的 dsh 包声明为 peer;查找走到这一层时,由运行中的 dsh 提供该包,为类型检查安装在这个位置的同名 devDependency 副本不会被加载。只声明为 `dependencies`、未声明为 peer 的包名不被占据,插件自己安装的第三方版本照 Node 规则最近者优先,与树内 ①② 赢 ③ 一致。 +在每个候选 `D/node_modules`,当前 `D/package.json` 的 peer 声明命中且运行时表提供该包名时,就使用运行时包。这只占据该包的位置,即使 `D/node_modules` 在磁盘上不存在也成立。声明和运行时条目缺少任一项,Node 就尝试物理候选。缺少 manifest 不会终止查找。`dependencies` 与 `devDependencies` 不启用拦截,peer 的版本范围也不是额外的解析筛选条件。运行时表提供 React 等第三方 peer 时,同样适用这条规则。 -peer 集合在每次解析时从 `R/package.json` 读取,不在 runtime resolution 构造时固定,linked importer 的路由也不做 memo:开发者改完 `peerDependencies` 后,重新加载插件时的新解析会读取新声明。这不清除 Node 的模块缓存,也不自动监视插件文件。未被占据的包名从 `R/package.json` 锚点交给 Node,即 `R/node_modules` 的物理内容再沿 R 的真实祖先链。linked root 的集合在 runtime resolution 构造时扫描 `/node_modules` 的顶层与 `@scope/*` 条目得到;successor 可以在既有包映射和本地包名约束内新增或移除 linked root,同名 link 换了真实目标则拒绝发布并要求重启,因为 Node 缓存 realpath。`R/package.json` 不可读时这一层不占据任何包名,诊断由 Node 报出。 +更近的物理候选先于后续祖先的 peer 声明。选中包的 `exports` 拒绝请求时,Node 的错误是终局。旧式 CommonJS 子路径缺失可以继续到下一位置,再应用那个目录的 peer 规则;不会重试已被占据位置上的物理副本。每次新的 linked 解析读取所访问位置的 manifest,不缓存选中的路由。不可读的 manifest 不提供 peer,Node 保留其原生 manifest 诊断。这不清除 Node 缓存,也不自动重新加载已加载的模块。 + +runtime resolution 构造时扫描 `/node_modules` 的顶层与 `@scope/*` 链接。successor 可以在既有包映射和本地包名约束内新增或移除 linked root;同名 link 换了真实目标则拒绝发布并要求重启,因为 Node 缓存 realpath。依赖的真实路径在所有已记录 linked root 之外时,即使插件链接到它,也不参与拦截。 #### 4. 拦截层里有什么:runtime resolution 的扫描内容 @@ -61,16 +63,20 @@ runtime resolution 在 profile 启动时一次算出,由四部分组成。 - installation 闭包:从当前运行的 dsh 包的 `package.json` 出发,沿 `dependencies` 与 `peerDependencies` 做广度优先遍历,每条边从声明它的 manifest 按 Node 规则解析,同一个包名由第一次找到的已安装包占有。闭包有数百条,约一半在 `@deepseek-ai/` 作用域,一半是第三方库。这些条目对所有 profile 生效。 - bundle-only 条目:profile 选中的、不属于闭包的 bundle,从它的 manifest 出发做同样的遍历,闭包已占有的包名不覆盖。这些条目只对选中该 bundle 的 profile 生效,用于让 Loader 从 profile 根按裸名导入 bundle 内嵌的插件。 - 本地包名:profile 直接依赖中已经安装在 `$DSH_HOME/profiles//node_modules` 的包名。它们本来就在主线 ② 上,记录下来只为免去一次目录探测。 -- linked root:`$DSH_HOME/profiles//node_modules` 顶层与 `@scope/*` 里目标位于 profiles 树外且含 `package.json` 的软链接,记录真实目录与 link 位置。目标仍在 profiles 树内的软链接不记录,主线已经覆盖它。 +- linked root:`$DSH_HOME/profiles//node_modules` 顶层与 `@scope/*` 里目标为 profiles 树外目录的链接,记录真实目录与 link 位置。目录自身的 manifest 可缺省。目标缺失、为文件或位于 profiles 树内的链接都排除。 CLI 的安装锚点来自 `import.meta.url`,Node 已对它做过 realpath;Desktop Host 从其运行时目录拼出锚点,该目录不是软链接。两者的安装根目录都等于真实目录,bundle 发现与依赖遍历使用同一个位置。遍历中每一层依赖都以所属包的真实目录作为下一层的查找锚点,并记录声明它的 manifest 位置。命中后 Node 从这个声明位置解析,得到与该包自己内部 import 相同的结果。每个条目记录包名、包目录、版本、声明位置与作用域。已声明但未安装的依赖跳过;bundle 包根自身不成为条目。 #### 5. hook 覆盖范围 -hook 只在 importer 位于 `$DSH_HOME/profiles/**` 或某个 linked root 之下时参与。builtin、相对路径、绝对路径、URL 请求,以及 importer 在这两处之外的一切请求,直接交给 Node。 +hook 只在 importer 位于 `$DSH_HOME/profiles/**` 或某个 linked root 之下时参与。builtin、相对路径、绝对路径、URL 请求,以及 importer 在这两处之外的一切请求,直接交给 Node。`require.resolve(request, { paths })` 同样直接交给 Node,包括路径指向 profile 或链接目录的情况。 ESM 与 CommonJS 两个适配器调用同一个路由函数,主线程与 Harness 自有 Worker 都安装同一份 runtime resolution。实现位于 `packages/boot/app-boot/src/profile-resolution/resolver.ts`,runtime resolution 的构造位于 `packages/boot/app-boot/src/profile.ts`。 +#### 6. 包目录与模块文件 + +`packageDir('pkg', parentURL)` 与 `packageDir('pkg/sub', parentURL)` 定位包目录,不加载代码,也不校验子路径。普通入口与文件请求仍由 Node 应用 `exports`、`main`、conditions 和文件存在性规则。因此,包目录查询可以成功,同时导入缺失或未导出的文件会失败。`import.meta.resolve` 可以为不存在的已导出文件返回 URL,但导入该 URL 仍然失败,这与原生 Node 一致。 + ### 二、预演 #### 表 1:ESM 与 CommonJS 在各类请求下的主线与拦截 @@ -79,12 +85,12 @@ ESM 与 CommonJS 两个适配器调用同一个路由函数,主线程与 Harne | 请求形态 | ESM | CommonJS | ③ 上该包名的位置 | 包内缺文件时 | |---|---|---|---|---| -| 裸包名 `pkg`,包有 `exports` | ①② 有 `pkg` 目录则 Node 在其中按 `exports` 取入口 | 同 ESM;①② 的候选目录缺入口文件时不算候选 | 有条目:runtime resolution 的包;无条目:物理目录 | 有 `exports` 的入口缺失是 `exports` 错误,终局 | -| 裸包名 `pkg`,包无 `exports` | 同上,入口取 `main` 或 `index` | 同上 | 同上 | ESM 终局报错;CommonJS 从下一层继续找入口 | +| 裸包名 `pkg`,包有 `exports` | ①② 有 `pkg` 目录则 Node 在其中按 `exports` 取入口 | Node 从同一候选选择 require condition | 有条目:runtime resolution 的包;无条目:物理目录 | 已导出目标缺失时终局报错 | +| 裸包名 `pkg`,包无 `exports` | 入口取 `main` 或 `index` | 原生旧式入口查询 | 同上 | ESM 终局报错;CommonJS 仅对原生查询未命中继续,声明的 `main` 无效时不继续 | | 子路径 `pkg/sub`,包有 `exports` | 第一个找到的 `pkg` 决定;`./sub` 未导出则 `ERR_PACKAGE_PATH_NOT_EXPORTED` 终局 | 同 ESM | 同上 | 终局,不找别的副本 | | 子路径 `pkg/sub`,包无 `exports` | 第一个找到的 `pkg` 内没有 `sub` 则 `ERR_MODULE_NOT_FOUND` 终局 | 逐层尝试 `<层>/pkg/sub`:①②,然后 ③ 上该包名的位置(有条目即 runtime resolution 的包目录),然后 ④ | 同上 | ESM 终局;CommonJS 继续下一层,即 ④ | | `#alias` 包内别名 | 所属 manifest 的 `imports` 映射到裸包名后,按上面各行处理;映射到相对路径则直接交 Node | 同 ESM,conditions 取调用方传入或默认值 | 同对应行 | 同对应行 | -| `require.resolve(pkg, { paths })` | 无此形式 | 对 `paths` 中每一项独立套用同一规则:项在 profile 树内则从该项出发走 ①②、③、④;项在树外交 Node;按调用方给出的顺序 | 同上 | 该项继续下一层,再轮到下一项 | +| `require.resolve(pkg, { paths })` | 无此形式 | 无论路径位于何处,都把整个请求及原始选项交给 Node | 不拦截,只看物理内容 | 原生 Node 的继续查询与错误 | | 包自引用(importer 所属包按自己的 `name` import) | 交 Node,保留原 importer | 同 ESM | 不参与 | 不适用 | | 相对 / 绝对 / URL / builtin | 交 Node | 交 Node | 不参与 | 不适用 | @@ -108,8 +114,11 @@ ESM 与 CommonJS 两个适配器调用同一个路由函数,主线程与 Harne | 链接插件 → `zod` | 参与,`R/node_modules` 上 `zod` 未被占据 | `R/node_modules/zod`,开发者自己安装的版本 | | 链接插件 → `@deepseek-ai/dsh-tools`(peer) | 参与,`R/node_modules` 上该名被占据 | 运行中的 dsh 的那一份;`R/node_modules` 里的 devDependency 副本不被读到 | | 链接插件 → 只声明为 dependency 的有状态 dsh 包 | 参与,未被占据 | `R/node_modules` 里自己的副本,产生第二个实例;与树内把 dsh 包装进 ② 的错误相同,改为 peer 即可 | -| 链接插件 → 未声明的包名 | 参与,未被占据 | `R/node_modules` 的物理内容,再沿 R 的真实祖先链 | -| R 内传递依赖 → 任何包名 | 参与 | 先它自己的本地层,再同上;占据集合仍取 `R/package.json` 的 peer | +| 链接插件 → 未声明的包名 | 参与,R 不占据该包名 | `R/node_modules` 的物理内容,再沿真实祖先链逐位置应用同一规则 | +| R 内传递依赖 → 任何包名 | 参与 | 每个位置使用自己的 manifest 的 peer;更近的物理候选先于后续 peer 声明 | +| link 目标 R 无 manifest → 祖先声明的 peer | 参与 | 从 R 开始查;更近的物理候选优先,否则祖先 peer 可以选中运行时包,即使那里没有物理 `node_modules` | +| 真实目录在所有 linked root 外的提升依赖 → 任何包名 | 不参与 | 从该依赖真实目录进行原生 Node 查询 | +| 任意 importer → `require.resolve(pkg, { paths })` | 不参与 | 使用指定路径进行原生 Node 查询 | ### 三、开发者接入指引 @@ -121,7 +130,7 @@ ESM 与 CommonJS 两个适配器调用同一个路由函数,主线程与 Harne #### 2. 开发模式:插件仓库在 profile 树外 -`npm link`,或 `dsh plugin add ../my-plugin` 这类裸目录路径(pnpm 按 `link:` 处理),会让 profile 里的条目成为指向插件仓库的软链接,仓库目录成为 linked root。插件以真实路径加载,第三方依赖用仓库里自己安装的版本;声明为 peer 的 dsh 包由 `R/node_modules` 上的拦截层提供运行中的那一份,与 dsh 的来源无关:npm 全局安装、Desktop 内置或源码仓启动都一样。仓库里为类型检查安装的 dsh devDependency 只服务编译器,运行时不会被读到。 +`npm link`,或 `dsh plugin add ../my-plugin` 这类裸目录路径(pnpm 按 `link:` 处理),会让 profile 里的条目成为指向插件仓库的软链接,仓库目录成为 linked root。插件以真实路径加载。查找到其 manifest 的 peer 位置时,匹配的运行时条目由当前运行的安装提供,无论 dsh 来自 npm 全局安装、Desktop 内置还是源码仓启动。该位置的 devDependency 副本服务编译器,普通请求不会加载它。link 指向无 manifest 的 `src` 目录时,也可以通过同一条祖先查询使用父目录的 peer。 manifest 的写法与 harness 自身的包相同:需要与宿主共享实例的 dsh 包同时声明在 `peerDependencies` 与 `devDependencies`,peer 让 `R/node_modules` 上的位置被占据,dev 副本给编译器和独立测试使用;第三方依赖以及 `@deepseek-ai/dsh-brand`、`@deepseek-ai/dsh-util-values` 这类无状态 dsh 工具包放在 `dependencies`。修改 `peerDependencies` 后,重新加载插件时的新解析会使用新声明;已加载模块的生命周期仍由 Node 和 Cordis 管理。 @@ -141,9 +150,13 @@ manifest 的写法与 harness 自身的包相同:需要与宿主共享实例 **让 runtime resolution 的全部条目占据 `R/node_modules` 上的包目录。** 与 ③ 完全同形,但闭包里的几百个第三方库会遮住插件仓库自己安装的 `zod`、`yaml` 版本,与树内 ①② 赢 ③ 相反。只占据 peer 保住了「插件自己的第三方版本优先」。 -**按 importer 最近的 manifest 的 `dependencies` 决定哪些包名走原生。** 能模拟「装进 profile 后不装 devDependencies 与 peer」的效果,但每次解析都要为 importer 找最近的 manifest,规则也不再与 ③ 同形。占据 peer 的做法只读 linked root 一份 manifest。 +**按 importer 最近的 manifest 的 `dependencies` 决定哪些包名走原生。** 这类声明不标识查询位置,也无法描述在祖先找到的未声明包。逐位置的 peer 声明只增加一条资格规则,不替换 Node 的查询顺序。 -**在 runtime resolution 构造时固定 peer 集合。** 开发者改一次 `peerDependencies` 就要重启 dsh。解析时读取让重载插件即可生效,代价是开发模式下每次路由多一次小文件读取。 +**只读 linked root 的 peer,或要求它自身有 manifest。** link 可以指向 `src` 目录,更近的包与祖先 manifest 都有各自的查询位置。把拦截固定在 R 会漏掉这些声明,或覆盖更近的物理候选。 + +**在 runtime resolution 构造时固定 peer 集合。** 开发者每次修改 `peerDependencies` 都得重启 dsh。解析时读取让新查询看到变动,代价是开发模式下要读取所访问的 manifest。已加载的请求是否需要再次解析,仍由 Node 的模块缓存决定。 + +**拦截指向 profile 内的显式 CommonJS paths。** 显式搜索列表是调用方的选择。原样交给 Node 能保留一个清晰的例外,而不是让各个路径项遵循不同策略。 **把 linked root 之上的主线接回 profile 的 ②③。** 这是 Node `--preserve-symlinks` 的形式,`R/node_modules` 仍是原生的第一层,devDependency 副本照样先被找到,单实例问题原样保留。 @@ -151,11 +164,16 @@ manifest 的写法与 harness 自身的包相同:需要与宿主共享实例 - [profile-resolution.spec.ts](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts) 中的表驱动矩阵:importer 取 profile 根与 profile 内插件,包名取 installation 条目、bundle-only 条目与表外包名,①②③④ 四层的每一种有无组合,②③ 各含真目录与指向别处的软链接两种形态;每格断言 ESM import、CommonJS require、`require.resolve` 与 `packageDir` 元数据落在同一个目录。 - 同一文件内的 linked root 用例:`/node_modules` 的软链接指向树外仓库,仓库 `node_modules` 里放同名 devDependency 副本;包名取声明为 peer 的 installation 条目、声明为 dependency 的 installation 条目、仓库自己的第三方 dependency、未声明的包名,importer 取仓库自身文件与仓库内传递依赖;断言四种解析方式一致、devDependency 副本不被读到,以及改写 `peerDependencies` 后下一次解析立即按新声明进行。 +- [差分矩阵](../../../../packages/boot/app-boot/tests/linked-resolution-matrix.spec.ts)构造独立的原生、拦截与参考目录。只有参考副本把合格 peer 位置替换为运行时包的链接,再让 Node 解析文件。单包与 pnpm monorepo 用例对比入口、文件、目录、import/require、`import.meta.resolve` 与显式路径的结果,覆盖 manifest 缺失、`node_modules` 缺失、错误 peer 声明、React、作用域外 helper 和旧式子路径继续查询。断言比较选包、现存路径、错误码与模块实例;显式 paths 使用未投射的原生参考。 - 同一文件内的专项用例覆盖表 1 各行:有无 `exports` 的裸包名与子路径、`#alias`、显式 `paths`、包自引用、命中 runtime resolution 后 CommonJS 子路径缺失时跳过 ③ 直接到 ④,以及树外 profile 的拦截位置。 -- [CLI 真启动测试](../../../../apps/cli/tests/profiles/headless/tests/profile-resolution.ts)在 src 与 lib 两种启动、普通目录与 npm-link 两种布局下,放置 ③ 的旧 `@deepseek-ai/dsh-tools` 链接、③ 的外部包及其内嵌依赖,npm-link 布局再给 link 出去的插件放一份 `@deepseek-ai/dsh-tools` devDependency 副本并声明为 peer;断言 Tools 与 AgentLoop 共用同一模块实例、link 出去的插件拿到的 Tools 也是这一份、外部包沿真实路径解析、所有文件与链接目标逐字节不变。 +- [CLI 真启动测试](../../../../apps/cli/tests/profiles/headless/tests/profile-resolution.ts)覆盖 src 与 lib 启动、普通与 npm-link 布局,以及指向无 manifest 的 `src` 目录且其父目录声明 peer 的链接。测试检查 Tools/AgentLoop 共享实例、原生显式路径选中开发者副本、依赖沿真实路径解析,以及文件和链接目标保持不变。 ## Consequences 买到的:模块解析无需磁盘投影;命中拦截层的 dsh 本体包来自当前运行的安装,link 到树外的插件声明的 peer 也适用;其余解析保留 Node 的祖先链和包入口规则;解析路径不识别历史投影目录。 -付出的:installation 闭包里的第三方库仍占据 ③ 上的包目录,profile 插件把第三方库声明成 peer 或漏声明时会拿到 dsh 内部使用的版本,与磁盘链接时代相同,插件应把第三方库声明成 dependency;link 到树外的插件只有声明为 peer 的 dsh 包由运行中的 dsh 提供,声明为 dependency 的仍是自己的副本;只有 `/node_modules` 的直接软链接成为 linked root,插件仓库再 link 出去的依赖、npm workspace 提升到仓库之外的依赖不在任何 linked root 下,仍是纯 Node;peer 到 profile 里其他插件的请求不接 ②,沿 R 的真实祖先链找不到就报错;开发模式下每次路由读一次插件 manifest;同一逻辑路径换 link 目标仍需重启;不经过 hook 的消费者,即插件自己 spawn 的子进程、第三方 Worker、在 profile 目录里运行的外部工具,不再能通过 `$DSH_HOME/profiles/node_modules` 的磁盘链接找到本体包;resolver 继续依赖受支持的 Node Internal 接口。 +付出的:installation 闭包中的第三方库仍占据 ③ 上的包目录;profile 插件没有更近副本时会使用安装中的版本。linked 请求只在匹配的 peer 位置选中运行时包,更近的物理副本仍优先。开发者需要相应安排声明与依赖位置。runtime resolution 不校验 peer 版本范围。 + +只有 `/node_modules` 的直接链接成为 linked root;依赖真实目录在所有已记录根之外时使用原生 Node。peer 请求不会回到 profile 的 ②:运行时表不提供的包名必须能在真实祖先链上找到。linked 请求承担实时读取 peer manifest 的成本。同一链接换目标仍需重启;模块缓存失效与自动监视不属于这条规则。 + +显式 CommonJS paths、插件自行启动的子进程、第三方 Worker 和外部工具不会获得运行时 peer 映射。不经过 hook 的消费者无法通过生成的磁盘链接找到本体包。resolver 继续依赖受支持的 Node Internal 接口。 diff --git a/apps/cli/tests/profiles/headless/tests/profile-resolution.ts b/apps/cli/tests/profiles/headless/tests/profile-resolution.ts index e869e02282..90fb6bc7f2 100644 --- a/apps/cli/tests/profiles/headless/tests/profile-resolution.ts +++ b/apps/cli/tests/profiles/headless/tests/profile-resolution.ts @@ -15,6 +15,7 @@ const bundleName = 'profile-resolution-bundle' const bridgeName = 'profile-resolution-bridge' const leafName = 'profile-resolution-leaf' const pluginName = 'profile-resolution-plugin' +const sourceProbeName = 'source-probe' const externalName = 'profile-resolution-external' const externalLeafName = 'profile-resolution-external-leaf' const marker = 'DSH_PROFILE_RESOLUTION ' @@ -34,6 +35,10 @@ interface ResolutionEvidence { externalManaged: boolean toolsInstance: boolean pluginToolsInstance: boolean + sourceToolsInstance: boolean + profileToolsCjs: string + sourceToolsCjs: string + sourceToolsExplicitCjs: string scheduler: boolean modules: string[] } @@ -132,8 +137,25 @@ export function testProfileResolution(mode: ExampleMode): void { 'index.mjs': "export default class Tools {}\nexport const TOOL_RUNTIME_SCHEDULER = Symbol()\nthrow new Error('STALE_DSH_TOOLS')", 'index.cjs': "throw new Error('STALE_DSH_TOOLS')", }) + const sourcePackageDir = join(root, 'work', 'source-package') + const sourceDir = join(sourcePackageDir, 'src') + await mkdir(sourceDir, { recursive: true }) + await writePackage(sourcePackageDir, { + name: 'source-package', version: '1.0.0', peerDependencies: { '@deepseek-ai/dsh-tools': '*' }, + }, { + 'src/query.mjs': [ + "import { createRequire } from 'node:module'", + "import Tools from '@deepseek-ai/dsh-tools'", + 'export { Tools as SourceTools }', + 'const require = createRequire(import.meta.url)', + "export const sourceToolsCjs = require.resolve('@deepseek-ai/dsh-tools')", + `export const sourceToolsExplicitCjs = require.resolve('@deepseek-ai/dsh-tools', { paths: [${JSON.stringify(sourceDir)}] })`, + ].join('\n'), + }) for (const [target, link] of [ [staleTools, staleToolsLink], + [sourceDir, join(profileDir, 'node_modules', sourceProbeName)], + [staleTools, join(sourcePackageDir, 'node_modules', '@deepseek-ai', 'dsh-tools')], ...layout === 'npm-link' ? [ [externalDir, sharedExternal], [pluginDir, installedPlugin], @@ -159,6 +181,7 @@ export function testProfileResolution(mode: ExampleMode): void { `import { leaf as bridgeLeaf } from '${bridgeName}'`, `import { external } from '${externalName}'`, `import { external as pluginExternal, PluginTools } from '${pluginName}'`, + `import { SourceTools, sourceToolsCjs, sourceToolsExplicitCjs } from '${sourceProbeName}/query.mjs'`, `import { leaf as externalLeaf } from ${JSON.stringify(pathToFileURL(join(externalLeaf, 'index.mjs')).href)}`, 'const require = createRequire(import.meta.url)', "export const inject = ['tools', 'agentLoop', 'loader']", @@ -181,6 +204,9 @@ export function testProfileResolution(mode: ExampleMode): void { ` externalManaged: entries.some(entry => [${JSON.stringify(externalName)}, ${JSON.stringify(externalLeafName)}].includes(entry.name)),`, ' toolsInstance: ctx.tools instanceof Tools,', ' pluginToolsInstance: ctx.tools instanceof PluginTools,', + ' sourceToolsInstance: ctx.tools instanceof SourceTools,', + " profileToolsCjs: require.resolve('@deepseek-ai/dsh-tools'),", + ' sourceToolsCjs, sourceToolsExplicitCjs,', " scheduler: typeof ctx.tools[TOOL_RUNTIME_SCHEDULER]?.prepare === 'function',", ' modules: [...ctx.loader.internal.loadCache.keys()]', ' .filter(url => /\\/packages\\/core\\/(?:tools|agent-loop)\\//.test(url)),', @@ -202,7 +228,7 @@ export function testProfileResolution(mode: ExampleMode): void { }) const packageDirs = [ bundleDir, bridgeDir, logicalLeaf, realLeaf, pluginDir, externalDir, externalLeaf, - sharedLeaf, ancestorExternal, ancestorLeaf, staleTools, profileDir, + sharedLeaf, ancestorExternal, ancestorLeaf, staleTools, sourcePackageDir, sourceDir, profileDir, ] const packageFiles = (await Promise.all(packageDirs.map(async dir => (await readdir(dir, { withFileTypes: true })).filter(entry => entry.isFile()).map(entry => join(dir, entry.name)), @@ -250,6 +276,10 @@ export function testProfileResolution(mode: ExampleMode): void { expect(evidence.externalManaged).toBe(false) expect(evidence.toolsInstance).toBe(true) expect(evidence.pluginToolsInstance).toBe(true) + expect(evidence.sourceToolsInstance).toBe(true) + expect(evidence.sourceToolsCjs).toBe(evidence.profileToolsCjs) + expect(evidence.sourceToolsExplicitCjs).toBe(realpathSync.native(join(staleTools, 'index.cjs'))) + expect(evidence.sourceToolsCjs).not.toBe(evidence.sourceToolsExplicitCjs) expect(evidence.scheduler).toBe(true) expect(evidence.execArgv).toEqual(mode === 'src' ? launch.args.slice(0, 2) : []) for (const name of ['tools', 'agent-loop']) { @@ -260,6 +290,7 @@ export function testProfileResolution(mode: ExampleMode): void { } for (const [path, content] of contents) expect(await readFile(path), path).toEqual(content) for (const [path, target] of linkTargets) expect(await readlink(path), path).toBe(target) + expect(await readdir(sourceDir)).toEqual(['query.mjs']) } finally { try { for (const link of links.reverse()) await unlink(link) diff --git a/docs/user/develop/basic/publish.i18n.yaml b/docs/user/develop/basic/publish.i18n.yaml index 52fc874528..4641bc607c 100644 --- a/docs/user/develop/basic/publish.i18n.yaml +++ b/docs/user/develop/basic/publish.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 docs/user/develop/basic/publish.md -publish.md: f7b62bce5c66dd183707795754d210f5117de7c4 -publish.zh.md: f999714d90397865d6f89e7ef02766c01f73683c +publish.md: bdc6f21ec6d3a4777cf3e0c14771c19a08ed4b5e +publish.zh.md: 43fcea22873733784f46d97bcd16bfdb297dc3ed diff --git a/docs/user/develop/basic/publish.md b/docs/user/develop/basic/publish.md index f7b62bce5c..bdc6f21ec6 100644 --- a/docs/user/develop/basic/publish.md +++ b/docs/user/develop/basic/publish.md @@ -100,7 +100,9 @@ The first use initializes the profile (with `@deepseek-ai/dsh-base` as its first } ``` -A linked checkout keeps its own `node_modules`. Declare dsh packages whose instances the plugin must share with the host under both `peerDependencies` and `devDependencies`, as the harness packages do. The devDependency copy serves your type checker and standalone tests; peers present in the running dsh's runtime resolution use that installation's copy, whether dsh comes from npm, Desktop, or source. Keep third-party dependencies and stateless dsh utilities under `dependencies`. After changing `peerDependencies`, new resolutions during a plugin reload read the new declaration; this does not automatically reload already loaded modules. +A linked checkout keeps its own `node_modules`. Declare dsh packages whose instances the plugin must share with the host under both `peerDependencies` and `devDependencies`, as the harness packages do. At that manifest's lookup position, peers present in the running dsh's runtime resolution use the installation's copy; the devDependency copy serves your type checker and standalone tests. Keep independently versioned third-party dependencies and stateless dsh utilities under `dependencies`. + +Ordinary linked imports follow Node's ancestor order and check each directory's current peer declarations. A nearer physical package wins before a higher peer declaration. A link target can lack `package.json`; ancestor peers still apply, even without a physical `node_modules` beside that manifest. Explicit `require.resolve(..., { paths })` is always native, including paths inside a profile. These rules are shared by npm, Desktop, and source launches; they do not invalidate loaded modules or validate peer version ranges. See the [resolution rules](../../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md) for scope and file-query behavior. Verify the layer without booting, then boot: diff --git a/docs/user/develop/basic/publish.zh.md b/docs/user/develop/basic/publish.zh.md index f999714d90..43fcea2287 100644 --- a/docs/user/develop/basic/publish.zh.md +++ b/docs/user/develop/basic/publish.zh.md @@ -100,7 +100,9 @@ dsh plugin --profile demo add ./hello-plugin } ``` -通过链接安装的 checkout 保留自己的 `node_modules`。与 harness 自身的包一样,需要与宿主共享实例的 dsh 包同时声明在 `peerDependencies` 与 `devDependencies` 中。devDependency 副本供类型检查和独立测试使用;运行中 dsh 的 runtime resolution 已包含的 peer 使用该安装提供的副本,无论 dsh 来自 npm、Desktop 还是源码。第三方依赖和无状态 dsh 工具包放在 `dependencies` 中。修改 `peerDependencies` 后,重新加载插件时的新解析会读取新声明;这不会自动重载已经加载的模块。 +通过链接安装的 checkout 保留自己的 `node_modules`。与 harness 自身的包一样,需要与宿主共享实例的 dsh 包同时声明在 `peerDependencies` 与 `devDependencies` 中。在该 manifest 的查询位置,运行中 dsh 的 runtime resolution 已包含的 peer 使用安装中的副本;devDependency 副本供类型检查和独立测试使用。需要独立版本的第三方依赖和无状态 dsh 工具包放在 `dependencies` 中。 + +普通 linked import 遵循 Node 的祖先顺序,检查每个目录当前的 peer 声明。更近的物理包先于更高的 peer 声明。link 目标可以没有 `package.json`,祖先 peer 仍可生效,即使该 manifest 旁没有物理 `node_modules`。显式 `require.resolve(..., { paths })` 始终是原生查询,包括指向 profile 内的路径。npm、Desktop 与源码启动共用这些规则;规则不会使已加载模块失效,也不校验 peer 版本范围。作用域和文件查询行为见[解析规则](../../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md)。 先不启动、只验证该层,再启动: diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml index b6de37fe50..67d3b0d201 100644 --- a/packages/boot/app-boot/README.i18n.yaml +++ b/packages/boot/app-boot/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md -README.md: bccf796fb679ebd7251baae5ae0952a8f6498ae1 -README.zh.md: fc421045ed45d639ec92be2ebe43a888c808ce0a +README.md: a3c85a76c919cbedf548a35008660a0346a8e8f7 +README.zh.md: b53d8eeff682ffa6040a2a4c10a79f0b9cedb827 diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md index bccf796fb6..a3c85a76c9 100644 --- a/packages/boot/app-boot/README.md +++ b/packages/boot/app-boot/README.md @@ -114,7 +114,9 @@ This section explains how the outcomes above are realized and points at the code ### Design notes - **Profile launch data.** `ctx.profileContext` contains only profile locations, startup bundle names, parsed invocation overlays and the telemetry opt-out value. `readProfilePatches()` composes the supplied startup profile or reads current files at those locations; callers schedule and apply the result. -- **Process-local module resolution.** The launcher installs the runtime resolution as an interception on Node's internal ESM and CommonJS resolvers before profile rows mount. Node still owns exports, conditions, subpaths, module caches, and error codes; routed ESM failures report the original importer instead of the internal lookup anchor. A profile package linked outside the profiles tree is a linked root. At `/node_modules`, the runtime resolution supplies names that have an entry and appear in the linked package's current `peerDependencies`; the same-named devDependency copy at this position is not loaded ([rule](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md)). `ctx.pluginPackages` exposes package metadata from the same runtime resolution without recording Entry imports; an installed runtime resolution is authoritative even for a miss, while low-level embedders that install the service without one retain native lookup. +- **Process-local module resolution.** The launcher installs the runtime resolution on Node's internal ESM and CommonJS resolvers before profile rows mount. Node still owns exports, conditions, subpaths, module caches, and error codes; routed ESM failures report the original importer. Explicit CommonJS `paths` always retain native lookup, including paths inside profiles. +- **Linked directories.** A profile link to an external directory admits its importers to peer-aware ancestor lookup, even without its own `package.json`. At each `D/node_modules` position, current `D/package.json` peer names present in the runtime table use the runtime package; other names use the physical candidate. A nearer physical package precedes a later peer declaration, and a peer position needs no physical `node_modules` ([rule](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md)). +- **Package metadata.** `ctx.pluginPackages.packageOf` locates the owning package without loading code or requiring an exported `package.json`; a subpath selects its package without validating that file. The installed runtime resolution owns selection even for a miss. Low-level embedders that install the service without one retain native lookup. Display metadata uses the separate entry-aware reader described above. - **Two Loader builtins.** `mountRootInclude` registers `cordis:include` and `cordis:group` as Loader builtins: a group row gives one `isolate` realm to a provider and its consumers together, and an agent preset outside this workspace cannot resolve `@deepseek-ai/cordis-plugin-group` by name. Both load through the ambient module pipeline rather than the included tree's own specifier resolution. - **Consumer-owned strictness.** Ordinary Loader groups keep successful siblings. App-boot applies the global required-entry policy after initial settlement; agent presets and dynamic multi-entry compositions own and dispose their separate Loader subtree when they require all-or-nothing setup. App-boot reads failed fibers to report their recorded errors and coalesces duplicate Loader rejection notifications through one process checkpoint. - **One runtime resolution.** The installation-first and ordered-bundle breadth-first traversal produces the runtime table. Runtime resolution creates no links; runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`, and every other name sees that directory as an ordinary ancestor. Profile load removes the `.dsh-module-fallback` projections that link-backend releases wrote into a profile; pnpm-installed packages stay. External bare targets selected by package `imports` use the same package order, while Node retains mapping, conditions, and exact target resolution. A complete successor may add package names and update linked-root membership atomically within the existing package-mapping and local-name constraints; changing or removing an existing mapping, or pointing an existing linked root at another directory, requires restart. @@ -179,6 +181,7 @@ These limits describe when this boot library is a poor fit or needs special care - **Runtime resolution depends on Node internals** — supported Node versions require the native builtin-access addon and executable compatibility coverage. Only built Harness-owned Workers receive the runtime resolution bootstrap; third-party Workers and custom `vm` linkers keep native resolution. - **Relinking a profile package needs a restart** — Node caches real paths, so changing the target of a profile link or a dependency link requires a process restart. +- **Linked scope follows recorded real directories** — a hoisted dependency outside every linked root uses native Node. Current peer reads do not invalidate Node caches, watch files, or validate peer version ranges. - **Snapshot replay swapping is basename-specific** — only a config ending in `cordis.yml` or `cordis.yaml` maps to the sibling `cordis.snapshot.yml`; custom config names require caller-managed selection. - **Environment discovery is launch-scoped** — `loadLayeredEnv` reads only the invocation directory and Harness home once; it does not search parents or follow a workspace selected later. `loadEnv` remains the one-directory helper for non-product bins. - **A user patch replaces the whole matched config** — an id-targeted patch does not deep-merge, so a profile override restates the bundle fields it keeps. diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md index fc421045ed..b53d8eeff6 100644 --- a/packages/boot/app-boot/README.zh.md +++ b/packages/boot/app-boot/README.zh.md @@ -114,7 +114,9 @@ Loader 结算后,app-boot 在仅 optional 条目未激活时输出警告。如 ### 设计说明 - **Profile 启动数据。** `ctx.profileContext` 只包含 profile 位置、启动时组合包名称、已解析的调用级 overlay 与遥测退出值。`readProfilePatches()` 组合传入的启动 profile,或读取这些位置上的当前文件;调用方负责调度和应用结果。 -- **进程内模块解析。** runtime 解析会在挂载 profile 条目前,将 runtime resolution 作为拦截安装到 Node 的 ESM 与 CommonJS 内部 resolver。exports、conditions、subpath、模块缓存和错误码仍由 Node 负责;路由后的 ESM 失败会报告原始 importer,而不是内部查找锚点。profile 中链接到 profiles 树外的包是一个 linked root。在 `/node_modules` 这一层,runtime resolution 提供同时具有表条目、且出现在该包当前 `peerDependencies` 中的包名;这个位置的同名 devDependency 副本不会被加载([规则](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md))。`ctx.pluginPackages` 从同一 runtime resolution 提供 package metadata,不记录 Entry import;安装 runtime resolution 后,即使查询未命中也以 runtime resolution 为准,仅安装服务而未提供 runtime resolution 的底层嵌入方仍使用 Node 原生查找。 +- **进程内模块解析。** launcher 在挂载 profile 条目前,将 runtime resolution 安装到 Node 的 ESM 与 CommonJS 内部 resolver。exports、conditions、子路径、模块缓存和错误码仍由 Node 负责;路由后的 ESM 失败报告原始 importer。显式 CommonJS `paths` 始终保留原生查询,包括指向 profile 内的路径。 +- **链接目录。** profile 链接到树外目录时,其下的 importer 参与逐层 peer 查询,即使目标没有自身的 `package.json`。在每个 `D/node_modules` 位置,当前 `D/package.json` 的 peer 包名若存在于运行时表,就使用运行时包;其他包名查询物理候选。更近的物理包先于后续 peer 声明,peer 位置无需物理 `node_modules`([规则](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md))。 +- **包元数据。** `ctx.pluginPackages.packageOf` 定位所属包,不加载代码,也不要求导出 `package.json`;子路径选择其所属包,不校验该文件。安装 runtime resolution 后,即使查询未命中也以其选包规则为准。仅安装服务而不提供 runtime resolution 的底层嵌入方保留原生查询。展示元数据使用上文另述的入口感知读取器。 - **两个 Loader builtin。** `mountRootInclude` 把 `cordis:include` 与 `cordis:group` 注册为 Loader builtin:group 行能把一个提供方与它的消费方放进同一个 `isolate` realm,而位于本工作区之外的 agent preset 无法按名称解析 `@deepseek-ai/cordis-plugin-group`。两者都通过宿主的模块管线加载,而非被包含树自身的说明符解析。 - **由 consumer 持有严格语义。** 普通 Loader group 保留成功 sibling。App-boot 在首次结算后应用全局 required-entry policy;agent preset 与动态多 entry 组合在需要 all-or-nothing setup 时,持有并拆卸各自的独立 Loader 子树。App-boot 读取 failed fiber 来报告已记录的错误,并在一个进程检查点内合并 Loader 重复的 rejection 通知。 - **唯一 runtime resolution。** 安装优先、有序 bundle 逐根 breadth-first 遍历生成运行时表。runtime 解析不创建链接;runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置,其余包名把该目录当作普通祖先。profile 加载时删除 Link 后端发布版写进 profile 的 `.dsh-module-fallback` 投影;pnpm 安装的包保留。package `imports` 选中的外部 bare target 使用相同的选包顺序,映射、conditions 和精确 target 解析仍由 Node 负责。完整后继 runtime resolution 可以在既有包映射和本地包名约束内原子增加 package name、更新 linked root 集合;修改或删除既有映射,或把既有 linked root 指向另一个目录,则要求重启。 @@ -179,6 +181,7 @@ Loader 结算后,app-boot 在仅 optional 条目未激活时输出警告。如 - **运行时解析依赖 Node 内部机制**——受支持的 Node 版本需要 native builtin access addon 和可执行兼容验证。只有构建后的 Harness 自有 Worker 接收 runtime resolution bootstrap;第三方 Worker 与自定义 `vm` linker 保持原生解析。 - **重新链接 profile 包需要重启**——Node 缓存真实路径,因此改变 profile 链接或依赖链接的目标需要重启进程。 +- **链接作用域以记录的真实目录为准**——提升后的依赖若在所有 linked root 之外,就使用原生 Node。实时读取 peer 不会使 Node 缓存失效、监视文件或校验 peer 版本范围。 - **快照回放替换仅识别特定 basename**——只有以 `cordis.yml` 或 `cordis.yaml` 结尾的配置会映射到同级 `cordis.snapshot.yml`;自定义配置名称需要调用方自行选择。 - **环境发现以启动为界**——`loadLayeredEnv` 只读取一次调用目录与 harness home 中的 `.env`;它不搜索父目录,也不跟随之后选择的 workspace。`loadEnv` 仍是非产品 bin 使用的单目录 helper。 - **用户 patch 会替换匹配到的整个配置**——按 id 定位的 patch 不做深度合并,因此 profile 覆盖必须重述需要保留的组合包字段。 diff --git a/packages/boot/app-boot/src/profile-resolution/resolver.ts b/packages/boot/app-boot/src/profile-resolution/resolver.ts index feed6790aa..edbeafc597 100644 --- a/packages/boot/app-boot/src/profile-resolution/resolver.ts +++ b/packages/boot/app-boot/src/profile-resolution/resolver.ts @@ -66,6 +66,12 @@ interface ResolutionRouteState { cjs?: string } +interface CommonJsLookup { + readonly cacheable: boolean + resolveNative(searchPaths: readonly string[]): string + resolveEntry(entry: RuntimeResolutionEntry, after: string): string +} + /** The lookup positions that one interception layer fixes on an importer's ancestor chain. */ interface LayerPositions { /** Search paths with this prefix lie below the layer and are answered by their physical content. */ @@ -78,12 +84,12 @@ interface LayerPositions { /** * The interception layer of one importer. A profile's layer is its parent's node_modules and answers every entry - * for the active profile; a linked package's layer is its own node_modules, occupied only by the package's - * current peers and never memoized. + * for the active profile. Linked importers apply current peer declarations at each ancestor node_modules + * position without memoizing the selected route. */ type InterceptionLayer = | LayerPositions & { readonly kind: 'profile'; readonly active: boolean } - | LayerPositions & { readonly kind: 'linked'; readonly root: LinkedRoot } + | { readonly kind: 'linked'; readonly root: LinkedRoot } interface CompiledLinkedRoot { readonly root: LinkedRoot @@ -116,6 +122,7 @@ interface CompiledResolution { export interface RuntimeInterception { /** * Locate a bare package without requiring one of its exports. + * A package subpath selects its package directory without resolving or validating the requested file. * @param specifier - bare package or package-subpath specifier. * @param parentURL - file URL whose lookup order applies. * @returns selected package directory, or undefined when it is absent. @@ -190,15 +197,11 @@ function computeProfileLayer(dir: string, active: boolean): InterceptionLayer { } /** - * A linked package keeps Node's lookup from its real path: `/node_modules` is its interception layer, - * deeper node_modules directories are local, and the layer above it belongs to the real parent directory. + * A linked directory admits its importers to peer-aware lookup along Node's real ancestor chain. */ function computeLinkedLayer(root: LinkedRoot): InterceptionLayer { return { kind: 'linked', root, - localPrefix: join(root.realPath, 'node_modules') + sep, - nativeAfter: join(root.realPath, 'package.json'), - after: join(dirname(root.realPath), 'package.json'), } } @@ -211,10 +214,10 @@ function findInterceptionLayer(path: string, resolution: CompiledResolution): In return resolution.linkedRoots.find(candidate => startsWithin(path, candidate.paths))?.layer } -/** Package names the linked package's manifest currently lists as peers; an unreadable manifest lists none. */ -function readLinkedPeerNames(root: LinkedRoot): ReadonlySet { +/** Package names a directory's current manifest lists as peers; an unreadable manifest lists none. */ +function readPeerNames(directory: string): ReadonlySet { try { - const manifest = JSON.parse(readFileSync(join(root.realPath, 'package.json'), 'utf8')) as { + const manifest = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8')) as { peerDependencies?: unknown } const peers = manifest.peerDependencies @@ -368,7 +371,7 @@ function sameResolution(left: string, right: string): boolean { class ResolutionRouter { private current: CompiledResolution - constructor(resolution: RuntimeResolution) { + constructor(resolution: RuntimeResolution, private readonly nodeModulePaths: (directory: string) => string[]) { this.current = compileResolution(resolution) } @@ -446,11 +449,10 @@ class ResolutionRouter { parentRoutes: ParentRoutes, resolution: CompiledResolution, flavor: 'esm' | 'cjs', - nativeResolve?: (searchPaths: readonly string[]) => string, - cacheable = false, + cjs?: CommonJsLookup, ): ResolutionRouteState | undefined { const { parent, layer, requests } = parentRoutes - const memo = layer.kind === 'profile' + const memo = layer.kind === 'profile' && (cjs === undefined || cjs.cacheable) const name = barePackageName(request) if (name === undefined) return undefined @@ -463,6 +465,8 @@ class ResolutionRouter { return state } + if (layer.kind === 'linked') return this.routeLinked(request, name, parent, resolution, flavor, cjs) + const target = resolution.entries.get(name) const candidates: string[] = [] const localSearchPaths: string[] = [] @@ -473,9 +477,9 @@ class ResolutionRouter { if (candidate !== undefined) candidates.push(candidate) } if (candidates.length > 0) { - if (flavor === 'cjs' && nativeResolve !== undefined) { + if (cjs !== undefined) { try { - const resolved = nativeResolve(localSearchPaths) + const resolved = cjs.resolveNative(localSearchPaths) const selected = candidates.find(candidate => ( localCandidateOwnsResolution(candidate, resolved, request, name) )) @@ -483,7 +487,7 @@ class ResolutionRouter { const state = { route: { kind: 'native' as const, packageDir: selected }, packageDir: selected, - ...(cacheable && memo ? { cjs: resolved } : {}), + cjs: resolved, } if (memo) requests.set(request, state) return state @@ -497,15 +501,13 @@ class ResolutionRouter { route: { kind: 'native' as const, packageDir: selected }, packageDir: selected, } - if (memo) requests.set(request, state) + requests.set(request, state) return state } } - // An entry occupies its name at the interception layer; below a linked root only the names its manifest - // currently lists as peers are occupied. const route: ResolutionRoute = target !== undefined - && (layer.kind === 'linked' ? readLinkedPeerNames(layer.root).has(name) : target.scope === 'installation' || layer.active) + && (target.scope === 'installation' || layer.active) ? { kind: 'interception', entry: target, after: layer.after } : { kind: 'native-after-interception', parent: layer.nativeAfter } const state: ResolutionRouteState = { route } @@ -513,6 +515,47 @@ class ResolutionRouter { return state } + private routeLinked( + request: string, name: string, parent: string, resolution: CompiledResolution, + flavor: 'esm' | 'cjs', cjs: CommonJsLookup | undefined, + ): ResolutionRouteState { + const target = resolution.entries.get(name) + if (target === undefined) return { route: { kind: 'native' } } + const ancestors = this.nodeModulePaths(dirname(parent)) + const ancestorSet = new Set(ancestors) + const searchPaths = flavor === 'esm' ? ancestors : createRequire(parent).resolve.paths(name) as string[] + for (const searchPath of searchPaths) { + const directory = dirname(searchPath) + if (ancestorSet.has(searchPath) && readPeerNames(directory).has(name)) { + const route: ResolutionRoute = { kind: 'interception', entry: target, after: join(dirname(directory), 'package.json') } + if (cjs === undefined) return { route } + try { + const resolved = cjs.resolveEntry(target, route.after) + if (localCandidateOwnsResolution(target.packageDir, resolved, request, name)) { + return { route, packageDir: target.packageDir, cjs: resolved } + } + } catch (error) { + if (!isUnselectedPackageMiss(error)) throw error + } + // This position is occupied even when a legacy CommonJS subpath is absent from the supplied package. + continue + } + const candidate = localPackageCandidate(searchPath, name, flavor) + if (candidate === undefined) continue + if (cjs === undefined) return { route: { kind: 'native', packageDir: candidate }, packageDir: candidate } + try { + const resolved = cjs.resolveNative([searchPath]) + if (localCandidateOwnsResolution(candidate, resolved, request, name)) { + return { route: { kind: 'native', packageDir: candidate }, packageDir: candidate, cjs: resolved } + } + } catch (error) { + if (!isUnselectedPackageMiss(error)) throw error + } + } + // An exhausted CommonJS lookup must not retry the physical copies at occupied peer positions. + return cjs === undefined ? { route: { kind: 'native' } } : { route: { kind: 'native' }, cjs: cjs.resolveNative([]) } + } + private routeLocalPackage( request: string, parentRoutes: ParentRoutes, resolution: CompiledResolution, ): ResolutionRouteState | undefined { @@ -536,45 +579,25 @@ class ResolutionRouter { } routePath( - request: string, parent: string, nativeResolve?: (searchPaths: readonly string[]) => string, cacheable = false, + request: string, parent: string, cjs: CommonJsLookup, ): ResolutionRouteState | undefined { const resolution = this.current let parentRoutes = resolution.cjsRoutes.get(parent) if (parentRoutes === false) return undefined - const cached = parentRoutes?.requests.get(request) + const cached = cjs.cacheable ? parentRoutes?.requests.get(request) : undefined if (cached !== undefined) return cached if (parentRoutes === undefined) { parentRoutes = this.createParentRoutes(parent, resolution) ?? false resolution.cjsRoutes.set(parent, parentRoutes) if (parentRoutes === false) return undefined } - return this.routeScoped(request, parentRoutes, resolution, 'cjs', nativeResolve, cacheable) - } - - explicitRoute( - request: string, paths: readonly string[], - ): { index: number; parent: string } | undefined { - if (barePackageName(request) === undefined) return undefined - for (const [index, path] of paths.entries()) { - const parent = join(resolve(path), '.dsh-profile-resolution.cjs') - if (startsWithin(parent, this.current.profilePaths) || startsWithin(parent, this.current.profile)) { - return { index, parent } - } - } - return undefined - } - - nativeSelfReference(request: string, parent: string): boolean { - const name = barePackageName(request) - if (name === undefined) return false - const self = selfReferenceName(parent) - return self === name || self === null + return this.routeScoped(request, parentRoutes, resolution, 'cjs', cjs) } packageDir(specifier: string, parentURL: string): string | undefined { const name = barePackageName(specifier) if (name === undefined) return undefined - const state = this.routeUrl(specifier, parentURL) + const state = this.routeUrl(name, parentURL) if (state?.route.kind === 'interception') return state.route.entry.packageDir if (state?.packageDir !== undefined) return state.packageDir let parent: string @@ -677,8 +700,8 @@ function throwWithoutCjsAnchor(error: unknown, anchor: string): never { export function installRuntimeInterception( resolution: RuntimeResolution, ): RuntimeInterception { - const router = new ResolutionRouter(resolution) const { esm, esmDefaultResolve, esmConditions, cjs, cjsConditions, modern } = internalModules() + const router = new ResolutionRouter(resolution, directory => cjs._nodeModulePaths(directory)) let delegatedEsm: { parent: string | undefined; request: string } | undefined const adaptEsm = (native: EsmResolve): EsmResolve => { @@ -801,7 +824,7 @@ export function installRuntimeInterception( parentFilename: string, main: boolean, conditions: ReadonlySet | undefined, ): string => { const synthetic = new cjs(parentFilename) - synthetic.parent = parent + if (parent.parent !== undefined) synthetic.parent = parent.parent synthetic.filename = parentFilename synthetic.paths = [...searchPaths] const options = conditions === undefined ? undefined : { conditions } @@ -822,37 +845,24 @@ export function installRuntimeInterception( return resolveFrom(pathToFileURL(route.entry.declarer).href) } const wrappedFilename: CommonJsModule['_resolveFilename'] = (request, parent, main, options) => { - if (delegatedCjs || !parent?.filename) { + if (delegatedCjs || !parent?.filename || options?.paths !== undefined) { return originalFilename.call(cjs, request, parent, main, options) } const parentFilename = parent.filename - const cacheable = options?.paths === undefined && options?.conditions === undefined - const explicitPaths = Array.isArray(options?.paths) ? options.paths : undefined - if (explicitPaths !== undefined && router.nativeSelfReference(request, parentFilename)) { - return originalFilename.call(cjs, request, parent, main, options) - } - const explicit = explicitPaths === undefined - ? undefined - : router.explicitRoute(request, explicitPaths) - if (options?.paths !== undefined && explicit === undefined) { - return originalFilename.call(cjs, request, parent, main, options) - } - if (explicit !== undefined && explicitPaths !== undefined && explicit.index > 0) { - try { - return originalFilename.call(cjs, request, parent, main, { - ...options, - paths: explicitPaths.slice(0, explicit.index), - }) - } catch (error) { - if (!isUnselectedPackageMiss(error)) throw error - } - } - const state = router.routePath( - request, - explicit?.parent ?? parentFilename, - searchPaths => resolveNativeCjs(request, searchPaths, parent, parentFilename, main, options?.conditions), - explicit === undefined && cacheable, - ) + const cacheable = options?.conditions === undefined + const routedOptions = options?.conditions === undefined ? undefined : { conditions: options.conditions } + const state = router.routePath(request, parentFilename, { + cacheable, + resolveNative: searchPaths => resolveNativeCjs(request, searchPaths, parent, parentFilename, main, options?.conditions), + resolveEntry: (entry, after) => { + delegatedCjs++ + try { + return resolveRoutedCjs(request, { kind: 'interception', entry, after }, parent, main, routedOptions) + } finally { + delegatedCjs-- + } + }, + }) if (state === undefined) { const scoped = router.hasInterceptionLayerForPath(parentFilename) const conditions = options?.conditions ?? cjsConditions @@ -862,52 +872,23 @@ export function installRuntimeInterception( if (target === undefined) return originalFilename.call(cjs, request, parent, main, options) return resolvePackageImportCjs(target, conditions) } - if (cacheable && state.cjs !== undefined) return state.cjs + if (state.cjs !== undefined) return state.cjs const route = state.route if (route.kind === 'native') { const result = originalFilename.call(cjs, request, parent, main, options) if (cacheable) state.cjs = result return result } - if (route.kind === 'native-after-interception' && explicit !== undefined && explicitPaths !== undefined) { - try { - return originalFilename.call(cjs, request, parent, main, { - ...options, - paths: [dirname(route.parent)], - }) - } catch (error) { - if (!isUnselectedPackageMiss(error)) throw error - const remaining = explicitPaths.slice(explicit.index + 1) - if (remaining.length === 0) throw error - return wrappedFilename(request, parent, main, { ...options, paths: remaining }) - } - } delegatedCjs++ try { - const routedOptions = options?.conditions === undefined ? undefined : { conditions: options.conditions } let expected: string try { expected = resolveRoutedCjs(request, route, parent, main, routedOptions) } catch (error) { if (route.kind !== 'interception' || !isUnselectedPackageMiss(error)) throw error - try { - expected = resolveRoutedCjs( - request, { kind: 'native-after-interception', parent: route.after }, parent, main, routedOptions, - ) - } catch (afterError) { - const remaining = explicit === undefined || explicitPaths === undefined - ? [] - : explicitPaths.slice(explicit.index + 1) - if (!isUnselectedPackageMiss(afterError) || remaining.length === 0) { - throw afterError - } - delegatedCjs-- - try { - return wrappedFilename(request, parent, main, { ...options, paths: remaining }) - } finally { - delegatedCjs++ - } - } + expected = resolveRoutedCjs( + request, { kind: 'native-after-interception', parent: route.after }, parent, main, routedOptions, + ) } if (cacheable) state.cjs = expected return expected diff --git a/packages/boot/app-boot/src/profile.ts b/packages/boot/app-boot/src/profile.ts index d6e7cb183e..ac0fb71734 100644 --- a/packages/boot/app-boot/src/profile.ts +++ b/packages/boot/app-boot/src/profile.ts @@ -22,7 +22,7 @@ */ import { createRequire } from 'node:module' -import { existsSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, unlinkSync, writeFileSync } from 'node:fs' +import { existsSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs' import { basename, dirname, join, relative, resolve, sep } from 'node:path' import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader' import { applyEntryPatches, type PatchOptions } from '@deepseek-ai/cordis-plugin-include' @@ -113,16 +113,15 @@ export interface RuntimeResolutionEntry { } /** - * A profile package whose `node_modules` entry is a symlink or junction to a directory outside the profiles tree. - * Importers below `realPath` keep Node's lookup from the real path; `/node_modules` is their interception - * layer, occupied only by the names the package's current manifest lists under `peerDependencies`. + * A profile node_modules entry linked to a directory outside the profiles tree. + * Importers below `realPath` use Node's real ancestor chain, with peer mappings read at each node_modules position. */ export interface LinkedRoot { /** Package name of the profile `node_modules` entry, including its scope. */ readonly name: string /** The symlink or junction path under the active profile's node_modules. */ readonly linkPath: string - /** Real directory the link resolves to; it lies outside the profiles tree and holds a package.json. */ + /** Real directory the link resolves to; it lies outside the profiles tree and need not hold a package.json. */ readonly realPath: string } @@ -275,8 +274,8 @@ function symlinksUnder(modules: string): string[] { } /** - * Active profile `node_modules` entries linked to package directories outside the profiles tree. - * Links whose target is missing, lies inside the profiles tree, or holds no package.json are not roots. + * Active profile `node_modules` entries linked to directories outside the profiles tree. + * Missing targets, files, and directories inside the profiles tree are not linked roots. */ function linkedProfileRoots(profile: Profile, profilesDir: string): LinkedRoot[] { const modules = join(profile.dir, 'node_modules') @@ -300,7 +299,7 @@ function linkedProfileRoots(profile: Profile, profilesDir: string): LinkedRoot[] if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error continue } - if (realPath.startsWith(tree) || !existsSync(join(realPath, 'package.json'))) continue + if (realPath + sep === tree || realPath.startsWith(tree) || !statSync(realPath).isDirectory()) continue roots.push({ name: relative(modules, linkPath).split(sep).join('/'), linkPath, realPath }) } return roots.sort((left, right) => left.name.localeCompare(right.name)) diff --git a/packages/boot/app-boot/tests/linked-resolution-matrix.spec.ts b/packages/boot/app-boot/tests/linked-resolution-matrix.spec.ts new file mode 100644 index 0000000000..624eb7ae98 --- /dev/null +++ b/packages/boot/app-boot/tests/linked-resolution-matrix.spec.ts @@ -0,0 +1,644 @@ +/** Differential regressions for Node lookup with peer mappings at each linked importer's ancestor position. */ + +import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs' +import { execFileSync } from 'node:child_process' +import { createRequire } from 'node:module' +import { tmpdir } from 'node:os' +import { dirname, join, relative, resolve, sep } from 'node:path' +import { fileURLToPath, pathToFileURL } from 'node:url' +import { afterAll, beforeAll, describe, expect, it } from 'vitest' +import { createRuntimeResolution, type Profile } from '../src/profile.ts' +import { barePackageName, installRuntimeInterception } from '../src/profile-resolution/resolver.ts' + +type Layout = 'single-flat' | 'single-pnpm' | 'pnpm-monorepo' +type Method = 'esm-resolve' | 'esm-meta-resolve' | 'esm-import' | 'cjs-resolve' | 'cjs-require' | 'cjs-paths' | 'metadata' +type Importer = 'root' | 'source' | 'nested' | 'pnpm-helper' +type Source = 'runtime' | 'local' | 'parent' | 'workspace' | 'profile' | 'private' +type ManifestState = 'absent' | 'plain' | 'peer' +type ModulesState = 'absent' | 'empty' | 'target' + +interface DirectoryState { + manifest: ManifestState + modules: ModulesState +} + +interface PeerProjection { + directory: string + peerMatches: boolean + physicalModules: boolean + physicalTarget: boolean + projected: boolean +} + +interface MatrixCase { + id: string + family: string + layout: Layout + name: string + inRuntime: boolean + declarations: number + copies: number + importer: Importer + workspaceDeclarations?: number + helperDeclarations?: number + variant?: string + rawPeers?: unknown + request?: string + explicitStart?: 'profile' + comparison?: { start: DirectoryState; parent: DirectoryState; grandparent?: DirectoryState } + legacy?: { missingSubpaths: readonly Source[] } +} + +interface Observation { + selected: string + path?: string + code?: string + message?: string + sameRuntimeInstance?: boolean + exists?: boolean +} + +interface MatrixRow { + scenario: MatrixCase + declarationText: string + copiesText: string + importerPath: string + linkedRoots: string[] + methods: Record + comparison?: { + native: Record + reference: Record + peerProjection: readonly PeerProjection[] + } +} + +interface ProbeModule { + source: string + token: object +} + +interface ResolveProbeModule { + locate(specifier: string): string +} + +interface NativeLoader { + getOrCreateModuleJob?: unknown + import(specifier: string, parent: string, attributes: ImportAttributes): Promise + resolveSync( + first: string, + second: string | { specifier: string; attributes: ImportAttributes }, + attributes?: ImportAttributes, + ): { url: string } +} + +const requireHere = createRequire(import.meta.url) +const nativeModule = requireHere('node:module') as { _initPaths(): void } +const originalNodePath = process.env.NODE_PATH +const addon = requireHere('node-addon-require-builtin') as { requireBuiltin(id: string): unknown } +const loaderModule = addon.requireBuiltin('internal/modules/esm/loader') as { + getOrInitializeCascadedLoader(): NativeLoader +} +const loader = loaderModule.getOrInitializeCascadedLoader() +const methods: readonly Method[] = ['esm-resolve', 'esm-meta-resolve', 'esm-import', 'cjs-resolve', 'cjs-require', 'cjs-paths', 'metadata'] +const layouts: readonly Layout[] = ['single-flat', 'single-pnpm', 'pnpm-monorepo'] +// These are real request spellings; each fixture supplies its own package implementations. +const names = ['@deepseek-ai/dsh-tools', 'react'] as const +const copyBits: readonly [Source, number][] = [ + ['local', 1], ['parent', 2], ['profile', 4], ['private', 8], ['workspace', 16], +] +const rows: MatrixRow[] = [] +let fixtureSequence = 0 + +// pnpm's launcher adds repository packages to NODE_PATH; fixtures must supply their own copies. +beforeAll(() => { + delete process.env.NODE_PATH + nativeModule._initPaths() +}) +afterAll(() => { + if (originalNodePath === undefined) delete process.env.NODE_PATH + else process.env.NODE_PATH = originalNodePath + nativeModule._initPaths() +}) + +function declarationFields(name: string, bits: number): Record { + return { + ...(bits & 1 ? { dependencies: { [name]: '*' } } : {}), + ...(bits & 2 ? { devDependencies: { [name]: '*' } } : {}), + ...(bits & 4 ? { peerDependencies: { [name]: '*' } } : {}), + } +} + +function declarations(bits: number): string { + return [[1, 'dependency'], [2, 'dev'], [4, 'peer']] + .filter(([bit]) => bits & Number(bit)).map(([, name]) => name).join('+') || 'none' +} + +function copies(bits: number): string { + return copyBits.filter(([, bit]) => bits & bit).map(([name]) => name).join('+') || 'none' +} + +function matrixCases(): MatrixCase[] { + const cases: MatrixCase[] = [] + for (const layout of layouts) { + for (const name of names) { + for (const inRuntime of [false, true]) { + for (let declarations = 0; declarations < 8; declarations++) { + for (let copies = 0; copies < 8; copies++) { + cases.push({ id: '', family: 'root', layout, name, inRuntime, declarations, copies, importer: 'root' }) + } + } + } + } + } + for (const layout of layouts) { + for (const name of names) { + for (const inRuntime of [false, true]) { + for (let declarations = 0; declarations < 8; declarations++) { + for (const importer of ['source', 'nested', 'pnpm-helper'] as const) { + for (const copies of [8, 9, 10, 11, 16, 17, 31]) { + cases.push({ id: '', family: 'placement', layout, name, inRuntime, declarations, copies, importer }) + } + } + } + } + } + } + for (const name of names) { + for (const inRuntime of [false, true]) { + for (let declarations = 0; declarations < 8; declarations++) { + for (let workspaceDeclarations = 0; workspaceDeclarations < 8; workspaceDeclarations++) { + for (const copies of [1, 16, 17]) { + cases.push({ id: '', family: 'workspace-declaration', layout: 'pnpm-monorepo', name, + inRuntime, declarations, workspaceDeclarations, copies, importer: 'root' }) + } + } + } + } + } + for (const layout of layouts) { + for (const name of names) { + for (const inRuntime of [false, true]) { + for (const [variant, rawPeers] of [ + ['peer-null', null], ['peer-array', [name]], ['peer-string', name], + ['peer-empty', {}], ['wrong-field', {}], ['peer-range-mismatch', { [name]: '^999.0.0' }], + ] as const) { + for (const copies of [1, 19]) { + cases.push({ id: '', family: 'malformed-declaration', layout, name, inRuntime, + declarations: 2, copies, importer: 'root', variant, rawPeers }) + } + } + for (const declarations of [2, 6]) { + for (const request of ['#target', `${name}/sub`, `${name}/private`, `${name}/missing`]) { + for (const copies of [1, 3]) { + cases.push({ id: '', family: 'request-form', layout, name, inRuntime, + declarations, copies, importer: 'root', request }) + } + } + } + for (const importer of ['nested', 'pnpm-helper'] as const) { + for (const declarations of [2, 6]) { + for (const helperDeclarations of [2, 6]) { + for (const copies of [1, 9]) { + cases.push({ id: '', family: 'helper-declaration', layout, name, inRuntime, + declarations, helperDeclarations, copies, importer }) + } + } + } + } + } + } + } + const parents: readonly DirectoryState[] = [ + { manifest: 'absent', modules: 'absent' }, + { manifest: 'absent', modules: 'target' }, + { manifest: 'plain', modules: 'target' }, + { manifest: 'peer', modules: 'absent' }, + { manifest: 'peer', modules: 'target' }, + ] + let comparisonId = 0 + for (const layout of ['single-flat', 'pnpm-monorepo'] as const) { + for (const name of names) { + for (const inRuntime of [false, true]) { + for (const startManifest of ['absent', 'plain', 'peer'] as const) { + for (const startModules of ['absent', 'empty', 'target'] as const) { + for (const parent of parents) { + cases.push({ id: `N${String(++comparisonId).padStart(4, '0')}`, family: 'node-comparison', layout, name, + inRuntime, declarations: startManifest === 'peer' ? 4 : 0, copies: 0, importer: 'root', + comparison: { start: { manifest: startManifest, modules: startModules }, parent } }) + } + } + } + for (const importer of ['root', 'source'] as const) { + for (const request of [name, `${name}/sub`, `${name}/missing`, `${name}/private`]) { + for (const startModules of ['absent', 'target'] as const) { + cases.push({ id: `N${String(++comparisonId).padStart(4, '0')}`, family: 'node-comparison-files', layout, name, + inRuntime, declarations: 0, copies: 0, importer, request, + comparison: { start: { manifest: 'absent', modules: startModules }, + parent: { manifest: 'plain', modules: 'absent' }, + grandparent: { manifest: 'peer', modules: 'target' } } }) + } + } + } + } + } + } + for (const layout of ['single-flat', 'pnpm-monorepo'] as const) { + for (const name of names) { + for (const inRuntime of [false, true]) { + for (const copies of [0, 4]) { + cases.push({ id: `N${String(++comparisonId).padStart(4, '0')}`, family: 'node-comparison-explicit', layout, + name, inRuntime, declarations: 4, copies, importer: 'root', explicitStart: 'profile', + comparison: { start: { manifest: 'peer', modules: 'target' }, + parent: { manifest: 'absent', modules: 'absent' } } }) + } + } + } + } + const legacyCases: readonly { start: ManifestState; parent: ManifestState; missingSubpaths: readonly Source[] }[] = [ + { start: 'peer', parent: 'peer', missingSubpaths: [] }, + { start: 'peer', parent: 'plain', missingSubpaths: ['runtime'] }, + { start: 'plain', parent: 'peer', missingSubpaths: ['runtime', 'local'] }, + { start: 'peer', parent: 'peer', missingSubpaths: ['runtime'] }, + { start: 'plain', parent: 'peer', missingSubpaths: ['local'] }, + { start: 'peer', parent: 'peer', missingSubpaths: ['runtime', 'workspace'] }, + ] + let legacyId = 0 + for (const layout of layouts) { + for (const name of names) { + for (const inRuntime of [false, true]) { + for (const entry of legacyCases) { + for (const request of [name, `${name}/sub.cjs`, `${name}/missing.cjs`]) { + cases.push({ id: `L${String(++legacyId).padStart(4, '0')}`, family: 'node-legacy', layout, name, + inRuntime, declarations: 0, copies: 0, importer: 'root', request, + variant: `missing-sub:${entry.missingSubpaths.join('+') || 'none'}`, legacy: entry, + comparison: { start: { manifest: entry.start, modules: 'target' }, + parent: { manifest: entry.parent, modules: 'target' }, + grandparent: { manifest: 'plain', modules: 'target' } } }) + } + } + } + } + } + return cases.map((value, index) => ({ ...value, id: value.id || `M${String(index + 1).padStart(4, '0')}` })) +} + +function put(path: string, content: string): void { + mkdirSync(dirname(path), { recursive: true }) + writeFileSync(path, content) +} + +function manifest(path: string, content: Record): void { + put(join(path, 'package.json'), JSON.stringify(content) + '\n') +} + +class MatrixFixture { + // Node keeps resolved paths and modules after cleanup; no fixture may reuse an earlier fixture's path. + readonly root = realpathSync.native(mkdtempSync(join(tmpdir(), `dsh-linked-matrix-${++fixtureSequence}-`))) + readonly home = join(this.root, 'home') + readonly profileDir = join(this.home, 'profiles', 'web') + readonly workspace = join(this.root, 'work', 'workspace') + readonly packageDir: string + readonly sources = new Map() + readonly importerDir: string + readonly installDir = join(this.root, 'installation', 'node_modules', '@deepseek-ai', 'dsh') + readonly runtimeDir: string + readonly peerProjection: PeerProjection[] = [] + + constructor(readonly scenario: MatrixCase) { + this.packageDir = scenario.layout === 'pnpm-monorepo' + ? join(this.workspace, 'packages', 'my-plugin') + : join(this.root, 'work', 'my-plugin') + const storeOwner = scenario.layout === 'pnpm-monorepo' ? this.workspace : this.packageDir + const helper = join(storeOwner, 'node_modules', '.pnpm', 'helper@1.0.0', 'node_modules', 'helper') + this.importerDir = scenario.importer === 'source' ? join(this.packageDir, 'src') + : scenario.importer === 'nested' ? join(this.packageDir, 'node_modules', 'nested-helper') + : scenario.importer === 'pnpm-helper' ? helper : this.packageDir + this.runtimeDir = join(this.installDir, 'node_modules', scenario.name) + } + + setup(): void { + const value = this.scenario + manifest(this.installDir, { + name: '@deepseek-ai/dsh', version: '1.0.0', + dependencies: value.inRuntime ? { [value.name]: '*' } : {}, + }) + if (value.inRuntime) this.package(this.runtimeDir, 'runtime') + manifest(this.profileDir, { name: 'matrix-profile', private: true, dependencies: { 'my-plugin': '*' } }) + if (value.layout === 'pnpm-monorepo') { + manifest(this.workspace, { name: 'matrix-workspace', private: true, + ...declarationFields(value.name, value.workspaceDeclarations ?? 0) }) + put(join(this.workspace, 'pnpm-workspace.yaml'), "packages:\n - 'packages/*'\n") + } + const fields = declarationFields(value.name, value.declarations) + if (Object.hasOwn(value, 'rawPeers')) fields.peerDependencies = value.rawPeers + if (value.variant === 'wrong-field') { + delete fields.peerDependencies + fields.peerDependecies = { [value.name]: '*' } + } + manifest(this.packageDir, { name: 'my-plugin', version: '1.0.0', type: 'module', + exports: { import: './index.mjs', require: './index.cjs' }, imports: { '#target': value.name }, ...fields }) + put(join(this.packageDir, 'index.mjs'), 'export const plugin = true\n') + put(join(this.packageDir, 'index.cjs'), 'exports.plugin = true\n') + if (this.importerDir !== this.packageDir) { + if (value.importer !== 'source') manifest(this.importerDir, { name: 'matrix-helper', type: 'module', + ...declarationFields(value.name, value.helperDeclarations ?? 4) }) + put(join(this.importerDir, 'probe.mjs'), 'export {}\n') + put(join(this.importerDir, 'probe.cjs'), '') + } + const profileLink = join(this.profileDir, 'node_modules', 'my-plugin') + this.link(this.packageDir, profileLink) + if (value.importer === 'pnpm-helper') this.link(this.importerDir, join(this.packageDir, 'node_modules', 'helper')) + if (value.layout !== 'single-flat') { + const storeOwner = value.layout === 'pnpm-monorepo' ? this.workspace : this.packageDir + put(join(storeOwner, 'node_modules', '.modules.yaml'), 'nodeLinker: isolated\nvirtualStoreDir: .pnpm\n') + } + if (value.copies & 1) { + const local = join(this.packageDir, 'node_modules', value.name) + if (value.layout === 'single-flat') this.package(local, 'local') + else { + const storeOwner = value.layout === 'pnpm-monorepo' ? this.workspace : this.packageDir + const target = join(storeOwner, 'node_modules', '.pnpm', `${value.name.replaceAll('/', '+')}@2.0.0`, 'node_modules', value.name) + this.package(target, 'local') + this.link(target, local) + } + } + if (value.copies & 2) this.package(join(dirname(this.packageDir), 'node_modules', value.name), 'parent') + if (value.copies & 4) this.package(join(this.profileDir, 'node_modules', value.name), 'profile') + if (value.copies & 8) { + if (value.importer === 'pnpm-helper') { + const storeOwner = value.layout === 'pnpm-monorepo' ? this.workspace : this.packageDir + const target = join(storeOwner, 'node_modules', '.pnpm', `${value.name.replaceAll('/', '+')}@6.0.0`, 'node_modules', value.name) + this.package(target, 'private') + this.link(target, join(dirname(this.importerDir), value.name)) + } else this.package(join(this.importerDir, 'node_modules', value.name), 'private') + } + if (value.copies & 16) this.package(join(this.workspace, 'node_modules', value.name), 'workspace') + if (value.comparison !== undefined) { + this.configureDirectory(this.importerDir, value.comparison.start, 'local') + this.configureDirectory(dirname(this.importerDir), value.comparison.parent, 'parent') + if (value.comparison.grandparent !== undefined) { + this.configureDirectory(dirname(dirname(this.importerDir)), value.comparison.grandparent, 'workspace') + } + } + put(join(this.importerDir, 'entry-query.mjs'), 'export function locate(specifier) { return import.meta.resolve(specifier) }\n') + } + + private configureDirectory(directory: string, state: DirectoryState, source: Source): void { + if (state.manifest === 'absent') rmSync(join(directory, 'package.json'), { force: true }) + else manifest(directory, { name: `matrix-${source}`, type: 'module', + ...(state.manifest === 'peer' ? { peerDependencies: { [this.scenario.name]: '*' } } : {}) }) + const modules = join(directory, 'node_modules') + // All configured directories are inside this fixture and are changed before any module is resolved. + if (state.modules === 'absent') rmSync(modules, { recursive: true, force: true }) + else { + mkdirSync(modules, { recursive: true }) + if (state.modules === 'target') this.package(join(modules, this.scenario.name), source) + } + } + + /** Only the reference fixture materializes peer positions; the product resolver is not replaced. */ + projectPeerPositions(): void { + // A hoisted monorepo helper outside the recorded linked directory remains native. + if (this.importerDir !== this.packageDir && !this.importerDir.startsWith(this.packageDir + sep)) return + const paths = createRequire(join(this.importerDir, 'probe.cjs')).resolve.paths(this.scenario.name) ?? [] + for (const modules of paths) { + if (!modules.startsWith(this.root + sep)) continue + const directory = dirname(modules) + const manifestPath = join(directory, 'package.json') + const info = existsSync(manifestPath) + ? JSON.parse(readFileSync(manifestPath, 'utf8')) as { peerDependencies?: Record } : {} + const peerMatches = Object.hasOwn(info.peerDependencies ?? {}, this.scenario.name) + const target = join(modules, this.scenario.name) + const projected = peerMatches && this.scenario.inRuntime + this.peerProjection.push({ directory: relative(this.root, directory).split(sep).join('/'), peerMatches, + physicalModules: existsSync(modules), physicalTarget: existsSync(target), projected }) + if (!projected) continue + const entry = lstatSync(target, { throwIfNoEntry: false }) + if (entry?.isSymbolicLink()) unlinkSync(target) + else if (entry !== undefined) rmSync(target, { recursive: true }) + this.link(this.runtimeDir, target) + } + } + + private nativePackageDir(request: string, parent: string): string | undefined { + const name = barePackageName(request) + if (name === undefined) return undefined + for (const modules of createRequire(parent).resolve.paths(name) ?? []) { + const directory = join(modules, name) + if (existsSync(join(directory, 'package.json'))) return directory + } + return undefined + } + + private package(dir: string, source: Source): void { + manifest(dir, { name: this.scenario.name, version: '2.0.0', type: 'module', + ...this.scenario.legacy === undefined ? { exports: { '.': { import: './index.mjs', require: './index.cjs' }, + './sub': { import: './sub.mjs', require: './sub.cjs' }, + './missing': { import: './missing.mjs', require: './missing.cjs' } } } : { main: './index.cjs' } }) + for (const stem of ['index', 'sub']) { + if (stem === 'sub' && this.scenario.legacy?.missingSubpaths.includes(source)) continue + put(join(dir, `${stem}.mjs`), `export const source = ${JSON.stringify(source)}\nexport const token = {}\n`) + put(join(dir, `${stem}.cjs`), `exports.source = ${JSON.stringify(source)}\nexports.token = {}\n`) + } + this.sources.set(realpathSync.native(dir), source) + } + + private link(target: string, path: string): void { + mkdirSync(dirname(path), { recursive: true }) + symlinkSync(target, path, process.platform === 'win32' ? 'junction' : 'dir') + // import.meta.resolve retains the logical symlink spelling for missing exported files. + const source = this.sources.get(realpathSync.native(target)) + if (source !== undefined) this.sources.set(path, source) + } + + private classify(path: string): Observation { + const exists = existsSync(path) + const canonical = exists ? realpathSync.native(path) : resolve(path) + for (const [directory, selected] of this.sources) { + if (canonical === directory || canonical.startsWith(directory + sep)) { + return { selected, exists, path: relative(this.root, canonical).split(sep).join('/') } + } + } + return { selected: 'external', exists, path: canonical } + } + + private failed(error: unknown): Observation { + const code = error instanceof Error && 'code' in error && typeof error.code === 'string' + ? error.code : error instanceof Error ? error.name : 'UNKNOWN' + const message = error instanceof Error ? error.message : String(error) + return { selected: 'error', code, message: message.replaceAll(this.root, '') } + } + + async observe(mode: 'current' | 'native' = 'current'): Promise { + const profile: Profile = { name: 'web', dir: this.profileDir, layers: [], + patchPath: join(this.profileDir, 'cordis.patch.yml'), patches: [] } + const resolution = mode === 'current' + ? await createRuntimeResolution({ installAnchor: join(this.installDir, 'package.json'), profile, home: this.home }) : undefined + expect(realpathSync.native(join(this.profileDir, 'node_modules', 'my-plugin'))).toBe(this.packageDir) + const registration = resolution === undefined ? undefined : installRuntimeInterception(resolution) + try { + const request = this.scenario.request ?? this.scenario.name + const parent = pathToFileURL(join(this.importerDir, 'probe.mjs')).href + const require = createRequire(join(this.importerDir, 'probe.cjs')) + const query = await loader.import(pathToFileURL(join(this.importerDir, 'entry-query.mjs')).href, parent, {}) + const esmResolve = (): string => 'getOrCreateModuleJob' in loader + ? loader.resolveSync(parent, { specifier: request, attributes: {} }).url + : loader.resolveSync(request, parent, {}).url + const runtimeEntry = (extension: 'mjs' | 'cjs'): string => join(this.runtimeDir, + `${request.endsWith('/sub') || request.endsWith('/sub.cjs') ? 'sub' : 'index'}.${this.scenario.legacy === undefined ? extension : 'cjs'}`) + const observe = async (method: Method): Promise => { + try { + if (method === 'metadata') { + const path = registration === undefined ? this.nativePackageDir(request, parent) : registration.packageDir(request, parent) + return path === undefined ? { selected: 'missing' } : this.classify(path) + } + const path = method === 'esm-meta-resolve' ? fileURLToPath(query.locate(request)) + : method.startsWith('esm') ? fileURLToPath(esmResolve()) + : method === 'cjs-paths' ? require.resolve(request, { + paths: [this.scenario.explicitStart === 'profile' ? this.profileDir : this.importerDir], + }) : require.resolve(request) + const result = this.classify(path) + // A real host package is not fixture evidence and must never be evaluated by this probe. + if (result.selected === 'external') return result + if (method === 'esm-import') { + const loaded = await loader.import(request, parent, {}) + result.selected = loaded.source + if (this.scenario.inRuntime) { + const entry = runtimeEntry('mjs') + result.sameRuntimeInstance = existsSync(entry) + && loaded.token === (await loader.import(pathToFileURL(entry).href, parent, {})).token + } + } else if (method === 'cjs-require') { + const loaded = require(request) as ProbeModule + result.selected = loaded.source + if (this.scenario.inRuntime) { + const entry = runtimeEntry('cjs') + result.sameRuntimeInstance = existsSync(entry) && loaded.token === (require(entry) as ProbeModule).token + } + } + return result + } catch (error) { return this.failed(error) } + } + const answers = {} as Record + for (const method of methods) answers[method] = await observe(method) + return { scenario: this.scenario, declarationText: declarations(this.scenario.declarations), + copiesText: copies(this.scenario.copies), importerPath: relative(this.root, this.importerDir).split(sep).join('/'), + linkedRoots: resolution?.linkedRoots.map(root => relative(this.root, root.realPath).split(sep).join('/')) ?? [], + methods: answers } + } finally { registration?.dispose() } + } + + dispose(): void { rmSync(this.root, { recursive: true, force: true }) } +} + +function outcome(value: Observation): string { + return value.code ?? `${value.selected}${value.exists === false ? ':path-absent' : ''}` +} + +function comparable(value: Observation): object { + return { outcome: outcome(value), sameRuntimeInstance: value.sameRuntimeInstance, + ...(value.exists ? { path: value.path } : {}) } +} + +function writeNodeComparison(output: string, selected: readonly MatrixRow[]): void { + const records = selected.flatMap((row) => { + const comparison = row.comparison + const directories = row.scenario.comparison + if (comparison === undefined) return [] + return methods.map(method => ({ + id: row.scenario.id, layout: row.scenario.layout, name: row.scenario.name, + inRuntime: row.scenario.inRuntime, request: row.scenario.request ?? row.scenario.name, + importer: row.scenario.importer, startManifest: directories?.start.manifest ?? row.declarationText, + explicitStart: row.scenario.explicitStart ?? 'importer', + startModules: directories?.start.modules ?? row.copiesText, parentManifest: directories?.parent.manifest ?? 'layout', + parentModules: directories?.parent.modules ?? 'layout', grandparentManifest: directories?.grandparent?.manifest ?? 'layout', + grandparentModules: directories?.grandparent?.modules ?? 'layout', method, + native: outcome(comparison.native[method]), current: outcome(row.methods[method]), + peerReference: outcome(comparison.reference[method]), + currentMatchesReference: JSON.stringify(comparable(row.methods[method])) === JSON.stringify(comparable(comparison.reference[method])), + })) + }) + if (records.length === 0) return + const columns = ['id', 'layout', 'name', 'inRuntime', 'request', 'importer', 'explicitStart', 'startManifest', 'startModules', + 'parentManifest', 'parentModules', 'grandparentManifest', 'grandparentModules', 'method', + 'native', 'current', 'peerReference', 'currentMatchesReference'] as const + const csv = [columns.join(','), ...records.map(record => columns.map(column => JSON.stringify(String(record[column]))).join(','))] + writeFileSync(join(output, 'node-comparison.csv'), csv.join('\n') + '\n', { flag: 'wx' }) + const markdown = [ + '# Node baseline and peer-position reference', '', + 'Native, current, and reference runs use independent fixture paths. Only the reference fixture materializes peer mappings before Node resolves them. Explicit paths and importers outside recorded linked directories use the unmodified native behavior. Assertions compare selected packages, existing file paths, failure codes, and runtime module identity.', '', + '| ID | Layout | Package | Runtime | Request | Importer | Explicit paths start | JSON here | node_modules here | Parent JSON | Parent node_modules | Method | Native Node | Current DSH | Peer reference | Matches reference |', + '|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|', + ...records.map(record => `| ${[record.id, record.layout, record.name, record.inRuntime, record.request, record.importer, + record.explicitStart, record.startManifest, record.startModules, record.parentManifest, record.parentModules, + record.method, record.native, record.current, record.peerReference, record.currentMatchesReference].join(' | ')} |`), '', + ] + writeFileSync(join(output, 'node-comparison.md'), markdown.join('\n'), { flag: 'wx' }) +} + +afterAll(() => { + const parent = process.env.DSH_RESOLUTION_MATRIX_REPORT_DIR + if (parent === undefined) return + mkdirSync(parent, { recursive: true }) + const output = mkdtempSync(join(resolve(parent), 'run-')) + const sorted = [...rows].sort((left, right) => left.scenario.id.localeCompare(right.scenario.id)) + const csv = [ + ['id', 'family', 'layout', 'package', 'inRuntime', 'declarations', 'workspaceDeclarations', 'helperDeclarations', + 'variant', 'request', 'copies', 'importer', ...methods], + ...sorted.map(row => [row.scenario.id, row.scenario.family, row.scenario.layout, row.scenario.name, + row.scenario.inRuntime, row.declarationText, declarations(row.scenario.workspaceDeclarations ?? 0), + declarations(row.scenario.helperDeclarations ?? 4), row.scenario.variant ?? '', row.scenario.request ?? row.scenario.name, + row.copiesText, row.importerPath, + ...methods.map(method => outcome(row.methods[method]))]), + ].map(line => line.map(value => JSON.stringify(String(value))).join(',')).join('\n') + '\n' + const sourceHead = execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim() + writeFileSync(join(output, 'matrix.json'), JSON.stringify({ node: process.versions.node, platform: process.platform, + sourceHead, plannedCases: matrixCases().length, observedCases: sorted.length, rule: 'native-node-with-peer-positions', + rows: sorted }, null, 2) + '\n', { flag: 'wx' }) + writeFileSync(join(output, 'matrix.csv'), csv, { flag: 'wx' }) + writeNodeComparison(output, sorted) + const markdown = [ + '# Linked resolution regression matrix', '', + 'Every row is checked against native Node with only the matching peer positions replaced by the runtime package. The node-comparison report includes both baselines and the per-operation verdict.', '', + '| ID | Family | Layout | Package | Runtime entry | Declaration | Workspace declaration | Helper declaration | Variant | Request | Copies | Importer | ESM resolve | import.meta.resolve | ESM import | CJS resolve | CJS require | CJS paths | Metadata |', + '|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|', + ...sorted.map(row => `| ${[row.scenario.id, row.scenario.family, row.scenario.layout, row.scenario.name, row.scenario.inRuntime, + row.declarationText, declarations(row.scenario.workspaceDeclarations ?? 0), declarations(row.scenario.helperDeclarations ?? 4), + row.scenario.variant ?? '', row.scenario.request ?? row.scenario.name, row.copiesText, row.scenario.importer, + ...methods.map(method => outcome(row.methods[method]))].join(' | ')} |`), + '', + ].join('\n') + writeFileSync(join(output, 'matrix.md'), markdown, { flag: 'wx' }) + console.info(`Resolution matrix: ${sorted.length} observations at ${output}`) +}) + +describe('linked resolution differential matrix', { concurrent: false }, () => { + it.each(matrixCases())('$id $family $layout $name runtime=$inRuntime declarations=$declarations copies=$copies importer=$importer', async (scenario) => { + const fixtures: MatrixFixture[] = [] + try { + const baseline = new MatrixFixture(scenario) + fixtures.push(baseline) + baseline.setup() + const native = await baseline.observe('native') + const fixture = new MatrixFixture(scenario) + fixtures.push(fixture) + fixture.setup() + const row = await fixture.observe() + const reference = new MatrixFixture(scenario) + fixtures.push(reference) + reference.setup() + reference.projectPeerPositions() + const projected = await reference.observe('native') + // Explicit paths are exempt from the policy and use the pristine native filesystem. + projected.methods['cjs-paths'] = native.methods['cjs-paths'] + row.comparison = { native: native.methods, reference: projected.methods, peerProjection: reference.peerProjection } + rows.push(row) + if (reference.peerProjection.every(layer => !layer.projected)) expect(projected.methods).toEqual(native.methods) + for (const method of methods) { + for (const observed of [native, row, projected]) expect(observed.methods[method].selected).not.toBe('external') + expect(comparable(row.methods[method]), `${scenario.id}: ${method}`).toEqual(comparable(projected.methods[method])) + } + expect(Object.keys(row.methods)).toEqual(methods) + } finally { for (const fixture of fixtures.reverse()) fixture.dispose() } + }) +}) diff --git a/packages/boot/app-boot/tests/profile-resolution.spec.ts b/packages/boot/app-boot/tests/profile-resolution.spec.ts index 01cce9660c..86634ebc5a 100644 --- a/packages/boot/app-boot/tests/profile-resolution.spec.ts +++ b/packages/boot/app-boot/tests/profile-resolution.spec.ts @@ -407,7 +407,8 @@ describe('runtime resolution', { concurrent: false }, () => { registrations.push(registration) const require = createRequire(join(profileDir, 'entry.cjs')) expect(require('@deepseek-ai/dsh-core')).toEqual({ marker: 1 }) - expect(require.resolve('@deepseek-ai/dsh-core', { paths: [profileDir] })).toBe(join(f.installed, 'index.cjs')) + expect(require.resolve('@deepseek-ai/dsh-core', { paths: [profileDir] })) + .toBe(join(f.root, 'node_modules', '@deepseek-ai/dsh-core', 'index.cjs')) const parent = pathToFileURL(join(profileDir, 'entry.mjs')).href expect(resolveFrom('@deepseek-ai/dsh-core', parent)).toBe(pathToFileURL(join(f.installed, 'index.js')).href) expect(await importFrom('@deepseek-ai/dsh-core', parent)).toMatchObject({ marker: 1 }) @@ -425,9 +426,11 @@ describe('runtime resolution', { concurrent: false }, () => { const require = createRequire(join(f.profile.dir, 'entry.cjs')) expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(f.installed, 'index.cjs')) expect(require.resolve('@deepseek-ai/dsh-core', { paths: [alternative] })).toBe(join(alternativePackage, 'index.cjs')) - expect(require.resolve('@deepseek-ai/dsh-core', { paths: [f.profile.dir] })).toBe(join(f.installed, 'index.cjs')) - expect(require.resolve('@deepseek-ai/dsh-core', { paths: [join(f.root, 'missing'), f.profile.dir] })) - .toBe(join(f.installed, 'index.cjs')) + expect(thrownError(() => require.resolve('@deepseek-ai/dsh-core', { paths: [f.profile.dir] }))) + .toMatchObject({ code: 'MODULE_NOT_FOUND' }) + expect(thrownError(() => require.resolve('@deepseek-ai/dsh-core', { + paths: [join(f.root, 'missing'), f.profile.dir], + }))).toMatchObject({ code: 'MODULE_NOT_FOUND' }) const relative = join(f.profile.dir, 'relative.cjs') file(relative, '') expect(require.resolve('./relative.cjs', { paths: [f.profile.dir] })).toBe(relative) @@ -435,9 +438,10 @@ describe('runtime resolution', { concurrent: false }, () => { file(join(invalid, 'node_modules', '@deepseek-ai/dsh-core', 'package.json'), '{') expect(() => { require.resolve('@deepseek-ai/dsh-core', { paths: [invalid, f.profile.dir] }) }) .toThrow(/Invalid package config/u) + expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(f.installed, 'index.cjs')) }) - it('keeps earlier explicit CommonJS paths ahead of a managed local failure', async () => { + it('keeps earlier explicit CommonJS paths ahead of a profile-local failure', async () => { const f = fixture() const resolution = await createRuntimeResolution({ installAnchor: f.installAnchor, @@ -460,7 +464,7 @@ describe('runtime resolution', { concurrent: false }, () => { expect(require.resolve('@deepseek-ai/dsh-core', { paths })).toBe(selected) }) - it('keeps a missing legacy main before a managed explicit CommonJS path', async () => { + it('preserves a missing legacy main error before an explicit profile path', async () => { const f = fixture() const invalid = join(f.root, 'invalid') const selected = join(invalid, 'node_modules', '@deepseek-ai/dsh-core') @@ -480,7 +484,7 @@ describe('runtime resolution', { concurrent: false }, () => { expect(runtimeError.message).toBe(nativeError.message) }) - it('keeps a missing fallback legacy main before later explicit CommonJS paths', async () => { + it('preserves a missing ancestor legacy main error before later explicit CommonJS paths', async () => { const f = fixture() const name = 'fallback-invalid-main' const selected = join(f.root, 'node_modules', name) @@ -502,7 +506,7 @@ describe('runtime resolution', { concurrent: false }, () => { expect(runtimeError.message).toBe(nativeError.message) }) - it('keeps a missing fallback legacy main after a resolution miss', async () => { + it('preserves a missing legacy main error for explicit paths when a runtime entry is unavailable', async () => { const f = fixture() const selected = join(f.root, 'node_modules', '@deepseek-ai/dsh-core') file(join(selected, 'package.json'), JSON.stringify({ name: '@deepseek-ai/dsh-core', main: './missing.cjs' })) @@ -945,7 +949,7 @@ describe('runtime resolution', { concurrent: false }, () => { )).toThrow(/Cannot find/u) }) - it('limits bundle-only entries to the active profile', async () => { + it('limits bundle-only interception to ordinary lookup in the active profile', async () => { const f = fixture() const bundleDir = join(f.root, 'bundle') pkg(bundleDir, 'test-bundle', 0, { 'bundle-only': '*' }) @@ -962,10 +966,9 @@ describe('runtime resolution', { concurrent: false }, () => { expect(createRequire(join(f.profile.dir, 'entry.cjs'))('bundle-only')).toEqual({ marker: 4 }) const other = join(f.root, 'profiles', 'other', 'entry.cjs') expect(() => { createRequire(other)('bundle-only') }).toThrow(/Cannot find module/u) - const resolvedBundleOnly = createRequire(other).resolve('bundle-only', { + expect(thrownError(() => createRequire(other).resolve('bundle-only', { paths: [dirname(other), f.profile.dir], - }) - expect(realpathSync.native(resolvedBundleOnly)).toBe(realpathSync.native(join(bundleOnly, 'index.cjs'))) + }))).toMatchObject({ code: 'MODULE_NOT_FOUND' }) expect(() => createRequire(other).resolve('bundle-only', { paths: [dirname(other)] })) .toThrow(/Cannot find module/u) expect(() => createRequire(other).resolve('missing-explicit', { paths: [dirname(other)] })) @@ -1024,7 +1027,7 @@ describe('runtime resolution', { concurrent: false }, () => { expect(require.resolve('@deepseek-ai/dsh-core/sub.cjs')).toBe(ancestorSubpath) }) - it('continues explicit CommonJS paths after a resolution subpath miss', async () => { + it('uses later explicit CommonJS paths when the profile has no matching package', async () => { const f = fixture() file(join(f.installed, 'package.json'), JSON.stringify({ name: '@deepseek-ai/dsh-core', version: '1.0.0', type: 'module', main: './index.cjs', @@ -1045,7 +1048,7 @@ describe('runtime resolution', { concurrent: false }, () => { file(join(f.installed, 'package.json'), JSON.stringify({ name: '@deepseek-ai/dsh-core', version: '1.0.0', main: './index.cjs', })) - // The resolution entry stands in for profiles/node_modules/@deepseek-ai/dsh-core, so this stale copy is never read. + // Ordinary profile lookup replaces the shared copy with the runtime entry; explicit paths still read the shared copy. const shared = join(f.root, 'profiles', 'node_modules', '@deepseek-ai/dsh-core') file(join(shared, 'package.json'), JSON.stringify({ name: '@deepseek-ai/dsh-core', version: '9.0.0' })) file(join(shared, 'sub.cjs'), 'module.exports = { marker: 9 }\n') @@ -1062,7 +1065,7 @@ describe('runtime resolution', { concurrent: false }, () => { expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(f.installed, 'index.cjs')) expect(require.resolve('@deepseek-ai/dsh-core/sub.cjs')).toBe(join(home, 'sub.cjs')) expect(require('@deepseek-ai/dsh-core/sub.cjs')).toEqual({ marker: 3 }) - expect(require.resolve('@deepseek-ai/dsh-core/sub.cjs', { paths: [f.profile.dir] })).toBe(join(home, 'sub.cjs')) + expect(require.resolve('@deepseek-ai/dsh-core/sub.cjs', { paths: [f.profile.dir] })).toBe(join(shared, 'sub.cjs')) expect(require('left-pad')).toEqual({ marker: 9 }) // ESM resolves the subpath inside the selected package and never consults another copy. const parent = pathToFileURL(join(f.profile.dir, 'entry.mjs')).href @@ -1293,10 +1296,18 @@ describe('runtime resolution', { concurrent: false }, () => { const importerDir = importer === 'plugin' ? pluginDir : f.profile.dir const require = createRequire(join(importerDir, 'entry.cjs')) const parent = pathToFileURL(join(importerDir, 'entry.mjs')).href + const explicitWinner = LOOKUP_LAYERS.find(layer => ( + layers.includes(layer) && (layer !== 'private' || importer === 'plugin') + )) + if (explicitWinner === undefined) { + expect(thrownError(() => require.resolve(name, { paths: [importerDir] }))) + .toMatchObject({ code: 'MODULE_NOT_FOUND' }) + } else { + expect(require.resolve(name, { paths: [importerDir] })).toBe(join(real[explicitWinner], 'index.cjs')) + } const winner = lookupWinner(matrixCase) if (winner === 'missing') { expect(thrownError(() => require(name))).toMatchObject({ code: 'MODULE_NOT_FOUND' }) - expect(thrownError(() => require.resolve(name, { paths: [importerDir] }))).toMatchObject({ code: 'MODULE_NOT_FOUND' }) await expect(importFrom(name, parent)).rejects.toMatchObject({ code: 'ERR_MODULE_NOT_FOUND' }) expect(registration.packageDir(name, parent)).toBeUndefined() return @@ -1308,7 +1319,6 @@ describe('runtime resolution', { concurrent: false }, () => { const marker = winner === 'interception' ? (kind === 'installation' ? 1 : 2) : LOOKUP_MARKERS[winner] expect(require(name)).toEqual({ marker }) expect(require.resolve(name)).toBe(join(realDir, 'index.cjs')) - expect(require.resolve(name, { paths: [importerDir] })).toBe(join(realDir, 'index.cjs')) expect(resolveFrom(name, parent)).toBe(pathToFileURL(join(realDir, 'index.js')).href) expect(await importFrom(name, parent)).toMatchObject({ marker }) expect(registration.packageDir(name, parent)).toBe(packageDir) @@ -1670,7 +1680,7 @@ describe('runtime resolution', { concurrent: false }, () => { expect(getEnvironmentData(key)).toBe(previous) }) - it('records active profile packages linked outside the profiles tree as linked roots', async () => { + it('records active profile links to external directories with or without manifests', async () => { const f = fixture() const modules = join(f.profile.dir, 'node_modules') const outside = join(f.root, 'work', 'my-plugin') @@ -1688,6 +1698,7 @@ describe('runtime resolution', { concurrent: false }, () => { symlinkSync(outside, join(modules, 'my-plugin'), linkType) symlinkSync(scopedOutside, join(modules, '@scope', 'linked'), linkType) symlinkSync(inside, join(modules, 'inside-lib'), linkType) + symlinkSync(join(f.root, 'profiles'), join(modules, 'profiles-root'), linkType) symlinkSync(bare, join(modules, 'bare-dir'), linkType) symlinkSync(dangling, join(modules, 'dangling'), linkType) rmSync(dangling, { recursive: true }) @@ -1695,6 +1706,7 @@ describe('runtime resolution', { concurrent: false }, () => { const resolution = await resolutionOf(f) expect(resolution.linkedRoots).toEqual([ { name: '@scope/linked', linkPath: join(modules, '@scope', 'linked'), realPath: scopedOutside }, + { name: 'bare-dir', linkPath: join(modules, 'bare-dir'), realPath: bare }, { name: 'my-plugin', linkPath: join(modules, 'my-plugin'), realPath: outside }, ]) expect(Object.isFrozen(resolution.linkedRoots)).toBe(true) @@ -1709,6 +1721,19 @@ describe('runtime resolution', { concurrent: false }, () => { expect(unmaterialized.linkedRoots).toEqual([]) }) + it('excludes profile symlinks to files from linked roots', async () => { + const f = fixture() + const modules = join(f.profile.dir, 'node_modules') + const target = join(f.root, 'work', 'file.cjs') + file(target, 'module.exports = { marker: 5 }\n') + mkdirSync(join(modules, '@scope'), { recursive: true }) + symlinkSync(target, join(modules, 'file-link'), 'file') + symlinkSync(target, join(modules, '@scope', 'file-link'), 'file') + + const resolution = await resolutionOf(f) + expect(resolution.linkedRoots).toEqual([]) + }) + /** A plugin repository linked into the profile, with the manifest a plugin developer keeps for type checking. */ function linkedPluginFixture(peerDependencies: Record | undefined = { '@deepseek-ai/dsh-core': '*' }): { f: ReturnType @@ -1814,6 +1839,33 @@ describe('runtime resolution', { concurrent: false }, () => { expect(require('@deepseek-ai/dsh-core/sub.cjs')).toEqual({ marker: 3 }) }) + it('preserves the native require stack for a missing linked legacy subpath', async () => { + const { f, linkedRoot } = linkedPluginFixture() + const name = '@deepseek-ai/dsh-core' + file(join(f.installed, 'package.json'), JSON.stringify({ + name, version: '1.0.0', type: 'module', main: './index.cjs', + })) + rmSync(join(linkedRoot, 'node_modules', name), { recursive: true }) + const importer = join(linkedRoot, 'entry.cjs') + const require = createRequire(importer) + const request = `${name}/missing.cjs` + const nativeError = thrownError(() => require.resolve(request)) + expect(nativeError.code).toBe('MODULE_NOT_FOUND') + expect(nativeError.requireStack).toEqual([importer]) + + const registration = installRuntimeInterception(await resolutionOf(f)) + registrations.push(registration) + try { + const runtimeError = thrownError(() => require.resolve(request)) + expect(runtimeError.code).toBe(nativeError.code) + expect(runtimeError.requireStack).toEqual(nativeError.requireStack) + expect(runtimeError.message).toBe(nativeError.message) + } finally { + registration.dispose() + registrations.pop() + } + }) + it('reads a linked plugin manifest at every resolution', async () => { const { f, linkedRoot, writeManifest } = linkedPluginFixture({}) const registration = installRuntimeInterception(await resolutionOf(f)) @@ -1844,6 +1896,37 @@ describe('runtime resolution', { concurrent: false }, () => { expect(require.resolve('@deepseek-ai/dsh-core')).toBe(join(devCopy, 'index.cjs')) }) + it('reads ancestor peer declarations at every linked resolution', async () => { + const { f, linkedRoot } = linkedPluginFixture({}) + const name = '@deepseek-ai/dsh-core' + rmSync(join(linkedRoot, 'node_modules', name), { recursive: true }) + const ancestor = dirname(linkedRoot) + const ancestorCopy = join(ancestor, 'node_modules', name) + pkg(ancestorCopy, name, 31) + const manifestPath = join(ancestor, 'package.json') + const manifest = { name: 'plugin-workspace', private: true } + file(manifestPath, JSON.stringify(manifest)) + const require = createRequire(join(linkedRoot, 'entry.cjs')) + const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href + const registration = installRuntimeInterception(await resolutionOf(f)) + registrations.push(registration) + try { + for (const [peerDependencies, expectedDir] of [ + [undefined, ancestorCopy], + [{ [name]: '*' }, f.installed], + [undefined, ancestorCopy], + ] as const) { + file(manifestPath, JSON.stringify({ ...manifest, peerDependencies })) + expect(require.resolve(name)).toBe(join(expectedDir, 'index.cjs')) + expect(resolveFrom(name, parent)).toBe(pathToFileURL(join(expectedDir, 'index.js')).href) + expect(registration.packageDir(name, parent)).toBe(expectedDir) + } + } finally { + registration.dispose() + registrations.pop() + } + }) + it('restores CommonJS resolution when the registration is disposed', async () => { const f = fixture() const registration = installRuntimeInterception(await resolutionOf(f)) From cf41c158bae2e1d0d2e2e84a2c6e6ce486495033 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Mon, 21 Sep 2026 12:42:49 +0800 Subject: [PATCH 098/100] fix(boot): keep host lookups native and fix source smoke fixtures --- ...9-profile-resolution-generations.i18n.yaml | 4 +- ...26-09-09-profile-resolution-generations.md | 4 +- ...09-09-profile-resolution-generations.zh.md | 4 +- ...-profile-resolution-lookup-order.i18n.yaml | 4 +- ...6-09-19-profile-resolution-lookup-order.md | 7 +- ...9-19-profile-resolution-lookup-order.zh.md | 7 +- .../headless/tests/profile-resolution.ts | 39 ++- docs/user/develop/basic/publish.i18n.yaml | 4 +- docs/user/develop/basic/publish.md | 2 + docs/user/develop/basic/publish.zh.md | 2 + packages/boot/app-boot/README.i18n.yaml | 4 +- packages/boot/app-boot/README.md | 5 +- packages/boot/app-boot/README.zh.md | 5 +- .../src/profile-resolution/resolver.ts | 22 +- packages/boot/app-boot/src/profile.ts | 24 +- .../app-boot/tests/profile-resolution.spec.ts | 278 +++++++++++++++++- 16 files changed, 354 insertions(+), 61 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml index 087f067fb9..0f95b21360 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.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 .agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md -2026-09-09-profile-resolution-generations.md: e524150b4928e0ed239cd10efd668e3400718ecc -2026-09-09-profile-resolution-generations.zh.md: 1a6104586f0d4c7d5911128557485a1bc277f426 +2026-09-09-profile-resolution-generations.md: 39ce2415ca51b31641d643a9635ad57205385975 +2026-09-09-profile-resolution-generations.zh.md: ea15cb2792a49c2c99951f2faf619d68b6b5b98a diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md index e524150b49..39ce2415ca 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md +++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md @@ -62,6 +62,8 @@ The [source launcher](2026-07-29-dsh-source-launch-tsx-esm.md) uses tsx's ESM-on For example, `@deepseek-ai/dsh-tools` creates its scheduler key with `Symbol()`. A Tools instance loaded from `lib/` cannot expose that scheduler through a key imported from the separate `src/` module instance. Source launches keep Tools and AgentLoop in `src/`; plain Node launches keep them in `lib/`. The scheduler retains its local Symbol; correct imports share one module instance. +The source launcher does not install a CommonJS TypeScript hook. `createRequire().resolve()` still selects the package's published JavaScript entry and requires that file to exist. Source-mode resolution tests therefore use fixture-provided CommonJS files; checks of real installation CommonJS entries run with build outputs present. + ### Immutable generations A runtime interception holds one `current` generation. Each synchronous resolution captures that reference once. Generation construction reads every required dependency-graph manifest before publication; an error leaves the current generation unchanged. Successful publication replaces one reference, and in-flight calls may finish against the generation they captured. @@ -104,7 +106,7 @@ Replacing, upgrading, or removing an already loaded package requires process res ### Filesystem and runtime carriers -The resolver does not create, update, or remove fallback symlinks and proxy packages. Runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`; every other name sees that directory as an ordinary ancestor. Construction also records profile links to real directories outside the profiles tree, including directories without their own manifest. Linked importers retain native ancestor order and apply peer mappings at the matching manifest's position, even without a physical `node_modules` there. Profile-local package metadata and bundle dependency discovery follow the same Node lookup. The [lookup-order Note](2026-09-19-profile-resolution-lookup-order.md) records precedence and scope. Writable profile state and package-manager transactions remain outside the resolver. +The resolver does not create, update, or remove fallback symlinks and proxy packages. Runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`; every other name sees that directory as an ordinary ancestor. Construction records links to directories outside the shared profiles tree and the active profile itself, including targets without their own manifest. Installation-scope package directories stay outside linked interception even when a broader linked root contains them. Eligible linked importers retain native ancestor order and per-position peer mappings. The [lookup-order Note](2026-09-19-profile-resolution-lookup-order.md) records precedence and scope. Writable profile state and package-manager transactions remain outside the resolver. Runtime resolution requires a supported Node Internal loader interface. The Electron Host runs through the Electron executable with `ELECTRON_RUN_AS_NODE=1`; packaged builds read the dsh tree from ASAR and map executable ASAR entries to electron-builder's unpacked tree. Pkg and Electron use the same runtime resolution mechanism as ordinary Node launches. diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md index 1a6104586f..ea15cb2792 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md @@ -62,6 +62,8 @@ ESM `import` 和 CommonJS `require` 都选中这些版本。在每种模块格 例如,`@deepseek-ai/dsh-tools` 使用 `Symbol()` 创建 scheduler 键。从 `lib/` 加载的 Tools 实例,无法通过另一个 `src/` 模块实例导入的键暴露该 scheduler。源码启动让 Tools 与 AgentLoop 都位于 `src/`;普通 Node 启动让两者都位于 `lib/`。scheduler 保留模块本地的 Symbol;正确的 import 共享同一个模块实例。 +源码启动器不安装 CommonJS TypeScript 钩子。`createRequire().resolve()` 仍选择包发布的 JavaScript 入口,并要求该文件存在。因此,源码模式的解析测试使用 fixture 提供的 CommonJS 文件,真实安装包的 CommonJS 入口检查则在构建产物存在时运行。 + ### 不可变 generation 一个 runtime interception 持有一个 `current` generation。每个同步 resolve 在入口只捕获一次该引用,完整调用只读该引用。generation 构造在发布前读取依赖图所需的全部 manifest;失败时当前 generation 不变。发布成功只替换一个引用,执行中的调用可以继续使用它已捕获的 generation。 @@ -104,7 +106,7 @@ runtime resolution 列出它提供的包;Loader entries 组成活动插件列 ### 文件系统与运行时载体 -解析器不创建、更新或删除 fallback 软链接与代理包。runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置;其余包名把该目录当作普通祖先。构造时还会记录指向 profiles 树外真实目录的 profile 链接,包括没有自身 manifest 的目录。linked importer 保留原生祖先顺序,在匹配 manifest 对应的位置应用 peer 映射,即使那里没有物理 `node_modules`。profile 本地包元数据与 bundle 依赖展开遵循同一套 Node 查找。优先级和范围见[查找顺序 Note](2026-09-19-profile-resolution-lookup-order.zh.md)。可写 profile 状态和包管理器事务不属于解析器。 +解析器不创建、更新或删除 fallback 软链接与代理包。runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置;其余包名把该目录当作普通祖先。构造时记录目标同时位于共享 profiles 树和当前 profile 自身之外的目录链接,包括没有自身 manifest 的目标。installation 作用域包目录不参与 linked 拦截,即使更宽的 linked root 包含它们。符合条件的 linked importer 保留原生祖先顺序与逐位置的 peer 映射。优先级和范围见[查找顺序 Note](2026-09-19-profile-resolution-lookup-order.zh.md)。可写 profile 状态和包管理器事务不属于解析器。 运行时解析要求受支持的 Node Internal loader 接口。Electron Host 通过设置 `ELECTRON_RUN_AS_NODE=1` 的 Electron 可执行文件运行;打包构建从 ASAR 读取 dsh 依赖树,并把 ASAR 中的可执行条目映射到 electron-builder 的 unpacked 目录。pkg 与 Electron 使用和普通 Node 启动相同的 runtime resolution 机制。 diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml index 9adcca0495..8965c2b9db 100644 --- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.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 .agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md -2026-09-19-profile-resolution-lookup-order.md: cb4c677e30a8d0f104a3cacf6c97407a8ea70576 -2026-09-19-profile-resolution-lookup-order.zh.md: cf33a9b5b1d56e23c8060418d8c5c8dc076574e0 +2026-09-19-profile-resolution-lookup-order.md: 0830aac1ef00aadf56aee8179c59324230e132d5 +2026-09-19-profile-resolution-lookup-order.zh.md: 9817f2001e484208edd3755bc0f80d5a3029b4c7 diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md index cb4c677e30..0830aac1ef 100644 --- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md +++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md @@ -50,6 +50,8 @@ The interception layer reads, writes, and deletes no disk links. Leftover histor When `/node_modules/` links to a real directory R outside the profiles tree, R is a linked root. R need not contain `package.json` or `node_modules`: it may be a package directory, a monorepo package, or a `src` directory. Importers below R follow Node's real ancestor chain. The recorded root decides which importers participate; it does not stop their lookup at R. +Linked interception excludes importers inside installation-scope package directories, using both their configured and real paths. A broad checkout link therefore does not take over the host's own dependency lookup. Overlapping linked roots describe one participation scope: the importer determines the ancestor chain, so neither root order nor link names choose a different peer set. + At each candidate `D/node_modules`, a matching current `D/package.json` peer declaration uses the runtime package if the table supplies that name. This occupies only that package's position, including when `D/node_modules` does not physically exist. Without both a declaration and a runtime entry, Node tries the physical candidate. A missing manifest does not stop lookup. `dependencies` and `devDependencies` do not enable interception, and a peer version range is not an additional resolver filter. The same rule applies to third-party peers such as React when the runtime table supplies them. A nearer physical candidate wins before any later ancestor peer declaration. If a selected package's `exports` rejects the request, Node's error is final. A legacy CommonJS subpath miss can continue to the next position, where that directory's peer rule applies again; the physical copy at an occupied position is not retried. Each new linked resolution reads the manifests at the positions it visits, without memoizing its selected route. An unreadable manifest supplies no peers; Node retains its native manifest diagnostics. This does not clear Node's caches or automatically reload already loaded modules. @@ -63,7 +65,7 @@ The runtime resolution is computed once at profile startup and consists of four - Installation closure: starting from the `package.json` of the currently running dsh package, a breadth-first traversal follows `dependencies` and `peerDependencies`; each edge resolves from the manifest that declares it per Node rules, and the first installed package found owns a package name. The closure holds several hundred entries, roughly half in the `@deepseek-ai/` scope and half third-party libraries. These entries apply to every profile. - Bundle-only entries: for a bundle selected by the profile that is not part of the closure, the same traversal starts from its manifest, and package names the closure already owns are not overridden. These entries apply only to profiles that select that bundle; they let the Loader import the bundle's embedded plugins by bare name from the profile root. - Local package names: package names among the profile's direct dependencies that are already installed in `$DSH_HOME/profiles//node_modules`. They already sit at ② on the ancestor chain; recording them only saves one directory probe. -- Linked roots: top-level and `@scope/*` links in `$DSH_HOME/profiles//node_modules` whose targets are directories outside the profiles tree; each records its real directory and link position. Their own manifests are optional. Missing targets, files, and directories inside the profiles tree are excluded. +- Linked roots: top-level and `@scope/*` links in `$DSH_HOME/profiles//node_modules` whose targets are directories outside both the shared profiles tree and the active profile directory; each records its link name and real directory. Their own manifests are optional. Missing targets and files are excluded. An application-owned profile outside the shared tree does not register its internal pnpm store links as external roots. The CLI derives the installation anchor from `import.meta.url`, which Node has already resolved to its real path; the Desktop Host builds it from its runtime directory, which is not a symlink. Both leave the installation root equal to its real directory, so bundle discovery and dependency traversal use the same location. During the traversal, every dependency level uses the real directory of its owning package as the lookup anchor for the next level and records the location of the manifest that declares it. After a hit, Node resolves from that declaring location and gets the same result the package's own internal imports get. Every entry records the package name, package directory, version, declaring location, and scope. Declared but uninstalled dependencies are skipped; the bundle package root itself does not become an entry. @@ -118,6 +120,7 @@ The profile links `/node_modules/my-plugin` to the plugin's real direct | Transitive dependency inside R → any package name | Participates | Each position uses its own manifest's peers; nearer physical candidates precede later peer declarations | | Link target R has no manifest → peer declared by an ancestor | Participates | Search starts at R; an earlier physical candidate wins, otherwise the ancestor peer can select the runtime package even without physical `node_modules` there | | Hoisted dependency whose real directory is outside every linked root → any package name | Does not participate | Native Node lookup from that dependency's real directory | +| Installation-scope package inside a broad linked directory → any package name | Does not participate in linked interception | Native lookup retains the host package's own dependencies | | Any importer → `require.resolve(pkg, { paths })` | Does not participate | Native Node lookup using the supplied paths | ### Part 3: Developer integration guide @@ -166,7 +169,7 @@ Two other layouts remain available: install `@deepseek-ai/dsh` in the plugin rep - Linked-root cases in the same file link a profile package to an external repository with a same-named devDependency copy in its `node_modules`. Package names cover an installation entry declared as a peer, one declared as a dependency, the repository's own third-party dependency, and an undeclared name; importers cover the repository's own files and transitive dependencies inside it. The cases assert agreement across the four resolution forms, that the devDependency copy is not read, and that the next resolution observes a rewritten `peerDependencies` declaration. - The [differential matrix](../../../../packages/boot/app-boot/tests/linked-resolution-matrix.spec.ts) constructs independent native, intercepted, and reference directories. Only the reference copy replaces eligible peer positions with links to the runtime package; Node resolves the resulting files. Single-package and pnpm monorepo cases compare entry, file, directory, import/require, `import.meta.resolve`, and explicit-path outcomes, including absent manifests, absent `node_modules`, malformed peer declarations, React, outside-scope helpers, and legacy subpath continuation. Assertions compare package selection, existing paths, error codes, and module identity; explicit paths use the pristine native reference. - Dedicated cases in the same file cover each row of Table 1: bare names and subpaths with and without `exports`, `#alias`, explicit `paths`, package self-reference, CommonJS skipping ③ and going straight to ④ when a subpath is missing after a runtime resolution hit, and the interception position of an out-of-tree profile. -- The [real CLI launch test](../../../../apps/cli/tests/profiles/headless/tests/profile-resolution.ts) covers src and lib launches with ordinary and npm-link layouts, plus a link to a manifest-free `src` directory whose parent declares a peer. It checks shared Tools/AgentLoop instances, native explicit-path selection of the developer's copy, real-path dependency resolution, and unchanged files and link targets. +- The [real CLI launch test](../../../../apps/cli/tests/profiles/headless/tests/profile-resolution.ts) covers src and lib launches with ordinary and npm-link layouts, plus a link to a manifest-free `src` directory whose parent declares a peer. It checks shared Tools/AgentLoop instances, native explicit-path selection of the developer's copy, real-path dependency resolution, and unchanged files and link targets. Source-mode CommonJS checks use fixture packages with existing JavaScript entries; real installation CommonJS entries require their build outputs. ## Consequences diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md index cf33a9b5b1..9817f2001e 100644 --- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md @@ -50,6 +50,8 @@ Node 仍然负责 `exports`、`imports`、conditions、`main`、子路径、扩 `/node_modules/<包名>` 链接到 profiles 树外的真实目录 R 时,R 是一个 linked root。R 不必包含 `package.json` 或 `node_modules`,可以是包目录、monorepo 中的单个包,也可以是 `src` 目录。R 之下的 importer 沿 Node 的真实祖先链查询。记录的根目录决定哪些 importer 参与拦截,不会把它们的查找限制在 R 内。 +linked 拦截排除 installation 作用域包目录内的 importer,同时识别配置路径和真实路径。因此,链接整个 checkout 不会接管宿主自身的依赖查询。重叠的 linked root 共同描述参与范围:祖先链由 importer 决定,root 顺序和链接名称都不会选择另一套 peer 集合。 + 在每个候选 `D/node_modules`,当前 `D/package.json` 的 peer 声明命中且运行时表提供该包名时,就使用运行时包。这只占据该包的位置,即使 `D/node_modules` 在磁盘上不存在也成立。声明和运行时条目缺少任一项,Node 就尝试物理候选。缺少 manifest 不会终止查找。`dependencies` 与 `devDependencies` 不启用拦截,peer 的版本范围也不是额外的解析筛选条件。运行时表提供 React 等第三方 peer 时,同样适用这条规则。 更近的物理候选先于后续祖先的 peer 声明。选中包的 `exports` 拒绝请求时,Node 的错误是终局。旧式 CommonJS 子路径缺失可以继续到下一位置,再应用那个目录的 peer 规则;不会重试已被占据位置上的物理副本。每次新的 linked 解析读取所访问位置的 manifest,不缓存选中的路由。不可读的 manifest 不提供 peer,Node 保留其原生 manifest 诊断。这不清除 Node 缓存,也不自动重新加载已加载的模块。 @@ -63,7 +65,7 @@ runtime resolution 在 profile 启动时一次算出,由四部分组成。 - installation 闭包:从当前运行的 dsh 包的 `package.json` 出发,沿 `dependencies` 与 `peerDependencies` 做广度优先遍历,每条边从声明它的 manifest 按 Node 规则解析,同一个包名由第一次找到的已安装包占有。闭包有数百条,约一半在 `@deepseek-ai/` 作用域,一半是第三方库。这些条目对所有 profile 生效。 - bundle-only 条目:profile 选中的、不属于闭包的 bundle,从它的 manifest 出发做同样的遍历,闭包已占有的包名不覆盖。这些条目只对选中该 bundle 的 profile 生效,用于让 Loader 从 profile 根按裸名导入 bundle 内嵌的插件。 - 本地包名:profile 直接依赖中已经安装在 `$DSH_HOME/profiles//node_modules` 的包名。它们本来就在主线 ② 上,记录下来只为免去一次目录探测。 -- linked root:`$DSH_HOME/profiles//node_modules` 顶层与 `@scope/*` 里目标为 profiles 树外目录的链接,记录真实目录与 link 位置。目录自身的 manifest 可缺省。目标缺失、为文件或位于 profiles 树内的链接都排除。 +- linked root:`$DSH_HOME/profiles//node_modules` 顶层与 `@scope/*` 里目标同时位于共享 profiles 树和当前 profile 目录之外的目录链接,记录链接名称与真实目录。目录自身的 manifest 可缺省。目标缺失或为文件的链接都排除。位于共享树外的应用自有 profile,不会把内部 pnpm store 链接登记为外部 root。 CLI 的安装锚点来自 `import.meta.url`,Node 已对它做过 realpath;Desktop Host 从其运行时目录拼出锚点,该目录不是软链接。两者的安装根目录都等于真实目录,bundle 发现与依赖遍历使用同一个位置。遍历中每一层依赖都以所属包的真实目录作为下一层的查找锚点,并记录声明它的 manifest 位置。命中后 Node 从这个声明位置解析,得到与该包自己内部 import 相同的结果。每个条目记录包名、包目录、版本、声明位置与作用域。已声明但未安装的依赖跳过;bundle 包根自身不成为条目。 @@ -118,6 +120,7 @@ ESM 与 CommonJS 两个适配器调用同一个路由函数,主线程与 Harne | R 内传递依赖 → 任何包名 | 参与 | 每个位置使用自己的 manifest 的 peer;更近的物理候选先于后续 peer 声明 | | link 目标 R 无 manifest → 祖先声明的 peer | 参与 | 从 R 开始查;更近的物理候选优先,否则祖先 peer 可以选中运行时包,即使那里没有物理 `node_modules` | | 真实目录在所有 linked root 外的提升依赖 → 任何包名 | 不参与 | 从该依赖真实目录进行原生 Node 查询 | +| 位于宽链接目录内的 installation 作用域包 → 任何包名 | 不参与 linked 拦截 | 原生查询保留宿主包自身的依赖 | | 任意 importer → `require.resolve(pkg, { paths })` | 不参与 | 使用指定路径进行原生 Node 查询 | ### 三、开发者接入指引 @@ -166,7 +169,7 @@ manifest 的写法与 harness 自身的包相同:需要与宿主共享实例 - 同一文件内的 linked root 用例:`/node_modules` 的软链接指向树外仓库,仓库 `node_modules` 里放同名 devDependency 副本;包名取声明为 peer 的 installation 条目、声明为 dependency 的 installation 条目、仓库自己的第三方 dependency、未声明的包名,importer 取仓库自身文件与仓库内传递依赖;断言四种解析方式一致、devDependency 副本不被读到,以及改写 `peerDependencies` 后下一次解析立即按新声明进行。 - [差分矩阵](../../../../packages/boot/app-boot/tests/linked-resolution-matrix.spec.ts)构造独立的原生、拦截与参考目录。只有参考副本把合格 peer 位置替换为运行时包的链接,再让 Node 解析文件。单包与 pnpm monorepo 用例对比入口、文件、目录、import/require、`import.meta.resolve` 与显式路径的结果,覆盖 manifest 缺失、`node_modules` 缺失、错误 peer 声明、React、作用域外 helper 和旧式子路径继续查询。断言比较选包、现存路径、错误码与模块实例;显式 paths 使用未投射的原生参考。 - 同一文件内的专项用例覆盖表 1 各行:有无 `exports` 的裸包名与子路径、`#alias`、显式 `paths`、包自引用、命中 runtime resolution 后 CommonJS 子路径缺失时跳过 ③ 直接到 ④,以及树外 profile 的拦截位置。 -- [CLI 真启动测试](../../../../apps/cli/tests/profiles/headless/tests/profile-resolution.ts)覆盖 src 与 lib 启动、普通与 npm-link 布局,以及指向无 manifest 的 `src` 目录且其父目录声明 peer 的链接。测试检查 Tools/AgentLoop 共享实例、原生显式路径选中开发者副本、依赖沿真实路径解析,以及文件和链接目标保持不变。 +- [CLI 真启动测试](../../../../apps/cli/tests/profiles/headless/tests/profile-resolution.ts)覆盖 src 与 lib 启动、普通与 npm-link 布局,以及指向无 manifest 的 `src` 目录且其父目录声明 peer 的链接。测试检查 Tools/AgentLoop 共享实例、原生显式路径选中开发者副本、依赖沿真实路径解析,以及文件和链接目标保持不变。源码模式的 CommonJS 检查使用具备现存 JavaScript 入口的 fixture 包;安装中真实的 CommonJS 入口需要相应构建产物。 ## Consequences diff --git a/apps/cli/tests/profiles/headless/tests/profile-resolution.ts b/apps/cli/tests/profiles/headless/tests/profile-resolution.ts index 90fb6bc7f2..9978557402 100644 --- a/apps/cli/tests/profiles/headless/tests/profile-resolution.ts +++ b/apps/cli/tests/profiles/headless/tests/profile-resolution.ts @@ -36,9 +36,10 @@ interface ResolutionEvidence { toolsInstance: boolean pluginToolsInstance: boolean sourceToolsInstance: boolean - profileToolsCjs: string - sourceToolsCjs: string - sourceToolsExplicitCjs: string + profileToolsCjs: string | null + sourceToolsCjs: string | null + sourceLeafCjs: string + sourceLeafExplicitCjs: string scheduler: boolean modules: string[] } @@ -70,6 +71,8 @@ export function testProfileResolution(mode: ExampleMode): void { const bridgeDir = layout === 'npm-link' ? join(root, 'dependencies', bridgeName) : installedBridge const logicalLeaf = join(bundleDir, 'node_modules', leafName) const realLeaf = join(root, 'dependencies', 'node_modules', leafName) + const sourcePackageDir = join(root, 'work', 'source-package') + const sourceDevLeaf = join(sourcePackageDir, 'node_modules', leafName) const exports = { import: './index.mjs', require: './index.cjs' } await writePackage(bundleDir, { name: bundleName, version: '1.0.0', dependencies: { [bridgeName]: '*' }, @@ -81,7 +84,9 @@ export function testProfileResolution(mode: ExampleMode): void { 'index.mjs': `export { leaf } from '${leafName}'`, 'index.cjs': `module.exports = require('${leafName}')`, }) - for (const [dir, version] of [[logicalLeaf, '1.0.0'], [realLeaf, '2.0.0']] as const) { + for (const [dir, version] of [ + [logicalLeaf, '1.0.0'], [realLeaf, '2.0.0'], [sourceDevLeaf, '0.0.0'], + ] as const) { await writePackage(dir, { name: leafName, version, exports }, { 'index.mjs': `export const leaf = { version: '${version}', url: import.meta.url }`, 'index.cjs': `exports.leaf = { version: '${version}', filename: __filename }`, @@ -137,19 +142,21 @@ export function testProfileResolution(mode: ExampleMode): void { 'index.mjs': "export default class Tools {}\nexport const TOOL_RUNTIME_SCHEDULER = Symbol()\nthrow new Error('STALE_DSH_TOOLS')", 'index.cjs': "throw new Error('STALE_DSH_TOOLS')", }) - const sourcePackageDir = join(root, 'work', 'source-package') const sourceDir = join(sourcePackageDir, 'src') + const toolsCjsExpression = mode === 'lib' ? "require.resolve('@deepseek-ai/dsh-tools')" : 'null' await mkdir(sourceDir, { recursive: true }) + // The ESM-only source hook does not map CommonJS exports to source, so its CJS probe uses a fixture-owned peer. await writePackage(sourcePackageDir, { - name: 'source-package', version: '1.0.0', peerDependencies: { '@deepseek-ai/dsh-tools': '*' }, + name: 'source-package', version: '1.0.0', peerDependencies: { '@deepseek-ai/dsh-tools': '*', [leafName]: '*' }, }, { 'src/query.mjs': [ "import { createRequire } from 'node:module'", "import Tools from '@deepseek-ai/dsh-tools'", 'export { Tools as SourceTools }', 'const require = createRequire(import.meta.url)', - "export const sourceToolsCjs = require.resolve('@deepseek-ai/dsh-tools')", - `export const sourceToolsExplicitCjs = require.resolve('@deepseek-ai/dsh-tools', { paths: [${JSON.stringify(sourceDir)}] })`, + `export const sourceToolsCjs = ${toolsCjsExpression}`, + `export const sourceLeafCjs = require.resolve('${leafName}')`, + `export const sourceLeafExplicitCjs = require.resolve('${leafName}', { paths: [${JSON.stringify(sourceDir)}] })`, ].join('\n'), }) for (const [target, link] of [ @@ -181,7 +188,7 @@ export function testProfileResolution(mode: ExampleMode): void { `import { leaf as bridgeLeaf } from '${bridgeName}'`, `import { external } from '${externalName}'`, `import { external as pluginExternal, PluginTools } from '${pluginName}'`, - `import { SourceTools, sourceToolsCjs, sourceToolsExplicitCjs } from '${sourceProbeName}/query.mjs'`, + `import { SourceTools, sourceToolsCjs, sourceLeafCjs, sourceLeafExplicitCjs } from '${sourceProbeName}/query.mjs'`, `import { leaf as externalLeaf } from ${JSON.stringify(pathToFileURL(join(externalLeaf, 'index.mjs')).href)}`, 'const require = createRequire(import.meta.url)', "export const inject = ['tools', 'agentLoop', 'loader']", @@ -205,8 +212,8 @@ export function testProfileResolution(mode: ExampleMode): void { ' toolsInstance: ctx.tools instanceof Tools,', ' pluginToolsInstance: ctx.tools instanceof PluginTools,', ' sourceToolsInstance: ctx.tools instanceof SourceTools,', - " profileToolsCjs: require.resolve('@deepseek-ai/dsh-tools'),", - ' sourceToolsCjs, sourceToolsExplicitCjs,', + ` profileToolsCjs: ${toolsCjsExpression},`, + ' sourceToolsCjs, sourceLeafCjs, sourceLeafExplicitCjs,', " scheduler: typeof ctx.tools[TOOL_RUNTIME_SCHEDULER]?.prepare === 'function',", ' modules: [...ctx.loader.internal.loadCache.keys()]', ' .filter(url => /\\/packages\\/core\\/(?:tools|agent-loop)\\//.test(url)),', @@ -227,7 +234,7 @@ export function testProfileResolution(mode: ExampleMode): void { ]), }) const packageDirs = [ - bundleDir, bridgeDir, logicalLeaf, realLeaf, pluginDir, externalDir, externalLeaf, + bundleDir, bridgeDir, logicalLeaf, realLeaf, sourceDevLeaf, pluginDir, externalDir, externalLeaf, sharedLeaf, ancestorExternal, ancestorLeaf, staleTools, sourcePackageDir, sourceDir, profileDir, ] const packageFiles = (await Promise.all(packageDirs.map(async dir => @@ -278,8 +285,12 @@ export function testProfileResolution(mode: ExampleMode): void { expect(evidence.pluginToolsInstance).toBe(true) expect(evidence.sourceToolsInstance).toBe(true) expect(evidence.sourceToolsCjs).toBe(evidence.profileToolsCjs) - expect(evidence.sourceToolsExplicitCjs).toBe(realpathSync.native(join(staleTools, 'index.cjs'))) - expect(evidence.sourceToolsCjs).not.toBe(evidence.sourceToolsExplicitCjs) + expect(evidence.profileToolsCjs).toBe(mode === 'lib' + ? realpathSync.native(join(repoRoot, 'packages/core/tools/lib/index.js')) + : null) + expect(evidence.sourceLeafCjs).toBe(evidence.cjs.filename) + expect(evidence.sourceLeafExplicitCjs).toBe(realpathSync.native(join(sourceDevLeaf, 'index.cjs'))) + expect(evidence.sourceLeafCjs).not.toBe(evidence.sourceLeafExplicitCjs) expect(evidence.scheduler).toBe(true) expect(evidence.execArgv).toEqual(mode === 'src' ? launch.args.slice(0, 2) : []) for (const name of ['tools', 'agent-loop']) { diff --git a/docs/user/develop/basic/publish.i18n.yaml b/docs/user/develop/basic/publish.i18n.yaml index 4641bc607c..88df3856da 100644 --- a/docs/user/develop/basic/publish.i18n.yaml +++ b/docs/user/develop/basic/publish.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 docs/user/develop/basic/publish.md -publish.md: bdc6f21ec6d3a4777cf3e0c14771c19a08ed4b5e -publish.zh.md: 43fcea22873733784f46d97bcd16bfdb297dc3ed +publish.md: b317943954972e63d0e4b741fb16d2fc19091f58 +publish.zh.md: b7864f7e7596681f48fc87590772841294d2a039 diff --git a/docs/user/develop/basic/publish.md b/docs/user/develop/basic/publish.md index bdc6f21ec6..b317943954 100644 --- a/docs/user/develop/basic/publish.md +++ b/docs/user/develop/basic/publish.md @@ -104,6 +104,8 @@ A linked checkout keeps its own `node_modules`. Declare dsh packages whose insta Ordinary linked imports follow Node's ancestor order and check each directory's current peer declarations. A nearer physical package wins before a higher peer declaration. A link target can lack `package.json`; ancestor peers still apply, even without a physical `node_modules` beside that manifest. Explicit `require.resolve(..., { paths })` is always native, including paths inside a profile. These rules are shared by npm, Desktop, and source launches; they do not invalidate loaded modules or validate peer version ranges. See the [resolution rules](../../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md) for scope and file-query behavior. +Linking a broad checkout does not apply peer interception to the running installation's own package directories. Links whose targets stay inside the profile, including its pnpm store, remain profile-owned installation content rather than external linked roots. Overlapping external links do not change lookup order: each request still starts from its importer's directory. + Verify the layer without booting, then boot: ```sh diff --git a/docs/user/develop/basic/publish.zh.md b/docs/user/develop/basic/publish.zh.md index 43fcea2287..b7864f7e75 100644 --- a/docs/user/develop/basic/publish.zh.md +++ b/docs/user/develop/basic/publish.zh.md @@ -104,6 +104,8 @@ dsh plugin --profile demo add ./hello-plugin 普通 linked import 遵循 Node 的祖先顺序,检查每个目录当前的 peer 声明。更近的物理包先于更高的 peer 声明。link 目标可以没有 `package.json`,祖先 peer 仍可生效,即使该 manifest 旁没有物理 `node_modules`。显式 `require.resolve(..., { paths })` 始终是原生查询,包括指向 profile 内的路径。npm、Desktop 与源码启动共用这些规则;规则不会使已加载模块失效,也不校验 peer 版本范围。作用域和文件查询行为见[解析规则](../../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md)。 +链接整个 checkout 不会对运行中安装自身的包目录应用 peer 拦截。目标仍位于 profile 内的链接(包括它的 pnpm store)属于 profile 自己安装的内容,不算外部 linked root。外部链接互相重叠也不改变查找顺序,每个请求仍从其 importer 所在目录开始。 + 先不启动、只验证该层,再启动: ```sh diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml index 67d3b0d201..0896d50887 100644 --- a/packages/boot/app-boot/README.i18n.yaml +++ b/packages/boot/app-boot/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md -README.md: a3c85a76c919cbedf548a35008660a0346a8e8f7 -README.zh.md: b53d8eeff682ffa6040a2a4c10a79f0b9cedb827 +README.md: e2bea1658eaff832eecef815f8d86215efbdf88b +README.zh.md: 927d88e4ca147cb7be0e2a6f839c6c94da96aef5 diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md index a3c85a76c9..e2bea1658e 100644 --- a/packages/boot/app-boot/README.md +++ b/packages/boot/app-boot/README.md @@ -115,12 +115,12 @@ This section explains how the outcomes above are realized and points at the code - **Profile launch data.** `ctx.profileContext` contains only profile locations, startup bundle names, parsed invocation overlays and the telemetry opt-out value. `readProfilePatches()` composes the supplied startup profile or reads current files at those locations; callers schedule and apply the result. - **Process-local module resolution.** The launcher installs the runtime resolution on Node's internal ESM and CommonJS resolvers before profile rows mount. Node still owns exports, conditions, subpaths, module caches, and error codes; routed ESM failures report the original importer. Explicit CommonJS `paths` always retain native lookup, including paths inside profiles. -- **Linked directories.** A profile link to an external directory admits its importers to peer-aware ancestor lookup, even without its own `package.json`. At each `D/node_modules` position, current `D/package.json` peer names present in the runtime table use the runtime package; other names use the physical candidate. A nearer physical package precedes a later peer declaration, and a peer position needs no physical `node_modules` ([rule](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md)). +- **Linked directories.** A profile link to an external directory admits its importers to peer-aware ancestor lookup, even without its own `package.json`. At each `D/node_modules` position, current `D/package.json` peer names present in the runtime table use the runtime package; other names use the physical candidate. A nearer physical package precedes a later peer declaration, and a peer position needs no physical `node_modules`. Installation-scope package directories are excluded from linked interception; overlapping roots do not change the importer's lookup order ([rule](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md)). - **Package metadata.** `ctx.pluginPackages.packageOf` locates the owning package without loading code or requiring an exported `package.json`; a subpath selects its package without validating that file. The installed runtime resolution owns selection even for a miss. Low-level embedders that install the service without one retain native lookup. Display metadata uses the separate entry-aware reader described above. - **Two Loader builtins.** `mountRootInclude` registers `cordis:include` and `cordis:group` as Loader builtins: a group row gives one `isolate` realm to a provider and its consumers together, and an agent preset outside this workspace cannot resolve `@deepseek-ai/cordis-plugin-group` by name. Both load through the ambient module pipeline rather than the included tree's own specifier resolution. - **Consumer-owned strictness.** Ordinary Loader groups keep successful siblings. App-boot applies the global required-entry policy after initial settlement; agent presets and dynamic multi-entry compositions own and dispose their separate Loader subtree when they require all-or-nothing setup. App-boot reads failed fibers to report their recorded errors and coalesces duplicate Loader rejection notifications through one process checkpoint. - **One runtime resolution.** The installation-first and ordered-bundle breadth-first traversal produces the runtime table. Runtime resolution creates no links; runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`, and every other name sees that directory as an ordinary ancestor. Profile load removes the `.dsh-module-fallback` projections that link-backend releases wrote into a profile; pnpm-installed packages stay. External bare targets selected by package `imports` use the same package order, while Node retains mapping, conditions, and exact target resolution. A complete successor may add package names and update linked-root membership atomically within the existing package-mapping and local-name constraints; changing or removing an existing mapping, or pointing an existing linked root at another directory, requires restart. -- **Application-owned profiles.** Application-owned profiles use the same runtime resolution. Resolution does not modify their `node_modules`; pnpm owns installed packages. +- **Application-owned profiles.** Application-owned profiles use the same runtime resolution. Links within the active profile directory, including pnpm store links, are not external roots even when the profile is outside the shared profiles tree. Resolution does not modify their `node_modules`; pnpm owns installed packages. - **Owned Workers.** Worker build banners import `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap` before bundled business code. Each Worker installs the structured-cloned runtime resolution in its own isolate. The bootstrap bundle has no static package imports. Source Worker entries retain their self-contained dependency closure, and third-party Workers receive no injection. - **Update completion.** App boot observes restart failures through the `internal/update` waterfall. Live patch reloads wait for the tree's fibers before auditing activation; `Fiber.update()` and `Entry.update()` alone do not establish restart success. - **One rejection checkpoint.** `inactiveEntries` keeps the exact reasons it folds into the boot diagnostic visible through the next process rejection checkpoint, so `installFailLoud` coalesces Loader's duplicate notification while unrelated unhandled rejections remain fatal. @@ -182,6 +182,7 @@ These limits describe when this boot library is a poor fit or needs special care - **Runtime resolution depends on Node internals** — supported Node versions require the native builtin-access addon and executable compatibility coverage. Only built Harness-owned Workers receive the runtime resolution bootstrap; third-party Workers and custom `vm` linkers keep native resolution. - **Relinking a profile package needs a restart** — Node caches real paths, so changing the target of a profile link or a dependency link requires a process restart. - **Linked scope follows recorded real directories** — a hoisted dependency outside every linked root uses native Node. Current peer reads do not invalidate Node caches, watch files, or validate peer version ranges. +- **Source launches use an ESM-only hook** — CommonJS requests still need the JavaScript files selected by package exports; resolution does not supply missing build outputs. - **Snapshot replay swapping is basename-specific** — only a config ending in `cordis.yml` or `cordis.yaml` maps to the sibling `cordis.snapshot.yml`; custom config names require caller-managed selection. - **Environment discovery is launch-scoped** — `loadLayeredEnv` reads only the invocation directory and Harness home once; it does not search parents or follow a workspace selected later. `loadEnv` remains the one-directory helper for non-product bins. - **A user patch replaces the whole matched config** — an id-targeted patch does not deep-merge, so a profile override restates the bundle fields it keeps. diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md index b53d8eeff6..927d88e4ca 100644 --- a/packages/boot/app-boot/README.zh.md +++ b/packages/boot/app-boot/README.zh.md @@ -115,12 +115,12 @@ Loader 结算后,app-boot 在仅 optional 条目未激活时输出警告。如 - **Profile 启动数据。** `ctx.profileContext` 只包含 profile 位置、启动时组合包名称、已解析的调用级 overlay 与遥测退出值。`readProfilePatches()` 组合传入的启动 profile,或读取这些位置上的当前文件;调用方负责调度和应用结果。 - **进程内模块解析。** launcher 在挂载 profile 条目前,将 runtime resolution 安装到 Node 的 ESM 与 CommonJS 内部 resolver。exports、conditions、子路径、模块缓存和错误码仍由 Node 负责;路由后的 ESM 失败报告原始 importer。显式 CommonJS `paths` 始终保留原生查询,包括指向 profile 内的路径。 -- **链接目录。** profile 链接到树外目录时,其下的 importer 参与逐层 peer 查询,即使目标没有自身的 `package.json`。在每个 `D/node_modules` 位置,当前 `D/package.json` 的 peer 包名若存在于运行时表,就使用运行时包;其他包名查询物理候选。更近的物理包先于后续 peer 声明,peer 位置无需物理 `node_modules`([规则](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md))。 +- **链接目录。** profile 链接到树外目录时,其下的 importer 参与逐层 peer 查询,即使目标没有自身的 `package.json`。在每个 `D/node_modules` 位置,当前 `D/package.json` 的 peer 包名若存在于运行时表,就使用运行时包;其他包名查询物理候选。更近的物理包先于后续 peer 声明,peer 位置无需物理 `node_modules`。installation 作用域包目录不参与 linked 拦截,重叠 root 不改变 importer 的查询顺序([规则](../../../.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md))。 - **包元数据。** `ctx.pluginPackages.packageOf` 定位所属包,不加载代码,也不要求导出 `package.json`;子路径选择其所属包,不校验该文件。安装 runtime resolution 后,即使查询未命中也以其选包规则为准。仅安装服务而不提供 runtime resolution 的底层嵌入方保留原生查询。展示元数据使用上文另述的入口感知读取器。 - **两个 Loader builtin。** `mountRootInclude` 把 `cordis:include` 与 `cordis:group` 注册为 Loader builtin:group 行能把一个提供方与它的消费方放进同一个 `isolate` realm,而位于本工作区之外的 agent preset 无法按名称解析 `@deepseek-ai/cordis-plugin-group`。两者都通过宿主的模块管线加载,而非被包含树自身的说明符解析。 - **由 consumer 持有严格语义。** 普通 Loader group 保留成功 sibling。App-boot 在首次结算后应用全局 required-entry policy;agent preset 与动态多 entry 组合在需要 all-or-nothing setup 时,持有并拆卸各自的独立 Loader 子树。App-boot 读取 failed fiber 来报告已记录的错误,并在一个进程检查点内合并 Loader 重复的 rejection 通知。 - **唯一 runtime resolution。** 安装优先、有序 bundle 逐根 breadth-first 遍历生成运行时表。runtime 解析不创建链接;runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置,其余包名把该目录当作普通祖先。profile 加载时删除 Link 后端发布版写进 profile 的 `.dsh-module-fallback` 投影;pnpm 安装的包保留。package `imports` 选中的外部 bare target 使用相同的选包顺序,映射、conditions 和精确 target 解析仍由 Node 负责。完整后继 runtime resolution 可以在既有包映射和本地包名约束内原子增加 package name、更新 linked root 集合;修改或删除既有映射,或把既有 linked root 指向另一个目录,则要求重启。 -- **应用自有 profile。** 应用自有 profile 使用相同的 runtime resolution。解析过程不修改其 `node_modules`;已安装包由 pnpm 管理。 +- **应用自有 profile。** 应用自有 profile 使用相同的 runtime resolution。目标位于当前 profile 目录内的链接(包括 pnpm store 链接)不算外部 root,即使 profile 位于共享 profiles 树外。解析过程不修改其 `node_modules`;已安装包由 pnpm 管理。 - **自有 Worker。** Worker 构建 banner 会在业务 bundle 前导入 `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap`。每个 Worker 在自己的 isolate 中安装结构化克隆的 runtime resolution。bootstrap bundle 不静态导入任何包。源码 Worker 入口保留自包含依赖,第三方 Worker 不接受注入。 - **更新完成。** App boot 通过 `internal/update` waterfall 观察重启失败。实时 patch 重载在检查激活状态前等待配置树中的 fiber;单独调用 `Fiber.update()` 或 `Entry.update()` 不能确定重启成功。 - **单一 rejection 检查点。** `inactiveEntries` 把折入启动诊断的确切原因保持到下一个进程级 rejection 检查点可见,使 `installFailLoud` 能合并 Loader 的重复通知,而所有无关的未处理 rejection 仍然致命。 @@ -182,6 +182,7 @@ Loader 结算后,app-boot 在仅 optional 条目未激活时输出警告。如 - **运行时解析依赖 Node 内部机制**——受支持的 Node 版本需要 native builtin access addon 和可执行兼容验证。只有构建后的 Harness 自有 Worker 接收 runtime resolution bootstrap;第三方 Worker 与自定义 `vm` linker 保持原生解析。 - **重新链接 profile 包需要重启**——Node 缓存真实路径,因此改变 profile 链接或依赖链接的目标需要重启进程。 - **链接作用域以记录的真实目录为准**——提升后的依赖若在所有 linked root 之外,就使用原生 Node。实时读取 peer 不会使 Node 缓存失效、监视文件或校验 peer 版本范围。 +- **源码启动只安装 ESM 钩子**——CommonJS 请求仍需要 package exports 选中的 JavaScript 文件,解析器不会补出缺失的构建产物。 - **快照回放替换仅识别特定 basename**——只有以 `cordis.yml` 或 `cordis.yaml` 结尾的配置会映射到同级 `cordis.snapshot.yml`;自定义配置名称需要调用方自行选择。 - **环境发现以启动为界**——`loadLayeredEnv` 只读取一次调用目录与 harness home 中的 `.env`;它不搜索父目录,也不跟随之后选择的 workspace。`loadEnv` 仍是非产品 bin 使用的单目录 helper。 - **用户 patch 会替换匹配到的整个配置**——按 id 定位的 patch 不做深度合并,因此 profile 覆盖必须重述需要保留的组合包字段。 diff --git a/packages/boot/app-boot/src/profile-resolution/resolver.ts b/packages/boot/app-boot/src/profile-resolution/resolver.ts index edbeafc597..215c82b0d0 100644 --- a/packages/boot/app-boot/src/profile-resolution/resolver.ts +++ b/packages/boot/app-boot/src/profile-resolution/resolver.ts @@ -89,12 +89,11 @@ interface LayerPositions { */ type InterceptionLayer = | LayerPositions & { readonly kind: 'profile'; readonly active: boolean } - | { readonly kind: 'linked'; readonly root: LinkedRoot } + | { readonly kind: 'linked' } interface CompiledLinkedRoot { readonly root: LinkedRoot readonly paths: readonly string[] - readonly layer: InterceptionLayer } interface ParentRoutes { @@ -112,6 +111,7 @@ interface CompiledResolution { readonly profileDir: string | undefined readonly profilePaths: readonly string[] readonly profile: readonly string[] + readonly installationPaths: readonly string[] readonly linkedRoots: readonly CompiledLinkedRoot[] readonly localPackageNames: ReadonlySet readonly esmRoutes: ResolutionRoutes @@ -175,7 +175,10 @@ function compileResolution(resolution: RuntimeResolution): CompiledResolution { profileDir: resolution.profileDir, profilePaths: prefixes(resolution.profilesDir), profile: resolution.profileDir === undefined ? [] : prefixes(resolution.profileDir), - linkedRoots: resolution.linkedRoots.map(root => ({ root, paths: prefixes(root.realPath), layer: computeLinkedLayer(root) })), + installationPaths: [...new Set(resolution.entries + .filter(entry => entry.scope === 'installation') + .flatMap(entry => prefixes(entry.packageDir)))], + linkedRoots: resolution.linkedRoots.map(root => ({ root, paths: prefixes(root.realPath) })), localPackageNames: new Set(resolution.localPackageNames), esmRoutes: new Map(), cjsRoutes: new Map(), @@ -196,22 +199,15 @@ function computeProfileLayer(dir: string, active: boolean): InterceptionLayer { } } -/** - * A linked directory admits its importers to peer-aware lookup along Node's real ancestor chain. - */ -function computeLinkedLayer(root: LinkedRoot): InterceptionLayer { - return { - kind: 'linked', root, - } -} - /** The interception layer of a module path: from its profile directory inside a profiles tree, or its linked root. */ function findInterceptionLayer(path: string, resolution: CompiledResolution): InterceptionLayer | undefined { const treeRoot = resolution.profilePaths.find(prefix => path.startsWith(prefix)) const activeProfile = resolution.profile.find(prefix => path.startsWith(prefix)) const dir = treeRoot !== undefined ? profileChild(path, treeRoot) : activeProfile?.slice(0, -1) if (dir !== undefined) return computeProfileLayer(dir, activeProfile !== undefined) - return resolution.linkedRoots.find(candidate => startsWithin(path, candidate.paths))?.layer + if (!resolution.linkedRoots.some(candidate => startsWithin(path, candidate.paths))) return undefined + if (startsWithin(path, resolution.installationPaths)) return undefined + return { kind: 'linked' } } /** Package names a directory's current manifest lists as peers; an unreadable manifest lists none. */ diff --git a/packages/boot/app-boot/src/profile.ts b/packages/boot/app-boot/src/profile.ts index ac0fb71734..c377b57438 100644 --- a/packages/boot/app-boot/src/profile.ts +++ b/packages/boot/app-boot/src/profile.ts @@ -113,15 +113,13 @@ export interface RuntimeResolutionEntry { } /** - * A profile node_modules entry linked to a directory outside the profiles tree. + * A profile node_modules entry linked to a directory outside the shared profiles tree and the active profile. * Importers below `realPath` use Node's real ancestor chain, with peer mappings read at each node_modules position. */ export interface LinkedRoot { /** Package name of the profile `node_modules` entry, including its scope. */ readonly name: string - /** The symlink or junction path under the active profile's node_modules. */ - readonly linkPath: string - /** Real directory the link resolves to; it lies outside the profiles tree and need not hold a package.json. */ + /** Real directory outside the shared profiles tree and active profile; a package.json is optional. */ readonly realPath: string } @@ -135,7 +133,7 @@ export interface RuntimeResolution { readonly localPackageNames: readonly string[] /** Installation-scope entries followed by profile-scope entries in precedence order. */ readonly entries: readonly RuntimeResolutionEntry[] - /** Active profile packages linked to directories outside the profiles tree, sorted by name. */ + /** Active profile links to external directories, sorted by name. */ readonly linkedRoots: readonly LinkedRoot[] } @@ -274,33 +272,35 @@ function symlinksUnder(modules: string): string[] { } /** - * Active profile `node_modules` entries linked to directories outside the profiles tree. - * Missing targets, files, and directories inside the profiles tree are not linked roots. + * Active profile `node_modules` entries linked outside the shared profiles tree and the active profile. + * Missing targets and files are not linked roots; invalid link chains retain Node's diagnostic. */ function linkedProfileRoots(profile: Profile, profilesDir: string): LinkedRoot[] { const modules = join(profile.dir, 'node_modules') + const links = symlinksUnder(modules) + if (links.length === 0) return [] let tree: string try { tree = realModuleDirectory(profilesDir) + sep } catch (error) { // A profiles tree that is not materialized yet holds no links. - /* v8 ignore next -- a non-ENOENT realpath failure requires a host filesystem fault */ if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error tree = resolve(profilesDir) + sep } + const excludedTrees = [tree, realModuleDirectory(profile.dir) + sep] const roots: LinkedRoot[] = [] - for (const linkPath of symlinksUnder(modules)) { + for (const linkPath of links) { let realPath: string try { realPath = realModuleDirectory(linkPath) } catch (error) { // A dangling link is not a package Node can load from the profile. - /* v8 ignore next -- a non-ENOENT realpath failure requires a host filesystem fault */ if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error continue } - if (realPath + sep === tree || realPath.startsWith(tree) || !statSync(realPath).isDirectory()) continue - roots.push({ name: relative(modules, linkPath).split(sep).join('/'), linkPath, realPath }) + if (excludedTrees.some(prefix => realPath + sep === prefix || realPath.startsWith(prefix)) + || !statSync(realPath).isDirectory()) continue + roots.push({ name: relative(modules, linkPath).split(sep).join('/'), realPath }) } return roots.sort((left, right) => left.name.localeCompare(right.name)) } diff --git a/packages/boot/app-boot/tests/profile-resolution.spec.ts b/packages/boot/app-boot/tests/profile-resolution.spec.ts index 86634ebc5a..7d0a78f2d3 100644 --- a/packages/boot/app-boot/tests/profile-resolution.spec.ts +++ b/packages/boot/app-boot/tests/profile-resolution.spec.ts @@ -1606,7 +1606,7 @@ describe('runtime resolution', { concurrent: false }, () => { registration.replace({ ...first, localPackageNames: ['new-local'] }) registration.replace({ ...first, localPackageNames: ['new-local'] }) expect(() => { registration.replace(first) }).toThrow(/removing local package/u) - const linked = { name: 'linked-plugin', linkPath: join(f.profile.dir, 'node_modules', 'linked-plugin'), realPath: join(f.root, 'work', 'a') } + const linked = { name: 'linked-plugin', realPath: join(f.root, 'work', 'a') } const withLocal = { ...first, localPackageNames: ['new-local'] } registration.replace({ ...withLocal, linkedRoots: [linked] }) registration.replace({ ...withLocal, linkedRoots: [] }) @@ -1705,9 +1705,9 @@ describe('runtime resolution', { concurrent: false }, () => { pkg(join(modules, 'installed'), 'installed', 8) const resolution = await resolutionOf(f) expect(resolution.linkedRoots).toEqual([ - { name: '@scope/linked', linkPath: join(modules, '@scope', 'linked'), realPath: scopedOutside }, - { name: 'bare-dir', linkPath: join(modules, 'bare-dir'), realPath: bare }, - { name: 'my-plugin', linkPath: join(modules, 'my-plugin'), realPath: outside }, + { name: '@scope/linked', realPath: scopedOutside }, + { name: 'bare-dir', realPath: bare }, + { name: 'my-plugin', realPath: outside }, ]) expect(Object.isFrozen(resolution.linkedRoots)).toBe(true) expect(Object.isFrozen(resolution.linkedRoots[0])).toBe(true) @@ -1721,6 +1721,68 @@ describe('runtime resolution', { concurrent: false }, () => { expect(unmaterialized.linkedRoots).toEqual([]) }) + it.each([ + { layout: 'directory', sharedTree: 'present' }, + { layout: 'symlink', sharedTree: 'present' }, + { layout: 'directory', sharedTree: 'missing' }, + { layout: 'symlink', sharedTree: 'missing' }, + ])( + 'excludes a $layout application-owned profile and its pnpm packages from linked roots ($sharedTree shared tree)', async ({ layout, sharedTree }) => { + const f = fixture() + const realProfile = join(f.root, 'application-profile') + const profileDir = layout === 'symlink' ? join(f.root, 'application-profile-alias') : realProfile + file(join(realProfile, 'package.json'), JSON.stringify({ name: 'application-profile', private: true })) + const local = join(realProfile, 'node_modules', '.pnpm', 'local@1.0.0', 'node_modules', 'local') + pkg(local, 'local', 2) + const outside = join(f.root, 'external-plugin') + pkg(outside, 'external-plugin', 3) + const shared = join(f.root, 'profiles', 'node_modules', 'shared-package') + pkg(shared, 'shared-package', 4) + const linkType = process.platform === 'win32' ? 'junction' : 'dir' + const links: string[] = [] + try { + if (layout === 'symlink') { + symlinkSync(realProfile, profileDir, linkType) + links.push(profileDir) + } + for (const [name, target] of [ + ['local', join(profileDir, 'node_modules', '.pnpm', 'local@1.0.0', 'node_modules', 'local')], + ['profile-self', profileDir], + ['profile-real', realProfile], + ['external-plugin', outside], + ['shared-package', shared], + ] as const) { + const link = join(profileDir, 'node_modules', name) + symlinkSync(target, link, linkType) + links.push(link) + } + if (sharedTree === 'missing') rmSync(join(f.root, 'profiles'), { recursive: true }) + const resolution = await createRuntimeResolution({ + installAnchor: f.installAnchor, + profile: { ...f.profile, dir: profileDir, patchPath: join(profileDir, 'cordis.patch.yml') }, + home: f.root, + }) + expect(resolution.linkedRoots).toEqual([{ name: 'external-plugin', realPath: outside }]) + } finally { + for (const link of links.reverse()) unlinkSync(link) + } + }, + ) + + it.each(['unmaterialized', 'empty'] as const)( + 'leaves an %s application-owned profile without linked roots', async (state) => { + const f = fixture() + const dir = join(f.root, 'application-profile') + if (state === 'empty') mkdirSync(join(dir, 'node_modules'), { recursive: true }) + const resolution = await createRuntimeResolution({ + installAnchor: f.installAnchor, + profile: { ...f.profile, dir, patchPath: join(dir, 'cordis.patch.yml') }, + home: f.root, + }) + expect(resolution.linkedRoots).toEqual([]) + }, + ) + it('excludes profile symlinks to files from linked roots', async () => { const f = fixture() const modules = join(f.profile.dir, 'node_modules') @@ -1734,6 +1796,38 @@ describe('runtime resolution', { concurrent: false }, () => { expect(resolution.linkedRoots).toEqual([]) }) + it.each(['linked target', 'profiles directory'] as const)( + 'reports a cyclic %s with the original Node error and path', async (location) => { + const f = fixture() + const home = location === 'profiles directory' ? join(f.root, 'cycle-home') : f.root + const modules = join(f.profile.dir, 'node_modules') + const outside = join(f.root, 'external-directory') + mkdirSync(outside, { recursive: true }) + mkdirSync(modules, { recursive: true }) + const cycle = location === 'profiles directory' ? join(home, 'profiles') : join(modules, 'cycle') + mkdirSync(dirname(cycle), { recursive: true }) + const linkType = process.platform === 'win32' ? 'junction' : 'dir' + const links: string[] = [] + try { + const ordinaryLink = join(modules, 'external-directory') + symlinkSync(outside, ordinaryLink, linkType) + links.push(ordinaryLink) + symlinkSync(cycle, cycle, linkType) + links.push(cycle) + const nativeError = thrownError(() => realpathSync.native(cycle)) + expect(nativeError.code).toBe('ELOOP') + expect(nativeError.path).toBe(cycle) + await expect(createRuntimeResolution({ + installAnchor: f.installAnchor, profile: f.profile, home, + })).rejects.toMatchObject({ + code: 'ELOOP', path: cycle, message: nativeError.message, + }) + } finally { + for (const link of links.reverse()) unlinkSync(link) + } + }, + ) + /** A plugin repository linked into the profile, with the manifest a plugin developer keeps for type checking. */ function linkedPluginFixture(peerDependencies: Record | undefined = { '@deepseek-ai/dsh-core': '*' }): { f: ReturnType @@ -1782,6 +1876,182 @@ describe('runtime resolution', { concurrent: false }, () => { return { f, linkedRoot, helper, writeManifest } } + it.each(['src', 'dist'] as const)( + 'keeps intermediate %s/node_modules ahead of linked-root peers and ancestor packages', async (directory) => { + const { f, linkedRoot } = linkedPluginFixture() + const intermediate = join(linkedRoot, directory) + const queries = [ + ['@deepseek-ai/dsh-core', 41], + ['@deepseek-ai/dsh-util', 42], + ['left-pad', 43], + ] as const + for (const [name, marker] of queries) pkg(join(intermediate, 'node_modules', name), name, marker) + const require = createRequire(join(intermediate, 'nested', 'entry.cjs')) + const parent = pathToFileURL(join(intermediate, 'nested', 'entry.mjs')).href + const registration = installRuntimeInterception(await resolutionOf(f)) + registrations.push(registration) + try { + for (const [name, marker] of queries) { + const selected = join(intermediate, 'node_modules', name) + expect(require.resolve(name), name).toBe(join(selected, 'index.cjs')) + expect(require(name), name).toEqual({ marker }) + expect(resolveFrom(name, parent), name).toBe(pathToFileURL(join(selected, 'index.js')).href) + expect(await importFrom(name, parent), name).toMatchObject({ marker }) + expect(registration.packageDir(name, parent), name).toBe(selected) + } + } finally { + registration.dispose() + registrations.pop() + } + }, + ) + + it.each([ + { names: 'outer-first', reverse: false }, + { names: 'outer-first', reverse: true }, + { names: 'inner-first', reverse: false }, + { names: 'inner-first', reverse: true }, + ])('resolves overlapping linked roots independently of names and order ($names, reverse=$reverse)', async ({ names, reverse }) => { + const f = fixture('inner-peer') + const installDir = dirname(f.installAnchor) + const outer = join(f.root, 'work', 'repo') + const inner = join(outer, 'packages', 'plugin') + pkg(outer, 'outer-repo', 0, {}, { 'shadowed-outer-peer': '*', 'outer-peer': '*' }) + pkg(inner, 'inner-plugin', 0, {}, { 'inner-peer': '*' }) + const queries = [ + { + name: 'inner-peer', nativeDir: join(inner, 'node_modules', 'inner-peer'), nativeMarker: 11, + selected: join(installDir, 'node_modules', 'inner-peer'), marker: 1, + }, + { + name: 'shadowed-outer-peer', nativeDir: join(inner, 'node_modules', 'shadowed-outer-peer'), nativeMarker: 12, + selected: join(inner, 'node_modules', 'shadowed-outer-peer'), marker: 12, + }, + { + name: 'outer-peer', nativeDir: join(outer, 'node_modules', 'outer-peer'), nativeMarker: 13, + selected: join(installDir, 'node_modules', 'outer-peer'), marker: 3, + }, + ] + pkg(installDir, '@deepseek-ai/dsh', 0, Object.fromEntries(queries.map(({ name }) => [name, '*']))) + for (const [index, query] of queries.entries()) { + pkg(join(installDir, 'node_modules', query.name), query.name, index + 1) + pkg(query.nativeDir, query.name, query.nativeMarker) + } + const outerName = names === 'outer-first' ? 'a-repo' : 'z-repo' + const innerName = names === 'outer-first' ? 'z-plugin' : 'a-plugin' + const modules = join(f.profile.dir, 'node_modules') + mkdirSync(modules, { recursive: true }) + const links: string[] = [] + try { + for (const [name, target] of [[outerName, outer], [innerName, inner]] as const) { + const link = join(modules, name) + symlinkSync(target, link, process.platform === 'win32' ? 'junction' : 'dir') + links.push(link) + } + const resolution = await resolutionOf(f) + expect(resolution.linkedRoots.map(root => root.realPath)) + .toEqual(names === 'outer-first' ? [outer, inner] : [inner, outer]) + const linkedRoots = reverse ? [...resolution.linkedRoots].reverse() : resolution.linkedRoots + const require = createRequire(join(inner, 'entry.cjs')) + const parent = pathToFileURL(join(inner, 'entry.mjs')).href + for (const query of queries) expect(require.resolve(query.name)).toBe(join(query.nativeDir, 'index.cjs')) + const registration = installRuntimeInterception({ ...resolution, linkedRoots }) + registrations.push(registration) + try { + for (const { name, selected, marker } of queries) { + expect(require.resolve(name), name).toBe(join(selected, 'index.cjs')) + expect(require(name), name).toEqual({ marker }) + expect(resolveFrom(name, parent), name).toBe(pathToFileURL(join(selected, 'index.js')).href) + expect(await importFrom(name, parent), name).toMatchObject({ marker }) + expect(registration.packageDir(name, parent), name).toBe(selected) + } + } finally { + registration.dispose() + registrations.pop() + } + for (const query of queries) expect(require.resolve(query.name)).toBe(join(query.nativeDir, 'index.cjs')) + } finally { + for (const link of links.reverse()) unlinkSync(link) + } + }) + + it.each(['host', 'dependency', 'workspace-logical', 'workspace-real'] as const)( + 'keeps %s importers native inside a wide linked root', async (importer) => { + const name = '@deepseek-ai/dsh-core' + const f = fixture(name) + const installDir = dirname(f.installAnchor) + pkg(installDir, '@deepseek-ai/dsh', 0, { + [name]: '*', 'host-consumer': '*', 'workspace-consumer': '*', + }) + const hostSource = join(installDir, 'src') + const dependency = join(installDir, 'node_modules', 'host-consumer') + const workspace = join(f.root, 'workspace-consumer') + const workspaceLink = join(installDir, 'node_modules', 'workspace-consumer') + const external = join(f.root, 'external-plugin') + for (const [dir, packageName, marker] of [ + [hostSource, 'host-source', 11], + [dependency, 'host-consumer', 21], + [workspace, 'workspace-consumer', 22], + [external, 'external-plugin', 31], + ] as const) { + pkg(dir, packageName, 0, {}, { [name]: '*' }) + pkg(join(dir, 'node_modules', name), name, marker) + } + const linkType = process.platform === 'win32' ? 'junction' : 'dir' + const wideLink = join(f.profile.dir, 'node_modules', 'wide-workspace') + mkdirSync(dirname(wideLink), { recursive: true }) + const links: string[] = [] + try { + symlinkSync(workspace, workspaceLink, linkType) + links.push(workspaceLink) + symlinkSync(f.root, wideLink, linkType) + links.push(wideLink) + const importers = { + host: { dir: hostSource, marker: 11 }, + dependency: { dir: dependency, marker: 21 }, + 'workspace-logical': { dir: workspaceLink, marker: 22 }, + 'workspace-real': { dir: workspace, marker: 22 }, + } + const { dir, marker } = importers[importer] + const expectedDir = join(dir, 'node_modules', name) + const realDir = realpathSync.native(expectedDir) + const require = createRequire(join(dir, 'entry.cjs')) + const parent = pathToFileURL(join(dir, 'entry.mjs')).href + const nativeCjs = require.resolve(name) + const nativeEsm = resolveFrom(name, parent) + expect(nativeCjs).toBe(join(realDir, 'index.cjs')) + expect(nativeEsm).toBe(pathToFileURL(join(realDir, 'index.js')).href) + const resolution = await resolutionOf(f) + expect(resolution.entries.find(entry => entry.name === 'workspace-consumer')) + .toMatchObject({ scope: 'installation', packageDir: workspaceLink }) + expect(resolution.linkedRoots).toEqual([ + { name: 'wide-workspace', realPath: f.root }, + ]) + const registration = installRuntimeInterception(resolution) + registrations.push(registration) + try { + const externalRequire = createRequire(join(external, 'entry.cjs')) + const externalParent = pathToFileURL(join(external, 'entry.mjs')).href + expect(externalRequire.resolve(name)).toBe(join(f.installed, 'index.cjs')) + expect(externalRequire(name)).toEqual({ marker: 1 }) + expect(resolveFrom(name, externalParent)).toBe(pathToFileURL(join(f.installed, 'index.js')).href) + expect(await importFrom(name, externalParent)).toMatchObject({ marker: 1 }) + expect(registration.packageDir(name, externalParent)).toBe(f.installed) + expect(require.resolve(name)).toBe(nativeCjs) + expect(require(name)).toEqual({ marker }) + expect(resolveFrom(name, parent)).toBe(nativeEsm) + expect(await importFrom(name, parent)).toMatchObject({ marker }) + expect(registration.packageDir(name, parent)).toBe(expectedDir) + } finally { + registration.dispose() + registrations.pop() + } + } finally { + for (const link of links.reverse()) unlinkSync(link) + } + }, + ) + it('occupies only the peer names of a linked plugin at its own node_modules', async () => { const { f, linkedRoot, helper } = linkedPluginFixture() const registration = installRuntimeInterception(await resolutionOf(f)) From 73e9efbbdff61522e867908c6ad29caa18d30673 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Mon, 21 Sep 2026 13:37:24 +0800 Subject: [PATCH 099/100] docs(boot): define linked-root removal across generations --- ...-09-profile-resolution-generations.i18n.yaml | 4 ++-- ...2026-09-09-profile-resolution-generations.md | 17 +++++++++++------ ...6-09-09-profile-resolution-generations.zh.md | 17 +++++++++++------ ...19-profile-resolution-lookup-order.i18n.yaml | 4 ++-- ...026-09-19-profile-resolution-lookup-order.md | 2 +- ...-09-19-profile-resolution-lookup-order.zh.md | 2 +- packages/boot/app-boot/README.i18n.yaml | 4 ++-- packages/boot/app-boot/README.md | 3 ++- packages/boot/app-boot/README.zh.md | 3 ++- 9 files changed, 34 insertions(+), 22 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml index 0f95b21360..1d1ecb3a28 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.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 .agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md -2026-09-09-profile-resolution-generations.md: 39ce2415ca51b31641d643a9635ad57205385975 -2026-09-09-profile-resolution-generations.zh.md: ea15cb2792a49c2c99951f2faf619d68b6b5b98a +2026-09-09-profile-resolution-generations.md: 649c6c358fece5557031b4a21f3d3ebdd9dac8f7 +2026-09-09-profile-resolution-generations.zh.md: 4e84cc1f1b763c88b4ae96c4c44ae79de0d4c0d6 diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md index 39ce2415ca..649c6c358f 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md +++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md @@ -8,11 +8,11 @@ English | [中文](2026-09-09-profile-resolution-generations.zh.md) A profile loads plugin rows from its own package project, while Harness packages and packages carried by selected bundles can live outside that project's ordinary dependency tree. Bridging the trees through shared symlinks, profile-owned links, or packaged-executable proxy packages persists package selections across processes and installations. Those files require reconciliation and locking, expose generated proxy manifests to metadata readers, and cannot represent a process-local change atomically. -The runtime design keeps installation-first, ordered-bundle, and local-before-fallback precedence. It covers imports performed by plugin modules as well as Loader row imports and works in the main thread and Harness-owned Workers. Generation replacement accepts only additive package sets and never mutates a live table entry by entry. +The runtime design keeps installation-first, ordered-bundle, and local-before-fallback precedence. It covers imports performed by plugin modules as well as Loader row imports and works in the main thread and Harness-owned Workers. Generation replacement preserves existing package mappings and local package names, permits linked-root membership changes, and never mutates a live table entry by entry. ## Decision -Profile startup computes one immutable `RuntimeResolution` and installs it into Node's ESM and CommonJS resolvers. Runtime is the only resolution backend; there is no mode selector or disk materializer. `PluginPackages.replace()` publishes a complete additive successor with one reference replacement. +Profile startup computes one immutable `RuntimeResolution` and installs it into Node's ESM and CommonJS resolvers. Runtime is the only resolution backend; there is no mode selector or disk materializer. `PluginPackages.replace()` publishes a complete successor with one reference replacement. ### One selection algorithm @@ -64,13 +64,18 @@ For example, `@deepseek-ai/dsh-tools` creates its scheduler key with `Symbol()`. The source launcher does not install a CommonJS TypeScript hook. `createRequire().resolve()` still selects the package's published JavaScript entry and requires that file to exist. Source-mode resolution tests therefore use fixture-provided CommonJS files; checks of real installation CommonJS entries run with build outputs present. + ### Immutable generations A runtime interception holds one `current` generation. Each synchronous resolution captures that reference once. Generation construction reads every required dependency-graph manifest before publication; an error leaves the current generation unchanged. Successful publication replaces one reference, and in-flight calls may finish against the generation they captured. Selection and package-metadata caches belong to a generation. Publishing a successor invalidates them by making the old generation unreachable after its callers finish; update code does not mutate or clear individual entries. Profile-importer hits and successful native selections can be cached, but a generation miss is rescanned so a profile-local package installed after the miss becomes visible through native lookup. Linked importer routes are not cached: each resolution reads current peer declarations at the ancestor positions it visits. Explicit CommonJS paths bypass interception entirely; non-default conditions never reuse a default-resolution cache entry. -The launcher constructs one startup generation. The service accepts an additive successor, but no package-manager transaction invokes replacement in this implementation. +Linked-root membership is immutable within a generation. A successor may add or remove roots without restarting the process. When no remaining root covers a directory, subsequent resolutions there use native Node lookup, including new requests from already loaded modules. A request may then select a development copy or fail because the package is absent. Removing interception does not unload modules, replace existing references, or clear Node's own caches. + +The router retains the real target of each successfully published link name for its lifetime, solely to validate successors. Removing a root does not erase that record or keep its directory intercepted. Re-adding the same name and target is allowed; a different target is rejected because Node caches real paths. Failed publication changes neither the current generation nor the recorded targets. + +The launcher constructs one startup generation. The service accepts a complete successor, but no package-manager transaction invokes replacement in this implementation. ### Shared ESM and CommonJS rule @@ -102,7 +107,7 @@ New Workers inherit the latest published generation. Existing Workers keep the g A caller adding a package completes its pnpm transaction before constructing a successor generation. Replacement rejects any generation that changes the directory or version of an existing package. The caller publishes an additive successor before mounting the new Loader row; this implementation does not provide that package transaction. A mount failure may leave the package installed but inactive. -Replacing, upgrading, or removing an already loaded package requires process restart because Node's ESM Module Map, CommonJS cache, existing object references, and running Workers can retain the old module identity. Generation replacement does not claim to unload modules. +Changing or removing an existing runtime package mapping, or removing a recorded profile-local package name, requires process restart because Node's ESM Module Map, CommonJS cache, existing object references, and running Workers can retain the old module identity. These restrictions do not prohibit removing a linked root from the interception scope. Generation replacement does not claim to unload modules. ### Filesystem and runtime carriers @@ -137,7 +142,7 @@ Behavior tests exercise root order, transitive and peer dependencies, local and ## Verification - One eager computation supplies the runtime resolution; startup neither writes nor retires module-resolution data. -- [Generation tests](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts) cover installation and selected-bundle graphs with ordinary directories and recursive symlinks, including different dependency versions beside logical and real anchors. +- [Generation tests](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts) cover installation and selected-bundle graphs with ordinary directories and recursive symlinks, including different dependency versions beside logical and real anchors. They also cover linked-root removal, same-target restoration, overlapping roots, native misses, new requests from loaded modules, and relink rejection after removal. - [Source-launch tests](../../../../apps/cli/tests/source-launch.compat.spec.ts) and [built-bin tests](../../../../apps/cli/tests/built-bin.e2e.ts) run both profile layouts through the real CLI. They assert ESM/CJS versions, loaded paths, per-format dependency identity, and consistent Tools/AgentLoop module instances with an accessible scheduler key. - Pkg and Electron carriers select runtime resolution; Electron executes its Host in Node mode from the ASAR-backed dsh tree while native executable entries remain unpacked. - ESM and CommonJS adapters share one router and delegate final resolution to Node without `module.registerHooks` or `_findPath` replacement. @@ -147,4 +152,4 @@ Behavior tests exercise root order, transitive and peer dependencies, local and ## Consequences -Runtime startup avoids disk mutation and proxy manifests while retaining package-precedence rules. Real-directory anchors align dependency discovery with default Node loading and tsx workspace mapping, including cases where a logical symlink path would select another version. The implementation accepts the maintenance cost of Node Internal compatibility tests and an early, self-contained bootstrap in each owned Worker; it provides no disk-only backend or dual comparison mode. Generation replacement remains additive until the product owns module-cache invalidation and Worker restart. +Runtime startup avoids disk mutation and proxy manifests while retaining package-precedence rules. Real-directory anchors align dependency discovery with default Node loading and tsx workspace mapping, including cases where a logical symlink path would select another version. The implementation accepts the maintenance cost of Node Internal compatibility tests and an early, self-contained bootstrap in each owned Worker; it provides no disk-only backend or dual comparison mode. Package mappings and local package names remain additive; linked-root membership may change without unloading modules. diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md index ea15cb2792..4e84cc1f1b 100644 --- a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md @@ -8,11 +8,11 @@ Status: implemented profile 从自己的包项目加载插件配置项,而 Harness 包和所选 bundle 携带的包可能位于该项目普通依赖树之外。通过共享 symlink、profile 自有链接或打包可执行文件的代理包连接两棵依赖树,会让选包结果跨进程和安装版本持续存在。这些文件需要协调和锁来维护,并向元数据读取方暴露生成的代理 manifest(元数据清单),也无法原子表示进程内变更。 -运行时设计保留安装优先、有序 bundle 和本地包优先于 fallback 的顺序。它覆盖插件模块内部的 import 以及 Loader 配置项的 import,并在主线程和 Harness 自有 Worker 中工作。generation 替换只接受新增包的集合,不会逐项修改正在使用的表。 +运行时设计保留安装优先、有序 bundle 和本地包优先于 fallback 的顺序。它覆盖插件模块内部的 import 以及 Loader 配置项的 import,并在主线程和 Harness 自有 Worker 中工作。generation 替换保留既有包映射和本地包名,允许调整 linked root 集合,不会逐项修改正在使用的表。 ## Decision -profile 启动生成一个不可变 `RuntimeResolution`,并将其安装到 Node 的 ESM 与 CommonJS 解析器。runtime 是唯一的解析后端,不提供模式选择器或磁盘物化器。`PluginPackages.replace()` 通过一次引用替换发布完整的新增型后继 generation。 +profile 启动生成一个不可变 `RuntimeResolution`,并将其安装到 Node 的 ESM 与 CommonJS 解析器。runtime 是唯一的解析后端,不提供模式选择器或磁盘物化器。`PluginPackages.replace()` 通过一次引用替换发布完整的后继 generation。 ### 唯一选包算法 @@ -64,13 +64,18 @@ ESM `import` 和 CommonJS `require` 都选中这些版本。在每种模块格 源码启动器不安装 CommonJS TypeScript 钩子。`createRequire().resolve()` 仍选择包发布的 JavaScript 入口,并要求该文件存在。因此,源码模式的解析测试使用 fixture 提供的 CommonJS 文件,真实安装包的 CommonJS 入口检查则在构建产物存在时运行。 + ### 不可变 generation 一个 runtime interception 持有一个 `current` generation。每个同步 resolve 在入口只捕获一次该引用,完整调用只读该引用。generation 构造在发布前读取依赖图所需的全部 manifest;失败时当前 generation 不变。发布成功只替换一个引用,执行中的调用可以继续使用它已捕获的 generation。 选包缓存和包元数据缓存归 generation 所有。发布下一代后,旧 generation 在调用方退出后自然不可达,不逐项清理缓存。profile importer 的命中和原生解析成功结果可以缓存,但 generation 未命中会重新扫描,因此未命中后安装的 profile 本地包会通过原生查找变为可见。linked importer 的路由不缓存,每次解析读取所访问祖先位置当前的 peer 声明。显式 CommonJS paths 完全绕过拦截,非默认 conditions 不复用默认解析缓存。 -launcher 只构造启动 generation。服务接受新增型后继 generation,但本实现没有包管理器事务调用替换操作。 +linked root 集合在一个 generation 内不可变。后继 generation 可以增加或移除 root,无需重启进程。目录不再被任何剩余 root 覆盖时,该目录后续的解析使用原生 Node 查询,包括已加载模块发起的新请求。请求可能因此选中开发副本,也可能因缺包而失败。移除拦截不会卸载模块、替换已有引用或清空 Node 自身的缓存。 + +解析器在自身生命周期内保留每个已成功发布的 link 名称对应的真实目标,仅用于校验后继 generation。移除 root 不会抹掉该记录,也不会让其目录继续被拦截。同名、同目标可以重新加入;不同目标会被拒绝,因为 Node 缓存真实路径。发布失败时,当前 generation 和已记录目标均不变。 + +launcher 只构造启动 generation。服务接受完整的后继 generation,但本实现没有包管理器事务调用替换操作。 ### ESM 与 CommonJS 共用规则 @@ -102,7 +107,7 @@ runtime resolution 列出它提供的包;Loader entries 组成活动插件列 添加包的调用方先完成 pnpm 事务,再构造下一代。替换操作会拒绝改变任何既有 package name 的目录或版本。调用方先发布只增加映射的后继 generation,再挂载新的 Loader 配置项;本实现不提供该包事务。挂载失败可以留下已安装但未启用的包。 -替换、升级或删除已加载包需要重启,因为 Node 的 ESM Module Map、CommonJS cache、现存对象引用和运行中的 Worker 都可能保留旧模块 identity。generation 换代不声称卸载模块。 +修改或删除既有运行时包映射,或删除已记录的 profile 本地包名,需要重启,因为 Node 的 ESM Module Map、CommonJS cache、现存对象引用和运行中的 Worker 都可能保留旧模块 identity。这些限制不禁止从拦截范围移除 linked root。generation 换代不声称卸载模块。 ### 文件系统与运行时载体 @@ -137,7 +142,7 @@ generation 构造发生在启动或显式更新阶段,不属于单次 resolve ## Verification - 一次 eager 计算供应 runtime resolution;启动既不写入也不退休模块解析数据。 -- [Generation 测试](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts)覆盖普通目录和递归软链接下的安装图与所选 bundle 图,包括逻辑锚点和真实锚点旁存在不同依赖版本的情况。 +- [Generation 测试](../../../../packages/boot/app-boot/tests/profile-resolution.spec.ts)覆盖普通目录和递归软链接下的安装图与所选 bundle 图,包括逻辑锚点和真实锚点旁存在不同依赖版本的情况。测试还覆盖 linked root 移除、同目标恢复、重叠 root、原生缺包、已加载模块的新请求,以及移除后重新链接不同目标时的拒绝。 - [源码启动测试](../../../../apps/cli/tests/source-launch.compat.spec.ts)与[构建入口测试](../../../../apps/cli/tests/built-bin.e2e.ts)通过真实 CLI 运行两种 profile 布局,断言 ESM/CJS 版本、加载路径、各模块格式内的依赖身份,以及一致的 Tools/AgentLoop 模块实例和可访问的 scheduler 键。 - pkg 与 Electron 载体选择 runtime 解析;Electron 以 Node 模式从 ASAR 承载的 dsh 依赖树执行 Host,原生可执行条目保持 unpacked。 - ESM 与 CommonJS 适配器共享同一个路由器,并把最终解析委托给 Node,不使用 `module.registerHooks` 或替换 `_findPath`。 @@ -147,4 +152,4 @@ generation 构造发生在启动或显式更新阶段,不属于单次 resolve ## Consequences -runtime 启动避免磁盘修改和代理 manifest,同时保留包优先级规则。真实目录锚点让依赖发现对齐 Node 默认加载与 tsx workspace 映射,也覆盖软链接逻辑路径会选中另一版本的情况。实现需要持续维护 Node Internal 兼容测试,并在每个自有 Worker 中尽早执行自包含 bootstrap;它不提供纯磁盘后端或 dual 对比模式。在产品拥有模块缓存失效和 Worker 重启前,generation 替换只能新增映射。 +runtime 启动避免磁盘修改和代理 manifest,同时保留包优先级规则。真实目录锚点让依赖发现对齐 Node 默认加载与 tsx workspace 映射,也覆盖软链接逻辑路径会选中另一版本的情况。实现需要持续维护 Node Internal 兼容测试,并在每个自有 Worker 中尽早执行自包含 bootstrap;它不提供纯磁盘后端或 dual 对比模式。包映射和本地包名仍只允许新增;linked root 集合可以变化,而不卸载模块。 diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml index 8965c2b9db..da2d68745b 100644 --- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.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 .agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md -2026-09-19-profile-resolution-lookup-order.md: 0830aac1ef00aadf56aee8179c59324230e132d5 -2026-09-19-profile-resolution-lookup-order.zh.md: 9817f2001e484208edd3755bc0f80d5a3029b4c7 +2026-09-19-profile-resolution-lookup-order.md: 6dfb5511afe885875a778b8a4f1b7c5fc3c0d842 +2026-09-19-profile-resolution-lookup-order.zh.md: 2474a9b040cb4917e71b7002d36c1e61fe3bc106 diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md index 0830aac1ef..6dfb5511af 100644 --- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md +++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.md @@ -56,7 +56,7 @@ At each candidate `D/node_modules`, a matching current `D/package.json` peer dec A nearer physical candidate wins before any later ancestor peer declaration. If a selected package's `exports` rejects the request, Node's error is final. A legacy CommonJS subpath miss can continue to the next position, where that directory's peer rule applies again; the physical copy at an occupied position is not retried. Each new linked resolution reads the manifests at the positions it visits, without memoizing its selected route. An unreadable manifest supplies no peers; Node retains its native manifest diagnostics. This does not clear Node's caches or automatically reload already loaded modules. -Runtime resolution construction scans top-level and `@scope/*` links in `/node_modules`. A successor may add or remove linked roots within the existing package-mapping and local-name constraints; changing the real target of an existing link name rejects publication and requires restart because Node caches real paths. A dependency whose real path lies outside every recorded linked root remains outside interception, even when a plugin links to it. +Runtime resolution construction scans top-level and `@scope/*` links in `/node_modules`. A successor may add or remove linked roots within the existing package-mapping and local-name constraints. Removal needs no restart: a directory no longer covered by any root returns to native lookup for subsequent resolutions. The [generation rules](2026-09-09-profile-resolution-generations.md#immutable-generations) define publication, existing module references, and relink checks across removal. A dependency whose real path lies outside every recorded linked root remains outside interception, even when a plugin links to it. #### 4. What the interception layer holds: the runtime resolution's scan contents diff --git a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md index 9817f2001e..2474a9b040 100644 --- a/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-19-profile-resolution-lookup-order.zh.md @@ -56,7 +56,7 @@ linked 拦截排除 installation 作用域包目录内的 importer,同时识 更近的物理候选先于后续祖先的 peer 声明。选中包的 `exports` 拒绝请求时,Node 的错误是终局。旧式 CommonJS 子路径缺失可以继续到下一位置,再应用那个目录的 peer 规则;不会重试已被占据位置上的物理副本。每次新的 linked 解析读取所访问位置的 manifest,不缓存选中的路由。不可读的 manifest 不提供 peer,Node 保留其原生 manifest 诊断。这不清除 Node 缓存,也不自动重新加载已加载的模块。 -runtime resolution 构造时扫描 `/node_modules` 的顶层与 `@scope/*` 链接。successor 可以在既有包映射和本地包名约束内新增或移除 linked root;同名 link 换了真实目标则拒绝发布并要求重启,因为 Node 缓存 realpath。依赖的真实路径在所有已记录 linked root 之外时,即使插件链接到它,也不参与拦截。 +runtime resolution 构造时扫描 `/node_modules` 的顶层与 `@scope/*` 链接。successor 可以在既有包映射和本地包名约束内新增或移除 linked root。移除无需重启:目录不再被任何 root 覆盖时,后续解析恢复原生查询。[Generation 规则](2026-09-09-profile-resolution-generations.zh.md#immutable-generations)定义了发布、已有模块引用,以及跨越移除操作的重新链接检查。依赖的真实路径在所有已记录 linked root 之外时,即使插件链接到它,也不参与拦截。 #### 4. 拦截层里有什么:runtime resolution 的扫描内容 diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml index 0896d50887..4414ee4397 100644 --- a/packages/boot/app-boot/README.i18n.yaml +++ b/packages/boot/app-boot/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md -README.md: e2bea1658eaff832eecef815f8d86215efbdf88b -README.zh.md: 927d88e4ca147cb7be0e2a6f839c6c94da96aef5 +README.md: 8a62a75dc5be8c2e55d8908a46f9c91581427a46 +README.zh.md: b7c07b1018be9413f0844fb26904797102acee1e diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md index e2bea1658e..8a62a75dc5 100644 --- a/packages/boot/app-boot/README.md +++ b/packages/boot/app-boot/README.md @@ -119,7 +119,8 @@ This section explains how the outcomes above are realized and points at the code - **Package metadata.** `ctx.pluginPackages.packageOf` locates the owning package without loading code or requiring an exported `package.json`; a subpath selects its package without validating that file. The installed runtime resolution owns selection even for a miss. Low-level embedders that install the service without one retain native lookup. Display metadata uses the separate entry-aware reader described above. - **Two Loader builtins.** `mountRootInclude` registers `cordis:include` and `cordis:group` as Loader builtins: a group row gives one `isolate` realm to a provider and its consumers together, and an agent preset outside this workspace cannot resolve `@deepseek-ai/cordis-plugin-group` by name. Both load through the ambient module pipeline rather than the included tree's own specifier resolution. - **Consumer-owned strictness.** Ordinary Loader groups keep successful siblings. App-boot applies the global required-entry policy after initial settlement; agent presets and dynamic multi-entry compositions own and dispose their separate Loader subtree when they require all-or-nothing setup. App-boot reads failed fibers to report their recorded errors and coalesces duplicate Loader rejection notifications through one process checkpoint. -- **One runtime resolution.** The installation-first and ordered-bundle breadth-first traversal produces the runtime table. Runtime resolution creates no links; runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`, and every other name sees that directory as an ordinary ancestor. Profile load removes the `.dsh-module-fallback` projections that link-backend releases wrote into a profile; pnpm-installed packages stay. External bare targets selected by package `imports` use the same package order, while Node retains mapping, conditions, and exact target resolution. A complete successor may add package names and update linked-root membership atomically within the existing package-mapping and local-name constraints; changing or removing an existing mapping, or pointing an existing linked root at another directory, requires restart. +- **One runtime resolution.** The installation-first and ordered-bundle breadth-first traversal produces the runtime table. Runtime resolution creates no links; runtime resolution entries occupy their package names at `$DSH_HOME/profiles/node_modules`, and every other name sees that directory as an ordinary ancestor. Profile load removes the `.dsh-module-fallback` projections that link-backend releases wrote into a profile; pnpm-installed packages stay. External bare targets selected by package `imports` use the same package order, while Node retains mapping, conditions, and exact target resolution. A complete successor may add package names and update linked-root membership atomically within the existing package-mapping and local-name constraints. +- **Removing linked interception.** A successor may remove a linked root without restart. Directories outside all remaining roots use native lookup for subsequent requests, which may find a development copy or report a missing package. Existing module references and Node caches stay unchanged. Re-adding the same link name and target is allowed; pointing a previously published name at a different target is rejected even after removal ([generation rules](../../../.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md#immutable-generations)). - **Application-owned profiles.** Application-owned profiles use the same runtime resolution. Links within the active profile directory, including pnpm store links, are not external roots even when the profile is outside the shared profiles tree. Resolution does not modify their `node_modules`; pnpm owns installed packages. - **Owned Workers.** Worker build banners import `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap` before bundled business code. Each Worker installs the structured-cloned runtime resolution in its own isolate. The bootstrap bundle has no static package imports. Source Worker entries retain their self-contained dependency closure, and third-party Workers receive no injection. - **Update completion.** App boot observes restart failures through the `internal/update` waterfall. Live patch reloads wait for the tree's fibers before auditing activation; `Fiber.update()` and `Entry.update()` alone do not establish restart success. diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md index 927d88e4ca..b7c07b1018 100644 --- a/packages/boot/app-boot/README.zh.md +++ b/packages/boot/app-boot/README.zh.md @@ -119,7 +119,8 @@ Loader 结算后,app-boot 在仅 optional 条目未激活时输出警告。如 - **包元数据。** `ctx.pluginPackages.packageOf` 定位所属包,不加载代码,也不要求导出 `package.json`;子路径选择其所属包,不校验该文件。安装 runtime resolution 后,即使查询未命中也以其选包规则为准。仅安装服务而不提供 runtime resolution 的底层嵌入方保留原生查询。展示元数据使用上文另述的入口感知读取器。 - **两个 Loader builtin。** `mountRootInclude` 把 `cordis:include` 与 `cordis:group` 注册为 Loader builtin:group 行能把一个提供方与它的消费方放进同一个 `isolate` realm,而位于本工作区之外的 agent preset 无法按名称解析 `@deepseek-ai/cordis-plugin-group`。两者都通过宿主的模块管线加载,而非被包含树自身的说明符解析。 - **由 consumer 持有严格语义。** 普通 Loader group 保留成功 sibling。App-boot 在首次结算后应用全局 required-entry policy;agent preset 与动态多 entry 组合在需要 all-or-nothing setup 时,持有并拆卸各自的独立 Loader 子树。App-boot 读取 failed fiber 来报告已记录的错误,并在一个进程检查点内合并 Loader 重复的 rejection 通知。 -- **唯一 runtime resolution。** 安装优先、有序 bundle 逐根 breadth-first 遍历生成运行时表。runtime 解析不创建链接;runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置,其余包名把该目录当作普通祖先。profile 加载时删除 Link 后端发布版写进 profile 的 `.dsh-module-fallback` 投影;pnpm 安装的包保留。package `imports` 选中的外部 bare target 使用相同的选包顺序,映射、conditions 和精确 target 解析仍由 Node 负责。完整后继 runtime resolution 可以在既有包映射和本地包名约束内原子增加 package name、更新 linked root 集合;修改或删除既有映射,或把既有 linked root 指向另一个目录,则要求重启。 +- **唯一 runtime resolution。** 安装优先、有序 bundle 逐根 breadth-first 遍历生成运行时表。runtime 解析不创建链接;runtime resolution 条目占据 `$DSH_HOME/profiles/node_modules` 上各自的包名位置,其余包名把该目录当作普通祖先。profile 加载时删除 Link 后端发布版写进 profile 的 `.dsh-module-fallback` 投影;pnpm 安装的包保留。package `imports` 选中的外部 bare target 使用相同的选包顺序,映射、conditions 和精确 target 解析仍由 Node 负责。完整后继 runtime resolution 可以在既有包映射和本地包名约束内原子增加 package name、更新 linked root 集合。 +- **移除链接拦截。** 后继 generation 可以移除 linked root,无需重启。目录不再被任何剩余 root 覆盖时,后续请求使用原生查询,可能找到开发副本,也可能报告缺包。已有模块引用和 Node 缓存保持不变。同名、同目标可以重新加入;曾发布的名称改指向不同目标时,即使中间移除过也会被拒绝([generation 规则](../../../.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md#immutable-generations))。 - **应用自有 profile。** 应用自有 profile 使用相同的 runtime resolution。目标位于当前 profile 目录内的链接(包括 pnpm store 链接)不算外部 root,即使 profile 位于共享 profiles 树外。解析过程不修改其 `node_modules`;已安装包由 pnpm 管理。 - **自有 Worker。** Worker 构建 banner 会在业务 bundle 前导入 `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap`。每个 Worker 在自己的 isolate 中安装结构化克隆的 runtime resolution。bootstrap bundle 不静态导入任何包。源码 Worker 入口保留自包含依赖,第三方 Worker 不接受注入。 - **更新完成。** App boot 通过 `internal/update` waterfall 观察重启失败。实时 patch 重载在检查激活状态前等待配置树中的 fiber;单独调用 `Fiber.update()` 或 `Entry.update()` 不能确定重启成功。 From 7252e5823b438bb033ceec64c84275d247df88a7 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Mon, 21 Sep 2026 13:46:21 +0800 Subject: [PATCH 100/100] fix(boot): keep linked-root removal independent of relinking --- .../src/profile-resolution/resolver.ts | 38 +-- .../src/profile-resolution/service.ts | 5 +- .../tests/profile-resolution-service.spec.ts | 65 ++++ .../app-boot/tests/profile-resolution.spec.ts | 304 ++++++++++++++++++ 4 files changed, 392 insertions(+), 20 deletions(-) diff --git a/packages/boot/app-boot/src/profile-resolution/resolver.ts b/packages/boot/app-boot/src/profile-resolution/resolver.ts index 215c82b0d0..ea931a5087 100644 --- a/packages/boot/app-boot/src/profile-resolution/resolver.ts +++ b/packages/boot/app-boot/src/profile-resolution/resolver.ts @@ -7,7 +7,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url' import { getEnvironmentData, setEnvironmentData } from 'node:worker_threads' import type { ModuleLoaderV1, ModuleLoaderV2, ResolveResult } from '@deepseek-ai/cordis-plugin-loader' import { imports as resolvePackageImports, type Package as ResolvePackageManifest } from 'resolve.exports' -import type { LinkedRoot, RuntimeResolutionEntry, RuntimeResolution } from '../profile.ts' +import type { RuntimeResolutionEntry, RuntimeResolution } from '../profile.ts' const WORKER_RESOLUTION_KEY = '@deepseek-ai/dsh-app-boot/profile-resolution' const EMPTY_ATTRIBUTES: ImportAttributes = Object.freeze({}) @@ -91,11 +91,6 @@ type InterceptionLayer = | LayerPositions & { readonly kind: 'profile'; readonly active: boolean } | { readonly kind: 'linked' } -interface CompiledLinkedRoot { - readonly root: LinkedRoot - readonly paths: readonly string[] -} - interface ParentRoutes { readonly parent: string readonly layer: InterceptionLayer @@ -112,7 +107,7 @@ interface CompiledResolution { readonly profilePaths: readonly string[] readonly profile: readonly string[] readonly installationPaths: readonly string[] - readonly linkedRoots: readonly CompiledLinkedRoot[] + readonly linkedPaths: readonly string[] readonly localPackageNames: ReadonlySet readonly esmRoutes: ResolutionRoutes readonly cjsRoutes: ResolutionRoutes @@ -129,9 +124,11 @@ export interface RuntimeInterception { */ packageDir(specifier: string, parentURL: string): string | undefined /** - * Atomically publish an additive package table and fresh caches. - * @param successor - fully constructed additive successor generation. - * @throws when the profile scope, an existing package mapping, or a linked root's real directory changes. + * Atomically publish a complete successor and fresh caches. Linked roots may be added or removed. + * Removed roots stop intercepting uncovered directories; existing modules and Node caches remain intact. + * @param successor - fully constructed generation retaining existing package mappings and local names. + * @throws when the profile scope or existing mappings change, local names are removed or override + * existing mappings, or a previously published link name selects a different real directory. */ replace(successor: RuntimeResolution): void /** Restore the native resolver methods. Interceptions dispose in reverse order. */ @@ -178,7 +175,7 @@ function compileResolution(resolution: RuntimeResolution): CompiledResolution { installationPaths: [...new Set(resolution.entries .filter(entry => entry.scope === 'installation') .flatMap(entry => prefixes(entry.packageDir)))], - linkedRoots: resolution.linkedRoots.map(root => ({ root, paths: prefixes(root.realPath) })), + linkedPaths: resolution.linkedRoots.flatMap(root => prefixes(root.realPath)), localPackageNames: new Set(resolution.localPackageNames), esmRoutes: new Map(), cjsRoutes: new Map(), @@ -205,7 +202,7 @@ function findInterceptionLayer(path: string, resolution: CompiledResolution): In const activeProfile = resolution.profile.find(prefix => path.startsWith(prefix)) const dir = treeRoot !== undefined ? profileChild(path, treeRoot) : activeProfile?.slice(0, -1) if (dir !== undefined) return computeProfileLayer(dir, activeProfile !== undefined) - if (!resolution.linkedRoots.some(candidate => startsWithin(path, candidate.paths))) return undefined + if (!startsWithin(path, resolution.linkedPaths)) return undefined if (startsWithin(path, resolution.installationPaths)) return undefined return { kind: 'linked' } } @@ -366,9 +363,11 @@ function sameResolution(left: string, right: string): boolean { /** One mutable pointer to the immutable runtime resolution. */ class ResolutionRouter { private current: CompiledResolution + private readonly linkedTargets: Map constructor(resolution: RuntimeResolution, private readonly nodeModulePaths: (directory: string) => string[]) { this.current = compileResolution(resolution) + this.linkedTargets = new Map(resolution.linkedRoots.map(root => [root.name, root.realPath])) } replace(successor: RuntimeResolution): void { @@ -398,15 +397,18 @@ class ResolutionRouter { throw new Error(`profile resolution: overriding ${JSON.stringify(name)} locally requires a process restart`) } } - // Node memoizes real paths for the process lifetime, so a link that now points elsewhere would keep - // answering from its former directory. - for (const { root } of this.current.linkedRoots) { - const next = successor.linkedRoots.find(candidate => candidate.name === root.name) - if (next !== undefined && !sameResolution(root.realPath, next.realPath)) { + // Node retains realpath caches after a root leaves the interception scope. + for (const root of successor.linkedRoots) { + const previous = this.linkedTargets.get(root.name) + if (previous !== undefined && !sameResolution(previous, root.realPath)) { throw new Error(`profile resolution: relinking ${JSON.stringify(root.name)} requires a process restart`) } } - this.current = compileResolution(successor) + const next = compileResolution(successor) + for (const { name, realPath } of successor.linkedRoots) { + if (!this.linkedTargets.has(name)) this.linkedTargets.set(name, realPath) + } + this.current = next } /** Whether a module path has an interception layer: it lies in the profiles tree, the active profile, or a linked root. */ diff --git a/packages/boot/app-boot/src/profile-resolution/service.ts b/packages/boot/app-boot/src/profile-resolution/service.ts index fad03a2582..5523b51eaf 100644 --- a/packages/boot/app-boot/src/profile-resolution/service.ts +++ b/packages/boot/app-boot/src/profile-resolution/service.ts @@ -75,8 +75,9 @@ export class PluginPackages extends Service { } /** - * Publish an additive successor generation for this process and subsequently created Workers. - * @param successor - fully constructed successor generation. + * Publish a complete successor generation for this process and subsequently created Workers. + * Linked roots may be removed without unloading modules or clearing Node caches. + * @param successor - fully constructed generation accepted by {@link RuntimeInterception.replace}. */ replace(successor: RuntimeResolution): void { if (this.interception === undefined) throw new Error('plugin-packages: runtime resolution is not installed') diff --git a/packages/boot/app-boot/tests/profile-resolution-service.spec.ts b/packages/boot/app-boot/tests/profile-resolution-service.spec.ts index 2ba557170c..d066329d36 100644 --- a/packages/boot/app-boot/tests/profile-resolution-service.spec.ts +++ b/packages/boot/app-boot/tests/profile-resolution-service.spec.ts @@ -161,6 +161,71 @@ describe('profile package metadata service', () => { )).toBeUndefined() }) + it('removes and restores linked roots while rejecting changes to their historical targets', async () => { + const root = realpathSync.native(mkdtempSync(join(tmpdir(), 'dsh-linked-package-service-'))) + roots.push(root) + const profilesDir = join(root, 'profiles') + const profileDir = join(profilesDir, 'test') + const runtime = join(root, 'runtime') + const runtimeAnchor = pkg(runtime, '1.0.0') + const linkedA = join(root, 'work', 'a') + const linkedB = join(root, 'work', 'b') + for (const dir of [linkedA, linkedB]) { + file(join(dir, 'package.json'), JSON.stringify({ + name: 'linked-plugin', peerDependencies: { 'metadata-lib': '*' }, + })) + } + const local = join(linkedA, 'node_modules', 'metadata-lib') + pkg(local, '2.0.0') + const parentPath = join(linkedA, 'entry.mjs') + file(parentPath, '') + const parentURL = pathToFileURL(parentPath).href + const require = createRequire(parentURL) + const linked = { name: 'linked-plugin', realPath: linkedA } + const initial: RuntimeResolution = { + ...resolution(profilesDir, profileDir, runtime, runtimeAnchor, '1.0.0'), + linkedRoots: [linked], + } + const removed: RuntimeResolution = { ...initial, linkedRoots: [] } + const relinked: RuntimeResolution = { ...initial, linkedRoots: [{ ...linked, realPath: linkedB }] } + const key = '@deepseek-ai/dsh-app-boot/profile-resolution' + const previous = getEnvironmentData(key) + const ctx = new Context() + contexts.push(ctx) + await ctx.plugin(PluginPackages, { resolution: initial }) + + const expectSelectedPackage = (dir: string, version: string): void => { + expect(ctx.pluginPackages.packageOf('metadata-lib', parentURL)).toMatchObject({ + name: 'metadata-lib', version, dir, + }) + expect(require.resolve('metadata-lib')).toBe(realpathSync.native(join(dir, 'index.cjs'))) + } + expectSelectedPackage(runtime, '1.0.0') + expect(getEnvironmentData(key)).toEqual({ resolution: initial }) + + ctx.pluginPackages.replace(removed) + expectSelectedPackage(local, '2.0.0') + expect(getEnvironmentData(key)).toEqual({ resolution: removed }) + + ctx.pluginPackages.replace(initial) + expectSelectedPackage(runtime, '1.0.0') + expect(getEnvironmentData(key)).toEqual({ resolution: initial }) + + ctx.pluginPackages.replace(removed) + expectSelectedPackage(local, '2.0.0') + const removedWorkerData = getEnvironmentData(key) + expect(removedWorkerData).toEqual({ resolution: removed }) + expect(() => { ctx.pluginPackages.replace(relinked) }).toThrow( + 'profile resolution: relinking "linked-plugin" requires a process restart', + ) + expectSelectedPackage(local, '2.0.0') + expect(getEnvironmentData(key)).toBe(removedWorkerData) + + await ctx.fiber.dispose() + contexts.pop() + expect(getEnvironmentData(key)).toBe(previous) + }) + it('publishes additive generations to the process and future Workers', async () => { const root = mkdtempSync(join(tmpdir(), 'dsh-package-service-resolution-')) roots.push(root) diff --git a/packages/boot/app-boot/tests/profile-resolution.spec.ts b/packages/boot/app-boot/tests/profile-resolution.spec.ts index 7d0a78f2d3..493202fd69 100644 --- a/packages/boot/app-boot/tests/profile-resolution.spec.ts +++ b/packages/boot/app-boot/tests/profile-resolution.spec.ts @@ -1876,6 +1876,310 @@ describe('runtime resolution', { concurrent: false }, () => { return { f, linkedRoot, helper, writeManifest } } + describe('linked root generations', () => { + const peer = '@deepseek-ai/dsh-core' + + function unsavedFixture(): ReturnType { + const result = linkedPluginFixture() + file(join(result.f.profile.dir, 'package.json'), JSON.stringify({ + name: 'dsh-profile-web', private: true, dependencies: {}, + })) + return result + } + + function expectPeerLookup( + registration: RuntimeInterception, require: NodeJS.Require, parent: string, selected: string, + ): void { + expect(require.resolve(peer)).toBe(join(selected, 'index.cjs')) + expect(resolveFrom(peer, parent)).toBe(pathToFileURL(join(selected, 'index.js')).href) + expect(registration.packageDir(peer, parent)).toBe(selected) + } + + it('returns an unlinked importer to native lookup without changing its first generation', async () => { + const { f, linkedRoot } = unsavedFixture() + const link = join(f.profile.dir, 'node_modules', 'my-plugin') + const local = join(linkedRoot, 'node_modules', peer) + const require = createRequire(join(linkedRoot, 'entry.cjs')) + const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href + const first = await resolutionOf(f) + expect(first.localPackageNames).toEqual([]) + expect(first.linkedRoots).toEqual([{ name: 'my-plugin', realPath: linkedRoot }]) + const registration = installRuntimeInterception(first) + registrations.push(registration) + try { + expectPeerLookup(registration, require, parent, f.installed) + unlinkSync(link) + const second = await resolutionOf(f) + expect(second.localPackageNames).toEqual([]) + expect(second.linkedRoots).toEqual([]) + registration.replace(second) + expectPeerLookup(registration, require, parent, local) + expect(first.linkedRoots).toEqual([{ name: 'my-plugin', realPath: linkedRoot }]) + } finally { + registration.dispose() + registrations.pop() + } + }) + + it('reports native misses after unlinking when no physical peer remains', async () => { + const { f, linkedRoot } = unsavedFixture() + rmSync(join(linkedRoot, 'node_modules', peer), { recursive: true }) + const require = createRequire(join(linkedRoot, 'entry.cjs')) + const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href + const first = await resolutionOf(f) + expect(first.localPackageNames).toEqual([]) + const registration = installRuntimeInterception(first) + registrations.push(registration) + try { + expectPeerLookup(registration, require, parent, f.installed) + unlinkSync(join(f.profile.dir, 'node_modules', 'my-plugin')) + const second = await resolutionOf(f) + expect(second.linkedRoots).toEqual([]) + registration.replace(second) + expect(thrownError(() => require.resolve(peer))).toMatchObject({ code: 'MODULE_NOT_FOUND' }) + expect(thrownError(() => require(peer))).toMatchObject({ code: 'MODULE_NOT_FOUND' }) + expect(thrownError(() => resolveFrom(peer, parent))).toMatchObject({ code: 'ERR_MODULE_NOT_FOUND' }) + await expect(importFrom(peer, parent)).rejects.toMatchObject({ code: 'ERR_MODULE_NOT_FOUND' }) + expect(registration.packageDir(peer, parent)).toBeUndefined() + } finally { + registration.dispose() + registrations.pop() + } + }) + + it('restores the same link target and admits an additional root name', async () => { + const { f, linkedRoot } = unsavedFixture() + const link = join(f.profile.dir, 'node_modules', 'my-plugin') + const require = createRequire(join(linkedRoot, 'entry.cjs')) + const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href + const first = await resolutionOf(f) + expect(first.localPackageNames).toEqual([]) + const registration = installRuntimeInterception(first) + registrations.push(registration) + try { + expectPeerLookup(registration, require, parent, f.installed) + unlinkSync(link) + registration.replace(await resolutionOf(f)) + expectPeerLookup(registration, require, parent, join(linkedRoot, 'node_modules', peer)) + const linkType = process.platform === 'win32' ? 'junction' : 'dir' + symlinkSync(linkedRoot, link, linkType) + registration.replace(await resolutionOf(f)) + expectPeerLookup(registration, require, parent, f.installed) + + const additional = join(f.root, 'work', 'another-plugin') + pkg(additional, 'another-plugin', 0, {}, { [peer]: '*' }) + pkg(join(additional, 'node_modules', peer), peer, 31) + symlinkSync(additional, join(f.profile.dir, 'node_modules', 'another-plugin'), linkType) + const successor = await resolutionOf(f) + expect(successor.localPackageNames).toEqual([]) + expect(successor.linkedRoots).toEqual([ + { name: 'another-plugin', realPath: additional }, + { name: 'my-plugin', realPath: linkedRoot }, + ]) + registration.replace(successor) + expectPeerLookup(registration, require, parent, f.installed) + expectPeerLookup(registration, createRequire(join(additional, 'entry.cjs')), + pathToFileURL(join(additional, 'entry.mjs')).href, f.installed) + } finally { + registration.dispose() + registrations.pop() + } + }) + + it.each(['inner', 'outer'] as const)( + 'keeps an overlapping importer proxied after removing the %s root until the last root is removed', async (removed) => { + const { f, linkedRoot } = unsavedFixture() + const innerLink = join(f.profile.dir, 'node_modules', 'my-plugin') + const outer = dirname(linkedRoot) + const outerLink = join(f.profile.dir, 'node_modules', 'workspace') + symlinkSync(outer, outerLink, process.platform === 'win32' ? 'junction' : 'dir') + const require = createRequire(join(linkedRoot, 'entry.cjs')) + const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href + const first = await resolutionOf(f) + expect(first.localPackageNames).toEqual([]) + expect(first.linkedRoots).toEqual([ + { name: 'my-plugin', realPath: linkedRoot }, + { name: 'workspace', realPath: outer }, + ]) + const registration = installRuntimeInterception(first) + registrations.push(registration) + try { + expectPeerLookup(registration, require, parent, f.installed) + unlinkSync(removed === 'inner' ? innerLink : outerLink) + const second = await resolutionOf(f) + expect(second.linkedRoots).toEqual(removed === 'inner' + ? [{ name: 'workspace', realPath: outer }] + : [{ name: 'my-plugin', realPath: linkedRoot }]) + registration.replace(second) + expectPeerLookup(registration, require, parent, f.installed) + unlinkSync(removed === 'inner' ? outerLink : innerLink) + const third = await resolutionOf(f) + expect(third.linkedRoots).toEqual([]) + registration.replace(third) + expectPeerLookup(registration, require, parent, join(linkedRoot, 'node_modules', peer)) + } finally { + registration.dispose() + registrations.pop() + } + }, + ) + + it('uses native fresh subpaths from a loaded caller while held modules keep their values', async () => { + const { f, linkedRoot } = unsavedFixture() + const local = join(linkedRoot, 'node_modules', peer) + for (const [dir, marker] of [[f.installed, 1], [local, 21]] as const) { + file(join(dir, 'package.json'), JSON.stringify({ + name: peer, version: `${String(marker)}.0.0`, type: 'module', + exports: { + '.': { import: './index.js', require: './index.cjs' }, + './fresh': { import: './fresh.js', require: './fresh.cjs' }, + }, + })) + file(join(dir, 'fresh.js'), `export const marker = ${String(marker)}\n`) + file(join(dir, 'fresh.cjs'), `module.exports = { marker: ${String(marker)} }\n`) + } + // The fresh subpath has no completed Node resolution; root removal does not replace held module references. + file(join(linkedRoot, 'caller.js'), `import * as held from '${peer}'\nexport { held }\n` + + `export async function fresh() { return await import('${peer}/fresh') }\n`) + file(join(linkedRoot, 'caller.cjs'), `module.exports = { held: require('${peer}'), ` + + `fresh: () => require('${peer}/fresh') }\n`) + const require = createRequire(join(linkedRoot, 'entry.cjs')) + const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href + const first = await resolutionOf(f) + expect(first.localPackageNames).toEqual([]) + const registration = installRuntimeInterception(first) + registrations.push(registration) + try { + const cjsCaller = require('./caller.cjs') as { held: { marker: number }; fresh(): { marker: number } } + const esmCaller = await importFrom('./caller.js', parent) as { + held: { marker: number } + fresh(): Promise<{ marker: number }> + } + const heldCjs = cjsCaller.held + const heldEsm = esmCaller.held + expect(heldCjs).toEqual({ marker: 1 }) + expect(heldEsm).toMatchObject({ marker: 1 }) + unlinkSync(join(f.profile.dir, 'node_modules', 'my-plugin')) + const second = await resolutionOf(f) + expect(second.linkedRoots).toEqual([]) + registration.replace(second) + expect(cjsCaller.fresh()).toEqual({ marker: 21 }) + await expect(esmCaller.fresh()).resolves.toMatchObject({ marker: 21 }) + expect(cjsCaller.held).toBe(heldCjs) + expect(esmCaller.held).toBe(heldEsm) + expect(heldCjs).toEqual({ marker: 1 }) + expect(heldEsm).toMatchObject({ marker: 1 }) + } finally { + registration.dispose() + registrations.pop() + } + }) + + it.each(['initial', 'added'] as const)( + 'rejects a removed %s root retarget without reactivating either directory', async (generation) => { + const { f, linkedRoot } = unsavedFixture() + const link = join(f.profile.dir, 'node_modules', 'my-plugin') + const linkType = process.platform === 'win32' ? 'junction' : 'dir' + const require = createRequire(join(linkedRoot, 'entry.cjs')) + const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href + if (generation === 'added') unlinkSync(link) + const first = await resolutionOf(f) + expect(first.localPackageNames).toEqual([]) + expect(first.linkedRoots).toEqual(generation === 'added' + ? [] : [{ name: 'my-plugin', realPath: linkedRoot }]) + const registration = installRuntimeInterception(first) + registrations.push(registration) + try { + if (generation === 'added') { + symlinkSync(linkedRoot, link, linkType) + registration.replace(await resolutionOf(f)) + } + expectPeerLookup(registration, require, parent, f.installed) + unlinkSync(link) + const removed = await resolutionOf(f) + expect(removed.linkedRoots).toEqual([]) + registration.replace(removed) + expectPeerLookup(registration, require, parent, join(linkedRoot, 'node_modules', peer)) + + const target = join(f.root, 'work', 'retargeted-plugin') + pkg(target, 'my-plugin', 0, {}, { [peer]: '*' }) + pkg(join(target, 'node_modules', peer), peer, 22) + symlinkSync(target, link, linkType) + const successor = await resolutionOf(f) + expect(successor.localPackageNames).toEqual([]) + expect(successor.linkedRoots).toEqual([{ name: 'my-plugin', realPath: target }]) + expect(() => { registration.replace(successor) }) + .toThrow(/^profile resolution: relinking "my-plugin" requires a process restart$/u) + expectPeerLookup(registration, require, parent, join(linkedRoot, 'node_modules', peer)) + expectPeerLookup(registration, createRequire(join(target, 'entry.cjs')), + pathToFileURL(join(target, 'entry.mjs')).href, join(target, 'node_modules', peer)) + } finally { + registration.dispose() + registrations.pop() + } + }, + ) + + it('does not retain targets from a rejected successor', async () => { + const { f, linkedRoot } = unsavedFixture() + const modules = join(f.profile.dir, 'node_modules') + const originalLink = join(modules, 'my-plugin') + const newLink = join(modules, 'a-new-plugin') + const replacement = join(f.root, 'work', 'replacement') + const rejectedTarget = join(f.root, 'work', 'rejected-target') + const acceptedTarget = join(f.root, 'work', 'accepted-target') + for (const [dir, name, marker] of [ + [replacement, 'my-plugin', 22], + [rejectedTarget, 'a-new-plugin', 31], + [acceptedTarget, 'a-new-plugin', 32], + ] as const) { + pkg(dir, name, 0, {}, { [peer]: '*' }) + pkg(join(dir, 'node_modules', peer), peer, marker) + } + const require = createRequire(join(linkedRoot, 'entry.cjs')) + const parent = pathToFileURL(join(linkedRoot, 'entry.mjs')).href + const first = await resolutionOf(f) + expect(first.localPackageNames).toEqual([]) + const registration = installRuntimeInterception(first) + registrations.push(registration) + try { + expectPeerLookup(registration, require, parent, f.installed) + unlinkSync(originalLink) + const removed = await resolutionOf(f) + expect(removed.linkedRoots).toEqual([]) + registration.replace(removed) + expectPeerLookup(registration, require, parent, join(linkedRoot, 'node_modules', peer)) + + const linkType = process.platform === 'win32' ? 'junction' : 'dir' + symlinkSync(replacement, originalLink, linkType) + symlinkSync(rejectedTarget, newLink, linkType) + const rejected = await resolutionOf(f) + expect(rejected.linkedRoots).toEqual([ + { name: 'a-new-plugin', realPath: rejectedTarget }, + { name: 'my-plugin', realPath: replacement }, + ]) + expect(() => { registration.replace(rejected) }) + .toThrow(/^profile resolution: relinking "my-plugin" requires a process restart$/u) + expectPeerLookup(registration, require, parent, join(linkedRoot, 'node_modules', peer)) + expectPeerLookup(registration, createRequire(join(rejectedTarget, 'entry.cjs')), + pathToFileURL(join(rejectedTarget, 'entry.mjs')).href, join(rejectedTarget, 'node_modules', peer)) + + unlinkSync(originalLink) + unlinkSync(newLink) + symlinkSync(acceptedTarget, newLink, linkType) + const accepted = await resolutionOf(f) + expect(accepted.linkedRoots).toEqual([{ name: 'a-new-plugin', realPath: acceptedTarget }]) + registration.replace(accepted) + expectPeerLookup(registration, createRequire(join(acceptedTarget, 'entry.cjs')), + pathToFileURL(join(acceptedTarget, 'entry.mjs')).href, f.installed) + expectPeerLookup(registration, require, parent, join(linkedRoot, 'node_modules', peer)) + } finally { + registration.dispose() + registrations.pop() + } + }) + }) + it.each(['src', 'dist'] as const)( 'keeps intermediate %s/node_modules ahead of linked-root peers and ancestor packages', async (directory) => { const { f, linkedRoot } = linkedPluginFixture()