praana 0.5.0

package/dist/tools/index.js

@@ -0,0 +1,86 @@
+import { createMemoryTools } from "./memory.js";
+import { createKnowledgeTools } from "./knowledge.js";
+import { createSystemTools } from "./system.js";
+import { createSearchCodeTool } from "./search-code.js";
+export function createAllTools(ctx) {
+    const classicMode = ctx.classicMode ?? false;
+    const memoryTools = createMemoryTools({
+        eventLog: ctx.eventLog,
+        stateGraph: ctx.stateGraph,
+        includeWorkingMemoryTools: !classicMode,
+        searchTurnEvents: ctx.contextEngine
+            ? (query, limit, currentTurn) => ctx.contextEngine.searchTurnEvents(query, limit, currentTurn ?? ctx.getCurrentTurn?.() ?? 0)
+            : undefined,
+    });
+    const knowledgeTools = createKnowledgeTools({
+        eventLog: ctx.eventLog,
+        memoryStore: ctx.memoryStore,
+        memoryEnabled: ctx.memoryEnabled,
+        incognito: ctx.incognito,
+        contextEngine: ctx.contextEngine,
+        getCurrentTurn: ctx.getCurrentTurn ?? (() => 0),
+    });
+    const systemTools = createSystemTools({
+        cwd: ctx.cwd,
+        getAbortSignal: ctx.getAbortSignal,
+        sandbox: ctx.sandbox,
+        editConfirm: ctx.editConfirm,
+    });
+    const searchCodeTools = createSearchCodeTool({
+        cwd: ctx.cwd,
+        getAbortSignal: ctx.getAbortSignal,
+        sandbox: ctx.sandbox,
+        rgPath: ctx.searchCode?.rg_path,
+    });
+    return {
+        ...memoryTools,
+        ...knowledgeTools,
+        ...systemTools,
+        ...searchCodeTools,
+    };
+}
+const WORKING_MEMORY_TOOL_DESCRIPTIONS = [
+    "create_task(title, description?) — Create a new task",
+    "complete_task(id) — Mark a task as done",
+    "retract_task(id) — Retract a task/object from working memory (tombstone)",
+    "add_constraint(text) — Add a constraint",
+    "decide(summary, rationale) — Record a decision",
+    "add_note(text) — Add a note",
+    "soft_unload(id) — Demote object to soft tier",
+    "hard_unload(id) — Demote object to hard tier",
+    "hydrate(id) — Promote object back to active",
+    "list_state() — List all state objects",
+    "focus_task(id) — Pin a task/object as current focus",
+];
+const SHARED_TOOL_DESCRIPTIONS = [
+    "search_session_log(query, kinds?, limit?) — Search current session event log (not cross-session recall)",
+    "read_and_summarize(path) — Read file and return structured summary (exports, imports, metrics)",
+    "recall(query, mode?, kinds?) — Search cross-session memory",
+    "remember(content, kind?, certainty?, scope?) — Store in cross-session memory (kinds: fact, preference, decision, pattern, mistake, constraint)",
+    "forget_memory(id) — Retract a cross-session memory entry (tombstone)",
+    "shell(command, timeout?) — Execute a shell command",
+    "read_file(path, offset?, limit?) — Read a file",
+    "write_file(path, content) — Write or overwrite a file",
+    "edit_file(path, oldText, newText) — Replace text in a file",
+    "batch_write(files) — Write multiple files atomically",
+    "batch_edit(edits) — Edit multiple files atomically",
+    "search_code(pattern, path?, glob?, glob_exclude?, case_insensitive?, context?, max_results?, file_type?, include_hidden?, no_ignore?, multiline?, timeout?) — Structured ripgrep-backed code search (file:line:column matches with context and stats)",
+];
+const ENGINE_TOOL_DESCRIPTIONS = [
+    "search_turn_events(query, limit?) — BM25 search over structured turn ledger",
+    'retrieve_artifact(id, grep?, lineStart?, lineEnd?, jsonPath?) — Retrieve full raw content for a stored tool-output artifact',
+    "context_summary() — Current session checkpoint, open errors, and recent activity",
+    "event_lineage(artifactId) — Trace artifact provenance, related decisions, and linked artifacts/files",
+];
+/** Build a human-readable list of tool descriptions for the system prompt. */
+export function describeTools(options) {
+    const classicMode = options?.classicMode ?? options?.contextEngineEnabled === false;
+    if (classicMode) {
+        return [...SHARED_TOOL_DESCRIPTIONS];
+    }
+    const tools = [...WORKING_MEMORY_TOOL_DESCRIPTIONS, ...SHARED_TOOL_DESCRIPTIONS];
+    if (options?.contextEngineEnabled) {
+        tools.push(...ENGINE_TOOL_DESCRIPTIONS);
+    }
+    return tools;
+}

package/dist/tools/knowledge.d.ts

@@ -0,0 +1,140 @@
+import type { MemoryStore } from "../memory/index.js";
+import type { EventLog } from "../event-log.js";
+import type { ContextEngine } from "../context-engine/index.js";
+export interface KnowledgeToolContext {
+    eventLog: EventLog;
+    memoryStore: MemoryStore | null;
+    memoryEnabled: boolean;
+    incognito: boolean;
+    contextEngine: ContextEngine | null;
+    getCurrentTurn: () => number;
+}
+export declare function createKnowledgeTools(ctx: KnowledgeToolContext): {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage: import("./tool-def.js").ToolDefinition;
+    retrieve_artifact: import("./tool-def.js").ToolDefinition;
+    context_summary: import("./tool-def.js").ToolDefinition;
+    search_turn_events: import("./tool-def.js").ToolDefinition;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage?: undefined;
+    retrieve_artifact: import("./tool-def.js").ToolDefinition;
+    context_summary: import("./tool-def.js").ToolDefinition;
+    search_turn_events: import("./tool-def.js").ToolDefinition;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage: import("./tool-def.js").ToolDefinition;
+    retrieve_artifact?: undefined;
+    context_summary: import("./tool-def.js").ToolDefinition;
+    search_turn_events: import("./tool-def.js").ToolDefinition;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage?: undefined;
+    retrieve_artifact?: undefined;
+    context_summary: import("./tool-def.js").ToolDefinition;
+    search_turn_events: import("./tool-def.js").ToolDefinition;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage: import("./tool-def.js").ToolDefinition;
+    retrieve_artifact: import("./tool-def.js").ToolDefinition;
+    context_summary?: undefined;
+    search_turn_events: import("./tool-def.js").ToolDefinition;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage?: undefined;
+    retrieve_artifact: import("./tool-def.js").ToolDefinition;
+    context_summary?: undefined;
+    search_turn_events: import("./tool-def.js").ToolDefinition;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage: import("./tool-def.js").ToolDefinition;
+    retrieve_artifact?: undefined;
+    context_summary?: undefined;
+    search_turn_events: import("./tool-def.js").ToolDefinition;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage?: undefined;
+    retrieve_artifact?: undefined;
+    context_summary?: undefined;
+    search_turn_events: import("./tool-def.js").ToolDefinition;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage: import("./tool-def.js").ToolDefinition;
+    retrieve_artifact: import("./tool-def.js").ToolDefinition;
+    context_summary: import("./tool-def.js").ToolDefinition;
+    search_turn_events?: undefined;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage?: undefined;
+    retrieve_artifact: import("./tool-def.js").ToolDefinition;
+    context_summary: import("./tool-def.js").ToolDefinition;
+    search_turn_events?: undefined;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage: import("./tool-def.js").ToolDefinition;
+    retrieve_artifact?: undefined;
+    context_summary: import("./tool-def.js").ToolDefinition;
+    search_turn_events?: undefined;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage?: undefined;
+    retrieve_artifact?: undefined;
+    context_summary: import("./tool-def.js").ToolDefinition;
+    search_turn_events?: undefined;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage: import("./tool-def.js").ToolDefinition;
+    retrieve_artifact: import("./tool-def.js").ToolDefinition;
+    context_summary?: undefined;
+    search_turn_events?: undefined;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage?: undefined;
+    retrieve_artifact: import("./tool-def.js").ToolDefinition;
+    context_summary?: undefined;
+    search_turn_events?: undefined;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage: import("./tool-def.js").ToolDefinition;
+    retrieve_artifact?: undefined;
+    context_summary?: undefined;
+    search_turn_events?: undefined;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+} | {
+    forget_memory: import("./tool-def.js").ToolDefinition;
+    event_lineage?: undefined;
+    retrieve_artifact?: undefined;
+    context_summary?: undefined;
+    search_turn_events?: undefined;
+    recall: import("./tool-def.js").ToolDefinition;
+    remember: import("./tool-def.js").ToolDefinition;
+};

package/dist/tools/knowledge.js

@@ -0,0 +1,260 @@
+import { defineTool } from "./tool-def.js";
+import { z } from "zod";
+export function createKnowledgeTools(ctx) {
+    const { eventLog, memoryStore, memoryEnabled, incognito, contextEngine, getCurrentTurn } = ctx;
+    const searchTurnEvents = contextEngine
+        ? {
+            search_turn_events: defineTool({
+                description: "Search the structured turn ledger for this session using BM25 ranking. " +
+                    "Returns turn summaries with artifact IDs, files touched, and errors — faster than scanning raw events.jsonl.",
+                parameters: z.object({
+                    query: z.string().describe("Search query"),
+                    limit: z
+                        .number()
+                        .int()
+                        .min(1)
+                        .max(50)
+                        .default(20)
+                        .describe("Max matches to return"),
+                }),
+                execute: async ({ query, limit }) => {
+                    const matches = contextEngine.searchTurnEvents(query, limit ?? 20, getCurrentTurn());
+                    eventLog.append({
+                        kind: "system_note",
+                        actor: "kernel",
+                        payload: {
+                            type: "turn_ledger_search",
+                            query,
+                            hits: matches.length,
+                        },
+                    });
+                    return {
+                        ok: true,
+                        query,
+                        matchCount: matches.length,
+                        matches,
+                    };
+                },
+            }),
+        }
+        : {};
+    const contextSummary = contextEngine
+        ? {
+            context_summary: defineTool({
+                description: "Return the current session checkpoint summary: active intent, recent decisions, open errors, and recent activity.",
+                parameters: z.object({}),
+                execute: async () => {
+                    const summary = contextEngine.renderContextSummary();
+                    eventLog.append({
+                        kind: "system_note",
+                        actor: "kernel",
+                        payload: { type: "context_summary" },
+                    });
+                    return { ok: true, summary };
+                },
+            }),
+        }
+        : {};
+    const retrieveArtifact = contextEngine
+        ? {
+            retrieve_artifact: defineTool({
+                description: "Retrieve the full raw content of a stored tool-output artifact by ID. Use when an artifact card in the prompt is insufficient.",
+                parameters: z.object({
+                    id: z.string().describe("Artifact ID (e.g. art_abc123def456)"),
+                    grep: z.string().optional().describe("Keep only lines matching this regex"),
+                    lineStart: z.number().int().positive().optional().describe("First line to return (1-based)"),
+                    lineEnd: z.number().int().positive().optional().describe("Last line to return (1-based)"),
+                    jsonPath: z.string().optional().describe("Extract a value from JSON content (dot-separated path)"),
+                }),
+                execute: async ({ id, grep, lineStart, lineEnd, jsonPath }) => {
+                    const retrieved = contextEngine.retrieveArtifact(id, getCurrentTurn(), {
+                        grep,
+                        lineStart,
+                        lineEnd,
+                        jsonPath,
+                    });
+                    if (!retrieved.ok) {
+                        return { ok: false, error: retrieved.error };
+                    }
+                    eventLog.append({
+                        kind: "system_note",
+                        actor: "kernel",
+                        payload: {
+                            type: "artifact_retrieve",
+                            id,
+                            grep: grep ?? null,
+                            lineStart: lineStart ?? null,
+                            lineEnd: lineEnd ?? null,
+                            jsonPath: jsonPath ?? null,
+                        },
+                    });
+                    return { ok: true, id, content: retrieved.content };
+                },
+            }),
+        }
+        : {};
+    const eventLineage = contextEngine
+        ? {
+            event_lineage: defineTool({
+                description: "Trace an artifact back to the turn, tool call, decisions, and related artifacts/files that produced or used it.",
+                parameters: z.object({
+                    artifactId: z.string().describe("Artifact ID (e.g. art_abc123def456)"),
+                }),
+                execute: async ({ artifactId }) => {
+                    const result = contextEngine.eventLineage(artifactId, getCurrentTurn());
+                    if (!result.ok) {
+                        return { ok: false, error: result.error };
+                    }
+                    eventLog.append({
+                        kind: "system_note",
+                        actor: "kernel",
+                        payload: {
+                            type: "event_lineage",
+                            artifactId,
+                            producedTurn: result.lineage.producedTurn,
+                        },
+                    });
+                    return {
+                        ok: true,
+                        lineage: result.lineage,
+                        text: result.text,
+                    };
+                },
+            }),
+        }
+        : {};
+    return {
+        recall: defineTool({
+            description: "Search your cross-session memory for past learnings, decisions, preferences, or patterns. Use when you need context from previous sessions.",
+            parameters: z.object({
+                query: z.string().describe("Search query"),
+                mode: z
+                    .enum(["standard", "causal_chain"])
+                    .optional()
+                    .describe("Search mode"),
+                kinds: z
+                    .array(z.string())
+                    .optional()
+                    .describe("Filter by kinds (fact, preference, decision, pattern, mistake, constraint)"),
+            }),
+            execute: async ({ query, kinds }) => {
+                if (!memoryEnabled || !memoryStore) {
+                    return {
+                        ok: false,
+                        error: incognito
+                            ? "Incognito mode is active — cross-session memory is disabled for this session."
+                            : "Cross-session memory is not available.",
+                    };
+                }
+                try {
+                    const result = await memoryStore.recall(query, { limit: 10, kinds: kinds });
+                    eventLog.append({
+                        kind: "system_note",
+                        actor: "kernel",
+                        payload: {
+                            type: "memory_recall",
+                            query,
+                            hits: result.entries.length,
+                        },
+                    });
+                    if (result.entries.length === 0) {
+                        return {
+                            ok: true,
+                            entries: [],
+                            note: "No cross-session matches. If this was discussed earlier in this same session, use search_session_log(query, kinds?, limit?) to recover it from events.jsonl.",
+                        };
+                    }
+                    return { ok: true, entries: result.entries };
+                }
+                catch (err) {
+                    const message = err?.message ?? "Recall failed";
+                    return {
+                        ok: false,
+                        error: `${message}. For same-session history, use search_session_log(query, kinds?, limit?) instead of recall.`,
+                    };
+                }
+            },
+        }),
+        remember: defineTool({
+            description: "Store a fact, preference, decision, mistake, or pattern in your cross-session memory for future sessions.",
+            parameters: z.object({
+                content: z.string().describe("What to remember"),
+                kind: z
+                    .enum(["preference", "context_fact", "decision", "mistake", "pattern", "fact", "constraint"])
+                    .optional()
+                    .describe("Type of knowledge"),
+                certainty: z
+                    .enum(["high", "medium", "low"])
+                    .optional()
+                    .describe("How certain you are"),
+                scope: z
+                    .array(z.string())
+                    .optional()
+                    .describe("Scope labels to isolate this memory (e.g. ['context:my-project']). Defaults to automatic scopes."),
+            }),
+            execute: async ({ content, kind, certainty, scope }) => {
+                if (!memoryEnabled || !memoryStore) {
+                    return {
+                        ok: false,
+                        error: incognito
+                            ? "Incognito mode is active — cross-session memory writes are disabled."
+                            : "Cross-session memory is not available.",
+                    };
+                }
+                try {
+                    // Map bodha-style kinds to our kinds
+                    const mappedKind = kind === "context_fact" ? "fact" :
+                        kind ?? "fact";
+                    const result = await memoryStore.remember(content, {
+                        kind: mappedKind,
+                        certainty: certainty ?? "medium",
+                        scope: scope ?? undefined,
+                    });
+                    return { ok: true, id: result.id };
+                }
+                catch (err) {
+                    return { ok: false, error: err?.message ?? "Remember failed" };
+                }
+            },
+        }),
+        ...searchTurnEvents,
+        ...contextSummary,
+        ...retrieveArtifact,
+        ...eventLineage,
+        forget_memory: defineTool({
+            description: "Retract (tombstone) a cross-session memory entry. The memory is excluded from future recall and digest, but retained for audit.",
+            parameters: z.object({
+                id: z.string().describe("Memory entry ID to retract"),
+            }),
+            execute: async ({ id }) => {
+                if (incognito) {
+                    return {
+                        ok: false,
+                        error: "Memory is disabled in incognito mode.",
+                    };
+                }
+                if (!memoryEnabled || !memoryStore) {
+                    return {
+                        ok: false,
+                        error: "Cross-session memory is not available.",
+                    };
+                }
+                try {
+                    if (!memoryStore.hasEntry(id)) {
+                        return { ok: false, error: `Memory ${id} not found` };
+                    }
+                    memoryStore.retractMemory(id);
+                    eventLog.append({
+                        kind: "system_note",
+                        actor: "kernel",
+                        payload: { type: "memory_forget", id },
+                    });
+                    return { ok: true, id };
+                }
+                catch (err) {
+                    return { ok: false, error: err?.message ?? "Forget failed" };
+                }
+            },
+        }),
+    };
+}

package/dist/tools/memory.d.ts

@@ -0,0 +1,39 @@
+import type { EventLog } from "../event-log.js";
+import type { StateGraph } from "../state-graph.js";
+import type { TurnSearchMatch } from "../context-engine/types.js";
+export interface MemoryToolContext {
+    eventLog: EventLog;
+    stateGraph: StateGraph;
+    searchTurnEvents?: (query: string, limit?: number, currentTurn?: number) => TurnSearchMatch[];
+    /** false in classic mode — StateGraph tools are not registered. */
+    includeWorkingMemoryTools?: boolean;
+}
+export declare function createMemoryTools(ctx: MemoryToolContext): {
+    search_session_log: import("./tool-def.js").ToolDefinition;
+    create_task: import("./tool-def.js").ToolDefinition;
+    complete_task: import("./tool-def.js").ToolDefinition;
+    retract_task: import("./tool-def.js").ToolDefinition;
+    add_constraint: import("./tool-def.js").ToolDefinition;
+    decide: import("./tool-def.js").ToolDefinition;
+    add_note: import("./tool-def.js").ToolDefinition;
+    soft_unload: import("./tool-def.js").ToolDefinition;
+    hard_unload: import("./tool-def.js").ToolDefinition;
+    hydrate: import("./tool-def.js").ToolDefinition;
+    list_state: import("./tool-def.js").ToolDefinition;
+    focus_task: import("./tool-def.js").ToolDefinition;
+} | {
+    search_session_log: import("./tool-def.js").ToolDefinition;
+    create_task?: undefined;
+    complete_task?: undefined;
+    retract_task?: undefined;
+    add_constraint?: undefined;
+    decide?: undefined;
+    add_note?: undefined;
+    soft_unload?: undefined;
+    hard_unload?: undefined;
+    hydrate?: undefined;
+    list_state?: undefined;
+    focus_task?: undefined;
+};
+/** Warn when a note looks like an activity log instead of a semantic finding. */
+export declare function detectActivityLogNote(text: string): string | null;