@avantf/dsh-mem 0.1.0

package/lib/types/provision.js

@@ -0,0 +1,233 @@
+/**
+ * This plugin's compatibility spec, and the wiring that runs it.
+ *
+ * The rules, the probes, the report and the post-registration check all live in
+ * `@avantf/dsh-compat` (shared with the rest of the family). What stays here is only what is true of
+ * THIS plugin: the services and methods it calls, the dsh packages that identify the host, the wire
+ * schema names and tool names that must be visible afterwards, the events it listens to, and the
+ * Chinese report a user reads. See `DESIGN.md` §12.1.
+ *
+ * **Who obtains the base.** Not this module. The family framework `@avantf/dsh-envinit` provisions
+ * `@avantf/dsh-compat` as the `mem:compat` manifest item and hands back the directory it landed in
+ * (`src/envinit.ts`); this module is given the loaded module and derives everything from it. That is
+ * the whole point of the framework: acquisition (resolve → managed copy → verified download →
+ * atomic publish) is one shared mechanism, and the plugin only declares what it needs.
+ *
+ * The base therefore has NO import path of its own here — not even a dynamic one. A static `import`
+ * would throw `ERR_MODULE_NOT_FOUND` while the artifact was being evaluated (the base is not a
+ * runtime dependency of the published plugin any more), and a bare dynamic `import()` would bypass
+ * the framework's managed copy. The plugin loads the module the framework resolved, by file URL.
+ *
+ * The plugin computes the gate's verdict here and hands it to the engine as plain data
+ * (`{ load, status, reason }`), so the inlined engine bundle never imports the base either.
+ *
+ * @module @avantf/dsh-mem/provision
+ */
+import { readFile } from 'node:fs/promises';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { hostContribution } from './remote.js';
+/** The base package id, named here too so the item declaration and the spec need no import. */
+export const COMPAT_PACKAGE = '@avantf/dsh-compat';
+/**
+ * Fallback range for `@avantf/dsh-compat`, used only when `package.json` has lost the dependency
+ * entry. The manifest is the single source of truth (`compatRange()`); `scripts/pack-plugin.mjs`
+ * pins this constant to it so the two cannot drift.
+ */
+export const COMPAT_RANGE = '^0.1.0';
+/**
+ * The services this plugin calls, with the methods it calls on them.
+ *
+ * `required` is this plugin's REFUSAL policy, not cordis's `inject`: `typert` is injected (the real
+ * wire face is registered at mount) yet a composition without the registry must still mount the
+ * memory tools, so its absence is a note rather than a refusal. Optional services are read with
+ * `ctx.get()`.
+ *
+ * `tools` lists only `register` because that is the one method this plugin calls; the post-load
+ * check reads `get`, but guards it and degrades to "not verified", so demanding it here would refuse
+ * a host this plugin can still drive.
+ */
+export const SERVICE_CONTRACTS = [
+    { name: 'tools', required: true, methods: ['register'] },
+    { name: 'systemPrompt', required: true, methods: ['section', 'context'] },
+    { name: 'typert', required: false, methods: ['register', 'get', 'list', 'listPackages', 'toJSONSchema'] },
+    // Read with `ctx.get()` only by the refusal megaphone; a host without it must not become a refusal.
+    { name: 'commands', required: false, methods: ['register'] },
+];
+/**
+ * The events this plugin listens to — reported, never verified.
+ *
+ * A listener for a name the host no longer emits registers happily and then never runs: the house
+ * hints would simply stop appearing. Nothing inside a plugin can prove the host still emits a name,
+ * so the list is a known limit the gate records and the running dsh version is the operator's signal.
+ */
+export const REQUIRED_EVENTS = ['agent/inbox/inserted', 'tools/result'];
+/** Packages released in lockstep with dsh; their version says which dsh is running. */
+export const VERSION_PACKAGES = ['@deepseek-ai/dsh-tools', '@deepseek-ai/dsh-typert-protocol'];
+/** This plugin's npm package id, which names the probe and verification keys. */
+const PACKAGE_ID = String(hostContribution.package ?? '@avantf/dsh-mem');
+/** Best-effort one-line reason for a caught value. */
+export function reasonOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Emit a warning without ever letting the logger turn it into a crash. */
+export function warn(log, message) {
+    try {
+        log?.warn(message);
+    }
+    catch {
+        // A logger that throws is not evidence of anything.
+    }
+}
+/**
+ * The range of `@avantf/dsh-compat` this build is written against.
+ *
+ * Read from THIS plugin's manifest, which is the single source of truth — the framework does not
+ * pick it, and a hardcoded constant would silently keep provisioning an old range after the family
+ * publishes a new one. The constant is only a fallback for a manifest that lost the entry.
+ *
+ * It lives in `devDependencies`, deliberately. Nothing imports the base: the framework fetches it
+ * into its own managed home and this plugin loads it from there, so a RUNTIME dependency would
+ * install a second copy on every consumer that no code path ever loads. `devDependencies` still
+ * ships in the packed manifest (pnpm keeps it, rewriting `catalog:` like any other field), so the
+ * range travels with the artifact; it just is not installed.
+ */
+export async function compatRange(manifestUrl = new URL('../package.json', import.meta.url)) {
+    try {
+        const raw = JSON.parse(await readFile(manifestUrl, 'utf8'));
+        const declared = raw.devDependencies?.[COMPAT_PACKAGE] ?? raw.dependencies?.[COMPAT_PACKAGE];
+        if (typeof declared === 'string' && declared.trim() !== '')
+            return declared;
+    }
+    catch {
+        // Fall through to the pinned fallback.
+    }
+    return COMPAT_RANGE;
+}
+/**
+ * Build the plugin-specific half of the gate from a loaded base.
+ *
+ * Called ONCE per process (the loaded runtime is cached by `src/envinit.ts`), which is what makes the
+ * lazy construction equivalent to the module-level constants it replaces — `readBuildVersions` still
+ * reads the baked `lib/dsh-build.json` beside the built entry, falling back per package to the peer
+ * range floor when it is absent (a dev tree, a test run).
+ */
+export function runtimeFromCompat(module) {
+    const peerFloors = module.readDeclaredVersions(new URL('../package.json', import.meta.url), VERSION_PACKAGES);
+    const buildVersionsUrl = new URL(`./${module.BUILD_VERSIONS_FILE}`, import.meta.url);
+    const schemaNames = module.schemaNamesFrom(hostContribution);
+    const spec = {
+        packageId: PACKAGE_ID,
+        services: SERVICE_CONTRACTS,
+        // The version THIS BUILD was compiled against: the exact one baked at build time, falling back
+        // per package to the peer range floor. A range floor alone cannot say what the build linked.
+        declared: module.readBuildVersions(buildVersionsUrl, VERSION_PACKAGES, peerFloors),
+        // Resolved from THIS package's links: the packages that identify the host are its peers. Note
+        // this is NOT the host's identity — see the base package's README «已知边界».
+        runtime: module.readRuntimeVersions(VERSION_PACKAGES, import.meta.url),
+        // The base package knows no dsh type, so the probe's declaration comes from here — the probe must
+        // mirror the declaration path the REAL tools use.
+        probeTool: module.toolProbeDeclaration(defineTool),
+        // The wire probe IS the real host face, codecs and all. A probe that merely RESEMBLED it once
+        // reported `ok` on a 0.1.6 host whose codec contract had moved, and the real registration then
+        // threw halfway through `apply` — the half-mounted outcome this gate exists to prevent. Same
+        // object, same host, so "the probe passed" now means "this registration passes".
+        probeTypert: () => hostContribution,
+        schemaNames,
+        events: REQUIRED_EVENTS,
+    };
+    return { module, prefix: module.COMPAT_PREFIX, spec, schemaNames };
+}
+/** The "the check itself failed" outcome: keep loading, say why. */
+function cannotDetermine(error, log, prefix) {
+    const message = `${prefix} WARNING — the compatibility check itself failed (${reasonOf(error)}); loading anyway`;
+    warn(log, message);
+    return {
+        verdict: {
+            load: true,
+            skipped: true,
+            status: 'probe-skipped',
+            problems: [],
+            warnings: [message],
+            notes: ['the check itself failed'],
+            lines: [{ level: 'warn', message }],
+            reason: '',
+        },
+    };
+}
+/**
+ * Run the gate. Call this FIRST in `apply()`: on a refusal nothing has been registered yet, so
+ * "do not load" costs nothing to unwind. Never throws — not even with a throwing logger, because
+ * "cannot tell" is not "incompatible".
+ * @param ctx - the plugin's context.
+ * @param log - the plugin's logger.
+ * @param compat - the loaded gate runtime (see `src/envinit.ts`).
+ * @param spec - what to judge (defaults to the runtime's spec; injectable so the version path is
+ *   testable without a second host).
+ * @returns the verdict `apply` branches on.
+ */
+export function provision(ctx, log, compat, spec = compat.spec) {
+    let evidence;
+    try {
+        evidence = compat.module.gatherEvidence(ctx, spec);
+    }
+    catch (error) {
+        return cannotDetermine(error, log, compat.prefix);
+    }
+    let verdict;
+    try {
+        verdict = compat.module.verdictOf(evidence);
+    }
+    catch (error) {
+        return cannotDetermine(error, log, compat.prefix);
+    }
+    for (const line of verdict.lines) {
+        try {
+            log[line.level](line.message);
+        }
+        catch {
+            // A logger that throws must not turn a verdict into a crash.
+        }
+    }
+    return { verdict };
+}
+/**
+ * Keep one `/mem` command that reports a refusal.
+ *
+ * The plugin provides nothing else when it refuses, and the alternative is a user watching a tab
+ * that never loads with no way to ask why.
+ * @param ctx - the plugin's context.
+ * @param verdict - the refusal to report.
+ * @param log - the plugin's logger.
+ * @param compat - the loaded gate runtime.
+ */
+export function registerCompatMegaphone(ctx, verdict, log, compat) {
+    compat.module.registerMegaphone({
+        ctx,
+        log,
+        command: { name: 'mem', description: '报告记忆插件为何未加载（兼容性检查未通过）' },
+        text: compat.module.compatReport(verdict, {
+            heading: '记忆插件未加载：与当前 dsh 的兼容性检查未通过，插件已拒绝加载（不注册服务、工具、prompt 段与真实 typert face）。',
+            warningsLabel: '风险提示：',
+            warnings: verdict.warnings,
+            fix: '修复：在本仓库重建（`pnpm build:dsh`），或把 `@deepseek-ai/dsh` 换回本构建声明的版本。',
+        }),
+    });
+}
+/**
+ * The second phase: every real registration must be visible afterwards.
+ *
+ * Warn-only by design — the plugin is mounted by now, so there is no clean "do not load" left to
+ * take, and a silently dropped schema or tool is exactly what nothing else would report.
+ * @param input - the live context, the real tool names, the logger, and the loaded gate runtime.
+ * @returns the registrations that did not show up (empty on success).
+ */
+export function verifyRegisteredFaces(input) {
+    return input.compat.module.verifyRegisteredFaces({
+        ctx: input.ctx,
+        log: input.log,
+        packageId: input.compat.spec.packageId,
+        schemaNames: input.compat.schemaNames,
+        toolNames: input.toolNames,
+    });
+}
+//# sourceMappingURL=provision.js.map

package/lib/types/provision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provision.js","sourceRoot":"","sources":["../../src/provision.ts"],"names":[],"mappings":"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"}

package/lib/types/remote.d.ts

@@ -0,0 +1,17 @@
+import type { InvocationDescriptor, TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol';
+import type { TypertContribution } from '@deepseek-ai/dsh-typert-registry/types';
+export declare const descriptors: readonly InvocationDescriptor[];
+/** Client face: mounted by the client half through `ctx.remote.$mount()`. */
+export declare const clientContribution: TypertRemoteContribution;
+/**
+ * Host face: registered by the host half through `ctx.typert.register()`.
+ *
+ * The schema assertions name `TypertSchema['schema']` — the FIELD they are assigned to — rather
+ * than this package's own `z.ZodType`. The two are different zod copies: the plugin pins
+ * zod 4.4.3, the harness bundles 4.6.2, and `ZodType` gained members between them, so a cast to
+ * the local `z.ZodType` could never be assignable and the annotation said nothing. Through
+ * `TypertSchema['schema']` the assertion is at least against the type the field actually
+ * requires, and a future zod alignment (which would make the cast unnecessary) shows up here.
+ */
+export declare const hostContribution: TypertContribution;
+//# sourceMappingURL=remote.d.ts.map

package/lib/types/remote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../src/remote.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EACV,oBAAoB,EAGpB,wBAAwB,EACzB,MAAM,kCAAkC,CAAA;AACzC,OAAO,KAAK,EAAE,kBAAkB,EAAgB,MAAM,wCAAwC,CAAA;AAuE9F,eAAO,MAAM,WAAW,EAAE,SAAS,oBAAoB,EAqGtD,CAAA;AAED,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,EAAE,wBAGhC,CAAA;AAqBD;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,EAAE,kBA0C9B,CAAA"}

package/lib/types/remote.js

@@ -0,0 +1,233 @@
+/**
+ * Hand-written Typert wire faces for the `avantfMem` Remote namespace.
+ *
+ * DSH packages normally ship generator-produced faces (`typert.host.js` /
+ * `typert.remote-client.js`), but the Typert generator runs only inside the
+ * harness workspace. Both faces are therefore hand-written here, following the
+ * generator's exact conventions: zod v4 strict codecs, one `args` object
+ * parameter per method, `<pkg>#<namespace>/<method>` invocation ids, and a host
+ * contribution registered through `ctx.typert.register()` (the documented
+ * path for hand-written wire schemas, see `@deepseek-ai/dsh-typert-loader`).
+ *
+ * The five methods mirror the five agent tools (remember/recall/admin/kb/query)
+ * so the 记忆/知识 tabs can do full CRUD + KB management. Args carry the merged
+ * optional field set of the contract's action unions; the HOST re-validates
+ * every payload with the contract zod schema before dispatch, so the wire face
+ * only needs to guarantee JSON shape sanity. Five methods have no tool behind
+ * them — `openDoc` (the 知识 tab's 「编辑」/「打开目录」 buttons), `classifySource`
+ * and `browseDir` (its source input and 选择 picker), `kbDomains` (its domain
+ * dropdown) and `kbAddDomain` (its 「+」 next to that dropdown).
+ *
+ * The host half consumes `hostContribution`; the client half mounts
+ * `clientContribution` via `ctx.remote.$mount()`.
+ */
+import { z } from 'zod';
+const PACKAGE = '@avantf/dsh-mem';
+const NAMESPACE = 'avantfMem';
+const endpointId = (method) => `${PACKAGE}#${NAMESPACE}/${method}`;
+const fieldSymbol = (method, field) => `${PACKAGE}#${NAMESPACE}/${method}:${field}`;
+const resultSymbol = (method) => fieldSymbol(method, 'result');
+/**
+ * zod v4 strict codec envelope the Typert boundary validates with.
+ *
+ * Carries BOTH members on purpose: the host's validator moved from `codec.schema.parse` (0.1.5) to
+ * `codec.create()` (0.1.6), and each generation checks only its own. One shape therefore serves
+ * either host — the same "one shape satisfies two revisions" trick the job plugin's `strict()` uses.
+ */
+function strict(schema, typeSymbol) {
+    return { mode: 'strict', typeSymbol, schema, create: () => schema };
+}
+/** One JSON wire parameter; optional parameters accept a missing wire field. */
+function parameter(method, name, schema, acceptsUndefined) {
+    return {
+        name,
+        wire: name,
+        source: 'json',
+        codec: strict(schema, fieldSymbol(method, name)),
+        ...(acceptsUndefined === undefined ? {} : { acceptsUndefined }),
+    };
+}
+const text = z.string();
+// Optional wire fields are written as `X.optional()`, NOT `z.union([z.undefined(), X])`. The two
+// accept the same payloads, but the union is invisible to the HOST's JSON-Schema projector:
+// `z.toJSONSchema()` throws "Undefined cannot be represented in JSON Schema" over it, and the
+// startup compatibility gate projects the REAL wire face through that host method — so the union
+// form made a healthy host read as an incompatible one. `.optional()` projects to a non-required
+// property, which is exactly what these fields are.
+const count = z.number().int().optional();
+const optionalText = z.string().optional();
+const bool = z.boolean().optional();
+const textArray = z.array(z.string()).optional();
+/** One direct Remote method carrying a single `args` object parameter. */
+function direct(method, args) {
+    return {
+        id: endpointId(method),
+        service: NAMESPACE,
+        namespace: NAMESPACE,
+        method,
+        invocation: { kind: 'direct' },
+        parameters: [parameter(method, 'args', args)],
+        // The runtime's result shapes vary by store backend and evolve fast;
+        // keep the boundary tolerant (`z.any()` never rejects a host reply).
+        result: strict(z.any(), resultSymbol(method)),
+    };
+}
+export const descriptors = [
+    // remember: add/update/remove/helpful/unhelpful (action defaults to 'add' host-side)
+    direct('remember', z.object({
+        action: optionalText.optional(),
+        content: optionalText.optional(),
+        fact_id: count.optional(),
+        category: optionalText.optional(),
+        ttl_days: count.optional(),
+        reason: optionalText.optional(),
+    })),
+    // recall: search/ask/chain/probe/reason/related/contradict (defaults to 'search')
+    direct('recall', z.object({
+        action: optionalText.optional(),
+        query: optionalText.optional(),
+        entity: optionalText.optional(),
+        entities: textArray.optional(),
+        subj: optionalText.optional(),
+        pred: optionalText.optional(),
+        obj: optionalText.optional(),
+        second_pred: optionalText.optional(),
+        category: optionalText.optional(),
+        limit: count.optional(),
+        max_tokens: count.optional(),
+    })),
+    // admin: stats/list/detail/archive/restore/vectors_*/contradict_*/maintenance (defaults to 'list')
+    //
+    // Every field the client sends must be declared here: a strict codec PARSES the args before they
+    // go out (harness `api/gateway` `parseInput`), and a zod object drops unknown keys — a missing
+    // field is not an error, it is a silently emptied request that then fails contract validation
+    // host-side. That is exactly how the three 矛盾裁决 buttons shipped broken: `contradiction_id`,
+    // `resolution` and `loser_fact_id` were never declared, so only `{action}` reached the host.
+    // `test/remote_wire.spec.ts` pins the invariant that actually generalises — declared ⊇ the
+    // contract union's fields — because "declared ⊇ what the client source sends" has blind spots a
+    // wrapper function (`kbCall(label, args)`) or a conditional spread hides.
+    direct('admin', z.object({
+        action: optionalText.optional(),
+        fact_id: count.optional(),
+        category: optionalText.optional(),
+        status: optionalText.optional(),
+        limit: count.optional(),
+        offset: count.optional(),
+        reason: optionalText.optional(),
+        dry_run: bool.optional(),
+        contradiction_id: count.optional(),
+        resolution: optionalText.optional(),
+        loser_fact_id: count.optional(),
+    })),
+    // kb: ingest/import/list/detail/remove/reindex/sync (action REQUIRED — no safe default)
+    //
+    // `overwrite` is a field of THIS face only: the UI's 入库 form sends it after the user confirms
+    // the collision dialog, and the CLI after `--overwrite`. It is deliberately NOT a field of
+    // `KB_ADD_TOOL.input`, so the add-only mode cannot leak into the model's view.
+    //
+    // `adopt` is the 知识 tab's 「认领文件」 button: sync one document whose frontmatter was destroyed
+    // by a whole-file overwrite, accepting the store's guess about which row it belongs to. It was
+    // missing from this face, so the button sent `{action:'sync', doc_id}` and reported
+    // 「认领完成：0 篇」 — the fourth field to ship silently undeclared.
+    direct('kb', z.object({
+        action: optionalText.optional(),
+        text: optionalText.optional(),
+        source_uri: optionalText.optional(),
+        domain: optionalText.optional(),
+        source: optionalText.optional(),
+        title: optionalText.optional(),
+        paths: textArray.optional(),
+        doc_id: count.optional(),
+        limit: count.optional(),
+        offset: count.optional(),
+        dry_run: bool.optional(),
+        overwrite: bool.optional(),
+        adopt: bool.optional(),
+    })),
+    // query: cross-store retrieval
+    direct('query', z.object({
+        query: text,
+        kind: optionalText.optional(),
+        domain: optionalText.optional(),
+        source: optionalText.optional(),
+        limit: count.optional(),
+        max_tokens: count.optional(),
+    })),
+    // classifySource / browseDir: UI-only. The 知识 tab has ONE source input, so the host has to say
+    // what a string IS (URL / file / directory / missing / pasted text) and let the user browse for a
+    // path — a browser can check `^https?://` and nothing else, and only the host may stat a path.
+    direct('classifySource', z.object({ text: optionalText.optional() })),
+    direct('browseDir', z.object({ path: optionalText.optional() })),
+    // kbDomains: UI-only. The 知识 tab's domain control is a picker, and the two halves of its option
+    // list — the configured `knowledge.domains` allowlist and the domains already in the library —
+    // live host-side, so the client asks for the union instead of guessing it.
+    direct('kbDomains', z.object({})),
+    // kbAddDomain: UI-only (no agent tool mirrors it, deliberately — an autonomous writer is where
+    // domain sprawl would come from). Appends the name to the store config's `domains` allowlist and
+    // to the live set, and answers with the new catalog so the picker can select it.
+    direct('kbAddDomain', z.object({ domain: text })),
+    // openDoc: UI-only (no agent tool mirrors it) — hand one managed document file, or the
+    // directory holding it, to the user's editor. The host resolves the path from `doc_id`, so the
+    // client never supplies a path the host would have to trust.
+    direct('openDoc', z.object({
+        doc_id: count,
+        target: optionalText.optional(),
+    })),
+];
+/** Client face: mounted by the client half through `ctx.remote.$mount()`. */
+export const clientContribution = {
+    package: PACKAGE,
+    descriptors,
+};
+/** Declare one registered wire schema: the factory 0.1.6 calls, plus the schema 0.1.5 reads. */
+function declared(name, schema) {
+    return { name, schema, create: () => schema };
+}
+/**
+ * Host face: registered by the host half through `ctx.typert.register()`.
+ *
+ * The schema assertions name `TypertSchema['schema']` — the FIELD they are assigned to — rather
+ * than this package's own `z.ZodType`. The two are different zod copies: the plugin pins
+ * zod 4.4.3, the harness bundles 4.6.2, and `ZodType` gained members between them, so a cast to
+ * the local `z.ZodType` could never be assignable and the annotation said nothing. Through
+ * `TypertSchema['schema']` the assertion is at least against the type the field actually
+ * requires, and a future zod alignment (which would make the cast unnecessary) shows up here.
+ */
+export const hostContribution = {
+    package: PACKAGE,
+    face: 'host',
+    schemas: descriptors.flatMap((descriptor) => [
+        ...descriptor.parameters.map(parameter => declared(`${descriptor.method}${parameter.name}`, parameter.codec.schema)),
+        declared(`${descriptor.method}Result`, descriptor.result.schema),
+    ]),
+    model: {
+        services: [
+            {
+                key: 'avantfMemory',
+                exportName: 'avantfMemory',
+                description: 'avantf-mem runtime facade: memory store, knowledge store, ingestion, lifecycle, cross-retrieval router',
+                summary: 'avantf-mem engine runtime',
+                tags: [],
+                members: [],
+                types: [],
+            },
+            {
+                key: NAMESPACE,
+                exportName: NAMESPACE,
+                description: 'Client Remote namespace: remember / recall / admin / kb / query over the avantf-mem stores',
+                summary: 'avantf-mem client remote',
+                tags: [],
+                members: descriptors.map(descriptor => ({
+                    kind: 'method',
+                    name: descriptor.method,
+                    signature: '(args: object) => Promise<unknown>',
+                })),
+                types: [],
+            },
+        ],
+        events: [],
+        objects: [],
+    },
+    invocations: descriptors,
+};
+//# sourceMappingURL=remote.js.map

package/lib/types/remote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.js","sourceRoot":"","sources":["../../src/remote.ts"],"names":[],"mappings":"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"}

package/lib/types/tool_schema.d.ts

@@ -0,0 +1,40 @@
+import { type ToolSpec } from '@avantf/mem-contract';
+export type ParamSpec = {
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+    description?: string;
+    required?: true;
+    enum?: readonly string[];
+    items?: ParamSpec;
+};
+/** The slice of zod v4's `def` this derivation reads (structure only, never type tags). */
+export interface ZodDef {
+    type?: string;
+    shape?: Record<string, unknown>;
+    options?: unknown[];
+    /** A literal's / enum's values; v4 keeps them in an array. */
+    values?: unknown;
+}
+export declare function zodDef(schema: unknown): ZodDef;
+/** Nearest `description` on a schema (wrappers included — the converter already unwrapped them). */
+export declare function schemaDescription(schema: unknown): string | undefined;
+export declare function zodToSpec(schema: unknown): ParamSpec;
+/** Materialize one zod object branch's fields, or undefined for a non-object. */
+export declare function branchShape(schema: unknown): Record<string, unknown> | undefined;
+/**
+ * Flatten a tool input schema into DSH's implicit parameter map. A discriminated
+ * union contributes one required `action` enum plus the merged field set (fields
+ * stay optional at the schema level because requiredness differs per action; the
+ * per-action requirement is stated in each field's description and enforced by
+ * `spec.input` validation before dispatch). A plain object marks its own required
+ * fields directly.
+ *
+ * The merged descriptions come from the contract's {@link mergedFieldDescription}, the SAME
+ * function `toolInputJsonSchema` uses for the MCP surface. Taking each field's first branch
+ * verbatim is what made the two model-facing surfaces disagree: `mem_admin`'s `fact_id` said
+ * "action=detail 时必填" on this surface while the MCP schema said
+ * "【detail/archive/restore/pin/unpin 必填】" — so a model calling `archive` without it had to
+ * learn the requirement from a `violations` retry. Both surfaces now read the same merged
+ * descriptions, which is what keeps them in agreement field for field.
+ */
+export declare function flattenToolSpec(spec: ToolSpec): Record<string, ParamSpec>;
+//# sourceMappingURL=tool_schema.d.ts.map

package/lib/types/tool_schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool_schema.d.ts","sourceRoot":"","sources":["../../src/tool_schema.ts"],"names":[],"mappings":"AAgBA,OAAO,EAA0B,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAE5E,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAA;IACtE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,IAAI,CAAA;IACf,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB,CAAA;AAED,2FAA2F;AAC3F,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,OAAO,CAAC,EAAE,OAAO,EAAE,CAAA;IACnB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,wBAAgB,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAE9C;AAkBD,oGAAoG;AACpG,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGrE;AAqBD,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAEpD;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEhF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAiDzE"}