@cerebriline/core 4.100.240 → 4.100.241

package/dist/extensions/tools/library-tools.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The Library's tools: what the model sees of it.
+ *
+ * `search_library` finds passages in the books the user has collected and
+ * `list_library` says what is there, shelf by shelf. Both are offered
+ * whenever the Library is on. Everything that changes the Library is the
+ * librarian's (`librarian-tools.ts`), and offered only with that skill.
+ *
+ * They work on keywords alone; an embedding model and a reranker, when the
+ * user has configured them, make the search better and change nothing else.
+ */
+import { type AgentTool, type LibrarySettings } from "@cerebriline/shared";
+import type { Catalogue, LibraryBook, LibraryShelf } from "../../services/retrieval/catalogue";
+import type { RetrievalEndpoint } from "../../services/retrieval/embedding-client";
+import type { ScrapeEndpoint } from "../../services/retrieval/firecrawl";
+import { type Library } from "../../services/retrieval/library";
+import type { RetrieveResult } from "../../services/retrieval/retrieve";
+import type { DocumentReaderSettings } from "./executors/document/ocr";
+import type { DescribeImages } from "./executors/document/recognition";
+export declare const LIBRARY_TOOL_NAMES: readonly ["search_library", "list_library"];
+export type LibraryToolName = (typeof LIBRARY_TOOL_NAMES)[number];
+/** The built-in skill that brings the librarian's tools with it. */
+export declare const LIBRARIAN_SKILL_NAME = "librarian";
+export interface LibraryScrapeConfig extends ScrapeEndpoint {
+    /** Pages one crawl reads, at most. */
+    maxPages: number;
+    /** How many links deep a crawl follows. */
+    maxDepth: number;
+}
+export interface LibraryToolsConfig {
+    settings: LibrarySettings;
+    /** The embedding model, when the user has set one. */
+    embedding?: RetrievalEndpoint;
+    /** The reranking model, when the user has set one. */
+    reranker?: RetrievalEndpoint;
+    documentReader?: DocumentReaderSettings;
+    /**
+     * The scraping endpoint, when it is set up under Features and the
+     * session's profile allows it. Without it the librarian has no web tools.
+     */
+    scrape?: LibraryScrapeConfig;
+}
+export interface CreateLibraryToolsOptions {
+    cwd: string;
+    /**
+     * Read on every call: the settings can change mid-session. Undefined, or
+     * settings with `enabled` off, means the Library is off.
+     */
+    getConfig: () => LibraryToolsConfig | undefined;
+    /** @default the shared Library of the data folder */
+    library?: Library;
+    /**
+     * The model that describes a book's pictures, read when a book is added.
+     * May take a moment: a host can ask a server whether a model reads images.
+     */
+    getDescribeImages?: () => DescribeImages | undefined | Promise<DescribeImages | undefined>;
+    /** Whether the librarian's tools are offered. @default the librarian skill is on */
+    librarian?: boolean;
+    onError?: (message: string, error: unknown) => void;
+    log?: (message: string) => void;
+}
+export declare const LIBRARY_OFF = "The Library is turned off. The user turns it on under Settings > Library; do not call this again in this task.";
+export declare function errorText(error: unknown): string;
+export declare function strings(value: unknown): string[];
+export declare function text(value: unknown): string;
+export declare function activeConfig(options: CreateLibraryToolsOptions): LibraryToolsConfig | undefined;
+export declare function plural(count: number, one: string, many?: string): string;
+/** What is on the shelves, as the model is shown it. */
+export declare function describeShelves(catalogue: Catalogue): string;
+/**
+ * A shelf as the model names it: "Section / Shelf", or the shelf's name
+ * alone when only one shelf has it.
+ */
+export declare function resolveShelf(catalogue: Catalogue, reference: string, section?: string): (LibraryShelf & {
+    section: string;
+}) | undefined;
+export declare function describeBookLine(book: LibraryBook): string;
+export declare function describeSearch(query: string, result: RetrieveResult, collectionName: (id: number) => string): string;
+/** One book in full: what it is, what it was made from, its pictures. */
+export declare function describeBook(catalogue: Catalogue, book: LibraryBook): string;
+/** Whether the user has the librarian skill turned on. */
+export declare function isLibrarianEnabled(): boolean;
+/**
+ * The Library's tools, when the Library is on at session start. Whether it
+ * is on is read again on every call, so turning it off mid-session stops the
+ * tools answering without a restart.
+ */
+export declare function createLibraryTools(options: CreateLibraryToolsOptions): AgentTool[];

package/dist/extensions/tools/memory-tools.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Memory's tools: `remember`, `recall` and `forget`.
+ *
+ * What the model keeps from one task to the next. The store works on
+ * keywords alone; the embedding and reranking models of the Embedding tab,
+ * when set, make a recall find a note by what it means.
+ *
+ * Which memories a session uses is the user's choice per workspace, made in
+ * the Memory panel: one memory new notes are kept in, and the memories that
+ * are searched. The tools take no memory name: a model cannot store to, or
+ * read from, a memory the user did not allow this workspace.
+ */
+import { type AgentTool, type MemorySettings } from "@cerebriline/shared";
+import { type Memory, type MemoryEndpoints } from "../../services/retrieval/memory";
+export declare const MEMORY_TOOL_NAMES: readonly ["remember", "recall", "forget"];
+export type MemoryToolName = (typeof MEMORY_TOOL_NAMES)[number];
+export interface MemoryToolsConfig extends MemoryEndpoints {
+    settings: MemorySettings;
+}
+export interface CreateMemoryToolsOptions {
+    /** The workspace, which is what the user's choice of memories is filed under. */
+    cwd: string;
+    /** Read on every call. Undefined, or `enabled` off, means Memory is off. */
+    getConfig: () => MemoryToolsConfig | undefined;
+    /** @default the shared Memory of the data folder */
+    memory?: Memory;
+    onError?: (message: string, error: unknown) => void;
+    log?: (message: string) => void;
+}
+/**
+ * The memories this workspace uses, held to the ones that exist: a memory
+ * deleted after it was picked is left out of the search, and notes go to
+ * the main memory rather than nowhere.
+ */
+export declare function resolveMemoryAccess(memory: Memory, settings: MemorySettings, cwd: string): {
+    store: string;
+    recall: string[];
+    storeFellBack?: string;
+};
+/** Memory's tools, when Memory is on at session start. */
+export declare function createMemoryTools(options: CreateMemoryToolsOptions): AgentTool[];

package/dist/extensions/tools/sdd-tool.d.ts

@@ -0,0 +1,215 @@
+/**
+ * The `sdd` tool: the spec-driven engine, as the model sees it.
+ *
+ * One tool with an `action`, not twenty tools: every tool's schema is paid
+ * for in every request, and these are used one at a time. Every answer ends
+ * with the step that is due, so the model never has to work out its place.
+ */
+import { type AgentTool } from "@cerebriline/shared";
+import { SddEngine } from "../../services/sdd/sdd-engine";
+export declare const SDD_TOOL_NAME = "sdd";
+export declare const SDD_ACTIONS: readonly ["next", "status", "set_project", "add_requirement", "update_requirement", "add_decision", "add_knowledge", "capture", "add_milestone", "update_milestone", "approve", "plan_milestone", "add_slices", "remove_slice", "plan_slice", "replan_slice", "start_task", "complete_task", "block_task", "complete_slice", "validate_milestone", "complete_milestone", "quick"];
+export type SddAction = (typeof SDD_ACTIONS)[number];
+export declare const SDD_TOOL_DESCRIPTION = "Spec-driven development: the project's plan and where the work stands, kept in a database in the project (.sdd/). Use it for every step of a planned build; do not keep the plan in your head or in files of your own.\n\nCall with action \"next\" whenever you are unsure what to do: it answers with the one step that is due and everything that step needs. Every other action ends by telling you the next step too. A step out of turn is refused with the reason.\n\nActions:\n- next, status: where things stand. Change nothing.\n- set_project {name, description, agreements}\n- add_requirement {title, description}; update_requirement {id, status: active | validated | deferred | out_of_scope}\n- add_decision {title, choice, why}; add_knowledge {text}; capture {text} (a thought for later)\n- add_milestone {title, context}; update_milestone {title, context}\n- approve {what: \"requirements\" | \"roadmap\"}: only after the user has said yes to them.\n- plan_milestone {slices: [{title, goal, demo, depends: [\"S01\"], requirements: [\"R001\"]}]}\n- add_slices {slices}: more slices on an approved roadmap, when the user agreed to more scope. remove_slice {slice, reason}: take off one that has no work in it.\n- plan_slice {research, tasks: [{title, steps, files: [], verify, expect}]}\n- replan_slice {reason, tasks}: after a blocker; done tasks are kept.\n- start_task; complete_task {summary, evidence}; block_task {reason}\n- complete_slice {summary, uat: [{check, result: \"pass\" | \"fail\" | \"needs_human\", note}]}\n- validate_milestone {verdict: \"pass\" | \"needs_remediation\", findings, remediation: [slices]}\n- complete_milestone {summary}\n- quick {title, summary}: record a small change made outside the plan.\n\nevidence is the real output of the task's verify command, run in the workspace. Never write it from memory.";
+export declare const SDD_TOOL_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["next", "status", "set_project", "add_requirement", "update_requirement", "add_decision", "add_knowledge", "capture", "add_milestone", "update_milestone", "approve", "plan_milestone", "add_slices", "remove_slice", "plan_slice", "replan_slice", "start_task", "complete_task", "block_task", "complete_slice", "validate_milestone", "complete_milestone", "quick"];
+        };
+        readonly name: {
+            readonly type: "string";
+        };
+        readonly title: {
+            readonly type: "string";
+        };
+        readonly description: {
+            readonly type: "string";
+        };
+        readonly agreements: {
+            readonly type: "string";
+        };
+        readonly context: {
+            readonly type: "string";
+        };
+        readonly text: {
+            readonly type: "string";
+        };
+        readonly id: {
+            readonly type: "string";
+            readonly description: "A requirement id, e.g. R003.";
+        };
+        readonly status: {
+            readonly type: "string";
+            readonly enum: readonly ["active", "validated", "deferred", "out_of_scope"];
+        };
+        readonly choice: {
+            readonly type: "string";
+        };
+        readonly why: {
+            readonly type: "string";
+        };
+        readonly what: {
+            readonly type: "string";
+            readonly enum: readonly ["requirements", "roadmap"];
+        };
+        readonly slice: {
+            readonly type: "string";
+            readonly description: "A slice, e.g. S02. Leave out for the one that is due.";
+        };
+        readonly task: {
+            readonly type: "string";
+            readonly description: "A task, e.g. T03. Leave out for the one that is due.";
+        };
+        readonly slices: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly goal: {
+                        readonly type: "string";
+                    };
+                    readonly demo: {
+                        readonly type: "string";
+                        readonly description: "What shows that the slice works.";
+                    };
+                    readonly depends: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly requirements: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+                readonly required: readonly ["title"];
+            };
+        };
+        readonly remediation: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly goal: {
+                        readonly type: "string";
+                    };
+                    readonly demo: {
+                        readonly type: "string";
+                        readonly description: "What shows that the slice works.";
+                    };
+                    readonly depends: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly requirements: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+                readonly required: readonly ["title"];
+            };
+        };
+        readonly research: {
+            readonly type: "string";
+        };
+        readonly tasks: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly steps: {
+                        readonly type: "string";
+                    };
+                    readonly files: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly verify: {
+                        readonly type: "string";
+                        readonly description: "The one command whose output proves the task.";
+                    };
+                    readonly expect: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["title", "steps", "verify"];
+            };
+        };
+        readonly reason: {
+            readonly type: "string";
+        };
+        readonly summary: {
+            readonly type: "string";
+        };
+        readonly evidence: {
+            readonly type: "string";
+        };
+        readonly uat: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly check: {
+                        readonly type: "string";
+                    };
+                    readonly result: {
+                        readonly type: "string";
+                        readonly enum: readonly ["pass", "fail", "needs_human"];
+                    };
+                    readonly note: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["check", "result"];
+            };
+        };
+        readonly verdict: {
+            readonly type: "string";
+            readonly enum: readonly ["pass", "needs_remediation"];
+        };
+        readonly findings: {
+            readonly type: "string";
+        };
+    };
+    readonly required: readonly ["action"];
+};
+export interface SddToolOptions {
+    /** The project the plan belongs to. */
+    cwd: string;
+    onError?: (message: string, error: unknown) => void;
+}
+/** Run one action. Returns what happened, without the next step. */
+export declare function runSddAction(engine: SddEngine, input: Record<string, unknown>): string;
+export declare function createSddTool(options: SddToolOptions): AgentTool;
+/** The spec-driven skills, any one of which brings the tool with it. */
+export declare const SDD_SKILL_NAMES: readonly ["sdd-wizard", "sdd-discuss", "sdd-plan", "sdd-execute", "sdd-verify", "sdd-quick", "sdd-status"];
+/** Whether the user has any of the spec-driven skills turned on. */
+export declare function isSddEnabled(): boolean;
+/**
+ * The tool, when a spec-driven skill is on. The skills are what tell the
+ * model how to work this way; without one the tool would be a cost in every
+ * request and no use.
+ */
+export declare function createSddTools(options: SddToolOptions & {
+    log?: (message: string) => void;
+}): AgentTool[];

package/dist/extensions/tools/team/create-agent-tool.d.ts

@@ -7,10 +7,11 @@
  * directory is not somewhere it would guess, and the VS Code editor that knows
  * both is reachable only by a human with a mouse.
  *
- * A tool rather than a skill because skills have to be installed by hand --
- * `resolveSkillsConfigSearchPaths` looks only in the workspace and the Cline
- * data directory -- so a skill that teaches this would need the user to already
- * know the thing it was going to tell them.
+ * A tool rather than a skill because, when this was written, skills had to be
+ * installed by hand, so a skill that taught this would have needed the user to
+ * already know the thing it was going to tell them. Skills can ship with the
+ * product now (`bundled-skills.ts`); the tool stays, since it also writes the
+ * file.
  */
 import { type AgentTool } from "@cerebriline/shared";
 import { z } from "zod";