@khorsheed/dsh-local-agent 0.2.0-rc.1 → 0.2.0

package/lib/types/index.js

@@ -30,6 +30,7 @@ import { appendFileSync, chmodSync, mkdirSync, readFileSync, statSync } from 'no
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import z from '@deepseek-ai/schemastery';
+import * as sessionModule from '@deepseek-ai/dsh-session';
 import { SessionId } from '@deepseek-ai/dsh-session';
 // The durable reader validates plugin vocabulary before replay. Register in
 // both resolution planes: source-based host toolchains and installed bundles
@@ -46,6 +47,7 @@ for (const catalog of streamCatalogs) {
 }
 import LocalAgentGateway from './gateway.js';
 import { MemberChannel } from './member-channel.js';
+import { PresetToolHost } from './preset-tool-host.js';
 import { MemberInbox } from './member-inbox.js';
 import { PreparedMembers } from './prepared-members.js';
 import { MemberControls } from './member-controls.js';
@@ -56,6 +58,7 @@ export const name = 'local-agent';
 export const inject = ['commands'];
 export { delegationEnv } from './env.js';
 export { ModelDirectoryCache, extendModelDirectory, modelDirectoryContextKey } from './model-directory.js';
+export { MODEL_LIST_FILE, firstModelOf, normalizeModelList, readModelList, readModelListSync, writeModelList } from './model-list.js';
 export { MemberConfigurationController } from './member-control.js';
 export { FileMemberControlStorage } from './member-control-storage.js';
 export { LiveFlush, LIVE_FLUSH_INTERVAL_MS } from './live-flush.js';
@@ -318,12 +321,43 @@ function delegationIntentKey(parentSessionId, provider) {
  * `cancel()` and the caller's own abort channel both reach the run.
  * `AbortSignal.any` is the harness's own fusion primitive (agent-loop's resume
  * uses it); either source aborts the run.
+ *
+ * Host 0.2.1 note: the fused signal reaches `startActivation`'s `spec.signal`,
+ * which owns cancellation only up to publication — after the activation is
+ * published the manager unlinks it and `dispose()` is the sole cancel channel.
+ * {@link activationRun} therefore re-wires the caller signal to disposal.
  */
 function fusedSignal(controller, caller) {
     if (caller === undefined)
         return controller.signal;
     return AbortSignal.any([controller.signal, caller]);
 }
+/**
+ * Adapt a 0.2.1 managed activation to the family's published `SubagentRun`
+ * shape. The adapter's `id` is the dsh child session id — the family's
+ * tracking key, resume handle, and client-facing identity — NOT the
+ * activation's `childId`, which for an external (CLI) provider is the
+ * provider's per-execution id and never names the mirrored live Session.
+ * `dispose()` is the activation's exact-epoch cancellation: it settles the
+ * result with an `aborted`-class stop reason and runs teardown, so a caller
+ * signal aborted mid-run is re-wired to it (the start signal the facade fused
+ * is unlinked by the manager at publication). The listener detaches when the
+ * result settles, so a long-lived caller signal never accumulates them.
+ */
+function activationRun(activation, childSessionId, caller, warn) {
+    const dispose = () => activation.dispose();
+    if (caller !== undefined) {
+        const onAbort = () => {
+            void dispose().catch((error) => {
+                warn(`localAgent: caller-signal disposal of ${childSessionId} failed: ${String(error)}`);
+            });
+        };
+        caller.addEventListener('abort', onAbort, { once: true });
+        const detach = () => { caller.removeEventListener('abort', onAbort); };
+        void activation.result.then(detach, detach);
+    }
+    return { id: SessionId(childSessionId), result: activation.result, dispose };
+}
 /**
  * The per-harness append-only delegation-mapping log inside the harness's
  * scoped home (`<homeDir>/<harness>/delegations.jsonl`): one JSON record per
@@ -508,6 +542,11 @@ export function parseScopeFlag(input) {
     }
     return { input: rest.join(' ').trim(), ...scope === undefined ? {} : { scope } };
 }
+/** A delegation record without its requested model. */
+function withoutModel(record) {
+    const { model: _model, ...rest } = record;
+    return rest;
+}
 /** Map a login failure to a command error, naming the swallowed signal. */
 function loginFailure(harness, exitCode, signal) {
     return `${harness.name} login exited with ${signal ?? `code ${exitCode ?? 'unknown'}`}; try /${harness.name} login again.`;
@@ -666,9 +705,9 @@ export class LocalAgentRegistry {
     /**
      * Per-(parent session, provider) FIFO of delegation intents. The family
      * resume tool stages exactly one intent per call before awaiting
-     * `ctx.subagents.start()`, and the owning provider consumes exactly one per
-     * start, so fresh and resume rounds stay paired even under parallel
-     * delegations from one parent.
+     * `ctx.subagents.startActivation()`, and the owning provider consumes
+     * exactly one per start, so fresh and resume rounds stay paired even under
+     * parallel delegations from one parent.
      */
     delegationIntents = new Map();
     /**
@@ -721,10 +760,12 @@ export class LocalAgentRegistry {
      * - **facade-tracked** ({@link trackRun}): runs started through
      *   {@link LocalAgentRegistry.start} / {@link LocalAgentRegistry.resume},
      *   carrying the fused AbortController whose signal reached
-     *   `ctx.subagents.start`; cancel aborts it.
+     *   `ctx.subagents.startActivation`; cancel aborts the pre-publication
+     *   signal and disposes the published activation.
      * - **tool-registered** ({@link trackDelegationRun}): runs the family tool
-     *   starts directly through `ctx.subagents.start`, carrying an explicit
-     *   cancel lever (its fused controller); cancel calls it.
+     *   starts directly through `ctx.subagents.startActivation`, carrying an
+     *   explicit cancel lever (its fused controller plus the activation's
+     *   dispose); cancel calls it.
      *
      * Every entry clears itself when the run's result settles (any stop
      * reason), and facade entries also stop their heartbeat timer then.
@@ -1137,7 +1178,12 @@ export class LocalAgentRegistry {
         const binding = this.memberControls.binding(record.childSessionId);
         if (binding !== undefined)
             record = {
-                ...record,
+                // The model a resume re-requests is the bound one, verbatim: a provider
+                // recording its resolved model ('opus' → 'claude-opus-5-5', or the
+                // default a model-less start resolved to) would make the next round's
+                // binding differ and the member refuse it ("identity changed: model").
+                ...withoutModel(record),
+                ...binding.model === undefined ? {} : { model: binding.model },
                 ...binding.effort === undefined ? {} : { effort: binding.effort },
                 ...binding.configurationLock === undefined ? {} : { configurationLock: binding.configurationLock },
             };
@@ -1186,9 +1232,10 @@ export class LocalAgentRegistry {
     /**
      * Stage one delegation intent for a provider's next `start()`. The family
      * resume tool stages exactly one intent per call before awaiting
-     * `ctx.subagents.start()`; the provider consumes exactly one per start via
-     * {@link takeDelegationIntent}, so the per-(parent, provider) FIFO pairs
-     * fresh and resume rounds even under parallel delegations from one parent.
+     * `ctx.subagents.startActivation()`; the provider consumes exactly one per
+     * start via {@link takeDelegationIntent}, so the per-(parent, provider)
+     * FIFO pairs fresh and resume rounds even under parallel delegations from
+     * one parent.
      * @param parentSessionId - the delegating parent session id.
      * @param provider - the `ctx.subagents` provider name.
      * @param intent - the fresh or resume intent for the next start.
@@ -1222,7 +1269,7 @@ export class LocalAgentRegistry {
     }
     /**
      * Remove one previously staged intent by reference, returning whether it was
-     * still queued. The delegation facade calls this when `ctx.subagents.start()`
+     * still queued. The delegation facade calls this when `ctx.subagents.startActivation()`
      * throws: an intent the provider never consumed must not linger in the FIFO,
      * where the NEXT same-(parent, provider) start would misconsume it as its own
      * (orphan-intent crosstalk). When the provider already consumed the intent
@@ -1248,9 +1295,7 @@ export class LocalAgentRegistry {
         return true;
     }
     /**
-     * Every recorded delegation, in recording order. The invariant companion
-     * cross-checks each record's provider against the mounted subagent
-     * providers so a provider rename cannot leave a stale resume mapping.
+     * Every recorded delegation, in recording order.
      * @returns the recorded delegations.
      */
     listDelegations() {
@@ -1554,7 +1599,9 @@ export class LocalAgentRegistry {
      * {@link unstageDelegationIntent} (a no-op once the provider consumed it).
      *
      * The returned run is tracked under its `run.id` (== the new dsh child
-     * session id) until `run.result` settles; {@link cancel} aborts it by that
+     * session id, minted here and carried to the provider through the staged
+     * intent — host 0.2.1's `startActivation` never surfaces it on the
+     * activation) until `run.result` settles; {@link cancel} aborts it by that
      * id. Note on trust: cordis plugins share one process, so the ownership
      * checks here and in {@link resume} guard against caller MISTAKES, not
      * against a malicious plugin — their real protection target is untrusted
@@ -1588,13 +1635,21 @@ export class LocalAgentRegistry {
         const subagents = this.requireSubagents();
         this.requireProvider(subagents, provider);
         const parent = this.requireLiveParent(parentSessionId);
+        // The durable child identity is caller-minted here: host 0.2.1 activations
+        // forbid a provider run id that names a live Session (the manager rejects
+        // it as DUPLICATE_CHILD), so the provider's returned run carries a
+        // per-execution id and the child session id rides the staged intent — the
+        // same channel the prepared-member path already used for it.
+        const childSessionId = prepared?.binding.childSessionId ?? randomUUID();
         // The cwd override rides the staged intent, not the host seam (the
-        // SubagentStartRequest contract has no cwd field and must not grow one):
-        // the provider consumes it as the resolveChildCwd override.
+        // SubagentStartRequest contract's cwd is the manager-resolved directory,
+        // not the family's resolveChildCwd override): the provider consumes it as
+        // the resolveChildCwd override.
         const intent = {
             kind: 'fresh',
             ...options?.onAdmitted === undefined ? {} : { onAdmitted: options.onAdmitted },
             ...options?.preparedMemberId === undefined ? {} : { preparedMemberId: options.preparedMemberId },
+            ...prepared === undefined ? { childSessionId } : {},
             ...options?.cwd === undefined ? {} : { cwd: options.cwd },
             // The container exec target rides the same channel for the same
             // reason: it is a family-private start fact, and the host
@@ -1615,18 +1670,25 @@ export class LocalAgentRegistry {
         const controller = new AbortController();
         let run;
         try {
-            run = await subagents.start(provider, {
-                prompt,
-                parent,
+            // Caller delivery: the family collects the result itself and pushes it
+            // through its own Remote; the parent agent gets no completion notice.
+            // The activation spec's label is required, so the absent-description
+            // case rides through as the empty string, which the provider's label
+            // composition reads as "no description" (the harness display name wins).
+            const activation = await subagents.startActivation({
+                provider,
+                label: options?.label ?? '',
+                request: { prompt, parent },
                 signal: fusedSignal(controller, options?.signal),
-                ...options?.label === undefined ? {} : { label: options.label },
+                delivery: 'caller',
             });
+            run = activationRun(activation, childSessionId, options?.signal, message => this.ctx.logger.warn(message));
         }
         catch (error) {
             this.unstageDelegationIntent(parentSessionId, provider, intent);
             throw error;
         }
-        this.trackRun(run.id, controller, run, options?.onProgress);
+        this.trackRun(childSessionId, controller, run, options?.onProgress);
         if (prepared !== undefined) {
             try {
                 this.preparedMembers.write({ ...prepared, phase: 'used' });
@@ -1652,12 +1714,12 @@ export class LocalAgentRegistry {
      *    without staging; the provider still takes the authoritative lock inside
      *    its `start()`;
      * 4. live parent agent resolution (`ctx.agents.get`) — a harness hard
-     *    constraint, since `ctx.subagents.start` requires a live parent;
+     *    constraint, since `ctx.subagents.startActivation` requires a live parent;
      * 5. child-session REATTACH when `ctx.sessions.get(childSessionId)` is
      *    undefined (recipe below; `opts.reattach === false` disables this step
      *    and fails loud on a non-live child instead);
      * 6. stage `{ kind: 'resume', childSessionId, cliSessionId }` and, in the
-     *    same synchronous flow, `await ctx.subagents.start(provider, …)`;
+     *    same synchronous flow, `await ctx.subagents.startActivation({…})`;
      * 7. on start failure, roll the intent back via
      *    {@link unstageDelegationIntent} (no-op once consumed);
      * 8. on success, track the run under `childSessionId` for {@link cancel}
@@ -1670,8 +1732,12 @@ export class LocalAgentRegistry {
      * const handle = await ctx.sessionPersistence.open(SessionId(childSessionId), 'write')
      * try {
      *   const cold = await handle.read(0)
+     *   // Close a turn a restart interrupted, or the next round's turn/start
+     *   // makes the stored log unreadable.
+     *   const closers = interruptedTurnClosers(cold.events)
+     *   if (closers.length > 0) await handle.append(closers)
      *   const session = ctx.sessions.prepare(SessionId(childSessionId), {
-     *     seed: [...cold.events],
+     *     seed: [...cold.events, ...closers],
      *     meta: structuredClone(handle.header),
      *     inheritedEventCount: handle.inheritedEventCount,
      *     eventState: cold.eventState,
@@ -1679,7 +1745,7 @@ export class LocalAgentRegistry {
      *   // The seeded constructor's session/end-seed marker lands before enter()
      *   // installs publication hooks — push the unstored suffix through the
      *   // handle directly, or the writer's contiguous cursor diverges.
-     *   const unstored = session.snapshotEvents().slice(cold.events.length)
+     *   const unstored = session.snapshotEvents().slice(cold.events.length + closers.length)
      *   if (unstored.length > 0) await handle.append(unstored)
      *   const detach = ctx.sessions.enter(session)
      *   try { ctx.sessions.announce(session) }
@@ -1766,12 +1832,18 @@ export class LocalAgentRegistry {
         const controller = new AbortController();
         let run;
         try {
-            run = await subagents.start(provider, {
-                prompt,
-                parent,
+            // Caller delivery (see start): the family self-collects the result and
+            // pushes it through its own Remote; the resumed child session id stays
+            // the tracking key while the activation carries the provider's
+            // per-execution id.
+            const activation = await subagents.startActivation({
+                provider,
+                label: options?.label ?? '',
+                request: { prompt, parent },
                 signal: fusedSignal(controller, options?.signal),
-                ...options?.label === undefined ? {} : { label: options.label },
+                delivery: 'caller',
             });
+            run = activationRun(activation, childSessionId, options?.signal, message => this.ctx.logger.warn(message));
         }
         catch (error) {
             this.unstageDelegationIntent(parentSessionId, provider, intent);
@@ -1781,11 +1853,12 @@ export class LocalAgentRegistry {
         return run;
     }
     /**
-     * Cancel an in-flight facade-started run by its dsh child session id: aborts
-     * the internal controller whose (fused) signal was passed to
-     * `ctx.subagents.start`, which is the canonical cancellation channel for a
-     * one-shot run. The provider settles the run with an `aborted`-class stop
-     * reason. A caller holding the `SubagentRun` may also `run.dispose()`.
+     * Cancel an in-flight facade-started run by its dsh child session id:
+     * aborts the internal controller (the pre-publication channel fused into
+     * the activation's start signal) and disposes the activation — host 0.2.1's
+     * canonical POST-publication cancellation, which settles the run with an
+     * `aborted`-class stop reason. A caller holding the `SubagentRun` may also
+     * `run.dispose()`.
      * @param childSessionId - the dsh child session id of the run to cancel.
      * @returns whether an in-flight run was found and signalled (false on a
      *   miss — never a silent success, never a throw).
@@ -1796,10 +1869,17 @@ export class LocalAgentRegistry {
             return this.memberInbox.cancelStarting(childSessionId);
         if (entry.controller !== undefined) {
             entry.controller.abort();
+            // The start signal is unlinked at publication, so disposal is the lever
+            // that actually reaches a running round. Idempotent and memoized by the
+            // manager; a teardown failure is reported, never thrown from here.
+            void entry.run.dispose().catch((error) => {
+                this.ctx.logger.warn(`localAgent: cancel disposal of ${childSessionId} failed: ${String(error)}`);
+            });
         }
         else {
             // Tool-registered run: the caller-supplied cancel lever (its fused
-            // controller), the same abort channel the facade entry aborts.
+            // controller plus the activation's dispose), the same channels the
+            // facade entry drives.
             entry.cancel?.();
         }
         return true;
@@ -1808,16 +1888,17 @@ export class LocalAgentRegistry {
      * Register a NON-facade in-flight delegation run with the active-delegation
      * registry, keyed by the dsh child session id, so the `/local-agent stop`
      * command and {@link cancel} can reach it. This is the family TOOL's entry
-     * point: the tool starts its runs through `ctx.subagents.start` directly
-     * (not the facade), so without this registration its in-flight runs would
-     * be invisible to the stop command. The caller owns the cancel lever — a
-     * controller fused with the run's request signal, aborted exactly like the
-     * facade's tracked controller. The entry clears itself when the run's
-     * result settles (any stop reason); an existing facade entry for the same
-     * child session wins (it already owns cancellation and progress).
-     * @param childSessionId - the dsh child session id (the run id).
-     * @param run - the published subagent run.
-     * @param cancel - the lever that aborts the run's request signal.
+     * point: the tool starts its runs through `ctx.subagents.startActivation`
+     * directly (not the facade), so without this registration its in-flight
+     * runs would be invisible to the stop command. The caller owns the cancel
+     * lever — aborting the fused controller (pre-publication) and disposing the
+     * activation (post-publication), the same channels the facade drives. The
+     * entry clears itself when the run's result settles (any stop reason); an
+     * existing facade entry for the same child session wins (it already owns
+     * cancellation and progress).
+     * @param childSessionId - the dsh child session id.
+     * @param run - the published subagent run (the tool's activation adapter).
+     * @param cancel - the lever that cancels the run.
      */
     trackDelegationRun(childSessionId, run, cancel) {
         if (this.runs.has(childSessionId))
@@ -1917,7 +1998,7 @@ export class LocalAgentRegistry {
      * from persistence when it is not — a host restart evicts every child from
      * the live store. This is the public entry of the facade resume's reattach
      * recipe for callers that start resume rounds WITHOUT the facade (the
-     * family subagent tool starts runs directly through `ctx.subagents.start`;
+     * family subagent tool starts runs directly through `ctx.subagents.startActivation`;
      * without this call the provider refuses the resume as "not live").
      * Idempotent; a child that was never persisted fails through the
      * persistence layer's own not-found error.
@@ -1954,8 +2035,18 @@ export class LocalAgentRegistry {
         const handle = await this.acquireChildWriteHandle(childSessionId);
         try {
             const cold = await handle.read(0);
+            // A host restart mid-round leaves the child's last turn open on disk;
+            // the next round's turn/start would then follow an unclosed turn and
+            // the strict reader rejects the whole log. Close it the way the agent
+            // loop's own resume does: synthetic closers (missing tool errors,
+            // step/end, an `interrupted` turn/end) appended through the handle.
+            // Older hosts without the helper keep the previous behavior.
+            const closeOpenTurn = sessionModule.interruptedTurnClosers;
+            const closers = closeOpenTurn === undefined ? [] : closeOpenTurn(cold.events);
+            if (closers.length > 0)
+                await handle.append(closers);
             const session = sessions.prepare(SessionId(childSessionId), {
-                seed: [...cold.events],
+                seed: [...cold.events, ...closers],
                 meta: structuredClone(handle.header),
                 inheritedEventCount: handle.inheritedEventCount,
                 eventState: cold.eventState,
@@ -1965,7 +2056,7 @@ export class LocalAgentRegistry {
             // — push the unstored suffix through the handle directly (the agent
             // loop's resume does the same via appendUnstoredSuffix), or the writer's
             // contiguous cursor and the session log diverge.
-            const unstored = session.snapshotEvents().slice(cold.events.length);
+            const unstored = session.snapshotEvents().slice(cold.events.length + closers.length);
             if (unstored.length > 0)
                 await handle.append(unstored);
             const detach = sessions.enter(session);
@@ -2000,20 +2091,48 @@ export class LocalAgentRegistry {
      * @param session - the live child session to sync.
      */
     async syncChildSession(session, strict = false) {
+        const id = String(session.id);
         try {
-            const handle = await this.acquireChildWriteHandle(String(session.id), session.header);
-            const stored = await handle.read(0);
-            const suffix = session.snapshotEvents().slice(stored.events.length);
-            if (suffix.length > 0)
-                await handle.append(suffix);
-            await handle.flush();
+            try {
+                await this.syncChildSessionOnce(session);
+            }
+            catch (error) {
+                if (!/append seq mismatch/.test(error instanceof Error ? error.message : String(error)))
+                    throw error;
+                // A routed live buffer the explicit suffix raced (see
+                // syncChildSessionOnce) stays poisoned for the handle's lifetime:
+                // drop the handle with it and catch up from disk on a fresh one.
+                await this.releaseChildWriteHandle(id);
+                await this.syncChildSessionOnce(session);
+            }
         }
         catch (error) {
             if (strict)
                 throw error;
-            this.ctx.logger.warn(`localAgent: syncing child session ${String(session.id)} to persistence failed: ${error instanceof Error ? error.message : String(error)}`);
+            this.ctx.logger.warn(`localAgent: syncing child session ${id} to persistence failed: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * One sync pass. While the write handle is open the host routes every live
+     * append into the writer's buffer, so the routed events are drained first
+     * (`sessions.flush`: drain + flush) and only what is STILL missing — events
+     * from before the handle opened, or a host that routes nothing — goes in
+     * explicitly, bounded to the events that existed before the drain. Appending
+     * routed-but-undrained events explicitly as well would land them twice: the
+     * explicit write wins, the buffered copy then fails contiguity forever, and
+     * every later flush — the host's tool-execution checkpoint included —
+     * throws "append seq mismatch".
+     */
+    async syncChildSessionOnce(session) {
+        const handle = await this.acquireChildWriteHandle(String(session.id), session.header);
+        const known = session.snapshotEvents().length;
+        await this.ctx.get('sessions')?.flush(session);
+        const stored = await handle.read(0);
+        const missing = session.snapshotEvents().slice(stored.events.length, known);
+        if (missing.length > 0)
+            await handle.append(missing);
+        await handle.flush();
+    }
     /**
      * Get or open the child session's registry-owned WRITE handle (the
      * {@link childWriteHandles} cache). When the caller carries the session
@@ -2670,9 +2789,22 @@ export async function apply(ctx, config) {
     // The member channel's loopback listener (bridge MCP servers call back here).
     // Degrade, don't explode: a failed bind leaves member_message failing with a
     // tool error while everything else works.
-    const memberChannel = new MemberChannel(ctx, registry, registry.memberBridgeSocketPath());
+    // Mode tools: a member with a mode reaches that preset's plugin tools
+    // through the same bridge (see preset-tool-host.ts).
+    const modeTools = new PresetToolHost(ctx, join(config.homesRoot, 'mode-tools.jsonl'));
+    const memberChannel = new MemberChannel(ctx, registry, registry.memberBridgeSocketPath(), modeTools);
     void memberChannel.start();
-    ctx.effect(() => () => { void memberChannel.dispose(); });
+    ctx.on('approval/request', async (request, next) => {
+        const child = modeTools.memberOf(request.agent);
+        const delegation = child === undefined ? undefined : registry.getDelegation(child);
+        const room = ctx.get.call(ctx, 'room');
+        if (child === undefined || delegation === undefined || room?.askMemberApproval === undefined)
+            return next();
+        const reason = request.displayReason ?? request.reason;
+        const outcome = await room.askMemberApproval({ childSessionId: child, parentSessionId: delegation.parentSessionId, provider: delegation.provider }, { toolName: request.toolName, ...reason === undefined ? {} : { reason }, ...request.signal === undefined ? {} : { signal: request.signal } });
+        return outcome === 'unavailable' ? next() : outcome;
+    }, { prepend: true });
+    ctx.effect(() => () => { void memberChannel.dispose(); void modeTools.dispose(); });
     ctx.commands.register({
         name: 'local-agent',
         description: 'list the registered local code-agent harnesses, or stop an in-flight delegation',

package/lib/types/live-stream.d.ts

@@ -27,7 +27,18 @@ export declare class LiveStreamPublisher {
     private readonly persist;
     private readonly onError;
     private readonly states;
+    /** Items shown live but not yet in the log: their step cannot open before the earlier steps close. */
+    private readonly previews;
     constructor(streams: LocalAgentStreams, session: Session, turn: number, persist: () => void, onError: (error: unknown) => void);
+    /**
+     * Show an item live without writing it to the session: a step may open in
+     * the log only after every earlier step has closed, so a later item that
+     * streams first waits here (browser-only) until the driver can open it.
+     */
+    preview(step: number, kind: 'think' | 'text', text: string, options?: {
+        itemId?: string;
+        receivedAt?: number;
+    }): void;
     update(step: number, kind: 'think' | 'text', text: string, options?: {
         itemId?: string;
         receivedAt?: number;

package/lib/types/live-stream.js

@@ -97,6 +97,8 @@ export class LiveStreamPublisher {
     persist;
     onError;
     states = new Map();
+    /** Items shown live but not yet in the log: their step cannot open before the earlier steps close. */
+    previews = new Map();
     constructor(streams, session, turn, persist, onError) {
         this.streams = streams;
         this.session = session;
@@ -104,8 +106,23 @@ export class LiveStreamPublisher {
         this.persist = persist;
         this.onError = onError;
     }
+    /**
+     * Show an item live without writing it to the session: a step may open in
+     * the log only after every earlier step has closed, so a later item that
+     * streams first waits here (browser-only) until the driver can open it.
+     */
+    preview(step, kind, text, options = {}) {
+        const id = `${this.turn}:${step}${options.itemId === undefined ? '' : `:${options.itemId}`}`;
+        const previous = this.previews.get(id);
+        if (previous?.text === text && previous.kind === kind)
+            return;
+        const item = { id, turn: this.turn, step, kind, text, receivedAt: previous?.receivedAt ?? options.receivedAt ?? Date.now() };
+        this.previews.set(id, item);
+        this.streams.publish(String(this.session.id), item);
+    }
     update(step, kind, text, options = {}) {
         const id = `${this.turn}:${step}${options.itemId === undefined ? '' : `:${options.itemId}`}`;
+        this.previews.delete(id);
         let state = this.states.get(id);
         if (state?.item.text === text && state.item.kind === kind)
             return;
@@ -150,6 +167,12 @@ export class LiveStreamPublisher {
     }
     /** Call only after the corresponding native final message has been appended. */
     finish(step) {
+        for (const [id, item] of this.previews) {
+            if (item.step !== step)
+                continue;
+            this.previews.delete(id);
+            this.streams.finish(String(this.session.id), id);
+        }
         for (const [id, state] of this.states) {
             if (state.item.step !== step)
                 continue;
@@ -167,6 +190,9 @@ export class LiveStreamPublisher {
     }
     /** A producer failure keeps a durable partial, without claiming completion. */
     dispose() {
+        for (const id of this.previews.keys())
+            this.streams.finish(String(this.session.id), id);
+        this.previews.clear();
         for (const [id, state] of this.states) {
             this.checkpoint(id);
             if (state.timer !== undefined)

package/lib/types/member-bridge.d.ts

@@ -10,7 +10,9 @@
  * it bare: `node <this file>`, with the socket path and token in its
  * environment (written into the CLI's scoped MCP config by the provider).
  * Covers the MCP handshake subset a client needs: `initialize`,
- * `notifications/initialized`, `ping`, `tools/list`, `tools/call`.
+ * `notifications/initialized`, `ping`, `tools/list`, `tools/call`. A member
+ * with a mode also gets that preset's plugin tools: `tools/list` asks the
+ * host for them and any other tool name is forwarded as a mode-tool call.
  * @module @khorsheed/dsh-local-agent/member-bridge
  */
 import type { Readable, Writable } from 'node:stream';
@@ -25,6 +27,10 @@ export interface MemberBridgeEnv {
     /** This run's member-channel token. */
     readonly token?: string | undefined;
 }
+/** The member's mode tools (the preset's plugin tools), empty when it has none or the host is unreachable. */
+export declare function listModeTools(env: MemberBridgeEnv): Promise<readonly Record<string, unknown>[]>;
+/** Run one mode tool on the host; the host's MCP result passes through. */
+export declare function callModeTool(env: MemberBridgeEnv, name: string, args: unknown): Promise<Record<string, unknown>>;
 /**
  * Handle one `member_message` tool call: forward to the host listener and map
  * the outcome to a tool result. Channel failures (missing env, unreachable
@@ -36,6 +42,10 @@ export interface MemberBridgeEnv {
 export declare function callMemberMessage(env: MemberBridgeEnv, args: {
     to?: unknown;
     text?: unknown;
+    kind?: unknown;
+    inReplyTo?: unknown;
+    note?: unknown;
+    task?: unknown;
 }): Promise<Record<string, unknown>>;
 /**
  * Run the stdio JSON-RPC loop over the given streams (injectable for tests).