@xmoon76/dsh-pi-tui 0.1.4 → 0.1.5

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.
@@ -60,11 +149,66 @@ 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;
@@ -168,4 +312,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, RecomposableSession, RecomposeOutcome, ResolveInitialCatalogOptions, SESSIONLESS_COMMANDS, apply, composeAgent, dangerCommand, forkSeed, inject, name, recomposeBlank, recordedPreset, resolveInitialCatalog, resumeCommand, runningProfile, shouldConsumeAdvertisedMiss, shouldSteerOnEnter, subagentJobTranscriptId, subagentJobViewHint };