@keb-org/consol 0.0.0-stage → 0.1.1

package/dist/vault.d.ts

@@ -0,0 +1,180 @@
+import { type EngineOptions } from "./stdio";
+import { type CallOptions } from "./transport";
+import type { ConsolidationDisposition, PairDisposition, ReadResult, RecallResult, Reply, ReflectResult, RememberResult, RemoveResult, Scope, SourceDisposition } from "./types";
+export { sliceUtf8 } from "./types";
+export declare const CLIENT_INFO: {
+    name: string;
+    version: string;
+};
+/** Local vault: the SDK spawns `consol stdio` for it. */
+export interface VaultOptions extends EngineOptions {
+    /** Local directory, or `s3://bucket[/prefix]/<name>` (needs `db`; AWS_* from the environment). */
+    path: string;
+    /** Default agent of every call; a call's own `agent` argument overrides it. */
+    agent: string;
+}
+/** Hosted vault: POSTs to a backend that runs `Consol.handle`. Backends create vaults, clients only open. */
+export interface HostedOptions {
+    url: string;
+    /** Sent with every request: the backend developer's own auth. */
+    headers?: Record<string, string>;
+    /** The backend's name for the vault. */
+    vault: string;
+    agent: string;
+    /** 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";
+    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";
+}
+/**
+ * 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.
+ */
+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;
+};
+/** Flat wire args for recall. */
+export interface RecallArgs {
+    query: string;
+    agent?: string;
+    include_history?: boolean;
+    limit?: number;
+}
+/** Flat wire args for read. */
+export interface ReadArgs {
+    id: string;
+    agent?: string;
+    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.
+ */
+export interface RememberArgs {
+    id: string;
+    agent?: string;
+    /** 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;
+}
+/** Flat wire args for remove (archives the note; its body stays readable). */
+export interface RemoveArgs {
+    id: string;
+    expected_version: string;
+    agent?: string;
+    reflection?: ReflectionContext;
+}
+/** Resume a pending reflection-bound write with the same context and tool. */
+export interface ResumeArgs {
+    resume: true;
+    reflection: ReflectionContext;
+    agent?: string;
+}
+/** Flat wire args for reflect. */
+export interface ReflectArgs {
+    agent?: string;
+    ids?: string[];
+    work_ids?: string[];
+    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. */
+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. */
+    get serverVersion(): string | null;
+    /** Final and idempotent; concurrent calls share one completion. Later calls fail with `closed`. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Raw call for LLM loops: tool errors come back as the reply's `error`, never thrown. */
+    callTool(name: string, args: Record<string, unknown>, options?: CallOptions): Promise<Reply>;
+    /** Leads, not proof: read a note before relying on it or editing it. */
+    recall(args: RecallArgs, options?: CallOptions): Promise<RecallResult>;
+    read(args: ReadArgs, options?: CallOptions): Promise<ReadResult>;
+    remember(args: RememberArgs | ResumeArgs, options?: CallOptions): Promise<RememberResult>;
+    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. */
+export declare function createVault(options: VaultOptions): Promise<Vault>;
+/**
+ * Local: starts the child 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,60 @@
 {
   "name": "@keb-org/consol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Consol memory engine SDK: a local vault, a hosted vault client, and the Consol backend class",
+  "keywords": [
+    "mcp",
+    "memory",
+    "agents",
+    "llm",
+    "markdown"
+  ],
+  "author": "Khas",
+  "homepage": "https://github.com/keb-org/consol/tree/main/bindings/js#readme",
+  "bugs": {
+    "url": "https://github.com/keb-org/consol/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keb-org/consol.git",
+    "directory": "bindings/js"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "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",
+    "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:consumers": "bun run build && bash consumers/run.sh"
+  },
+  "devDependencies": {
+    "typescript": "5.3.3",
+    "@types/node": "20.11.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "@keb-org/consol-win32-x64": "0.1.1",
+    "@keb-org/consol-darwin-arm64": "0.1.1",
+    "@keb-org/consol-darwin-x64": "0.1.1",
+    "@keb-org/consol-linux-x64": "0.1.1",
+    "@keb-org/consol-linux-arm64": "0.1.1"
+  }
+}