natroc 0.0.1

package/install.sh

@@ -0,0 +1,132 @@
+#!/bin/sh
+# Natroc installer — Unix / macOS / Linux / WSL
+#
+# Default:
+#   curl -fsSL https://natroc.ai/install.sh | sh
+#
+# Variants (set env BEFORE pipe):
+#   NATROC_INSTALL_METHOD=git    curl -fsSL .../install.sh | sh   # clone + build from source
+#   NATROC_INSTALL_METHOD=tarball NATROC_TARBALL_URL=URL ...      # install .tgz
+#   NATROC_INSTALL_DIR=$HOME/apps/natroc  ...                     # custom source dir (git mode)
+set -eu
+
+REQUIRED_NODE_MAJOR=24
+PACKAGE_NAME="natroc"
+GIT_REPO="https://github.com/Licentora/Natroc.git"
+INSTALL_DIR="${NATROC_INSTALL_DIR:-${HOME}/.natroc}"
+SRC_DIR="${INSTALL_DIR}/src"
+METHOD="${NATROC_INSTALL_METHOD:-npm}"
+
+# ----- helpers ---------------------------------------------------------------
+
+err() { printf 'Error: %s\n' "$1" >&2; }
+info() { printf '%s\n' "$1"; }
+
+require_cmd() {
+  if ! command -v "$1" >/dev/null 2>&1; then
+    err "$1 is required but not found in PATH."
+    [ -n "${2:-}" ] && err "$2"
+    exit 1
+  fi
+}
+
+# ----- OS / arch detection ---------------------------------------------------
+
+OS=unknown
+ARCH=$(uname -m 2>/dev/null || echo unknown)
+
+case "$(uname -s 2>/dev/null || echo unknown)" in
+  Darwin) OS=macos ;;
+  Linux)
+    if grep -qi microsoft /proc/version 2>/dev/null; then
+      OS=wsl
+    else
+      OS=linux
+    fi
+    ;;
+esac
+
+# ----- prerequisites ---------------------------------------------------------
+
+require_cmd node "Install Node.js ${REQUIRED_NODE_MAJOR}+ from https://nodejs.org and try again."
+NODE_VERSION=$(node -p "process.versions.node")
+NODE_MAJOR=$(printf '%s' "$NODE_VERSION" | cut -d. -f1)
+if [ "$NODE_MAJOR" -lt "$REQUIRED_NODE_MAJOR" ]; then
+  err "Node.js ${REQUIRED_NODE_MAJOR}+ required (found v${NODE_VERSION})."
+  err "Tip: nvm install ${REQUIRED_NODE_MAJOR} && nvm use ${REQUIRED_NODE_MAJOR}"
+  exit 1
+fi
+require_cmd npm
+
+info "Natroc installer"
+info "  OS: ${OS} (${ARCH})"
+info "  Node: v${NODE_VERSION}"
+info "  Method: ${METHOD}"
+info ""
+
+# ----- install methods -------------------------------------------------------
+
+install_npm() {
+  info "Installing ${PACKAGE_NAME} from the npm registry..."
+  if ! npm install -g "${PACKAGE_NAME}@latest"; then
+    err ""
+    err "npm install -g failed. Two common causes:"
+    err "  1. Package not published yet — try git mode:"
+    err "       NATROC_INSTALL_METHOD=git curl -fsSL https://natroc.ai/install.sh | sh"
+    err "  2. No write permission to global prefix — use a user-local prefix:"
+    err "       npm config set prefix \"\$HOME/.local\""
+    err "       export PATH=\"\$HOME/.local/bin:\$PATH\""
+    exit 1
+  fi
+}
+
+install_git() {
+  require_cmd git
+
+  if [ -d "${SRC_DIR}/.git" ]; then
+    info "Updating existing clone in ${SRC_DIR}..."
+    (cd "${SRC_DIR}" && git pull --ff-only)
+  else
+    info "Cloning ${GIT_REPO} into ${SRC_DIR}..."
+    mkdir -p "$(dirname "${SRC_DIR}")"
+    git clone --depth=1 "${GIT_REPO}" "${SRC_DIR}"
+  fi
+
+  info "Installing dependencies + building (this may take a minute)..."
+  (cd "${SRC_DIR}" && npm install && npm run all:build)
+
+  info "Linking 'natroc' bin globally (via npm link)..."
+  (cd "${SRC_DIR}" && npm link)
+}
+
+install_tarball() {
+  url="${NATROC_TARBALL_URL:-}"
+  if [ -z "$url" ]; then
+    err "Set NATROC_TARBALL_URL=<url-or-path-to-natroc-x.y.z.tgz> for tarball method."
+    exit 1
+  fi
+  info "Installing from tarball: ${url}"
+  npm install -g "${url}"
+}
+
+case "${METHOD}" in
+  npm)     install_npm ;;
+  git)     install_git ;;
+  tarball) install_tarball ;;
+  *)
+    err "Unknown NATROC_INSTALL_METHOD: ${METHOD}"
+    err "Valid values: npm | git | tarball"
+    exit 1
+    ;;
+esac
+
+# ----- post-install hint -----------------------------------------------------
+
+info ""
+info "Installed. Next steps:"
+info "  natroc setup                  # initialize ~/.natroc/"
+info "  natroc server                 # run gateway in the foreground"
+info "  natroc daemon install         # OR install as a system service"
+info "  natroc daemon status          # inspect the service"
+info ""
+info "Web UI + WebSocket: http://127.0.0.1:18789/"

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "natroc",
+  "version": "0.0.1",
+  "description": "Ultimate Personal AI Agent that can perform complex tasks and even become a Personal Assistant",
+  "type": "module",
+  "bin": {
+    "natroc": "./server/dist/cli.js"
+  },
+  "files": [
+    "server/dist",
+    "ui/dist",
+    "install.sh",
+    "install.ps1",
+    "PLAN.md",
+    "README.md",
+    "LICENSE",
+    "AGENTS.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "ui:clean": "rimraf ui/dist ui/node_modules ui/package-lock.json",
+    "ui:install": "cd ui && npm install",
+    "ui:build": "cd ui && npm run build",
+    "ui:dev": "cd ui && npm run dev",
+    "ui:typecheck": "cd ui && npm run typecheck",
+    "ui:lint": "cd ui && npm run lint",
+    "ui:format": "cd ui && npm run format",
+    "server:clean": "rimraf server/dist server/node_modules server/package-lock.json",
+    "server:install": "cd server && npm install",
+    "server:build": "cd server && npm run build",
+    "server:dev": "cd server && npm run dev",
+    "server:typecheck": "cd server && npm run typecheck",
+    "server:test": "cd server && npm run test",
+    "all:clean": "npm run ui:clean && npm run server:clean",
+    "all:install": "npm run ui:install && npm run server:install",
+    "all:build": "npm run ui:build && npm run server:build",
+    "prepublishOnly": "npm run all:install && npm run all:build"
+  },
+  "dependencies": {
+    "@fastify/cors": "^11.2.0",
+    "@fastify/websocket": "^11.2.0",
+    "@openrouter/agent": "^0.7.0",
+    "@openrouter/sdk": "^0.12.35",
+    "@whiskeysockets/baileys": "^6.7.23",
+    "fastify": "^5.8.5",
+    "grammy": "^1.43.0",
+    "ollama": "^0.6.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "rimraf": "^6.1.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Licentora/Natroc.git"
+  },
+  "keywords": [
+    "Natroc",
+    "AI Agent",
+    "Personal Assistant",
+    "Artificial Intelligence",
+    "Task Automation",
+    "Productivity",
+    "Machine Learning",
+    "Natural Language Processing",
+    "Deep Learning",
+    "Intelligent Agent"
+  ],
+  "author": "Licentora <support@licentora.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Licentora/Natroc/issues"
+  },
+  "homepage": "https://github.com/Licentora/Natroc#readme"
+}

package/server/dist/agent/agent-loop.d.ts

@@ -0,0 +1,71 @@
+import type { ProviderAdapter, ProviderChatMessage, ProviderUsage, ProviderThinkingRequest, ProviderName } from "../providers/types.js";
+import type { ToolContext, ToolMode, ToolRisk } from "./tools/types.js";
+export type AgentToolCallRecord = {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    risk: ToolRisk;
+    status: "ok" | "error";
+    output: string;
+};
+export type AgentLoopEvent = {
+    type: "metadata";
+    provider: ProviderName;
+    model: string;
+} | {
+    type: "step";
+    index: number;
+} | {
+    type: "text";
+    delta: string;
+} | {
+    type: "reasoning";
+    delta: string;
+} | {
+    type: "tool_call";
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    risk: ToolRisk;
+} | {
+    type: "tool_result";
+    id: string;
+    status: "ok" | "error";
+    output: string;
+} | {
+    type: "done";
+    content: string;
+    model: string;
+    toolCalls: AgentToolCallRecord[];
+    usage: ProviderUsage[];
+} | {
+    type: "error";
+    error: string;
+};
+export type AgentLoopInput = {
+    adapter: ProviderAdapter;
+    provider: ProviderName;
+    baseSystemPrompt: string;
+    history: ProviderChatMessage[];
+    userMessage: string;
+    model?: string;
+    thinking?: ProviderThinkingRequest;
+    mode: ToolMode;
+    context: ToolContext;
+    maxIterations?: number;
+};
+/**
+ * Runs the agentic ReAct loop: the model is asked to either call a tool (by
+ * replying with a JSON object) or to give a final plain-text answer. Tool calls
+ * are executed and their results fed back until the model produces a final
+ * answer or the iteration cap is reached.
+ */
+export declare function runAgentLoop(input: AgentLoopInput): AsyncGenerator<AgentLoopEvent>;
+/**
+ * Detects a tool call inside a model reply. Returns null when the reply is a
+ * plain-text answer (no JSON object with a `tool` field).
+ */
+export declare function parseToolCall(text: string): {
+    name: string;
+    args: Record<string, unknown>;
+} | null;

package/server/dist/agent/agent-loop.js

@@ -0,0 +1,171 @@
+import { buildToolsPrompt, executeTool, findTool, getAvailableTools, } from "./tools/index.js";
+const DEFAULT_MAX_ITERATIONS = 8;
+const EMPTY_MODEL_RESPONSE_RETRY_PROMPT = [
+    "Your previous response contained no user-visible answer and no tool call.",
+    "Reply now with either a normal plain-text final answer for the user or exactly one JSON tool call using an available tool.",
+    "If the needed tool is unavailable, explain the limitation in plain text and answer as far as you can.",
+].join("\n");
+const MAX_ITERATIONS_MESSAGE = "I reached the maximum number of agent steps before producing a final answer. Please try again or narrow the request.";
+/**
+ * Runs the agentic ReAct loop: the model is asked to either call a tool (by
+ * replying with a JSON object) or to give a final plain-text answer. Tool calls
+ * are executed and their results fed back until the model produces a final
+ * answer or the iteration cap is reached.
+ */
+export async function* runAgentLoop(input) {
+    const tools = getAvailableTools(input.mode);
+    const systemPrompt = `${input.baseSystemPrompt}\n\n${buildToolsPrompt(tools)}`;
+    const maxIterations = input.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    const messages = [
+        { role: "system", content: systemPrompt },
+        ...input.history,
+        { role: "user", content: input.userMessage },
+    ];
+    const toolCalls = [];
+    const usage = [];
+    let lastModel = input.model ?? "";
+    for (let index = 0; index < maxIterations; index += 1) {
+        yield { type: "step", index };
+        let turnText = "";
+        try {
+            for await (const event of input.adapter.streamChat({
+                message: input.userMessage,
+                model: input.model,
+                messages,
+                thinking: input.thinking,
+            })) {
+                if (event.type === "metadata") {
+                    lastModel = event.model;
+                    yield {
+                        type: "metadata",
+                        provider: event.provider,
+                        model: event.model,
+                    };
+                    continue;
+                }
+                if (event.type === "text") {
+                    turnText += event.delta;
+                    yield { type: "text", delta: event.delta };
+                    continue;
+                }
+                if (event.type === "reasoning") {
+                    yield { type: "reasoning", delta: event.delta };
+                    continue;
+                }
+                if (event.type === "usage") {
+                    usage.push(event.usage);
+                }
+            }
+        }
+        catch (error) {
+            yield {
+                type: "error",
+                error: error instanceof Error ? error.message : "Model request failed.",
+            };
+            return;
+        }
+        const trimmedTurnText = turnText.trim();
+        if (!trimmedTurnText) {
+            messages.push({
+                role: "user",
+                content: EMPTY_MODEL_RESPONSE_RETRY_PROMPT,
+            });
+            continue;
+        }
+        const toolCall = parseToolCall(trimmedTurnText);
+        if (!toolCall) {
+            yield {
+                type: "done",
+                content: trimmedTurnText,
+                model: lastModel,
+                toolCalls,
+                usage,
+            };
+            return;
+        }
+        messages.push({ role: "assistant", content: trimmedTurnText });
+        const callId = crypto.randomUUID();
+        const risk = findTool(toolCall.name)?.risk ?? "high";
+        yield {
+            type: "tool_call",
+            id: callId,
+            name: toolCall.name,
+            args: toolCall.args,
+            risk,
+        };
+        const result = await executeTool(toolCall.name, toolCall.args, input.mode, input.context);
+        yield {
+            type: "tool_result",
+            id: callId,
+            status: result.ok ? "ok" : "error",
+            output: result.output,
+        };
+        toolCalls.push({
+            id: callId,
+            name: toolCall.name,
+            args: toolCall.args,
+            risk,
+            status: result.ok ? "ok" : "error",
+            output: result.output,
+        });
+        messages.push({
+            role: "user",
+            content: buildToolResultMessage(toolCall.name, result),
+        });
+    }
+    yield {
+        type: "done",
+        content: MAX_ITERATIONS_MESSAGE,
+        model: lastModel,
+        toolCalls,
+        usage,
+    };
+}
+function buildToolResultMessage(name, result) {
+    const status = result.ok ? "success" : "error";
+    const lines = [`Result of tool "${name}" (${status}):`, result.output];
+    if (!result.ok) {
+        lines.push("", "The tool did not complete successfully. Do not repeat the same failed tool call unless you change the approach. If you cannot continue without that tool, reply with a plain-text explanation for the user.");
+    }
+    return lines.join("\n");
+}
+/**
+ * Detects a tool call inside a model reply. Returns null when the reply is a
+ * plain-text answer (no JSON object with a `tool` field).
+ */
+export function parseToolCall(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return null;
+    const json = extractJsonObject(trimmed);
+    if (!json)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    const name = typeof parsed.tool === "string" ? parsed.tool.trim() : "";
+    if (!name)
+        return null;
+    const args = isRecord(parsed.args) ? parsed.args : {};
+    return { name, args };
+}
+function extractJsonObject(value) {
+    const fenced = value.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1];
+    const raw = (fenced ?? value).trim();
+    const first = raw.indexOf("{");
+    const last = raw.lastIndexOf("}");
+    if (first === -1 || last === -1 || last < first) {
+        return null;
+    }
+    return raw.slice(first, last + 1);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=agent-loop.js.map

package/server/dist/agent/agent-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-loop.js","sourceRoot":"","sources":["../../src/agent/agent-loop.ts"],"names":[],"mappings":"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"}

package/server/dist/agent/home-context.d.ts

@@ -0,0 +1,29 @@
+import { type NatrocPaths } from "../config/natroc-home.js";
+import type { ChatRole } from "../providers/types.js";
+import type { AgentMemoryEntry } from "../storage/memory-repository.js";
+export declare const defaultHomeContextFileNames: string[];
+export type HomeContextFile = {
+    name: string;
+    content: string;
+    truncated: boolean;
+};
+export type HomeContext = {
+    files: HomeContextFile[];
+};
+export type AgentSystemMemory = Pick<AgentMemoryEntry, "id" | "kind" | "title" | "content">;
+export type AgentConversationRecall = {
+    id: string;
+    title: string;
+    updatedAt: string;
+    messages: Array<{
+        role: ChatRole;
+        content: string;
+        createdAt: string;
+    }>;
+};
+export declare function loadHomeContext(paths: NatrocPaths | undefined, options?: {
+    maxFileCharacters?: number;
+}): Promise<HomeContext>;
+export declare function listHomeContextFiles(paths: NatrocPaths | undefined): Promise<string[]>;
+export declare function resolveHomeFilePath(paths: NatrocPaths, fileName: string): string;
+export declare function buildAgentSystemPrompt(context: HomeContext, memories?: AgentSystemMemory[], conversationThreads?: AgentConversationRecall[]): string;

package/server/dist/agent/home-context.js

@@ -0,0 +1,134 @@
+import { readdir, readFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { natrocHomeFileNames } from "../config/natroc-home.js";
+export const defaultHomeContextFileNames = natrocHomeFileNames;
+export async function loadHomeContext(paths, options = {}) {
+    if (!paths) {
+        throw new Error("Natroc home path is not configured.");
+    }
+    const homeDir = resolve(paths.homeDir);
+    const maxFileCharacters = options.maxFileCharacters ?? 2400;
+    const homeFiles = await listHomeMarkdownFiles(homeDir);
+    const files = await Promise.all(homeFiles.map(async ({ absolutePath, name }) => {
+        assertInsideHome(homeDir, absolutePath);
+        const content = await readOptionalHomeFile(absolutePath);
+        if (!content.trim()) {
+            return null;
+        }
+        const truncated = content.length > maxFileCharacters;
+        const nextContent = truncated
+            ? `${content.slice(0, maxFileCharacters).trimEnd()}\n\n[truncated]`
+            : content.trimEnd();
+        return {
+            name,
+            content: nextContent,
+            truncated
+        };
+    }));
+    return {
+        files: files.filter((file) => Boolean(file))
+    };
+}
+export async function listHomeContextFiles(paths) {
+    if (!paths)
+        return [];
+    return (await listHomeMarkdownFiles(resolve(paths.homeDir))).map((file) => file.name);
+}
+export function resolveHomeFilePath(paths, fileName) {
+    const homeDir = resolve(paths.homeDir);
+    const absolutePath = resolve(homeDir, fileName);
+    assertInsideHome(homeDir, absolutePath);
+    return absolutePath;
+}
+export function buildAgentSystemPrompt(context, memories = [], conversationThreads = []) {
+    const sections = [
+        "## Natroc Runtime",
+        "You are running inside Natroc, a local-first personal AI agent runtime.",
+        "Use the injected home files and approved memory as durable local context.",
+        "Do not claim to have changed memory, knowledge, files, services, commits, or processes unless the runtime actually did it."
+    ];
+    if (context.files.length > 0) {
+        sections.push("## Natroc Home");
+        for (const file of context.files) {
+            sections.push(`### ${file.name}`, file.content);
+        }
+    }
+    if (memories.length > 0) {
+        sections.push("## Approved Agent Memory");
+        for (const memory of memories) {
+            sections.push(formatMemory(memory));
+        }
+    }
+    if (conversationThreads.length > 0) {
+        sections.push("## Prior Conversation Threads", "These are bounded snippets from stored Natroc conversations across sessions. Use them as recall of previous threads, while treating Approved Agent Memory and the current user message as higher priority if there is a conflict.");
+        for (const thread of conversationThreads) {
+            sections.push(formatConversationThread(thread));
+        }
+    }
+    sections.push("## Self Improvement Policy", "You may suggest memory, knowledge, or skill improvements, but they must stay pending until the user approves them.");
+    return sections.join("\n\n");
+}
+function formatMemory(memory) {
+    return `- [${memory.kind}] ${memory.title} (${memory.id}): ${memory.content}`;
+}
+function formatConversationThread(thread) {
+    const lines = [
+        `### ${thread.title} (${thread.id}, updated ${thread.updatedAt})`,
+        ...thread.messages.map((message) => `- ${message.role.toUpperCase()}: ${message.content}`)
+    ];
+    return lines.join("\n");
+}
+async function readOptionalHomeFile(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return "";
+        }
+        throw error;
+    }
+}
+async function listHomeMarkdownFiles(homeDir) {
+    const files = await collectMarkdownFiles(homeDir, homeDir);
+    return files.sort((left, right) => left.name.localeCompare(right.name));
+}
+async function collectMarkdownFiles(homeDir, currentDir) {
+    const entries = await readdir(currentDir, { withFileTypes: true }).catch((error) => {
+        if (error instanceof Error &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    });
+    const files = [];
+    for (const entry of entries) {
+        const absolutePath = resolve(currentDir, entry.name);
+        assertInsideHome(homeDir, absolutePath);
+        if (entry.isDirectory()) {
+            files.push(...(await collectMarkdownFiles(homeDir, absolutePath)));
+            continue;
+        }
+        if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md")) {
+            continue;
+        }
+        files.push({
+            absolutePath,
+            name: toHomeRelativeName(homeDir, absolutePath)
+        });
+    }
+    return files;
+}
+function toHomeRelativeName(homeDir, absolutePath) {
+    return relative(homeDir, absolutePath).split(sep).join("/");
+}
+function assertInsideHome(homeDir, absolutePath) {
+    const relativePath = relative(homeDir, absolutePath);
+    if (relativePath === "" ||
+        (!relativePath.startsWith("..") && !isAbsolute(relativePath))) {
+        return;
+    }
+    throw new Error("Natroc home context can only read files inside home.");
+}
+//# sourceMappingURL=home-context.js.map

package/server/dist/agent/home-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"home-context.js","sourceRoot":"","sources":["../../src/agent/home-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAE9D,OAAO,EACL,mBAAmB,EAEpB,MAAM,0BAA0B,CAAA;AAOjC,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAA;AA4B9D,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAA8B,EAC9B,UAA0C,EAAE;IAE5C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAA;IACxD,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IACtC,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,IAAI,IAAI,CAAA;IAC3D,MAAM,SAAS,GAAG,MAAM,qBAAqB,CAAC,OAAO,CAAC,CAAA;IACtD,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAC7B,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,EAAE;QAC7C,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;QACvC,MAAM,OAAO,GAAG,MAAM,oBAAoB,CAAC,YAAY,CAAC,CAAA;QAExD,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;YACpB,OAAO,IAAI,CAAA;QACb,CAAC;QAED,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,iBAAiB,CAAA;QACpD,MAAM,WAAW,GAAG,SAAS;YAC3B,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,OAAO,EAAE,iBAAiB;YACnE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAA;QAErB,OAAO;YACL,IAAI;YACJ,OAAO,EAAE,WAAW;YACpB,SAAS;SACgB,CAAA;IAC7B,CAAC,CAAC,CACH,CAAA;IAED,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAA2B,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;KACtE,CAAA;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAA8B;IAE9B,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAA;IAErB,OAAO,CAAC,MAAM,qBAAqB,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAC9D,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CACpB,CAAA;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAkB,EAAE,QAAgB;IACtE,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IACtC,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IAE/C,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;IAEvC,OAAO,YAAY,CAAA;AACrB,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,OAAoB,EACpB,WAAgC,EAAE,EAClC,sBAAiD,EAAE;IAEnD,MAAM,QAAQ,GAAG;QACf,mBAAmB;QACnB,yEAAyE;QACzE,2EAA2E;QAC3E,4HAA4H;KAC7H,CAAA;IAED,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,QAAQ,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAA;QAC/B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YACjC,QAAQ,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;QACjD,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAA;QAEzC,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;YAC9B,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAA;QACrC,CAAC;IACH,CAAC;IAED,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,QAAQ,CAAC,IAAI,CACX,+BAA+B,EAC/B,mOAAmO,CACpO,CAAA;QAED,KAAK,MAAM,MAAM,IAAI,mBAAmB,EAAE,CAAC;YACzC,QAAQ,CAAC,IAAI,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC,CAAA;QACjD,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,IAAI,CACX,4BAA4B,EAC5B,oHAAoH,CACrH,CAAA;IAED,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;AAC9B,CAAC;AAED,SAAS,YAAY,CAAC,MAKrB;IACC,OAAO,MAAM,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,KAAK,KAAK,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC,OAAO,EAAE,CAAA;AAC/E,CAAC;AAED,SAAS,wBAAwB,CAAC,MAA+B;IAC/D,MAAM,KAAK,GAAG;QACZ,OAAO,MAAM,CAAC,KAAK,KAAK,MAAM,CAAC,EAAE,aAAa,MAAM,CAAC,SAAS,GAAG;QACjE,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CACpB,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,CACnE;KACF,CAAA;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC;AAED,KAAK,UAAU,oBAAoB,CAAC,IAAY;IAC9C,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACzE,OAAO,EAAE,CAAA;QACX,CAAC;QAED,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC;AAED,KAAK,UAAU,qBAAqB,CAAC,OAAe;IAClD,MAAM,KAAK,GAAG,MAAM,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IAE1D,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;AACzE,CAAC;AAED,KAAK,UAAU,oBAAoB,CAAC,OAAe,EAAE,UAAkB;IACrE,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CACtE,CAAC,KAAc,EAAE,EAAE;QACjB,IACE,KAAK,YAAY,KAAK;YACtB,MAAM,IAAI,KAAK;YACf,KAAK,CAAC,IAAI,KAAK,QAAQ,EACvB,CAAC;YACD,OAAO,EAAE,CAAA;QACX,CAAC;QAED,MAAM,KAAK,CAAA;IACb,CAAC,CACF,CAAA;IACD,MAAM,KAAK,GAAkD,EAAE,CAAA;IAE/D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,YAAY,GAAG,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QAEpD,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;QAEvC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,oBAAoB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAA;YAClE,SAAQ;QACV,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACjE,SAAQ;QACV,CAAC;QAED,KAAK,CAAC,IAAI,CAAC;YACT,YAAY;YACZ,IAAI,EAAE,kBAAkB,CAAC,OAAO,EAAE,YAAY,CAAC;SAChD,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED,SAAS,kBAAkB,CAAC,OAAe,EAAE,YAAoB;IAC/D,OAAO,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC7D,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAe,EAAE,YAAoB;IAC7D,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;IAEpD,IACE,YAAY,KAAK,EAAE;QACnB,CAAC,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,EAC7D,CAAC;QACD,OAAM;IACR,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAA;AACzE,CAAC"}

package/server/dist/agent/improvement-engine.d.ts

@@ -0,0 +1,23 @@
+import type { ProviderAdapter } from "../providers/types.js";
+import type { AgentMemoryKind, CreateProposalInput } from "../storage/memory-repository.js";
+import type { MessageRecord } from "../storage/conversation-repository.js";
+export type ImprovementDraft = CreateProposalInput;
+export declare function parseImprovementProposalResponse(response: string): ImprovementDraft[];
+export declare function buildHeuristicImprovementProposals(input: {
+    userMessage: string;
+    assistantMessage: string;
+    conversationId?: string | null;
+}): ImprovementDraft[];
+export declare function generateImprovementProposals(input: {
+    adapter: ProviderAdapter;
+    model?: string;
+    messages: MessageRecord[];
+    conversationId?: string | null;
+}): Promise<{
+    sourceConversationId: string | null;
+    userId?: string | null;
+    kind: AgentMemoryKind;
+    title: string;
+    content: string;
+    reason: string;
+}[]>;