melchizedek-agents 0.9.0

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

@@ -0,0 +1,112 @@
+/**
+ * lib/tools/wikiTools.ts — the wiki's tool surface, defined once.
+ *
+ * WHY this file exists:
+ *   Everything an agent (or MCP client) can DO with the knowledge bundle is
+ *   a ToolContract here — zod schema single source of truth, derived into
+ *   ADK FunctionTools for syndicate agents and MCP definitions for outside
+ *   clients, exactly like the rest of lib/tools.
+ *
+ *   Three capability tiers, deliberately separated:
+ *
+ *   NAVIGATE (wiki_map, wiki_read, wiki_search, wiki_links, wiki_dive,
+ *     wiki_graph) — pure functions over the bundle. No model, no writes,
+ *     instant. These are what "repo dive" means: an agent on a knowledge
+ *     task orients, searches, follows links, and gets an ordered reading
+ *     plan. wiki_graph adds the second layer — the ENTITY graph of agents,
+ *     tools, models, modules, tables and env vars derived from repo truth
+ *     (lib/wiki/entities.ts) — which answers relational questions no
+ *     amount of document search can ("who calls this tool").
+ *
+ *   WRITE (wiki_save, wiki_relate) — the only two write paths, both gated.
+ *     wiki_save: parse → profile validation → lint (errors block,
+ *     including the private-closure rule) → path-jailed write → directory
+ *     index refresh → log.md entry. wiki_relate: one asserted relation,
+ *     refused unless the relation is an INFERRED one (structural relations
+ *     are derived by the build), both endpoints exist, no public document
+ *     points into the private annex, and evidence is supplied. Agents
+ *     cannot corrupt the bundle through either door; the worst they can do
+ *     is write mediocre prose, which lint's warnings surface and git can
+ *     revert.
+ *
+ *   AGENTIC (wiki_query, wiki_garden) — composites that put a model in
+ *     the loop, running a one-shot agent equipped with the tier-1 (and for
+ *     garden, tier-2) tools. Exposed so an MCP client can ask the wiki a
+ *     question or delegate an edit as ONE call.
+ *
+ *   Exposure stays deliberate (the registry/server decide); defining these
+ *   contracts publishes nothing by itself.
+ */
+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<{
+    path: z.ZodString;
+    section: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export declare const wikiSearchContract: ToolContract<z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const wikiLinksContract: ToolContract<z.ZodObject<{
+    path: z.ZodString;
+    depth: z.ZodDefault<z.ZodNumber>;
+    direction: z.ZodDefault<z.ZodEnum<{
+        in: "in";
+        out: "out";
+        both: "both";
+    }>>;
+}, z.core.$strip>>;
+export declare const wikiDiveContract: ToolContract<z.ZodObject<{
+    task: z.ZodString;
+    budget_words: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const wikiGraphContract: ToolContract<z.ZodObject<{
+    node: z.ZodOptional<z.ZodString>;
+    find: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodString>;
+    path_to: z.ZodOptional<z.ZodString>;
+    relations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    depth: z.ZodDefault<z.ZodNumber>;
+    direction: z.ZodDefault<z.ZodEnum<{
+        in: "in";
+        out: "out";
+        both: "both";
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+export declare const wikiRelateContract: ToolContract<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<{
+    path: z.ZodString;
+    content: z.ZodString;
+    actor: z.ZodString;
+    summary: z.ZodString;
+}, z.core.$strip>>;
+export declare const wikiQueryContract: ToolContract<z.ZodObject<{
+    question: z.ZodString;
+    model: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export declare const wikiGardenContract: ToolContract<z.ZodObject<{
+    instruction: z.ZodString;
+    model: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+/** Everything an MCP client may be offered (see the wiki MCP server script). */
+export declare const WIKI_TOOL_CONTRACTS: readonly ToolContract<any>[];
+/**
+ * What syndicate agents may declare in YAML (via lib/toolRegistry.ts).
+ * The agentic composites are excluded on purpose: a syndicate reaches
+ * query/garden behavior by BEING the agent with these primitives, not by
+ * nesting another agent run inside a tool call.
+ */
+export declare const WIKI_AGENT_TOOL_CONTRACTS: readonly ToolContract<any>[];
+/** Lint the whole bundle — shared by the build script and tests. */
+export declare function lintWholeVault(): string;
+/** Census helper for scripts (not a tool): concepts + word count. */
+export declare function vaultCensus(): string;