@avantf/dsh-mem 0.3.0 → 0.4.0

package/lib/engine/mem-contract/tools.d.ts

@@ -0,0 +1,284 @@
+import { z } from 'zod';
+export declare const CONTRADICTION_RESOLUTIONS: readonly ["true_positive", "false_positive"];
+export declare const QUERY_KINDS: readonly ["all", "fact", "doc_chunk"];
+/**
+ * The longest retrieval query the contract accepts, in characters.
+ *
+ * There is no useful query beyond this, and there IS a cost: a CJK query is expanded into one trigram
+ * OR-phrase per character and evaluated by SQLite **synchronously on the host's event loop** (200 000
+ * characters measured at 119 seconds, of which the expansion was 27–52 ms — the rest was `MATCH`). The
+ * cap belongs HERE because every entry point derives from this union: the plugin's tools, the MCP
+ * inputSchema, the CLI's argv validation and the browser payload are all this same object.
+ */
+export declare const MAX_QUERY_CHARS = 2000;
+export type ContradictionResolution = (typeof CONTRADICTION_RESOLUTIONS)[number];
+/** Action unions — one source of truth for tool schemas, MCP inputSchema, CLI args, UI payloads. */
+/**
+ * Cap on the conflicts reported back to a WRITER. A hub fact can be named in many open
+ * pairs, and the write path's payload goes to a model; the full list stays available
+ * through `contradict` / the settings page. Ordered by score, so a cap drops the least
+ * severe first.
+ *
+ * Declared here (not in `core`) because the write path takes the cap from the contract. The
+ * `mem_remember` description deliberately does NOT state the number any more — model-facing
+ * text describes what a call does, never the shape of its result.
+ */
+export declare const MAX_REPORTED_CONFLICTS = 20;
+/**
+ * Vocabulary that describes HOW memory is retained, banned from every model-facing string.
+ *
+ * The model cannot observe those clocks and has no action to take on them; the one thing such
+ * text enables is rewriting a fact to "refresh" it, which defeats the policy it just described.
+ * It binds every tool description and parameter description AND the DSH plugin's system-prompt
+ * section, because the prompt section is prompt text too and a second copy of the list is a copy
+ * that drifts.
+ */
+export declare const RETENTION_VOCABULARY: readonly ["衰减", "消退", "遗忘", "强化", "活跃使用日", "信任度", "永久记忆", "长期有效的信息"];
+/**
+ * Admin actions that return a FACT VIEW. Their payload goes through
+ * {@link modelFacingToolResult}, which drops the retention diagnostics; the other admin
+ * actions (`trust_diagnose`, `vectors_diagnose`, …) are diagnostics the caller asked for and
+ * pass through untouched.
+ */
+export declare const FACT_VIEW_ADMIN_ACTIONS: readonly ["list", "detail"];
+/**
+ * Shape one validated tool result for the MODEL. Applied at the two model-facing boundaries
+ * (`@avantf/dsh-mem`'s tool runner and the MCP dispatch); the Remote gateway that drives the
+ * operator UI keeps the full payload, and a caller that wants the numbers can ask for them
+ * explicitly with `mem_admin`'s diagnostic actions.
+ */
+export declare function modelFacingToolResult(toolKey: string, action: unknown, value: unknown): unknown;
+export declare const REMEMBER_ACTIONS: readonly ["add", "update", "remove", "helpful", "unhelpful"];
+export declare const RememberUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    action: z.ZodLiteral<"add">;
+    content: z.ZodString;
+    category: z.ZodOptional<z.ZodString>;
+    ttl_days: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"update">;
+    fact_id: z.ZodNumber;
+    content: z.ZodString;
+    category: z.ZodOptional<z.ZodString>;
+    ttl_days: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"remove">;
+    fact_id: z.ZodNumber;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"helpful">;
+    fact_id: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"unhelpful">;
+    fact_id: z.ZodNumber;
+}, z.core.$strip>], "action">;
+export type RememberRequest = z.infer<typeof RememberUnion>;
+export declare const RECALL_ACTIONS: readonly ["search", "ask", "chain", "probe", "reason", "related", "contradict"];
+export declare const RecallUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    action: z.ZodLiteral<"search">;
+    query: z.ZodString;
+    category: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    floors: z.ZodOptional<z.ZodEnum<{
+        strict: "strict";
+        loose: "loose";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"ask">;
+    subj: z.ZodOptional<z.ZodString>;
+    pred: z.ZodOptional<z.ZodString>;
+    obj: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"chain">;
+    subj: z.ZodString;
+    pred: z.ZodOptional<z.ZodString>;
+    second_pred: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"probe">;
+    entity: z.ZodString;
+    category: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"reason">;
+    entities: z.ZodArray<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"related">;
+    entity: z.ZodString;
+    category: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"contradict">;
+    category: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "action">;
+export type RecallRequest = z.infer<typeof RecallUnion>;
+export declare const ADMIN_ACTIONS: readonly ["stats", "list", "detail", "archive", "restore", "pin", "unpin", "trust_diagnose", "vectors_diagnose", "vectors_fix", "contradict_check", "contradict_resolve", "maintenance"];
+export declare const AdminUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    action: z.ZodLiteral<"stats">;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"list">;
+    category: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        archived: "archived";
+    }>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"detail">;
+    fact_id: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"archive">;
+    fact_id: z.ZodNumber;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"restore">;
+    fact_id: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"pin">;
+    fact_id: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"unpin">;
+    fact_id: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"trust_diagnose">;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"vectors_diagnose">;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"vectors_fix">;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"contradict_check">;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"contradict_resolve">;
+    contradiction_id: z.ZodNumber;
+    resolution: z.ZodEnum<{
+        true_positive: "true_positive";
+        false_positive: "false_positive";
+    }>;
+    loser_fact_id: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"maintenance">;
+}, z.core.$strip>], "action">;
+export type AdminRequest = z.infer<typeof AdminUnion>;
+/** The `source` a write gets when it omits one; a document's identity is `(domain, source, title)`. */
+export declare const DEFAULT_KB_SOURCE = "default";
+export declare const KbUnion: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    action: z.ZodLiteral<"ingest">;
+    text: z.ZodOptional<z.ZodString>;
+    source_uri: z.ZodOptional<z.ZodString>;
+    domain: z.ZodString;
+    source: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    title: z.ZodOptional<z.ZodString>;
+    overwrite: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"import">;
+    paths: z.ZodArray<z.ZodString>;
+    domain: z.ZodString;
+    source: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    overwrite: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"list">;
+    domain: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"detail">;
+    doc_id: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"remove">;
+    doc_id: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"reindex">;
+    domain: z.ZodOptional<z.ZodString>;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    action: z.ZodLiteral<"sync">;
+    doc_id: z.ZodOptional<z.ZodNumber>;
+    adopt: z.ZodOptional<z.ZodBoolean>;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>], "action">;
+export type KbRequest = z.infer<typeof KbUnion>;
+export declare const QueryUnion: z.ZodObject<{
+    query: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        fact: "fact";
+        doc_chunk: "doc_chunk";
+        all: "all";
+    }>>;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    domain: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    floors: z.ZodOptional<z.ZodEnum<{
+        strict: "strict";
+        loose: "loose";
+    }>>;
+}, z.core.$strip>;
+export type QueryRequest = z.infer<typeof QueryUnion>;
+/** Transport-agnostic tool spec: name / key / description / zod input. */
+export interface ToolSpec {
+    key: string;
+    name: string;
+    description: string;
+    input: z.ZodType;
+}
+export declare const REMEMBER_TOOL: ToolSpec;
+export declare const RECALL_TOOL: ToolSpec;
+export declare const ADMIN_TOOL: ToolSpec;
+export declare const KB_TOOL: ToolSpec;
+export declare const QUERY_TOOL: ToolSpec;
+/** One new document, or a batch import — never an update (see the tool description). */
+export declare const KB_ADD_TOOL: ToolSpec;
+/**
+ * The parsed `kb_add` input, no `overwrite`: the add-only MODE is a property of the runtime face
+ * (`rt.kbAdd`), not a field the model can set. Spelled out (rather than `z.infer` of
+ * `KB_ADD_TOOL.input`, which is widened to `z.ZodType` by `ToolSpec`) so the runtime method and the
+ * plugin handler agree on the request. `source` is present because the contract defaults it.
+ */
+export interface KbAddRequest {
+    domain: string;
+    source: string;
+    title?: string;
+    text?: string;
+    source_uri?: string;
+    paths?: string[];
+}
+/** The corpus listing, with the managed path — the entry point for editing a document. */
+export declare const KB_LIST_TOOL: ToolSpec;
+export declare const KB_REMOVE_TOOL: ToolSpec;
+export declare const KB_REINDEX_TOOL: ToolSpec;
+export declare const TOOL_SPECS: ToolSpec[];
+/**
+ * Compose the top-level (merged) description for a union field.
+ *
+ * Descriptions are authored per action ("action=update 时必填"), so taking the
+ * first branch's text verbatim told a model that `fact_id` only matters for
+ * `update` although `remove/helpful/unhelpful` require it too. The action-clause
+ * is stripped and replaced by the derived set of actions that make the field
+ * required.
+ *
+ * Both model-facing surfaces call this: `toolInputJsonSchema` (MCP `inputSchema`) and
+ * `@avantf/dsh-mem`'s `flattenToolSpec` (DSH tool parameters). They each walk the union and must
+ * agree field for field — deriving the sentence in ONE place is what makes that so.
+ */
+export declare function mergedFieldDescription(base: string | undefined, requiredIn: string[]): string | undefined;
+/**
+ * Derive a full JSON Schema (draft-07) for a tool's input — used as the MCP
+ * `inputSchema`.
+ *
+ * A discriminated union emits `oneOf` with ONE schema per action: each branch
+ * carries its own `required` list, so `{"action":"search"}` (no `query`) is
+ * rejected exactly like the server's own contract validation rejects it. The
+ * merged `properties` map is kept alongside for MCP clients that ignore `oneOf`,
+ * with every field's description stating which actions require it. Field-level
+ * value constraints (`minimum`/`maximum`/`minLength`/`minItems`/`default`) are
+ * carried over from zod. A plain object marks its own required fields.
+ */
+export declare function toolInputJsonSchema(spec: ToolSpec): Record<string, unknown>;