praana 0.5.0

package/dist/tools/memory.js

@@ -0,0 +1,300 @@
+import { defineTool } from "./tool-def.js";
+import { z } from "zod";
+export function createMemoryTools(ctx) {
+    const { eventLog, stateGraph, searchTurnEvents } = ctx;
+    const includeWorkingMemory = ctx.includeWorkingMemoryTools !== false;
+    const logAction = (action, payload) => {
+        eventLog.append({
+            kind: "context_action",
+            actor: "kernel",
+            payload: { action, ...payload },
+        });
+    };
+    const workingMemoryTools = includeWorkingMemory
+        ? {
+            create_task: defineTool({
+                description: "Create a new task in working memory. Tasks track what you're working on.",
+                parameters: z.object({
+                    title: z.string().describe("Task title"),
+                    description: z.string().optional().describe("Optional details"),
+                }),
+                execute: async ({ title, description }) => {
+                    const obj = stateGraph.create("task", {
+                        title,
+                        description,
+                        status: "todo",
+                    });
+                    logAction("create", {
+                        id: obj.id,
+                        kind: "task",
+                        tier: obj.tier,
+                        statePayload: obj.payload,
+                        created: obj.created,
+                        updated: obj.updated,
+                        lastTouched: obj.lastTouched,
+                    });
+                    return { ok: true, id: obj.id };
+                },
+            }),
+            complete_task: defineTool({
+                description: "Mark a task as done. Use when you've completed a task.",
+                parameters: z.object({
+                    id: z.string().describe("Task ID to complete"),
+                }),
+                execute: async ({ id }) => {
+                    const obj = stateGraph.get(id);
+                    if (!obj || obj.kind !== "task") {
+                        return { ok: false, error: `Task ${id} not found` };
+                    }
+                    const updated = stateGraph.update(id, { status: "done" });
+                    if (updated) {
+                        logAction("update", {
+                            id,
+                            statePayload: { status: "done" },
+                            updated: updated.updated,
+                            lastTouched: updated.lastTouched,
+                        });
+                    }
+                    // Auto-soft-unload on complete_task
+                    stateGraph.setTier(id, "soft");
+                    logAction("setTier", {
+                        id,
+                        tier: "soft",
+                        lastTouched: stateGraph.get(id).lastTouched,
+                    });
+                    return { ok: true };
+                },
+            }),
+            retract_task: defineTool({
+                description: "Retract a task from working memory. The task is tombstoned (not deleted) so it won't appear in prompts or state listings.",
+                parameters: z.object({
+                    id: z.string().describe("Task/object ID to retract"),
+                }),
+                execute: async ({ id }) => {
+                    const obj = stateGraph.get(id);
+                    if (!obj) {
+                        return { ok: false, error: `Object ${id} not found` };
+                    }
+                    const retracted = stateGraph.retractObject(id);
+                    if (retracted) {
+                        logAction("retract", { id, kind: obj.kind });
+                    }
+                    return { ok: true, retracted };
+                },
+            }),
+            add_constraint: defineTool({
+                description: "Add a constraint to working memory. Use for rules, limitations, or requirements to keep in mind.",
+                parameters: z.object({
+                    text: z.string().describe("The constraint text"),
+                }),
+                execute: async ({ text }) => {
+                    const obj = stateGraph.create("constraint", { text });
+                    logAction("create", {
+                        id: obj.id,
+                        kind: "constraint",
+                        tier: obj.tier,
+                        statePayload: obj.payload,
+                        created: obj.created,
+                        updated: obj.updated,
+                        lastTouched: obj.lastTouched,
+                    });
+                    return { ok: true, id: obj.id };
+                },
+            }),
+            decide: defineTool({
+                description: "Record a decision in working memory with its rationale.",
+                parameters: z.object({
+                    summary: z.string().describe("Short summary of the decision"),
+                    rationale: z.string().describe("Why this decision was made"),
+                }),
+                execute: async ({ summary, rationale }) => {
+                    const obj = stateGraph.create("decision", {
+                        summary,
+                        rationale,
+                    });
+                    logAction("create", {
+                        id: obj.id,
+                        kind: "decision",
+                        tier: obj.tier,
+                        statePayload: obj.payload,
+                        created: obj.created,
+                        updated: obj.updated,
+                        lastTouched: obj.lastTouched,
+                    });
+                    return { ok: true, id: obj.id };
+                },
+            }),
+            add_note: defineTool({
+                description: "Add a general note to working memory. Capture semantic findings (facts, behavior, decisions) — not activity logs or file lists. After significant analysis, add notes immediately so findings survive context truncation.",
+                parameters: z.object({
+                    text: z.string().describe("The note text — a finding or fact, not a list of files read"),
+                }),
+                execute: async ({ text }) => {
+                    const qualityWarning = detectActivityLogNote(text);
+                    const obj = stateGraph.create("note", { text });
+                    logAction("create", {
+                        id: obj.id,
+                        kind: "note",
+                        tier: obj.tier,
+                        statePayload: obj.payload,
+                        created: obj.created,
+                        updated: obj.updated,
+                        lastTouched: obj.lastTouched,
+                    });
+                    return qualityWarning
+                        ? { ok: true, id: obj.id, warning: qualityWarning }
+                        : { ok: true, id: obj.id };
+                },
+            }),
+            soft_unload: defineTool({
+                description: "Demote a state object to the soft tier (shown as one-line stub in memory). Use when something is less relevant now.",
+                parameters: z.object({
+                    id: z.string().describe("Object ID to demote"),
+                }),
+                execute: async ({ id }) => {
+                    const obj = stateGraph.get(id);
+                    if (!obj)
+                        return { ok: false, error: `Object ${id} not found` };
+                    stateGraph.setTier(id, "soft");
+                    logAction("setTier", {
+                        id,
+                        tier: "soft",
+                        lastTouched: stateGraph.get(id).lastTouched,
+                    });
+                    return { ok: true };
+                },
+            }),
+            hard_unload: defineTool({
+                description: "Demote a state object to the hard tier (shown as minimal anchor in memory). Use when something is even less relevant.",
+                parameters: z.object({
+                    id: z.string().describe("Object ID to demote to hard"),
+                }),
+                execute: async ({ id }) => {
+                    const obj = stateGraph.get(id);
+                    if (!obj)
+                        return { ok: false, error: `Object ${id} not found` };
+                    stateGraph.setTier(id, "hard");
+                    logAction("setTier", {
+                        id,
+                        tier: "hard",
+                        lastTouched: stateGraph.get(id).lastTouched,
+                    });
+                    return { ok: true };
+                },
+            }),
+            hydrate: defineTool({
+                description: "Promote a peripheral (soft/hard) object back to active memory, restoring its full content.",
+                parameters: z.object({
+                    id: z.string().describe("Object ID to hydrate"),
+                }),
+                execute: async ({ id }) => {
+                    const obj = stateGraph.get(id);
+                    if (!obj)
+                        return { ok: false, error: `Object ${id} not found` };
+                    stateGraph.setTier(id, "active");
+                    logAction("setTier", {
+                        id,
+                        tier: "active",
+                        lastTouched: stateGraph.get(id).lastTouched,
+                    });
+                    return { ok: true, payload: obj.payload };
+                },
+            }),
+            list_state: defineTool({
+                description: "List all state objects with their id, kind, tier, and summary.",
+                parameters: z.object({}),
+                execute: async () => {
+                    const objects = stateGraph.list();
+                    return { ok: true, objects };
+                },
+            }),
+            focus_task: defineTool({
+                description: "Pin a task (or any state object) as the current focus. Focused objects render first in active state.",
+                parameters: z.object({
+                    id: z.string().describe("Object ID to focus"),
+                }),
+                execute: async ({ id }) => {
+                    const obj = stateGraph.get(id);
+                    if (!obj)
+                        return { ok: false, error: `Object ${id} not found` };
+                    stateGraph.setFocus(id);
+                    logAction("setFocus", {
+                        id,
+                        lastTouched: stateGraph.get(id).lastTouched,
+                    });
+                    return { ok: true, id };
+                },
+            }),
+        }
+        : {};
+    return {
+        ...workingMemoryTools,
+        search_session_log: defineTool({
+            description: "Search the current session's event log for earlier messages, tool calls, and results. " +
+                "Use this to recover in-session context (e.g. a code review from earlier turns) — not recall, which only searches cross-session memory. " +
+                "Session log path: events.jsonl",
+            parameters: z.object({
+                query: z
+                    .string()
+                    .describe("Search terms (ANDed, case-insensitive). Use | for OR, e.g. 'issue|review'"),
+                kinds: z
+                    .array(z.enum([
+                    "user_message",
+                    "agent_message",
+                    "tool_call",
+                    "tool_result",
+                    "context_action",
+                    "system_note",
+                ]))
+                    .optional()
+                    .describe("Optional event kinds to filter"),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(50)
+                    .default(20)
+                    .describe("Max matches to return"),
+            }),
+            execute: async ({ query, kinds, limit }) => {
+                if (searchTurnEvents && !kinds?.length) {
+                    const ledgerMatches = searchTurnEvents(query, limit ?? 20);
+                    return {
+                        ok: true,
+                        query,
+                        source: "turn_ledger",
+                        matchCount: ledgerMatches.length,
+                        matches: ledgerMatches,
+                    };
+                }
+                const matches = eventLog.search(query, { kinds, limit: limit ?? 20 });
+                return {
+                    ok: true,
+                    query,
+                    source: "event_log",
+                    matchCount: matches.length,
+                    matches: matches.map(({ event, excerpt }) => ({
+                        event_id: event.event_id,
+                        kind: event.kind,
+                        actor: event.actor,
+                        timestamp: event.timestamp,
+                        excerpt,
+                    })),
+                };
+            },
+        }),
+    };
+}
+/** Warn when a note looks like an activity log instead of a semantic finding. */
+export function detectActivityLogNote(text) {
+    const trimmed = text.trim();
+    if (trimmed.length < 20)
+        return null;
+    const fileListPattern = /(?:read|analyzed|reviewed|checked).{0,40}(?:src\/|\b[\w.-]+\.(?:ts|js|tsx|jsx|py|go|rs)\b)/i;
+    const commaFileRun = /(?:src\/[\w./-]+(?:,\s*|\s+and\s+)){2,}/i;
+    const lacksFindingLanguage = !/\b(uses|implements|returns|calls|handles|because|found|decided|pattern|via|is a|are stored)\b/i.test(trimmed);
+    if ((fileListPattern.test(trimmed) || commaFileRun.test(trimmed)) && lacksFindingLanguage) {
+        return "This note looks like an activity log. Prefer a semantic finding (what you learned), not which files you read.";
+    }
+    return null;
+}

package/dist/tools/search-code.d.ts

@@ -0,0 +1,134 @@
+import { z } from "zod";
+import type { SandboxConfig } from "../types.js";
+/**
+ * search_code — ripgrep-backed structured code search.
+ *
+ * Wraps `rg --json` with a stable JSON contract the model can consume:
+ *   { matches: [{ file, line, column, text, context_before, context_after }],
+ *     stats:   { totalMatches, filesWithMatches, truncated } }
+ *
+ * rg is resolved from the inherited PATH by default; an override is accepted
+ * for tests and packaged-binary scenarios.
+ */
+export interface SearchCodeMatch {
+    file: string;
+    line: number;
+    column: number;
+    text: string;
+    context_before: string[];
+    context_after: string[];
+}
+export interface SearchCodeStats {
+    totalMatches: number;
+    filesWithMatches: number;
+    truncated: boolean;
+    /** Minimum number of matches dropped due to `max_results`. 0 when not truncated. */
+    dropped: number;
+}
+export interface SearchCodeSuccess {
+    ok: true;
+    pattern: string;
+    path: string;
+    matches: SearchCodeMatch[];
+    stats: SearchCodeStats;
+    duration_ms: number;
+}
+export interface SearchCodeError {
+    ok: false;
+    error: string;
+}
+export type SearchCodeResult = SearchCodeSuccess | SearchCodeError;
+export interface SearchCodeToolContext {
+    cwd: string;
+    getAbortSignal?: () => AbortSignal | undefined;
+    sandbox?: SandboxConfig;
+    /** Override ripgrep binary path (default: "rg" via PATH lookup). */
+    rgPath?: string;
+}
+declare const searchCodeSchema: z.ZodObject<{
+    pattern: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    glob: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    glob_exclude: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    case_insensitive: z.ZodOptional<z.ZodBoolean>;
+    context: z.ZodOptional<z.ZodNumber>;
+    max_results: z.ZodOptional<z.ZodNumber>;
+    file_type: z.ZodOptional<z.ZodString>;
+    include_hidden: z.ZodOptional<z.ZodBoolean>;
+    no_ignore: z.ZodOptional<z.ZodBoolean>;
+    multiline: z.ZodOptional<z.ZodBoolean>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    pattern: string;
+    path?: string | undefined;
+    timeout?: number | undefined;
+    glob?: string | string[] | undefined;
+    glob_exclude?: string | string[] | undefined;
+    case_insensitive?: boolean | undefined;
+    context?: number | undefined;
+    max_results?: number | undefined;
+    file_type?: string | undefined;
+    include_hidden?: boolean | undefined;
+    no_ignore?: boolean | undefined;
+    multiline?: boolean | undefined;
+}, {
+    pattern: string;
+    path?: string | undefined;
+    timeout?: number | undefined;
+    glob?: string | string[] | undefined;
+    glob_exclude?: string | string[] | undefined;
+    case_insensitive?: boolean | undefined;
+    context?: number | undefined;
+    max_results?: number | undefined;
+    file_type?: string | undefined;
+    include_hidden?: boolean | undefined;
+    no_ignore?: boolean | undefined;
+    multiline?: boolean | undefined;
+}>;
+export type SearchCodeArgs = z.infer<typeof searchCodeSchema>;
+/**
+ * Build the ripgrep argv for the given arguments.
+ *
+ * Pattern is passed as `--` then `pattern` so it can't be misinterpreted as
+ * a flag even if it starts with `-`.
+ */
+export declare function buildRipgrepArgs(args: SearchCodeArgs, searchPath: string): string[];
+/**
+ * Streaming ripgrep-JSON parser.
+ *
+ * The parser holds mutable state (matches array, per-file context map, last
+ * match in file) that the caller can feed events into incrementally. This
+ * lets `runRipgrep` parse as bytes arrive from rg's stdout rather than
+ * buffering every event in a `string[]` until the child closes — which
+ * previously grew linearly with match count and OOM'd on broad searches.
+ *
+ * Context events are accumulated into a per-file line map. For each match,
+ * the lines with `line_number ∈ [match.line - context, match.line + context]`
+ * populate `context_before` / `context_after`. The last match's "after"
+ * context is back-filled on the file's `end` event so trailing context
+ * lines aren't lost.
+ */
+export interface ParseState {
+    matches: SearchCodeMatch[];
+    totalMatches: number;
+    truncated: boolean;
+    _currentFile: string | null;
+    _currentFileLineMap: Map<number, string>;
+    _lastMatchInFile: SearchCodeMatch | null;
+}
+export declare function createParseState(): ParseState;
+/** Feed raw rg --json lines into the parse state. Triggers `onTruncate` on cap. */
+export declare function feedParseState(state: ParseState, rawLines: string[], context: number, maxResults: number | undefined, onTruncate: () => void): void;
+/** Convenience wrapper: feed a complete log at once. Used by tests. */
+export declare function parseRipgrepEvents(rawLines: string[], context: number, maxResults: number | undefined, onTruncate: () => void): {
+    matches: SearchCodeMatch[];
+    totalMatches: number;
+    filesWithMatches: number;
+    truncated: boolean;
+};
+/** Spawn ripgrep, return structured result. */
+export declare function runRipgrep(args: SearchCodeArgs, rgBin: string, cwd: string, sandbox: SandboxConfig | undefined, getAbortSignal?: () => AbortSignal | undefined): Promise<SearchCodeResult>;
+export declare function createSearchCodeTool(ctx: SearchCodeToolContext): {
+    search_code: import("./tool-def.js").ToolDefinition;
+};
+export {};