@aiwayds/dsh-tui-pi 0.28.0 → 0.29.0

package/lib/session.js

@@ -14,10 +14,14 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { settingsNamespace, SettingsConflictError } from '@deepseek-ai/dsh-settings';
 import { SessionId } from '@deepseek-ai/dsh-session';
 import { readAppendSystem } from "./append-system.js";
+import { join } from 'node:path';
 import { isAgentEnd, isAgentStart, isDcpCompactionNotice, isLlmRetry, isSubagentDescriptor, isTuiPluginInjection } from "./dsh-events.js";
 import { loadModelProfiles, modelProfilesPath, resolvePinnedProfile } from "./model-profiles.js";
 import { installSpawnToolFence, markTuiSurface } from "./subagent-policy.js";
+import { RemoteSessionTail } from "./remote-tail.js";
+import { sessionLogRoot } from "./sessions.js";
 import { estimateContentTokens, estimateTextTokens } from "./tokens.js";
+import { acquireWriterLock, projectKeyFor, releaseOwnedWriterLock, WriterLockedError } from "./writer-lock.js";
 /**
  * Register the APPEND_SYSTEM.md section on ONE agent's scoped context, so the
  * user's orchestrator identity applies to the TUI's main agent ONLY. A section
@@ -166,6 +170,34 @@ export class DshSessionBridge {
     resuming;
     /** Target id of the in-flight resume — see `resume()`/`getResumingSessionId()`. */
     resumeTargetId;
+    /**
+     * Session dirs whose cross-process writer lock THIS bridge established via
+     * a cold arm. Release is bound to the owning handle's disposal
+     * (`ownWithLock`), so the set itself only tracks double-release safety.
+     */
+    heldLockDirs = new Set();
+    /** Active cross-process read-only view (see watchRemote). */
+    remoteTail;
+    /** Session watched read-only right now. */
+    remoteWatchId;
+    /** Follow-ups typed while watching — sent once promotion wins the lock. */
+    remoteFollowups = [];
+    promotingRemote = false;
+    promoteTimer;
+    idleReleaseTimer;
+    /** Writer lock taken for the CURRENTLY bound local agent (see drive arms). */
+    driveLock;
+    /** Test seam + tuning for the watcher (interval/decoder injection). */
+    remoteTailOptions;
+    idleReleaseDelayMs;
+    promoteIntervalMs;
+    /** Serializes watch-lifecycle ops against the promotion poll. */
+    opChain = Promise.resolve();
+    runExclusive(op) {
+        const next = this.opChain.then(op, op);
+        this.opChain = next.then(() => undefined, () => undefined);
+        return next;
+    }
     disposers = [];
     sessionId;
     /** Agent preset id to pass to `meta.agentPreset` on the next `createSession`. */
@@ -269,9 +301,12 @@ export class DshSessionBridge {
     trackedSessions = new Set();
     /** `${runId}:${seq}` → childId, for `tool-workflow/agent-end` pairing. */
     runSeqToChild = new Map();
-    constructor(ctx, callbacks) {
+    constructor(ctx, callbacks, options = {}) {
         this.ctx = ctx;
         this.callbacks = callbacks;
+        this.remoteTailOptions = options.remoteTailOptions ?? {};
+        this.idleReleaseDelayMs = options.idleReleaseDelayMs ?? 800;
+        this.promoteIntervalMs = options.promoteIntervalMs ?? 1000;
         // Footer shows provider/model from the very first frame — read the cwd
         // pin (if any) else the composed default selection eagerly; a session
         // created later refreshes it the same way.
@@ -339,6 +374,8 @@ export class DshSessionBridge {
                 return;
             this.running = status === 'running';
             this.callbacks.onStatus(status);
+            if (status === 'idle')
+                this.scheduleIdleRelease();
         }));
         // Round-count reconcile fallback: keep "rounds" and the maxRounds policy
         // live even when a child's own events never bubble to this plugin (see
@@ -456,6 +493,12 @@ export class DshSessionBridge {
     }
     /** Queue one user prompt, creating the session lazily on first use. */
     async prompt(text) {
+        if (this.remoteTail !== undefined) {
+            // Lockless viewer: never refuse, QUEUE. The promote poll sends it the
+            // moment the driver goes idle and we win the writer lock.
+            this.remoteFollowups.push(text);
+            return;
+        }
         const handle = await this.ensureSession();
         const message = createUserMessage({
             content: [{ type: 'text', text }],
@@ -463,6 +506,171 @@ export class DshSessionBridge {
         });
         handle.agent.followup(message);
     }
+    /** While a remote watch is active input QUEUES instead of driving. */
+    isReadOnlyView() {
+        return this.remoteTail !== undefined;
+    }
+    /** Follow-ups typed while watching, oldest first; takes them all. */
+    takePendingRemoteFollowups() {
+        return this.remoteFollowups.splice(0);
+    }
+    /**
+     * READ-ONLY cross-process view: another dsh process drives this session
+     * (the single-writer guard refused our cold resume), so sync DISPLAY from
+     * its persisted log instead — poll-decode, emit durable events through
+     * the same render pipeline a live session uses. Contract: latency ≈ poll
+     * interval, streaming detail omitted, every turn's final assistant
+     * message arrives. Replaces any prior binding; ends via stopRemoteWatch
+     * on dispose or the next resume.
+     */
+    watchRemote(sessionId) {
+        return this.runExclusive(() => this.watchRemoteInner(sessionId));
+    }
+    async watchRemoteInner(sessionId) {
+        await this.stopRemoteWatch();
+        // Same derivation as acquireSessionLock — no cwd, no view.
+        const cwd = await this.headerCwdOf(sessionId);
+        if (cwd === undefined)
+            throw new Error(`cannot locate the log of ${sessionId} for read-only viewing`);
+        const file = join(sessionLogRoot(), projectKeyFor(cwd), sessionId, 'session.jsonl.zstd');
+        // The firehose gate uses this id; harmless cross-process (nothing in
+        // THIS process will publish for it) and required so a later local agent
+        // for the SAME id (post-switch) re-binds cleanly.
+        this.sessionId = SessionId(sessionId);
+        this.handle = undefined;
+        this.remoteWatchId = sessionId;
+        const tail = new RemoteSessionTail(file, {
+            onEvents: events => {
+                // A stopped tail's in-flight final tick must not paint after detach.
+                if (this.remoteTail !== tail)
+                    return;
+                for (const raw of events) {
+                    const event = raw;
+                    // Per-event containment mirrors the firehose listener contract:
+                    // one unsupported/malformed row must not kill the rest of the
+                    // view batch. Projection and render dispatch are contained
+                    // SEPARATELY so a projection gap cannot suppress rendering.
+                    try {
+                        this.applyEvent(event);
+                    }
+                    catch {
+                        /* projection drift — the view row still renders below */
+                    }
+                    try {
+                        this.callbacks.onEvent(event);
+                        if (event.type === 'turn/start') {
+                            this.running = true;
+                            this.callbacks.onStatus('running');
+                        }
+                        else if (event.type === 'turn/end') {
+                            this.running = false;
+                            this.callbacks.onStatus('idle');
+                        }
+                    }
+                    catch {
+                        /* contained — keep rendering the remaining events */
+                    }
+                }
+            },
+        }, this.remoteTailOptions);
+        this.remoteTail = tail;
+        // Deterministic backfill before returning: callers may render/report
+        // immediately; live ticks continue on the poll cadence afterwards.
+        await tail.tickOnce();
+        tail.start();
+        // Promotion lives OUTSIDE the event stream: one independent poll checks
+        // (queue non-empty ∧ driver idle ∵ running flag ∧ lock winnable). This
+        // keeps takeover state transitions off the render path entirely.
+        if (this.promoteTimer === undefined) {
+            this.promoteTimer = setInterval(() => void this.maybePromoteRemote(), this.promoteIntervalMs);
+        }
+    }
+    async stopRemoteWatch() {
+        if (this.promoteTimer !== undefined) {
+            clearInterval(this.promoteTimer);
+            this.promoteTimer = undefined;
+        }
+        this.remoteWatchId = undefined;
+        if (this.remoteTail === undefined)
+            return;
+        this.remoteTail.stop();
+        this.remoteTail = undefined;
+    }
+    /**
+     * Contract "idle releases the write; next input takes it": when OUR agent
+     * settles with nothing pending locally (own re-wake included), drop the
+     * writer lock so another surface can take over. Delayed once and
+     * re-checked because upstream may latch idle only to immediately replay
+     * a queued wake as a new turn.
+     */
+    scheduleIdleRelease() {
+        if (this.idleReleaseTimer !== undefined)
+            clearTimeout(this.idleReleaseTimer);
+        this.idleReleaseTimer = setTimeout(() => {
+            this.idleReleaseTimer = undefined;
+            if (this.running)
+                return;
+            // Contained: foreign-shaped agents must not let a release timer blow
+            // up the process; when the inbox is unreadable we conservatively keep
+            // the lock.
+            try {
+                if (this.getPendingPrompts().length > 0)
+                    return;
+            }
+            catch {
+                return;
+            }
+            const lock = this.driveLock;
+            if (lock === undefined)
+                return;
+            void this.releaseColdLock(lock);
+        }, this.idleReleaseDelayMs);
+    }
+    /**
+     * Promote poll tick: viewer + queued follow-ups + watched driver idle →
+     * race for the writer lock; winning hands to onRemotePromotable (UI
+     * rebuild via resume + queue drain), losing retries next tick. All async
+     * sequencing stays in THIS loop — never inside event callbacks.
+     */
+    maybePromoteRemote() {
+        return this.runExclusive(async () => {
+            await this.maybePromoteRemoteInner();
+        });
+    }
+    async maybePromoteRemoteInner() {
+        if (this.promotingRemote || this.running)
+            return;
+        const id = this.remoteWatchId;
+        if (id === undefined || this.remoteFollowups.length === 0)
+            return;
+        const promote = this.callbacks.onRemotePromotable;
+        if (promote === undefined)
+            return;
+        this.promotingRemote = true;
+        let locked = false;
+        try {
+            await this.acquireSessionLock(id);
+            locked = true;
+        }
+        catch {
+            /* still held / driver alive — retry next poll */
+        }
+        if (!locked) {
+            this.promotingRemote = false;
+            return;
+        }
+        await this.stopRemoteWatch(); // ends the view BEFORE any UI rebuild
+        try {
+            await promote(id);
+            this.promotingRemote = false;
+        }
+        catch {
+            // Took the lock but the rebuild failed: back to spectating; ownership
+            // persists cooperatively so the retry below costs nothing extra.
+            this.promotingRemote = false;
+            await this.watchRemote(id).catch(() => { });
+        }
+    }
     /** The live agent, creating the session lazily when needed. */
     async ensureAgent() {
         const handle = await this.ensureSession();
@@ -534,6 +742,9 @@ export class DshSessionBridge {
     }
     /** Dispose the live agent (if any) and stop event subscriptions. */
     async dispose() {
+        if (this.idleReleaseTimer !== undefined)
+            clearTimeout(this.idleReleaseTimer);
+        await this.stopRemoteWatch();
         for (const dispose of this.disposers.splice(0)) {
             try {
                 dispose();
@@ -601,6 +812,74 @@ export class DshSessionBridge {
         if (handle !== undefined)
             await handle.dispose();
     }
+    /**
+     * Historical cwd for a session, from the persistence header list — the
+     * log lives under THAT project key. All access best-effort: an absent
+     * service or odd host yields undefined and the arm stays UNGUARDED
+     * (fail-open, never locks a decoy), never breaks the resume.
+     */
+    async headerCwdOf(sessionId) {
+        try {
+            const persistence = this.ctx.get?.('sessionPersistence');
+            const stored = (await persistence?.list?.().catch(() => [])) ?? [];
+            const header = stored.find(candidate => String(candidate.id) === sessionId);
+            return typeof header?.cwd === 'string' && header.cwd !== '' ? header.cwd : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Single-writer guard for COLD arms (create / cold resume) only — the
+     * adopt arm above shares the live instance in-process and must stay
+     * lock-free. Locks sit beside the jsonl log so every process that could
+     * append to it competes on one file; a live foreign holder throws
+     * WriterLockedError (surfaces as "Cannot resume <id>: session is locked
+     * by a live process …"). `knownCwd` skips the header scan for creations,
+     * which always target process.cwd().
+     */
+    async acquireSessionLock(sessionId, knownCwd) {
+        const cwd = knownCwd ?? (await this.headerCwdOf(sessionId));
+        if (cwd === undefined || cwd === '') {
+            // No trustworthy cwd → the derived path would be a decoy the real
+            // writer never touches (fail-open, same policy as the feishu guard):
+            // locking a decoy would silently protect nothing while pretending to.
+            return undefined;
+        }
+        const dir = join(sessionLogRoot(), projectKeyFor(cwd), sessionId);
+        const result = await acquireWriterLock(dir);
+        if (!result.ok)
+            throw new WriterLockedError(result.holder);
+        this.heldLockDirs.add(dir);
+        return { dir };
+    }
+    /** Undo a guard whose arm then failed — transient errors must not pin the session. */
+    async releaseColdLock(lock) {
+        if (lock === undefined)
+            return;
+        this.heldLockDirs.delete(lock.dir);
+        await releaseOwnedWriterLock(lock.dir);
+    }
+    /**
+     * Bind lock release to an owned handle's disposal — every teardown path
+     * already goes through handle.dispose(), so this is the single choke
+     * point; switching away or exiting releases what we established.
+     */
+    ownWithLock(handle, lock) {
+        if (lock === undefined)
+            return handle;
+        const base = handle.dispose.bind(handle);
+        const bridge = this;
+        handle.dispose = async () => {
+            try {
+                await base();
+            }
+            finally {
+                await bridge.releaseColdLock(lock);
+            }
+        };
+        return handle;
+    }
     /**
      * Resume a persisted session: tear down the live agent (disposers are kept —
      * the session-id filter re-binds to the resumed id) and load the persisted
@@ -621,6 +900,7 @@ export class DshSessionBridge {
         // touching this field, so it always names the id actually loading.
         this.resumeTargetId = sessionId;
         const task = (async () => {
+            await this.stopRemoteWatch();
             const handle = this.handle;
             this.handle = undefined;
             this.sessionId = undefined;
@@ -666,26 +946,39 @@ export class DshSessionBridge {
                 }
                 return adopted;
             }
-            const resumed = await this.ctx.agents.resume({
-                resumeSessionId: sessionId,
-                agentOptions: this.selection ?? {},
-                // Install the mutable selection so `/model` can live-switch the route,
-                // the APPEND_SYSTEM.md section on this agent ONLY (never its
-                // subagents), and the spawn-tool hide so the agent sees a single
-                // `use_agent` delegation entry. The surface marker scopes the live
-                // disableSubagent guard to THIS agent (resume runs setup too, so a
-                // resumed session is re-marked without relying on persisted meta).
-                setup: async (agentCtx) => {
-                    markTuiSurface(agentCtx);
-                    installModelSelection(agentCtx, this.selectionRef);
-                    installAppendSystem(agentCtx);
-                    installSpawnToolFence(agentCtx);
-                },
-            });
-            this.handle = resumed;
+            // Cold arm — guarded: without the registry hit above, nothing here can
+            // see whether ANOTHER process owns this id right now. Take the writer
+            // lock beside its jsonl first so a concurrent owner refuses us loudly
+            // instead of two appends interleaving into "corrupt session log".
+            const lock = await this.acquireSessionLock(String(sessionId));
+            let resumed;
+            try {
+                resumed = await this.ctx.agents.resume({
+                    resumeSessionId: sessionId,
+                    agentOptions: this.selection ?? {},
+                    // Install the mutable selection so `/model` can live-switch the route,
+                    // the APPEND_SYSTEM.md section on this agent ONLY (never its
+                    // subagents), and the spawn-tool hide so the agent sees a single
+                    // `use_agent` delegation entry. The surface marker scopes the live
+                    // disableSubagent guard to THIS agent (resume runs setup too, so a
+                    // resumed session is re-marked without relying on persisted meta).
+                    setup: async (agentCtx) => {
+                        markTuiSurface(agentCtx);
+                        installModelSelection(agentCtx, this.selectionRef);
+                        installAppendSystem(agentCtx);
+                        installSpawnToolFence(agentCtx);
+                    },
+                });
+            }
+            catch (error) {
+                await this.releaseColdLock(lock);
+                throw error;
+            }
+            this.driveLock = lock;
+            this.handle = this.ownWithLock(resumed, lock);
             this.sessionId = sessionId;
             this.trackedSessions.add(String(sessionId));
-            return resumed;
+            return this.handle;
         })();
         this.resuming = task;
         try {
@@ -1185,27 +1478,41 @@ export class DshSessionBridge {
             };
     }
     /** Create the agent with the composed default model selection. */
-    createSession() {
+    async createSession() {
         this.seedSelectionFromDefault();
-        return this.ctx.agents.create({
-            sessionId: SessionId(crypto.randomUUID()),
-            meta: {
-                cwd: process.cwd(),
-                ...this.agentPreset !== undefined ? { agentPreset: this.agentPreset } : {},
-            },
-            agentOptions: this.selection ?? {},
-            // Install the mutable selection so `/model` can live-switch the route,
-            // the APPEND_SYSTEM.md section on this agent ONLY (never its
-            // subagents), and the spawn-tool hide so the agent sees a single
-            // `use_agent` delegation entry. The surface marker scopes the live
-            // disableSubagent guard to THIS agent.
-            setup: async (agentCtx) => {
-                markTuiSurface(agentCtx);
-                installModelSelection(agentCtx, this.selectionRef);
-                installAppendSystem(agentCtx);
-                installSpawnToolFence(agentCtx);
-            },
-        });
+        // Mint the id HERE so the pre-create lock covers exactly the directory
+        // agents.create is about to persist into (same cold-arm guard as resume).
+        const sessionId = crypto.randomUUID();
+        const cwd = process.cwd();
+        const lock = await this.acquireSessionLock(sessionId, cwd);
+        let handle;
+        try {
+            handle = await this.ctx.agents.create({
+                sessionId: SessionId(sessionId),
+                meta: {
+                    cwd,
+                    ...this.agentPreset !== undefined ? { agentPreset: this.agentPreset } : {},
+                },
+                agentOptions: this.selection ?? {},
+                // Install the mutable selection so `/model` can live-switch the route,
+                // the APPEND_SYSTEM.md section on this agent ONLY (never its
+                // subagents), and the spawn-tool hide so the agent sees a single
+                // `use_agent` delegation entry. The surface marker scopes the live
+                // disableSubagent guard to THIS agent.
+                setup: async (agentCtx) => {
+                    markTuiSurface(agentCtx);
+                    installModelSelection(agentCtx, this.selectionRef);
+                    installAppendSystem(agentCtx);
+                    installSpawnToolFence(agentCtx);
+                },
+            });
+        }
+        catch (error) {
+            await this.releaseColdLock(lock);
+            throw error;
+        }
+        this.driveLock = lock;
+        return this.ownWithLock(handle, lock);
     }
     /** The model selection shown in the footer (live value after `/model`). */
     getSelection() {