@xmoon76/dsh-pi-tui 0.1.4 → 0.1.6

package/dist/index.d.mts

@@ -1,8 +1,112 @@
 import z from "@deepseek-ai/schemastery";
-import { ModelSelectionRef } from "@deepseek-ai/dsh-agent";
+import { Agent, ModelSelectionRef } from "@deepseek-ai/dsh-agent";
+import { ContentBlock } from "@deepseek-ai/dsh-llm";
 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/tui-app.d.ts
+/** One queued inbox row for the queue pane (mirrors the agent Inbox's lists). */
+interface QueueItem {
+  /** The pending message id (agent inbox identity). */
+  id: string;
+  /** The message text, single-line display form. */
+  text: string;
+  /** next-turn followup vs next-step steer. */
+  mode: 'followup' | 'steer';
+  /** Plugin notice (e.g. a background-job completion): NOT steerable — it
+   * renders with its own marker and the hint drops the steer verbs. */
+  notice?: boolean;
+}
+//#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.
@@ -60,14 +164,136 @@ declare function shouldSteerOnEnter(parsed: {
   name: string;
 } | undefined, running: boolean, busyEnter: string | undefined, forceQueue: boolean): boolean;
 /**
- * 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.
+ * 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;
+/** The message-source projection the queue filter reads (a structural subset
+ * of dsh's message sources, so the helpers are testable without dsh types). */
+interface QueueNoticeSource {
+  readonly form?: string;
+  readonly kind?: string;
+  readonly summary?: string;
+}
+/**
+ * Whether a plain submitted draft is the quit word: exactly `exit` (trimmed,
+ * lowercase). The runner intercepts this BEFORE any session creation or
+ * submission (shell muscle memory); anything else — `exit!`, `Exit`, or a
+ * draft with a recalled entry still in it — is an ordinary message.
+ * @param text - the submitted draft.
+ */
+declare function isPlainExitPrompt(text: string): boolean;
+/**
+ * Whether an inbox message is a BACKGROUND-SUBAGENT settlement notice — the
+ * runtime's account of a child ending, not steerable user input. Two dsh
+ * producers push these into the parent's inbox:
+ *  - continuable children: `source.kind === 'subagent-settled'` (the
+ *    continuation manager's settlement notice);
+ *  - one-shot background subagent jobs: tool-jobs completion notices whose
+ *    summary starts with the job kind (`subagent <label> [status: …]`).
+ * The queue pane mirrors the inbox, but these belong to the task browser
+ * (terminal job rows / inactive child rows), so the mirror drops them and
+ * only failures surface as a transient error notify.
+ * @param source - the message source projection, or undefined for a plain row.
+ */
+declare function isSubagentSettlementNotice(source: QueueNoticeSource | undefined): boolean;
+/**
+ * Whether a subagent settlement notice reports FAILURE, classified on the
+ * producers' own deterministic wording:
+ *  - `subagent-settled` summaries: "finished and will do no further work"
+ *    is the only success wording; aborted / max-tokens / refusal / error /
+ *    unknown endings all fail;
+ *  - tool-jobs subagent summaries carry the terminal status line, whose
+ *    failure statuses are `failed` and `killed` (dsh JobStatus).
+ * A notice that cannot be classified is treated as success (silent).
+ * @param source - the message source projection.
+ */
+declare function subagentNoticeIsFailure(source: QueueNoticeSource | undefined): boolean;
+/** One inbox message as the queue mirror sees it (a structural projection). */
+interface QueueInboxMessage {
+  readonly id: string;
+  readonly content: readonly ContentBlock[];
+  readonly source?: QueueNoticeSource;
+}
+/** The mirror result for one inbox batch: the rows to show plus the failed
+ * settlement summaries the caller should notify (each once). */
+interface QueueFoldResult {
+  /** Queue rows (background-subagent settlement notices excluded). */
+  readonly rows: QueueItem[];
+  /** Failed settlement summaries not yet notified (the caller notifies). */
+  readonly failures: readonly string[];
+}
+/**
+ * Build the queue-pane rows for one inbox batch, dropping background-subagent
+ * settlement notices (the task browser is their surface) and reporting which
+ * FAILED settlements should notify. Pure and injectable so the filter +
+ * once-notify semantics are testable without the agent.
+ * @param messages - one inbox batch (next-turn or next-step), in order.
+ * @param mode - the delivery mode for surviving rows.
+ * @param notified - the notify-once guard; failed notices already in it are
+ *   skipped, and a newly-reported id is ADDED here so a re-render can never
+ *   double-notify.
+ */
+declare function foldQueueRows(messages: readonly QueueInboxMessage[], mode: 'followup' | 'steer', notified: Set<string>): QueueFoldResult;
 /**
  * Whether a shell command matches a destructive pattern. `rm` is treated
  * specially: any spelling of recursive + force flags (`rm -rf`, `rm -r -f`,
@@ -93,6 +319,17 @@ declare function runningProfile(argv?: readonly string[], fallback?: string): st
  * @returns the resume command line, or undefined without a session.
  */
 declare function resumeCommand(profile: string, sessionId: string): string | undefined;
+/**
+ * A launch-time open-lock refusal: the requested session is held by another
+ * live dsh process (or its lock cannot be verified). Unlike a stale/missing
+ * session id, this is NOT recoverable by falling back to a fresh session —
+ * the user asked for a specific session and must resolve the holder first.
+ * Thrown from the resume path and re-thrown past the resume catch so the
+ * runner exits with the refusal as the error message.
+ */
+declare class SessionLockRefusedError extends Error {
+  constructor(message: string);
+}
 /** One agent's preset composition: the id to record and the setup that installs it. */
 interface AgentComposition {
   /** Preset id for the session header, absent when the deployment composes no roster. */
@@ -168,4 +405,4 @@ declare function recomposeBlank(ctx: Context, agent: {
  */
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { AgentComposition, Config, LOCAL_COMMANDS, RecomposableSession, RecomposeOutcome, SESSIONLESS_COMMANDS, apply, composeAgent, dangerCommand, forkSeed, inject, name, recomposeBlank, recordedPreset, resumeCommand, runningProfile, shouldSteerOnEnter, subagentJobTranscriptId, subagentJobViewHint };
+export { AgentComposition, Config, InitialCatalogResolution, LOCAL_COMMANDS, QueueFoldResult, QueueInboxMessage, QueueNoticeSource, RecomposableSession, RecomposeOutcome, ResolveInitialCatalogOptions, SESSIONLESS_COMMANDS, SessionLockRefusedError, apply, composeAgent, dangerCommand, foldQueueRows, forkSeed, inject, isPlainExitPrompt, isSubagentSettlementNotice, name, recomposeBlank, recordedPreset, resolveInitialCatalog, resumeCommand, runningProfile, shouldConsumeAdvertisedMiss, shouldSteerOnEnter, subagentJobTranscriptId, subagentJobViewHint, subagentNoticeIsFailure };