@keb-org/consol 0.2.1 → 0.3.1

package/dist/native.d.ts

@@ -1,14 +1,12 @@
 import { type CallOptions, type Context, type Transport } from "./transport";
 import type { Reply } from "./types";
-/** Any OpenAI-shaped `/embeddings` endpoint; without it recall stays lexical-only. */
+/** A contextualized-embeddings endpoint (`POST {url}/contextualizedembeddings`); without it recall stays lexical-only. */
 export interface EmbeddingOptions {
     url: string;
     /** Omit for endpoints that take no key. */
     apiKey?: string;
     model: string;
     dims?: number;
-    queryPrefix?: string;
-    batchSize?: number;
     timeoutMs?: number;
 }
 /** Jev advice (experimental). */
@@ -51,6 +49,10 @@ export interface Addon {
     /** `location` is the JSON `{"vaultRoot"}` or `{"vault"}`. */
     openEngine(location: string, settings: Record<string, string>): Promise<NativeEngine>;
     setLogSink(sink: ((line: string) => void) | null, level?: string): void;
+    /** JSON `{instructions, tools: [{name, description, inputSchema}]}` of the MCP server. Needs no engine. */
+    mcpSurface(): string;
+    /** The MCP `CallToolResult` (JSON) of a wire reply (JSON) of `tool`. Needs no engine. */
+    mcpResult(tool: string, reply: string): string;
 }
 /**
  * Explicit path authoritative (a missing file fails here), then CONSOL_ADDON authoritative, then the

package/dist/types.d.ts

@@ -3,7 +3,7 @@ import type { ConsolErrorCode } from "./errors";
 type Open<T extends string> = T | (string & {});
 /**
  * The wire reply, the same on every transport. `text` is rendered for an LLM, `result` is the
- * contract payload (receipt fields next to `error` for a failed reflection-bound write). Tool
+ * contract payload (receipt fields next to `error` for a failed token-bound write). Tool
  * errors are replies with `error`, never exceptions.
  */
 export interface Reply {
@@ -19,7 +19,7 @@ export interface ToolError {
     code: ConsolErrorCode;
     retryable: boolean;
     message: string;
-    /** Input at fault as a path, e.g. `decisions[2].temporal.evidence[0]`; only when one input is to blame. */
+    /** Input at fault as a path, e.g. `decisions[2].refs[0]`; only when one input is to blame. */
     field?: string;
 }
 /** Part of a successful call that could not be done; an empty list means nothing was degraded. */
@@ -103,19 +103,33 @@ export interface RecallCard {
     relationships?: Relationship[];
     linked_via?: string;
     compact?: boolean;
+    /**
+     * The note's best passage whole (its `#`/`##` section, or part of a long one), as UTF-8 byte
+     * offsets into the text `read` returns: what a caller quotes when an excerpt window is too short to
+     * carry the evidence (`sliceUtf8(text, ...passage.byte_range)`). Full and lead cards.
+     */
+    passage?: {
+        byte_range: ByteRange;
+        heading_context?: string;
+    };
 }
 /** Every `jev`, `jev_triage` and `jev_advisory` field is experimental: present only with Jev configured. */
 export type Experimental = Record<string, unknown>;
-/** `recall` payload: at most `limit` cards, linked companions included. */
+/** `recall` payload: at most 30 cards (100 for a `*` query), linked companions included. */
 export interface RecallResult {
     /**
      * The progressive disclosure as a model reads it: full cards with excerpts, lead and id cards,
-     * the question's intent block and the hints. `candidates` are the same cards as data.
+     * the blocks its query symbols ask for and the hints. `candidates` are the same cards as data.
      */
     text: string;
     candidates: RecallCard[];
     /** True when more matched cards or companions were omitted. */
     truncated: boolean;
+    /**
+     * No note is near the top of both the word and the meaning search: the vault may not hold the
+     * answer. Without a judge, treat it as "not found" where a wrong answer costs more than none.
+     */
+    weak_evidence: boolean;
     unavailable: Unavailable[];
     jev?: Experimental;
 }
@@ -131,7 +145,7 @@ export interface EntityAffectedGroup {
     entity: string;
     docs: AffectedDoc[];
 }
-/** `remember` receipt; a reflection-bound write adds `reflection_write` to this same shape. */
+/** `remember` receipt; a token-bound write adds `reflection_write` to this same shape. */
 export interface RememberResult {
     changed: boolean;
     indexed: boolean;
@@ -145,8 +159,10 @@ export interface RememberResult {
     affected: AffectedDoc[];
     entity_affected: EntityAffectedGroup[];
     unavailable: Unavailable[];
-    /** Outcome of a reflection-bound write (and of the resume form). */
+    /** Outcome of a token-bound write (and of the write-token resume form). */
     reflection_write?: WriteOutcome;
+    /** `meta.<key>` for each `meta` key the server does not know; absent when there are none. */
+    ignored?: string[];
     jev?: Experimental;
 }
 /** `remove` receipt: the note is archived, its body stays readable and editable. */
@@ -163,7 +179,7 @@ export interface RemoveResult {
     reflection_write?: WriteOutcome;
     jev?: Experimental;
 }
-/** Durable state of a reflection-bound write (open); only `succeeded` published bytes. */
+/** Durable state of a token-bound write (open); only `succeeded` published bytes. */
 export type WriteState = Open<"pending" | "succeeded" | "conflicted" | "abandoned">;
 /** Why a reflection write has not succeeded yet (open); resume or abandon it explicitly. */
 export type WriteFailureCode = Open<"source_conflict" | "basis_changed" | "index_pending" | "publication_pending" | "receipt_pending">;
@@ -180,10 +196,13 @@ export interface WriteResolution {
     inspected: SourceRef | null;
     reason: string;
 }
-/** Outcome of one reflection-bound write; a write never completes the work by itself. */
+/** Outcome of one token-bound write; a write never completes the work by itself. */
 export interface WriteOutcome {
-    work_id: string;
-    action_key: string;
+    /** Write token: resume the write with it through `tool`, or abandon it through `reflect`. */
+    token: string;
+    tool: "remember" | "remove";
+    /** The note the write targets. */
+    id: string;
     state: WriteState;
     /** True for a replayed terminal outcome: it describes history, not the current source. */
     historical: boolean;
@@ -193,8 +212,16 @@ export interface WriteOutcome {
     resolution: WriteResolution | null;
     failure_code: WriteFailureCode | null;
 }
-/** Queue state of a work item; only an accepted decision completes it. */
-export type WorkStatus = "pending" | "completed" | "blocked" | "retryable" | "stale";
+/** An unresolved (pending or conflicted) write, as `reflect` lists every one of them on every call. */
+export interface UnresolvedWrite {
+    token: string;
+    tool: "remember" | "remove";
+    id: string;
+    state: WriteState;
+    failure_code: WriteFailureCode | null;
+}
+/** Queue state of a work item that is not open for a decision; only an accepted decision completes work. */
+export type ItemStatus = Open<"completed" | "stale">;
 /** Pair found through a link authored in `owner`. */
 export interface AuthoredLead {
     route: "authored";
@@ -236,43 +263,6 @@ export interface PromotionLead {
     scope: "skills" | "core";
     existing: string[];
 }
-/** Sources a work item was judged on; the basis hash binds decisions to exactly these versions. */
-export interface WorkBasis<L> {
-    subjects: SourceRef[];
-    sources: SourceRef[];
-    lead: L;
-}
-/** Shared by every work kind, so they stay readable before narrowing on `kind`. */
-export interface WorkBase {
-    work_id: string;
-    basis_hash: string;
-    status: WorkStatus;
-}
-/** Review one note; source work carries no lead. */
-export interface SourceWork extends WorkBase {
-    kind: "source";
-    basis: {
-        subjects: SourceRef[];
-        sources: SourceRef[];
-    };
-}
-/** Compare two notes. */
-export interface PairWork extends WorkBase {
-    kind: "pair";
-    basis: WorkBasis<PairLead>;
-}
-/** Form, attach to or bridge a hub. Unstable: checked against Rust source only. */
-export interface HubWork extends WorkBase {
-    kind: "hub_attachment" | "hub_formation" | "hub_bridge";
-    basis: WorkBasis<HubLead>;
-}
-/** Promote recurring knowledge to skills/core. Unstable: checked against Rust source only. */
-export interface PromotionWork extends WorkBase {
-    kind: "promotion";
-    basis: WorkBasis<PromotionLead>;
-}
-/** A delivered work item, discriminated on `kind`. */
-export type ReflectionWork = SourceWork | PairWork | HubWork | PromotionWork;
 /** Markdown block of a delivered source, as a suggested excerpt boundary. */
 export interface CandidateBlock {
     byte_range: ByteRange;
@@ -287,50 +277,62 @@ export interface DeliveredSource {
     /** Suggested body spans, not a replacement for inspection. */
     candidate_blocks: CandidateBlock[];
 }
-/** Work delivered with every source body; deliver, write and decide are separate steps. */
-export interface CompleteDelivery {
-    work: ReflectionWork;
+/** Shared by every work kind, so they stay readable before narrowing on `kind`. */
+export interface ItemBase {
+    /** Work token: pass it to `remember` / `remove` to bind a write, and in a decision. Opaque. */
+    token: string;
+    /** What the server offers for this item (open: it grows without a schema change); empty when `status` is set. */
+    verdicts: string[];
+    /** The evidence each verdict requires. */
+    needs: string[];
+    subjects: SourceRef[];
+    /** The complete Markdown of every source the item was judged on. */
     sources: DeliveredSource[];
-    complete: true;
+    /** Present only when the work is not open for a decision (`verdicts` is then empty). */
+    status?: ItemStatus;
     jev_advisory?: Experimental;
 }
-/** Work or a requested source that could not be delivered this call; the call itself succeeded. */
-export interface FailedDelivery {
-    /** Present when the work is known. */
-    work_id?: string;
-    /** Present for a requested source (`ids` mode). */
-    requested_id?: string;
-    complete: false;
-    error: ToolError;
+/** Review one note; source work carries no lead. */
+export interface SourceItem extends ItemBase {
+    kind: "source";
 }
-/** One entry of `reflect().deliveries`; narrow on `complete`. */
-export type ReflectDelivery = CompleteDelivery | FailedDelivery;
-/** Allowed `disposition` values of a source decision. */
-export type SourceDisposition = "synthesize" | "connect" | "archive" | "retained_raw" | "blocked" | "retryable_error" | "stale";
-/** Allowed `disposition` values of a pair decision. */
-export type PairDisposition = "linked" | "no_relation" | "unresolved" | "blocked" | "retryable_error" | "stale";
-/** Allowed `disposition` values of a hub or promotion decision. */
-export type ConsolidationDisposition = "applied" | "reused" | "rejected" | "retained_raw" | "blocked" | "retryable_error" | "stale";
-/** Accepted source/pair/hub/promotion decision; `status` echoes the disposition. */
-export interface AcceptedDecision {
-    work_id: string;
-    accepted: true;
-    status: SourceDisposition | PairDisposition | ConsolidationDisposition;
+/** Compare two notes. `validity` is computed from their bounds; where it is `unknown` a verdict may carry a second word. */
+export interface PairItem extends ItemBase {
+    kind: "pair";
+    lead: PairLead;
+    validity?: Open<"overlap" | "disjoint" | "empty" | "unknown">;
+}
+/** Form, attach to or bridge a hub. Unstable: checked against Rust source only. */
+export interface HubItem extends ItemBase {
+    kind: "hub_attachment" | "hub_formation" | "hub_bridge";
+    lead: HubLead;
+}
+/** Promote recurring knowledge to skills/core. Unstable: checked against Rust source only. */
+export interface PromotionItem extends ItemBase {
+    kind: "promotion";
+    lead: PromotionLead;
 }
-/** Accepted `abandon_write`; the resulting outcome is in `writes`. */
-export interface AcceptedAbandon {
-    work_id: string;
-    action_key: string;
+/** A delivered work item, discriminated on `kind`. */
+export type ReflectItem = SourceItem | PairItem | HubItem | PromotionItem;
+/** Accepted decision; `verdict` repeats the outcome (and a pair's validity word). */
+export interface AcceptedDecision {
+    token: string;
     accepted: true;
+    verdict: string;
 }
 /** Failed decision; the call still succeeds and later decisions still run. */
 export interface RejectedDecision {
-    work_id: string;
+    token: string;
     accepted: false;
     error: ToolError;
 }
 /** One entry of `reflect().decisions`, in submission order. */
-export type DecisionReceipt = AcceptedDecision | AcceptedAbandon | RejectedDecision;
+export type DecisionReceipt = AcceptedDecision | RejectedDecision;
+/** A `focus` target that could not be delivered, or a work that failed to deliver; the call itself succeeded. */
+export interface FocusError {
+    focus: string;
+    error: ToolError;
+}
 /** Discovery lanes in the order the server reports them. */
 export type ReflectionLane = "source" | "semantic_pairs" | "structural_pairs" | "hubs" | "promotions";
 /** Progress of one discovery page. */
@@ -359,7 +361,7 @@ export type DiscoveryLane = {
     error: ToolError;
     current_complete?: boolean;
 };
-/** Queue counters; `done` is true only when every lane is exhausted and nothing is open. */
+/** Queue counters; `done` is true only when every lane is current and nothing is open. */
 export interface ReflectCounters {
     pending: number;
     blocked: number;
@@ -367,17 +369,25 @@ export interface ReflectCounters {
     unresolved_writes: number;
     done: boolean;
 }
-/** `reflect` payload for every mode; unused sections are empty. Check `counters.done` before assuming nothing is left. */
+/** What to do next: `resume` unresolved writes, `decide` the delivered items, `continue` the scan, or `done`. */
+export type ReflectNext = Open<"resume" | "decide" | "continue" | "done">;
+/**
+ * `reflect` payload. One call applies its decisions, then delivers work, so a loop is: call with the
+ * decisions so far and follow `next`. `writes` lists every unresolved write on every call.
+ */
 export interface ReflectResult {
-    deliveries: ReflectDelivery[];
+    next: ReflectNext;
+    items: ReflectItem[];
+    writes: UnresolvedWrite[];
+    /** Work tokens of blocked work; pass one in `focus` to reopen it. */
+    blocked: string[];
     decisions: DecisionReceipt[];
-    writes: WriteOutcome[];
-    /** Lanes are filled by discovery (no targets) only. */
-    discovery: {
-        completion_checked: boolean;
-        lanes: DiscoveryLane[];
-    };
     counters: ReflectCounters;
+    /** Empty when `focus` named targets. */
+    lanes: DiscoveryLane[];
+    /** `focus` symbols this version does not know. */
+    ignored?: string[];
+    errors?: FocusError[];
     jev?: Experimental;
     jev_triage?: Experimental;
 }

package/dist/vault.d.ts

@@ -1,6 +1,6 @@
 import { type EngineOptions } from "./native";
 import { type CallOptions } from "./transport";
-import type { ConsolidationDisposition, PairDisposition, ReadResult, RecallResult, Reply, ReflectResult, RememberResult, RemoveResult, Scope, SourceDisposition } from "./types";
+import type { ReadResult, RecallResult, Reply, ReflectResult, RememberResult, RemoveResult, Scope } from "./types";
 export { sliceUtf8 } from "./types";
 export declare const CLIENT_INFO: {
     name: string;
@@ -24,88 +24,28 @@ export interface HostedOptions {
     /** Default per-call deadline in ms (300000); 0 disables it. */
     timeoutMs?: number;
 }
-/** Binds one recoverable write to inspected work; a write never completes the work. */
-export interface ReflectionContext {
-    work_id: string;
-    basis_hash: string;
-    action_key: string;
-}
-/** Decision input source reference; unlike results it never carries `review_version`. */
-export interface InspectedSource {
-    id: string;
-    owner: string;
-    content_version: string;
-}
-/** Body byte range (UTF-8, frontmatter excluded) that a decision cites as evidence. */
-export interface InspectedSpan {
-    source: InspectedSource;
-    byte_range: [number, number];
-}
-/** Required for completed pair decisions so validity periods are compared, not assumed. */
-export interface TemporalAssessment {
-    validity: "overlap" | "disjoint" | "empty" | "unknown";
+/**
+ * One outcome for `reflect({ decisions })`. `token` is an item's work token, or a write token to
+ * abandon that write. `verdict` is one of the item's `verdicts` (`abandon` for a write token); a
+ * pair verdict may add `overlap`, `disjoint` or `empty` only where the item's `validity` is unknown.
+ * `refs` is what you inspected: `id@version` (a whole source) or `id@version#start-end` (a body
+ * span, UTF-8 byte offsets). `outputs` are the notes the work produced or relied on, `id@version`.
+ */
+export interface Decision {
+    token: string;
+    verdict: string;
     reason: string;
-    evidence: InspectedSpan[];
-    correction_reason?: string;
-}
-/** Names the authored link a `linked` pair decision relies on. */
-export interface PairAssertion {
-    owner: InspectedSource;
-    src: string;
-    dst: string;
-    relation: "derives" | "causes" | "contradicts" | "questions";
+    refs?: string[];
+    outputs?: string[];
 }
 /**
- * One explicit outcome for `reflect({ decisions })`; the tool schema defines each kind's required
- * evidence. `retry_after_ms` is an epoch-ms timestamp within the next day, only for `retryable_error`.
- * Hub and promotion decisions are experimental.
+ * Flat wire args for recall. Symbols in `query` (whitespace-separated punctuation tokens): `*` breadth,
+ * `~` chronology, `^` latest, `+` history, `#` numbers as words only, and `=` literal: the text as
+ * written, with no phrases, alternatives, ranges or other symbols (for free text an application passes).
  */
-export type Decision = {
-    kind: "source";
-    work_id: string;
-    basis_hash: string;
-    disposition: SourceDisposition;
-    reason: string;
-    outputs?: InspectedSource[];
-    action_keys?: string[];
-    retry_after_ms?: number;
-} | {
-    kind: "pair";
-    work_id: string;
-    basis_hash: string;
-    disposition: PairDisposition;
-    reason: string;
-    temporal?: TemporalAssessment;
-    assertion?: PairAssertion;
-    action_keys?: string[];
-    retry_after_ms?: number;
-} | {
-    kind: "hub" | "promotion";
-    work_id: string;
-    basis_hash: string;
-    disposition: ConsolidationDisposition;
-    reason: string;
-    outputs?: InspectedSource[];
-    evidence?: InspectedSpan[];
-    action_keys?: string[];
-    retry_after_ms?: number;
-} | {
-    kind: "abandon_write";
-    work_id: string;
-    basis_hash: string;
-    action_key: string;
-    inspected: InspectedSource | null;
-    reason: string;
-};
-/** What a recall question asks for beyond its terms; the caller declares it, in any language. */
-export type Intent = "breadth" | "chronology" | "latest";
-/** Flat wire args for recall. */
 export interface RecallArgs {
     query: string;
     agent?: string;
-    include_history?: boolean;
-    limit?: number;
-    intents?: Intent[];
 }
 /** Flat wire args for read. */
 export interface ReadArgs {
@@ -114,8 +54,8 @@ export interface ReadArgs {
     continuation?: string;
 }
 /**
- * Flat wire args for remember. Omitted or null metadata preserves the stored value; "" or [] clears
- * it. Without `expected_version` the write is create-only.
+ * Wire args for remember. Omitted or null `content` preserves the body. Without `expected_version`
+ * the write is create-only.
  */
 export interface RememberArgs {
     id: string;
@@ -123,35 +63,43 @@ export interface RememberArgs {
     /** Markdown body only, never frontmatter. */
     content?: string | null;
     expected_version?: string;
-    entities?: string[] | null;
-    facets?: string[] | null;
-    scope?: Scope | null;
-    summary?: string | null;
-    team?: string | null;
-    /** `YYYY-MM-DD` or RFC 3339 with `Z`/offset; "" clears the bound. */
-    valid_from?: string | null;
-    valid_to?: string | null;
-    reflection?: ReflectionContext;
+    /**
+     * A key left out keeps its value; null, "" or [] clears it (not `scope` or `team`: null keeps
+     * them). `valid_from`/`valid_to` are `YYYY-MM-DD` or RFC 3339 with `Z`/offset. A key the server
+     * does not know is ignored and listed in the receipt's `ignored`.
+     */
+    meta?: {
+        summary?: string | null;
+        entities?: string[] | null;
+        facets?: string[] | null;
+        scope?: Scope | null;
+        team?: string | null;
+        valid_from?: string | null;
+        valid_to?: string | null;
+        /** false: this note's `[[...]]` in prose is text, not a link (imported citations such as `[[1]]`). */
+        links?: boolean | null;
+        [key: string]: unknown;
+    };
+    /** An item's work token from `reflect` binds this write to that work; the server derives its action key. */
+    token?: string;
 }
 /** Flat wire args for remove (archives the note; its body stays readable). */
 export interface RemoveArgs {
     id: string;
     expected_version: string;
     agent?: string;
-    reflection?: ReflectionContext;
+    /** An item's work token from `reflect` records this archive as one write of that work. */
+    token?: string;
 }
-/** Resume a pending reflection-bound write with the same context and tool. */
+/** Resume (or replay) a write by its write token, with the tool that wrote it. */
 export interface ResumeArgs {
-    resume: true;
-    reflection: ReflectionContext;
+    token: string;
     agent?: string;
 }
-/** Flat wire args for reflect. */
+/** Flat wire args for reflect. `focus` is whitespace-separated work tokens and note ids. */
 export interface ReflectArgs {
     agent?: string;
-    ids?: string[];
-    work_ids?: string[];
-    limit?: number;
+    focus?: string;
     decisions?: Decision[];
 }
 /** One vault behind a transport (the in-process engine or a hosted backend). Build it with createVault or openVault; close() is final. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keb-org/consol",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Consol memory engine SDK: a local vault, a hosted vault client, and the Consol backend class",
   "keywords": [
     "mcp",
@@ -29,6 +29,9 @@
       "require": "./dist/index.js"
     }
   },
+  "bin": {
+    "consol-mcp": "dist/mcp.js"
+  },
   "files": [
     "dist"
   ],
@@ -37,7 +40,7 @@
   },
   "license": "MIT",
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && bun build src/index.ts --outfile dist/index.js --target node --format cjs && cp src/index.mjs dist/index.mjs && tsc --emitDeclarationOnly --pretty false",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && bun build src/index.ts --outfile dist/index.js --target node --format cjs && bun build src/mcp.ts --outfile dist/mcp.js --target node --format cjs && cp src/index.mjs dist/index.mjs && tsc --emitDeclarationOnly --pretty false",
     "typecheck": "tsc --noEmit --pretty false",
     "test": "bun run build && bun test/pure.ts && node test/http.ts && node test/native.ts && node test/sdk.ts && tsc --noEmit --pretty false -p test",
     "test:offline": "bun run build && bun test/pure.ts && node test/http.ts && node test/native.ts && tsc --noEmit --pretty false -p test",
@@ -45,16 +48,17 @@
   },
   "devDependencies": {
     "typescript": "5.3.3",
-    "@types/node": "20.11.0"
+    "@types/node": "20.11.0",
+    "@modelcontextprotocol/server": "2.3.1"
   },
   "publishConfig": {
     "access": "public"
   },
   "optionalDependencies": {
-    "@keb-org/consol-win32-x64": "0.2.1",
-    "@keb-org/consol-darwin-arm64": "0.2.1",
-    "@keb-org/consol-darwin-x64": "0.2.1",
-    "@keb-org/consol-linux-x64": "0.2.1",
-    "@keb-org/consol-linux-arm64": "0.2.1"
+    "@keb-org/consol-win32-x64": "0.3.1",
+    "@keb-org/consol-darwin-arm64": "0.3.1",
+    "@keb-org/consol-darwin-x64": "0.3.1",
+    "@keb-org/consol-linux-x64": "0.3.1",
+    "@keb-org/consol-linux-arm64": "0.3.1"
   }
 }