@keb-org/consol 0.1.0 → 0.2.1

package/README.md

@@ -2,27 +2,27 @@
 
 TypeScript SDK for the consol memory engine, for three uses:
 
-1. **Local**: a vault on disk (or S3) in your own process. The SDK starts `consol stdio` as a child.
+1. **Local**: a vault on disk (or S3), with the engine running in your own process as a native addon.
 2. **Hosted client**: the same `Vault` methods against a backend over HTTP.
 3. **Backend**: `Consol.handle` behind your own HTTP route, so clients of any language can use it.
 
 Node >= 22 or Bun, no dependencies; `import` and `require` share one implementation. The behaviour
 is the same in every mode.
 
-## The server binary and database
+## The engine addon and database
 
-The package does not build the server. The SDK uses the first of these that exists:
+The engine is the native addon `consol.node`, loaded the first time you start a vault or a
+`Consol` (importing the SDK loads nothing). The SDK uses the first of these:
 
-1. the `binaryPath` option,
-2. the `CONSOL_BIN` environment variable,
-3. the platform package `@keb-org/consol-<platform>-<arch>`, resolved from the SDK's own location,
-4. `consol` (`consol.exe` on Windows) on `PATH`.
+1. the `addonPath` option,
+2. the `CONSOL_ADDON` environment variable,
+3. the platform package `@keb-org/consol-<platform>-<arch>`, resolved from the SDK's own location.
 
-A `binaryPath` or `CONSOL_BIN` that points nowhere fails at once with `binary_not_found` instead
-of falling through to the next place. Build the binary from the repository with
-`cargo build --release -p consol-cli`.
+An `addonPath` or `CONSOL_ADDON` that points nowhere, or at a file that does not load, fails at
+once with `addon_not_found` instead of falling through to the next place. The platform package
+also ships the `consol` CLI as `bin/consol`.
 
-The engine needs a database, PostgreSQL with pgvector or CockroachDB: pass `db` or set
+The engine still needs a database, PostgreSQL with pgvector or CockroachDB: pass `db` or set
 `CONSOL_DB_URL` in your process (the one `CONSOL_*` variable the SDK takes from its host).
 
 ## 1. Local
@@ -44,8 +44,8 @@ try {
 ```
 
 `createVault` fails with `vault_exists` when the directory already holds a vault, `openVault`
-(same options) with `vault_not_found` when it does not. Both start the server and check that its
-version matches the SDK's major.minor before they return.
+(same options) with `vault_not_found` when it does not. Both open the engine and check that the
+addon's version matches the SDK's major.minor before they return.
 
 ## 2. Hosted client
 
@@ -109,7 +109,7 @@ Each method takes one object with the tool's wire argument names, plus optional
 
 | Method | Arguments | Returns |
 |---|---|---|
-| `recall` | `{ query, include_history?, limit?, agent? }` | `RecallResult`: `text` is the progressive disclosure to give a model (cards by tier, intent block, hints); `candidates` are the same cards as data. Cards are leads: read a note before relying on it |
+| `recall` | `{ query, include_history?, limit?, intents?, agent? }` | `RecallResult`: `text` is the progressive disclosure to give a model (cards by tier, intent block, hints); `candidates` are the same cards as data. Cards are leads: read a note before relying on it |
 | `read` | `{ id, continuation?, agent? }` | `ReadResult`; `text` is the exact file |
 | `remember` | `{ id, content?, expected_version?, summary?, entities?, facets?, scope?, team?, valid_from?, valid_to?, reflection?, agent? }` | `RememberResult` |
 | `remove` | `{ id, expected_version, reflection?, agent? }` | `RemoveResult`: the note is archived, its body stays readable |
@@ -189,8 +189,8 @@ try {
   `content_too_large`, `unsupported`, `work_not_found`, `basis_mismatch`, `already_decided`,
   `unresolved_writes`, `postcondition_failed`, `index_unavailable`, `storage_unavailable`, `vault_busy`, `internal`.
   Vault codes: `vault_exists`, `vault_not_found`.
-- SDK codes: `request_failed` (`status?`), `binary_not_found`, `incompatible_server` (server
-  major.minor differs from the SDK's), `server_exited`, `timeout`, `aborted`, `closed`.
+- SDK codes: `request_failed` (`status?`), `addon_not_found`, `incompatible_server` (addon or
+  server major.minor differs from the SDK's), `timeout`, `aborted`, `closed`.
 - `retryable: true` (`vault_busy`, `index_unavailable`, `storage_unavailable`, `request_failed` on a connect error or
   502/503/504) means the identical request may succeed later. The SDK never retries by itself.
 
@@ -198,22 +198,17 @@ try {
 
 - `close()` is final and idempotent: in-flight and later calls fail with `closed`, and concurrent
   calls share one completion. `await using vault = await openVault(...)` closes it for you.
-- An idle local vault does not keep Node or Bun alive: a script that forgets `close()` still
-  exits, and its server exits with it.
 - Every call has a deadline: 300 s by default, `timeoutMs` per vault or per call, `0` disables it.
   `signal` aborts a call. Both only stop waiting: a write may still complete, so read the note
   before you retry.
-- When a local server crashes, in-flight calls fail with `server_exited`. The next call starts the
-  server once more and opens the vault again (`vault_not_found` if it was deleted meanwhile).
-- Servers on one vault take turns on its lock, a lease in the database; a wait over 5 s fails with
-  `vault_busy`.
+- Engines on one vault, in this process or another, take turns on its lock, a lease in the
+  database; a wait over 5 s fails with `vault_busy`.
 
 ## Configuration and logging
 
-Options of `createVault`, `openVault` (local) and `Consol.start` become the server's environment,
-never its argv. Inherited `CONSOL_*` and `RUST_LOG` variables are dropped first (except
-`CONSOL_DB_URL` as the default for `db`), so a stray host variable cannot change the agent or the
-vault.
+Options of `createVault`, `openVault` (local) and `Consol.start` become the engine's settings (the
+`CONSOL_*` names). Your process's own `CONSOL_*` variables are not read (except `CONSOL_DB_URL` as
+the default for `db`), so a stray host variable cannot change the agent or the vault.
 
 | Option | Meaning |
 |---|---|
@@ -223,14 +218,14 @@ vault.
 | `db` | database URL (`CONSOL_DB_URL`): PostgreSQL with pgvector, or CockroachDB |
 | `embedding` | `{ url, model, apiKey?, dims?, queryPrefix?, batchSize?, timeoutMs? }` (`CONSOL_EMBED_*`); without it recall is lexical-only |
 | `jev` | `{ url?, apiKey?, model?, auto? }` (`CONSOL_JEV_*`); experimental advice |
-| `env` | any other server variable, applied last |
-| `binaryPath` | server binary, see above |
+| `env` | any other engine setting (a `CONSOL_*` name), applied last |
+| `addonPath` | the `consol.node` to load, see above |
 | `timeoutMs` | default per-call deadline in ms |
-| `onLog` | `(line) => void`, receives each server stderr line |
+| `onLog` | `(line) => void`, receives each engine log line |
+| `logLevel` | which lines reach `onLog`, such as `info` or `consol_engine=debug` (default `warn`) |
 
-The server's stderr is captured and never written to your process's stderr. Pass `onLog` to see
-it, and `env: { RUST_LOG: 'debug' }` for more detail. A `server_exited` error carries the server's
-last lines in its message and in `stderrTail`.
+The addon has one log sink per process: every engine's `onLog` receives the same lines at the
+latest `logLevel` set, and the sink is released when the last of them closes.
 
 ## Types and stability
 
@@ -246,21 +241,22 @@ decisions, and every `jev`, `jev_triage` and `jev_advisory` field (typed as plai
 bun install
 bun run build       # dist/index.js (CJS), dist/index.mjs (ESM wrapper), dist/*.d.ts
 bun run typecheck   # tsc over src
-# the rest needs the real binary and a database:
-export CONSOL_BIN=/abs/consol CONSOL_DB_URL=postgres://...
-bun run test            # pure checks, hosted-client stub, real-binary suite on Node, strict tsc incl. conformance
-bun run test:consumers  # packed tarballs in Bun, Node ESM, Node CJS and platform-package projects
-node test/capture.mjs   # recapture test/fixtures from the real server (without CONSOL_BIN it only regenerates the types check)
+bun run test:offline    # pure checks, hosted-client stub, fake-addon transport checks, strict tsc incl. conformance
+# the rest needs the real addon and a database:
+export CONSOL_ADDON=/abs/consol.node CONSOL_DB_URL=postgres://...
+bun run test            # the offline checks plus the real-addon suite on Node
+CONSOL_BIN=/abs/consol bun run test:consumers  # packed tarballs in Bun, Node ESM, Node CJS and platform-package projects
+node test/capture.mjs   # recapture test/fixtures from the real engine (without CONSOL_ADDON it only regenerates the types check)
 ```
 
 `bun run test`, not `bun test` (that is Bun's own runner). Consumer logs go to
 `consumers/<project>.log`.
 
-## Publishing platform binaries
+## Publishing platform packages
 
 1. `bun run build`
-2. `bun scripts/make-platform-package.mjs <binary> <platform> <arch> <outDir>` per target
-   (win32-x64, darwin-arm64, darwin-x64, linux-x64, linux-arm64); the binary is stored as
-   `bin/consol[.exe]` whatever its file name
+2. `bun scripts/make-platform-package.mjs <binary> <addon> <platform> <arch> <outDir>` per target
+   (win32-x64, darwin-arm64, darwin-x64, linux-x64, linux-arm64); the CLI binary is stored as
+   `bin/consol[.exe]` and the addon as `consol.node`, whatever their file names
 3. Publish each platform package, then `bun scripts/inject-optional-deps.mjs <publish-copy-of-package.json>`
 4. `bun publish` the main package (`publishConfig.access` is `public`)

package/dist/consol.d.ts

@@ -1,4 +1,4 @@
-import { type EngineOptions } from "./stdio";
+import { type EngineOptions } from "./native";
 import type { CallOptions, Context } from "./transport";
 import type { Reply } from "./types";
 /** Exactly one of `vaultRoot` / `vault`, plus the engine settings (`db`, `embedding`, `jev`, ...). */
@@ -10,7 +10,7 @@ export interface ConsolOptions extends EngineOptions {
 }
 export declare function httpStatus(reply: Reply): number;
 /**
- * The engine in your own backend: one `consol stdio` child behind `handle`. A backend authorizes
+ * The engine in your own backend: the in-process engine behind `handle`. A backend authorizes
  * the request itself, then passes the result as `ctx`.
  *
  * SECURITY: `ctx` (the vaults the caller may use, the agent they are) must come from YOUR auth,

package/dist/errors.d.ts

@@ -1,13 +1,12 @@
 import type { Reply } from "./types";
 /** Branchable error codes: wire tool codes (contract section 4) plus the SDK codes of section 6. */
-export type ConsolErrorCode = "invalid_argument" | "not_found" | "already_exists" | "version_conflict" | "team_not_attached" | "secret_rejected" | "content_too_large" | "unsupported" | "work_not_found" | "basis_mismatch" | "already_decided" | "unresolved_writes" | "postcondition_failed" | "index_unavailable" | "storage_unavailable" | "vault_busy" | "forbidden" | "vault_exists" | "vault_not_found" | "internal" | "request_failed" | "binary_not_found" | "incompatible_server" | "server_exited" | "timeout" | "aborted" | "closed" | (string & {});
+export type ConsolErrorCode = "invalid_argument" | "not_found" | "already_exists" | "version_conflict" | "team_not_attached" | "secret_rejected" | "content_too_large" | "unsupported" | "work_not_found" | "basis_mismatch" | "already_decided" | "unresolved_writes" | "postcondition_failed" | "index_unavailable" | "storage_unavailable" | "vault_busy" | "forbidden" | "vault_exists" | "vault_not_found" | "internal" | "request_failed" | "addon_not_found" | "incompatible_server" | "timeout" | "aborted" | "closed" | (string & {});
 export interface ConsolErrorDetails {
     retryable?: boolean;
     field?: string;
     tool?: string;
     /** HTTP status of a `request_failed` / `forbidden` that came from the transport, not the engine. */
     status?: number;
-    stderrTail?: string;
     result?: Reply;
     cause?: unknown;
 }
@@ -18,7 +17,6 @@ export declare class ConsolError extends Error {
     readonly field?: string;
     readonly tool?: string;
     readonly status?: number;
-    readonly stderrTail?: string;
     /** Raw reply of a failed typed call: durable write state (`result.result`) survives the throw. */
     readonly result?: Reply;
     constructor(code: ConsolErrorCode, message: string, details?: ConsolErrorDetails);

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { ConsolError, type ConsolErrorCode } from "./errors";
 export { Consol, httpStatus, type ConsolOptions } from "./consol";
 export type { CallOptions, Context } from "./transport";
-export type { EmbeddingOptions, EngineOptions, JevOptions } from "./stdio";
-export { Vault, createVault, openVault, sliceUtf8, type VaultOptions, type HostedOptions, type RecallArgs, type ReadArgs, type RememberArgs, type RemoveArgs, type ResumeArgs, type ReflectArgs, type ReflectionContext, type Decision, type InspectedSource, type InspectedSpan, type TemporalAssessment, type PairAssertion, } from "./vault";
+export type { EmbeddingOptions, EngineOptions, JevOptions } from "./native";
+export { Vault, createVault, openVault, sliceUtf8, type VaultOptions, type HostedOptions, type Intent, type RecallArgs, type ReadArgs, type RememberArgs, type RemoveArgs, type ResumeArgs, type ReflectArgs, type ReflectionContext, type Decision, type InspectedSource, type InspectedSpan, type TemporalAssessment, type PairAssertion, } from "./vault";
 export type { Reply, ToolError, Unavailable, Status, ByteRange, Scope, SourceRef, RelationshipKind, Relationship, RecallRetrieval, SourceExcerpt, RecallCard, RecallResult, ReadResult, RememberResult, RemoveResult, ReflectResult, AffectedDoc, EntityAffectedGroup, WriteState, WriteFailureCode, WriteReceipt, WriteResolution, WriteOutcome, ReflectionWork, SourceWork, PairWork, HubWork, PromotionWork, DeliveredSource, CompleteDelivery, FailedDelivery, ReflectDelivery, DecisionReceipt, SourceDisposition, PairDisposition, } from "./types";

package/dist/index.js

@@ -1,5 +1,3 @@
-var __create = Object.create;
-var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -7,30 +5,6 @@ var __hasOwnProp = Object.prototype.hasOwnProperty;
 function __accessProp(key) {
   return this[key];
 }
-var __toESMCache_node;
-var __toESMCache_esm;
-var __toESM = (mod, isNodeMode, target) => {
-  var canCache = mod != null && typeof mod === "object";
-  if (canCache) {
-    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
-    var cached = cache.get(mod);
-    if (cached)
-      return cached;
-  }
-  target = mod != null ? __create(__getProtoOf(mod)) : {};
-  const to = isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  if (mod && typeof mod === "object" || typeof mod === "function") {
-    for (let key of __getOwnPropNames(mod))
-      if (!__hasOwnProp.call(to, key))
-        __defProp(to, key, {
-          get: __accessProp.bind(mod, key),
-          enumerable: true
-        });
-  }
-  if (canCache)
-    cache.set(mod, to);
-  return to;
-};
 var __toCommonJS = (from) => {
   var entry = (__moduleCache ??= new WeakMap).get(from), desc;
   if (entry)
@@ -84,7 +58,6 @@ class ConsolError extends Error {
   field;
   tool;
   status;
-  stderrTail;
   result;
   constructor(code, message, details = {}) {
     super(message, details.cause === undefined ? undefined : { cause: details.cause });
@@ -97,8 +70,6 @@ class ConsolError extends Error {
       this.tool = details.tool;
     if (details.status !== undefined)
       this.status = details.status;
-    if (details.stderrTail !== undefined)
-      this.stderrTail = details.stderrTail;
     if (details.result !== undefined)
       this.result = details.result;
     Object.defineProperty(this, BRAND, { value: true });
@@ -118,11 +89,8 @@ function replyError(reply, tool) {
     result: reply
   });
 }
-// src/stdio.ts
-var import_node_child_process = require("node:child_process");
-var import_node_fs = require("node:fs");
-var readline = __toESM(require("node:readline"));
-var import_node_string_decoder = require("node:string_decoder");
+// src/native.ts
+var import_node_path = require("node:path");
 
 // src/transport.ts
 var DEFAULT_TIMEOUT_MS = 300000;
@@ -211,409 +179,168 @@ class HttpTransport {
   }
 }
 
-// src/stdio.ts
-var STDERR_TAIL_BYTES = 4096;
-var EXIT_WAIT_MS = 2000;
-var KILL_WAIT_MS = 4000;
-function engineEnv(o) {
-  const env = {};
+// src/native.ts
+function engineSettings(o) {
+  const s = {};
   const db = o.db ?? process.env.CONSOL_DB_URL;
   if (db !== undefined)
-    env.CONSOL_DB_URL = db;
+    s.CONSOL_DB_URL = db;
   const e = o.embedding;
   if (e !== undefined) {
-    env.CONSOL_EMBED_URL = e.url;
+    s.CONSOL_EMBED_URL = e.url;
     if (e.apiKey !== undefined)
-      env.CONSOL_EMBED_API_KEY = e.apiKey;
-    env.CONSOL_EMBED_MODEL = e.model;
+      s.CONSOL_EMBED_API_KEY = e.apiKey;
+    s.CONSOL_EMBED_MODEL = e.model;
     if (e.dims !== undefined)
-      env.CONSOL_EMBED_DIMS = String(e.dims);
+      s.CONSOL_EMBED_DIMS = String(e.dims);
     if (e.queryPrefix !== undefined)
-      env.CONSOL_EMBED_QUERY_PREFIX = e.queryPrefix;
+      s.CONSOL_EMBED_QUERY_PREFIX = e.queryPrefix;
     if (e.batchSize !== undefined)
-      env.CONSOL_EMBED_BATCH = String(e.batchSize);
+      s.CONSOL_EMBED_BATCH = String(e.batchSize);
     if (e.timeoutMs !== undefined)
-      env.CONSOL_EMBED_TIMEOUT_MS = String(e.timeoutMs);
+      s.CONSOL_EMBED_TIMEOUT_MS = String(e.timeoutMs);
   }
   const j = o.jev;
   if (j !== undefined) {
     if (j.url !== undefined)
-      env.CONSOL_JEV_URL = j.url;
+      s.CONSOL_JEV_URL = j.url;
     if (j.apiKey !== undefined)
-      env.CONSOL_JEV_API_KEY = j.apiKey;
+      s.CONSOL_JEV_API_KEY = j.apiKey;
     if (j.model !== undefined)
-      env.CONSOL_JEV_MODEL = j.model;
+      s.CONSOL_JEV_MODEL = j.model;
     if (j.auto === false)
-      env.CONSOL_JEV_AUTO = "0";
+      s.CONSOL_JEV_AUTO = "0";
   }
-  return env;
-}
-function platformExe() {
-  return process.platform === "win32" ? "consol.exe" : "consol";
+  return { ...s, ...o.env };
 }
-function isFile(path) {
+function loadAddon(explicit) {
+  const fromEnv = process.env.CONSOL_ADDON;
+  const spec = `@keb-org/consol-${process.platform}-${process.arch}/consol.node`;
+  const [attempt, target] = explicit ? [`addonPath:${explicit}`, import_node_path.resolve(explicit)] : fromEnv ? [`CONSOL_ADDON:${fromEnv}`, import_node_path.resolve(fromEnv)] : [`package:${spec}`, spec];
   try {
-    return import_node_fs.statSync(path).isFile();
-  } catch {
-    return false;
+    const sdkRequire = require;
+    return sdkRequire(target);
+  } catch (cause) {
+    throw new ConsolError("addon_not_found", `addon not found: ${attempt} (${String(cause?.message).split(`
+`)[0]})`, { cause });
   }
 }
-function missingBinary(attempt) {
-  return new ConsolError("binary_not_found", `binary not found: ${attempt}`, { stderrTail: attempt });
+var logSinks = new Set;
+var fanOut = (line) => {
+  for (const sink of logSinks)
+    sink(line);
+};
+function subscribe(addon, onLog, level) {
+  const sink = (line) => {
+    try {
+      onLog(line);
+    } catch {}
+  };
+  logSinks.add(sink);
+  addon.setLogSink(fanOut, level);
+  return () => {
+    if (logSinks.delete(sink) && logSinks.size === 0)
+      addon.setLogSink(null);
+  };
 }
-function resolveBinary(explicit) {
-  const exe = platformExe();
-  if (explicit) {
-    if (!isFile(explicit))
-      throw missingBinary(`explicit:${explicit}`);
-    return { path: explicit, attempts: [`explicit:${explicit}`] };
-  }
-  const fromEnv = process.env.CONSOL_BIN;
-  if (fromEnv) {
-    if (!isFile(fromEnv))
-      throw missingBinary(`CONSOL_BIN:${fromEnv}`);
-    return { path: fromEnv, attempts: [`CONSOL_BIN:${fromEnv}`] };
-  }
-  const spec = `@keb-org/consol-${process.platform}-${process.arch}/bin/${exe}`;
+function engineError(error) {
+  if (ConsolError.is(error))
+    return error;
+  const text = error instanceof Error ? error.message : String(error);
   try {
-    const sdkRequire = require;
-    return { path: sdkRequire.resolve(spec), attempts: [`package:${spec}`] };
-  } catch {
-    return { path: exe, attempts: [`package:${spec}`, `PATH:${exe}`] };
-  }
-}
-function childEnv(base = {}, extra = {}) {
-  const env = {};
-  for (const [key, value] of Object.entries(process.env)) {
-    const name = process.platform === "win32" ? key.toUpperCase() : key;
-    if (value === undefined || name.startsWith("CONSOL_") || name === "RUST_LOG")
-      continue;
-    env[key] = value;
-  }
-  return { ...env, ...base, ...extra };
+    const { code, message, field } = JSON.parse(text);
+    if (typeof code === "string") {
+      return new ConsolError(code, typeof message === "string" ? message : code, {
+        field: typeof field === "string" ? field : undefined,
+        cause: error
+      });
+    }
+  } catch {}
+  return new ConsolError("internal", text, { cause: error });
 }
-function lastBytes(text) {
-  const bytes = Buffer.from(text, "utf8");
-  if (bytes.length <= STDERR_TAIL_BYTES)
-    return text;
-  let start = bytes.length - STDERR_TAIL_BYTES;
-  while ((bytes[start] & 192) === 128)
-    start++;
-  return bytes.subarray(start).toString("utf8");
+function race(work, label, ms, closed, user) {
+  const timer = ms > 0 ? AbortSignal.timeout(ms) : undefined;
+  const stop = anySignal([closed, user, timer].filter((s) => s !== undefined));
+  return new Promise((resolve, reject) => {
+    const onStop = () => reject(closed?.aborted ? new ConsolError("closed", "vault is closed") : user?.aborted ? new ConsolError("aborted", `${label} aborted`, { cause: user.reason }) : new ConsolError("timeout", `${label} timed out after ${ms}ms`));
+    stop.addEventListener("abort", onStop, { once: true });
+    work.then(resolve, reject).finally(() => stop.removeEventListener("abort", onStop));
+  });
 }
-var READY = 0;
 
-class StdioTransport {
-  opts;
-  attempts;
-  binary;
+class NativeTransport {
+  engine;
+  version;
   timeoutMs;
-  child = null;
-  reader = null;
-  generation = 0;
-  nextId = 1;
-  pending = new Map;
-  starting = null;
-  started = false;
-  closed = false;
+  unsubscribe;
+  closed = new AbortController;
   closing = null;
-  stderrTail = [];
-  stderrTailBytes = 0;
-  version = null;
-  constructor(opts) {
-    this.timeoutMs = deadline(opts.timeoutMs, DEFAULT_TIMEOUT_MS);
-    this.opts = opts;
-    const resolved = resolveBinary(opts.binaryPath);
-    this.binary = resolved.path;
-    this.attempts = resolved.attempts;
-  }
-  decoder = new import_node_string_decoder.StringDecoder("utf8");
-  stderrPartial = "";
-  onStderr(chunk) {
-    const lines = (this.stderrPartial + this.decoder.write(chunk)).split(/\r?\n/);
-    this.stderrPartial = lastBytes(lines.pop() ?? "");
-    for (const line of lines)
-      this.pushLine(line);
-  }
-  flushStderr() {
-    const rest = (this.stderrPartial + this.decoder.end()).trim();
-    this.stderrPartial = "";
-    this.decoder = new import_node_string_decoder.StringDecoder("utf8");
-    if (rest)
-      this.pushLine(rest);
-  }
-  pushLine(line) {
-    const text = lastBytes(line.trim().replace(/\x1b\[[0-9;]*[A-Za-z]/g, ""));
-    if (!text)
-      return;
-    this.stderrTail.push(text);
-    this.stderrTailBytes += Buffer.byteLength(text, "utf8");
-    while (this.stderrTailBytes > STDERR_TAIL_BYTES && this.stderrTail.length > 1) {
-      const dropped = this.stderrTail.shift();
-      this.stderrTailBytes -= Buffer.byteLength(dropped, "utf8");
-    }
-    try {
-      this.opts.onLog?.(text);
-    } catch {}
-  }
-  tailText() {
-    return this.stderrTail.join(`
-`);
-  }
-  updateRef() {
-    const child = this.child;
-    if (!child || child.exitCode !== null || child.signalCode !== null)
-      return;
-    try {
-      if (this.pending.size > 0 || this.starting !== null)
-        child.ref();
-      else
-        child.unref();
-    } catch {}
-  }
-  onDeath(error) {
-    const child = this.child;
-    this.child = null;
-    this.reader?.close();
-    this.reader = null;
+  constructor(engine, version, timeoutMs, unsubscribe) {
+    this.engine = engine;
+    this.version = version;
+    this.timeoutMs = timeoutMs;
+    this.unsubscribe = unsubscribe;
+  }
+  static async start(opts) {
+    const timeoutMs = deadline(opts.timeoutMs, DEFAULT_TIMEOUT_MS);
+    const addon = loadAddon(opts.addonPath);
+    const version = checkVersion(addon.version(), opts.sdkVersion);
+    const unsubscribe = opts.onLog ? subscribe(addon, opts.onLog, opts.logLevel) : () => {};
+    let opening;
+    let engine;
     try {
-      child?.kill();
-    } catch {}
-    const failure = this.closed ? new ConsolError("closed", "vault is closed", { cause: error }) : error;
-    for (const pending of this.pending.values())
-      pending.reject(failure);
-    this.pending.clear();
-    this.updateRef();
+      opening = addon.openEngine(JSON.stringify(opts.location), engineSettings(opts));
+      engine = await race(opening, "start", timeoutMs);
+    } catch (error) {
+      unsubscribe();
+      opening?.then((late) => late.close()).catch(() => {});
+      throw engineError(error);
+    }
+    const transport = new NativeTransport(engine, version, timeoutMs, unsubscribe);
+    const { boot } = opts;
+    if (boot) {
+      try {
+        const error = replyError(await transport.vaultOp(boot.create ? "create_vault" : "open_vault", boot.vault));
+        if (error)
+          throw error;
+      } catch (error) {
+        await transport.close().catch(() => {});
+        throw error;
+      }
+    }
+    return transport;
   }
   close() {
     this.closing ??= this.shutdown();
     return this.closing;
   }
   async shutdown() {
-    this.closed = true;
-    const child = this.child;
-    this.child = null;
-    this.reader?.close();
-    this.reader = null;
-    const failure = new ConsolError("closed", "vault is closed");
-    for (const pending of this.pending.values())
-      pending.reject(failure);
-    this.pending.clear();
-    if (!child)
-      return;
-    await new Promise((resolve) => {
-      if (!child.pid || child.exitCode !== null || child.signalCode !== null) {
-        resolve();
-        return;
-      }
-      const terminate = setTimeout(() => {
-        try {
-          child.kill();
-        } catch {}
-      }, EXIT_WAIT_MS);
-      const force = setTimeout(() => {
-        try {
-          child.kill("SIGKILL");
-        } catch {}
-      }, KILL_WAIT_MS);
-      child.once("close", () => {
-        clearTimeout(terminate);
-        clearTimeout(force);
-        resolve();
-      });
-      try {
-        child.stdin?.end();
-      } catch {
-        resolve();
-      }
-    });
-  }
-  async start() {
-    if (this.closed)
-      throw new ConsolError("closed", "vault is closed");
-    if (!this.starting && !this.child)
-      this.starting = this.spawn();
-    if (this.starting) {
-      try {
-        await this.starting;
-      } finally {
-        this.starting = null;
-        this.updateRef();
-      }
-    }
-    if (this.closed)
-      throw new ConsolError("closed", "vault is closed");
-  }
-  async spawn() {
-    const generation = ++this.generation;
-    const child = import_node_child_process.spawn(this.binary, ["stdio", ...this.opts.location], {
-      stdio: ["pipe", "pipe", "pipe"],
-      env: childEnv(engineEnv(this.opts), this.opts.env)
-    });
-    this.child = child;
-    for (const stream of [child.stdin, child.stdout, child.stderr])
-      stream?.unref?.();
-    this.updateRef();
-    child.stderr?.on("data", (chunk) => this.onStderr(chunk));
-    child.stderr?.on("error", () => {});
-    const dead = (reason, cause) => {
-      if (this.child !== child)
-        return;
-      this.flushStderr();
-      const tail = this.stderrTail.slice(-3).join(" | ");
-      this.onDeath(new ConsolError("server_exited", `${reason}${tail ? `: ${tail}` : ""}`, {
-        stderrTail: this.tailText() || undefined,
-        ...cause === undefined ? {} : { cause }
-      }));
-    };
-    child.once("error", (error) => {
-      if (error?.code === "ENOENT") {
-        if (this.child !== child)
-          return;
-        this.onDeath(new ConsolError("binary_not_found", `binary not found: ${this.binary}`, {
-          stderrTail: this.attempts.join(`
-`),
-          cause: error
-        }));
-      } else {
-        dead(`server failed to start: ${error.message}`, error);
-      }
-    });
-    child.once("exit", (code, signal) => {
-      dead(`server exited (${signal ?? code})`);
-    });
-    child.stdin?.on("error", () => {
-      dead("server stdin failed");
-    });
-    const reader = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
-    this.reader = reader;
-    reader.once("close", () => {
-      dead("server closed output");
-    });
-    reader.on("line", (line) => {
-      if (this.child === child && generation === this.generation)
-        this.onLine(line);
-    });
+    this.closed.abort();
+    this.unsubscribe();
     try {
-      checkVersion(await this.call("ready", READY, null, {}), this.opts.sdkVersion);
-      const boot = this.opts.boot;
-      if (boot) {
-        const op = boot.create && !this.started ? "create_vault" : "open_vault";
-        const reply = await this.call(op, this.nextId++, { op, vault: boot.vault }, {});
-        const error = replyError(reply);
-        if (error)
-          throw error;
-      }
-      this.started = true;
-      this.stderrTail = [];
-      this.stderrTailBytes = 0;
+      await this.engine.close();
     } catch (error) {
-      if (this.child === child) {
-        this.child = null;
-        this.reader?.close();
-        this.reader = null;
-        try {
-          child.kill();
-        } catch {}
-      }
-      throw error instanceof ConsolError ? error : new ConsolError("internal", String(error), { cause: error });
+      throw engineError(error);
     }
   }
-  onLine(line) {
-    if (!line.trim())
-      return;
-    let msg;
+  async send(frame, options) {
+    const { signal } = options;
+    if (this.closed.signal.aborted)
+      throw new ConsolError("closed", "vault is closed");
+    if (signal?.aborted)
+      throw new ConsolError("aborted", `${frame.op} aborted before dispatch`, { cause: signal.reason });
+    const ms = deadline(options.timeoutMs, this.timeoutMs);
+    let text;
     try {
-      msg = JSON.parse(line);
-    } catch {
-      this.onDeath(new ConsolError("server_exited", "invalid JSON from server", {
-        stderrTail: this.tailText() || undefined
-      }));
-      return;
-    }
-    const id = msg?.ready === true ? READY : msg?.id;
-    if (typeof id !== "number")
-      return;
-    const pending = this.pending.get(id);
-    if (!pending || pending.settled)
-      return;
-    this.pending.delete(id);
-    if (id === READY) {
-      pending.resolve(msg.version);
-    } else {
-      try {
-        this.version = checkVersion(msg.reply?.version, this.opts.sdkVersion);
-        pending.resolve(msg.reply);
-      } catch (error) {
-        pending.reject(error);
-      }
+      text = JSON.stringify(frame);
+    } catch (cause) {
+      throw new ConsolError("invalid_argument", `${frame.op}: body is not JSON`, { cause });
     }
-    this.updateRef();
-  }
-  call(label, id, frame, options) {
-    return new Promise((resolve, reject) => {
-      const signal = options.signal;
-      if (signal?.aborted) {
-        reject(new ConsolError("aborted", `${label} aborted before dispatch`, { cause: signal.reason }));
-        return;
-      }
-      let line = null;
-      let timeoutMs;
-      try {
-        timeoutMs = deadline(options.timeoutMs, this.timeoutMs);
-        line = frame ? JSON.stringify({ id, ...frame }) + `
-` : null;
-      } catch (error) {
-        reject(ConsolError.is(error) ? error : new ConsolError("invalid_argument", `${label}: body is not JSON`, { cause: error }));
-        return;
-      }
-      const input = this.child?.stdin;
-      if (line && !input?.writable) {
-        reject(new ConsolError(this.closed ? "closed" : "server_exited", "server is not running"));
-        return;
-      }
-      const pending = { resolve, reject, settled: false };
-      const done = (error, value) => {
-        if (pending.settled)
-          return;
-        pending.settled = true;
-        if (pending.timer !== undefined)
-          clearTimeout(pending.timer);
-        if (pending.onAbort && signal)
-          signal.removeEventListener("abort", pending.onAbort);
-        this.pending.delete(id);
-        if (error)
-          reject(error);
-        else
-          resolve(value);
-        this.updateRef();
-      };
-      pending.resolve = (value) => done(null, value);
-      pending.reject = (error) => done(error);
-      if (timeoutMs > 0) {
-        pending.timer = setTimeout(() => done(new ConsolError("timeout", `${label} timed out after ${timeoutMs}ms`)), timeoutMs);
-        pending.timer.unref?.();
-      }
-      if (signal) {
-        pending.onAbort = () => done(new ConsolError("aborted", `${label} aborted`, { cause: signal.reason }));
-        signal.addEventListener("abort", pending.onAbort, { once: true });
-      }
-      this.pending.set(id, pending);
-      this.updateRef();
-      if (line) {
-        input.write(line, (error) => {
-          if (error)
-            done(new ConsolError("server_exited", "server stdin failed", { cause: error }));
-        });
-      }
-    });
-  }
-  async send(frame, options) {
-    if (options.signal?.aborted) {
-      throw new ConsolError("aborted", `${frame.op} aborted before dispatch`, { cause: options.signal.reason });
+    try {
+      return JSON.parse(await race(this.engine.request(text), frame.op, ms, this.closed.signal, signal));
+    } catch (error) {
+      throw engineError(error);
     }
-    await this.start();
-    return await this.call(frame.op, this.nextId++, frame, options);
   }
   handle(body, ctx, options = {}) {
     return this.send({ op: "handle", ctx: { vaults: ctx.vaults, agent: ctx.agent ?? null }, body }, options);
@@ -624,7 +351,7 @@ class StdioTransport {
 }
 
 // src/vault.ts
-var import_node_path = require("node:path");
+var import_node_path2 = require("node:path");
 
 // src/types.ts
 function sliceUtf8(text, start, end) {
@@ -646,7 +373,7 @@ function sliceUtf8(text, start, end) {
 }
 
 // src/vault.ts
-var CLIENT_INFO = { name: "consol-js-client", version: "0.1.0" };
+var CLIENT_INFO = { name: "consol-js-client", version: "0.2.1" };
 var LOCAL = "default";
 function payload(tool, reply) {
   const error = replyError(reply, tool);
@@ -709,19 +436,13 @@ function required(options, fields) {
 }
 async function local(options, create) {
   required(options, ["path", "agent"]);
-  const path = options.path.startsWith("s3://") ? options.path : import_node_path.resolve(options.path);
-  const transport = new StdioTransport({
+  const path = options.path.startsWith("s3://") ? options.path : import_node_path2.resolve(options.path);
+  const transport = await NativeTransport.start({
     ...options,
-    location: ["--vault", path],
+    location: { vault: path },
     boot: { vault: LOCAL, create },
     sdkVersion: CLIENT_INFO.version
   });
-  try {
-    await transport.start();
-  } catch (error) {
-    await transport.close();
-    throw error;
-  }
   return construct(transport, LOCAL, options.agent);
 }
 function createVault(options) {
@@ -777,18 +498,11 @@ class Consol {
     if (vaultRoot === undefined === (vault === undefined)) {
       throw new ConsolError("invalid_argument", "give exactly one of vaultRoot or vault", { field: "vaultRoot" });
     }
-    const transport = new StdioTransport({
+    return new Consol(await NativeTransport.start({
       ...engine,
-      location: vaultRoot === undefined ? ["--vault", vault] : ["--vault-root", vaultRoot],
+      location: vaultRoot === undefined ? { vault } : { vaultRoot },
       sdkVersion: CLIENT_INFO.version
-    });
-    try {
-      await transport.start();
-    } catch (error) {
-      await transport.close();
-      throw error;
-    }
-    return new Consol(transport);
+    }));
   }
   async handle(body, ctx, options) {
     if (ctx === null || typeof ctx !== "object" || ctx.vaults !== null && !Array.isArray(ctx.vaults)) {

package/dist/native.d.ts

@@ -0,0 +1,94 @@
+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. */
+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). */
+export interface JevOptions {
+    url?: string;
+    apiKey?: string;
+    model?: string;
+    /** `false` turns automatic triage off. */
+    auto?: boolean;
+}
+/**
+ * What starts the in-process engine. Options become its settings (the CONSOL_* map); this process's
+ * own CONSOL_* variables are never read, except CONSOL_DB_URL as the default database.
+ */
+export interface EngineOptions {
+    /** Database URL: PostgreSQL with pgvector, or CockroachDB. Without it this process's `CONSOL_DB_URL` applies; the engine needs one. */
+    db?: string;
+    embedding?: EmbeddingOptions;
+    jev?: JevOptions;
+    /** Explicit `consol.node`; otherwise CONSOL_ADDON, then the platform package. */
+    addonPath?: string;
+    /** Any other engine setting (a CONSOL_* name), applied last. */
+    env?: Record<string, string>;
+    /** Default per-call deadline in ms (300000); 0 disables it. */
+    timeoutMs?: number;
+    /** Receives each engine log line. One sink is shared by every engine in the process. */
+    onLog?: (line: string) => void;
+    /** Which engine lines reach `onLog`: an EnvFilter directive such as `info` or `consol_engine=debug` (default `warn`). Process-wide like the sink: the latest one set wins. */
+    logLevel?: string;
+}
+export declare function engineSettings(o: EngineOptions): Record<string, string>;
+/** One opened engine of `consol.node`. A frame is the JSON of `{op, ...}`; the answer is the Reply JSON. */
+export interface NativeEngine {
+    request(frame: string): Promise<string>;
+    close(): Promise<void>;
+}
+/** What the SDK uses of `consol.node`. Failures reject with an Error whose message is JSON `{code, message, field?}`. */
+export interface Addon {
+    version(): string;
+    /** `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;
+}
+/**
+ * Explicit path authoritative (a missing file fails here), then CONSOL_ADDON authoritative, then the
+ * platform package resolved relative to this SDK file. CONSOL_ADDON is read only here. Loaded on
+ * first use, so importing the SDK never fails.
+ */
+export declare function loadAddon(explicit?: string): Addon;
+export interface NativeOptions extends EngineOptions {
+    location: {
+        vaultRoot: string;
+    } | {
+        vault: string;
+    };
+    /** After opening the engine: create or open this vault. */
+    boot?: {
+        vault: string;
+        create: boolean;
+    };
+    /** The SDK version the addon's major.minor must match. */
+    sdkVersion: string;
+}
+/** The engine of `consol.node` in this process: one frame per call, answered by a Reply JSON, in any order. */
+export declare class NativeTransport implements Transport {
+    private readonly engine;
+    readonly version: string;
+    private readonly timeoutMs;
+    private readonly unsubscribe;
+    private readonly closed;
+    private closing;
+    private constructor();
+    /** Loads the addon, checks its version, opens the engine and runs the boot step; a failure leaves nothing open. */
+    static start(opts: NativeOptions): Promise<NativeTransport>;
+    /** Final and idempotent: in-flight and later calls fail with `closed`. Every close() returns the same promise. */
+    close(): Promise<void>;
+    private shutdown;
+    private send;
+    /** Runs one envelope under `ctx`. The reply is returned untouched, tool errors included. */
+    handle(body: unknown, ctx: Context, options?: CallOptions): Promise<Reply>;
+    /** Create or open a vault by name; a refusal arrives as the reply's `vault_exists` / `vault_not_found`. */
+    vaultOp(op: "create_vault" | "open_vault", vault: string, options?: CallOptions): Promise<Reply>;
+}

package/dist/transport.d.ts

@@ -12,9 +12,9 @@ export interface Context {
     /** Pins the agent; the request cannot name another one. */
     agent?: string | null;
 }
-/** One way to move an envelope: a stdio child or HTTP. Internal: only Vault and Consol are public. */
+/** One way to move an envelope: the in-process engine or HTTP. Internal: only Vault and Consol are public. */
 export interface Transport {
-    /** Server version of the last reply; null before the first. */
+    /** Engine version (known at start) or, over HTTP, that of the last reply; null before the first. */
     readonly version: string | null;
     handle(body: unknown, ctx: Context, options?: CallOptions): Promise<Reply>;
     /** Final and idempotent. */
@@ -24,6 +24,7 @@ export interface Transport {
 export declare function deadline(ms: number | undefined, fallback: number): number;
 /** Server major.minor must equal the SDK's; returns the server version. */
 export declare function checkVersion(got: unknown, sdk: string): string;
+export declare const anySignal: (signals: AbortSignal[]) => AbortSignal;
 /** POSTs the envelope to `url`; the caller's headers are the backend's auth. Stateless. */
 export declare class HttpTransport implements Transport {
     private readonly url;

package/dist/types.d.ts

@@ -208,11 +208,6 @@ export interface SharedFacetLead {
     route: "shared_facet";
     value: string;
 }
-/** Pair found through a shared numeric value. */
-export interface SharedNumericLead {
-    route: "shared_numeric";
-    value: string;
-}
 /** Pair found through embedding similarity (embeddings on only). */
 export interface SemanticLead {
     route: "semantic";
@@ -224,7 +219,7 @@ export interface SemanticLead {
     score: number;
 }
 /** Discovery witness of a pair; one witness, not an exhaustive list or a truth judgment. */
-export type PairLead = AuthoredLead | SharedFacetLead | SharedNumericLead | SemanticLead;
+export type PairLead = AuthoredLead | SharedFacetLead | SemanticLead;
 /** Hub witness; `target` is null when a new hub would be formed. Unstable: checked against Rust source only. */
 export interface HubLead {
     route: "hub";

package/dist/vault.d.ts

@@ -1,4 +1,4 @@
-import { type EngineOptions } from "./stdio";
+import { type EngineOptions } from "./native";
 import { type CallOptions } from "./transport";
 import type { ConsolidationDisposition, PairDisposition, ReadResult, RecallResult, Reply, ReflectResult, RememberResult, RemoveResult, Scope, SourceDisposition } from "./types";
 export { sliceUtf8 } from "./types";
@@ -6,7 +6,7 @@ export declare const CLIENT_INFO: {
     name: string;
     version: string;
 };
-/** Local vault: the SDK spawns `consol stdio` for it. */
+/** Local vault: the engine runs in this process. */
 export interface VaultOptions extends EngineOptions {
     /** Local directory, or `s3://bucket[/prefix]/<name>` (needs `db`; AWS_* from the environment). */
     path: string;
@@ -97,12 +97,15 @@ export type Decision = {
     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 {
@@ -151,13 +154,13 @@ export interface ReflectArgs {
     limit?: number;
     decisions?: Decision[];
 }
-/** One vault behind a transport (a local child or a hosted backend). Build it with createVault or openVault; close() is final. */
+/** One vault behind a transport (the in-process engine or a hosted backend). Build it with createVault or openVault; close() is final. */
 export declare class Vault {
     private readonly transport;
     private readonly vault;
     private readonly agent;
     private constructor();
-    /** Server version of the last reply; null before the first. */
+    /** Engine version (known once opened); a hosted vault's is that of the last reply, null before the first. */
     get serverVersion(): string | null;
     /** Final and idempotent; concurrent calls share one completion. Later calls fail with `closed`. */
     close(): Promise<void>;
@@ -171,10 +174,10 @@ export declare class Vault {
     remove(args: RemoveArgs | ResumeArgs, options?: CallOptions): Promise<RemoveResult>;
     reflect(args?: ReflectArgs, options?: CallOptions): Promise<ReflectResult>;
 }
-/** Creates the vault and starts its child; fails with `vault_exists` when a vault marker exists. */
+/** Creates the vault and opens its engine; fails with `vault_exists` when a vault marker exists. */
 export declare function createVault(options: VaultOptions): Promise<Vault>;
 /**
- * Local: starts the child of an existing vault (`vault_not_found` when no marker exists). Hosted
+ * Local: opens the engine of an existing vault (`vault_not_found` when no marker exists). Hosted
  * (`url`): no round trip here, a missing vault is `vault_not_found` on the first call.
  */
 export declare function openVault(options: VaultOptions | HostedOptions): Promise<Vault>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keb-org/consol",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Consol memory engine SDK: a local vault, a hosted vault client, and the Consol backend class",
   "keywords": [
     "mcp",
@@ -39,8 +39,8 @@
   "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",
     "typecheck": "tsc --noEmit --pretty false",
-    "test": "bun run build && bun test/pure.ts && node test/http.ts && node test/sdk.ts && tsc --noEmit --pretty false -p test",
-    "test:offline": "bun run build && bun test/pure.ts && node test/http.ts && tsc --noEmit --pretty false -p test",
+    "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",
     "test:consumers": "bun run build && bash consumers/run.sh"
   },
   "devDependencies": {
@@ -51,10 +51,10 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@keb-org/consol-win32-x64": "0.1.0",
-    "@keb-org/consol-darwin-arm64": "0.1.0",
-    "@keb-org/consol-darwin-x64": "0.1.0",
-    "@keb-org/consol-linux-x64": "0.1.0",
-    "@keb-org/consol-linux-arm64": "0.1.0"
+    "@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"
   }
 }

package/dist/stdio.d.ts

@@ -1,120 +0,0 @@
-import { type CallOptions, type Context, type Transport } from "./transport";
-import type { Reply } from "./types";
-/** Bound of the kept stderr tail and of any one line, in UTF-8 bytes. */
-export declare const STDERR_TAIL_BYTES = 4096;
-/** Any OpenAI-shaped `/embeddings` endpoint; 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). */
-export interface JevOptions {
-    url?: string;
-    apiKey?: string;
-    model?: string;
-    /** `false` turns automatic triage off. */
-    auto?: boolean;
-}
-/**
- * What starts the `consol stdio` child. Options become the child's environment (never argv);
- * inherited CONSOL_* and RUST_LOG are stripped first and `env` is applied last.
- */
-export interface EngineOptions {
-    /** Database URL: PostgreSQL with pgvector, or CockroachDB. Without it this process's `CONSOL_DB_URL` applies; the child needs one. */
-    db?: string;
-    embedding?: EmbeddingOptions;
-    jev?: JevOptions;
-    /** Explicit binary; otherwise CONSOL_BIN, the platform package, then PATH. */
-    binaryPath?: string;
-    env?: Record<string, string>;
-    /** Default per-call deadline in ms (300000); 0 disables it. */
-    timeoutMs?: number;
-    /** Receives each child stderr line. Without it lines are only kept for error messages. */
-    onLog?: (line: string) => void;
-}
-export declare function engineEnv(o: EngineOptions): Record<string, string>;
-export interface StdioOptions extends EngineOptions {
-    /** `--vault PATH` or `--vault-root ROOT`. */
-    location: ["--vault" | "--vault-root", string];
-    /** After the ready line: create (first start only) or open this vault. A restart always opens. */
-    boot?: {
-        vault: string;
-        create: boolean;
-    };
-    /** The SDK version the child's major.minor must match. */
-    sdkVersion: string;
-}
-export interface BinaryResolution {
-    path: string;
-    attempts: string[];
-}
-/**
- * Explicit path authoritative (missing file fails here), then CONSOL_BIN authoritative, then the
- * platform package resolved relative to this SDK file, then PATH. CONSOL_BIN is read only here,
- * never sent to the child.
- */
-export declare function resolveBinary(explicit?: string): BinaryResolution;
-/** Child env: host minus ALL CONSOL_* and RUST_LOG, then options, then explicit env last. */
-export declare function childEnv(base?: Record<string, string>, extra?: Record<string, string>): Record<string, string>;
-/** The last STDERR_TAIL_BYTES bytes of `text`, cut on a character boundary. */
-export declare function lastBytes(text: string): string;
-/**
- * One `consol stdio` child speaking JSON lines (docs W-wire): a ready line, then `{id, op, ...}`
- * frames answered by `{id, reply}` lines in any order. Stdin EOF ends the child gracefully.
- */
-export declare class StdioTransport implements Transport {
-    private readonly opts;
-    private readonly attempts;
-    private readonly binary;
-    private readonly timeoutMs;
-    private child;
-    private reader;
-    private generation;
-    private nextId;
-    private pending;
-    private starting;
-    /** After the first successful start, every restart opens the vault instead of creating it. */
-    private started;
-    private closed;
-    private closing;
-    private stderrTail;
-    private stderrTailBytes;
-    version: string | null;
-    constructor(opts: StdioOptions);
-    private decoder;
-    private stderrPartial;
-    private onStderr;
-    private flushStderr;
-    private pushLine;
-    private tailText;
-    /**
-     * Idle children are unref'd so a forgotten close() never keeps Node or Bun alive. Only the process
-     * handle toggles (its stdio is unref'd once at spawn): Bun cannot unref a stream again once ref'd.
-     */
-    private updateRef;
-    private onDeath;
-    /**
-     * Final and idempotent: in-flight calls reject now, later calls with `closed`. Every close()
-     * returns the same promise, settled once the child has exited.
-     */
-    close(): Promise<void>;
-    private shutdown;
-    /** Starts the child and waits for its ready line, unless one is running or starting already. */
-    start(): Promise<void>;
-    private spawn;
-    private onLine;
-    /** Waits for the answer to `id`, writing `frame` first unless it is null (the ready line). */
-    private call;
-    /** One frame; after a crash the next call starts the child once more. Never retried. */
-    private send;
-    /** Runs one envelope under `ctx`. The reply is returned untouched, tool errors included. */
-    handle(body: unknown, ctx: Context, options?: CallOptions): Promise<Reply>;
-    /** Create or open a vault by name; a refusal arrives as the reply's `vault_exists` / `vault_not_found`. */
-    vaultOp(op: "create_vault" | "open_vault", vault: string, options?: CallOptions): Promise<Reply>;
-}