@keb-org/consol 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,815 @@
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+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)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  Consol: () => Consol,
+  ConsolError: () => ConsolError,
+  Vault: () => Vault,
+  createVault: () => createVault,
+  httpStatus: () => httpStatus,
+  openVault: () => openVault,
+  sliceUtf8: () => sliceUtf8
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/errors.ts
+var BRAND = "__consolError";
+
+class ConsolError extends Error {
+  code;
+  retryable;
+  field;
+  tool;
+  status;
+  stderrTail;
+  result;
+  constructor(code, message, details = {}) {
+    super(message, details.cause === undefined ? undefined : { cause: details.cause });
+    this.name = "ConsolError";
+    this.code = code;
+    this.retryable = details.retryable ?? (code === "vault_busy" || code === "index_unavailable" || code === "storage_unavailable");
+    if (details.field !== undefined)
+      this.field = details.field;
+    if (details.tool !== undefined)
+      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 });
+  }
+  static is(error) {
+    return error instanceof ConsolError || typeof error === "object" && error !== null && error[BRAND] === true;
+  }
+}
+function replyError(reply, tool) {
+  const e = reply.error;
+  if (!e)
+    return;
+  return new ConsolError(e.code ?? "internal", e.message ?? `${tool ?? "request"} failed`, {
+    retryable: e.retryable,
+    field: e.field,
+    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/transport.ts
+var DEFAULT_TIMEOUT_MS = 300000;
+function deadline(ms, fallback) {
+  const value = ms ?? fallback;
+  if (!Number.isInteger(value) || value < 0)
+    throw new ConsolError("invalid_argument", `invalid timeoutMs ${String(ms)}`);
+  return value;
+}
+function checkVersion(got, sdk) {
+  const semver = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+  const server = typeof got === "string" ? semver.exec(got) : null;
+  const own = semver.exec(sdk);
+  if (!server || !own || server[1] !== own[1] || server[2] !== own[2]) {
+    throw new ConsolError("incompatible_server", `server ${String(got ?? "unknown")} is not SDK ${sdk} (major.minor must match)`);
+  }
+  return got;
+}
+var anySignal = (signals) => AbortSignal.any(signals);
+var RETRYABLE_STATUS = [502, 503, 504];
+
+class HttpTransport {
+  url;
+  headers;
+  timeoutMs;
+  sdkVersion;
+  version = null;
+  closed = new AbortController;
+  constructor(url, headers, timeoutMs, sdkVersion) {
+    this.url = url;
+    this.headers = headers;
+    this.timeoutMs = timeoutMs;
+    this.sdkVersion = sdkVersion;
+  }
+  async handle(body, _ctx, options = {}) {
+    if (this.closed.signal.aborted)
+      throw new ConsolError("closed", "vault is closed");
+    const ms = deadline(options.timeoutMs, this.timeoutMs);
+    const user = options.signal;
+    if (user?.aborted)
+      throw new ConsolError("aborted", "request aborted before dispatch", { cause: user.reason });
+    const timer = ms > 0 ? AbortSignal.timeout(ms) : undefined;
+    const headers = new Headers(this.headers);
+    headers.set("content-type", "application/json");
+    let status;
+    let text;
+    try {
+      const res = await fetch(this.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: anySignal([this.closed.signal, ...user ? [user] : [], ...timer ? [timer] : []])
+      });
+      status = res.status;
+      text = await res.text();
+    } catch (error) {
+      if (this.closed.signal.aborted)
+        throw new ConsolError("closed", "vault is closed", { cause: error });
+      if (user?.aborted)
+        throw new ConsolError("aborted", "request aborted", { cause: error });
+      if (timer?.aborted)
+        throw new ConsolError("timeout", `request timed out after ${ms}ms`, { cause: error });
+      const code = error?.cause?.code;
+      throw new ConsolError("request_failed", `request failed: ${code ?? error?.message ?? String(error)}`, {
+        retryable: true,
+        cause: error
+      });
+    }
+    let reply;
+    try {
+      const parsed = JSON.parse(text);
+      if (typeof parsed?.version === "string")
+        reply = parsed;
+    } catch {}
+    if (!reply) {
+      if (status === 401 || status === 403)
+        throw new ConsolError("forbidden", `request refused (HTTP ${status})`, { status });
+      throw new ConsolError("request_failed", `not a consol reply (HTTP ${status})`, { status, retryable: RETRYABLE_STATUS.includes(status) });
+    }
+    this.version = checkVersion(reply.version, this.sdkVersion);
+    return reply;
+  }
+  close() {
+    this.closed.abort();
+    return Promise.resolve();
+  }
+}
+
+// src/stdio.ts
+var STDERR_TAIL_BYTES = 4096;
+var EXIT_WAIT_MS = 2000;
+var KILL_WAIT_MS = 4000;
+function engineEnv(o) {
+  const env = {};
+  const db = o.db ?? process.env.CONSOL_DB_URL;
+  if (db !== undefined)
+    env.CONSOL_DB_URL = db;
+  const e = o.embedding;
+  if (e !== undefined) {
+    env.CONSOL_EMBED_URL = e.url;
+    if (e.apiKey !== undefined)
+      env.CONSOL_EMBED_API_KEY = e.apiKey;
+    env.CONSOL_EMBED_MODEL = e.model;
+    if (e.dims !== undefined)
+      env.CONSOL_EMBED_DIMS = String(e.dims);
+    if (e.queryPrefix !== undefined)
+      env.CONSOL_EMBED_QUERY_PREFIX = e.queryPrefix;
+    if (e.batchSize !== undefined)
+      env.CONSOL_EMBED_BATCH = String(e.batchSize);
+    if (e.timeoutMs !== undefined)
+      env.CONSOL_EMBED_TIMEOUT_MS = String(e.timeoutMs);
+  }
+  const j = o.jev;
+  if (j !== undefined) {
+    if (j.url !== undefined)
+      env.CONSOL_JEV_URL = j.url;
+    if (j.apiKey !== undefined)
+      env.CONSOL_JEV_API_KEY = j.apiKey;
+    if (j.model !== undefined)
+      env.CONSOL_JEV_MODEL = j.model;
+    if (j.auto === false)
+      env.CONSOL_JEV_AUTO = "0";
+  }
+  return env;
+}
+function platformExe() {
+  return process.platform === "win32" ? "consol.exe" : "consol";
+}
+function isFile(path) {
+  try {
+    return import_node_fs.statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+function missingBinary(attempt) {
+  return new ConsolError("binary_not_found", `binary not found: ${attempt}`, { stderrTail: attempt });
+}
+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}`;
+  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 };
+}
+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");
+}
+var READY = 0;
+
+class StdioTransport {
+  opts;
+  attempts;
+  binary;
+  timeoutMs;
+  child = null;
+  reader = null;
+  generation = 0;
+  nextId = 1;
+  pending = new Map;
+  starting = null;
+  started = false;
+  closed = false;
+  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;
+    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();
+  }
+  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);
+    });
+    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;
+    } 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 });
+    }
+  }
+  onLine(line) {
+    if (!line.trim())
+      return;
+    let msg;
+    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);
+      }
+    }
+    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 });
+    }
+    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);
+  }
+  vaultOp(op, vault, options = {}) {
+    return this.send({ op, vault }, options);
+  }
+}
+
+// src/vault.ts
+var import_node_path = require("node:path");
+
+// src/types.ts
+function sliceUtf8(text, start, end) {
+  if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start) {
+    throw new RangeError(`invalid byte range [${start}, ${end})`);
+  }
+  const bytes = Buffer.from(text, "utf8");
+  if (end > bytes.length) {
+    throw new RangeError(`byte range [${start}, ${end}) exceeds text length ${bytes.length}`);
+  }
+  const isContinuation = (b) => (b & 192) === 128;
+  if (start > 0 && isContinuation(bytes[start])) {
+    throw new RangeError(`start ${start} splits a UTF-8 character`);
+  }
+  if (end < bytes.length && isContinuation(bytes[end])) {
+    throw new RangeError(`end ${end} splits a UTF-8 character`);
+  }
+  return bytes.subarray(start, end).toString("utf8");
+}
+
+// src/vault.ts
+var CLIENT_INFO = { name: "consol-js-client", version: "0.1.0" };
+var LOCAL = "default";
+function payload(tool, reply) {
+  const error = replyError(reply, tool);
+  if (error)
+    throw error;
+  if (tool === "recall")
+    return { ...reply.result, text: reply.text ?? "" };
+  return reply.result;
+}
+var construct;
+
+class Vault {
+  transport;
+  vault;
+  agent;
+  static {
+    construct = (transport, vault, agent) => new Vault(transport, vault, agent);
+  }
+  constructor(transport, vault, agent) {
+    this.transport = transport;
+    this.vault = vault;
+    this.agent = agent;
+  }
+  get serverVersion() {
+    return this.transport.version;
+  }
+  close() {
+    return this.transport.close();
+  }
+  [Symbol.asyncDispose]() {
+    return this.close();
+  }
+  callTool(name, args, options) {
+    const agent = typeof args.agent === "string" ? args.agent : this.agent;
+    const ctx = { vaults: [this.vault], agent: null };
+    return this.transport.handle({ tool: name, vault: this.vault, agent, args }, ctx, options);
+  }
+  async recall(args, options) {
+    return payload("recall", await this.callTool("recall", { ...args }, options));
+  }
+  async read(args, options) {
+    return payload("read", await this.callTool("read", { ...args }, options));
+  }
+  async remember(args, options) {
+    return payload("remember", await this.callTool("remember", { ...args }, options));
+  }
+  async remove(args, options) {
+    return payload("remove", await this.callTool("remove", { ...args }, options));
+  }
+  async reflect(args = {}, options) {
+    return payload("reflect", await this.callTool("reflect", { ...args }, options));
+  }
+}
+function required(options, fields) {
+  for (const field of fields) {
+    const value = options?.[field];
+    if (typeof value !== "string" || value === "")
+      throw new ConsolError("invalid_argument", `${field} is required`, { field });
+  }
+}
+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({
+    ...options,
+    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) {
+  return local(options, true);
+}
+async function openVault(options) {
+  const hosted = options;
+  if (hosted?.url === undefined)
+    return local(options, false);
+  required(options, ["url", "vault", "agent"]);
+  if (options.path !== undefined) {
+    throw new ConsolError("invalid_argument", "give either path (local) or url (hosted), not both", { field: "path" });
+  }
+  let url;
+  try {
+    url = new URL(hosted.url);
+  } catch {
+    throw new ConsolError("invalid_argument", "url is not a valid URL", { field: "url" });
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new ConsolError("invalid_argument", "url must be http or https", { field: "url" });
+  }
+  const { vault, agent, headers = {}, timeoutMs } = options;
+  const transport = new HttpTransport(url.href, headers, timeoutMs ?? 300000, CLIENT_INFO.version);
+  return construct(transport, vault, agent);
+}
+
+// src/consol.ts
+var STATUS = new Map;
+for (const [status, codes] of [
+  [400, "invalid_argument secret_rejected"],
+  [403, "forbidden"],
+  [404, "not_found work_not_found vault_not_found"],
+  [409, "already_exists vault_exists version_conflict basis_mismatch already_decided unresolved_writes"],
+  [413, "content_too_large"],
+  [422, "unsupported postcondition_failed team_not_attached"],
+  [503, "vault_busy index_unavailable storage_unavailable"]
+]) {
+  for (const code of codes.split(" "))
+    STATUS.set(code, status);
+}
+function httpStatus(reply) {
+  return reply.error ? STATUS.get(reply.error.code) ?? 500 : 200;
+}
+
+class Consol {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  static async start(options) {
+    const { vaultRoot, vault, ...engine } = options ?? {};
+    if (vaultRoot === undefined === (vault === undefined)) {
+      throw new ConsolError("invalid_argument", "give exactly one of vaultRoot or vault", { field: "vaultRoot" });
+    }
+    const transport = new StdioTransport({
+      ...engine,
+      location: vaultRoot === undefined ? ["--vault", vault] : ["--vault-root", 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)) {
+      throw new ConsolError("invalid_argument", "ctx.vaults is a list of vault names, or null for any", { field: "ctx.vaults" });
+    }
+    if (ctx.agent !== undefined && ctx.agent !== null && typeof ctx.agent !== "string") {
+      throw new ConsolError("invalid_argument", "ctx.agent is a string", { field: "ctx.agent" });
+    }
+    return this.transport.handle(body, ctx, options);
+  }
+  async createVault(name, options) {
+    const error = replyError(await this.transport.vaultOp("create_vault", name, options));
+    if (error)
+      throw error;
+  }
+  async openVault(name, options) {
+    const error = replyError(await this.transport.vaultOp("open_vault", name, options));
+    if (error)
+      throw error;
+  }
+  close() {
+    return this.transport.close();
+  }
+}