@avernet-plugin/deepseek-harness-channel-bcn 0.1.0 → 0.2.1

package/README.md

@@ -3,25 +3,44 @@
 DeepSeek Harness channel bundle for connecting a DSH Bot to the Avernet Bot
 Collaboration Network (BCN).
 
+## 0.2.1
+
+Fix approval and question routing for BCN-owned Agents when the DSH Web UI is
+also enabled. BCN interaction handlers now run before the Web UI fallback, so
+pending requests reach BCN instead of waiting only in the native Web UI.
+Other Agents retain their existing interaction handlers.
+
 ## Compatibility
 
-- DeepSeek Harness baseline: `@deepseek-ai/dsh 0.1.1-rc.2`
-- BCN Bot WebSocket protocol: V2
+- DeepSeek Harness declared compatibility: `>=0.2.0-rc.2 <=0.2.1-alpha.2`
+- DeepSeek Harness development/test baseline: `@deepseek-ai/dsh 0.2.1-alpha.2`
+- BCN Bot WebSocket protocol: V3
 - Node.js: `>=22.19.0`
 
-This release deliberately negotiates BCN V2. Because V2 `session_key` can be
-shared by every conversation in a group, the adapter uses the session-scoped
-V2 `bcs_group_id` as the DSH identity when present and falls back to
-`session_key` only for legacy group frames. A future V3 `bcs_session_id` takes
-precedence without changing the rest of the bridge.
+This release requires BCN V3. Every `chat.send` and `chat.inject` must carry the canonical
+`bcs_session_id`; uplink events use the shared Run Event envelope with
+`runId`, `sessionId`, `seq`, and `ts`. The adapter still keeps the historical
+session-key mapping helper for persisted sessions created by older releases.
 
 ## Capabilities
 
-- Automatic registration and descriptor onboarding through DSH Credentials
+First-time setup exchanges the human Token through `POST /register`. That
+endpoint creates the Bot and establishes its display name and ownership. On
+restart, the plugin reuses the saved Bot Session and connects directly to
+`/ws/bot`; it does not re-register or require a separate `/bots/onboard` call.
+
+Current registration only publishes the Bot name and ownership. The configured
+`summary`, `domains`, `skills`, and `scopes` are not synchronized by this plugin;
+do not rely on these settings for skill-based discovery. Descriptor synchronization
+and propagation of server-side onboarding persistence failures require a separate
+registration contract update. A successful `/register` response currently cannot
+prove that the server persisted its optional descriptor.
+
+- Automatic registration and persistent Bot credentials through DSH Credentials
 - Persistent Bot Session storage through the official `ctx.credentials` seam
-- `chat.send` and `chat.inject` downlink handling
+- `chat.send`, `chat.inject`, and exact-run `chat.abort` downlink handling
 - Isolated DSH Agent/Session reuse for each BCN conversation, including
-  multiple V2 sessions that share one group-level `session_key`
+  multiple sessions that share one group-level `session_key`
 - DSH Agent preset composition matching Web sessions; new BCN sessions use the
   configured default preset and resumed sessions restore their recorded preset
 - Assistant delta, final, error, and aborted uplink events
@@ -31,14 +50,44 @@ precedence without changing the rest of the bridge.
 - `bcs_route` capture with routing metadata attached to the final chat event
 - Manager-worker `task.dispatch`, `task.message`, and `task.complete` support
 - Heartbeat, exponential reconnect, token rotation, and lifecycle cleanup
+- Agent-scoped execution approvals and structured questions through BCN
+  `interaction` events and authenticated `interaction.resolve` requests
 
 The plugin does not create an OpenClaw-style `.bcs/session.json` file or any
 other private session directory.
 
-The initial release does not implement `chat.abort` or `chat.history`.
+This release does not implement `chat.history`.
 Unsupported BCN requests receive the WebSocket client's standard `NOT_FOUND`
 response, and unsolicited unsupported events are ignored.
 
+`chat.abort` requires `session_key` (the canonical BCN session ID) and
+`run_id`. It cancels only that run: pending agent creation cannot deliver after
+the abort, queued input is removed by message ID, and active turns use
+`cancel({ kind: 'user' }, { keepInbox: true })`. Other queued runs survive.
+Repeated aborts acknowledge an empty `aborted_run_ids`; unknown runs and
+cross-session requests fail. Terminal events are emitted once.
+
+DSH 0.2 uses scoped live events and V4 tool-result messages. This adapter
+subscribes in each owned Agent's setup, reads tool identity from the message's
+top-level `toolCallId`, and never subscribes to replayed history. Assistant
+text is forwarded as deltas after each durable `assistant/message` commit,
+including interrupted prefixes. Failed/retried `assistant/attempt` output and
+raw reasoning are excluded; this deliberately buffers text until a step
+commits because BCN's append-only delta stream cannot retract a failed attempt.
+The scoped `agent/assistant-stream` feed retains only the current attempt's
+visible text so an explicit abort can preserve its partial answer.
+The historical `bcn-v2-*` DSH session IDs remain unchanged. DSH's own storage
+migration handles old session formats; the plugin never rewrites session logs.
+
+Execution approvals offer only `allow_once` and `deny`. Question options use
+their DSH labels as wire values; free-text answers return as `custom`.
+Cancellation and unload settle pending waits without granting approval.
+Timed questions attach to DSH's official foreground wait and respect its
+remaining duration. Late answers after that foreground wait closes are not
+accepted by this adapter. Mode-switch interactions are not implemented.
+These hooks are installed only on BCN-owned Agents and do not intercept Web
+sessions or subagents.
+
 BCN messages run in a dedicated in-process DSH Agent created through
 `ctx.agents.create` or restored through `ctx.agents.resume`; they do not reuse a
 browser tab's live Agent. The plugin mounts that session's DSH Agent preset
@@ -57,6 +106,9 @@ The manager/worker decision uses only the server-delivered
 participants, environment variables, or model input. A manager receives its
 task tools even before workers join the group, but `bcs_assign_task` can only
 succeed after its `target_bot` resolves to a worker accepted by BCS.
+Task RPCs carry the canonical `group:session` identity in their existing
+`group_id` wire field, which BCS unwraps into group and conversation scope.
+They do not fall back to a shared group's default conversation.
 
 With DSH's default `standard` preset the base tool set includes the Bash,
 filesystem, search, Skills, planning, subagent, and workflow capabilities
@@ -71,13 +123,29 @@ After this package is published, install, configure, and start a DSH profile
 with the repository installer:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/inclusionAI/Avernet/dev/src/bcs/crates/plugins/deepseek-harness-channel-bcn/install-dsh.sh | \
+curl -fsSL https://raw.githubusercontent.com/inclusionAI/Avernet/dev/apps/bcs/crates/plugins/deepseek-harness-channel-bcn/install-dsh.sh | \
   BCN_ONBOARDING_TOKEN='<registration-token>' bash -s -- \
     --endpoint http://127.0.0.1:21000/ \
     --profile web \
     --bot-name 'DeepSeek Harness Bot'
 ```
 
+The installer first checks whether the `dsh` executable is available. If it is
+missing, it exits without consuming the registration Token and prints the
+matching CLI installation command:
+
+```bash
+npm install --global @deepseek-ai/dsh@0.2.1-alpha.2
+```
+
+Run the generated onboarding command again after installing the CLI. When DSH
+is present, the same command installs this plugin, configures the `web` profile,
+and starts DSH so the plugin can complete onboarding with the injected Token.
+The DSH plugin manager checks the peer compatibility range declared in this
+package (`>=0.2.0-rc.2 <=0.2.1-alpha.2`) before activation. Existing
+`0.1.1-rc.2` installations must be upgraded first. Development dependencies
+remain pinned to `0.2.1-alpha.2` so builds and unit tests remain reproducible.
+
 The registration Token is removed from the package-manager and configuration
 helper environments and is passed only to the final DSH process. The installer
 does not print or persist it. If the command is generated by a trusted BCN
@@ -100,7 +168,7 @@ From a checkout, build the package and add its directory to an isolated DSH
 profile:
 
 ```bash
-cd src/bcs/crates/plugins/deepseek-harness-channel-bcn
+cd apps/bcs/crates/plugins/deepseek-harness-channel-bcn
 npm install --ignore-scripts --no-package-lock
 npm run build
 dsh plugin --profile bcn-local add "$(pwd)"
@@ -111,13 +179,13 @@ To exercise the exact prebuilt artifact that will be published:
 ```bash
 mkdir -p /tmp/dsh-bcn-pack
 npm pack --pack-destination /tmp/dsh-bcn-pack
-dsh plugin --profile bcn-tarball add /tmp/dsh-bcn-pack/avernet-plugin-deepseek-harness-channel-bcn-0.1.0.tgz
+dsh plugin --profile bcn-tarball add /tmp/dsh-bcn-pack/avernet-plugin-deepseek-harness-channel-bcn-0.2.1.tgz
 ```
 
 After publication, the installation command will be:
 
 ```bash
-dsh plugin --profile <profile> add @avernet-plugin/deepseek-harness-channel-bcn
+dsh plugin --profile <profile> add @avernet-plugin/deepseek-harness-channel-bcn@0.2.1
 ```
 
 The bundle patch adds the plugin in a disabled state, so installing it never
@@ -212,14 +280,14 @@ sends:
 - assistant-visible text and final routing metadata.
 
 Calls to `bcs_assign_task`, `bcs_send_task_message`, and `bcs_task_complete`
-use the existing BCN V2 `task.dispatch`, `task.message`, and `task.complete`
+use the existing BCN `task.dispatch`, `task.message`, and `task.complete`
 requests. Their arguments and model-visible results also appear through the
 same canonical `agent/tool` telemetry as other DSH tools.
 
 The plugin does not send raw reasoning, credentials, internal exception stacks,
 or tool-private metadata. Tool arguments and results are not copied into normal
 plugin logs. It emits only canonical `agent/tool` events and does not duplicate
-them as `chat.event tool_call_start/tool_call_end` events.
+them as legacy `chat.event tool_call_start/tool_call_end` events.
 
 ## Verify
 

package/dist/bridge.d.ts

@@ -1,9 +1,19 @@
 import type { Context } from '@deepseek-ai/cordis';
 import { type Agent } from '@deepseek-ai/dsh-agent';
-import type { JsonValue } from '@deepseek-ai/dsh-session';
 import type { Config } from './config.js';
 import { type RouteSelector } from './protocol.js';
 import type { BcnWsClient } from './ws-client.js';
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** @persistenceAttribution */
+        'bcn-channel': {
+            kind: 'bcn-channel';
+        };
+    }
+}
 export declare class BcnBridge {
     private readonly ctx;
     private readonly client;
@@ -19,6 +29,7 @@ export declare class BcnBridge {
     private completedRunIds;
     private disposers;
     private disposed;
+    private interactions;
     constructor(ctx: Context, client: BcnWsClient, config: Config, log?: {
         info(message: string): void;
         warn(message: string): void;
@@ -34,9 +45,11 @@ export declare class BcnBridge {
     completeTask(agent: Agent | undefined, summary: string, signal: AbortSignal): Promise<JsonValue>;
     private handleChatSend;
     private handleChatInject;
+    private handleChatAbort;
     private handleInboxClaimed;
     private handleInboxDiscarded;
     private handleSessionEvent;
+    private handleAssistantStream;
     private appendDelta;
     private captureAssistantMessage;
     private captureToolCall;
@@ -48,4 +61,5 @@ export declare class BcnBridge {
     private activeRunForTaskTool;
     private sendTaskRequest;
 }
+export {};
 //# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAEL,KAAK,KAAK,EAGX,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,SAAS,EAAmD,MAAM,0BAA0B,CAAC;AAE3G,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAYL,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AAQvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAuDlD,qBAAa,SAAS;IAalB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;IAfvB,OAAO,CAAC,aAAa,CAA4C;IACjE,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,0BAA0B,CAA6B;IAC/D,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,oBAAoB,CAA6B;IACzD,OAAO,CAAC,IAAI,CAAiC;IAC7C,OAAO,CAAC,eAAe,CAAgB;IACvC,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,QAAQ,CAAS;gBAGN,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE;QACrB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,YAAA;IAGH,KAAK,IAAI,IAAI;IAUb,IAAI,IAAI,IAAI,OAAO,CAGlB;IAEK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBxB,YAAY,CAChB,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,SAAS,EAAE,aAAa,EAAE,EAC1B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,SAAS,CAAC;IAuDf,UAAU,CACd,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,SAAS,CAAC;IA8Bf,eAAe,CACnB,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,SAAS,CAAC;IAef,YAAY,CAChB,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,SAAS,CAAC;YAcP,cAAc;YAqDd,gBAAgB;IAgC9B,OAAO,CAAC,kBAAkB;IAW1B,OAAO,CAAC,oBAAoB;IAS5B,OAAO,CAAC,kBAAkB;IA6C1B,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,uBAAuB;IAoB/B,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,YAAY;YAsCN,gBAAgB;YAiBhB,WAAW;IAkDzB,OAAO,CAAC,oBAAoB;YAUd,eAAe;CAgC9B"}
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAEL,KAAK,KAAK,EAIX,MAAM,wBAAwB,CAAC;AAIhC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAYL,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AAQvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAIlD,KAAK,SAAS,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAE/F,OAAO,QAAQ,sBAAsB,CAAC;IACpC,UAAU,gBAAgB;QACxB,8BAA8B;QAC9B,aAAa,EAAE;YAAE,IAAI,EAAE,aAAa,CAAA;SAAE,CAAC;KACxC;CACF;AAwDD,qBAAa,SAAS;IAclB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;IAhBvB,OAAO,CAAC,aAAa,CAA4C;IACjE,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,0BAA0B,CAA6B;IAC/D,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,oBAAoB,CAA6B;IACzD,OAAO,CAAC,IAAI,CAAiC;IAC7C,OAAO,CAAC,eAAe,CAAgB;IACvC,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAAkB;gBAGnB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE;QACrB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,YAAA;IASH,KAAK,IAAI,IAAI;IASb,IAAI,IAAI,IAAI,OAAO,CAGlB;IAEK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAuBxB,YAAY,CAChB,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,SAAS,EAAE,aAAa,EAAE,EAC1B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,SAAS,CAAC;IAuDf,UAAU,CACd,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,SAAS,CAAC;IAgCf,eAAe,CACnB,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,SAAS,CAAC;IAef,YAAY,CAChB,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,SAAS,CAAC;YAcP,cAAc;YAiEd,gBAAgB;YAiChB,eAAe;IA8B7B,OAAO,CAAC,kBAAkB;IAW1B,OAAO,CAAC,oBAAoB;IAS5B,OAAO,CAAC,kBAAkB;IAuC1B,OAAO,CAAC,qBAAqB;IAgB7B,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,uBAAuB;IAoB/B,OAAO,CAAC,eAAe;IA4BvB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,YAAY;YAuDN,gBAAgB;YAiBhB,WAAW;IAkEzB,OAAO,CAAC,oBAAoB;YAUd,eAAe;CAgC9B"}