@treeseed/dsh-chapters 0.2.8 → 0.2.11

package/docs/contract.md

@@ -706,6 +706,46 @@ version supplies, so Autorun reported itself unavailable on a host that exposes
 `{ captureInsertion, insertText, setDraft, addAttachments, removeAttachment, pruneAttachments, submit }`, and
 the composer-write limitation in #126 is measured against that same kit.
 
+**The running signal has seats, and the scalar is only one of them (measured 2026-10-31, #194).**
+`SessionSnapshot.running: boolean` (`packages/api/session-controller/src/client/contract/snapshot.ts:69-73`)
+arrives through the dock's standard prop `useSession` — a `MaybeSnapshotSelectorHook<SessionSnapshot>`
+(`useSession((s) => s.running)`), the same seat `ui-session` documents in `SessionStandardProps`.
+Some builds ALSO hand a scalar `running` prop. The shipped dock declared both hook channels
+(`useSessionStatus?`, `useSession?`) and consumed only the scalar — so on a hook-only host the #193
+idle edge never fired and the cadence silently degraded to the conservative 10s-active fallback
+(`props.running ?? true`). Resolution order, locked here: scalar `running` → `useSession((s) =>
+s.running)` → unknown (conservative true, legacy cadence). Conditional invocation of an optional
+hook prop is deliberate: the prop face is fixed per host build, so hook order is stable across
+renders within any one deployment, which is the invariant React actually keeps.
+
+**Push transport (interface lock, #194 — probe-verified on host 0.2.1-rc.5, `spikes/push-probe/FINDINGS.md`).**
+Where the host has `appendPluginRecord` (0.2.1+; absent from 0.2.0-rc.2 — grep-verified on both tags),
+the bar's state rides a plugin record and a projection, and the steady state costs ZERO command runs:
+
+- Record type: `plugin:dsh-chapters/prompt`. Payload = the bar's durable facts, versioned:
+  `{ v: 1, status, text, turnSeq, error, intent, goalRevision, autorun, at }`.
+- Append sites: every durable row write — the runner's `analyzing`/`ready`/`failed`/quiet-`off`
+  transitions (it holds the live session) and the bar-access mutations (`setAutorun`, `setOff`,
+  `setOn`, `runNow`'s consumption), which gain an optional live-session parameter for the purpose.
+- The function comes ONLY from the host's own module instance — `createRequire(process.argv[1])
+  → resolve('@deepseek-ai/dsh-session') → await import(resolved)`. The plugin's OWN copy at the
+  IDENTICAL version throws `Receiver must be an instance of class Session` against a host session
+  (measured), and a bare import from a `link:` install resolves by realpath into the source tree —
+  on a dev machine, into a DIFFERENT host checkout than the running server. No plugin dependency is
+  declared for it; detection is `typeof appendPluginRecord === 'function'`, one try behind try/catch,
+  and any failure marks push unavailable for the process.
+- Projection: key `chaptersPrompt`, registered ONLY when the writer resolved — registration is the
+  feature signal. `apply` folds records last-wins; `wire.view` passes the payload through.
+- Client: the dock reads the standard prop `useProjection('chaptersPrompt')`. A live value renders
+  through the SAME reducer (one fold path); `undefined` ⇒ the #203/#208 pull schedule stands,
+  unchanged — the fallback is the floor. In push mode the only pulls are the bar's own actions and
+  ONE staleness-confirm per idle edge, scheduled at +20s and cancelled when a fresher record arrives
+  (the runner writes `analyzing` within moments of turn/end, so a healthy push cancels every confirm):
+  a silently dead push degrades to one pull per turn, never to a frozen bar.
+- Records are `ignorable: true` with an unknown `plugin:` type — skipped by readers, rendered by
+  nothing; the projection value travels the host's own push channel. Verbs, state block, and the
+  pull schedule below are unchanged and remain the contract for pre-0.2.1 hosts.
+
 **Verbs (interface lock, #113).** `/chapters-prompt` accepts `model …|clear`, `off`, `on`, `state`, `autorun on|off`,
 and **`run`** — submit the offer currently on screen as a **human-authored user turn**, through the same follow-up
 path autorun uses (`agent.followup(suggestPromptMessage(…))`). Run goes through the command plane rather than the

package/lib/client.js

@@ -64,6 +64,14 @@ window.__ModuleLoader__.load({
 		function nativeTitle(label) {
 			return resolveTooltip() === null ? { title: label } : {};
 		}
+		// src/prompt-keys.ts
+		/**
+		* Identifiers shared by BOTH planes of the push transport (#194). One module, one spelling: the
+		* server registers the projection under this key and the client reads `useProjection(key)` — two
+		* literals in two planes would be exactly the drift #59 forbids. No node imports (the client
+		* compiles this), no DOM (the server imports this).
+		*/
+		const PROMPT_PROJECTION_KEY = "chaptersPrompt";
 		// src/client/prompt-bar.ts
 		function initialBarState(autorun = "disarmed") {
 			return {
@@ -176,11 +184,12 @@ window.__ModuleLoader__.load({
 		const ACTIVE_POLL_MS = 1e4;
 		const QUIET_POLL_MS = 6e4;
 		function pollSpacingFor(s) {
+			if (s.turnEndPulse === true) return ACTIVE_POLL_MS;
 			if (s.edges) {
 				if (s.status === "analyzing" || s.autorun === "armed") return ACTIVE_POLL_MS;
 				return null;
 			}
-			const active = s.status === "analyzing" || s.autorun === "armed" || s.running;
+			const active = s.status === "analyzing" || s.autorun === "armed";
 			if (!active && s.hidden) return null;
 			return active ? ACTIVE_POLL_MS : QUIET_POLL_MS;
 		}
@@ -319,6 +328,58 @@ window.__ModuleLoader__.load({
 			return /^\s*model:\s*unset\b/m.test(text);
 		}
 		/**
+		* A pushed payload becomes the SAME events the pull path dispatches — one fold, one reducer, no
+		* second implementation to drift (#59). Null when the payload is not ours or not trustworthy: an
+		* unrecognised push is ignored, never guessed at, and the pull schedule underneath keeps running
+		* until a payload this function accepts actually arrives.
+		*/
+		function pushEventsOf(payload) {
+			if (payload === null || payload === void 0 || typeof payload !== "object") return null;
+			const p = payload;
+			if (p.v !== 1 || typeof p.status !== "string") return null;
+			const status = p.status;
+			if (status !== "off" && status !== "idle" && status !== "analyzing" && status !== "ready" && status !== "failed") return null;
+			return {
+				polled: {
+					t: "polled",
+					status,
+					...status === "ready" ? {
+						text: typeof p.text === "string" ? p.text : "",
+						turnSeq: p.turnSeq ?? null,
+						intent: p.intent ?? "worker-step"
+					} : {},
+					...status === "failed" ? { error: p.error ?? "the suggestion call failed" } : {}
+				},
+				autorun: {
+					t: "autorun",
+					on: p.autorun === "armed"
+				}
+			};
+		}
+		/**
+		* The running signal's resolution order (scalar prop → `useSession` snapshot via `deriveRunning` →
+		* unknown) lives in the dock as `props.running ?? deriveRunning(sessionSnapshot)` — ONE expression,
+		* pinned by a source-scan row, folded by the deriveRunning rows that already cover every shape.
+		* A second pure helper for the same decision would be exactly the drift #59 forbids; the draft of
+		* #194 shipped one and this comment is its headstone.
+		*/
+		/** The staleness-confirm's one question: did a push arrive after the edge that scheduled it? */
+		function pushIsFresher(lastPushAt, edgeAt) {
+			return lastPushAt !== null && lastPushAt > edgeAt;
+		}
+		/**
+		* #218: a DEAD-PUSH HEARTBEAT, not a staleness confirm — 20s fired mid-turn before the turn's
+		* record could exist (turns outlast 20s), which was confirm spam wearing a safety hat. 5 minutes:
+		* during normal work a record arrives every turn and the push effect retires the pending timer, so
+		* a healthy push NEVER fires it; only a push silent for a whole 5 minutes pulls once — a frozen
+		* bar is the failure this bounds, and it is worth one node every 5 minutes, not one every 20
+		* seconds.
+		* within moments (the runner writes it BEFORE calling the model). If no push arrived this long
+		* after the edge, the push is presumed dead and ONE confirm pull runs — a silently dead push
+		* degrades to one pull per turn, never to a frozen bar.
+		*/
+		const PUSH_CONFIRM_GRACE_MS = 3e5;
+		/**
 		* #211 — the edge kick's delay, measured on the maintainer's host the hard way: some hosts publish
 		* `running` at STEP granularity (it flickers at every tool call and thinking block), and an
 		* immediate kick per falling edge was a rendered `chapters-prompt` node per tool call — all waste,
@@ -332,6 +393,26 @@ window.__ModuleLoader__.load({
 		function edgeKickDelayMs(msSinceLastPull) {
 			return Math.max(EDGE_DEBOUNCE_MS, EDGE_FLOOR_MS - msSinceLastPull);
 		}
+		/**
+		* #221: the turn-end pulse, derived from the host's own turn-boundary projection — no plugin
+		* record API needed, so it works on 0.2.0 hosts (where appendPluginRecord is absent) exactly as
+		* on newer ones. The host maintains a `turnBoundary` projection (the agent loop reads its
+		* lastTurn for its own bookkeeping); reading what the host already folds costs zero writes and
+		* delivers reactively through the same standard useProjection seat as any other projection.
+		* Returns true when a NEW turn ended since the last observation; the dock calls it once per
+		* render and stores the returned stamp back into `seen`.
+		*/
+		function turnEndPulse(lastTurn, seen) {
+			const cur = typeof lastTurn === "number" && Number.isFinite(lastTurn) ? lastTurn : 0;
+			if (cur > seen) return {
+				pulse: true,
+				seen: cur
+			};
+			return {
+				pulse: false,
+				seen
+			};
+		}
 		// src/client/prompt-dock.ts
 		/**
 		* The Suggested Next Step dock row (#113) — thin by design.
@@ -457,11 +538,21 @@ window.__ModuleLoader__.load({
 		}
 		function PromptDock(props) {
 			const { sessionId, inputActions, exec } = props;
+			const sessionSnapshot = (props.useSession ?? (() => void 0))((snapshot) => snapshot);
+			const running = props.running ?? deriveRunning(sessionSnapshot);
+			const useProjectionHook = props.useProjection ?? (() => void 0);
+			const pushed = useProjectionHook(PROMPT_PROJECTION_KEY);
+			const turnBoundary = useProjectionHook("turnBoundary");
 			const [state, dispatch] = (0, react.useReducer)(promptBarReducer, initialBarState(), (s) => {
+				const pushEvs = pushEventsOf(pushed);
+				if (pushEvs !== null) return {
+					...promptBarReducer(promptBarReducer(s, pushEvs.polled), pushEvs.autorun),
+					running: running ?? true
+				};
 				const c = sessionId !== void 0 ? stateCache.get(sessionId) : void 0;
 				return {
 					...c !== void 0 ? stateFromCache(c.ev, c.autorun) : s,
-					running: props.running ?? true
+					running: running ?? true
 				};
 			});
 			const pulling = (0, react.useRef)(false);
@@ -475,6 +566,9 @@ window.__ModuleLoader__.load({
 			const kick = (0, react.useRef)(void 0);
 			const lastPullAt = (0, react.useRef)(null);
 			const edgeTimer = (0, react.useRef)(void 0);
+			const pushLiveRef = (0, react.useRef)(false);
+			const seenTurnRef = (0, react.useRef)(0);
+			const lastPushAt = (0, react.useRef)(null);
 			const answered = (0, react.useRef)(false);
 			const replyStatus = (0, react.useRef)("unknown");
 			const stateRef = (0, react.useRef)(initialBarState());
@@ -517,19 +611,36 @@ window.__ModuleLoader__.load({
 					pulling.current = false;
 				}
 			}, [exec]);
+			(0, react.useEffect)(() => {
+				const evs = pushEventsOf(pushed);
+				if (evs === null) return;
+				pushLiveRef.current = true;
+				lastPushAt.current = Date.now();
+				dispatch(evs.polled);
+				dispatch(evs.autorun);
+				if (edgeTimer.current !== void 0) {
+					clearTimeout(edgeTimer.current);
+					edgeTimer.current = void 0;
+				}
+			}, [pushed]);
 			(0, react.useEffect)(() => {
 				ensureCss();
 				if (pulled.current) return;
 				pulled.current = true;
 				let timer;
 				const effectiveStatus = () => replyStatus.current === "unknown" ? stateRef.current.status : replyStatus.current;
-				const spacingNow = () => pollSpacingFor({
-					status: effectiveStatus(),
-					autorun: stateRef.current.autorun,
-					running: stateRef.current.running,
-					hidden: typeof document !== "undefined" && document.hidden === true,
-					edges: edgesRef.current
-				});
+				const spacingNow = () => {
+					const pe = turnEndPulse(turnBoundary?.lastTurn, seenTurnRef.current);
+					if (pe.pulse) seenTurnRef.current = pe.seen;
+					return pollSpacingFor({
+						status: effectiveStatus(),
+						autorun: stateRef.current.autorun,
+						running: stateRef.current.running,
+						hidden: typeof document !== "undefined" && document.hidden === true,
+						edges: edgesRef.current,
+						turnEndPulse: pe.pulse
+					});
+				};
 				const duePull = () => {
 					const c = sessionId !== void 0 ? stateCache.get(sessionId) : void 0;
 					return mountPullDecision({
@@ -540,6 +651,7 @@ window.__ModuleLoader__.load({
 					});
 				};
 				const tick = async (opts) => {
+					if (pushLiveRef.current && opts?.force !== true) return;
 					if (featureAbsent) return;
 					if (effectiveStatus() === "off") {
 						if (!(opts?.mount === true && duePull())) return;
@@ -571,9 +683,9 @@ window.__ModuleLoader__.load({
 					if (typeof document !== "undefined") document.removeEventListener("visibilitychange", onVisible);
 				};
 			}, [refresh]);
-			const prevRunning = (0, react.useRef)(props.running ?? true);
+			const prevRunning = (0, react.useRef)(running ?? true);
 			(0, react.useEffect)(() => {
-				const next = props.running ?? true;
+				const next = running ?? true;
 				const prev = prevRunning.current;
 				prevRunning.current = next;
 				dispatch({
@@ -583,17 +695,20 @@ window.__ModuleLoader__.load({
 				if (prev && !next) {
 					if (edgeTimer.current !== void 0) clearTimeout(edgeTimer.current);
 					const since = lastPullAt.current === null ? Number.MAX_SAFE_INTEGER : Date.now() - lastPullAt.current;
+					const delay = pushLiveRef.current ? Math.max(PUSH_CONFIRM_GRACE_MS, edgeKickDelayMs(since)) : edgeKickDelayMs(since);
+					const edgeAt = Date.now();
 					edgeTimer.current = setTimeout(() => {
 						edgeTimer.current = void 0;
+						if (pushLiveRef.current && pushIsFresher(lastPushAt.current, edgeAt)) return;
 						kick.current?.();
-					}, edgeKickDelayMs(since));
+					}, delay);
 				} else if (!prev && next) {
 					if (edgeTimer.current !== void 0) {
 						clearTimeout(edgeTimer.current);
 						edgeTimer.current = void 0;
 					}
 				}
-			}, [props.running]);
+			}, [running]);
 			const run = (0, react.useCallback)(() => {
 				if (state.text === null || state.text === "" || exec === void 0) return;
 				setBusy(true);
@@ -621,8 +736,7 @@ window.__ModuleLoader__.load({
 				if (!shouldAutoFire(state)) return;
 				run();
 			}, [state, run]);
-			const sessionSnapshot = (props.useSession ?? (() => void 0))((snapshot) => snapshot);
-			const autorunDisabled = (props.running ?? deriveRunning(sessionSnapshot)) === void 0;
+			const autorunDisabled = running === void 0;
 			if (sessionId === void 0 || !barVisible(state)) return null;
 			const populate = () => {
 				console.info(`[client:prompt] populate expanded=${String(state.expanded)} hasInsertText=${String(typeof inputActions?.insertText)} hasSetDraft=${String(typeof inputActions?.setDraft)} textLen=${String(state.text?.length ?? -1)}`);
@@ -706,7 +820,7 @@ window.__ModuleLoader__.load({
 							t: "autorun",
 							on: arm
 						});
-						await refresh();
+						if (!pushLiveRef.current) await refresh();
 					})();
 				}
 			}), (0, react.createElement)(Action, {
@@ -912,13 +1026,14 @@ window.__ModuleLoader__.load({
 			return tryClick();
 		}
 		function makeDoorRunner(remote, sessions, door, verifySwitched, opts) {
-			return async function run(sessionId) {
+			return async function run(sessionId, anchorSeq) {
 				try {
 					if (remote.commands?.execute === void 0) return {
 						ok: false,
 						message: "commands remote unavailable"
 					};
-					const res = await remote.commands.execute(sessionId, door.command, []);
+					const line = typeof anchorSeq === "number" && Number.isFinite(anchorSeq) ? `${door.command} ${String(Math.trunc(anchorSeq))}` : door.command;
+					const res = await remote.commands.execute(sessionId, line, []);
 					if (res.ok !== true) return {
 						ok: false,
 						message: (res.error?.message ?? `the ${door.noun} call failed`).slice(0, 90)
@@ -1155,12 +1270,27 @@ window.__ModuleLoader__.load({
 				}, { ...uiWorkspace !== void 0 ? { navigator: uiWorkspace } : {} }),
 				component: makeDoorAction(door)
 			}));
-			slots.inject("conversation.chat.assistant-actions", () => rows.map(({ door, run, component }) => slots.register({
-				name: "conversation.chat.assistant-actions",
-				id: door.id,
-				order: door.order,
-				inject: (sessionId) => ({ run: () => run(sessionId) })
-			}, component)));
+			console.info(`[client:chapters] injecting ${String(rows.length)} assistant-actions door(s)`);
+			const disposeDoors = slots.inject("conversation.chat.assistant-actions", () => {
+				const effects = rows.map(({ door, run, component }) => slots.register({
+					name: "conversation.chat.assistant-actions",
+					id: door.id,
+					label: door.label,
+					inject: (sessionId, owner) => ({ run: async () => {
+						let anchor = null;
+						const mid = typeof owner?.messageId === "string" ? owner.messageId : "";
+						if (mid !== "") try {
+							const out = await runCommandText(remote, sessionId, `/chapters-anchor ${mid}`);
+							const n = Number.parseInt(out.trim(), 10);
+							if (Number.isFinite(n) && n > 0) anchor = n;
+						} catch {}
+						return run(sessionId, anchor);
+					} })
+				}, component));
+				console.info(`[client:chapters] door factory ran: ${String(effects.length)} register effect(s), types: ${effects.map((e) => typeof e).join(",")}`);
+				return effects;
+			});
+			console.info(`[client:chapters] assistant-actions inject returned ${typeof disposeDoors}`);
 			slots.inject("conversation.input.dock", () => slots.register({
 				name: "conversation.input.dock",
 				id: "chapters-prompt",