melchizedek-agents 0.18.0 → 0.19.0

package/dist/lib/tools/wikiTools.d.ts

@@ -39,16 +39,16 @@
  */
 import { z } from 'zod';
 import { type ToolContract } from './toolContract.ts';
-export declare const wikiMapContract: ToolContract<z.ZodObject<{}, z.core.$strip>>;
-export declare const wikiReadContract: ToolContract<z.ZodObject<{
+export declare const wikiMapContract: import("./toolContract.ts").DefinedTool<z.ZodObject<{}, z.core.$strip>, string>;
+export declare const wikiReadContract: import("./toolContract.ts").DefinedTool<z.ZodObject<{
     path: z.ZodString;
     section: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
-export declare const wikiSearchContract: ToolContract<z.ZodObject<{
+}, z.core.$strip>, string>;
+export declare const wikiSearchContract: import("./toolContract.ts").DefinedTool<z.ZodObject<{
     query: z.ZodString;
     limit: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>>;
-export declare const wikiLinksContract: ToolContract<z.ZodObject<{
+}, z.core.$strip>, string>;
+export declare const wikiLinksContract: import("./toolContract.ts").DefinedTool<z.ZodObject<{
     path: z.ZodString;
     depth: z.ZodDefault<z.ZodNumber>;
     direction: z.ZodDefault<z.ZodEnum<{
@@ -56,12 +56,12 @@ export declare const wikiLinksContract: ToolContract<z.ZodObject<{
         in: "in";
         out: "out";
     }>>;
-}, z.core.$strip>>;
-export declare const wikiDiveContract: ToolContract<z.ZodObject<{
+}, z.core.$strip>, string>;
+export declare const wikiDiveContract: import("./toolContract.ts").DefinedTool<z.ZodObject<{
     task: z.ZodString;
     budget_words: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>>;
-export declare const wikiGraphContract: ToolContract<z.ZodObject<{
+}, z.core.$strip>, string>;
+export declare const wikiGraphContract: import("./toolContract.ts").DefinedTool<z.ZodObject<{
     node: z.ZodOptional<z.ZodString>;
     find: z.ZodOptional<z.ZodString>;
     kind: z.ZodOptional<z.ZodString>;
@@ -74,29 +74,29 @@ export declare const wikiGraphContract: ToolContract<z.ZodObject<{
         out: "out";
     }>>;
     limit: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>>;
-export declare const wikiRelateContract: ToolContract<z.ZodObject<{
+}, z.core.$strip>, string>;
+export declare const wikiRelateContract: import("./toolContract.ts").DefinedTool<z.ZodObject<{
     from: z.ZodString;
     to: z.ZodString;
     relation: z.ZodString;
     evidence: z.ZodString;
     actor: z.ZodString;
     note: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
-export declare const wikiSaveContract: ToolContract<z.ZodObject<{
+}, z.core.$strip>, string>;
+export declare const wikiSaveContract: import("./toolContract.ts").DefinedTool<z.ZodObject<{
     path: z.ZodString;
     content: z.ZodString;
     actor: z.ZodString;
     summary: z.ZodString;
-}, z.core.$strip>>;
-export declare const wikiQueryContract: ToolContract<z.ZodObject<{
+}, z.core.$strip>, string>;
+export declare const wikiQueryContract: import("./toolContract.ts").DefinedTool<z.ZodObject<{
     question: z.ZodString;
     model: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
-export declare const wikiGardenContract: ToolContract<z.ZodObject<{
+}, z.core.$strip>, string>;
+export declare const wikiGardenContract: import("./toolContract.ts").DefinedTool<z.ZodObject<{
     instruction: z.ZodString;
     model: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
+}, z.core.$strip>, string>;
 /** Everything an MCP client may be offered (see the wiki MCP server script). */
 export declare const WIKI_TOOL_CONTRACTS: readonly ToolContract<any>[];
 /**

package/dist/lib/tools/wikiTools.js

@@ -43,12 +43,13 @@ import { runWikiAgent } from '../wiki/agentRun.js';
 import { appendLog, indexSpec, upsertDoc } from '../wiki/builder.js';
 import { repoDive, scoreDocs } from '../wiki/dive.js';
 import { actorSchema, BUILD_ACTOR, CONCEPT_TYPES, isPrivatePath, isReservedFilename, trustTier, } from '../wiki/format.js';
-import { edgeKey, entityStats, findNodes, isPrivateNode, loadEntityGraph, loadRelations, neighbors, nodesOfKind, NODE_KINDS, RELATIONS, relationsByTier, saveRelations, shortestPath, snapshotDrift, } from '../wiki/entities.js';
+import { appendRelation, edgeKey, entityStats, findNodes, isPrivateNode, loadEntityGraph, loadRelations, neighbors, nodesOfKind, NODE_KINDS, RELATIONS, relationsByTier, shortestPath, snapshotDrift, } from '../wiki/entities.js';
 import { buildGraph, graphStats, neighborhood } from '../wiki/graph.js';
 import { formatLintReport, lintDoc, lintVault } from '../wiki/lint.js';
 import { sectionSlice } from '../wiki/markdown.js';
 import { docsInDirectory, jailedAbsPath, loadVault, lookupTarget, makeWikiDoc, resolveLinkTarget, resolveWikiRoot, writeDocFile, } from '../wiki/vault.js';
-import { defineTool, toFunctionTool } from './toolContract.js';
+import { toFunctionTool } from './adkTool.js';
+import { defineTool } from './toolContract.js';
 // ── Shared helpers ───────────────────────────────────────────────────────────
 function todayIso() {
     return new Date().toISOString().slice(0, 10);
@@ -474,11 +475,6 @@ export const wikiRelateContract = defineTool({
         if (fromNode.kind === 'doc' && !isPrivateNode(fromNode) && isPrivateNode(toNode)) {
             return `REJECTED — ${fromNode.id} is a public document and ${toNode.id} is private knowledge. Public documents never point into the private annex; move the claim to a /private/ document instead.`;
         }
-        const { records } = loadRelations(root);
-        const key = edgeKey({ from: fromNode.id, rel: relation, to: toNode.id });
-        if (records.some((r) => edgeKey(r) === key)) {
-            return `UNCHANGED — ${key} is already asserted. wiki_graph on either node shows it.`;
-        }
         const record = {
             from: fromNode.id,
             to: toNode.id,
@@ -488,9 +484,17 @@ export const wikiRelateContract = defineTool({
             at: todayIso(),
             ...(note ? { note } : {}),
         };
-        saveRelations(root, [...records, record]);
+        // Appended at the end, never re-sorted: relations.json merges by keeping both sides.
+        try {
+            if (!appendRelation(root, record)) {
+                return `UNCHANGED — ${edgeKey(record)} is already asserted. wiki_graph on either node shows it.`;
+            }
+        }
+        catch (err) {
+            return `REJECTED — the relation store could not be appended to, so nothing was written: ${err instanceof Error ? err.message : String(err)}. Fix .graph/relations.json first.`;
+        }
         appendLog(root, todayIso(), 'relate', `${fromNode.id} —${relation}→ ${toNode.id}`, `by ${actor}`, logTargetFor(isPrivateNode(fromNode) || isPrivateNode(toNode)));
-        const reverse = records.find((r) => r.from === toNode.id && r.to === fromNode.id && r.rel === relation);
+        const reverse = loadRelations(root).records.find((r) => r.from === toNode.id && r.to === fromNode.id && r.rel === relation);
         return [
             `ASSERTED ${fromNode.id} —${relation}→ ${toNode.id} · logged to /log.md`,
             `reads: ${fromNode.label} ${RELATIONS[relation].phrase} ${toNode.label}`,

package/dist/lib/tools/xApiSearchTool.d.ts

@@ -179,7 +179,7 @@ export interface XApiSearchInput {
 }
 /** One page of X, rendered for an agent. Never throws — see the header. */
 export declare function runXApiSearch(input: XApiSearchInput, deps?: XApiDeps): Promise<string>;
-export declare const xApiSearchContract: import("./toolContract.ts").ToolContract<z.ZodObject<{
+export declare const xApiSearchContract: import("./toolContract.ts").DefinedTool<z.ZodObject<{
     query: z.ZodOptional<z.ZodString>;
     post: z.ZodOptional<z.ZodString>;
     days: z.ZodOptional<z.ZodNumber>;
@@ -189,6 +189,6 @@ export declare const xApiSearchContract: import("./toolContract.ts").ToolContrac
     }>>;
     max_results: z.ZodOptional<z.ZodNumber>;
     read_images: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>>;
+}, z.core.$strip>, string>;
 /** ADK surface, registered under its contract name in lib/toolRegistry.ts. */
 export declare const xApiSearchTool: import("@google/adk").FunctionTool<undefined>;

package/dist/lib/tools/xApiSearchTool.js

@@ -57,7 +57,8 @@
  */
 import { GoogleGenAI } from '@google/genai';
 import { z } from 'zod';
-import { defineTool, toFunctionTool } from './toolContract.js';
+import { toFunctionTool } from './adkTool.js';
+import { defineTool } from './toolContract.js';
 export const X_API_SEARCH_TOOL_NAME = 'x_api_search';
 const API = 'https://api.x.com/2';
 /** Unit cost of a post read, USD — one place, dated in the header. */

package/dist/lib/tools/xSearchTool.d.ts

@@ -35,8 +35,11 @@
  */
 import { BaseTool } from '@google/adk';
 import type { LlmRequest } from '@google/adk';
+import { NATIVE_TOOL } from './tool.ts';
 export declare const X_SEARCH_TOOL_NAME = "x_search";
+/** The ADK runtime's form of X_SEARCH_MARKER (lib/tools/nativeTools.ts), carrying its marker. */
 export declare class XSearchTool extends BaseTool {
+    readonly [NATIVE_TOOL]: import("../model.ts").NativeTool;
     constructor();
     /** Never a client-side function tool — xAI runs the search server-side. */
     _getDeclaration(): undefined;
@@ -48,14 +51,9 @@ export declare class XSearchTool extends BaseTool {
 }
 /** Shared instance, mirroring WEB_SEARCH. */
 export declare const X_SEARCH: XSearchTool;
-/** True when the agent requested X search (xAI sentinel path). */
+/** True when the agent requested X search (xAI sentinel path), by marker. */
 export declare function wantsXSearch(llmRequest: LlmRequest): boolean;
-/** Sentinel test used by the request builder to skip function-tool emission. */
+/** Sentinel test used by the request builder to skip function-tool emission: the x_search marker, on either form. */
 export declare function isXSearchSentinel(tool: unknown): boolean;
-/**
- * Optional server-side constraints for the x_search tool, read from the
- * environment at request-build time (see WHICH CONSTRAINTS above). With
- * nothing configured this returns {} and the tool ships bare, exactly as
- * it always has.
- */
-export declare function xSearchParamsFromEnv(): Record<string, unknown>;
+/** The XAI_X_SEARCH_* reader lives in lib/tools/xaiSearchParams.ts (no @google/adk); re-exported here under its old name. */
+export { xSearchParamsFromEnv } from './xaiSearchParams.ts';

package/dist/lib/tools/xSearchTool.js

@@ -35,14 +35,14 @@
  */
 import { BaseTool } from '@google/adk';
 import { providerForModel } from '../models/providerMap.js';
+import { X_SEARCH_MARKER } from './nativeTools.js';
+import { NATIVE_TOOL, nativeToolMarkerOf } from './tool.js';
 export const X_SEARCH_TOOL_NAME = 'x_search';
+/** The ADK runtime's form of X_SEARCH_MARKER (lib/tools/nativeTools.ts), carrying its marker. */
 export class XSearchTool extends BaseTool {
+    [NATIVE_TOOL] = X_SEARCH_MARKER[NATIVE_TOOL];
     constructor() {
-        super({
-            name: X_SEARCH_TOOL_NAME,
-            description: 'Live search over X (Twitter) posts via xAI Agent Tools — ' +
-                'grok-* models only; a no-op sentinel on every other provider.',
-        });
+        super({ name: X_SEARCH_TOOL_NAME, description: X_SEARCH_MARKER.description });
     }
     /** Never a client-side function tool — xAI runs the search server-side. */
     _getDeclaration() {
@@ -62,64 +62,13 @@ export class XSearchTool extends BaseTool {
 }
 /** Shared instance, mirroring WEB_SEARCH. */
 export const X_SEARCH = new XSearchTool();
-/** True when the agent requested X search (xAI sentinel path). */
+/** True when the agent requested X search (xAI sentinel path), by marker. */
 export function wantsXSearch(llmRequest) {
-    return llmRequest.toolsDict?.[X_SEARCH_TOOL_NAME] instanceof XSearchTool;
+    return isXSearchSentinel(llmRequest.toolsDict?.[X_SEARCH_TOOL_NAME]);
 }
-/** Sentinel test used by the request builder to skip function-tool emission. */
+/** Sentinel test used by the request builder to skip function-tool emission: the x_search marker, on either form. */
 export function isXSearchSentinel(tool) {
-    return tool instanceof XSearchTool;
-}
-/** xAI's documented ceiling on allowed_x_handles / excluded_x_handles. */
-const X_SEARCH_MAX_HANDLES = 20;
-/** ISO date (YYYY-MM-DD) from an env var; malformed values warn and drop. */
-function isoDateFromEnv(name) {
-    const raw = process.env[name]?.trim();
-    if (!raw)
-        return undefined;
-    if (!/^\d{4}-\d{2}-\d{2}$/.test(raw)) {
-        console.warn(`[x_search] ${name}="${raw}" is not YYYY-MM-DD — ignored.`);
-        return undefined;
-    }
-    return raw;
-}
-/** Comma-separated handles from an env var; trimmed, @-stripped, capped. */
-function handlesFromEnv(name) {
-    const handles = (process.env[name] ?? '')
-        .split(',')
-        .map((h) => h.trim().replace(/^@/, ''))
-        .filter(Boolean);
-    if (handles.length > X_SEARCH_MAX_HANDLES) {
-        console.warn(`[x_search] ${name} lists ${handles.length} handles — xAI caps the ` +
-            `list at ${X_SEARCH_MAX_HANDLES}; keeping the first ${X_SEARCH_MAX_HANDLES}.`);
-        return handles.slice(0, X_SEARCH_MAX_HANDLES);
-    }
-    return handles;
-}
-/**
- * Optional server-side constraints for the x_search tool, read from the
- * environment at request-build time (see WHICH CONSTRAINTS above). With
- * nothing configured this returns {} and the tool ships bare, exactly as
- * it always has.
- */
-export function xSearchParamsFromEnv() {
-    const params = {};
-    const from = isoDateFromEnv('XAI_X_SEARCH_FROM_DATE');
-    const to = isoDateFromEnv('XAI_X_SEARCH_TO_DATE');
-    if (from)
-        params.from_date = from;
-    if (to)
-        params.to_date = to;
-    const allowed = handlesFromEnv('XAI_X_SEARCH_ALLOWED_HANDLES');
-    const excluded = handlesFromEnv('XAI_X_SEARCH_EXCLUDED_HANDLES');
-    if (allowed.length > 0 && excluded.length > 0) {
-        console.warn('[x_search] XAI_X_SEARCH_ALLOWED_HANDLES and _EXCLUDED_HANDLES are ' +
-            'mutually exclusive (xAI rejects both together) — keeping the ' +
-            'allowlist, dropping the exclusions.');
-    }
-    if (allowed.length > 0)
-        params.allowed_x_handles = allowed;
-    else if (excluded.length > 0)
-        params.excluded_x_handles = excluded;
-    return params;
+    return nativeToolMarkerOf(tool) === 'x_search';
 }
+/** The XAI_X_SEARCH_* reader lives in lib/tools/xaiSearchParams.ts (no @google/adk); re-exported here under its old name. */
+export { xSearchParamsFromEnv } from './xaiSearchParams.js';

package/dist/lib/tools/xaiSearchParams.d.ts

@@ -0,0 +1,41 @@
+/**
+ * lib/tools/xaiSearchParams.ts — the deployment settings for xAI's
+ * server-side search tools, read from the environment at request-build time.
+ *
+ * WHY its own module: GrokAdapter (lib/models/grokAdapter.ts) reads these
+ * on the engine's own contract, and the tool modules that also export them
+ * (webSearchTool.ts, xSearchTool.ts, collectionsSearchTool.ts) extend ADK's
+ * BaseTool. Here they import nothing, so the `melchizedek-agents/model`
+ * entry reaches no @google/adk. The tool modules re-export each reader under
+ * its old name.
+ *
+ * THE DOCTRINE (unchanged): constraints are deployment configuration, never
+ * YAML, so the YAML stays shareable. Misconfiguration degrades with a
+ * warning, never fatally.
+ *   - web_search (docs.x.ai/developers/tools/web-search, 2026-08-08):
+ *     allowed_domains / excluded_domains, at most 5 each and mutually
+ *     exclusive, nested under `filters`. No date bounds. xAI only: OpenAI's
+ *     web_search takes no such params.
+ *   - x_search (docs.x.ai/developers/tools/x-search, 2026-08-02):
+ *     from_date / to_date (YYYY-MM-DD) and allowed_x_handles /
+ *     excluded_x_handles, at most 20 each and mutually exclusive.
+ *   - collections_search: XAI_COLLECTION_IDS (comma-separated) and an
+ *     optional XAI_COLLECTIONS_MAX_RESULTS cap.
+ * When both lists of a pair are set, the allowlist wins. Oversize lists
+ * truncate. Malformed dates are dropped.
+ */
+/**
+ * Optional server-side domain filters for xAI's web_search tool. With
+ * nothing configured this returns {} and the tool ships bare. xAI only:
+ * apply on the xAI path, never on OpenAI's web_search.
+ */
+export declare function xaiWebSearchParamsFromEnv(): Record<string, unknown>;
+/**
+ * Optional server-side constraints for the x_search tool. With nothing
+ * configured this returns {} and the tool ships bare.
+ */
+export declare function xSearchParamsFromEnv(): Record<string, unknown>;
+/** Collection ids from XAI_COLLECTION_IDS (comma-separated, trimmed). */
+export declare function collectionIdsFromEnv(): string[];
+/** Optional retrieval cap from XAI_COLLECTIONS_MAX_RESULTS (positive int). */
+export declare function collectionsMaxResultsFromEnv(): number | undefined;

package/dist/lib/tools/xaiSearchParams.js

@@ -0,0 +1,126 @@
+/**
+ * lib/tools/xaiSearchParams.ts — the deployment settings for xAI's
+ * server-side search tools, read from the environment at request-build time.
+ *
+ * WHY its own module: GrokAdapter (lib/models/grokAdapter.ts) reads these
+ * on the engine's own contract, and the tool modules that also export them
+ * (webSearchTool.ts, xSearchTool.ts, collectionsSearchTool.ts) extend ADK's
+ * BaseTool. Here they import nothing, so the `melchizedek-agents/model`
+ * entry reaches no @google/adk. The tool modules re-export each reader under
+ * its old name.
+ *
+ * THE DOCTRINE (unchanged): constraints are deployment configuration, never
+ * YAML, so the YAML stays shareable. Misconfiguration degrades with a
+ * warning, never fatally.
+ *   - web_search (docs.x.ai/developers/tools/web-search, 2026-08-08):
+ *     allowed_domains / excluded_domains, at most 5 each and mutually
+ *     exclusive, nested under `filters`. No date bounds. xAI only: OpenAI's
+ *     web_search takes no such params.
+ *   - x_search (docs.x.ai/developers/tools/x-search, 2026-08-02):
+ *     from_date / to_date (YYYY-MM-DD) and allowed_x_handles /
+ *     excluded_x_handles, at most 20 each and mutually exclusive.
+ *   - collections_search: XAI_COLLECTION_IDS (comma-separated) and an
+ *     optional XAI_COLLECTIONS_MAX_RESULTS cap.
+ * When both lists of a pair are set, the allowlist wins. Oversize lists
+ * truncate. Malformed dates are dropped.
+ */
+/** xAI's documented ceiling on allowed_domains / excluded_domains. */
+const XAI_WEB_SEARCH_MAX_DOMAINS = 5;
+/** xAI's documented ceiling on allowed_x_handles / excluded_x_handles. */
+const X_SEARCH_MAX_HANDLES = 20;
+/** Comma-separated domains from an env var; trimmed, capped at xAI's limit. */
+function domainsFromEnv(name) {
+    const domains = (process.env[name] ?? '')
+        .split(',')
+        .map((d) => d.trim())
+        .filter(Boolean);
+    if (domains.length > XAI_WEB_SEARCH_MAX_DOMAINS) {
+        console.warn(`[web_search] ${name} lists ${domains.length} domains — xAI caps the ` +
+            `list at ${XAI_WEB_SEARCH_MAX_DOMAINS}; keeping the first ${XAI_WEB_SEARCH_MAX_DOMAINS}.`);
+        return domains.slice(0, XAI_WEB_SEARCH_MAX_DOMAINS);
+    }
+    return domains;
+}
+/**
+ * Optional server-side domain filters for xAI's web_search tool. With
+ * nothing configured this returns {} and the tool ships bare. xAI only:
+ * apply on the xAI path, never on OpenAI's web_search.
+ */
+export function xaiWebSearchParamsFromEnv() {
+    const allowed = domainsFromEnv('XAI_WEB_SEARCH_ALLOWED_DOMAINS');
+    const excluded = domainsFromEnv('XAI_WEB_SEARCH_EXCLUDED_DOMAINS');
+    if (allowed.length > 0 && excluded.length > 0) {
+        console.warn('[web_search] XAI_WEB_SEARCH_ALLOWED_DOMAINS and _EXCLUDED_DOMAINS are ' +
+            'mutually exclusive (xAI rejects both together) — keeping the ' +
+            'allowlist, dropping the exclusions.');
+    }
+    if (allowed.length > 0)
+        return { filters: { allowed_domains: allowed } };
+    if (excluded.length > 0)
+        return { filters: { excluded_domains: excluded } };
+    return {};
+}
+/** ISO date (YYYY-MM-DD) from an env var; malformed values warn and drop. */
+function isoDateFromEnv(name) {
+    const raw = process.env[name]?.trim();
+    if (!raw)
+        return undefined;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(raw)) {
+        console.warn(`[x_search] ${name}="${raw}" is not YYYY-MM-DD — ignored.`);
+        return undefined;
+    }
+    return raw;
+}
+/** Comma-separated handles from an env var; trimmed, @-stripped, capped. */
+function handlesFromEnv(name) {
+    const handles = (process.env[name] ?? '')
+        .split(',')
+        .map((h) => h.trim().replace(/^@/, ''))
+        .filter(Boolean);
+    if (handles.length > X_SEARCH_MAX_HANDLES) {
+        console.warn(`[x_search] ${name} lists ${handles.length} handles — xAI caps the ` +
+            `list at ${X_SEARCH_MAX_HANDLES}; keeping the first ${X_SEARCH_MAX_HANDLES}.`);
+        return handles.slice(0, X_SEARCH_MAX_HANDLES);
+    }
+    return handles;
+}
+/**
+ * Optional server-side constraints for the x_search tool. With nothing
+ * configured this returns {} and the tool ships bare.
+ */
+export function xSearchParamsFromEnv() {
+    const params = {};
+    const from = isoDateFromEnv('XAI_X_SEARCH_FROM_DATE');
+    const to = isoDateFromEnv('XAI_X_SEARCH_TO_DATE');
+    if (from)
+        params.from_date = from;
+    if (to)
+        params.to_date = to;
+    const allowed = handlesFromEnv('XAI_X_SEARCH_ALLOWED_HANDLES');
+    const excluded = handlesFromEnv('XAI_X_SEARCH_EXCLUDED_HANDLES');
+    if (allowed.length > 0 && excluded.length > 0) {
+        console.warn('[x_search] XAI_X_SEARCH_ALLOWED_HANDLES and _EXCLUDED_HANDLES are ' +
+            'mutually exclusive (xAI rejects both together) — keeping the ' +
+            'allowlist, dropping the exclusions.');
+    }
+    if (allowed.length > 0)
+        params.allowed_x_handles = allowed;
+    else if (excluded.length > 0)
+        params.excluded_x_handles = excluded;
+    return params;
+}
+/** Collection ids from XAI_COLLECTION_IDS (comma-separated, trimmed). */
+export function collectionIdsFromEnv() {
+    return (process.env.XAI_COLLECTION_IDS ?? '')
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean);
+}
+/** Optional retrieval cap from XAI_COLLECTIONS_MAX_RESULTS (positive int). */
+export function collectionsMaxResultsFromEnv() {
+    const raw = process.env.XAI_COLLECTIONS_MAX_RESULTS?.trim();
+    if (!raw)
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}

package/dist/lib/wiki/agentRun.d.ts

@@ -15,8 +15,16 @@
  *   provider — wiki operations inherit the framework's full model
  *   optionality. A missing provider key degrades to a clear error string;
  *   nothing here throws for want of credentials.
+ *
+ *   The runtime follows the turn runner's flag (lib/runtime/runtimeFlag.ts):
+ *   MELCHIZEDEK_RUNTIME, or the run's `runtime` option. On `native` the
+ *   same agent runs on the engine's own loop (lib/runtime/nativeTurn.ts),
+ *   each wiki FunctionTool as the own Tool behind it, and its events are
+ *   read the same way.
  */
 import type { FunctionTool } from '@google/adk';
+import type { ModelAdapter } from '../models/contract.ts';
+import type { RuntimeName } from '../runtime/runtimeFlag.ts';
 export interface WikiAgentRun {
     name: string;
     description: string;
@@ -26,6 +34,10 @@ export interface WikiAgentRun {
     tools?: FunctionTool[];
     temperature?: number;
     maxOutputTokens?: number;
+    /** The runtime that runs the agent. Default: MELCHIZEDEK_RUNTIME, else adk. */
+    runtime?: RuntimeName;
+    /** Native runtime only: the leaf adapter for a model id. Default resolveAdapter (lib/models/registry.ts). */
+    adapterFor?: (model: string) => ModelAdapter;
 }
 export interface WikiAgentResult {
     text: string;

package/dist/lib/wiki/agentRun.js

@@ -15,10 +15,21 @@
  *   provider — wiki operations inherit the framework's full model
  *   optionality. A missing provider key degrades to a clear error string;
  *   nothing here throws for want of credentials.
+ *
+ *   The runtime follows the turn runner's flag (lib/runtime/runtimeFlag.ts):
+ *   MELCHIZEDEK_RUNTIME, or the run's `runtime` option. On `native` the
+ *   same agent runs on the engine's own loop (lib/runtime/nativeTurn.ts),
+ *   each wiki FunctionTool as the own Tool behind it, and its events are
+ *   read the same way.
  */
 import { randomUUID } from 'node:crypto';
 import { InMemorySessionService, LlmAgent, Runner } from '@google/adk';
-import { providerForModel, providerKeyPresent, registerAvailableProviders, } from '../models/registry.js';
+import { providerForModel, providerKeyPresent, registerAvailableProviders, resolveAdapter, } from '../models/registry.js';
+import { SelfCorrection } from '../runtime/native/selfCorrection.js';
+import { runNativeAgent } from '../runtime/nativeTurn.js';
+import { chooseRuntime } from '../runtime/runtimeFlag.js';
+import { InProcessSessionService } from '../runtime/sessions.js';
+import { toolOf } from '../tools/tool.js';
 /** True when the model's provider has credentials (Ollama needs none). */
 export function modelAvailable(model) {
     const provider = providerForModel(model);
@@ -26,43 +37,26 @@ export function modelAvailable(model) {
         return { ok: true };
     return { ok: false, reason: `provider "${provider}" has no API key configured` };
 }
-export async function runWikiAgent(run) {
-    const availability = modelAvailable(run.model);
-    if (!availability.ok) {
-        return { text: '', error: availability.reason };
-    }
-    registerAvailableProviders();
-    const agent = new LlmAgent({
-        name: run.name,
-        description: run.description,
-        model: run.model,
-        instruction: run.instruction,
-        generateContentConfig: {
-            temperature: run.temperature ?? 0.3,
-            maxOutputTokens: run.maxOutputTokens ?? 4096,
-        },
-        ...(run.tools && run.tools.length > 0 ? { tools: run.tools } : {}),
-    });
-    const appName = 'melchizedek-wiki';
-    const userId = 'wiki';
-    const sessionId = randomUUID();
-    const sessionService = new InMemorySessionService();
-    const runner = new Runner({ agent, appName, sessionService });
-    await sessionService.createSession({ appName, userId, sessionId, state: {} });
+const APP_NAME = 'melchizedek-wiki';
+const USER_ID = 'wiki';
+/** The generateContentConfig every wiki run sends. */
+function configOf(run) {
+    return {
+        temperature: run.temperature ?? 0.3,
+        maxOutputTokens: run.maxOutputTokens ?? 4096,
+    };
+}
+/** Reads a run's events, either runtime: every non-thinking text part, and the last error. */
+async function readRun(stream) {
     let outputText = '';
     let errorText = '';
     try {
-        const stream = runner.runAsync({
-            userId,
-            sessionId,
-            newMessage: { role: 'user', parts: [{ text: run.userText }] },
-        });
-        for await (const event of stream) {
-            const evAny = event;
-            if ((evAny.errorCode || evAny.errorMessage) && evAny.errorCode !== 'STOP') {
-                errorText = `[${evAny.errorCode ?? 'ERROR'}] ${evAny.errorMessage ?? ''}`;
+        for await (const event of stream()) {
+            const e = event;
+            if ((e.errorCode || e.errorMessage) && e.errorCode !== 'STOP') {
+                errorText = `[${e.errorCode ?? 'ERROR'}] ${e.errorMessage ?? ''}`;
             }
-            for (const part of event.content?.parts ?? []) {
+            for (const part of e.content?.parts ?? []) {
                 const p = part;
                 if (!p.thought && p.text)
                     outputText += p.text;
@@ -77,3 +71,47 @@ export async function runWikiAgent(run) {
         ...(errorText ? { error: errorText } : {}),
     };
 }
+export async function runWikiAgent(run) {
+    const availability = modelAvailable(run.model);
+    if (!availability.ok) {
+        return { text: '', error: availability.reason };
+    }
+    const sessionId = randomUUID();
+    const newMessage = { role: 'user', parts: [{ text: run.userText }] };
+    if (chooseRuntime(run.runtime) === 'native') {
+        const agent = {
+            name: run.name,
+            description: run.description,
+            model: run.model,
+            instruction: run.instruction,
+            generateContentConfig: configOf(run),
+            tools: (run.tools ?? []).map((t) => toolOf(t) ?? t),
+        };
+        const sessions = new InProcessSessionService();
+        await sessions.create({ appName: APP_NAME, userId: USER_ID, sessionId });
+        return readRun(() => runNativeAgent({
+            agent,
+            adapterFor: run.adapterFor ?? ((model) => resolveAdapter(model)),
+            sessions,
+            appName: APP_NAME,
+            userId: USER_ID,
+            sessionId,
+            userParts: newMessage.parts,
+            // As on ADK, where this Runner installs no reflect-and-retry plugins.
+            selfCorrection: new SelfCorrection({ model_errors: 0, tool_errors: 0 }),
+        }));
+    }
+    registerAvailableProviders();
+    const agent = new LlmAgent({
+        name: run.name,
+        description: run.description,
+        model: run.model,
+        instruction: run.instruction,
+        generateContentConfig: configOf(run),
+        ...(run.tools && run.tools.length > 0 ? { tools: run.tools } : {}),
+    });
+    const sessionService = new InMemorySessionService();
+    const runner = new Runner({ agent, appName: APP_NAME, sessionService });
+    await sessionService.createSession({ appName: APP_NAME, userId: USER_ID, sessionId, state: {} });
+    return readRun(() => runner.runAsync({ userId: USER_ID, sessionId, newMessage }));
+}

package/dist/lib/wiki/entities.d.ts

@@ -182,7 +182,19 @@ export interface LoadedRelations {
 }
 export declare function loadRelations(wikiRoot: string): LoadedRelations;
 export declare function relationEdges(records: RelationRecord[]): EntityEdge[];
+/**
+ * Replace the whole store with `records`, in the order given. The store's
+ * order is the order of assertion; nothing sorts it.
+ */
 export declare function saveRelations(wikiRoot: string, records: RelationRecord[]): void;
+/**
+ * Add one assertion at the end of the store. Every record already there
+ * keeps its place and its bytes, so two branches that each assert something
+ * merge by keeping both sides. Returns false, writing nothing, when the edge
+ * is already asserted. Throws when the store does not parse rather than
+ * write over it.
+ */
+export declare function appendRelation(wikiRoot: string, record: RelationRecord): boolean;
 export interface GraphSnapshot {
     version: number;
     generated: {