@mstar-harness/dsh 3.5.1 → 3.6.0-alpha.2

package/dist/gates/fallbacks-decoration.d.ts

@@ -1,108 +0,0 @@
-/**
- * Role-based subagent decoration at the `subagent/start` seam (plan
- * `20260814-dsh-fallbacks-integration` Task 2).
- *
- * Decoration rides the `subagent/start` EMIT — NOT `tools/pre-execute`:
- * tool args are deep-frozen snapshots and persona/`agentOptions` come from
- * the tool-subagent's own Config, never call args. The listener is
- * SYNCHRONOUS (the section must register before the child's first LLM call)
- * and resolves the published child via `ctx.get('agents')?.get(info.id)` —
- * documented in the `@deepseek-ai/dsh-subagent` event contract ("For
- * in-process providers, `ctx.agents.get(info.id)` resolves during this
- * notification"). The registered section is agent-scoped on `Agent.ctx`
- * (contributions are agent-local and unwind on disposal — the
- * hooks-claude-code precedent).
- *
- * Role identity uses the engine Assignment header grammar — the SAME
- * parsers the dispatch gate uses (`assignmentHeaderRegion` +
- * `parseAssignmentFields`) — over the child's seeded task prompt (the
- * child session's first `user/message`). Persona lookup (plan
- * `20260815-dsh-fallbacks-personas` Task 3) is the single
- * {@link personaFor} surface — `Config.rolePersonas[executeAs]` →
- * `harness-agents/` mirror default → skip (never gated on `roleMap` or on
- * the fallbacks mounted state: unmounted fallbacks degrades to the same
- * injection with exactly one debug log; probe at the decision point, no
- * cache). `roleMap` is a taxonomy bridge for logging + future rule-driven
- * interop only. The mirror root is bound at apply (`setDecorationAgentsDir`
- * ← `packagedAgentsDir()`), package-relative so the shipped bundle works
- * from any launch cwd.
- *
- * Degradation (the listener never throws — contained like the dispatch
- * gate's degrade path): `agents` service absent → skip + one debug log
- * (documented Known Limitation for compositions without dsh-agent);
- * child unresolved / non-Assignment / role-unmatched → silent no-op
- * (role-unmatched with the mirror present and no eligible shell stays
- * silent; with NO mirror the config-miss path logs ONE debug per apply —
- * case (e) semantics). A throwing log sink is contained inside the log
- * helper itself (plan QC F-002) — the sink must not escape the listener
- * either.
- *
- * Persona text is rendered by dsh system-prompt's STRICT `{{...}}`
- * interpolation, so persona values MUST NOT contain `{{` paired with a
- * later `}}` — the Config schema rejects such values at plugin mount (see
- * `_shared.ts` `rolePersonas` / `PERSONA_INTERPOLATION_HAZARD`); a mirror
- * default carrying the hazard is warned + skipped at extraction (never a
- * boot throw).
- *
- * Module boundary: no barrel — the entry imports this module by explicit
- * relative path and re-exports the public names verbatim.
- */
-import type { Context } from '@deepseek-ai/cordis';
-import type { Config } from './_shared.ts';
-/** Logger label for the subagent decoration (dsh logger naming: `<scope>/<subject>`). */
-export declare const DECORATION_LOGGER = "mstar/subagent-decoration";
-/** The decoration's system-prompt section name (agent-scoped on `Agent.ctx`). */
-export declare const PERSONA_SECTION_NAME = "mstar:role-persona";
-/** Prompt order of the persona section — renders right after the deployment persona slot (order 0). */
-export declare const PERSONA_SECTION_ORDER = 1;
-/**
- * Structural view of the `subagent/start` emit payload the decoration
- * consumes (`@deepseek-ai/dsh-subagent` `SubagentRunInfo` — the plugin
- * carries no dsh-subagent dependency; same pattern as the probe's
- * `LoaderEntryView` and agent-flow's `TaskDoneSnapshot`). Only `id` is
- * consumed; the rest keeps the view faithful to the published contract.
- */
-export interface SubagentRunInfoView {
-    /** Unique identity shared with the paired terminal event. */
-    readonly runId: unknown;
-    /** Provider name recorded when the child was first created. */
-    readonly provider: string;
-    /** The child agent's id. */
-    readonly id: string;
-    /** Snapshot of whether the run's local agent was present when start fulfilled. */
-    readonly local: boolean;
-}
-/** Decoration log levels the module sink understands. */
-export type DecorationLogLevel = 'debug' | 'info' | 'warn';
-/** Module-level decoration log sink — bound by `apply` to `ctx.logger(DECORATION_LOGGER)` (agent-flow ledger precedent). */
-export type DecorationLogSink = (level: DecorationLogLevel, message: string) => void;
-/**
- * Bind the decoration log sink (the entry `apply` binds it to
- * `ctx.logger(DECORATION_LOGGER)`). Returns the PRIOR sink so a caller can
- * restore it (test pattern: agent-flow `setAgentFlowLogger`).
- */
-export declare function setDecorationLogger(sink: DecorationLogSink): DecorationLogSink;
-/**
- * Bind the persona-defaults mirror root. Returns the PRIOR binding so a
- * caller can restore it (test pattern: {@link setDecorationLogger}).
- * @param dir - the mirror root, or `undefined` to disable mirror defaults.
- */
-export declare function setDecorationAgentsDir(dir: string | undefined): string | undefined;
-/**
- * Decorate one `subagent/start` emit: resolve the child, extract its seeded
- * task prompt, and — when the prompt is Assignment-shaped and
- * `rolePersonas[executeAs]` is configured — register the persona as the
- * child's `mstar:role-persona` system-prompt section (agent-scoped on
- * `Agent.ctx`, unwinds on child disposal). Synchronous by design: the
- * section must register before the child's first LLM call.
- *
- * Never throws — every failure mode degrades (skip + one log line at most),
- * matching the dispatch gate's contained degrade path; the dispatch itself
- * is never affected.
- *
- * @param ctx - the plugin's registrant context (the app composition root).
- * @param config - validated plugin configuration (`rolePersonas` is the only
- *   payload source; `roleMap` is never consulted for injection).
- * @param info - the `subagent/start` emit payload.
- */
-export declare function decorateSubagentStart(ctx: Context, config: Config, info: SubagentRunInfoView): void;