@xmoon76/dsh-pi-tui 0.1.3 → 0.1.5

package/README.md

@@ -2,7 +2,7 @@
 
 A third-party TUI mode for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`), built on a vendored fork of [pi-tui](https://github.com/MoonshotAI/kimi-code/tree/main/packages/pi-tui).
 
-This package is the `dsh.bundle` layer that makes `dsh --profile pi-tui` run a terminal UI instead of the browser GUI (`dsh --profile web`) or one-shot mode (`dsh --profile headless`). The vendored pi-tui fork (`@xmoon76/pi-tui`, with its five local rendering fixes) is bundled inside this package's build output — you only ever install this one package.
+This package is the `dsh.bundle` layer that makes `dsh --profile pi-tui` run a terminal UI instead of the browser GUI (`dsh --profile web`) or one-shot mode (`dsh --profile headless`). The vendored pi-tui fork (`@xmoon76/pi-tui`, with its local rendering fixes — the divergence ledger lives in the repo at `packages/pi-tui/AGENTS.md`) is bundled inside this package's build output — you only ever install this one package.
 
 ## Install
 

package/dist/index.d.mts

@@ -1,8 +1,97 @@
 import z from "@deepseek-ai/schemastery";
-import { ModelSelectionRef } from "@deepseek-ai/dsh-agent";
+import { Agent, ModelSelectionRef } from "@deepseek-ai/dsh-agent";
 import { SessionEvent, SessionId } from "@deepseek-ai/dsh-session";
+import { CommandDescriptor } from "@deepseek-ai/dsh-commands";
 import { EventEmitter } from "events";
 import { Context } from "@deepseek-ai/cordis";
+//#region src/diag.d.ts
+interface Diag {
+  debug(message: string, fields?: Record<string, unknown>): void;
+  info(message: string, fields?: Record<string, unknown>): void;
+  warn(message: string, fields?: Record<string, unknown>): void;
+  error(message: string, fields?: Record<string, unknown>): void;
+  /** Release the file handle, if one is open. */
+  dispose(): void;
+}
+//#endregion
+//#region src/skill-catalog.d.ts
+/**
+ * The standing-scope skill catalog adapter: the SINGLE narrow seam between
+ * the TUI and the dsh skill services (the non-public-API isolation
+ * contract, plan appendix B).
+ *
+ * Everything the TUI knows about dsh-skill and agent-presets lives here:
+ * - structural service types (never upstream classes) with OPTIONAL
+ *   capability members — `snapshot` and `standingKeyFor` are detected at
+ *   call time, so an upstream change degrades instead of breaking;
+ * - `readHumanSkillCatalog()`: snapshot-first collector (list() fallback),
+ *   official `isUserInvocable` filter, field validation, stable sort,
+ *   deep freeze, distinct abort propagation;
+ * - `resolveColdSkillTarget()`: capability-gated cold target selection
+ *   (standing scope → rosterless global → degraded global with a notice);
+ * - `resolveLiveSkillTarget()`: the agent's own registry + agent scope.
+ *
+ * Failure contract: ordinary provider/composition failures surface as
+ * degraded targets or rethrown errors for the coordinator to classify;
+ * aborts ALWAYS propagate as aborts. No failure may hang or crash the TUI —
+ * the worst outcome is "the corresponding commands are missing".
+ * @module @xmoon76/dsh-pi-tui/skill-catalog
+ */
+/** The human-facing slice of one skill: display fields only. */
+interface HumanSkillSummary {
+  readonly name: string;
+  readonly description: string;
+  readonly whenToUse?: string;
+}
+/** The detached human skill catalog one observation produced. */
+interface HumanSkillCatalog {
+  readonly skills: readonly HumanSkillSummary[];
+  /** Whether discovery completed within a stable revision (an incomplete
+   * observation must not replace a last-good catalog). */
+  readonly complete: boolean;
+}
+//#endregion
+//#region src/surface-catalog.d.ts
+/** One effective command's discovery metadata (the official descriptor's
+ * display fields; never a handler or a definition). */
+interface SurfaceCommandSummary {
+  readonly name: string;
+  readonly description: string;
+  readonly input?: {
+    readonly hint: string;
+  };
+}
+/** One provider's detached failure text (never the thrown value itself). */
+interface SurfaceCatalogIssue {
+  readonly provider: 'commands' | 'skills';
+  readonly message: string;
+}
+/**
+ * The complete frozen catalog view installed before the first input:
+ * - `commands` — the full effective view at read time (diagnostics/tests);
+ * - `scopedCommands` — effective entries absent from, or shadowing, the
+ *   read-time global baseline (completion overrides while sessionless);
+ * - `skills` — human-invocable skill summaries (official policy applied);
+ * - `issues` — per-provider failures; an absent service is NOT an issue.
+ */
+interface SurfaceCatalogSnapshot {
+  readonly commands: readonly SurfaceCommandSummary[];
+  readonly scopedCommands: readonly SurfaceCommandSummary[];
+  readonly skills: readonly HumanSkillSummary[];
+  readonly issues: readonly SurfaceCatalogIssue[];
+}
+/** The commands-service surface the collector reads. */
+interface SurfaceCommandsService {
+  list(agent: Agent): readonly CommandDescriptor[];
+}
+/** The narrow context surface {@link readSurfaceCatalog} consumes. The
+ * SKILL services are NOT reached here: every dsh skill/agent-presets
+ * access goes through `src/skill-catalog.ts` (the single-point adapter,
+ * plan appendix B.1). */
+interface SurfaceCatalogContext {
+  get(name: 'commands'): SurfaceCommandsService | undefined;
+}
+//#endregion
 //#region src/commands.d.ts
 /** A balanced completed-turn prefix for forking: the log up to (and including)
  * the last `turn/end`. Undefined when no turn has completed yet.
@@ -23,11 +112,103 @@ interface Config {
 }
 declare const Config: z<Config>;
 /**
- * Read an explicit child-session reference from a future/extended job record.
- * Current dsh JobSnapshot records do not expose one, so this normally returns
- * undefined. Crucially, label, registration order and timestamps are never
- * accepted as identity signals.
+ * Slash commands that need no session: before the first user message
+ * (deferred start) they run locally without creating one. Everything else
+ * dispatches through `commands.execute`, which creates the session lazily
+ * (the command line IS the first user input). Commands in this set must
+ * tolerate `liveAgent === undefined` in their handlers.
+ *
+ * Exported for the headless suite: the gate is exactly where a sessionless
+ * command silently starts creating sessions again.
+ */
+declare const SESSIONLESS_COMMANDS: Set<string>;
+/**
+ * The LOCAL-execute command set: TUI-owned UI/control commands AND core
+ * control commands the TUI does not itself register (e.g. /kill) that
+ * must ALWAYS run locally through the commands service, never steered,
+ * regardless of the busyEnter preference. Everything NOT in this set —
+ * plain prompts AND non-local commands (the per-skill slash commands like
+ * /grilling or /matrix-cli) — flows through the busy-Enter submission
+ * policy while the agent is running: web parity, where a skill invocation
+ * is a plain `session.prompt` whose leading `/name` line the host's
+ * pre-step listener (dsh-tool-skill) resolves into the injected skill
+ * body — there is no command-execution wire for skills.
+ */
+declare const LOCAL_COMMANDS: Set<string>;
+/**
+ * Whether one submission steers under the busy-Enter preference: NOT a
+ * force-queued chord, NOT a TUI-owned local command, and the agent is
+ * running with the preference set to 'steer'. Pure so the dispatch gate
+ * (inside the runner closure) is testable headless.
+ * @param parsed - the parsed slash command, undefined for a plain prompt.
+ * @param running - whether the live agent reports running.
+ * @param busyEnter - the persisted preference value (''/undefined = queue).
+ * @param forceQueue - the Ctrl+Enter chord: always queue, never steer.
  */
+declare function shouldSteerOnEnter(parsed: {
+  name: string;
+} | undefined, running: boolean, busyEnter: string | undefined, forceQueue: boolean): boolean;
+/**
+ * The advertised-claim miss decision (pure, exported for the headless
+ * suite): a slash input whose name was advertised by the completion list at
+ * submit time but that the REAL session's catalog lacks is CONSUMED with an
+ * explicit error — never sent to the model as a plain user message. An
+ * unadvertised miss keeps the existing plain-input fallback (the user may
+ * deliberately send slash text to the model).
+ * @param execution - the settled `commands.execute` outcome.
+ * @param wasAdvertised - the claim captured BEFORE session creation.
+ * @returns whether the miss must be consumed as an advertised miss.
+ */
+declare function shouldConsumeAdvertisedMiss(execution: {
+  readonly result: unknown;
+} | undefined, wasAdvertised: boolean): boolean;
+/**
+ * The pre-mount surface catalog resolution:
+ * - an explicit `--session` start PREFETCHES the resumed agent's effective
+ *   catalog (a live read emits no session events);
+ * - the deferred start (no `--session`) reads the cold HUMAN SKILL catalog
+ *   through the preset's STANDING SCOPE — no Agent, no session, no turn —
+ *   so the first input sees human-invocable skills without any durable
+ *   side effect (the mechanism that avoids the probe dead end: host
+ *   `session/created` observers write durable knob events into every fresh
+ *   session).
+ *
+ * The snapshot (resume) or the skill catalog (cold) installs synchronously
+ * after mount (the ready barrier).
+ *
+ * Failure taxonomy (plan appendix B):
+ * - lifecycle cancellation: nothing installed, no notice;
+ * - a prefetch/standing read failure degrades to a one-shot notice (the
+ *   TUI mounts with the global view and built-in commands);
+ * - a missing/unknown preset or a broken standing mount degrades the cold
+ *   target to the global layer with a one-shot notice — never a probe
+ *   Agent, never a startup failure;
+ * - an ordinary provider read failure never rejects here: it becomes an
+ *   empty field + detached issue inside the catalog.
+ * @param options - injected dependencies (see {@link ResolveInitialCatalogOptions}).
+ * @returns the snapshot / skill catalog to install and an optional notice.
+ */
+interface InitialCatalogResolution {
+  /** The resume prefetch snapshot to install at mount. */
+  readonly snapshot?: SurfaceCatalogSnapshot;
+  /** The cold standing-scope human skill catalog (deferred start). */
+  readonly skills?: HumanSkillCatalog;
+  /** A user-facing notice when the prefetch/standing read degraded. */
+  readonly notice?: string;
+}
+/** Options for {@link resolveInitialCatalog}. */
+interface ResolveInitialCatalogOptions {
+  /** The resumed live agent, if any (prefetch path). */
+  readonly liveAgent?: Agent;
+  /** The effective preset id for the cold standing read (undefined = the
+   * deployment default; only consulted for the deferred start). */
+  readonly presetId?: string;
+  readonly signal: AbortSignal;
+  /** The context surface the collectors read services from. */
+  readonly ctx: SurfaceCatalogContext;
+  readonly diag: Diag;
+}
+declare function resolveInitialCatalog(options: ResolveInitialCatalogOptions): Promise<InitialCatalogResolution>;
 declare function subagentJobTranscriptId(snapshot: unknown): string | undefined;
 /** Viewer body for a subagent job with no uniquely matched child. */
 declare function subagentJobViewHint(status: string, detail: string | undefined): string;
@@ -131,4 +312,4 @@ declare function recomposeBlank(ctx: Context, agent: {
  */
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { AgentComposition, Config, RecomposableSession, RecomposeOutcome, apply, composeAgent, dangerCommand, forkSeed, inject, name, recomposeBlank, recordedPreset, resumeCommand, runningProfile, subagentJobTranscriptId, subagentJobViewHint };
+export { AgentComposition, Config, InitialCatalogResolution, LOCAL_COMMANDS, RecomposableSession, RecomposeOutcome, ResolveInitialCatalogOptions, SESSIONLESS_COMMANDS, apply, composeAgent, dangerCommand, forkSeed, inject, name, recomposeBlank, recordedPreset, resolveInitialCatalog, resumeCommand, runningProfile, shouldConsumeAdvertisedMiss, shouldSteerOnEnter, subagentJobTranscriptId, subagentJobViewHint };