@noir-ai/daemon 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agaaaptr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# @noir-ai/daemon
+
+The runtime authority: owns the store write handle, resolves the embedder once, and exposes the single Noir MCP server (stdio + Streamable HTTP). Store-touching CLI commands are MCP clients to this daemon; a read-only filesystem fallback covers the daemon-down case.
+
+Part of the **[Noir](https://github.com/agaaaptr/noir#readme)** toolkit — the discipline, context, and memory layer for any agentic CLI.
+
+## Install
+
+```bash
+npm install @noir-ai/daemon
+```
+
+> Most users install the CLI instead, which manages the daemon lifecycle (`noir daemon start|stop|status`):
+>
+> ```bash
+> npm install -g @noir-ai/cli
+> ```
+
+## License
+
+MIT © agaaaptr

package/dist/index.d.ts

@@ -0,0 +1,324 @@
+import { EmbedderConfig, ContextEngine, EmbedFn } from '@noir-ai/context';
+export { ContextStatus } from '@noir-ai/context';
+import { ProjectId, ProjectInfo } from '@noir-ai/core';
+import { Store } from '@noir-ai/store';
+import { MemoryConfig, MemoryEngine } from '@noir-ai/memory';
+import { ResolvedModelConfig } from '@noir-ai/model';
+import { McpServer } from '@modelcontextprotocol/server';
+import { WorkflowEngine, Phase, WorkflowState, Mode, GateResult } from '@noir-ai/workflow';
+
+/**
+ * Build the daemon's {@link ContextEngine} from its already-open store handle
+ * + the project `root` + `projectId` + a resolved {@link EmbedderConfig}.
+ *
+ * One engine per serve lifecycle — constructed once alongside the store (see
+ * {@link openStoreForDaemon}) and the workflow engine (see
+ * {@link buildWorkflowEngine}), and reused across every HTTP request, exactly
+ * as those handles are. The engine resolves its embedder once (a lazy local
+ * model loads at most once per lifecycle) and then owns the indexer (the only
+ * context writer) + the retriever (the only context reader) over the SAME
+ * injected handle — it never opens a second connection, so the daemon's
+ * single-writer discipline is preserved (blueprint D6: in-process, no sidecar,
+ * canonical `ProjectId`).
+ *
+ * Degraded story (mirrors the store + the engine's own contract): pass the
+ * store's `storeDegraded` flag so the engine's persistent `degraded` field is
+ * honest — `context_status` then reports `degraded:true` for a read-only
+ * (daemon-down) handle, and `context_index` short-circuits with a clear error
+ * envelope instead of letting the first write throw mid-run. A `kind:'none'`
+ * embedder on a WRITABLE store is NOT blocking here: docs still index without
+ * vectors (the indexer's tested degraded path), so only the read-only case is
+ * fenced off at the tool boundary.
+ */
+declare function buildContextEngine(store: Store, root: string, projectId: ProjectId, embedderCfg: EmbedderConfig, storeDegraded?: boolean): ContextEngine;
+
+interface EnsureResult {
+    port: number;
+    url: string;
+    started: boolean;
+    /**
+     * Stops the daemon THIS call started. When `started` is true this closes the
+     * in-process http server, clears `daemon.json`, and clears the idle timer.
+     * When `started` is false (a healthy daemon was reused) this is a no-op: the
+     * reused daemon is owned by whichever process started it (in tests that pid is
+     * `process.pid`, so killing it would be fatal) and must not be torn down by a
+     * mere consumer.
+     */
+    stop: () => Promise<void>;
+}
+declare function ensureDaemonRunning(opts: {
+    project: ProjectInfo;
+    idleTimeoutSec: number;
+}): Promise<EnsureResult>;
+
+interface StartHttpOptions {
+    project: ProjectInfo;
+    port?: number;
+    idleTimeoutSec: number;
+}
+interface RunningDaemon {
+    port: number;
+    pid: number;
+    startedAt: number;
+    stop: () => Promise<void>;
+}
+declare function startHttpServer(opts: StartHttpOptions): Promise<RunningDaemon>;
+
+interface DaemonRecord {
+    pid: number;
+    port: number;
+    startedAt: number;
+}
+declare function noirHome(): string;
+declare function daemonJsonPath(): string;
+declare function readDaemonRecord(): DaemonRecord | null;
+declare function writeDaemonRecord(rec: DaemonRecord): void;
+declare function clearDaemonRecord(): void;
+declare function pidAlive(pid: number): boolean;
+
+/**
+ * Derive the consolidation provider + model id from a resolved MODEL config —
+ * the MODEL-DERIVED FALLBACK used ONLY when the user enabled consolidation
+ * under `memory:` but did NOT name a provider there (see
+ * {@link resolveConsolidationCapability}). Blueprint D5/D6 — provider-EXPLICIT,
+ * never env-inferred.
+ *
+ * The provider is resolved ONLY from an explicit opt-in: the `consolidate` tier
+ * key, falling back to `defaultProvider`. Env-var presence is NEVER consulted
+ * (DS-6) — `ANTHROPIC_API_KEY` being set for another tool does NOT activate
+ * consolidation here. A provider is "consolidation-capable" only when that key
+ * resolves to a configured provider block that itself declares a `model` id;
+ * otherwise this returns `null`.
+ *
+ * NOTE: this function ALONE is NOT the consolidation gate — it ignores the
+ * user's `memory.consolidation.enabled` master switch. The AND of that switch
+ * with this derivation (and with the memory-block provider) lives in
+ * {@link resolveConsolidationCapability}, which is what the daemon wiring +
+ * {@link buildMemoryEngine} actually consult to decide tool registration.
+ */
+declare function resolveMemoryConsolidation(modelCfg: ResolvedModelConfig | undefined): {
+    provider: string;
+    model: string;
+} | null;
+/**
+ * The consolidation capability gate — the SINGLE source of truth both
+ * {@link buildMemoryEngine} and the daemon wiring (stdio/http) consult to decide
+ * (a) whether the `memory_consolidate` MCP tool registers and (b) whether the
+ * engine's `consolidate` can run. Returns the usable `{provider, model}` when
+ * consolidation is ON, or `null` when it must be fully off.
+ *
+ * The gate is the AND of ALL three (blueprint D6 / §9 — NEVER a silent paid
+ * call, the Agent-Memory anti-pattern):
+ *  (a) `resolvedMemory.consolidation.enabled === true` — the user's EXPLICIT
+ *      master switch under `memory:`. This is the LOAD-BEARING gate: a config
+ *      with no `memory:` block (or `enabled:false`) resolves to `null`
+ *      REGARDLESS of `model.defaultProvider`, so a `model:` block set for
+ *      summarize/title/draft does NOT silently enable a paid consolidation call.
+ *  (b) a usable provider+model — prefer the one named under `memory:` (with its
+ *      own `model` id); fall back to the MODEL-derived derivation
+ *      ({@link resolveMemoryConsolidation}) ONLY when the user enabled
+ *      consolidation but did NOT name a provider under `memory:`.
+ *  (c) the resolved pair has both a `provider` and a `model` id.
+ *
+ * `resolvedMemory` is the output of `resolveMemoryConfig(config.memory)` — the
+ * pure core→memory bridge (no env inference, no cycle). Pure projection — reads
+ * NO env, holds NO secrets, never throws. Whether the provider is actually
+ * CALLABLE at runtime (key present, network up) is decided inside `complete()`
+ * (S8) — here we only decide config-time capability.
+ */
+declare function resolveConsolidationCapability(resolvedMemory: MemoryConfig | undefined, modelCfg: ResolvedModelConfig | undefined): {
+    provider: string;
+    model: string;
+} | null;
+/**
+ * Build the daemon's {@link MemoryEngine} from its already-open store handle +
+ * the project `root` + `projectId` + the SAME `EmbedFn` the daemon resolved once
+ * for S6 (the daemon owns one embedder; memory takes `{store, embed, ...}`, no
+ * embedder duplication — plan §Architecture).
+ *
+ * One engine per serve lifecycle — constructed once alongside the store (see
+ * {@link openStoreForDaemon}), the workflow engine (see
+ * {@link buildWorkflowEngine}), and the context engine (see
+ * {@link buildContextEngine}), and reused across every HTTP request, exactly as
+ * those handles are. The engine — like the context indexer — is the ONLY thing
+ * that writes `source:'memory'` rows through the injected handle; it never opens
+ * a second connection, so the daemon's single-writer discipline is preserved
+ * (blueprint D6: in-process, no sidecar, canonical `ProjectId`).
+ *
+ * Consolidation is OPT-IN + provider-explicit (DS-6 / §9 — NEVER a silent paid
+ * call). The capability gate is {@link resolveConsolidationCapability} — the AND
+ * of the user's `memory.consolidation.enabled` master switch (the load-bearing
+ * gate), a usable provider+model (preferring the `memory:` block, falling back
+ * to the model-derived derivation when enabled but no provider named under
+ * `memory:`), and `modelCfg` being present to bind S8's `complete`. When the
+ * gate resolves a `{provider, model}`:
+ *   - S8's {@link complete} is bound as the engine's model injection, AND
+ *   - the runtime gate `config.consolidation` is set so `consolidate` can run.
+ * When the gate is `null` — most importantly when `enabled === false`, regardless
+ * of `model.defaultProvider` — NO model is wired and `engine.consolidate`
+ * self-refuses (`'no-provider'`) WITHOUT calling the model. The daemon registers
+ * the `memory_consolidate` MCP tool only in the capable case.
+ *
+ * `resolvedMemory` is the output of `resolveMemoryConfig(config.memory)` — the
+ * pure core→memory bridge. Passing it here means the engine's `config` reflects
+ * the user's `memory:` consent exactly (never a hardcoded `enabled:true`).
+ *
+ * Degraded story (mirrors the store + the context engine): pass the store's
+ * `storeDegraded` flag so the engine's persistent `degraded` field is honest —
+ * `memory_save` / `memory_forget` then refuse with a clear envelope (the engine
+ * throws upfront on a read-only handle) while reads (`memory_recall` /
+ * `memory_search` / `memory_sessions`) keep working off the same handle.
+ */
+declare function buildMemoryEngine(store: Store, root: string, projectId: ProjectId, embed: EmbedFn, modelCfg?: ResolvedModelConfig, storeDegraded?: boolean, resolvedMemory?: MemoryConfig): MemoryEngine;
+
+type Transport = 'stdio' | 'streamable-http';
+interface HostStatus {
+    noir: string;
+    project: {
+        id: string;
+        name: string;
+    };
+    host: string;
+    transport: Transport;
+    daemon: boolean;
+    pid?: number;
+    uptimeSec?: number;
+}
+interface StatusContext {
+    transport: Transport;
+    daemon: boolean;
+    pid?: number;
+    startedAt?: number;
+}
+declare function buildStatus(project: ProjectInfo, ctx: StatusContext): HostStatus;
+
+interface ServerContext {
+    project: ProjectInfo;
+    transport: Transport;
+    daemon: boolean;
+    pid?: number;
+    startedAt?: number;
+    /**
+     * Optional store handle. When present, the `store_status` tool is
+     * registered. The daemon is the single writer; stdio/HTTP serve paths open
+     * the store once per serve lifecycle and reuse the same handle.
+     */
+    store?: Store;
+    /** Filesystem path to the store DB (reported by `store_status`). */
+    dbPath?: string;
+    /** True when the store was opened read-only (writable open failed). */
+    storeDegraded?: boolean;
+    /**
+     * Optional workflow engine. When present, the `workflow_status` and
+     * `checkpoint` tools are registered. Built once per serve lifecycle from the
+     * same store handle (see {@link buildWorkflowEngine}) and reused across HTTP
+     * requests, mirroring the store.
+     */
+    engine?: WorkflowEngine;
+    /**
+     * Optional context engine. When present, the `context_search`,
+     * `context_index`, and `context_status` tools are registered. Built once per
+     * serve lifecycle from the same store handle (see `buildContextEngine` in
+     * `./context-seam.js`) and reused across HTTP requests, mirroring the store
+     * + engine. The engine — through its indexer — is the only thing that writes
+     * context rows, so the daemon's single-writer discipline is preserved.
+     */
+    context?: ContextEngine;
+    /**
+     * Optional memory engine. When present, the `memory_save`, `memory_recall`,
+     * `memory_search`, `memory_sessions`, and `memory_forget` tools are
+     * registered. Built once per serve lifecycle from the same store handle + the
+     * SAME `EmbedFn` already resolved for S6 (see `buildMemoryEngine` in
+     * `./memory-seam.js`) and reused across HTTP requests, mirroring the store +
+     * engine + context. The engine is the only thing that writes `source:memory`
+     * rows through the injected handle, so the daemon's single-writer discipline
+     * is preserved (blueprint D6: in-process, no sidecar, canonical `ProjectId`).
+     */
+    memory?: MemoryEngine;
+    /**
+     * Whether the {@link memory} engine is consolidation-capable — i.e. the user
+     * opted in (`memory.consolidation.enabled === true`) AND a usable provider+model
+     * resolved (see `resolveConsolidationCapability` in `./memory-seam.js`, the AND
+     * of the master switch + the provider derivation). Only when this is true is the
+     * `memory_consolidate` tool registered: consolidation is OPT-IN +
+     * provider-explicit (blueprint D5/D6/DS-6 / §9), NEVER a silent paid call — a
+     * `model:` block set for summarize/title/draft does NOT flip this when the user
+     * left `memory.consolidation.enabled` false. The engine's `consolidate`
+     * self-refuses (`no-provider`/`model-unavailable`) when this flag is false, so
+     * the flag + the engine agree by construction.
+     */
+    memoryConsolidation?: boolean;
+}
+/** JSON returned by the `store_status` tool. */
+interface StoreStatus {
+    ok: boolean;
+    projectId: string;
+    docCount: number;
+    vecCount: number;
+    dbPath: string | null;
+    degraded: boolean;
+}
+/** JSON returned by the `workflow_status` / `checkpoint` tools. */
+interface WorkflowStatus {
+    ok: boolean;
+    taskId: string;
+    phase: Phase;
+    state: WorkflowState;
+    /** Next gate-phase ahead of the current phase (null past verify, or blocked). */
+    nextGate: Phase | null;
+    mode: Mode;
+    /** In-process view of the observable gate audit (Noir §9.1). */
+    history: GateResult[];
+    updatedAt: number;
+    /** Mirrors `store_status`: true when the store is a read-only fallback. */
+    degraded: boolean;
+}
+declare function createNoirServer(ctx: ServerContext): McpServer;
+
+declare function startStdioServer(ctx: ServerContext): Promise<void>;
+
+/**
+ * A store handle opened by the daemon for its own lifecycle.
+ *
+ * - `store` — the single writer/reader handle (the daemon is the only writer).
+ * - `dbPath` — absolute path to `<root>/.noir/store/<projectId>.db`; reported by
+ *   `store_status`.
+ * - `degraded` — `true` when the writable open failed and we fell back to a
+ *   read-only handle. In degraded mode writes throw
+ *   `"store is read-only (daemon down)"`, but reads (FTS, kNN, counts) keep
+ *   working, so the MCP surface still reports accurate state.
+ */
+interface DaemonStore {
+    store: Store;
+    dbPath: string;
+    degraded: boolean;
+}
+/**
+ * Open the project's store for the daemon — the single writer.
+ *
+ * Tries a read-write open first (creating the DB + migrating schema if
+ * needed). On any failure (DB locked by another writer, permissions, transient
+ * FS error) it falls back to a read-only open so the daemon still has an
+ * accurate read handle — the FS-fallback / degraded story. The caller threads
+ * `degraded` into `ServerContext` so `store_status` can surface it.
+ */
+declare function openStoreForDaemon(projectId: ProjectId, root: string): Promise<DaemonStore>;
+
+/**
+ * Build the daemon's {@link WorkflowEngine} from its already-open store handle
+ * + the project `root` + `projectId`.
+ *
+ * One engine per serve lifecycle — constructed once alongside the store (see
+ * {@link openStoreForDaemon}) and reused across every HTTP request, exactly as
+ * the store handle is. The engine is a thin orchestrator over the store KV, so
+ * it inherits the daemon's single-writer discipline for free.
+ *
+ * Degraded story: the engine itself is mode-agnostic; when the underlying store
+ * was opened read-only (`storeDegraded === true`), `workflow_status` still works
+ * (a pure KV read via {@link Store.getState}) while `checkpoint { action:'save' }`
+ * throws `"store is read-only (daemon down)"` — the tool handler catches that and
+ * surfaces a clear JSON error instead of crashing the daemon.
+ */
+declare function buildWorkflowEngine(store: Store, root: string, projectId: ProjectId): WorkflowEngine;
+
+export { type DaemonRecord, type DaemonStore, type EnsureResult, type HostStatus, type RunningDaemon, type ServerContext, type StartHttpOptions, type StatusContext, type StoreStatus, type Transport, type WorkflowStatus, buildContextEngine, buildMemoryEngine, buildStatus, buildWorkflowEngine, clearDaemonRecord, createNoirServer, daemonJsonPath, ensureDaemonRunning, noirHome, openStoreForDaemon, pidAlive, readDaemonRecord, resolveConsolidationCapability, resolveMemoryConsolidation, startHttpServer, startStdioServer, writeDaemonRecord };