@bendyline/gezel-service 0.1.0 → 1.0.0

package/dist/index.d.ts

@@ -289,6 +289,15 @@ interface ProjectFindingLifecycleEntry {
 type ProjectFindingLifecycle = Record<string, ProjectFindingLifecycleEntry>;
 interface StoreOptions {
     home: string;
+    /**
+     * Whether `home` is private to one OS user. On Unix these homes are created
+     * and repaired as 0700 so ordinary 0644 state files remain unreachable to
+     * other local accounts. System/machine homes must opt out because their
+     * installer-managed runtime discovery is intentionally shared.
+     *
+     * Defaults to true. Production system-scope stores opt out explicitly.
+     */
+    privateUserHome?: boolean;
     /**
      * Optional history recorder. When set, the Store emits audit events after
      * successful writes (create/rename/update/delete for gezels + projects +
@@ -348,6 +357,8 @@ declare class Store {
     private readonly external?;
     /** True for a `machine-engine` broker: engines and models, no product state. */
     private readonly engineOnly;
+    /** Whether the Store owns a home private to the current OS account. */
+    private readonly privateUserHome;
     private readonly poppetjes;
     private readonly documents;
     private readonly artifacts;
@@ -2589,10 +2600,18 @@ interface ProviderUsage {
     quotaBuckets: QuotaBucket[];
     todayTurns: number;
     todayTokensIn: number;
+    /**
+     * Portion of `todayTokensIn` the provider reported as prompt-cache reads.
+     * Zero both when nothing was cached and when the provider reports no
+     * breakdown (e.g. Copilot) — absence of data and absence of hits are
+     * indistinguishable here, so render 0 as "no cache info", not "0% hit".
+     */
+    todayTokensCached: number;
     todayTokensOut: number;
     todayCost: number;
     totalTurns: number;
     totalTokensIn: number;
+    totalTokensCached: number;
     totalTokensOut: number;
     totalCost: number;
     /**
@@ -2844,7 +2863,7 @@ declare class ProviderQueue {
     private readonly affinityWindowMs;
     private readonly maxWaitMs;
     /** See {@link ProviderQueueOptions.ambientQuietMs}. 0 = gate off. */
-    private readonly ambientQuietMs;
+    readonly ambientQuietMs: number;
     /**
      * Last time NON-ambient work touched this queue (enqueue, dispatch,
      * or release — any lane). Initialized to construction time so a
@@ -4853,16 +4872,47 @@ declare class ModelFitnessManager {
 }
 
 /**
- * Per-file semantic enrichment (the boekwachter's unit of work): produce an
- * optional one-paragraph summary via a local LLM, build embeddable chunks, and
- * store their vectors. Embeddings run locally (transformers.js) and are the
- * always-on part; the LLM summary is best-effort (skipped when no local model
- * is configured). Hash-gated by the caller via `filesNeedingEnrichment`.
+ * Who produced an LLM-written index row. Output-only bookkeeping — never an
+ * input to model routing. Absent fields stay NULL (rows written before the
+ * v10 migration, or deps built without a boekwachter) and renderers degrade
+ * to whatever segments exist.
+ */
+interface IndexProvenance {
+    provider?: string;
+    gezelId?: string;
+    gezelName?: string;
+    appVersion?: string;
+}
+
+/**
+ * AI-shadow producers: the second shadow-tree producer class. Office docs get
+ * deterministic squisq conversions in the STATIC pass; images and audio need
+ * a model — a vision description (+OCR) or an STT transcript — so they run in
+ * the idle-gated AI tier instead, writing the same
+ * `artifacts/shadow/<parent>/<basename>_files/<stem>.md` layout with a YAML
+ * frontmatter header carrying source hash + provenance.
  *
- * Deps are injected so this is unit-testable without a real model:
- *   - `summarize(prompt)` → summary text, or '' to skip (e.g. no LLM)
- *   - `embed(texts)`      → one vector per text
+ * The sidecar is the artifact; `shadow_state` is only the work gate. The
+ * frontmatter's `source_hash` makes the file self-describing: a rebuilt DB
+ * (home-fallback flip, deleted index) re-adopts a fresh sidecar without
+ * re-paying the model call.
  */
+interface AiShadowProducers {
+    /** Absolute image path → markdown body (description + OCR), null when unavailable. */
+    describeImage?: (absPath: string) => Promise<{
+        body: string;
+        model?: string;
+    } | null>;
+    /** Absolute audio path → markdown transcript body, null when unavailable. */
+    transcribeAudio?: (absPath: string) => Promise<{
+        body: string;
+        model?: string;
+    } | null>;
+}
+interface AiShadowDeps extends AiShadowProducers {
+    provenance?: IndexProvenance;
+}
+
 interface EnrichDeps {
     summarize: (prompt: string) => Promise<string>;
     embed: (texts: string[]) => Promise<number[][]>;
@@ -4874,6 +4924,20 @@ interface EnrichDeps {
      * configured; the review pass skips entirely then.
      */
     review?: (prompt: string) => Promise<string>;
+    /**
+     * Stamped onto every row this deps object writes. Built once in
+     * `buildEnrichDeps` from the SAME resolved target that builds the
+     * completions, so it reflects reality (env overrides, Night Shift) —
+     * output-only, never a routing input.
+     */
+    provenance?: IndexProvenance;
+    /**
+     * Live concurrent-one-shot width of the resolved target's queue. Full
+     * drives dispatch this many per-file scans at once instead of one; the
+     * value is re-read as slots free because a lazily-initialized provider
+     * reports 1 until its first call spins it up.
+     */
+    oneShotWidth?: () => number;
 }
 
 interface AreaPassResult {
@@ -4897,6 +4961,24 @@ interface ResolvedRubric {
     source: 'builtin' | 'override';
 }
 
+/**
+ * Pool options for the AI passes. `concurrency` is the live width of the
+ * summarizer target's queue (full drives pass it; background stays serial).
+ * `drain` switches a call from "one fixed batch" to "run to empty": the
+ * work-list is re-queried as slots open so the pool never sits idle at a
+ * batch tail. `shouldStop` (the indexing job's pause switch) is checked and
+ * `onProgress` fired at each refill — the same cadence the caller's old
+ * per-batch loop provided.
+ */
+interface EnrichDriveOpts {
+    concurrency?: () => number;
+    drain?: {
+        shouldStop?: () => Promise<boolean> | boolean;
+        onProgress?: (progress: {
+            files: number;
+        }) => void;
+    };
+}
 declare class ContentIndex {
     private readonly store;
     private readonly home;
@@ -4974,13 +5056,26 @@ declare class ContentIndex {
         summarized: number;
         embedded: number;
         pending: number;
+        skipped: number;
+        shadowsPending: number;
         embedModel?: string;
     } | null>;
-    enrich(projectId: string, deps: EnrichDeps, limit?: number): Promise<{
+    enrich(projectId: string, deps: EnrichDeps, limit?: number, opts?: EnrichDriveOpts): Promise<{
         files: number;
         summarized: number;
         embedded: number;
     } | null>;
+    /**
+     * Run one batch of the AI-shadow tier: describe images / transcribe audio
+     * into `artifacts/shadow/` sidecars. Runs BEFORE the summary tier so a
+     * produced shadow immediately joins the enrichment work-list. No-op when
+     * neither producer is wired (no vision model / no STT configured).
+     */
+    aiShadows(projectId: string, deps: AiShadowDeps, limit?: number): Promise<{
+        files: number;
+        produced: number;
+        called: number;
+    } | null>;
     /**
      * Cheap existence probe — true when a content index db is on disk for
      * this project. File-stat only; never opens (an open would CREATE the
@@ -5008,7 +5103,7 @@ declare class ContentIndex {
      * whole night budget in timeouts). Rubrics can be injected (one resolve per
      * manager tick; also the test seam). Null when no index exists.
      */
-    review(projectId: string, deps: EnrichDeps, limit?: number, rubrics?: Map<string, ResolvedRubric>): Promise<{
+    review(projectId: string, deps: EnrichDeps, limit?: number, rubrics?: Map<string, ResolvedRubric>, opts?: EnrichDriveOpts): Promise<{
         files: number;
         reviewed: number;
     } | null>;
@@ -10229,6 +10324,15 @@ declare class ChatManager {
     }): Promise<ProviderName>;
     /** Return the provider if it has already been initialized; never creates one. */
     getProviderIfReady(name: ProviderName): LLMProvider | null;
+    /**
+     * Concurrent one-shot width for a provider: its queue's configured
+     * concurrency once initialized (singleton or pooled local engine), else 1.
+     * Bulk callers (index drives) dispatch width-many one-shots to keep the
+     * queue full — the queue still arbitrates its interactive/background lanes.
+     * Live value: an uninitialized provider reports 1 and widens after the
+     * first call spins it up, so callers should re-read between dispatches.
+     */
+    oneShotQueueWidth(name: ProviderName): number;
     /**
      * Snapshot of the Claude CLI worker pool, enriched with gezel + project
      * display names so the UI pill can render "Maya · Atari Adventure
@@ -11924,6 +12028,13 @@ interface TaskRunnerOptions {
      * to "always pending" (only the active-shift gate applies).
      */
     isNightShiftPending?: (task: Task) => boolean;
+    /**
+     * True while the night-shift index catch-up sweep runs. Night-shift
+     * handoffs stay held on the queue until it finishes, so batch work starts
+     * against a current static + AI index instead of racing the indexer for
+     * the engine. Defaults to never-active.
+     */
+    isIndexCatchUpActive?: () => boolean;
 }
 declare class TaskRunner {
     private readonly store;
@@ -11932,6 +12043,7 @@ declare class TaskRunner {
     private readonly now;
     private readonly isNightShiftActive;
     private readonly isNightShiftPending;
+    private readonly isIndexCatchUpActive;
     private readonly pending;
     private readonly activeDispatches;
     private nextId;
@@ -12108,6 +12220,13 @@ declare class WorkspaceIndexManager {
      *   - on-mount of the Commands panel when status is `never`
      */
     refresh(projectId: string): Promise<WorkspaceIndexStatus>;
+    /**
+     * Like {@link refresh}, but awaits the whole scan (structural pass + the
+     * content-index refresh it drives). For callers that sequence work on a
+     * CURRENT index — the on-demand enrichment drive and the night-shift
+     * catch-up must not summarize/review against yesterday's file list.
+     */
+    refreshAndWait(projectId: string): Promise<WorkspaceIndexStatus>;
     /**
      * Periodic tick: pick the highest-priority stale project and index
      * exactly one. One project per tick keeps the loop bounded; with a
@@ -12599,6 +12718,39 @@ interface IndexEnrichmentManagerOptions {
     events?: Pick<ChatEventBus, 'publishGlobalEvent'>;
     /** Test seam; production resolves the role from each project's roster. */
     resolveBoekwachter?: (projectId: string) => Promise<GezelDetail | null>;
+    /**
+     * AI-shadow producers (vision describe / STT transcribe). Absent when the
+     * install has neither capability; the shadow tier is skipped entirely then.
+     */
+    shadowProducers?: AiShadowProducers;
+    /** Audit log for the once-per-wave `project.index.reviewed` drain event. */
+    history?: {
+        log: (event: Omit<HistoryEvent, 'id' | 'at'> & {
+            at?: string;
+            id?: string;
+        }) => Promise<void>;
+    };
+    /**
+     * Awaitable structural refresh (WorkspaceIndexManager.refreshAndWait) run
+     * at the head of every drive so the AI tiers see current files. When
+     * absent (tests), the drive falls back to `contentIndex.refresh` directly.
+     */
+    refreshStatic?: (projectId: string) => Promise<unknown>;
+}
+/**
+ * On-demand drive intensity:
+ *   - `background` — start now (skip the idle wait) but stay polite: ambient
+ *     one-shots that the local engine holds behind live chat, day-size
+ *     batches.
+ *   - `full` — occupy the engine: non-ambient one-shots that compete like any
+ *     interactive work, night-size batches, run to drain without yielding.
+ * Both honor the indexing job's pause switch between batches.
+ */
+type DriveIntensity = 'background' | 'full';
+interface DriveOptions {
+    intensity: DriveIntensity;
+    /** Run the review tier after summaries drain (default true). */
+    reviews?: boolean;
 }
 declare class IndexEnrichmentManager {
     private readonly store;
@@ -12612,6 +12764,13 @@ declare class IndexEnrichmentManager {
     private readonly isPaused;
     private readonly events;
     private readonly resolveBoekwachter;
+    private readonly shadowProducers;
+    private readonly history;
+    private readonly refreshStatic;
+    /** In-flight on-demand drives, one per project (joiners get the same run). */
+    private readonly drives;
+    /** Nonzero while a night-shift catch-up sweep is holding task dispatch. */
+    private catchUpRuns;
     private startupTimer;
     private tickTimer;
     private running;
@@ -12621,6 +12780,42 @@ declare class IndexEnrichmentManager {
     stop(): void;
     /** Live, durable-for-the-tick status consumed by the Night Shift menu. */
     getActivity(): IndexEnrichmentActivity | null;
+    /**
+     * Emit the once-per-wave `project.index.reviewed` audit event: only on the
+     * transition where this tick stored reviews AND the queue is now empty.
+     * Per-file events would flood the ~150-kind flat log (day batches alone
+     * would emit dozens per sweep); the drain is the meaningful moment.
+     */
+    private logReviewDrain;
+    /**
+     * True while a night-shift catch-up sweep runs — the TaskRunner holds
+     * night-shift task dispatch on it so batch work starts against a current
+     * index, per the explicit "index first, then tasks" activation contract.
+     */
+    isCatchUpActive(): boolean;
+    /** True while an on-demand drive is running (optionally for one project). */
+    isDriving(projectId?: string): boolean;
+    /** Mode of the drive running for a project, or null when idle. */
+    driveMode(projectId: string): DriveIntensity | null;
+    /**
+     * Start an on-demand drive for one project: static refresh first, then the
+     * AI tiers (shadows → summaries → areas → reviews) to drain. Returns
+     * immediately; progress flows over the usual `index_progress` events and
+     * `/index/status` polling. One drive per project — a second request joins
+     * the running one.
+     */
+    drive(projectId: string, opts: DriveOptions): {
+        started: boolean;
+        alreadyRunning: boolean;
+    };
+    /**
+     * Bring every indexing-enabled project's static AND AI index up to date,
+     * sequentially at full intensity — the night-shift activation sweep. The
+     * catch-up flag is raised synchronously so a caller that kicks this (not
+     * awaited) and then wakes the TaskRunner still gets the dispatch hold.
+     */
+    catchUpAll(): Promise<void>;
+    private runDrive;
     /** Exposed for tests: run one batch ignoring the timers (still idle-gated). */
     tick(): Promise<void>;
     private isIdle;