dsh-code 1.3.0 → 1.4.0

package/lib/types/runner/submissions.d.ts

@@ -0,0 +1,87 @@
+/** Submission vocabulary and the startup input gate for the terminal runner.
+ *
+ * Pure over the handles they are given: the queue mutations and the session
+ * guard are decisions the runner applies, and the gate only orders deliveries,
+ * so every branch is testable without composing an Agent.
+ *
+ * @module @deepseek-ai/dsh-code/submissions
+ */
+import { type ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { Agent, AgentStatus, Inbox } from '@deepseek-ai/dsh-agent';
+import type { UserMessage } from '@deepseek-ai/dsh-session';
+import type { QueueMutation } from '../ui/ui-contract.ts';
+/** One composer submission waiting behind the startup delivery. */
+export interface QueuedSubmission {
+    readonly text: string;
+    /** `steer` inserts into the running turn; `followup` waits for the next one. */
+    readonly mode: 'followup' | 'steer';
+    readonly images: readonly ContentBlock[];
+}
+/** What one requested queue mutation did; the runner maps it to one notice. */
+export type QueueMutationOutcome = 'removed' | 'edited' | 'steered' | 'unavailable' | 'empty' | 'steerUnavailable';
+/**
+ * Replace one queued message's text while keeping its attachments. A queue
+ * edit rewrites what the user typed, not what they attached: image and file
+ * blocks ride through in delivery order (text first, then attachments, the
+ * shape {@link deliverLine} submits). Dropping them here would silently strip
+ * an attachment the user already confirmed, so this is the edit's single
+ * definition and the panel's read-only marker only mirrors it.
+ */
+export declare function queueEditContent(content: readonly ContentBlock[], text: string): ContentBlock[];
+/**
+ * Apply one terminal queue mutation to the live inbox. The decision and the
+ * inbox change are pure over the supplied handles so every branch is testable
+ * without an agent; steering itself is injected because it wakes the driver
+ * rather than mutating the inbox. The durable inbox splices remain the UI's
+ * single source of truth — this helper never reports a state the inbox did not
+ * actually reach.
+ * @param inbox - the live agent inbox (pending lists plus its mutators).
+ * @param status - the agent's lifecycle status; steering needs `running`.
+ * @param messageId - identity of the queued message to mutate.
+ * @param action - the requested mutation.
+ * @param steer - submits the removed message as next-step steering.
+ * @returns the outcome the caller reports.
+ */
+export declare function applyQueueMutation(inbox: Pick<Inbox, 'nextTurn' | 'append' | 'remove' | 'replace'>, status: AgentStatus, messageId: string, action: QueueMutation, steer: (message: UserMessage) => void): QueueMutationOutcome;
+/**
+ * Cancel the active turn while keeping the next-turn queue, then wake the
+ * driver again so the preserved messages actually run. `cancel` clears
+ * pending work by default and never wakes the driver on its own, so the queue
+ * is captured first and re-submitted afterwards: a waking submission latches
+ * the wake while the aborted activity converges to idle, which is what turns
+ * "preserved" into "sent next" instead of "parked forever". Next-step
+ * steering is deliberately dropped — it belonged to the cancelled turn.
+ * @param agent - the live agent handle.
+ * @returns how many queued messages were preserved across the abort.
+ */
+export declare function cancelPreservingQueue(agent: Pick<Agent, 'inbox' | 'cancel' | 'followup'>): number;
+/**
+ * Whether a tagged submission still belongs to the active session. Attachment
+ * prepares resolve on the microtask timeline, while a queued session switch
+ * remounts the app asynchronously — the composing instance's unmount cleanup
+ * runs too late to abort, so the delivery itself carries the composing
+ * session's full id and the runner drops it here when the world moved on.
+ * An untagged (synchronous) or pending-session ('') submission always passes.
+ */
+export declare function submissionBelongsToSession(origin: string | undefined, activeSessionId: string | undefined): boolean;
+/**
+ * Order-preserving gate for composer input while the startup prompt/images
+ * are still preparing. Anything submitted before the startup delivery settles
+ * queues and flushes afterwards in submit order, so the initial request can
+ * never be overtaken by typing that raced a slow image preparation. The flush
+ * also runs when the startup delivery fails: user input is never stranded.
+ */
+export declare class StartupInputGate {
+    private readonly deliver;
+    private readonly queued;
+    private pending;
+    constructor(deliver: (submission: QueuedSubmission) => void);
+    /** Submit one line: delivered now while idle, queued behind the startup delivery otherwise. */
+    submit(submission: QueuedSubmission): void;
+    /**
+     * Run the startup delivery — the callback receives the direct-delivery sink
+     * for the startup prompt itself — then flush everything that queued behind
+     * it, in order, even when the callback rejects.
+     */
+    run(startup: (deliver: (submission: QueuedSubmission) => void) => Promise<void>): Promise<void>;
+}

package/lib/types/session/attach.d.ts

@@ -0,0 +1,39 @@
+/**
+ * One live attachment to a subagent conversation: a transcript store seeded
+ * from the child's durable log and then fed by the process-local event and
+ * stream buses in real time. The parent's own store is never touched.
+ *
+ * @module @deepseek-ai/dsh-code/session/attach
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import { type TranscriptStore } from './store.ts';
+/** The bus surfaces one attachment reads; the runner wires these to ctx. */
+export interface SubagentAttachmentServices {
+    /** Seed: the child's full durable event log, oldest first. */
+    load(id: string, signal?: AbortSignal): Promise<readonly SessionEvent[]>;
+    /** Durable events for exactly this child session, live. */
+    subscribeEvents(id: string, onEvent: (event: SessionEvent) => void): () => void;
+    /** Token stream frames for exactly this child agent, live. */
+    subscribeStream(id: string, onFrame: (frame: Parameters<TranscriptStore['applyStreamFrame']>[0]) => void): () => void;
+}
+/** A live child view handed to the App while attached. */
+export interface SubagentAttachment {
+    readonly id: string;
+    readonly label: string;
+    readonly store: TranscriptStore;
+    /** Whether the durable seed has landed (frames are held back until then). */
+    seeded(): boolean;
+    /** Drop the bus subscriptions; the store freezes at its last state. */
+    dispose(): void;
+}
+/** An inert empty store keeps the App's external-store hook unconditional. */
+export declare const EMPTY_ATTACH_STORE: TranscriptStore;
+/**
+ * Attach to one subagent conversation.
+ *
+ * Ordering contract: durable events carry a per-session sequence, so the seed
+ * sets a watermark and live events at or below it are dropped as duplicates;
+ * stream frames are held until the seed lands so a frame whose settlement
+ * already arrived cannot resurrect a stale tail.
+ */
+export declare function createSubagentAttachment(services: SubagentAttachmentServices, id: string, label: string): SubagentAttachment;

package/lib/types/{store.d.ts → session/store.d.ts}

@@ -31,7 +31,7 @@
  */
 import type { AssistantStreamFrame } from '@deepseek-ai/dsh-agent';
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
-import { type TranscriptView } from './render/projection.ts';
+import { type TranscriptView } from '../render/projection.ts';
 /** The externally readable, event-fed transcript store for one session. */
 export interface TranscriptStore {
     /** The current view; the same object identity until an event changes it. */

package/lib/types/{subagents.d.ts → session/subagents.d.ts}

@@ -18,7 +18,7 @@
  * microtask notify chained SyncLane rerenders past React's nested update
  * limit; a bare macrotask merge repaints a whole turn's bursts at once).
  *
- * @module @deepseek-ai/dsh-code/subagents
+ * @module @deepseek-ai/dsh-code/session/subagents
  */
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
 /** Hard row cap: overflow evicts the oldest settled row; a fully busy feed waits. */
@@ -68,3 +68,10 @@ export declare function createSubagentFeed(): SubagentFeedView & {
     apply(sessionId: string, event: SessionEvent): void;
     reset(): void;
 };
+/**
+ * Root-log catalog facts a resumed session must replay into the subagent
+ * feed: constructor seeds never fire on the live bus, so without this the
+ * children of a resumed session vanish behind a restart. The empty-child
+ * placeholder row (childId '') is a placeholder, not a child, and stays out.
+ */
+export declare function subagentCatalogSeed(events: readonly SessionEvent[]): readonly SessionEvent<'subagent/catalog'>[];

package/lib/types/settings-file.d.ts

@@ -39,3 +39,13 @@ export interface UserSettingsPersistence {
  * @returns the persistence handle.
  */
 export declare function createUserSettingsPersistence(): UserSettingsPersistence;
+/**
+ * Read one user-level settings file as a plain object. The callers all treat a
+ * missing file as "unset" and a corrupt one as "warn and fall back", so this
+ * helper owns the one distinction they share: readable JSON that is not an
+ * object is corruption, not an absent preference, and must not surface as a
+ * cryptic property access on `null`.
+ * @param path - absolute path of the settings file.
+ * @returns the parsed object; the caller narrows each field itself.
+ */
+export declare function readSettingsObject(path: string): Record<string, unknown>;

package/lib/types/{panel-accent.d.ts → ui/panel-accent.d.ts}

@@ -10,7 +10,7 @@
  *
  * @module @deepseek-ai/dsh-tui/panel-accent
  */
-import { type RgbTriple } from './theme.ts';
+import { type RgbTriple } from '../theme.ts';
 /** One panel's resolved accent pair (border and title share the ring color in prismatic). */
 export interface PanelAccent {
     readonly border: RgbTriple;

package/lib/types/ui/panel-gap.d.ts

@@ -0,0 +1,6 @@
+/** Shared optional spacer row used by bounded panel layouts. */
+import { type ReactElement } from 'react';
+/** Codex-style panel rhythm that still participates in the row budget. */
+export declare function PanelGap({ visible }: {
+    visible: boolean;
+}): ReactElement | undefined;

package/lib/types/ui/query-editor.d.ts

@@ -0,0 +1,10 @@
+/** Shared one-line query editor for keyboard-owned filtering panels. */
+/**
+ * Apply one keystroke to a panel search query. IME commits arrive as one
+ * multi-character chunk, so the whole printable run is appended; paste
+ * markers are stripped and control-laden chunks are ignored.
+ */
+export declare function editQuery(query: string, input: string, key: {
+    backspace?: boolean;
+    delete?: boolean;
+}): string | undefined;

package/lib/types/ui/styled-rows.d.ts

@@ -0,0 +1,8 @@
+/** Ink renderer for width-safe styled terminal rows. */
+import { type ReactElement } from 'react';
+import type { StyledLine } from '../render/lines.ts';
+/** Render width-safe rows; every child is exactly one terminal row. */
+export declare function StyledRows({ lines }: {
+    lines: readonly StyledLine[];
+}): ReactElement;
+/** File-oriented, color-coded unified diff viewport. */

package/lib/types/{terminal-title.d.ts → ui/terminal-title.d.ts}

@@ -10,7 +10,7 @@
  * an empty OSC payload and the terminal falls back to its own default; the
  * previously set title is not portable to read back and is never restored.
  *
- * @module @deepseek-ai/dsh-code/terminal-title
+ * @module @deepseek-ai/dsh-code/ui/terminal-title
  */
 /** Tab label before a session carries a name. */
 export declare const DEFAULT_TERMINAL_TITLE = "deepseek";

package/lib/types/ui/ui-contract.d.ts

@@ -0,0 +1,12 @@
+/** Shared terminal UI contracts used by the runner, App, and composer. */
+/** Visual priority for one bounded local notice. */
+export type NoticeTone = 'info' | 'warning' | 'error';
+/** One mutation the terminal may request for a pending next-turn inbox item. */
+export type QueueMutation = {
+    readonly kind: 'remove';
+} | {
+    readonly kind: 'edit';
+    readonly text: string;
+} | {
+    readonly kind: 'steer';
+};

package/lib/types/ui/use-frames.d.ts

@@ -0,0 +1,6 @@
+/** Wall-clock animation frame hook shared by independent terminal leaves. */
+/**
+ * Derive ticks from elapsed wall time so a stretched interval skips ahead
+ * instead of slowing the animation under a busy event loop or remote shell.
+ */
+export declare function useFrames(intervalMs: number, active?: boolean): number;

package/lib/types/ui/use-stable-input.d.ts

@@ -0,0 +1,7 @@
+/** Stable Ink input subscription for stateful keyboard-owned surfaces. */
+import { type Key } from 'ink';
+/**
+ * Ink re-subscribes its input effect whenever the handler identity changes.
+ * Keep ownership stable while a surface updates cursor, scroll, or draft state.
+ */
+export declare function useStableInput(handler: (input: string, key: Key) => void, active: boolean): void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-code",
   "description": "DeepSeek Harness CLI core bundle: interactive coding terminal, durable sessions, and model management for dsh --profile cli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "packageManager": "pnpm@12.4.1",
   "type": "module",
   "bin": {