@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.21

package/lib/index.d.ts

@@ -0,0 +1,241 @@
+import Schema from '@deepseek-ai/schemastery';
+import { type PresetRegistryLike } from './preset.ts';
+import { type SyncScheduler } from './sync.ts';
+/** The cordis surface this entry touches; widened in later stages. */
+interface HostCtx {
+    logger?: {
+        info?: (message: string) => void;
+        warn?: (message: string) => void;
+    };
+    get?: (name: string) => unknown;
+    /** Cordis event subscription — door 5 registers the subagent-end listener here. */
+    on?: (name: string, fn: (info: never) => void) => unknown;
+    effect?: (fn: () => void, label?: string) => void;
+    agents?: unknown;
+    tools?: {
+        register(def: unknown): () => void;
+    };
+    sessionProjections?: {
+        stateOf(session: unknown, key: string): unknown;
+    };
+    llm?: {
+        resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<{
+            context?: {
+                contextWindow?: number;
+            };
+        } | undefined>;
+        stream?: (opts: unknown) => AsyncIterable<unknown>;
+        /** #173 catalog discovery — host-shaped: listProviders is SYNC (the host's own
+         * list_subagent_models tool consumes it that way), listModels is the advisory catalog. */
+        listProviders?: () => readonly {
+            id: string;
+            name: string;
+        }[];
+        listModels?: (provider: string) => Promise<readonly {
+            provider: string;
+            id: string;
+            name: string;
+            description?: string;
+        }[]>;
+    };
+}
+export interface Config {
+    /** @deprecated the preset is a declaration row now (`preset-chapters` in
+     *  cordis.patch.yml); `disabled: true` on that row is the switch, and the engine
+     *  threshold is `thresholdRatio` on its realm row. Accepted so an old profile patch
+     *  keeps parsing — nothing reads it. */
+    installChaptersPreset: boolean;
+    /** @deprecated see above; row config, not host config. */
+    compactionThresholdRatio: number;
+    artifactStoreRoot: string;
+    chapterTokenTarget: number;
+    toolResultDeferFloorTokens: number;
+    continuationBudgetRatio: number;
+    fallbackPreset: string;
+    mergeThreshold: number;
+    /**
+     * Door 5 (issue #47): archive a chapters-preset subagent's completed turns when
+     * its run settles (`subagent/end`). Save-only — no session, no compaction,
+     * enrichment queued never run. false = the listener never registers.
+     */
+    subagentAutoSave: boolean;
+    chapterLimit: number;
+    /** Past `chapterTokenTarget × this` a door refuses the archive (#59). ≥1; 2 by default. */
+    chapterOversizeFactor: number;
+    /**
+     * #61 loudness. How many warning TEXTS a door prints before switching to `…and M more`. The field
+     * failure was delivery, not detection: 86 warnings — naming a hollow chapter and an unarchived
+     * 0-4082 hole — reached a human as `(86 warning(s))`.
+     */
+    warningsDisplayCap: number;
+    /**
+     * #61: token ceiling on the oversized-result candidate list `chapters_segment` returns. Measured at
+     * 49,932 chars emitted while ALSO reporting `Omitted 275266 bytes`, ≈81K est tokens into a 32K-class
+     * window — the model was asked to judge a list it never received.
+     */
+    segmentCandidateCapTokens: number;
+    /**
+     * #61: where door/child failures are appended. Empty (the default) resolves to
+     * `<store-root>/diagnostics.log`; the literal `off` disables the file sink, and
+     * `DSH_CHAPTERS_ENGINE_ERRORS` overrides everything. Before this, unset meant NO TRACE ON DISK.
+     */
+    diagnosticsLog: string;
+    diagnosticsMaxBytes: number;
+    /** Plans (docs/plans-carriage.md § 7): verbatim plan chars shown in a chapter,
+     * the tool-call-argument artifact floor (0 = off), and whether the notice
+     * carries the `## Plans on this path` block. */
+    planInlineChars: number;
+    callArgArtifactTokens: number;
+    plansInNotice: boolean;
+    /** Teach the child its lookup verbs (read / chapters_artifact / chapters_search). */
+    retrievalHints: boolean;
+    /** Seed plan mode into continuation children (plans-carriage § 10). */
+    planSeedMode: boolean;
+    /** Carry the operative plan into every in-place checkpoint (§ 9). */
+    plansInCheckpoint: boolean;
+    planCheckpointChars: number;
+    harnessId: string;
+    /** §12: the project's knowledge repo URL ('' = rely on /chapters-link). */
+    knowledgeRemote: string;
+    /** §12: wins over the §2.3 derivation. */
+    projectKeyOverride: string;
+    /** §12: coalesce window for post-archive pushes. */
+    syncDebounceMs: number;
+    /** §12: default pack size for chapters_search. */
+    searchDefaultMaxTokens: number;
+    /** P2 §12: enrichment kill switch (auto triggers live on the realm plane;
+     * the host plane's queue is manual-only so nothing ever double-runs). */
+    enrichmentEnabled: boolean;
+    /** 'provider/model' or '' = conversation/stored route (record §6). */
+    enrichmentModel: string;
+    enrichmentIdleMs: number;
+    /** One auxiliary completion budget: annotation+mining and the conflicts report.
+     * Must cover reasoning tokens, not just the visible JSON (record §6.1, #50). */
+    enrichmentMaxTokens: number;
+    enrichmentBatchCap: number;
+    /** P2 §6.3 vocabulary pass (shadow by default). */
+    vocabApply: boolean;
+    vocabCoMin: number;
+    vocabOverlapMin: number;
+    /** P3 §7.3: budget for the notice's core-rules section (refuse, never clip). */
+    coreRulesBudgetTokens: number;
+    /** P3 §8: search bonus for effective-core rules (per-machine status). */
+    rulesCoreBonus: number;
+    /** #50 §7.5: deterministic `ADD RULE:` capture into the local session tier. */
+    sessionRulesEnabled: boolean;
+    /** #50 §7.5: the capture marker, matched at line start of human messages. */
+    rulesMarkerPrefix: string;
+    /** #50 §7.4: per-tier count caps on rules rendered into a rebuilt head. */
+    projectRulesDisplayCap: number;
+    /** #50 §7.4: session-tier display cap. */
+    sessionRulesDisplayCap: number;
+    /** #50 §7.4: topic-overlap selection on; off ⇒ deterministic category→id order. */
+    rulesRelevance: boolean;
+    /** #50 §7.5: mine standing orders during enrichment. Default ON — background
+     * capture is the whole point; the verbatim-quote gate (not a click) is what
+     * keeps a guess from steering a session. */
+    rulesEnrichment: boolean;
+    /** #50 §7.5: per-chapter cap on mined rules. */
+    rulesMinedPerChapter: number;
+    /** #50 §7.5: mined rules govern on arrival (default true); false holds them for review. */
+    rulesAutoActivate: boolean;
+    /** #50 §7.5: 'provider/model' for a dedicated mining call; '' ⇒ the annotation pass. */
+    rulesModel: string;
+    /** #71 site §28: the model that DEFINES the next work. '' ⇒ the feature does
+     * not exist; setting one (here or `/chapters-prompt model …`) IS the enable —
+     * one knob, no second boolean that could drift against it. */
+    promptModel: string;
+    /** #71: hard total budget on the assembled suggest input. */
+    promptContextChars: number;
+    /** #71: cap on the recommendation itself; over-cap ⇒ retry once ⇒ refuse (never truncate). */
+    promptMaxChars: number;
+    /** #188: share of the prompt model's context window the derived input budget takes. */
+    promptContextRatio: number;
+    /** #229: seconds between ambient state pulls while the bar is idle — the heartbeat that produced a
+     * durable command pair per tick (measured: exact 60.0s gaps on the maintainer's live log). Default
+     * ZERO: no ambient clock exists; sanctioned moments (mount discovery, turn-end pulse, visibility)
+     * remain. A nonzero value re-arms the heartbeat for hosts that want freshness over silence. */
+    promptQuietHeartbeatSec: number;
+    /** #113: how many turns an armed autorun may start before it stops and says so. Re-arming does NOT
+     * refresh it, so arming cannot become an infinite loop; the budget is per process, like the flag. */
+    promptMaxRounds: number;
+    /** #117: cap on the printed `/chapters-repair` report, so one dry-run cannot emit 300 KB into a 32K window. */
+    repairReportMaxLines: number;
+    /** §15 amendment: transport policy — 'auto' dispatches on the remote
+     * scheme (treedx+ → TreeDX, anything else → git); an explicit value must
+     * match the scheme or the link refuses (never a silent fallback). */
+    knowledgeProvider: 'auto' | 'git' | 'treedx';
+    /** TreeDX transport tunables (record §12 register: no hardcoded numbers). */
+    treedxFetchTimeoutMs: number;
+    treedxWorkspaceTtlSeconds: number;
+    treedxLeaseRetries: number;
+    treedxLeaseRetryDelayMs: number;
+    /** Optional CodeGraph integration: auto-detect the CLI on PATH and enrich
+     *  signatures, search scoring, and enrichment input with structural code
+     *  intelligence. The integration is invisible to the model — it makes
+     *  chapters_search return better results, not a competing tool surface.
+     *  false = hard off. */
+    codegraphEnabled: boolean;
+    /** Add CodeGraph structural context to enrichment slices. */
+    codegraphEnrich: boolean;
+    /** Per-symbol search score bonus for chapters with matching codegraphSymbols. */
+    codegraphSearchBonus: number;
+}
+export declare const Config: Schema<Config>;
+export declare const name = "@fractalsynapse/dsh-chapters";
+export declare const inject: string[];
+export declare function apply(ctx: HostCtx, config: Config): Promise<void>;
+/**
+ * The §5 sync loop for the host plane. Auto-link (when `knowledgeRemote` is
+ * configured) happens lazily inside resolveProject: a workspace's first
+ * archive event finds a project record, so nothing network-shaped runs
+ * before anything archives.
+ */
+export declare function createScheduler(store: import('./store.ts').RegistryStore, domain: import('./store.ts').DomainLike, config: Config, debounceOverride?: number, onSyncDone?: (cwd: string, ok: boolean) => void, warn?: (m: string) => void): SyncScheduler;
+/**
+ * Why delivery is a `register()` call and not a file, in one incident: hosts from
+ * 0.1.7-alpha.1 stopped reading `$DSH_HOME/.agent-presets/` — a preset is an
+ * `@deepseek-ai/dsh-agent-preset` declaration row — while the plugin kept copying,
+ * kept logging that it had mounted, and the preset was simply GONE. That is worse
+ * than a crash, because `resume` resolves the preset id recorded in the session's
+ * own log and throws `agent-preset/not-found`, so every chapters session became
+ * unopenable while its durable log sat there intact and uncorrupted.
+ *
+ * Shipping the row as a patch layer instead is what a reader will reach for, and it
+ * is a boot-breaking choice on the hosts this plugin used to support: `dsh.bundle.patch`
+ * as an array throws `ERR_INVALID_ARG_TYPE` at legacy `dsh-app-boot/lib/index.js:853`,
+ * an unresolvable row aborts a legacy plugin tree, and `disabled: !!js` cannot gate the
+ * row because the Loader evaluates `disabled` before any service is mounted (all three
+ * measured). Support floor is 0.2.0 now, so the row is registered here through the
+ * host's own `agentPresets.register()` — the same call its declaration-row plugin makes.
+ */
+/** What the host roster says about our preset. */
+export type RosterVerdict = {
+    state: 'present';
+    broken?: string;
+} | {
+    state: 'absent';
+    rows: string[];
+} | {
+    state: 'unknown';
+    error: string;
+};
+/** Ask the host which presets exist. Tolerates both shapes the service has
+ *  offered: the bare row array (`list()`) and the remote envelope (`{presets}`). */
+export declare function readRosterVerdict(presets: {
+    list?: () => Promise<unknown>;
+} | undefined, presetId: string): Promise<RosterVerdict>;
+/**
+ * The remedy for an absent preset. It is a configuration fact about someone else's tree —
+ * a patch layer can be overridden or disabled by a profile we do not own — so the job is to
+ * name where to look, never to retry behind the operator's back.
+ */
+export declare function rosterRemediation(presetId: string): string;
+/** Deferred boot check: one truthful line about the preset, plus the verdict for the witness.
+ * Exported so the four arms of that line are tested without booting a host — the line IS the
+ * health signal a user reads, and an untested health signal is how the silent case survived. */
+export declare function reportPresetRoster(ctx: HostCtx, presetId: string): Promise<RosterVerdict>;
+/** One phrase describing what the host's inventory says about the preset's own rows.
+ *  Never throws: an unavailable inventory must degrade the line, not the boot check. */
+export declare function describeMountedRows(presets: PresetRegistryLike | undefined, presetId: string): Promise<string>;
+export {};