datanotes 2.0.0 → 3.0.0

package/dist/api/otlp.d.cts

@@ -0,0 +1,65 @@
+/**
+ * OpenTelemetry log export over OTLP/HTTP, vendor-neutral: records are buffered and POSTed to
+ * `<endpoint>/v1/logs` as `http/protobuf` (the OTLP default) or `http/json`, which every
+ * OpenTelemetry collector and OTLP backend reads. No dependency, no SDK. Export failures are
+ * counted, never thrown: logging must not break the program. (OTLP over gRPC is not supported:
+ * use the collector's HTTP port, 4318 by default.)
+ *
+ * Configure it in code, or from the standard OpenTelemetry variables with `otlpFromEnv`.
+ */
+export type Severity = "DEBUG" | "INFO" | "WARN" | "ERROR";
+export type AttrValue = string | number | boolean | null | undefined;
+export type OtlpProtocol = "http/protobuf" | "http/json";
+export interface OtlpOptions {
+    /** Collector base URL, e.g. `http://127.0.0.1:4318` (`/v1/logs` is added). */
+    endpoint: string;
+    /** `service.name` of the records. */
+    serviceName: string;
+    serviceVersion?: string;
+    /** `http/protobuf` (default) or `http/json`. */
+    protocol?: OtlpProtocol;
+    /** Extra headers, e.g. an API key or `Authorization`, as the backend asks. */
+    headers?: Record<string, string>;
+    /** More resource attributes (e.g. `host.name`). */
+    resource?: Record<string, AttrValue>;
+    /** Send at most this many records per request (default 50); a full buffer is sent at once. */
+    maxBatch?: number;
+    /** Send the buffer every this many ms (default 5000; 0: only on `flush`). */
+    flushMs?: number;
+    /** POST a body; resolves on 2xx (default: fetch). `headers` include the Content-Type. */
+    send?: (url: string, body: string | Uint8Array, headers: Record<string, string>) => Promise<void>;
+    now?: () => number;
+}
+export declare class OtlpLogExporter {
+    private readonly o;
+    private buffer;
+    private inflight;
+    private timer;
+    /** Records sent, and records lost because the collector did not take them. */
+    sent: number;
+    dropped: number;
+    constructor(o: OtlpOptions);
+    log(severity: Severity, body: string, attributes?: Record<string, AttrValue>): void;
+    /** Send what is buffered. Never rejects. */
+    flush(): Promise<void>;
+    private protobuf;
+    /** Stop the timer and send what is left. */
+    close(): Promise<void>;
+}
+/** `k1=v1,k2=v2` (values URL-encoded), the format of `OTEL_EXPORTER_OTLP_HEADERS`. */
+export declare function parseOtlpHeaders(text: string | undefined): Record<string, string>;
+/** `k1=v1,k2=v2` resource attributes, the format of `OTEL_RESOURCE_ATTRIBUTES`. */
+export declare const parseResourceAttributes: typeof parseOtlpHeaders;
+/**
+ * Exporter options from the standard OpenTelemetry variables, or null when export is off (no
+ * endpoint, `OTEL_SDK_DISABLED=true` or `OTEL_LOGS_EXPORTER=none`):
+ * `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` (full URL of /v1/logs) or `OTEL_EXPORTER_OTLP_ENDPOINT`;
+ * `OTEL_EXPORTER_OTLP_[LOGS_]HEADERS`; `OTEL_EXPORTER_OTLP_[LOGS_]PROTOCOL` (`http/protobuf`,
+ * `http/json`); `OTEL_SERVICE_NAME`; `OTEL_RESOURCE_ATTRIBUTES`.
+ */
+export declare function otlpFromEnv(env: Record<string, string | undefined>, defaults: {
+    serviceName: string;
+    serviceVersion?: string;
+}): OtlpOptions | null;
+/** `http/protobuf` or `http/json` from a setting or variable; undefined for anything else. */
+export declare function otlpProtocol(v: string | undefined): OtlpProtocol | undefined;

package/dist/api/redact.d.cts

@@ -0,0 +1,17 @@
+/**
+ * Secrets out of recorded tool calls. A tool call becomes a `tool_call` event of the change feed,
+ * which the engine keeps in its store and the store backup commits and pushes: a webhook's secret
+ * or a token returned by a call must never get there. Removed are the arguments and result keys
+ * the catalogue marks `sensitive`, and, for any tool, the keys that name a secret
+ * ({@link SECRET_KEYS}), at any depth. A text (an error, a result sent as text) loses the values
+ * of those keys written as JSON.
+ */
+/** What a removed value becomes. */
+export declare const REDACTED = "[redacted]";
+/** Keys whose values are secrets, whatever the tool (compared without case, `_` or `-`). */
+export declare const SECRET_KEYS: readonly ["secret", "token", "password", "apikey", "authorization", "httpservertoken", "accesstoken", "refreshtoken", "clientsecret"];
+/** A tool call's arguments and result without their secrets (new objects; the call's own are kept). */
+export declare function redactToolCall(tool: string, args: Record<string, unknown>, value: unknown): {
+    args: Record<string, unknown>;
+    value: unknown;
+};

package/dist/api/redact.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Secrets out of recorded tool calls. A tool call becomes a `tool_call` event of the change feed,
+ * which the engine keeps in its store and the store backup commits and pushes: a webhook's secret
+ * or a token returned by a call must never get there. Removed are the arguments and result keys
+ * the catalogue marks `sensitive`, and, for any tool, the keys that name a secret
+ * ({@link SECRET_KEYS}), at any depth. A text (an error, a result sent as text) loses the values
+ * of those keys written as JSON.
+ */
+/** What a removed value becomes. */
+export declare const REDACTED = "[redacted]";
+/** Keys whose values are secrets, whatever the tool (compared without case, `_` or `-`). */
+export declare const SECRET_KEYS: readonly ["secret", "token", "password", "apikey", "authorization", "httpservertoken", "accesstoken", "refreshtoken", "clientsecret"];
+/** A tool call's arguments and result without their secrets (new objects; the call's own are kept). */
+export declare function redactToolCall(tool: string, args: Record<string, unknown>, value: unknown): {
+    args: Record<string, unknown>;
+    value: unknown;
+};

package/dist/api/requests.d.cts

@@ -0,0 +1,26 @@
+/**
+ * The HTTP request behind each operation of the catalogue (`catalog.ts`): every one is
+ * `POST /datanotes/operations/<name>/`, its JSON body the operation's arguments as they are (the
+ * same names an agent passes to the MCP tool), without the ones left out (null or undefined).
+ */
+import { type Guidance } from "./guidance.cjs";
+type Args = Record<string, unknown>;
+/** Arguments no request can be built from; `message` ends with how to fix them. */
+export declare class OperationInputError extends Error {
+    readonly name = "OperationInputError";
+    constructor(message: string, guidance: Guidance);
+}
+export declare const ROUTE_PREFIX = "/datanotes";
+/** The operations of the catalogue, by name. */
+export declare const CALLABLE_OPERATIONS: ReadonlySet<string>;
+/** The route of an operation, without the prefix: `/operations/<name>/`. */
+export declare function operationRoute(name: string): string;
+export interface OperationRequest {
+    method: "POST";
+    /** Path from the server root. */
+    path: string;
+    body: Args;
+}
+/** The request for an operation and its arguments; throws OperationInputError for an unknown operation. */
+export declare function operationRequest(name: string, args?: Args): OperationRequest;
+export {};

package/dist/api/requests.d.ts

@@ -1,28 +1,26 @@
 /**
- * The HTTP request behind each operation of the catalogue (`catalog.ts`): most are
- * `POST /datanotes/<route>` with a JSON body built from the operation's arguments (renamed where
- * the route names them differently); the note operations read the vault routes.
+ * The HTTP request behind each operation of the catalogue (`catalog.ts`): every one is
+ * `POST /datanotes/operations/<name>/`, its JSON body the operation's arguments as they are (the
+ * same names an agent passes to the MCP tool), without the ones left out (null or undefined).
  */
+import { type Guidance } from "./guidance.js";
 type Args = Record<string, unknown>;
+/** Arguments no request can be built from; `message` ends with how to fix them. */
 export declare class OperationInputError extends Error {
     readonly name = "OperationInputError";
+    constructor(message: string, guidance: Guidance);
 }
 export declare const ROUTE_PREFIX = "/datanotes";
+/** The operations of the catalogue, by name. */
+export declare const CALLABLE_OPERATIONS: ReadonlySet<string>;
+/** The route of an operation, without the prefix: `/operations/<name>/`. */
+export declare function operationRoute(name: string): string;
 export interface OperationRequest {
-    method: "GET" | "POST";
-    /** Path from the server root, query string included. */
+    method: "POST";
+    /** Path from the server root. */
     path: string;
-    body?: unknown;
-    /** Accept header, when the route answers in more than one format. */
-    accept?: string;
+    body: Args;
 }
-/** The request for an operation and its arguments; throws OperationInputError on bad arguments. */
+/** The request for an operation and its arguments; throws OperationInputError for an unknown operation. */
 export declare function operationRequest(name: string, args?: Args): OperationRequest;
-/** Operations this module can build a request for (to check the catalogue against). */
-export declare const CALLABLE_OPERATIONS: Set<string>;
-/** The route an operation calls (without the prefix) and the body fields it fixes (e.g. `op` for DDL), or null. */
-export declare function operationRoute(name: string): {
-    path: string;
-    fixed: Args;
-} | null;
 export {};

package/dist/api/results.d.cts

@@ -0,0 +1,16 @@
+/**
+ * What an operation returned, for its caller: the value of a success, or an agent-readable text
+ * for a refusal (what was refused; nothing was written) or an error, ending with the engine's
+ * `hint` (how to fix it) and `docs` (where to read more) when it sends them.
+ */
+/** Agent-readable summary of conflicts / violations / failures in a refused result. */
+export declare function describeRefusal(data: Record<string, unknown>): string;
+/** Agent-readable summary of a refused batch: the failing operation and the rollback. */
+export declare function describeBatch(data: Record<string, unknown>): string;
+export interface OperationResult {
+    ok: boolean;
+    /** The result (JSON, or the text of a note) or, when `ok` is false, the reason. */
+    value: unknown;
+}
+/** The result of an HTTP answer: `json` when the body was JSON, else its `text`. */
+export declare function resultOf(status: number, json: unknown, text: string): OperationResult;

package/dist/api/results.d.ts

@@ -1,6 +1,7 @@
 /**
  * What an operation returned, for its caller: the value of a success, or an agent-readable text
- * for a refusal (what was refused; nothing was written) or an error.
+ * for a refusal (what was refused; nothing was written) or an error, ending with the engine's
+ * `hint` (how to fix it) and `docs` (where to read more) when it sends them.
  */
 /** Agent-readable summary of conflicts / violations / failures in a refused result. */
 export declare function describeRefusal(data: Record<string, unknown>): string;

package/dist/api/tokens.d.cts

@@ -0,0 +1,7 @@
+/**
+ * A tokenizer-free estimate of how many tokens a text costs a model: words count about one token
+ * per 4 letters, numbers one per 3 digits, every other symbol (JSON punctuation, quotes, …) one.
+ * Close to real tokenizers on JSON and on Italian/English prose (within ~15%); good for telling
+ * which tools and sessions fill the context, not for billing.
+ */
+export declare function estimateTokens(text: string): number;